include/QtGui/qaction.h

0001 // Copyright (C) 2020 The Qt Company Ltd.
0002 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0003
0004 #ifndef QACTION_H
0005 #define QACTION_H
0006
0007 #include <QtGui/qtguiglobal.h>
0008 #if QT_CONFIG(shortcut)
0009 #  include <QtGui/qkeysequence.h>
0010 #endif
0011 #include <QtGui/qicon.h>
0012 #include <QtCore/qstring.h>
0013 #include <QtCore/qvariant.h>
0014 #include <QtCore/qobject.h>
0015
0016 QT_REQUIRE_CONFIG(action);
0017
0018 QT_BEGIN_NAMESPACE
0019
0020 class QActionEvent;
0021 class QActionGroup;
0022 class QActionPrivate;
0023 class QMenu;
0024 #if QT_DEPRECATED_SINCE(6,0)
0025 class QWidget;
0026 class QGraphicsWidget;
0027 #endif
0028
0029 class Q_GUI_EXPORT QAction : public QObject
0030 {
0031     Q_OBJECT
0032     Q_DECLARE_PRIVATE(QAction)
0033
0034     Q_PROPERTY(bool checkable READ isCheckable WRITE setCheckable NOTIFY checkableChanged FINAL)
0035     Q_PROPERTY(bool checked READ isChecked WRITE setChecked NOTIFY toggled)
0036     Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged
0037                RESET resetEnabled FINAL)
0038     Q_PROPERTY(QIcon icon READ icon WRITE setIcon NOTIFY changed)
0039     Q_PROPERTY(QString text READ text WRITE setText NOTIFY changed)
0040     Q_PROPERTY(QString iconText READ iconText WRITE setIconText NOTIFY changed)
0041     Q_PROPERTY(QString toolTip READ toolTip WRITE setToolTip NOTIFY changed)
0042     Q_PROPERTY(QString statusTip READ statusTip WRITE setStatusTip NOTIFY changed)
0043     Q_PROPERTY(QString whatsThis READ whatsThis WRITE setWhatsThis NOTIFY changed)
0044     Q_PROPERTY(QFont font READ font WRITE setFont NOTIFY changed)
0045 #if QT_CONFIG(shortcut)
0046     Q_PROPERTY(QKeySequence shortcut READ shortcut WRITE setShortcut NOTIFY changed)
0047     Q_PROPERTY(Qt::ShortcutContext shortcutContext READ shortcutContext WRITE setShortcutContext
0048                NOTIFY changed)
0049     Q_PROPERTY(bool autoRepeat READ autoRepeat WRITE setAutoRepeat NOTIFY changed)
0050 #endif // QT_CONFIG(shortcut)
0051     Q_PROPERTY(bool visible READ isVisible WRITE setVisible NOTIFY visibleChanged FINAL)
0052     Q_PROPERTY(MenuRole menuRole READ menuRole WRITE setMenuRole NOTIFY changed)
0053     Q_PROPERTY(bool iconVisibleInMenu READ isIconVisibleInMenu WRITE setIconVisibleInMenu
0054                NOTIFY changed)
0055     Q_PROPERTY(bool shortcutVisibleInContextMenu READ isShortcutVisibleInContextMenu
0056                WRITE setShortcutVisibleInContextMenu NOTIFY changed)
0057     Q_PROPERTY(Priority priority READ priority WRITE setPriority NOTIFY changed)
0058
0059 public:
0060     // note this is copied into qplatformmenu.h, which must stay in sync
0061     enum MenuRole { NoRole = 0, TextHeuristicRole, ApplicationSpecificRole, AboutQtRole,
0062                     AboutRole, PreferencesRole, QuitRole };
0063     Q_ENUM(MenuRole)
0064     enum Priority { LowPriority = 0,
0065                     NormalPriority = 128,
0066                     HighPriority = 256};
0067     Q_ENUM(Priority)
0068     explicit QAction(QObject *parent = nullptr);
0069     explicit QAction(const QString &text, QObject *parent = nullptr);
0070     explicit QAction(const QIcon &icon, const QString &text, QObject *parent = nullptr);
0071
0072     ~QAction();
0073
0074     QList<QObject *> associatedObjects() const;
0075
0076 #if QT_DEPRECATED_SINCE(6,0)
0077 #ifdef Q_QDOC
0078     QWidget *parentWidget() const;
0079     QList<QWidget*> associatedWidgets() const;
0080     QList<QGraphicsWidget*> associatedGraphicsWidgets() const;
0081 #else
0082     /*
0083         These are templates so that instantiation happens only in calling code, when
0084         QWidget, QMenu, and QGraphicsWidget can be expected to be fully defined.
0085     */
0086     template<typename T = QWidget*>
0087     QT_DEPRECATED_VERSION_X_6_0("Use parent() with qobject_cast() instead")
0088     T parentWidget() const
0089     {
0090         auto result = parent();
0091         while (result && !qobject_cast<T>(result))
0092             result = result->parent();
0093         return static_cast<T>(result);
0094     }
0095
0096     template<typename T = QWidget*>
0097     QT_DEPRECATED_VERSION_X_6_0("Use associatedObjects() with qobject_cast() instead")
0098     QList<T> associatedWidgets() const
0099     {
0100         QList<T> result;
0101         for (auto object : associatedObjects())
0102             if (auto widget = qobject_cast<T>(object))
0103                 result.append(widget);
0104         return result;
0105     }
0106     template<typename T = QGraphicsWidget*>
0107     QT_DEPRECATED_VERSION_X_6_0("Use associatedObjects() with qobject_cast() instead")
0108     QList<T> associatedGraphicsWidgets() const
0109     {
0110         QList<T> result;
0111         for (auto object : associatedObjects())
0112             if (auto graphicsWidget = qobject_cast<T>(object))
0113                 result.append(graphicsWidget);
0114         return result;
0115     }
0116 #endif
0117 #endif
0118
0119     void setActionGroup(QActionGroup *group);
0120     QActionGroup *actionGroup() const;
0121     void setIcon(const QIcon &icon);
0122     QIcon icon() const;
0123
0124     void setText(const QString &text);
0125     QString text() const;
0126
0127     void setIconText(const QString &text);
0128     QString iconText() const;
0129
0130     void setToolTip(const QString &tip);
0131     QString toolTip() const;
0132
0133     void setStatusTip(const QString &statusTip);
0134     QString statusTip() const;
0135
0136     void setWhatsThis(const QString &what);
0137     QString whatsThis() const;
0138
0139     void setPriority(Priority priority);
0140     Priority priority() const;
0141
0142     void setSeparator(bool b);
0143     bool isSeparator() const;
0144
0145 #if QT_CONFIG(shortcut)
0146     void setShortcut(const QKeySequence &shortcut);
0147     QKeySequence shortcut() const;
0148
0149     void setShortcuts(const QList<QKeySequence> &shortcuts);
0150     void setShortcuts(QKeySequence::StandardKey);
0151     QList<QKeySequence> shortcuts() const;
0152
0153     void setShortcutContext(Qt::ShortcutContext context);
0154     Qt::ShortcutContext shortcutContext() const;
0155
0156     void setAutoRepeat(bool);
0157     bool autoRepeat() const;
0158 #endif // QT_CONFIG(shortcut)
0159
0160     void setFont(const QFont &font);
0161     QFont font() const;
0162
0163     void setCheckable(bool);
0164     bool isCheckable() const;
0165
0166     QVariant data() const;
0167     void setData(const QVariant &var);
0168
0169     bool isChecked() const;
0170
0171     bool isEnabled() const;
0172
0173     bool isVisible() const;
0174
0175     enum ActionEvent { Trigger, Hover };
0176     void activate(ActionEvent event);
0177
0178     void setMenuRole(MenuRole menuRole);
0179     MenuRole menuRole() const;
0180
0181 #ifdef Q_QDOC
0182     QMenu *menu() const;
0183     void setMenu(QMenu *menu);
0184 #else
0185     template<typename T = QMenu*>
0186     T menu() const
0187     {
0188         return qobject_cast<T>(menuObject());
0189     }
0190     template<typename T = QMenu*>
0191     void setMenu(T m)
0192     {
0193         setMenuObject(m);
0194     }
0195 #endif
0196
0197     void setIconVisibleInMenu(bool visible);
0198     bool isIconVisibleInMenu() const;
0199
0200     void setShortcutVisibleInContextMenu(bool show);
0201     bool isShortcutVisibleInContextMenu() const;
0202
0203     bool showStatusText(QObject *object = nullptr);
0204
0205 protected:
0206     bool event(QEvent *) override;
0207     QAction(QActionPrivate &dd, QObject *parent);
0208
0209 public Q_SLOTS:
0210     void trigger() { activate(Trigger); }
0211     void hover() { activate(Hover); }
0212     void setChecked(bool);
0213     void toggle();
0214     void setEnabled(bool);
0215     void resetEnabled();
0216     inline void setDisabled(bool b) { setEnabled(!b); }
0217     void setVisible(bool);
0218
0219 Q_SIGNALS:
0220     void changed();
0221     void enabledChanged(bool enabled);
0222     void checkableChanged(bool checkable);
0223     void visibleChanged();
0224     void triggered(bool checked = false);
0225     void hovered();
0226     void toggled(bool);
0227
0228 private:
0229     Q_DISABLE_COPY(QAction)
0230     friend class QActionGroup;
0231     friend class QWidget;
0232     friend class QMenu;
0233     friend class QMenuPrivate;
0234     friend class QToolButton;
0235     friend class QGraphicsWidget;
0236
0237     QObject *menuObject() const;
0238     void setMenuObject(QObject *object);
0239 };
0240
0241 #ifndef QT_NO_DEBUG_STREAM
0242 Q_GUI_EXPORT QDebug operator<<(QDebug, const QAction *);
0243 #endif
0244
0245 QT_END_NAMESPACE
0246
0247 #endif // QACTION_H