Menu QML Type

Popup-Menü, das als Kontextmenü oder Popup-Menü verwendet werden kann. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

• 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

Methoden

• 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))

Detaillierte Beschreibung

Das Menü hat zwei Hauptanwendungsfälle:

• Kontextmenüs, z. B. ein Menü, das nach einem Rechtsklick angezeigt wird
• Popup-Menüs, z. B. ein Menü, das nach einem Klick auf eine Schaltfläche angezeigt wird

Bei der Verwendung als Kontextmenü wird empfohlen, das Menü durch den Aufruf von popup() zu öffnen. Wenn nicht explizit eine Position angegeben wird, wird das Menü auf Desktop-Plattformen, die über einen Mauszeiger verfügen, am Mauszeiger positioniert und ansonsten über seinem übergeordneten Element zentriert.

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" }
    }
}

Bei der Verwendung als Popup-Menü ist es am einfachsten, die Position anzugeben, indem man die gewünschten Koordinaten x und y über die entsprechenden Eigenschaften angibt und open() aufruft, um das Menü zu öffnen.

Button {
    id: fileButton
    text: "File"
    onClicked: menu.open()

    Menu {
        id: menu
        y: fileButton.height

        MenuItem {
            text: "New..."
        }
        MenuItem {
            text: "Open..."
        }
        MenuItem {
            text: "Save"
        }
    }
}

Wenn die Schaltfläche auch das Menü schließen soll, wenn sie angeklickt wird, verwenden Sie das Flag Popup.CloseOnPressOutsideParent:

onClicked: menu.visible = !menu.visible

Menu {
    // ...
    closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent

Seit QtQuick.Controls 2.3 (Qt 5.10) ist es auch möglich, Untermenüs zu erstellen und Action-Objekte innerhalb von Menu zu deklarieren:

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" }
    }
}

Untermenüs sind standardmäßig cascading auf Desktop-Plattformen, die über einen Mauszeiger verfügen. Nicht-kaskadierende Menüs werden jeweils einzeln und zentriert über dem übergeordneten Menü angezeigt.

Normalerweise werden Menüeinträge statisch als Kinder des Menüs deklariert, aber Menu bietet auch eine dynamische API für add, insert, move und remove Einträge. Auf die Einträge in einem Menü kann mit itemAt() oder contentChildren zugegriffen werden.

Obwohl MenuItems am häufigsten mit Menu verwendet wird, kann es jede Art von Element enthalten.

Ränder

Da es von Popup geerbt wurde, unterstützt Menu margins. Standardmäßig geben alle eingebauten Stile 0 für die Ränder von Menu an, um sicherzustellen, dass das Menü innerhalb der Grenzen des Fensters gehalten wird. Um ein Menü außerhalb des Fensters zuzulassen (z. B. um es zu animieren, wenn es sich in die Ansicht bewegt), setzen Sie die Eigenschaft margins auf -1.

Menüpunkte dynamisch generieren

Sie können Menüpunkte mit Instantiator oder dynamischer Objekterstellung dynamisch erstellen.

Verwendung von Instantiator

Sie können Menüpunkte dynamisch mit Instantiator erzeugen. Der folgende Code zeigt, wie Sie ein Untermenü "Letzte Dateien" implementieren können, wobei die Einträge aus einer Liste von Dateien stammen, die in den Einstellungen gespeichert sind:

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()
        }
    }
}

Dynamische Objekterzeugung verwenden

Sie können eine Komponente auch dynamisch aus einer QML-Datei laden, indem Sie Qt.createComponent() verwenden. Sobald die Komponente fertig ist, können Sie ihre Methode createObject() aufrufen, um eine Instanz dieser Komponente zu erstellen.

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.addItem(menuItem)
            }
        }
    }
}

Menü-Typen

Seit Qt 6.8 bietet ein Menü drei verschiedene Implementierungen, abhängig von der Plattform. Sie können wählen, welche bevorzugt werden soll, indem Sie popupType setzen. Damit können Sie steuern, ob ein Menü als separates Fenster, als Element innerhalb des übergeordneten Fensters oder als natives Menü angezeigt werden soll. Weitere Informationen zu diesen Optionen finden Sie unter here.

