ComboBox QML Type

Bouton et liste déroulante combinés pour la sélection d'options. En savoir plus...

• 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))
• highlightOnHover : bool (since QtQuick.Controls 6.12 (Qt 6.12))
• 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 un élément combinant un bouton et une liste déroulante. Il permet de présenter une liste d'options à l'utilisateur en occupant un minimum d'espace à l'écran.

La ComboBox est renseignée à partir d'un modèle de données. Ce dernier est généralement un tableau JavaScript, une chaîne de caractères ( 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

La ComboBox peut être rendue « editable ». Une ComboBox modifiable propose une saisie semi-automatique en fonction des éléments disponibles 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})
    }
}

Fenêtre contextuelle de la ComboBox

Par défaut, un clic en dehors de la fenêtre contextuelle de la 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 sa propriété ` 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

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

• les modèles qui ne possèdent qu'un seul rôle
• les modèles qui ne possèdent pas de rôles nommés (tableau JavaScript, entier)

Lorsque vous utilisez des modèles comportant plusieurs rôles nommés, ComboBox doit être configuré pour utiliser un « text role » spécifique pour ses instances « display text » et « delegate ». Si vous souhaitez utiliser un rôle de l’élément du modèle correspondant au rôle « text », 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 :

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, des contrôles de saisie et de la gestion du focus dans Qt Quick Controls.

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 également « validator » et « accepted ».

count : int [read-only]

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

currentIndex : int

Cette propriété contient l'index de l'élément actuel dans la liste déroulante.

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

Voir également activated(), currentText et highlightedIndex.

currentText : string [read-only]

Cette propriété contient le texte de l'élément actuellement sélectionné dans la liste déroulante.

Voir également 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. La définition de cette propriété attribuera à ` currentIndex ` la valeur de l'élément correspondant ou ` -1 ` si celui-ci est introuvable. La définition simultanée de ` currentIndex ` et ` currentValue ` de manière déclarative entraînera un comportement indéfini. La définition de cette propriété avec une valeur non 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 affiche un élément dans la fenêtre contextuelle de la liste déroulante.

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 fermera automatiquement le moment venu. Lorsque d’autres types sont utilisés comme délégué, 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 plus possession du délégué.

Voir également ItemDelegate et Personnalisation de la liste déroulante.

delegateModel : model [read-only]

Cette propriété contient le modèle qui fournit les instances de délégué pour la liste déroulante.

Elle est généralement attribuée à un ` ListView ` dans l'contentItem ` de l'popup.

Voir également Personnalisation dela liste déroulante.

displayText : string

Cette propriété contient le texte affiché sur le bouton de la liste déroulante.

Par défaut, le texte d'affichage correspond à la sélection actuelle. Autrement dit, il reprend le texte de l'élément actuellement sélectionné. Il est toutefois possible de remplacer le texte d'affichage 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 liste déroulante est visuellement en position « enfoncée ».

À moins d'être explicitement définie, cette propriété prend la valeur « true » lorsque l'une des propriétés suivantes est définie sur « true » : « pressed » ou « popup.visible ». Pour revenir à la valeur par défaut, définissez 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 affiché dans le champ de texte d'une liste déroulante modifiable.

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

Voir également 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é s'applique que le bouton de la liste déroulante soit plat ou non.

Un bouton de liste déroulante « plat » n'affiche pas d'arrière-plan tant qu'il n'est pas activé. Par rapport aux listes déroulantes classiques, les listes déroulantes « plates » offrent un aspect qui leur permet de se fondre davantage dans le reste de l'interface utilisateur. Par exemple, lorsque l'on place une liste déroulante dans une barre d'outils, il peut être souhaitable de la rendre plate afin qu'elle s'harmonise mieux avec l'aspect plat des boutons de la barre d'outils.

La valeur par défaut est « false ».

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

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

Cette propriété détermine si le survol d'éléments doit les mettre en surbrillance.

La valeur par défaut est « true ».

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

highlightedIndex : int [read-only]

Cette propriété contient l'index de l'élément sélectionné dans la liste contextuelle de la liste déroulante.

Lorsqu'un élément sélectionné est activé, la liste déroulante se ferme, la propriété ` 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 sélectionné.

Voir également highlighted() et currentIndex.

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

Cette propriété détermine la manière dont l'implicitContentWidth e de l'ComboBox est calculée.

Lorsque la largeur d’une « ComboBox » n’est pas suffisante pour afficher le texte, celui-ci est tronqué. Selon les parties du texte qui sont tronquées, cela peut compliquer la sélection d’un élément pour l’utilisateur final. Un moyen efficace de s’assurer qu’une « ComboBox » est suffisamment large pour éviter que le texte ne soit tronqué consiste à définir une largeur dont on sait qu’elle est suffisante :

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

Cependant, il n’est souvent pas possible de savoir si une valeur codée en dur sera suffisante, car la taille du texte dépend de nombreux facteurs, tels que la famille de polices, la taille des caractères, les traductions, etc.

implicitContentWidthPolicy offre un moyen simple de contrôler le calcul de la largeur implicite (implicitContentWidth), ce qui influe sur l’ implicitWidth de l’ ComboBox et garantit que le texte ne sera pas tronqué.

Les valeurs disponibles sont les suivantes :

La valeur par défaut est « ContentItemImplicitWidth ».

Comme cette propriété n'affecte que l'implicitWidth de l'ComboBox, la définition d'un width explicite peut tout de même entraîner une élision.

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 implicite de l'indicateur.

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

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

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

