ComboBox QML Type

Bouton et liste déroulante combinés pour la sélection d'options. Plus d'informations...

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

Propriétés

• acceptableInput : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• count : int
• currentIndex : int
• currentText : string
• currentValue : var (since QtQuick.Controls 2.14 (Qt 5.14))
• delegate : Component
• delegateModel : model
• displayText : string
• down : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• editText : string (since QtQuick.Controls 2.2 (Qt 5.9))
• editable : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• flat : bool (since QtQuick.Controls 2.1 (Qt 5.8))
• highlightedIndex : int
• implicitContentWidthPolicy : enumeration (since QtQuick.Controls 6.0 (Qt 6.0))
• implicitIndicatorHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitIndicatorWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• indicator : Item
• inputMethodComposing : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• inputMethodHints : flags (since QtQuick.Controls 2.2 (Qt 5.9))
• model : model
• popup : Popup
• pressed : bool
• selectTextByMouse : bool (since QtQuick.Controls 2.15 (Qt 5.15))
• textRole : string
• validator : Validator (since QtQuick.Controls 2.2 (Qt 5.9))
• valueRole : string (since QtQuick.Controls 2.14 (Qt 5.14))

Signaux

• void accepted() (since QtQuick.Controls 2.2 (Qt 5.9))
• void activated(int index)
• void highlighted(int index)

Méthodes

• void decrementCurrentIndex()
• int find(string text, enumeration flags)
• void incrementCurrentIndex()
• int indexOfValue(object value) (since QtQuick.Controls 2.14 (Qt 5.14))
• void selectAll() (since QtQuick.Controls 2.2 (Qt 5.9))
• string textAt(int index)
• var valueAt(int index) (since QtQuick.Controls 2.14 (Qt 5.14))

Description détaillée

ComboBox est une combinaison de bouton et de liste déroulante. Elle permet de présenter une liste d'options à l'utilisateur en occupant le moins d'espace possible à l'écran.

ComboBox est alimenté par un modèle de données. Le modèle de données est généralement un tableau JavaScript, un ListModel ou un entier, mais d'autres types de modèles de données sont également pris en charge.

ComboBox {
    model: ["First", "Second", "Third"]
}

ComboBox modifiable

Les combo-boxes peuvent être rendues editable. Une liste déroulante modifiable complète automatiquement son texte en fonction de ce qui est disponible dans le modèle.

L'exemple suivant montre comment ajouter du contenu à une liste déroulante modifiable en réagissant au signal accepted.

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

La fenêtre contextuelle de ComboBox

Par défaut, un clic à l'extérieur de la fenêtre contextuelle de ComboBox la ferme, et l'événement est propagé aux éléments situés plus bas dans l'ordre d'empilement. Pour empêcher la fermeture de la fenêtre contextuelle, définissez son adresse closePolicy:

    popup.closePolicy: Popup.CloseOnEscape

Pour empêcher la propagation de l'événement, définissez sa propriété modal sur true:

    popup.modal: true

Rôles du modèle ComboBox

ComboBox est capable de visualiser les modèles de données standard qui fournissent le rôle modelData:

• les modèles qui n'ont qu'un seul rôle
• les modèles qui n'ont pas de rôle nommé (tableau JavaScript, entier)

Lors de l'utilisation de modèles ayant plusieurs rôles nommés, ComboBox doit être configuré pour utiliser une text role spécifique pour ses instances display text et delegate. Si vous souhaitez utiliser un rôle de l'élément de modèle qui correspond au rôle texte, définissez valueRole. La propriété currentValue et la méthode indexOfValue() peuvent alors être utilisées pour obtenir des informations sur ces valeurs.

Par exemple, vous pouvez utiliser la propriété et la méthode () pour obtenir des informations sur ces valeurs :

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    // Used as an example of a backend - this would usually be
    // e.g. a C++ type exposed to QML.
    QtObject {
        id: backend
        property int modifier
    }

    ComboBox {
        model: [
            { value: Qt.NoModifier, text: qsTr("No modifier") },
            { value: Qt.ShiftModifier, text: qsTr("Shift") },
            { value: Qt.ControlModifier, text: qsTr("Control") }
        ]
        textRole: "text"
        valueRole: "value"
        // Set currentValue to the value stored in the backend.
        currentValue: backend.modifier
        // When an item is selected, update the backend.
        onActivated: backend.modifier = currentValue
    }
}

