1/****************************************************************************
2**
3** Copyright (C) 2020 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtGui module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#ifndef QACTION_H
41#define QACTION_H
42
43#include <QtGui/qtguiglobal.h>
44#if QT_CONFIG(shortcut)
45# include <QtGui/qkeysequence.h>
46#endif
47#include <QtGui/qicon.h>
48#include <QtCore/qstring.h>
49#include <QtCore/qvariant.h>
50
51QT_REQUIRE_CONFIG(action);
52
53QT_BEGIN_NAMESPACE
54
55class QActionEvent;
56class QActionGroup;
57class QActionPrivate;
58#if QT_DEPRECATED_SINCE(6,0)
59class QWidget;
60class QGraphicsWidget;
61class QMenu;
62#endif
63
64class Q_GUI_EXPORT QAction : public QObject
65{
66 Q_OBJECT
67 Q_DECLARE_PRIVATE(QAction)
68
69 Q_PROPERTY(bool checkable READ isCheckable WRITE setCheckable NOTIFY checkableChanged FINAL)
70 Q_PROPERTY(bool checked READ isChecked WRITE setChecked NOTIFY toggled)
71 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged RESET resetEnabled FINAL)
72 Q_PROPERTY(QIcon icon READ icon WRITE setIcon NOTIFY changed)
73 Q_PROPERTY(QString text READ text WRITE setText NOTIFY changed)
74 Q_PROPERTY(QString iconText READ iconText WRITE setIconText NOTIFY changed)
75 Q_PROPERTY(QString toolTip READ toolTip WRITE setToolTip NOTIFY changed)
76 Q_PROPERTY(QString statusTip READ statusTip WRITE setStatusTip NOTIFY changed)
77 Q_PROPERTY(QString whatsThis READ whatsThis WRITE setWhatsThis NOTIFY changed)
78 Q_PROPERTY(QFont font READ font WRITE setFont NOTIFY changed)
79#if QT_CONFIG(shortcut)
80 Q_PROPERTY(QKeySequence shortcut READ shortcut WRITE setShortcut NOTIFY changed)
81 Q_PROPERTY(Qt::ShortcutContext shortcutContext READ shortcutContext WRITE setShortcutContext NOTIFY changed)
82 Q_PROPERTY(bool autoRepeat READ autoRepeat WRITE setAutoRepeat NOTIFY changed)
83#endif // QT_CONFIG(shortcut)
84 Q_PROPERTY(bool visible READ isVisible WRITE setVisible NOTIFY visibleChanged FINAL)
85 Q_PROPERTY(MenuRole menuRole READ menuRole WRITE setMenuRole NOTIFY changed)
86 Q_PROPERTY(bool iconVisibleInMenu READ isIconVisibleInMenu WRITE setIconVisibleInMenu NOTIFY changed)
87 Q_PROPERTY(bool shortcutVisibleInContextMenu READ isShortcutVisibleInContextMenu WRITE setShortcutVisibleInContextMenu NOTIFY changed)
88 Q_PROPERTY(Priority priority READ priority WRITE setPriority)
89
90public:
91 // note this is copied into qplatformmenu.h, which must stay in sync
92 enum MenuRole { NoRole = 0, TextHeuristicRole, ApplicationSpecificRole, AboutQtRole,
93 AboutRole, PreferencesRole, QuitRole };
94 Q_ENUM(MenuRole)
95 enum Priority { LowPriority = 0,
96 NormalPriority = 128,
97 HighPriority = 256};
98 Q_ENUM(Priority)
99 explicit QAction(QObject *parent = nullptr);
100 explicit QAction(const QString &text, QObject *parent = nullptr);
101 explicit QAction(const QIcon &icon, const QString &text, QObject *parent = nullptr);
102
103 ~QAction();
104
105 QList<QObject *> associatedObjects() const;
106
107#if QT_DEPRECATED_SINCE(6,0)
108#ifdef Q_CLANG_QDOC
109 QWidget *parentWidget() const;
110 QList<QWidget*> associatedWidgets() const;
111 QList<QGraphicsWidget*> associatedGraphicsWidgets() const;
112#else
113 /*
114 These are templates so that instantiation happens only in calling code, when
115 QWidget, QMenu, and QGraphicsWidget can be expected to be fully defined.
116 */
117 template<typename T = QWidget*>
118 T parentWidget() const
119 {
120 auto result = parent();
121 while (result && !qobject_cast<T>(result))
122 result = result->parent();
123 return static_cast<T>(result);
124 }
125
126 template<typename T = QWidget*>
127 QList<T> associatedWidgets() const
128 {
129 QList<T> result;
130 for (auto object : associatedObjects())
131 if (auto widget = qobject_cast<T>(object))
132 result.append(widget);
133 return result;
134 }
135 template<typename T = QGraphicsWidget*>
136 QList<T> associatedGraphicsWidgets() const
137 {
138 QList<T> result;
139 for (auto object : associatedObjects())
140 if (auto graphicsWidget = qobject_cast<T>(object))
141 result.append(graphicsWidget);
142 return result;
143 }
144#endif
145#endif
146
147 void setActionGroup(QActionGroup *group);
148 QActionGroup *actionGroup() const;
149 void setIcon(const QIcon &icon);
150 QIcon icon() const;
151
152 void setText(const QString &text);
153 QString text() const;
154
155 void setIconText(const QString &text);
156 QString iconText() const;
157
158 void setToolTip(const QString &tip);
159 QString toolTip() const;
160
161 void setStatusTip(const QString &statusTip);
162 QString statusTip() const;
163
164 void setWhatsThis(const QString &what);
165 QString whatsThis() const;
166
167 void setPriority(Priority priority);
168 Priority priority() const;
169
170 void setSeparator(bool b);
171 bool isSeparator() const;
172
173#if QT_CONFIG(shortcut)
174 void setShortcut(const QKeySequence &shortcut);
175 QKeySequence shortcut() const;
176
177 void setShortcuts(const QList<QKeySequence> &shortcuts);
178 void setShortcuts(QKeySequence::StandardKey);
179 QList<QKeySequence> shortcuts() const;
180
181 void setShortcutContext(Qt::ShortcutContext context);
182 Qt::ShortcutContext shortcutContext() const;
183
184 void setAutoRepeat(bool);
185 bool autoRepeat() const;
186#endif // QT_CONFIG(shortcut)
187
188 void setFont(const QFont &font);
189 QFont font() const;
190
191 void setCheckable(bool);
192 bool isCheckable() const;
193
194 QVariant data() const;
195 void setData(const QVariant &var);
196
197 bool isChecked() const;
198
199 bool isEnabled() const;
200
201 bool isVisible() const;
202
203 enum ActionEvent { Trigger, Hover };
204 void activate(ActionEvent event);
205
206 void setMenuRole(MenuRole menuRole);
207 MenuRole menuRole() const;
208
209#if QT_DEPRECATED_SINCE(6,0)
210#ifdef Q_CLANG_QDOC
211 QMenu *menu() const;
212 void setMenu(QMenu *menu);
213#else
214 template<typename T = QMenu*>
215 T menu() const
216 {
217 return qobject_cast<T>(menuObject());
218 }
219 template<typename T = QMenu*>
220 void setMenu(T m)
221 {
222 setMenuObject(m);
223 }
224#endif
225#endif
226
227 void setIconVisibleInMenu(bool visible);
228 bool isIconVisibleInMenu() const;
229
230 void setShortcutVisibleInContextMenu(bool show);
231 bool isShortcutVisibleInContextMenu() const;
232
233 bool showStatusText(QObject *object = nullptr);
234
235protected:
236 bool event(QEvent *) override;
237 QAction(QActionPrivate &dd, QObject *parent);
238
239public Q_SLOTS:
240 void trigger() { activate(Trigger); }
241 void hover() { activate(Hover); }
242 void setChecked(bool);
243 void toggle();
244 void setEnabled(bool);
245 void resetEnabled();
246 inline void setDisabled(bool b) { setEnabled(!b); }
247 void setVisible(bool);
248
249Q_SIGNALS:
250 void changed();
251 void enabledChanged(bool enabled);
252 void checkableChanged(bool checkable);
253 void visibleChanged();
254 void triggered(bool checked = false);
255 void hovered();
256 void toggled(bool);
257
258private:
259 Q_DISABLE_COPY(QAction)
260 friend class QActionGroup;
261 friend class QWidget;
262 friend class QMenu;
263 friend class QMenuPrivate;
264 friend class QToolButton;
265 friend class QGraphicsWidget;
266
267 QObject *menuObject() const;
268 void setMenuObject(QObject *object);
269};
270
271#ifndef QT_NO_DEBUG_STREAM
272Q_GUI_EXPORT QDebug operator<<(QDebug, const QAction *);
273#endif
274
275QT_END_NAMESPACE
276
277#endif // QACTION_H
278