Voir également implicitIndicatorWidth.

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

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

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

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

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

Voir également implicitIndicatorHeight.

indicator : Item

Cette propriété contient l'élément indicateur de menu déroulant.

Voir également Personnalisation dela liste déroulante.

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

Cette propriété indique si une liste déroulante modifiable contient une saisie de texte partielle provenant d'une méthode de saisie.

Pendant la composition, une méthode de saisie peut s'appuyer sur les événements de souris ou de clavier provenant de la liste déroulante pour modifier ou valider le texte partiel. Cette propriété permet de déterminer quand désactiver les gestionnaires d'événements susceptibles d'interférer avec le bon fonctionnement 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 concernant le contenu attendu de la liste déroulante et son mode de fonctionnement.

La valeur par défaut est « Qt.ImhNoPredictiveText ».

La valeur est une combinaison binaire d’indicateurs ou « Qt.ImhNone » si aucun indice n’est défini.

Les indicateurs qui modifient le comportement sont les suivants :

• Qt.ImhHiddenText - Les caractères doivent être masqué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 enregistré par la méthode de saisie active dans un stockage persistant, tel qu’un dictionnaire prédictif utilisateur.
• Qt.ImhNoAutoUppercase - La méthode de saisie ne doit pas tenter 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 majuscules sont préférées (mais pas obligatoires).
• Qt.ImhPreferLowercase - Les lettres minuscules sont préférées (mais pas obligatoires).
• Qt.ImhNoPredictiveText - Ne pas utiliser la saisie prédictive (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 d'heure.

Les indicateurs qui restreignent la saisie (indicateurs exclusifs) sont les suivants :

• Qt.ImhDigitsOnly - Seuls les chiffres sont autorisés.
• Qt.ImhFormattedNumbersOnly - Seule la saisie de nombres est autorisée. Cela inclut la virgule décimale et le signe moins.
• Qt.ImhUppercaseOnly - Seules les lettres majuscules sont autorisées.
• Qt.ImhLowercaseOnly - Seule la saisie de lettres minuscules est autorisée.
• Qt.ImhDialableCharactersOnly : seuls les caractères pouvant être utilisés pour composer un numéro de téléphone sont autorisés.
• Qt.ImhEmailCharactersOnly - Seuls les caractères valides pour les adresses e-mail sont autorisés.
• Qt.ImhUrlCharactersOnly - Seuls les caractères adaptés aux URL sont autorisés.

Masques :

• Qt.ImhExclusiveInputMask - Ce masque renvoie une valeur non nulle si l'un des indicateurs d'exclusion 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 fournissant les données à 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 Personnalisation dela liste déroulante.

pressed : bool [read-only]

Cette propriété indique si le bouton de la liste déroulante est physiquement enfoncé. Un bouton peut être enfoncé soit par un événement tactile, soit par un événement de touche.

Voir également down.

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

Cette propriété indique si le champ de texte d'une « ComboBox » modifiable peut être sélectionné à l'aide de 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 comporte plusieurs rôles, la propriété « textRole » peut être définie 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é définit un validateur de texte pour une liste déroulante modifiable.

Lorsqu’un validateur est défini, le champ de texte n’accepte que les saisies qui laissent la propriété « text » dans un état intermédiaire. Le signal « accepted » n’est émis que si le texte se trouve dans un état acceptable lorsque la touche « Return » ou « Enter » est enfoncée.

Les validateurs actuellement pris en charge sont IntValidator, DoubleValidator et RegularExpressionValidator. Vous trouverez ci-dessous un exemple d’utilisation des validateurs, qui permet la saisie d’entiers compris 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é, consultez 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 liste déroulante « 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 l’émission du signal, une vérification est effectuée pour voir si la chaîne existe dans le modèle. Si c’est le cas, currentIndex sera défini sur son index, et currentText sur la chaîne elle-même.

Une fois le signal émis, 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 propriétés currentIndex et currentText sont mises à jour en conséquence. Sinon, elles sont respectivement définies sur -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 celle-ci (et la modification de currentIndex ), ou lorsque 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 définie sur index.

Voir également currentIndex.

void highlighted(int index)

Ce signal est émis lorsque l'élément situé à l'adresse index dans la liste contextuelle est sélectionné par l'utilisateur.

Le signal « highlighted » n'est émis que lorsque la liste déroulante est ouverte et qu'un élément est sélectionné, mais pas nécessairement activated.

Voir également highlightedIndex.

Documentation de la méthode

void decrementCurrentIndex()

Diminue l'index actuel de la liste déroulante, ou l'index sélectionné si la liste contextuelle est visible.

Voir également currentIndex et highlightedIndex.

int find(string text, enumeration flags)

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

Le mode de recherche est défini par l’ flags de correspondance spécifiée. Par défaut, la liste déroulante effectue une correspondance exacte sensible à la casse (Qt.MatchExactly). Tous les autres types de correspondance ne tiennent pas compte de la casse, sauf si l’indicateur « 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 également textRole.

void incrementCurrentIndex()

Incrémente l'index actuel de la liste déroulante, ou l'index sélectionné si la liste contextuelle est visible.

Voir également currentIndex et highlightedIndex.

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

Renvoie l'index de l'value spécifié, 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 également find(), currentValue, currentIndex, valueRole et valueAt.

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

Sélectionne tout le texte contenu dans le champ de texte modifiable de la liste déroulante.

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

Voir aussi editText.

string textAt(int index)

Renvoie le texte correspondant à l'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 située à 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.