QMenu Class
The QMenu class provides a menu widget for use in menu bars, context menus, and other popup menus. More...
| Header: | #include <QMenu> |
| qmake: | QT += widgets |
| Inherits: | QWidget |
Properties
|
|
Public Functions
| QIcon | icon() const |
| bool | isTearOffEnabled() const |
| bool | separatorsCollapsible() const |
| void | setIcon(const QIcon &icon) |
| void | setSeparatorsCollapsible(bool collapse) |
| void | setTearOffEnabled(bool) |
| void | setTitle(const QString &title) |
| void | setToolTipsVisible(bool visible) |
| QString | title() const |
| bool | toolTipsVisible() const |
Detailed Description
A menu widget is a selection menu. It can be either a pull-down menu in a menu bar or a standalone context menu. Pull-down menus are shown by the menu bar when the user clicks on the respective item or presses the specified shortcut key. Use QMenuBar::addMenu() to insert a menu into a menu bar. Context menus are usually invoked by some special keyboard key or by right-clicking. They can be executed either asynchronously with popup() or synchronously with exec(). Menus can also be invoked in response to button presses; these are just like context menus except for how they are invoked.
Actions
A menu consists of a list of action items. Actions are added with the addAction(), addActions() and insertAction() functions. An action is represented vertically and rendered by QStyle. In addition, actions can have a text label, an optional icon drawn on the very left side, and shortcut key sequence such as "Ctrl+X".
The existing actions held by a menu can be found with actions().
There are four kinds of action items: separators, actions that show a submenu, widgets, and actions that perform an action. Separators are inserted with addSeparator(), submenus with addMenu(), and all other items are considered action items.
When inserting action items you usually specify a receiver and a slot. The receiver will be notified whenever the item is triggered(). In addition, QMenu provides two signals, triggered() and hovered(), which signal the QAction that was triggered from the menu.
You clear a menu with clear() and remove individual action items with removeAction().
A QMenu can also provide a tear-off menu. A tear-off menu is a top-level window that contains a copy of the menu. This makes it possible for the user to "tear off" frequently used menus and position them in a convenient place on the screen. If you want this functionality for a particular menu, insert a tear-off handle with setTearOffEnabled(). When using tear-off menus, bear in mind that the concept isn't typically used on Microsoft Windows so some users may not be familiar with it. Consider using a QToolBar instead.
Widgets can be inserted into menus with the QWidgetAction class. Instances of this class are used to hold widgets, and are inserted into menus with the addAction() overload that takes a QAction. If the QWidgetAction fires the triggered() signal, the menu will close.
Warning: To make QMenu visible on the screen, exec() or popup() should be used instead of show().
QMenu on macOS with Qt Build Against Cocoa
QMenu can be inserted only once in a menu/menubar. Subsequent insertions will have no effect or will result in a disabled menu item.
See the Menus example for an example of how to use QMenuBar and QMenu in your application.
Important inherited functions: addAction(), removeAction(), clear(), addSeparator(), and addMenu().
See also QMenuBar, GUI Design Handbook: Menu, Drop-Down and Pop-Up, Application Example, and Menus Example.
Property Documentation
icon : QIcon
This property holds the icon of the menu
This is equivalent to the QAction::icon property of the menuAction().
By default, if no icon is explicitly set, this property contains a null icon.
Access functions:
| QIcon | icon() const |
| void | setIcon(const QIcon &icon) |
separatorsCollapsible : bool
This property holds whether consecutive separators should be collapsed
This property specifies whether consecutive separators in the menu should be visually collapsed to a single one. Separators at the beginning or the end of the menu are also hidden.
By default, this property is true.
This property was introduced in Qt 4.2.
Access functions:
| bool | separatorsCollapsible() const |
| void | setSeparatorsCollapsible(bool collapse) |
tearOffEnabled : bool
This property holds whether the menu supports being torn off
When true, the menu contains a special tear-off item (often shown as a dashed line at the top of the menu) that creates a copy of the menu when it is triggered.
This "torn-off" copy lives in a separate window. It contains the same menu items as the original menu, with the exception of the tear-off handle.
By default, this property is false.
Access functions:
| bool | isTearOffEnabled() const |
| void | setTearOffEnabled(bool) |
title : QString
This property holds the title of the menu
This is equivalent to the QAction::text property of the menuAction().
By default, this property contains an empty string.
Access functions:
| QString | title() const |
| void | setTitle(const QString &title) |
toolTipsVisible : bool
This property holds whether tooltips of menu actions should be visible
This property specifies whether action menu entries show their tooltip.
By default, this property is false.
This property was introduced in Qt 5.1.
Access functions:
| bool | toolTipsVisible() const |
| void | setToolTipsVisible(bool visible) |