Menu QML Type

Menu popup qui peut être utilisé comme menu contextuel ou menu popup. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• 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

Méthodes

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

Description détaillée

Le menu a deux utilisations principales :

• Les menus contextuels ; par exemple, un menu qui s'affiche après un clic droit.
• Menus contextuels ; par exemple, un menu qui s'affiche après avoir cliqué sur un bouton.

Pour les menus contextuels, voir Context Menus.

Lorsqu'il s'agit d'un menu contextuel, il est plus facile de spécifier la position en indiquant les coordonnées x et y souhaitées à l'aide des propriétés respectives, et d'appeler open() pour ouvrir le menu.

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

    Menu {
        id: menu
        y: fileButton.height

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

Si le bouton doit également fermer le menu lorsqu'il est cliqué, utilisez l'indicateur Popup.CloseOnPressOutsideParent:

    onClicked: menu.visible = !menu.visible

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

Vous pouvez créer des sous-menus et déclarer des objets Action à l'intérieur de 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" }
    }
}

Les sous-menus sont affichés par défaut à l'adresse cascading sur les plates-formes de bureau qui disposent d'un curseur de souris. Les menus non en cascade sont affichés un par un et centrés sur le menu parent.

En règle générale, les éléments de menu sont déclarés de manière statique en tant qu'enfants du menu, mais Menu fournit également une API pour les éléments add, insert, move et remove de manière dynamique. Les éléments d'un menu sont accessibles à l'aide de itemAt() ou contentChildren.

Bien que MenuItems soit le plus souvent utilisé avec Menu, il peut contenir n'importe quel type d'élément.

Menus contextuels

Pour les menus contextuels, il est plus facile d'utiliser le type de pièce jointe ContextMenu, qui crée un menu lors d'un événement spécifique à la plate-forme. En outre, les contrôles d'édition de texte tels que TextField, TextArea, SpinBox et DoubleSpinBox fournissent leurs propres menus contextuels par défaut.

Si vous n'utilisez pas ContextMenu, la méthode recommandée pour ouvrir le menu est d'appeler popup(). À moins qu'une position ne soit explicitement spécifiée, le menu est positionné au niveau du curseur de la souris sur les plates-formes de bureau qui disposent d'un curseur de souris, et sinon il est centré sur son élément parent :

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

Notez que si vous implémentez votre propre menu contextuel pour les contrôles d'édition de texte, vous n'avez besoin de l'afficher que sur les plateformes de bureau, car iOS et Android ont leurs propres menus contextuels natifs :

    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")
            // ...
        }
    }

Marges

Comme il est hérité de Popup, Menu prend en charge margins. Par défaut, tous les styles intégrés spécifient 0 pour les marges de Menu afin de garantir que le menu reste dans les limites de la fenêtre. Pour permettre à un menu de sortir de la fenêtre (pour l'animer en l'affichant, par exemple), définissez la propriété des marges à -1.

Génération dynamique d'éléments de menu

Vous pouvez créer dynamiquement des éléments de menu à l'aide de Instantiator ou de la création dynamique d'objets.

Utilisation de l'instanciateur

Vous pouvez générer dynamiquement des éléments de menu à l'aide de Instantiator. Le code suivant montre comment implémenter un sous-menu "Fichiers récents", dont les éléments proviennent d'une liste de fichiers stockés dans les paramètres :

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

Utilisation de la création dynamique d'objets

Vous pouvez également charger dynamiquement un composant à partir d'un fichier QML à l'aide de Qt.createComponent(). Une fois le composant prêt, vous pouvez appeler sa méthode createObject() pour créer une instance de ce composant.

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

Types de menus

Depuis Qt 6.8, un menu offre trois implémentations différentes, en fonction de la plateforme. Vous pouvez choisir celle qui sera préférée en définissant popupType. Cela vous permettra de contrôler si un menu doit être affiché comme une fenêtre séparée, comme un élément à l'intérieur de la fenêtre parent, ou comme un menu natif. Pour en savoir plus sur ces options, consultez le site here.

L'adresse popupType par défaut est déterminée par le style. Le style macOS, par exemple, la fixe à Popup.Native, tandis que le style Imagine utilise Popup.Window (qui est la valeur par défaut lorsque le style ne définit pas de type de fenêtre contextuelle). Si vous ajoutez des personnalisations à un menu et que vous souhaitez qu'elles soient utilisées quel que soit le style, vous devez définir explicitement le type de fenêtre contextuelle comme étant Popup.Window (ou Popup.Item). Une autre solution consiste à définir le type Qt::AA_DontUseNativeMenuWindows application attribute . Cela désactivera les menus contextuels natifs pour l'ensemble de l'application, quel que soit le style.

