include/QtWidgets/qmenu.h

0001 // Copyright (C) 2016 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 // Qt-Security score:significant reason:default
0004
0005 #ifndef QMENU_H
0006 #define QMENU_H
0007
0008 #include <QtWidgets/qtwidgetsglobal.h>
0009 #include <QtWidgets/qwidget.h>
0010 #include <QtCore/qstring.h>
0011 #include <QtGui/qicon.h>
0012 #include <QtGui/qaction.h>
0013
0014 #if defined(Q_OS_MACOS) || defined(Q_QDOC)
0015 Q_FORWARD_DECLARE_OBJC_CLASS(NSMenu);
0016 #endif
0017
0018 QT_REQUIRE_CONFIG(menu);
0019
0020 QT_BEGIN_NAMESPACE
0021
0022 class QMenuPrivate;
0023 class QStyleOptionMenuItem;
0024 class QPlatformMenu;
0025
0026 class Q_WIDGETS_EXPORT QMenu : public QWidget
0027 {
0028 private:
0029     Q_OBJECT
0030     Q_DECLARE_PRIVATE(QMenu)
0031
0032     Q_PROPERTY(bool tearOffEnabled READ isTearOffEnabled WRITE setTearOffEnabled)
0033     Q_PROPERTY(QString title READ title WRITE setTitle)
0034     Q_PROPERTY(QIcon icon READ icon WRITE setIcon)
0035     Q_PROPERTY(bool separatorsCollapsible READ separatorsCollapsible WRITE setSeparatorsCollapsible)
0036     Q_PROPERTY(bool toolTipsVisible READ toolTipsVisible WRITE setToolTipsVisible)
0037
0038 public:
0039     explicit QMenu(QWidget *parent = nullptr);
0040     explicit QMenu(const QString &title, QWidget *parent = nullptr);
0041     ~QMenu();
0042
0043     using QWidget::addAction;
0044 #if QT_WIDGETS_REMOVED_SINCE(6, 3)
0045     QAction *addAction(const QString &text);
0046     QAction *addAction(const QIcon &icon, const QString &text);
0047 #if !QT_CONFIG(shortcut)
0048     QAction *addAction(const QString &text, const QObject *receiver, const char* member);
0049     QAction *addAction(const QIcon &icon, const QString &text,
0050                        const QObject *receiver, const char* member);
0051 #endif
0052 #endif
0053
0054 #if QT_CONFIG(shortcut)
0055 #if QT_DEPRECATED_SINCE(6, 4)
0056     QT_DEPRECATED_VERSION_X_6_4("Use addAction(text, shortcut, receiver, member) instead.")
0057     QAction *addAction(const QString &text, const QObject *receiver, const char* member,
0058                        const QKeySequence &shortcut);
0059     QT_DEPRECATED_VERSION_X_6_4("Use addAction(icon, text, shortcut, receiver, member) instead.")
0060     QAction *addAction(const QIcon &icon, const QString &text,
0061                        const QObject *receiver, const char* member,
0062                        const QKeySequence &shortcut);
0063
0064 #ifdef Q_QDOC
0065     template<typename Functor>
0066     QAction *addAction(const QString &text, Functor functor, const QKeySequence &shortcut);
0067     template<typename Functor>
0068     QAction *addAction(const QString &text, const QObject *context, Functor functor, const QKeySequence &shortcut);
0069     template<typename Functor>
0070     QAction *addAction(const QIcon &icon, const QString &text, Functor functor, const QKeySequence &shortcut);
0071     template<typename Functor>
0072     QAction *addAction(const QIcon &icon, const QString &text, const QObject *context, Functor functor, const QKeySequence &shortcut);
0073 #else
0074     // addAction(QString): Connect to a QObject slot / functor or function pointer (with context)
0075     template<class Obj, typename Func1>
0076     QT_DEPRECATED_VERSION_X_6_4("Use addAction(text, shortcut, object, slot) instead.")
0077     inline typename std::enable_if<!std::is_same<const char*, Func1>::value
0078         && QtPrivate::IsPointerToTypeDerivedFromQObject<Obj*>::Value, QAction *>::type
0079         addAction(const QString &text, const Obj *object, Func1 slot,
0080                   const QKeySequence &shortcut)
0081     {
0082         return addAction(text, shortcut, object, slot);
0083     }
0084     // addAction(QString): Connect to a functor or function pointer (without context)
0085     template <typename Func1>
0086     QT_DEPRECATED_VERSION_X_6_4("Use addAction(text, shortcut, slot) instead.")
0087     inline QAction *addAction(const QString &text, Func1 slot, const QKeySequence &shortcut)
0088     {
0089         return addAction(text, shortcut, slot);
0090     }
0091     // addAction(QIcon, QString): Connect to a QObject slot / functor or function pointer (with context)
0092     template<class Obj, typename Func1>
0093     QT_DEPRECATED_VERSION_X_6_4("Use addAction(icon, text, shortcut, object, slot) instead.")
0094     inline typename std::enable_if<!std::is_same<const char*, Func1>::value
0095         && QtPrivate::IsPointerToTypeDerivedFromQObject<Obj*>::Value, QAction *>::type
0096         addAction(const QIcon &actionIcon, const QString &text, const Obj *object, Func1 slot,
0097                   const QKeySequence &shortcut)
0098
0099     {
0100         return addAction(actionIcon, text, shortcut, object, slot);
0101     }
0102     // addAction(QIcon, QString): Connect to a functor or function pointer (without context)
0103     template <typename Func1>
0104     QT_DEPRECATED_VERSION_X_6_4("Use addAction(icon, text, shortcut, slot) instead.")
0105     inline QAction *addAction(const QIcon &actionIcon, const QString &text, Func1 slot,
0106                               const QKeySequence &shortcut)
0107     {
0108         return addAction(actionIcon, text, shortcut, slot);
0109     }
0110 #endif // !Q_QDOC
0111 #endif // QT_DEPRECATED_SINCE(6, 4)
0112 #endif // QT_CONFIG(shortcut)
0113
0114     QAction *addMenu(QMenu *menu);
0115     QMenu *addMenu(const QString &title);
0116     QMenu *addMenu(const QIcon &icon, const QString &title);
0117
0118     QAction *addSeparator();
0119
0120     QAction *addSection(const QString &text);
0121     QAction *addSection(const QIcon &icon, const QString &text);
0122
0123     QAction *insertMenu(QAction *before, QMenu *menu);
0124     QAction *insertSeparator(QAction *before);
0125     QAction *insertSection(QAction *before, const QString &text);
0126     QAction *insertSection(QAction *before, const QIcon &icon, const QString &text);
0127
0128     bool isEmpty() const;
0129     void clear();
0130
0131     void setTearOffEnabled(bool);
0132     bool isTearOffEnabled() const;
0133
0134     bool isTearOffMenuVisible() const;
0135     void showTearOffMenu();
0136     void showTearOffMenu(const QPoint &pos);
0137     void hideTearOffMenu();
0138
0139     void setDefaultAction(QAction *);
0140     QAction *defaultAction() const;
0141
0142     void setActiveAction(QAction *act);
0143     QAction *activeAction() const;
0144
0145     void popup(const QPoint &pos, QAction *at = nullptr);
0146     QAction *exec();
0147     QAction *exec(const QPoint &pos, QAction *at = nullptr);
0148
0149     static QAction *exec(const QList<QAction *> &actions, const QPoint &pos, QAction *at = nullptr, QWidget *parent = nullptr);
0150
0151     QSize sizeHint() const override;
0152
0153     QRect actionGeometry(QAction *) const;
0154     QAction *actionAt(const QPoint &) const;
0155
0156     QAction *menuAction() const;
0157     static QMenu *menuInAction(const QAction *action)
0158     { return qobject_cast<QMenu *>(action->menuObject()); }
0159
0160     QString title() const;
0161     void setTitle(const QString &title);
0162
0163     QIcon icon() const;
0164     void setIcon(const QIcon &icon);
0165
0166     void setNoReplayFor(QWidget *widget);
0167     QPlatformMenu *platformMenu();
0168     void setPlatformMenu(QPlatformMenu *platformMenu);
0169
0170 #if defined(Q_OS_MACOS) || defined(Q_QDOC)
0171     NSMenu* toNSMenu();
0172     void setAsDockMenu();
0173 #endif
0174
0175     bool separatorsCollapsible() const;
0176     void setSeparatorsCollapsible(bool collapse);
0177
0178     bool toolTipsVisible() const;
0179     void setToolTipsVisible(bool visible);
0180
0181 Q_SIGNALS:
0182     void aboutToShow();
0183     void aboutToHide();
0184     void triggered(QAction *action);
0185     void hovered(QAction *action);
0186
0187 protected:
0188     int columnCount() const;
0189
0190     void changeEvent(QEvent *) override;
0191     void keyPressEvent(QKeyEvent *) override;
0192     void mouseReleaseEvent(QMouseEvent *) override;
0193     void mousePressEvent(QMouseEvent *) override;
0194     void mouseMoveEvent(QMouseEvent *) override;
0195 #if QT_CONFIG(wheelevent)
0196     void wheelEvent(QWheelEvent *) override;
0197 #endif
0198     void enterEvent(QEnterEvent *) override;
0199     void leaveEvent(QEvent *) override;
0200     void hideEvent(QHideEvent *) override;
0201     void paintEvent(QPaintEvent *) override;
0202     void actionEvent(QActionEvent *) override;
0203     void timerEvent(QTimerEvent *) override;
0204     bool event(QEvent *) override;
0205     bool focusNextPrevChild(bool next) override;
0206     virtual void initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const;
0207
0208 private Q_SLOTS:
0209     void internalDelayedPopup();
0210
0211 private:
0212     Q_PRIVATE_SLOT(d_func(), void _q_actionTriggered())
0213     Q_PRIVATE_SLOT(d_func(), void _q_actionHovered())
0214     Q_PRIVATE_SLOT(d_func(), void _q_overrideMenuActionDestroyed())
0215     Q_PRIVATE_SLOT(d_func(), void _q_platformMenuAboutToShow())
0216
0217 protected:
0218     QMenu(QMenuPrivate &dd, QWidget* parent = nullptr);
0219
0220 private:
0221     Q_DISABLE_COPY(QMenu)
0222
0223     friend class QMenuBar;
0224     friend class QMenuBarPrivate;
0225     friend class QTornOffMenu;
0226     friend class QComboBox;
0227     friend class QtWidgetsActionPrivate;
0228     friend class QToolButtonPrivate;
0229     friend void qt_mac_emit_menuSignals(QMenu *menu, bool show);
0230     friend void qt_mac_menu_emit_hovered(QMenu *menu, QAction *action);
0231 };
0232
0233 QT_END_NAMESPACE
0234
0235 #endif // QMENU_H