ContextMenu QML Type | Qt Quick Controls (original) (raw)

The ContextMenu attached type provides a way to open a context menu in a platform-appropriate manner. More...

Import Statement: import QtQuick.Controls
Since: Qt 6.9

Properties

Signals

Detailed Description

ContextMenu can be attached to any item in order to show a context menu upon a platform-specific event, such as a right click or the context menu key.

Pane { anchors.fill: parent

ContextMenu.menu: Menu {
    [MenuItem](qml-qtquick-controls-menuitem.html) {
        text: qsTr("Eat Tomato")
        onTriggered: { /* ... */ }
    }
    [MenuItem](qml-qtquick-controls-menuitem.html) {
        text: qsTr("Throw Tomato")
        onTriggered: { /* ... */ }
    }
    [MenuItem](qml-qtquick-controls-menuitem.html) {
        text: qsTr("Squash Tomato")
        onTriggered: { /* ... */ }
    }
}

}

Sharing context menus

It's possible to share a Menu amongst several attached context menu objects. This allows reusing a single Menu when the items that need context menus have data in common. For example:

pragma ComponentBehavior: Bound

import QtQuick import QtQuick.Controls.Basic import QtQuick.Templates as T

ApplicationWindow { width: 600 height: 400 visible: true

component Tomato: [Label](qml-qtquick-controls-label.html) {
    id: tomato
    objectName: text
    horizontalAlignment: Label.AlignHCenter
    verticalAlignment: Label.AlignVCenter
    width: Math.max(200, contentWidth * 1.5, contentWidth * 1.5)
    height: width
    color: skinColor

    function eat() { print("Ate " + text) }
    function ditch() { print("Threw " + text) }
    function squash() { print("Squashed " + text) }

    property [color](qml-color.html) skinColor: "tomato"

    background: Rectangle {
        color: tomato.skinColor
        radius: width / 2
    }

    ContextMenu.menu: contextMenu
}

[Menu](qml-qtquick-controls-menu.html) {
    id: contextMenu

    readonly property Tomato triggerItem: parent as Tomato
    readonly property [string](qml-string.html) triggerItemText: triggerItem?.text ?? ""

    [MenuItem](qml-qtquick-controls-menuitem.html) {
        text: qsTr("Eat %1").arg(contextMenu.triggerItemText)
        onTriggered: contextMenu.triggerItem.eat()
    }
    [MenuItem](qml-qtquick-controls-menuitem.html) {
        text: qsTr("Throw %1").arg(contextMenu.triggerItemText)
        onTriggered: contextMenu.triggerItem.ditch()
    }
    [MenuItem](qml-qtquick-controls-menuitem.html) {
        text: qsTr("Squash %1").arg(contextMenu.triggerItemText)
        onTriggered: contextMenu.triggerItem.squash()
    }
}

[Row](qml-qtquick-row.html) {
    anchors.centerIn: parent

    Tomato {
        text: qsTr("tomato")
    }

    Tomato {
        text: qsTr("really ripe tomato")
        skinColor: "maroon"
    }
}

}

Performance

ContextMenu lazily creates its Menu only when it's requested. If it wasn't for this optimization, the Menu would be created when the containing component is being loaded, which is typically at application startup.

It is recommended not to give the Menu assigned to ContextMenu's menu property an id when it's defined where it's assigned. Doing so prevents this optimization. For example:

Pane { anchors.fill: parent

ContextMenu.menu: Menu {
    // This prevents lazy creation of the Menu.
    id: myMenu

    // ...
}

}

The example in the Sharing context menus section works because the Menu is defined separately from its assignment.

Interaction with other menus

If a Menu is opened via e.g. a TapHandler or other means, ContextMenu will not open at the same time. This allows legacy applications that were written before ContextMenu was introduced to continue working as expected.

Property Documentation

This property holds the context menu that will be opened. It can be set to any Menu object.

Note: The Menu assigned to this property cannot be given an id. See Sharing context menus for more information.

Signal Documentation

requested(point position)

This signal is emitted when a context menu is requested.

If it was requested by a right mouse button click, position gives the position of the click relative to the parent.

The example below shows how to programmatically open a context menu:

Button { id: button text: qsTr("Click me!") ContextMenu.onRequested: position => { const menu = buttonMenu.createObject(button) menu.popup(position) } }

Component { id: buttonMenu Menu { MenuItem { text: qsTr("Open") } } }

If no menu is set, but this signal is connected, the context menu event will be accepted and will not propagate.

Note: The corresponding handler is onRequested.

See also QContextMenuEvent::pos().

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.