Menu QML Type

Menu contextuel pouvant servir de menu de contexte ou de menu déroulant. En savoir plus…

• 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))
• separatorsCollapsible : bool (since QtQuick.Controls 6.12 (Qt 6.12))
• 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 présente deux cas d'utilisation principaux :

• 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, consultez Context Menus.

Lorsqu’il est utilisé comme menu contextuel, le plus simple est de définir sa position en indiquant les coordonnées souhaitées ( x et y ) à l’aide des propriétés correspondantes, puis d’appeler la fonction 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’on clique dessus, 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 cascading par défaut sur les plateformes de bureau disposant d’un curseur de souris. Les menus non s’affichent un par un et sont centrés par rapport au menu parent.

En général, 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 permettant d’ add, d’ insert, d’ move et d’ remove des éléments de manière dynamique. Les éléments d’un menu sont accessibles via ` itemAt()` ou ` contentChildren`.

Bien que les éléments de type « MenuItems » soient les plus couramment utilisés avec Menu, celui-ci peut contenir n’importe quel type d’élément.

Menus contextuels

Pour les menus contextuels, il est plus simple d’utiliser le type associé « ContextMenu », qui crée un menu lors d’un événement spécifique à la plateforme. De plus, 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 consiste à 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 plateformes de bureau disposant d’un curseur de souris, et sinon 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 disposent de 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 hérite de la classe `Popup`, `Menu` prend en charge la propriété ` margins`. Par défaut, tous les styles intégrés définissent ` 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 dépasser les limites de la fenêtre (afin de l’animer lorsqu’il apparaît à l’écran, par exemple), définissez la propriété `margins` sur ` -1`.

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

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

Utilisation d’Instantiator

Vous pouvez générer dynamiquement des éléments de menu à l’aide d’ 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 propose trois implémentations différentes, selon la plateforme. Vous pouvez choisir celle que vous préférez en définissant ` popupType`. Cela vous permettra de contrôler si un menu doit s’afficher dans une fenêtre distincte, en tant qu’élément à l’intérieur de la fenêtre parente, ou sous forme de menu natif. Pour en savoir plus sur ces options, consultez ` here`.

La valeur par défaut de ` popupType ` est déterminée par le style. Le style macOS, par exemple, la définit sur ` Popup.Native`, tandis que le style Imagine utilise ` Popup.Window ` (ce qui correspond à la valeur par défaut lorsque le style ne spécifie pas de type de menu contextuel). Si vous ajoutez des personnalisations à un menu et que vous souhaitez qu’elles s’appliquent quel que soit le style, vous devez définir explicitement le type de menu contextuel sur « Popup.Window » (ou « Popup.Item »). Une autre solution consiste à définir la propriété « Qt::AA_DontUseNativeMenuWindows » sur « 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 plateforme. Le type « Popup.Item » est pris en charge sur toutes les plateformes, mais le type « Popup.Window » n’est généralement pris en charge que sur les plateformes de bureau. De plus, si le menu se trouve à l’intérieur d’un élément « native menubar », il sera également natif. Et si le menu est un sous-menu à l’intérieur d’un autre menu, c’est le menu parent (ou racine) qui déterminera le type.

Limitations liées à l’utilisation des menus natifs

Lorsque vous définissez ` popupType ` sur ` 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 des menus natifs, seul un sous-ensemble de l’API Menu est pris en charge sur toutes les plateformes :

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

