SearchField QML Type

Champ de saisie spécialisé destiné à la fonctionnalité de recherche. En savoir plus...

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

Propriétés

• clearIndicator
  • clearIndicator.hovered : bool
  • clearIndicator.implicitIndicatorHeight : real
  • clearIndicator.implicitIndicatorWidth : real
  • clearIndicator.indicator : Item
  • clearIndicator.pressed : bool
• currentIndex : int
• cursorPosition : int (since 6.12)
• delegate : Component
• delegateModel : model
• highlightedIndex : int
• live : bool
• placeholderText : string (since 6.12)
• popup : Popup
• searchIndicator
  • searchIndicator.hovered : bool
  • searchIndicator.implicitIndicatorHeight : real
  • searchIndicator.implicitIndicatorWidth : real
  • searchIndicator.indicator : Item
  • searchIndicator.pressed : bool
• selectTextByMouse : bool (since 6.12)
• selectedText : string (since 6.12)
• selectionEnd : int (since 6.12)
• selectionStart : int (since 6.12)
• suggestionCount : int
• suggestionModel : model
• text : string
• textRole : string

Signaux

• void accepted()
• void activated(int index)
• void clearButtonPressed()
• void highlighted(int index)
• void searchButtonPressed()
• void searchTriggered()
• void textEdited()

Méthodes

• void deselect() (since 6.12)
• void select(int start, int end) (since 6.12)
• void selectAll() (since 6.12)
• void selectWord() (since 6.12)

Description détaillée

SearchField est un champ de saisie spécialisé conçu pour les fonctionnalités de recherche. Ce contrôle comprend un champ de texte, des icônes de recherche et d'effacement, ainsi qu'une fenêtre contextuelle affichant des suggestions ou des résultats de recherche.

Indicateurs de SearchField

SearchField propose deux boutons indicateurs intégrés en option : « searchIndicator » et « clearIndicator ».

Il ne s’agit pas d’indicateurs au sens de BusyIndicator ou ProgressBar. Il s’agit plutôt de commandes interactives intégrées au champ (à l’instar des boutons haut/bas dans SpinBox). Appuyer sur searchIndicator déclenche searchButtonPressed, et appuyer sur clearIndicator déclenche clearButtonPressed.

Outre l’accès aux actions, les boutons d’indicateur fournissent des états d’interaction (enfoncé/survolé/sélectionné, etc.) pouvant être utilisés par les styles.

Personnalisation du contenu des indicateurs

Les propriétés searchIndicator et clearIndicator sont en lecture seule. La personnalisation s’effectue via leurs propriétés internes.

En particulier, le contenu visuel du bouton est fourni par son élément indicator, qui est modifiable. Cela permet de remplacer ou de supprimer entièrement le contenu par défaut.

Par exemple, pour supprimer les deux icônes d’indicateur :

SearchField {
    searchIndicator.indicator: null
    clearIndicator.indicator: null
}

Il s’agit d’un scénario de personnalisation pris en charge. Différentes variantes de SearchField peuvent omettre l’un des boutons (par exemple, en ne proposant qu’un bouton de recherche) ou remplacer le contenu de l’indicateur par un autre élément (par exemple, une icône de microphone pour déclencher la saisie vocale).

Rôles du modèle SearchField

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

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

Lors de l’utilisation de modèles comportant plusieurs rôles nommés, SearchField doit être configuré pour utiliser un « text role » spécifique pour ses instances « text » et « delegate ».

ListModel {
    id : fruitModel
    ListElement { name: "Apple"; color: "green" }
    ListElement { name: "Cherry"; color: "red" }
    ListElement { name: "Banana"; color: "yellow" }
    ListElement { name: "Orange"; color: "orange" }
    ListElement { name: "WaterMelon"; color: "pink" }
}

SortFilterProxyModel {
    id: fruitFilter
    sourceModel: fruitModel
    sorters: [
        RoleSorter {
            roleName: "name"
        }
    ]
    filters: [
        FunctionFilter {
            property var regExp: new RegExp(fruitSearch.text, "i")
            onRegExpChanged: invalidate()
            function filter(name: string): bool {
                return regExp.test(name);
            }
        }
    ]
}

SearchField {
    id: fruitSearch
    suggestionModel: fruitFilter
    textRole: "name"
    anchors.horizontalCenter: parent.horizontalCenter
}

