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: |
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 } }
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 |
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).
count : int |
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 |
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 |
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 |
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 |
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).
editText : string |
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 |
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 |
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 |
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 |
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
| Constante | Description |
|---|---|
ContentItemImplicitWidth | La 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. |
WidestText | La 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. |
WidestTextWhenCompleted | La 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 |
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 |
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 |
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 |
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.
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 aussi Personnalisation de ComboBox.
pressed : bool |
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 |
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 |
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 |
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
|
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.
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é.
| Constante | Description |
|---|---|
Qt.MatchExactly | Le terme de recherche correspond exactement (par défaut). |
Qt.MatchRegularExpression | Le terme de recherche correspond à une expression régulière. |
Qt.MatchWildcard | Le terme de recherche correspond à l'aide de caractères génériques. |
Qt.MatchFixedString | Le terme de recherche correspond à une chaîne fixe. |
Qt.MatchStartsWith | Le terme de recherche correspond au début de l'élément. |
Qt.MatchEndsWith | Le terme de recherche correspond à la fin de l'élément. |
Qt.MatchContains | Le terme de recherche est contenu dans l'élément. |
Qt.MatchCaseSensitive | La 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.
|
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.
|
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.
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.
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.