De plus, l'affichage d'une fenêtre contextuelle (à l'aide, par exemple, de open() ou popup()) constituera un appel bloquant sur certaines plateformes. Cela signifie que l'appel ne se terminera pas avant la fermeture du menu, ce qui peut affecter la logique de votre application. Il est particulièrement important d’en tenir compte si votre application cible plusieurs plateformes et, à ce titre, s’exécute parfois sur des plateformes où les menus natifs ne sont pas pris en charge. Dans ce cas, le paramètre popupType reviendra par défaut à Popup.Item, par exemple, et les appels à open() ne seront pas bloquants.

Les éléments tels que ` MenuItem ` continueront de réagir aux clics sur l’élément de menu natif correspondant en émettant des signaux, par exemple, mais seront remplacés par leur équivalent natif.

Différences d’affichage

Les menus natifs sont implémentés à l’aide des API de menus natifs disponibles sur la plateforme. Ces menus, ainsi que l’ensemble de leur contenu, seront donc rendus par la plateforme, et non par QML. Cela signifie que l’ delegate ne sera pas utilisé pour le rendu. Il sera toutefois toujours instancié (mais masqué), de sorte que des fonctions telles que onCompleted() s’exécutent quelle que soit la plateforme et popupType.

Plateformes prises en charge

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

• Android
• iOS
• Linux (disponible uniquement sous forme de menu contextuel autonome lors de l’exécution avec le thème de la plateforme GTK+)
• macOS
• Windows

Voir aussi Personnalisation des menus, MenuItem, Contrôles de menu, Contrôles contextuels, 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é détermine si le menu affiche ses sous-menus en cascade.

La valeur par défaut dépend de la plateforme. Sur les plateformes de bureau disposant d'un curseur de souris, les menus sont en cascade par défaut. Les menus non en cascade s'affichent un par un et sont centrés par rapport au 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.

Cette liste contient tous les objets déclarés en QML en tant qu’enfants du menu, ainsi que les éléments 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é en tant que modèle à un élément de contenu qui présente le contenu du menu.

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

Ce modèle permet de déclarer de manière statique les éléments de menu en tant qu’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 sélectionné.

Les éléments de menu peuvent être mis en surbrillance au passage de la souris ou via la 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 permettant d'afficher des actions.

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

Le menu ne prend pas possession 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 contextuelle souhaite recevoir le focus.

Lorsque la fenêtre contextuelle reçoit effectivement le focus, la valeur « activeFocus » devient « true ». Pour plus d'informations, consultez la section «Focus clavier» à 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 « Icônes » dans « Qt Quick Controls ».

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

Cette propriété définit le nombre de pixels de chevauchement horizontal du menu par rapport à 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 dépend du style.

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

Voir également cascade.

separatorsCollapsible : bool [since QtQuick.Controls 6.12 (Qt 6.12)]

Cette propriété détermine si les séparateurs consécutifs doivent être masqués.

Lorsque cette propriété est définie sur « true », le menu masque automatiquement les séparateurs qui apparaîtraient au début ou à la fin des éléments visibles, ainsi que les séparateurs consécutifs entre lesquels tous les éléments sont masqués. Ce comportement correspond à celui de l’option « QMenu::separatorsCollapsible » (Masquer les séparateurs non nécessaires) dans Qt Widgets.

La valeur par défaut est « true ».

Cette fonctionnalité est utile lorsque les éléments de menu sont affichés ou masqués de manière dynamique, car elle empêche l’affichage de séparateurs orphelins.

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

Voir également MenuSeparator.

title : string

Cette propriété contient le titre du menu.

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

Documentation des méthodes

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

Renvoie l'action associée à l'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 ne prend pas en charge le « action » nouvellement ajouté.

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 ne prend pas possession 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 » en tant que sous-menu à la fin de ce menu. Le menu ne prend pas possession du « menu » nouvellement ajouté.

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 appartient ce menu.

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 à l'adresse index. L'index figure parmi tous les éléments du menu. Le menu ne prend pas possession du action nouvellement inséré.

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

void insertItem(int index, Item item)

Insère item à l'adresse index. Le menu ne prend pas possession du fichier item nouvellement inséré.

Voir également Dynamically Generating Menu Items.

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

Insère menu en tant que sous-menu à l'adresse index. L'index figure parmi tous les éléments du menu. Le menu ne prend pas possession du lien menu nouvellement inséré.

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

Item itemAt(int index)

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

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

Renvoie le sous-menu situé à l'adresse index, ou null si l'index n'est pas valide ou s'il n'existe aucun 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 vers un autre.

Ouvre le menu à l'emplacement du curseur de la souris sur les plateformes de bureau disposant d'un curseur de souris ; dans le cas contraire, centre le menu sur son élément d'parent.

Le menu peut, au choix, être aligné sur une position spécifique ( item). Cet élément prendra alors la valeur « current. ». Si aucune position ( item ) n’est spécifiée, la position ( currentIndex ) sera définie sur « -1 ».

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

Voir également 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, si nécessaire, être aligné sur une position spécifique du menu item. Cet élément deviendra alors current.. Si aucune item n'est spécifiée, currentIndex sera défini sur -1.

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

Voir également 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, au choix, ê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 sur -1.

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

Voir également dismiss() et Popup::open().

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

Supprime et détruit l'action 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 removeItem(Item item)

Supprime et détruit l'item 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 removeMenu(Menu menu)

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

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 située à l'adresse index. L'index correspond à l'un des é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)

Supprime et renvoie l'élément à l'adresse 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 situé à l'adresse index. L'index se trouve parmi tous les éléments du menu.

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