QMenu Class

The QMenu class provides a menu: a list of actions to choose from. More…

List of all members, including inherited members

Public Functions

Reimplemented Public Functions

Signals

Reimplemented Protected Functions

Detailed Description

A menu holds actions, with separators between groups of them, and submenus. It is shown at a place with popup() or exec(), or from a QMenuBar or a menu that has it as a submenu, and it closes when the user has chosen an action or clicked outside of it. Choosing an action triggers it:

QMenu *menu = new QMenu(window);
QAction *open = menu->addAction("&Open...");
open->setShortcut(QKeySequence::Open);
connect(open, &QAction::triggered, window, &Editor::openFile);
menu->addSeparator();
QMenu *recent = menu->addMenu("Open &Recent");
recent->addAction("notes.txt");
QAction *wrap = menu->addAction("&Wrap lines");
wrap->setCheckable(true);
menu->popup(button->mapToGlobal(QPoint(0, button->height())));

The menu follows its actions: a disabled action is dimmed and cannot be chosen, a hidden one is left out, and a checkable one has a check box. The up and down keys move through the entries, Right opens a submenu and Left or Escape closes it, Return and Space choose, and the letter after a & in the text of an action chooses it.

Menus open and close with the mouse, too: moving over an entry highlights it, moving over a submenu opens it after a short delay, and releasing the button over an entry chooses it.

The menu is a widget inside the window of the widget that it belongs to, not a window of its own, so it never reaches outside the window and it is clipped to it. It opens at the place that popup() is given, or to the left of it or above it if there is not room.

See also QMenuBar, QAction and QActionGroup.

Differences from Qt

Member Function Documentation

[explicit] QMenu::QMenu(QWidget *parent = nullptr)

Constructs a menu with the given parent. The menu is hidden until it is popped up.

[explicit] QMenu::QMenu(const QString &title, QWidget *parent = nullptr)

Constructs a menu with the given title and parent. The title is what a menu bar or the menu that has this one as a submenu shows.

[override] QMenu::~QMenu()

Destroys the menu.

[signal] void QMenu::aboutToHide()

This signal is emitted just after the menu has been hidden.

[signal] void QMenu::aboutToShow()

This signal is emitted just before the menu is shown.

QAction * QMenu::actionAt(const QPoint &point) const

Returns the action at point in the menu, which can be a separator; nullptr if there is none there.

See also actionGeometry().

[override, protected] void QMenu::actionEvent(QActionEvent *event)

Reimplements QWidget::actionEvent().

QRect QMenu::actionGeometry(QAction *action) const

Returns the rectangle of action in the menu; an empty rectangle if the action is not shown.

See also actionAt().

QAction * QMenu::activeAction() const

Returns the action that is highlighted; nullptr if there is none.

See also setActiveAction().

QAction * QMenu::addAction(const QString &text)

Creates an action with the given text, adds it to the end of the menu, and returns it. The menu owns the action.

See also addSeparator() and addMenu().

template <typename Functor>QAction * QMenu::addAction(const QString &text, Functor functor)

Creates an action with the given text, connects its triggered() signal to functor, adds the action to the end of the menu, and returns it.

QAction * QMenu::addMenu(QMenu *menu)

Adds menu as a submenu at the end of this menu, and returns the action of the submenu, which is the same as menu->menuAction(). The menu is not owned by this one.

See also insertMenu() and addSeparator().

QMenu * QMenu::addMenu(const QString &title)

Creates a menu with the given title, adds it as a submenu at the end of this menu, and returns it. This menu owns the new one.

See also addMenu(QMenu *).

QAction * QMenu::addSeparator()

Adds a separator, a line between groups of entries, at the end of the menu, and returns its action. A separator at the start or the end of a menu, and one next to another, is not shown.

See also insertSeparator().

[override, protected] void QMenu::changeEvent(QEvent *event)

Reimplements QWidget::changeEvent().

void QMenu::clear()

Removes all the actions of the menu. The actions that the menu owns and that no other widget has, and the submenus that it owns, are deleted.

See also isEmpty().

QAction * QMenu::exec()

Shows the menu at the position that the menu has in its window, and waits until it is closed. Returns the action that the user chose; nullptr if the menu was closed without one.

See also popup().

QAction * QMenu::exec(const QPoint &pos, QAction *at = nullptr)

Shows the menu at pos like popup(), and waits until it is closed, running the event loop meanwhile. Returns the action that the user chose, after it has been triggered; nullptr if the menu was closed without one. at is the action that is put at pos.

See also popup().

[override, protected] void QMenu::hideEvent(QHideEvent *event)

Reimplements QWidget::hideEvent().

[signal] void QMenu::hovered(QAction *action)

This signal is emitted when the user moves to an action of the menu, with that action. The action is hovered too.

QAction * QMenu::insertMenu(QAction *before, QMenu *menu)

Adds menu as a submenu in front of the action before, and returns the action of the submenu.

See also addMenu().

QAction * QMenu::insertSeparator(QAction *before)

Adds a separator in front of the action before, and returns its action.

See also addSeparator().

bool QMenu::isEmpty() const

Returns true if the menu has no entries that can be chosen: no visible actions, apart from separators; otherwise returns false.

[override, protected] void QMenu::keyPressEvent(QKeyEvent *event)

Reimplements QWidget::keyPressEvent().

[override, protected] void QMenu::leaveEvent(QEvent *event)

Reimplements QWidget::leaveEvent().

QAction * QMenu::menuAction() const

Returns the action that stands for the menu: its text is the title, and its menu is this one. A menu bar or another menu that has this menu has this action.

See also addMenu().

[override, protected] void QMenu::mouseMoveEvent(QMouseEvent *event)

Reimplements QWidget::mouseMoveEvent().

[override, protected] void QMenu::mousePressEvent(QMouseEvent *event)

Reimplements QWidget::mousePressEvent().

[override, protected] void QMenu::mouseReleaseEvent(QMouseEvent *event)

Reimplements QWidget::mouseReleaseEvent().

[override, protected] void QMenu::paintEvent(QPaintEvent *event)

Reimplements QWidget::paintEvent().

void QMenu::popup(const QPoint &pos, QAction *at = nullptr)

Shows the menu with its top left corner at pos, a position on the screen, and returns at once. If at is an action of the menu, the menu is placed so that the action is at pos, and it is the current action. The menu is moved if it would reach outside the window.

See also exec().

void QMenu::setActiveAction(QAction *action)

Sets the action that is current, the one that is highlighted and that Return chooses, to action; nullptr for none. This emits hovered(). It does not open a submenu.

See also activeAction().

void QMenu::setTitle(const QString &title)

Sets the title of the menu to title.

See also title().

[override] QSize QMenu::sizeHint() const

Reimplements QWidget::sizeHint().

QString QMenu::title() const

Returns the title of the menu.

See also setTitle().

[signal] void QMenu::triggered(QAction *action)

This signal is emitted when an action of the menu, or of a menu that is open below it, is triggered by the user, with that action. It comes after the menu has closed.