Voir également searchIndicator, clearIndicator, searchButtonPressed et clearButtonPressed.

Documentation sur les propriétés

clearIndicator group

Cette propriété groupée contient l'élément indicateur « clearIndicator » et ses propriétés associées.

Cette propriété contient l'indicateur « clear ». En cliquant dessus, on déclenche l'événement « clearButtonPressed ».

Elle est exposée afin que les styles et les applications puissent la personnaliser via ses propriétés internes (par exemple, en remplaçant ou en supprimant l'clearIndicator via clearIndicator.indicator, ou en réagissant à l'état d'interaction, tel que « enfoncé » ou « survolé »).

Voir également SearchField's Indicators.

currentIndex : int

Cette propriété contient l'index de la suggestion actuellement sélectionnée dans la liste contextuelle.

Sa valeur est « -1 » lorsqu'aucune suggestion n'est sélectionnée.

currentIndex n’est pas modifié automatiquement lorsque le modèle change ou lorsque l’utilisateur saisit ou modifie du texte. Il n’est mis à jour que lorsque l’utilisateur sélectionne explicitement une suggestion, soit en cliquant sur un élément de la liste contextuelle, soit en appuyant sur Entrée sur un élément mis en surbrillance.

currentIndex peut être défini ; par exemple, pour afficher le premier élément du modèle au démarrage. Avant de le faire, assurez-vous que le modèle n’est pas vide :

SearchField {
    id: searchField
    suggestionModel: ListModel {
        ListElement { value: "123,456" }
    }
    textRole: "value"

    Component.onCompleted: {
        if (suggestionModel.count > 0) {
           text = suggestionModel.get(0).value
           currentIndex = 0
       }
    }
}

Voir également activated(), text et highlightedIndex.

cursorPosition : int [since 6.12]

La position du curseur dans le champ de texte. Le curseur est positionné entre deux caractères.

Cette propriété a été introduite dans Qt 6.12.

delegate : Component

Cette propriété contient un délégué qui affiche un élément dans la fenêtre contextuelle du champ de recherche.

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: searchField.popup.close()
    }
}

Depuis Qt 6.11, ` SearchField ` ne prend plus possession du délégué.

delegateModel : model [read-only]

Cette propriété contient le modèle qui fournit les instances de délégué pour le champ de recherche.

Elle est généralement attribuée à une instance de « ListView » dans la méthode « contentItem » de l'objet « popup ».

highlightedIndex : int [read-only]

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

Lorsque l'élément sélectionné est activé, la liste déroulante se ferme, la propriété ` currentIndex ` est mise à jour pour correspondre à ` highlightedIndex`, et cette propriété est réinitialisée à ` -1`, indiquant qu'aucun élément n'est actuellement sélectionné.

Voir également highlighted() et currentIndex.

live : bool

Cette propriété contient une valeur booléenne qui détermine si la recherche est déclenchée à chaque modification du texte.

Lorsqu’elle est définie sur « true », le signal « searchTriggered()» est émis à chaque modification du texte, ce qui vous permet de réagir à chaque frappe. Lorsqu’elle est définie sur « false », le signal « searchTriggered()» n’est émis que lorsque l’utilisateur appuie sur la touche Entrée ou Retour.

Voir également searchTriggered().

placeholderText : string [since 6.12]

Cette propriété contient l'indice qui s'affiche dans l'SearchField e avant que l'utilisateur ne saisisse du texte.

Cette propriété a été introduite dans Qt 6.12.

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: searchField.popup.close()

searchIndicator group

Cette propriété groupée contient l'élément « searchIndicator » et ses propriétés associées.

Cette propriété contient l'indicateur de recherche. Un clic dessus déclenche l'événement « searchButtonPressed ».