Die Standardeinstellung popupType wird durch den Stil bestimmt. Der macOS-Stil legt beispielsweise Popup.Native fest, während der Imagine-Stil Popup.Window verwendet (was der Standard ist, wenn der Stil keinen Popup-Typ festlegt). Wenn Sie einem Menü Anpassungen hinzufügen und möchten, dass diese unabhängig vom Stil verwendet werden, sollten Sie den Popup-Typ explizit auf Popup.Window (oder Popup.Item) setzen. Eine andere Alternative ist die Einstellung Qt::AA_DontUseNativeMenuWindows application attribute . Dadurch werden die nativen Kontextmenüs für die gesamte Anwendung deaktiviert, unabhängig vom Stil.

Die Voreinstellung popupType wird durch den Stil bestimmt. Der macOS-Stil zum Beispiel setzt ihn auf Popup.Native, während der Imagine-Stil Popup.Window verwendet (was der Standard ist, wenn der Stil keinen Popup-Typ festlegt). Wenn Sie einem Menü Anpassungen hinzufügen und möchten, dass diese unabhängig vom Stil verwendet werden, sollten Sie den Popup-Typ explizit auf Popup.Window (oder Popup.Item) setzen.

Ob ein Menü den bevorzugten Typ verwenden kann, hängt von der Plattform ab. Popup.Item wird auf allen Plattformen unterstützt, aber Popup.Window wird normalerweise nur auf Desktop-Plattformen unterstützt. Wenn sich das Menü innerhalb eines native menubar befindet, ist das Menü ebenfalls nativ. Und wenn das Menü ein Untermenü innerhalb eines anderen Menüs ist, entscheidet das übergeordnete (oder Stamm-)Menü über den Typ.

Beschränkungen bei der Verwendung nativer Menüs

Bei der Einstellung von popupType auf Popup.Native gibt es einige Einschränkungen und Unterschiede im Vergleich zur Verwendung von Popup.Item und Popup.Window.

API-Unterschiede

Bei der Verwendung nativer Menüs wird nur eine Teilmenge der Menü-API auf allen Plattformen unterstützt:

• x
• y
• visible
• opened
• title
• count
• contentData
• contentChildren (visuelle Kinder werden nicht sichtbar sein)
• contentModel
• open()
• popup()
• close()
• opened()
• closed()
• aboutToShow()
• aboutToHide()

Darüber hinaus ist die Anzeige eines Popup-Menüs (z. B. mit open() oder popup()) auf einigen Plattformen ein blockierender Aufruf. Das bedeutet, dass der Aufruf nicht zurückkehrt, bevor das Menü wieder geschlossen wird, was sich auf die Logik in Ihrer Anwendung auswirken kann. Dies ist vor allem dann zu berücksichtigen, wenn Ihre Anwendung auf mehrere Plattformen ausgerichtet ist und daher manchmal auf Plattformen läuft, auf denen native Menüs nicht unterstützt werden. In diesem Fall wird der PopupType z. B. auf Popup.Item zurückfallen, und die Aufrufe von open() werden nicht blockiert.

Elemente wie MenuItem reagieren immer noch auf Klicks im entsprechenden nativen Menüelement, indem sie z. B. Signale ausgeben, werden aber durch ihr natives Gegenstück ersetzt.

Unterschiede bei der Darstellung

Native Menüs werden mithilfe der auf der Plattform verfügbaren nativen Menü-APIs implementiert. Diese Menüs und ihr gesamter Inhalt werden daher von der Plattform und nicht von QML gerendert. Das bedeutet, dass delegate nicht für das Rendering verwendet wird. Es wird jedoch immer instanziiert (aber versteckt), so dass Funktionen wie onCompleted() unabhängig von der Plattform und popupType ausgeführt werden.

Unterstützte Plattformen

Native Menüs werden derzeit auf den folgenden Plattformen unterstützt:

• Android
• iOS
• Linux (nur als eigenständiges Kontextmenü verfügbar, wenn es mit dem GTK+-Plattformthema ausgeführt wird)
• macOS
• Windows

Siehe auch Menü anpassen, MenuItem, Menü-Steuerelemente, Popup-Steuerelemente, Dynamische QML-Objekterzeugung aus JavaScript, Popup type, [QML], und popupType.

Dokumentation der Eigenschaften

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

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

Dokumentation der Methode