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 (since QtQuick.Controls 6.5)
  • icon.cache : bool (since QtQuick.Controls 6.5)
  • icon.color : color (since QtQuick.Controls 6.5)
  • icon.height : int (since QtQuick.Controls 6.5)
  • icon.name : string (since QtQuick.Controls 6.5)
  • icon.source : url (since QtQuick.Controls 6.5)
  • icon.width : int (since QtQuick.Controls 6.5)
• 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))

Ausführliche 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

Für Kontextmenüs, siehe Context Menus.

Bei der Verwendung als Popup-Menü ist es am einfachsten, die Position zu bestimmen, indem man die gewünschten Koordinaten x und y über die jeweiligen 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 {
        id: menu
        // ...
        closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent

Sie können Untermenüs erstellen und Action-Objekte innerhalb von Menu 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 auf Desktop-Plattformen, die über einen Mauszeiger verfügen, standardmäßig cascading. Nicht-kaskadierende Menüs werden jeweils einzeln angezeigt und über dem übergeordneten Menü zentriert.

Normalerweise werden Menüeinträge statisch als Kinder des Menüs deklariert, aber Menu bietet auch eine API für add, insert, move und remove dynamische 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.

Kontextmenüs

Für Kontextmenüs ist es einfacher, den angehängten Typ ContextMenu zu verwenden, der ein Menü bei einem plattformspezifischen Ereignis erzeugt. Darüber hinaus bieten Textbearbeitungs-Steuerelemente wie TextField, TextArea, SpinBox und DoubleSpinBox standardmäßig ihre eigenen Kontextmenüs.

Wenn Sie nicht ContextMenu verwenden, ist der empfohlene Weg zum Öffnen des Menüs der Aufruf von popup(). 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:

    TapHandler {
        acceptedButtons: Qt.RightButton
        onPressedChanged: {
            if (pressed && Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Press)
                contextMenu.popup()
        }
        onTapped: {
            if (Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Release)
                contextMenu.popup()
        }
    }
    TapHandler {
        acceptedDevices: PointerDevice.TouchScreen
        onLongPressed: contextMenu.popup()
    }

    Menu {
        id: contextMenu

        MenuItem {
            text: qsTr("Do stuff")
        }
        MenuItem {
            text: qsTr("Do more stuff")
        }
    }

Beachten Sie, dass Sie, wenn Sie Ihr eigenes Kontextmenü für Textbearbeitungssteuerelemente implementieren, es nur auf Desktop-Plattformen anzeigen müssen, da iOS und Android ihre eigenen nativen Kontextmenüs haben:

    TextArea {
        text: qsTr("TextArea")

        // Disable the built-in context menu (since Qt 6.9).
        ContextMenu.menu: null

        TapHandler {
            acceptedButtons: Qt.RightButton
            onPressedChanged: {
                if (pressed === (Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Press))
                    contextMenu.popup()
            }
        }
    }

    Menu {
        id: contextMenu

        MenuItem {
            text: qsTr("Cut")
            // ...
        }
        MenuItem {
            text: qsTr("Copy")
            // ...
        }
        MenuItem {
            text: qsTr("Paste")
            // ...
        }
    }

Margins

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, sich in die Ansicht zu bewegen), setzen Sie die Eigenschaft margins auf -1.

Menüeinträge dynamisch generieren

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

Instantiator verwenden

Sie können Menüeinträge mit Instantiator dynamisch 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. Mehr über diese Optionen erfahren 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.

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 von nativen Menüs wird auf allen Plattformen nur eine Teilmenge der Menü-API 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 das Anzeigen 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 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 im Rendering

Native Menüs werden mit den 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

cascade : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

Diese Eigenschaft legt fest, ob das Menü seine Untermenüs kaskadiert.

Der Standardwert ist plattformspezifisch. Auf Desktop-Plattformen, die über einen Mauszeiger verfügen, werden Menüs standardmäßig kaskadiert. Nicht kaskadierende Menüs werden jeweils einzeln und zentriert über dem übergeordneten Menü angezeigt.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch overlap.

contentData : list<QtObject> [default]

Diese Eigenschaft enthält die Liste der Inhaltsdaten.

Die Liste enthält alle Objekte, die in QML als Unterobjekte des Menüs deklariert wurden, sowie Elemente, die mit den Methoden addItem() und insertItem() dynamisch hinzugefügt bzw. eingefügt wurden.

Siehe auch Item::data und contentChildren.

contentModel : model [read-only]

Diese Eigenschaft enthält das Modell, das zur Anzeige von Menüpunkten verwendet wird.

Das Inhaltsmodell wird für Visualisierungszwecke bereitgestellt. Es kann als Modell einem Inhaltselement zugewiesen werden, das den Inhalt des Menüs darstellt.

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

Das Modell ermöglicht es, Menüpunkte statisch als Kinder des Menüs zu deklarieren.

