1 | /* |
2 | * SPDX-FileCopyrightText: 2016 Marco Martin <mart@kde.org> |
3 | * |
4 | * SPDX-License-Identifier: LGPL-2.0-or-later |
5 | */ |
6 | |
7 | #ifndef DISPLAYHINT_H |
8 | #define DISPLAYHINT_H |
9 | |
10 | #include <QObject> |
11 | #include <QQmlEngine> |
12 | |
13 | /*! |
14 | * \qmltype DisplayHint |
15 | * \inqmlmodule org.kde.kirigami.layouts |
16 | * |
17 | * \brief Hints for implementations using Actions indicating preferences about how to display the action. |
18 | * |
19 | * This is a singleton type. |
20 | * |
21 | * Possible hint values are: |
22 | * \list |
23 | * \li NoPreference: Indicates there is no specific preference. |
24 | * \li IconOnly: Only display an icon for this Action |
25 | * \li KeepVisible: Try to keep the action visible even when space constrained. Mutually exclusive with AlwaysHide, KeepVisible has priority. |
26 | * \li AlwaysHide: If possible, hide the action in an overflow menu or similar location. Mutually exclusive with KeepVisible, KeepVisible has priority. |
27 | * \li HideChildIndicator: When this action has children, do not display any indicator (like a menu arrow) for this action. |
28 | * \endlist |
29 | */ |
30 | class DisplayHint : public QObject |
31 | { |
32 | Q_OBJECT |
33 | QML_ELEMENT |
34 | QML_SINGLETON |
35 | |
36 | public: |
37 | enum Hint : uint { |
38 | NoPreference = 0, |
39 | IconOnly = 1, |
40 | KeepVisible = 2, |
41 | AlwaysHide = 4, |
42 | HideChildIndicator = 8, |
43 | }; |
44 | Q_DECLARE_FLAGS(DisplayHints, Hint) |
45 | Q_ENUM(Hint) |
46 | Q_FLAG(DisplayHints) |
47 | |
48 | // Note: These functions are instance methods because they need to be |
49 | // exposed to QML. Unfortunately static methods are not supported. |
50 | |
51 | /*! |
52 | * \qmlmethod bool DisplayHint::displayHintSet(DisplayHints hints, Hint hint) |
53 | * |
54 | * Helper function to check if a certain display hint has been set. |
55 | * |
56 | * This function is mostly convenience to enforce certain behaviour of the |
57 | * various display hints, primarily the mutual exclusivity of KeepVisible |
58 | * and AlwaysHide. |
59 | * |
60 | * \a values The display hints to check. |
61 | * |
62 | * \a hint The display hint to check if it is set. |
63 | * |
64 | * Return \c true if the hint was set for this action, false if not. |
65 | * |
66 | * \since 2.14 |
67 | */ |
68 | Q_INVOKABLE bool displayHintSet(DisplayHints values, Hint hint); |
69 | |
70 | /*! |
71 | * \qmlmethod bool DisplayHint::displayHintSet(QtObject hints, Hint hint) |
72 | * |
73 | * Check if a certain display hint has been set on an object. |
74 | * |
75 | * This overloads displayHintSet(DisplayHints, Hint) to accept a QObject |
76 | * instance. This object is checked to see if it has a displayHint property |
77 | * and if so, if that property has \a hint set. |
78 | * |
79 | * \a object The object to check. |
80 | * |
81 | * \a hint The hint to check for. |
82 | * |
83 | * Returns \c false if object is null, object has no displayHint property or |
84 | * the hint was not set. \c true if it has the property and the hint is |
85 | * set. |
86 | */ |
87 | Q_INVOKABLE bool displayHintSet(QObject *object, Hint hint); |
88 | |
89 | /*! |
90 | * Static version of displayHintSet(DisplayHints, Hint) that can be |
91 | * called from C++ code. |
92 | */ |
93 | static bool isDisplayHintSet(DisplayHints values, Hint hint); |
94 | }; |
95 | |
96 | Q_DECLARE_OPERATORS_FOR_FLAGS(DisplayHint::DisplayHints) |
97 | |
98 | #endif // DISPLAYHINT_H |
99 | |