Voir également Personnalisation de ComboBox, Contrôles d'entrée et Gestion du focus dans les contrôles Qt Quick .

Documentation sur les propriétés

acceptableInput : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

Cette propriété indique si la liste déroulante contient un texte acceptable dans le champ de texte modifiable.

Si un validateur a été défini, la valeur est true uniquement si le texte actuel est acceptable pour le validateur en tant que chaîne finale (et non en tant que chaîne intermédiaire).

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

Voir aussi validator et accepted.

count : int [read-only]

Cette propriété indique le nombre d'éléments de la liste déroulante.

currentIndex : int

Cette propriété contient l'index de l'élément actuel de la boîte combo.

La valeur par défaut est -1 lorsque count est 0, et 0 dans le cas contraire.

Voir aussi activated(), currentText, et highlightedIndex.

currentText : string [read-only]

Cette propriété contient le texte de l'élément actuel de la boîte combo.

Voir aussi currentIndex, displayText, textRole, et editText.

currentValue : var [since QtQuick.Controls 2.14 (Qt 5.14)]

Cette propriété contient la valeur de l'élément actuel de la liste déroulante. En définissant cette propriété, currentIndex correspondra à l'élément ayant la valeur correspondante ou -1 s'il n'est pas trouvé. Le fait de définir currentIndex et currentValue de manière déclarative entraînera un comportement indéfini. La définition de cette propriété avec une valeur qui n'est pas unique n'est pas prise en charge.

Pour un exemple d'utilisation de cette propriété, voir ComboBox Model Roles.

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

Voir également currentIndex, currentText, et valueRole.

delegate : Component

Cette propriété contient un délégué qui présente un élément dans la fenêtre contextuelle de la boîte combo.

Il est recommandé d'utiliser ItemDelegate (ou tout autre dérivé de AbstractButton ) comme délégué. Cela garantit que l'interaction fonctionne comme prévu et que la fenêtre contextuelle se ferme automatiquement le cas échéant. Lorsque d'autres types sont utilisés comme délégués, la fenêtre contextuelle doit être fermée manuellement. Par exemple, si MouseArea est utilisé :

delegate: Rectangle {
    // ...
    MouseArea {
        // ...
        onClicked: comboBox.popup.close()
    }
}

Depuis Qt 6.11, ComboBox ne prend pas la propriété du délégué.

Voir également ItemDelegate et Customizing ComboBox.

delegateModel : model [read-only]

Cette propriété contient le modèle qui fournit des instances de délégués pour la boîte combo.

Elle est généralement attribuée à une ListView dans la contentItem de la popup.

Voir aussi Personnalisation de ComboBox.

displayText : string

Cette propriété contient le texte qui est affiché sur le bouton de la boîte combo.

Par défaut, le texte affiché présente la sélection courante. En d'autres termes, il suit le texte de l'élément courant. Toutefois, il est possible de remplacer le texte affiché par défaut par une valeur personnalisée.

ComboBox {
    currentIndex: 1
    displayText: "Size: " + currentText
    model: ["S", "M", "L"]
}

Voir également currentText et textRole.

down : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

Cette propriété indique si le bouton de la boîte combo est visuellement abaissé.

Sauf si elle est explicitement définie, cette propriété vaut true lorsque pressed ou popup.visible vaut true. Pour revenir à la valeur par défaut, réglez cette propriété sur undefined.

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

Voir également pressed et popup.

editText : string [since QtQuick.Controls 2.2 (Qt 5.9)]

Cette propriété contient le texte du champ de texte d'une boîte combo modifiable.

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

Voir aussi editable, currentText, et displayText.

editable : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

Cette propriété indique si la liste déroulante est modifiable.

La valeur par défaut est false.

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

Voir également validator.

flat : bool [since QtQuick.Controls 2.1 (Qt 5.8)]

Cette propriété indique si le bouton de la liste déroulante est plat.

