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 */
30class DisplayHint : public QObject
31{
32 Q_OBJECT
33 QML_ELEMENT
34 QML_SINGLETON
35
36public:
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
96Q_DECLARE_OPERATORS_FOR_FLAGS(DisplayHint::DisplayHints)
97
98#endif // DISPLAYHINT_H
99

source code of kirigami/src/layouts/displayhint.h