ComboBox QML Type

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

Import Statement: import QtQuick.Controls
Inherits:

Control

Propriétés

Signaux

Méthodes

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

Remarque : Si un modèle de données comportant plusieurs rôles nommés est attribué à ComboBox, mais que textRole n'est pas défini, ComboBox ne peut pas le visualiser et envoie un message d'erreur ReferenceError: modelData is not defined.

Voir également la personnalisation de ComboBox, des contrôles d'entrée et de la gestion du focus à l'adresse Qt Quick Controls.

Propriété Documentation

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 courant de 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 actuel de la liste déroulante.

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. La définition de cette propriété permet de définir currentIndex comme étant 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 non dé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()
    }
}

Voir également ItemDelegate et la personnalisation de ComboBox.


delegateModel : model [read-only]

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

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

Voir également Personnalisation de ComboBox.


displayText : string

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

Par défaut, le texte affiché présente la sélection en cours. 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 liste déroulante est visuellement abaissé.

Sauf si elle est explicitement définie, cette propriété prend la valeur true lorsque pressed ou popup.visible prend la valeur 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 é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 éditable.

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 tant qu'il n'y a pas d'interaction avec lui. 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)]

implicitContentWidth Cette propriété contrôle le mode de calcul de la largeur de la page ComboBox.

Lorsque la largeur d'un site ComboBox n'est pas suffisante pour afficher du texte, celui-ci est élidé. 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

ConstanteDescription
ContentItemImplicitWidthLa largeur implicite du contenu sera par défaut celle de contentItem. Il s'agit de l'option la plus efficace, car aucune mise en page supplémentaire du texte n'est effectuée.
WidestTextLa largeur implicite du contenu sera fixée à la largeur implicite du texte le plus grand pour le site textRole donné chaque fois que le modèle changera. Cette option doit être utilisée avec des modèles plus petits, car elle peut s'avérer coûteuse.
WidestTextWhenCompletedLa largeur implicite du contenu (implicitContentWidth) sera fixée à la largeur implicite du texte le plus grand pour l'adresse textRole une fois après component completion. Cette option devrait être utilisée avec des modèles plus petits, car elle peut être coûteuse.

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.

Remarque : cette fonctionnalité exige que le contentItem soit un type dérivé de TextInput.

Note : Cette fonctionnalité nécessite la mise en page du texte et peut donc s'avérer coûteuse pour les modèles de grande taille ou les modèles dont le contenu est fréquemment mis à jour.

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é contient la largeur implicite de l'indicateur.

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

Elle est généralement utilisée, avec implicitContentWidth et implicitBackgroundWidth, pour calculer l'indicateur 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 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 liste déroulante éditable a une entrée de texte partielle provenant d'une méthode d'entrée.

Pendant qu'elle compose, une méthode de saisie peut s'appuyer sur les événements souris ou touche de la liste déroulante pour modifier 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 liste déroulante 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 convenant 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 boîte combo.

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.


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 aussi Personnalisation de ComboBox.


pressed : bool [read-only]

Cette propriété indique si le bouton de la liste déroulante est physiquement enfoncé. Un bouton peut être pressé 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'un site 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 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 d'entrée 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 aussi 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 "".

Remarque : si la liste déroulante est dotée d'une adresse validator, le signal ne sera émis que si l'entrée est dans un état acceptable.

Note : Le gestionnaire correspondant est onAccepted.

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 à 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 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 remplacée par index.

Remarque : le gestionnaire correspondant est onActivated.

Voir également currentIndex.


void highlighted(int index)

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

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

Remarque : le gestionnaire correspondant est onHighlighted.

Voir également highlightedIndex.


Documentation de la méthode

void decrementCurrentIndex()

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

Voir également currentIndex et highlightedIndex.


int find(string text, enumeration flags)

Renvoie l'index de l'élément spécifié text, 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é.

ConstanteDescription
Qt.MatchExactlyLe terme de recherche correspond exactement (par défaut).
Qt.MatchRegularExpressionLe terme de recherche correspond à une expression régulière.
Qt.MatchWildcardLe terme de recherche correspond à l'aide de caractères génériques.
Qt.MatchFixedStringLe terme de recherche correspond à une chaîne fixe.
Qt.MatchStartsWithLe terme de recherche correspond au début de l'élément.
Qt.MatchEndsWithLe terme de recherche correspond à la fin de l'élément.
Qt.MatchContainsLe terme de recherche est contenu dans l'élément.
Qt.MatchCaseSensitiveLa recherche est sensible à la casse.

Remarque : cette fonction ne peut être utilisée qu'après l'émission de Component.completed() pour ComboBox.

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'indice actuel de la liste déroulante ou l'indice en surbrillance si la liste déroulante est visible.

Voir aussi 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.

Remarque : cette fonction ne peut être utilisée qu'après l'émission de Component.completed() pour ComboBox.

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 correspondant à l'adresse index, ou une chaîne vide si l'index est hors limites.

Remarque : cette fonction ne peut être utilisée qu'après l'émission de Component.completed() pour le ComboBox.

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.


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.