Un bouton de liste déroulante plat ne dessine pas d'arrière-plan sauf en cas d'interaction. Par rapport aux combo-boxes normales, les combo-boxes plates ont un aspect qui les fait moins ressortir du reste de l'interface utilisateur. Par exemple, lorsqu'on place une liste déroulante dans une barre d'outils, il peut être souhaitable de rendre la liste déroulante plate afin qu'elle s'harmonise mieux avec l'aspect plat des boutons d'outils.

La valeur par défaut est false.

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

highlightedIndex : int [read-only]

Cette propriété contient l'index de l'élément en surbrillance dans la liste déroulante de la boîte combo.

Lorsqu'un élément en surbrillance est activé, la fenêtre contextuelle est fermée, currentIndex prend la valeur highlightedIndex et la valeur de cette propriété est réinitialisée à -1, car il n'y a plus d'élément en surbrillance.

Voir également highlighted() et currentIndex.

implicitContentWidthPolicy : enumeration [since QtQuick.Controls 6.0 (Qt 6.0)]

Cette propriété contrôle la manière dont est calculé le implicitContentWidth du ComboBox.

Lorsque la largeur d'un site ComboBox n'est pas suffisante pour afficher du texte, celui-ci est masqué. Selon les parties du texte qui sont masquées, cela peut rendre la sélection d'un élément difficile pour l'utilisateur final. Un moyen efficace de s'assurer que la largeur d'un site ComboBox est suffisante pour éviter que le texte ne soit masqué consiste à définir une largeur que l'on sait suffisante :

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

Cependant, il est souvent impossible de savoir si une valeur codée en dur sera suffisante ou non, car la taille du texte dépend de nombreux facteurs, tels que la famille de polices, la taille des polices, les traductions, etc.

ComboBox implicitContentWidthPolicy permet de contrôler facilement la manière dont la largeur implicite du contenu est calculée, ce qui affecte le site implicitWidth et garantit que le texte ne sera pas élidé.

Les valeurs disponibles sont les suivantes

La valeur par défaut est ContentItemImplicitWidth.

Étant donné que cette propriété n'affecte que le implicitWidth du ComboBox, la définition d'un width explicite peut toujours entraîner un élidage.

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

implicitIndicatorHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété contient la hauteur de l'indicateur implicite.

La valeur est égale à indicator ? indicator.implicitHeight : 0.

Elle est généralement utilisée, avec implicitContentHeight et implicitBackgroundHeight, pour calculer implicitHeight.

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

Voir aussi implicitIndicatorWidth.

implicitIndicatorWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété définit la largeur de l'indicateur implicite.

La valeur est égale à indicator ? indicator.implicitWidth : 0.

Elle est généralement utilisée, avec implicitContentWidth et implicitBackgroundWidth, pour calculer implicitWidth.

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

Voir aussi implicitIndicatorHeight.

indicator : Item

Cette propriété contient l'élément de l'indicateur de chute.

Voir aussi Personnalisation de ComboBox.

inputMethodComposing : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

Cette propriété indique si une zone combo modifiable a été partiellement saisie par une méthode de saisie.

Pendant qu'elle compose, une méthode de saisie peut s'appuyer sur des événements souris ou touche de la liste déroulante pour éditer ou valider le texte partiel. Cette propriété peut être utilisée pour déterminer quand désactiver les gestionnaires d'événements susceptibles d'interférer avec le fonctionnement correct d'une méthode de saisie.

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

inputMethodHints : flags [since QtQuick.Controls 2.2 (Qt 5.9)]

Fournit des indications à la méthode de saisie sur le contenu attendu de la boîte combo et sur la manière dont elle doit fonctionner.

La valeur par défaut est Qt.ImhNoPredictiveText.

La valeur est une combinaison bit à bit de drapeaux ou Qt.ImhNone si aucun indice n'est défini.

Les drapeaux qui modifient le comportement sont :