Elle est exposée afin que les styles et les applications puissent la personnaliser via ses propriétés internes (par exemple, en remplaçant ou en supprimant l'searchIndicator via searchIndicator.indicator, ou en réagissant à l'état d'interaction, tel que « enfoncé » ou « survolé »).

Voir également SearchField's Indicators.

selectTextByMouse : bool [since 6.12]

Cette propriété indique si le texte peut être sélectionné à l'aide de la souris.

La valeur par défaut est « true ».

Cette propriété a été introduite dans Qt 6.12.

selectedText : string [read-only, since 6.12]

Cette propriété en lecture seule contient le texte actuellement sélectionné.

Cette propriété a été introduite dans Qt 6.12.

selectionEnd : int [read-only, since 6.12]

Position du curseur après le dernier caractère de la sélection actuelle.

Cette propriété est en lecture seule. Pour modifier la sélection, utilisez select(start, end), selectAll() ou selectWord().

Cette propriété a été introduite dans Qt 6.12.

Voir également selectionStart, cursorPosition et selectedText.

selectionStart : int [read-only, since 6.12]

Position du curseur avant le premier caractère de la sélection actuelle.

Cette propriété est en lecture seule. Pour modifier la sélection, utilisez select(start, end), selectAll() ou selectWord().

Cette propriété a été introduite dans Qt 6.12.

Voir également selectionEnd, cursorPosition et selectedText.

suggestionCount : int [read-only]

Cette propriété indique le nombre de suggestions à afficher à partir du modèle de suggestions.

suggestionModel : model

Cette propriété contient le modèle de données utilisé pour afficher les suggestions de recherche dans le menu contextuel.

SearchField {
    textRole: "age"
    suggestionModel: ListModel {
        ListElement { name: "Karen"; age: "66" }
        ListElement { name: "Jim"; age: "32" }
        ListElement { name: "Pamela"; age: "28" }
    }
}

Voir également textRole.

text : string

Cette propriété contient le texte actuellement saisi dans le champ de recherche.

Le texte est lié à la saisie de l'utilisateur, ce qui déclenche la mise à jour des suggestions ou la logique de recherche.

Voir également searchTriggered() et textEdited().

textRole : string

Cette propriété contient le rôle du modèle utilisé pour afficher les éléments dans le modèle de suggestions présenté dans la liste contextuelle.

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é.

Documentation Signal

void accepted()

Ce signal est émis lorsque l'utilisateur valide sa saisie en appuyant sur la touche Entrée ou Retour.

Ce signal est généralement utilisé pour déclencher une recherche ou une action en fonction du texte saisi, et il indique l'intention de l'utilisateur de valider ou d'envoyer la requête.

Voir également searchTriggered().

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 ). La propriété currentIndex est définie sur index.

Voir également currentIndex.

void clearButtonPressed()

Ce signal est émis lorsque l'on appuie sur le bouton « Effacer ».

Voir également searchButtonPressed().

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.

void searchButtonPressed()

Ce signal est émis lorsque l'on appuie sur le bouton de recherche.

Voir également clearButtonPressed().

void searchTriggered()

Ce signal est émis lorsqu'une action de recherche est lancée.

Il se produit dans deux cas : 1. Lorsque la touche Entrée ou Retour est enfoncée, il est émis en même temps que le signal « accepted() » ; 2. Lorsque le texte est modifié et que la propriété « live » est définie sur « true », ce signal est émis.

Ce signal est idéal pour lancer des recherches à la demande ou en temps réel au fur et à mesure que l’utilisateur tape, selon le modèle d’interaction souhaité.

Voir également accepted() et textEdited().

void textEdited()

Ce signal est émis chaque fois que l'utilisateur modifie le texte dans le champ de recherche, généralement à chaque frappe.

Voir également searchTriggered().

Documentation de la méthode

[since 6.12] void deselect()

Supprime la sélection de texte active.

Cette méthode a été introduite dans Qt 6.12.

Voir également selectedText, selectionStart et selectionEnd.

[since 6.12] void select(int start, int end)

Sélectionne le texte compris entre start et end.

Si l'une des adresses start ou end est hors de la plage définie, la sélection reste inchangée.

Après l'appel de cette méthode, selectionStart deviendra la valeur la plus petite et selectionEnd la plus grande (quel que soit l'ordre dans lequel les paramètres ont été passés à cette méthode).

Cette méthode a été introduite dans Qt 6.12.

Voir également selectionStart et selectionEnd.

[since 6.12] void selectAll()

Sélectionne tout le texte contenu dans le champ de texte du contrôle.

Cette méthode a été introduite dans Qt 6.12.

[since 6.12] void selectWord()

Permet de sélectionner le mot le plus proche de la position actuelle du curseur.

Cette méthode a été introduite dans Qt 6.12.

Voir également cursorPosition et selectedText.