La possibilité pour un menu d'utiliser le type préféré dépend de la plate-forme. Popup.Item est pris en charge sur toutes les plates-formes, mais Popup.Window n'est normalement pris en charge que sur les plates-formes de bureau. En outre, si le menu se trouve à l'intérieur d'un site native menubar, il sera également de type natif. Si le menu est un sous-menu à l'intérieur d'un autre menu, c'est le menu parent (ou racine) qui détermine le type de menu.

Limites de l'utilisation des menus natifs

Lorsque vous utilisez popupType pour Popup.Native, il existe certaines limitations et différences par rapport à l'utilisation de Popup.Item et Popup.Window.

Différences au niveau de l'API

Lors de l'utilisation de menus natifs, seul un sous-ensemble de l'API des menus est pris en charge sur toutes les plateformes :

• x
• y
• visible
• opened
• title
• count
• contentData
• contentChildren (les enfants visuels ne seront pas visibles)
• contentModel
• open()
• popup()
• close()
• opened()
• closed()
• aboutToShow()
• aboutToHide()

En outre, l'affichage d'une fenêtre contextuelle (à l'aide, par exemple, de open() ou popup()) est un appel bloquant sur certaines plates-formes. Cela signifie que l'appel ne reviendra pas avant que le menu ne soit refermé, ce qui peut affecter la logique de votre application. Il est particulièrement important de prendre cela en considération si votre application vise plusieurs plateformes et, à ce titre, est parfois exécutée sur des plateformes où les menus natifs ne sont pas pris en charge. Dans ce cas, le type de popup reviendra à Popup.Item, par exemple, et les appels à open() ne seront pas bloquants.

Les éléments tels que MenuItem réagiront toujours aux clics dans l'élément de menu natif correspondant en émettant des signaux, par exemple, mais ils seront remplacés par leur équivalent natif.

Différences de rendu

Les menus natifs sont mis en œuvre à l'aide des API de menu natif disponibles sur la plateforme. Ces menus, et l'ensemble de leur contenu, seront donc rendus par la plateforme, et non par QML. Cela signifie que le site delegate ne sera pas utilisé pour le rendu. Il sera cependant toujours instancié (mais caché), de sorte que des fonctions telles que onCompleted() s'exécutent indépendamment de la plate-forme et de popupType.

Plates-formes prises en charge

Les menus natifs sont actuellement pris en charge sur les plateformes suivantes :

• Android
• iOS
• Linux (uniquement disponible en tant que menu contextuel autonome lorsqu'il est exécuté avec le thème de plateforme GTK+)
• macOS
• Windows

Voir aussi Personnalisation du menu, MenuItem, Contrôles de menu, Contrôles de fenêtre contextuelle, Création dynamique d'objets QML à partir de JavaScript, Popup type, [QML], et popupType.

Documentation sur les propriétés

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

Cette propriété indique si le menu se répercute sur ses sous-menus.

La valeur par défaut est spécifique à la plate-forme. Les menus sont affichés en cascade par défaut sur les plates-formes de bureau qui disposent d'un curseur de souris. Les menus qui ne sont pas en cascade sont affichés un par un et centrés sur le menu parent.

Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

Voir également overlap.

contentData : list<QtObject> [default]

Cette propriété contient la liste des données de contenu.

La liste contient tous les objets qui ont été déclarés en QML comme enfants du menu, ainsi que les éléments qui ont été ajoutés ou insérés dynamiquement à l'aide des méthodes addItem() et insertItem(), respectivement.

Voir également Item::data et contentChildren.

contentModel : model [read-only]

Cette propriété contient le modèle utilisé pour afficher les éléments du menu.

Le modèle de contenu est fourni à des fins de visualisation. Il peut être attribué comme modèle à un élément de contenu qui présente le contenu du menu.

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

Le modèle permet aux éléments de menu d'être déclarés statiquement comme enfants du menu.

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

Cette propriété contient le nombre d'éléments.

Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

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

Cette propriété contient l'index de l'élément actuellement mis en évidence.

Les éléments de menu peuvent être mis en surbrillance au survol de la souris ou par navigation au clavier.

Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

Voir également MenuItem::highlighted.

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

Cette propriété contient le composant utilisé pour créer des éléments afin de présenter des actions.

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

Le menu n'est pas propriétaire du délégué.

Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

Voir également Action.

focus : bool

Cette propriété indique si la fenêtre popup souhaite être mise en avant.

Lorsque la fenêtre contextuelle reçoit effectivement le focus, activeFocus sera true. Pour plus d'informations, voir Keyboard Focus à l'adresse Qt Quick.

La valeur par défaut est true.

Voir également activeFocus.

icon group

Ces propriétés ont été introduites dans QtQuick.Controls 6.5.

Voir également AbstractButton::text, AbstractButton::display, et Icons in Qt Quick Controls.

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

Cette propriété indique la quantité de pixels par laquelle le menu chevauche horizontalement son menu parent.

Cette propriété n'a d'effet que lorsque le menu est utilisé comme sous-menu en cascade.

La valeur par défaut est spécifique au style.

Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

Voir également cascade.

title : string

Cette propriété contient le titre du menu.

Le titre d'un menu est souvent affiché dans le texte d'un élément de menu lorsque le menu est un sous-menu, et dans le texte d'un bouton d'outil lorsqu'il se trouve dans une barre de menus.

Documentation de la méthode

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

Renvoie l'action à index, ou null si l'index n'est pas valide ou s'il n'y a pas d'action à l'index spécifié.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

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

Ajoute action à la fin de ce menu. Le menu n'est pas propriétaire de l'adresse action nouvellement ajoutée.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

void addItem(Item item)

Ajoute item à la fin de la liste des éléments. Le menu n'est pas propriétaire de l'élément nouvellement ajouté item.

Voir également Dynamically Generating Menu Items.

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

Ajoute menu comme sous-menu à la fin de ce menu. Le menu ne prend pas possession du nouveau menu.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

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

Ferme tous les menus de la hiérarchie à laquelle ce menu appartient.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

Voir également popup() et Popup::close().

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

Insère action à index. L'index se trouve dans tous les éléments du menu. Le menu n'est pas propriétaire de l'élément nouvellement inséré action.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

void insertItem(int index, Item item)

Insère item à index. Le menu ne s'approprie pas la nouvelle insertion item.

Voir également Dynamically Generating Menu Items.

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

Insère menu comme sous-menu à index. L'index se trouve dans tous les éléments du menu. Le menu n'est pas propriétaire de l'élément nouvellement inséré menu.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

Item itemAt(int index)

Renvoie l'élément à index, ou null s'il n'existe pas.

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

Renvoie le sous-menu à index, ou null si l'index n'est pas valide ou s'il n'y a pas de sous-menu à l'index spécifié.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

void moveItem(int from, int to)

Déplace un élément from d'un index to à un autre.

Ouvre le menu au niveau du curseur de la souris sur les plates-formes de bureau qui disposent d'un curseur de souris, et centre le menu sur son élément parent.

Le menu peut éventuellement être aligné sur un menu spécifique item. Cet élément deviendra alors current. Si aucun item n'est spécifié, currentIndex sera défini comme -1.

Ces méthodes ont été introduites dans QtQuick.Controls 2.3 (Qt 5.10).

Voir aussi Popup::open().

Ouvre le menu à la position spécifiée pos dans le système de coordonnées des fenêtres contextuelles, c'est-à-dire une coordonnée relative à son élément parent.

Le menu peut éventuellement être aligné sur un menu spécifique item. Cet élément deviendra alors current. Si aucun item n'est spécifié, currentIndex sera défini comme -1.

Ces méthodes ont été introduites dans QtQuick.Controls 2.3 (Qt 5.10).

Voir aussi Popup::open().

Ouvre le menu à la position spécifiée x, y dans le système de coordonnées des fenêtres contextuelles, c'est-à-dire une coordonnée relative à son élément parent.

Le menu peut éventuellement être aligné sur un menu spécifique item. Cet élément deviendra alors current.. Si aucun item n'est spécifié, currentIndex sera placé à -1.

Ces méthodes ont été introduites dans QtQuick.Controls 2.3 (Qt 5.10).

Voir aussi dismiss() et Popup::open().

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

Supprime et détruit l'adresse action spécifiée.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

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

Supprime et détruit l'adresse item spécifiée.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

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

Supprime et détruit l'adresse menu spécifiée.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

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

Supprime et renvoie l'action à index. L'index se trouve dans tous les éléments du menu.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

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

Retire et renvoie l'article à index.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

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

Supprime et renvoie le menu à l'adresse index. L'index se trouve dans tous les éléments du menu.

Cette méthode a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).