• Qt.ImhHiddenText - Les caractères doivent être cachés, comme c'est généralement le cas lors de la saisie de mots de passe.
• Qt.ImhSensitiveData - Le texte saisi ne doit pas être stocké par la méthode de saisie active dans une mémoire persistante telle que le dictionnaire prédictif de l'utilisateur.
• Qt.ImhNoAutoUppercase - La méthode de saisie ne doit pas essayer de passer automatiquement en majuscules à la fin d'une phrase.
• Qt.ImhPreferNumbers - Les chiffres sont préférés (mais pas obligatoires).
• Qt.ImhPreferUppercase - Les lettres majuscules sont préférées (mais pas obligatoires).
• Qt.ImhPreferLowercase - Les lettres minuscules sont préférées (mais pas obligatoires).
• Qt.ImhNoPredictiveText - N'utilise pas le texte prédictif (c'est-à-dire la recherche dans le dictionnaire) pendant la saisie.
• Qt.ImhDate - L'éditeur de texte fonctionne comme un champ de date.
• Qt.ImhTime - L'éditeur de texte fonctionne comme un champ de temps.

Les drapeaux qui limitent la saisie (drapeaux exclusifs) sont :

• Qt.ImhDigitsOnly - Seuls les chiffres sont autorisés.
• Qt.ImhFormattedNumbersOnly - Seule la saisie de nombres est autorisée. Cela inclut le point décimal et le signe moins.
• Qt.ImhUppercaseOnly - Seule la saisie des lettres majuscules est autorisée.
• Qt.ImhLowercaseOnly - Seule la saisie des lettres minuscules est autorisée.
• Qt.ImhDialableCharactersOnly - Seuls les caractères permettant de composer un numéro de téléphone sont autorisés.
• Qt.ImhEmailCharactersOnly - Seuls les caractères adaptés aux adresses électroniques sont autorisés.
• Qt.ImhUrlCharactersOnly - Seuls les caractères adaptés aux URL sont autorisés.

Masques :

• Qt.ImhExclusiveInputMask - Ce masque produit un résultat non nul si l'un des drapeaux exclusifs est utilisé.

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

model : model

Cette propriété contient le modèle qui fournit les données de la liste déroulante.

ComboBox {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}

Voir également textRole et Modèles de données.

popup : Popup

Cette propriété contient la fenêtre contextuelle.

La fenêtre contextuelle peut être ouverte ou fermée manuellement, si nécessaire :

onSpecialEvent: comboBox.popup.close()

Voir également la personnalisation de ComboBox.

pressed : bool [read-only]

Cette propriété indique si le bouton de la boîte combo est physiquement enfoncé. Un bouton peut être enfoncé par des événements tactiles ou par des touches.

Voir également down.

selectTextByMouse : bool [since QtQuick.Controls 2.15 (Qt 5.15)]

Cette propriété indique si le champ de texte d'une page ComboBox modifiable peut être sélectionné avec la souris.

La valeur par défaut est false.

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

textRole : string

Cette propriété contient le rôle du modèle utilisé pour remplir la liste déroulante.

Lorsque le modèle a plusieurs rôles, textRole peut être défini pour déterminer quel rôle doit être affiché.

Voir également model, currentText, displayText, et ComboBox Model Roles.

validator : Validator [since QtQuick.Controls 2.2 (Qt 5.9)]

Cette propriété contient un validateur de texte pour une liste déroulante modifiable.

Lorsqu'un validateur est défini, le champ de texte n'accepte que les entrées qui laissent la propriété text dans un état intermédiaire. Le signal accepted ne sera émis que si le texte est dans un état acceptable lorsque la touche Return ou Enter est enfoncée.

Les validateurs actuellement pris en charge sont IntValidator, DoubleValidator et RegularExpressionValidator. Un exemple d'utilisation des validateurs est présenté ci-dessous, qui autorise la saisie d'entiers entre 0 et 10 dans le champ de texte :

ComboBox {
    model: 10
    editable: true
    validator: IntValidator {
        top: 9
        bottom: 0
    }
}

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

Voir également acceptableInput, accepted, et editable.

valueRole : string [since QtQuick.Controls 2.14 (Qt 5.14)]

Cette propriété contient le rôle du modèle utilisé pour stocker la valeur associée à chaque élément du modèle.

Pour un exemple d'utilisation de cette propriété, voir ComboBox Model Roles.

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

