Menu QML Type
Menu popup that can be used as a context menu or popup menu. More...
Properties
- cascade : bool
- contentData : list<QtObject>
- contentModel : model
- count : int
- currentIndex : int
- delegate : Component
- focus : bool
- icon
- icon.cache : bool
- icon.color : color
- icon.height : int
- icon.name : string
- icon.source : url
- icon.width : int
- overlap : real
- title : string
Methods
- Action actionAt(int index)
- void addAction(Action action)
- void addItem(Item item)
- void addMenu(Menu menu)
- void dismiss()
- void insertAction(int index, Action action)
- void insertItem(int index, Item item)
- void insertMenu(int index, Menu menu)
- Item itemAt(int index)
- Menu menuAt(int index)
- void moveItem(int from, int to)
- void popup(MenuItem item)
- void popup(Item parent, MenuItem item)
- void popup(point pos, MenuItem item)
- void popup(Item parent, point pos, MenuItem item)
- void popup(real x, real y, MenuItem item)
- void popup(Item parent, real x, real y, MenuItem item)
- void removeAction(Action action)
- void removeItem(Item item)
- void removeMenu(Menu menu)
- Action takeAction(int index)
- MenuItem takeItem(int index)
- Menu takeMenu(int index)
Detailed Description
\inherits
Popup \inqmlmodule
QtQuick.Controls \since
5.7 \ingroup
qtquickcontrols-menus \ingroup
qtquickcontrols-popups
Menu has two main use cases:
- Context menus; for example, a menu that is shown after right clicking
- Popup menus; for example, a menu that is shown after clicking a button
When used as a context menu, the recommended way of opening the menu is to call popup(). Unless a position is explicitly specified, the menu is positioned at the mouse cursor on desktop platforms that have a mouse cursor available, and otherwise centered over its parent item.
MouseArea { anchors.fill: parent acceptedButtons: Qt.LeftButton | Qt.RightButton onClicked: { if (mouse.button === Qt.RightButton) contextMenu.popup() } onPressAndHold: { if (mouse.source === Qt.MouseEventNotSynthesized) contextMenu.popup() } Menu { id: contextMenu MenuItem { text: "Cut" } MenuItem { text: "Copy" } MenuItem { text: "Paste" } } }
When used as a popup menu, it is easiest to specify the position by specifying the desired x and y coordinates using the respective properties, and call open() to open the menu.
Button { id: fileButton text: "File" onClicked: menu.open() Menu { id: menu y: fileButton.height MenuItem { text: "New..." } MenuItem { text: "Open..." } MenuItem { text: "Save" } } }
If the button should also close the menu when clicked, use the Popup.CloseOnPressOutsideParent
flag:
onClicked: menu.visible = !menu.visible Menu { // ... closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent
Since QtQuick.Controls 2.3 (Qt 5.10), it is also possible to create sub-menus and declare Action objects inside Menu:
Menu { Action { text: "Cut" } Action { text: "Copy" } Action { text: "Paste" } MenuSeparator { } Menu { title: "Find/Replace" Action { text: "Find Next" } Action { text: "Find Previous" } Action { text: "Replace" } } }
Sub-menus are cascading by default on desktop platforms that have a mouse cursor available. Non-cascading menus are shown one menu at a time, and centered over the parent menu.
Typically, menu items are statically declared as children of the menu, but Menu also provides API to add, insert, move and remove items dynamically. The items in a menu can be accessed using itemAt() or contentChildren.
Although MenuItems are most commonly used with Menu, it can contain any type of item.
Margins
As it is inherited from Popup, Menu supports margins. By default, all of the built-in styles specify 0
for Menu's margins to ensure that the menu is kept within the bounds of the window. To allow a menu to go outside of the window (to animate it moving into view, for example), set the margins property to -1
.
Dynamically Generating Menu Items
You can dynamically create menu items with Instantiator or dynamic object creation.
Using Instantiator
You can dynamically generate menu items with Instantiator. The following code shows how you can implement a "Recent Files" submenu, where the items come from a list of files stored in settings:
Menu { title: qsTr("File") Menu { id: recentFilesMenu title: qsTr("Recent Files") enabled: recentFilesInstantiator.count > 0 Instantiator { id: recentFilesInstantiator model: settings.recentFiles delegate: MenuItem { text: settings.displayableFilePath(modelData) onTriggered: loadFile(modelData) } onObjectAdded: (index, object) => recentFilesMenu.insertItem(index, object) onObjectRemoved: (index, object) => recentFilesMenu.removeItem(object) } MenuSeparator {} MenuItem { text: qsTr("Clear Recent Files") onTriggered: settings.clearRecentFiles() } } }
Using Dynamic Object Creation
You can also dynamically load a component from a QML file using Qt.createComponent(). Once the component is ready, you can call its createObject() method to create an instance of that component.
Row { anchors.centerIn: parent Component { id: menuItemComponent MenuItem {} } Button { id: button text: "Menu" onClicked: menu.open() Menu { id: menu } } Button { text: "Add item" onClicked: { onClicked: { let menuItem = menuItemComponent.createObject( menu.contentItem, { text: qsTr("New item") }) menu.addMenu(menuItem) } } } }
See also Customizing Menu, MenuItem, Menu Controls, Popup Controls, and Dynamic QML Object Creation from JavaScript.
Property Documentation
cascade : bool |
\since
QtQuick.Controls 2.3 (Qt 5.10)
This property holds whether the menu cascades its sub-menus.
The default value is platform-specific. Menus are cascading by default on desktop platforms that have a mouse cursor available. Non-cascading menus are shown one menu at a time, and centered over the parent menu.
Note: Changing the value of the property has no effect while the menu is open.
See also overlap.
\qmldefault
This property holds the list of content data.
The list contains all objects that have been declared in QML as children of the menu, and also items that have been dynamically added or inserted using the addItem() and insertItem() methods, respectively.
Note: Unlike contentChildren
, contentData
does include non-visual QML objects. It is not re-ordered when items are inserted or moved.
See also Item::data and contentChildren.
contentModel : model |
\readonly
This property holds the model used to display menu items.
The content model is provided for visualization purposes. It can be assigned as a model to a content item that presents the contents of the menu.
Menu { id: menu contentItem: ListView { model: menu.contentModel } }
The model allows menu items to be statically declared as children of the menu.
currentIndex : int |
\since
QtQuick.Controls 2.3 (Qt 5.10)
This property holds the index of the currently highlighted item.
Menu items can be highlighted by mouse hover or keyboard navigation.
See also MenuItem::highlighted.
delegate : Component |
focus : bool |
This property holds whether the popup wants focus.
When the popup actually receives focus, activeFocus will be true
. For more information, see Keyboard Focus in Qt Quick.
The default value is true
.
See also activeFocus.
This property group was added in QtQuick.Controls 6.5.
Name | Description |
---|---|
name | This property holds the name of the icon to use. The icon will be loaded from the platform theme. If the icon is found in the theme, it will always be used; even if icon.source is also set. If the icon is not found, icon.source will be used instead. For more information on theme icons, see QIcon::fromTheme(). |
source | This property holds the name of the icon to use. The icon will be loaded as a regular image. If icon.name is set and refers to a valid theme icon, it will always be used instead of this property. |
width | This property holds the width of the icon. The icon's width will never exceed this value, though it will shrink when necessary. |
height | This property holds the height of the icon. The icon's height will never exceed this value, though it will shrink when necessary. |
color | This property holds the color of the icon. The icon is tinted with the specified color, unless the color is set to |
cache | This property specifies whether the icon should be cached. The default value is true. For more information, see cache. This property was introduced in QtQuick.Controls 2.13. |
See also AbstractButton::text, AbstractButton::display, and Icons in Qt Quick Controls.
overlap : real |
\since
QtQuick.Controls 2.3 (Qt 5.10)
This property holds the amount of pixels by which the menu horizontally overlaps its parent menu.
The property only has effect when the menu is used as a cascading sub-menu.
The default value is style-specific.
Note: Changing the value of the property has no effect while the menu is open.
See also cascade.
title : string |
This property holds the title for the menu.
The title of a menu is often displayed in the text of a menu item when the menu is a submenu, and in the text of a tool button when it is in a menubar.
Method Documentation
\since
QtQuick.Controls 2.3 (Qt 5.10)
Opens the menu at the mouse cursor on desktop platforms that have a mouse cursor available, and otherwise centers the menu over its parent item.
The menu can be optionally aligned to a specific menu item.
See also Popup::open().
\since
QtQuick.Controls 2.3 (Qt 5.10)
Opens the menu at the specified position pos in the popups coordinate system, that is, a coordinate relative to its parent item.
The menu can be optionally aligned to a specific menu item.
See also Popup::open().
\since
QtQuick.Controls 2.3 (Qt 5.10)
Opens the menu at the specified position x, y in the popups coordinate system, that is, a coordinate relative to its parent item.
The menu can be optionally aligned to a specific menu item.
See also dismiss() and Popup::open().
\since
QtQuick.Controls 2.3 (Qt 5.10)
Returns the action at index, or null
if the index is not valid or there is no action at the specified index.
void addAction(Action action) |
\since
QtQuick.Controls 2.3 (Qt 5.10)
Adds action to the end of this menu.
void addItem(Item item) |
Adds item to the end of the list of items.
void addMenu(Menu menu) |
\since
QtQuick.Controls 2.3 (Qt 5.10)
Adds menu as a sub-menu to the end of this menu.
void dismiss() |
\since
QtQuick.Controls 2.3 (Qt 5.10)
Closes all menus in the hierarchy that this menu belongs to.
Note: Unlike close() that only closes a menu and its sub-menus, dismiss()
closes the whole hierarchy of menus, including the parent menus. In practice, close()
is suitable e.g. for implementing navigation in a hierarchy of menus, and dismiss()
is the appropriate method for closing the whole hierarchy of menus.
See also popup() and Popup::close().
\since
QtQuick.Controls 2.3 (Qt 5.10)
Inserts action at index. The index is within all items in the menu.
\since
QtQuick.Controls 2.3 (Qt 5.10)
Inserts menu as a sub-menu at index. The index is within all items in the menu.
\since
QtQuick.Controls 2.3 (Qt 5.10)
Returns the sub-menu at index, or null
if the index is not valid or there is no sub-menu at the specified index.
void removeAction(Action action) |
\since
QtQuick.Controls 2.3 (Qt 5.10)
Removes and destroys the specified action.
void removeItem(Item item) |
\since
QtQuick.Controls 2.3 (Qt 5.10)
Removes and destroys the specified item.
void removeMenu(Menu menu) |
\since
QtQuick.Controls 2.3 (Qt 5.10)
Removes and destroys the specified menu.
\since
QtQuick.Controls 2.3 (Qt 5.10)
Removes and returns the action at index. The index is within all items in the menu.
Note: The ownership of the action is transferred to the caller.
\since
QtQuick.Controls 2.3 (Qt 5.10)
Removes and returns the item at index.
Note: The ownership of the item is transferred to the caller.
\since
QtQuick.Controls 2.3 (Qt 5.10)
Removes and returns the menu at index. The index is within all items in the menu.
Note: The ownership of the menu is transferred to the caller.