count : int [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

Diese Eigenschaft enthält die Anzahl der Elemente.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

currentIndex : int [since QtQuick.Controls 2.3 (Qt 5.10)]

Diese Eigenschaft enthält den Index des aktuell hervorgehobenen Elements.

Menüpunkte können durch Mausverschiebung oder Tastaturnavigation hervorgehoben werden.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch MenuItem::highlighted.

delegate : Component [since QtQuick.Controls 2.3 (Qt 5.10)]

Diese Eigenschaft enthält die Komponente, die zur Erstellung von Elementen zur Präsentation von Aktionen verwendet wird.

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

Menu übernimmt nicht den Besitz des Delegates.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch Action.

focus : bool

Diese Eigenschaft gibt an, ob das Popup den Fokus erhalten soll.

Wenn das Popup tatsächlich den Fokus erhält, wird activeFocus zu true. Weitere Informationen finden Sie unter Tastaturfokus in Qt Quick.

Der Standardwert ist true.

Siehe auch activeFocus.

icon group

Diese Eigenschaften wurden in QtQuick.Controls 6.5 eingeführt.

Siehe auch AbstractButton::text, AbstractButton::display, und Icons in Qt Quick Controls.

overlap : real [since QtQuick.Controls 2.3 (Qt 5.10)]

Diese Eigenschaft gibt die Anzahl der Pixel an, um die das Menü sein übergeordnetes Menü horizontal überlappt.

Die Eigenschaft hat nur Auswirkungen, wenn das Menü als kaskadierendes Untermenü verwendet wird.

Der Standardwert ist stilabhängig.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch cascade.

title : string

Diese Eigenschaft enthält den Titel des Menüs.

Der Titel eines Menüs wird oft im Text eines Menüeintrags angezeigt, wenn es sich um ein Untermenü handelt, und im Text einer Werkzeugschaltfläche, wenn sie sich in einer Menüleiste befindet.

Dokumentation der Methode

[since QtQuick.Controls 2.3 (Qt 5.10)] Action actionAt(int index)

Gibt die Aktion an index zurück, oder null wenn der Index nicht gültig ist oder es keine Aktion am angegebenen Index gibt.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

[since QtQuick.Controls 2.3 (Qt 5.10)] void addAction(Action action)

Fügt action am Ende dieses Menüs hinzu. Das Menü übernimmt nicht das Eigentum an dem neu hinzugefügten action.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

void addItem(Item item)

Fügt item am Ende der Liste der Elemente hinzu. Das Menü übernimmt nicht das Eigentum an dem neu hinzugefügten item.

Siehe auch Dynamically Generating Menu Items.

[since QtQuick.Controls 2.3 (Qt 5.10)] void addMenu(Menu menu)

Fügt menu als Untermenü am Ende dieses Menüs hinzu. Das Menü übernimmt nicht das Eigentum an dem neu hinzugefügten menu.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

[since QtQuick.Controls 2.3 (Qt 5.10)] void dismiss()

Schließt alle Menüs in der Hierarchie, zu der dieses Menü gehört.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch popup() und Popup::close().

[since QtQuick.Controls 2.3 (Qt 5.10)] void insertAction(int index, Action action)

Fügt action unter index ein. Der Index befindet sich in allen Einträgen des Menüs. Das Menü übernimmt nicht das Eigentum an dem neu eingefügten action.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

void insertItem(int index, Item item)

Fügt item unter index ein. Das Menü übernimmt nicht den Besitz des neu eingefügten item.

Siehe auch Dynamically Generating Menu Items.

[since QtQuick.Controls 2.3 (Qt 5.10)] void insertMenu(int index, Menu menu)

Fügt menu als Untermenü unter index ein. Der Index befindet sich in allen Einträgen des Menüs. Das Menü übernimmt nicht das Eigentum an dem neu eingefügten menu.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Item itemAt(int index)

Gibt das Element unter index zurück, oder null, wenn es nicht vorhanden ist.

[since QtQuick.Controls 2.3 (Qt 5.10)] Menu menuAt(int index)

Gibt das Untermenü unter index zurück, oder null, wenn der Index nicht gültig ist oder es kein Untermenü am angegebenen Index gibt.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

void moveItem(int from, int to)

Verschiebt ein Element from einen Index to einen anderen.

Öffnet das Menü am Mauszeiger auf Desktop-Plattformen, die über einen Mauszeiger verfügen, und zentriert das Menü andernfalls über seinem parent Element.

Das Menü kann optional auf einen bestimmten Menüpunkt item ausgerichtet werden. Dieses Element wird dann zu current.. Wenn kein item angegeben wird, wird currentIndex auf -1 gesetzt.

Diese Methoden wurden in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch Popup::open().

Öffnet das Menü an der angegebenen Position pos im Popup-Koordinatensystem, d. h. an einer Koordinate relativ zu seinem parent Element.

Das Menü kann optional an einem bestimmten Menüpunkt item ausgerichtet werden. Dieses Element wird dann zu current.. Wenn kein item angegeben ist, wird currentIndex auf -1 gesetzt.

Diese Methoden wurden in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch Popup::open().

Öffnet das Menü an der angegebenen Position x, y im Popup-Koordinatensystem, d. h. an einer Koordinate relativ zu seinem Element parent.

Das Menü kann optional an einem bestimmten Menüpunkt item ausgerichtet werden. Dieses Element wird dann zu current.. Wenn kein item angegeben ist, wird currentIndex auf -1 gesetzt.

Diese Methoden wurden in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch dismiss() und Popup::open().

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeAction(Action action)

Entfernt und zerstört das angegebene action.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeItem(Item item)

Entfernt und zerstört das angegebene item.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeMenu(Menu menu)

Entfernt und zerstört das angegebene menu.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

[since QtQuick.Controls 2.3 (Qt 5.10)] Action takeAction(int index)

Entfernt und gibt die Aktion unter index zurück. Der Index befindet sich in allen Einträgen des Menüs.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

[since QtQuick.Controls 2.3 (Qt 5.10)] MenuItem takeItem(int index)

Entfernt den Artikel und gibt ihn unter index zurück.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

[since QtQuick.Controls 2.3 (Qt 5.10)] Menu takeMenu(int index)

Entfernt und gibt das Menü unter index zurück. Der Index befindet sich innerhalb aller Einträge des Menüs.

Diese Methode wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.