Voir également model et currentValue.

Documentation sur les signaux

[since QtQuick.Controls 2.2 (Qt 5.9)] void accepted()

Ce signal est émis lorsque la touche Return ou Enter est enfoncée dans une boîte combo editable.

Vous pouvez gérer ce signal afin d'ajouter l'élément nouvellement saisi au modèle, par exemple :

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

Avant que le signal ne soit émis, une vérification est effectuée pour voir si la chaîne existe dans le modèle. Si c'est le cas, currentIndex sera mis à son index, et currentText à la chaîne elle-même.

Après l'émission du signal, et si la première vérification a échoué (c'est-à-dire que l'élément n'existait pas), une autre vérification est effectuée pour voir si l'élément a été ajouté par le gestionnaire de signal. Si c'est le cas, les adresses currentIndex et currentText sont mises à jour en conséquence. Dans le cas contraire, ils seront respectivement définis comme -1 et "".

Ce signal a été introduit dans QtQuick.Controls 2.2 (Qt 5.9).

void activated(int index)

Ce signal est émis lorsque l'élément situé à l'adresse index est activé par l'utilisateur.

Un élément est activé lorsqu'il est sélectionné alors que la fenêtre contextuelle est ouverte, ce qui entraîne la fermeture de la fenêtre (et la modification de currentIndex ), ou alors que la fenêtre contextuelle est fermée et que l'on navigue dans la liste déroulante à l'aide du clavier, ce qui entraîne la modification de currentIndex. La propriété currentIndex est remplacée par index.

Voir également currentIndex.

void highlighted(int index)

Ce signal est émis lorsque l'élément situé à index dans la liste popup est mis en évidence par l'utilisateur.

Ce signal n'est émis que lorsque la fenêtre contextuelle est ouverte et qu'un élément est mis en évidence, mais pas nécessairement activated.

Voir également highlightedIndex.

Documentation de la méthode

void decrementCurrentIndex()

Diminue l'index actuel de la boîte combo, ou l'index en surbrillance si la liste déroulante est visible.

Voir également currentIndex et highlightedIndex.

int find(string text, enumeration flags)

Renvoie l'index de l'adresse text spécifiée, ou -1 si aucune correspondance n'est trouvée.

La manière dont la recherche est effectuée est définie par la correspondance spécifiée flags. Par défaut, la boîte combo effectue une correspondance exacte sensible à la casse (Qt.MatchExactly). Tous les autres types de correspondance sont insensibles à la casse, sauf si le drapeau Qt.MatchCaseSensitive est également spécifié.

Par exemple :

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    Component.onCompleted: currentIndex = find("Coconut")
}

Voir aussi textRole.

void incrementCurrentIndex()

Augmente l'index actuel de la liste déroulante, ou l'index en surbrillance si la liste déroulante est visible.

Voir également currentIndex et highlightedIndex.

[since QtQuick.Controls 2.14 (Qt 5.14)] int indexOfValue(object value)

Renvoie l'index de l'adresse value spécifiée, ou -1 si aucune correspondance n'est trouvée.

Pour un exemple d'utilisation de cette méthode, voir ComboBox Model Roles.

Cette méthode a été introduite dans QtQuick.Controls 2.14 (Qt 5.14).

Voir aussi find(), currentValue, currentIndex, valueRole, et valueAt.

[since QtQuick.Controls 2.2 (Qt 5.9)] void selectAll()

Sélectionne tout le texte dans le champ de texte éditable de la boîte combo.

Cette méthode a été introduite dans QtQuick.Controls 2.2 (Qt 5.9).

Voir aussi editText.

string textAt(int index)

Renvoie le texte de l'adresse index spécifiée, ou une chaîne vide si l'index est hors limites.

Par exemple :

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onActivated: (index) => { print(textAt(index)) }
}

Voir aussi textRole.

[since QtQuick.Controls 2.14 (Qt 5.14)] var valueAt(int index)

Renvoie la valeur à la position index dans la liste déroulante.

Cette méthode a été introduite dans QtQuick.Controls 2.14 (Qt 5.14).

Voir aussi indexOfValue.