Menu QML Type

Menu popup that can be used as a context menu or popup menu. More...

• List of all members, including inherited members

Properties

• cascade : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• contentData : list<QtObject>
• contentModel : model
• count : int (since QtQuick.Controls 2.3 (Qt 5.10))
• currentIndex : int (since QtQuick.Controls 2.3 (Qt 5.10))
• delegate : Component (since QtQuick.Controls 2.3 (Qt 5.10))
• focus : bool
• icon
  • icon.cache : bool
  • icon.color : color
  • icon.height : int
  • icon.name : string
  • icon.source : url
  • icon.width : int
• overlap : real (since QtQuick.Controls 2.3 (Qt 5.10))
• title : string

Methods

• Action actionAt(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• void addAction(Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void addItem(Item item)
• void addMenu(Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• void dismiss() (since QtQuick.Controls 2.3 (Qt 5.10))
• void insertAction(int index, Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void insertItem(int index, Item item)
• void insertMenu(int index, Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• Item itemAt(int index)
• Menu menuAt(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• void moveItem(int from, int to)
• void popup(MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(point pos, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, point pos, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(real x, real y, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, real x, real y, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeAction(Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeItem(Item item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeMenu(Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• Action takeAction(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• MenuItem takeItem(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• Menu takeMenu(int index) (since QtQuick.Controls 2.3 (Qt 5.10))

Detailed Description

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

 Menu {
     id: menu
     contentItem: ListView {
         model: menu.contentModel
     }
 }

 Menu {
     Action { text: "Cut" }
     Action { text: "Copy" }
     Action { text: "Paste" }
 }

Method Documentation