SpinBox QML Type

Permet à l'utilisateur de choisir parmi un ensemble de valeurs prédéfinies. En savoir plus...

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

Propriétés

• displayText : string (since QtQuick.Controls 2.4 (Qt 5.11))
• down
  • down.hovered : bool
  • down.implicitIndicatorHeight : real
  • down.implicitIndicatorWidth : real
  • down.indicator : Item
  • down.pressed : bool
• editable : bool
• from : int
• inputMethodComposing : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• inputMethodHints : flags (since QtQuick.Controls 2.2 (Qt 5.9))
• live : bool (since 6.6)
• stepSize : int
• textFromValue : function
• to : int
• up
  • up.hovered : bool
  • up.implicitIndicatorHeight : real
  • up.implicitIndicatorWidth : real
  • up.indicator : Item
  • up.pressed : bool
• validator : Validator
• value : int
• valueFromText : function
• wrap : bool (since QtQuick.Controls 2.3 (Qt 5.10))

Signaux

• valueModified() (since QtQuick.Controls 2.2 (Qt 5.9))

Méthodes

• void decrease()
• void increase()

Description détaillée

SpinBox permet à l'utilisateur de choisir une valeur entière en cliquant sur les boutons fléchés haut ou bas, ou en appuyant sur les touches haut ou bas du clavier. En option, SpinBox peut également être configuré en mode « editable », ce qui permet à l'utilisateur de saisir une valeur textuelle dans le champ de saisie.

Par défaut, SpinBox propose des valeurs discrètes comprises dans l’intervalle [0-99] avec une stepSize e de 1.

SpinBox {
    value: 50
}

Pour les valeurs à virgule flottante, utilisez DoubleSpinBox.

Valeurs personnalisées

Même si SpinBox fonctionne avec des valeurs entières, il peut être personnalisé pour accepter des valeurs d’entrée arbitraires. L’extrait de code suivant montre comment validator, textFromValue et valueFromText peuvent être utilisés pour personnaliser le comportement par défaut.

SpinBox {
    id: spinBox
    from: 0
    to: items.length - 1
    value: 1 // "Medium"

    property list<string> items: ["Small", "Medium", "Large"]

    validator: RegularExpressionValidator {
        regularExpression: new RegExp("(Small|Medium|Large)", "i")
    }

    textFromValue: function(value) {
        return items[value];
    }

    valueFromText: function(text) {
        for (var i = 0; i < items.length; ++i) {
            if (items[i].toLowerCase().indexOf(text.toLowerCase()) === 0)
                return i
        }
        return spinBox.value
    }
}

Un préfixe et un suffixe peuvent être ajoutés à l'aide d'expressions régulières :

SpinBox {
    id: spinBox
    from: -100
    value: 11
    to: 100
    editable: true
    anchors.centerIn: parent

    property string prefix: "L="
    property string suffix: "m"

    readonly property regexp numberExtractionRegExp: /\D*?(-?\d*\.?\d*)\D*$/

    validator: RegularExpressionValidator { regularExpression: numberExtractionRegExp }

    textFromValue: function(value, locale) {
        return prefix + Number(value).toLocaleString(locale, 'f', 0) + suffix
    }

    valueFromText: function(text, locale) {
        return Number.fromLocaleString(locale, numberExtractionRegExp.exec(text)[1])
    }
}

Voir également Tumbler, Personnalisation de SpinBox, Gestion du focus dans Qt Quick Controls et DoubleSpinBox.

Documentation sur les propriétés

displayText : string [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

Cette propriété contient la valeur textuelle de la zone de saisie à rouleau.

La valeur de cette propriété s'appuie sur textFromValue et locale, et est égale à :

var text = spinBox.textFromValue(spinBox.value, spinBox.locale)

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

Voir également textFromValue.

down group

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

La propriété down.hovered a été introduite dans QtQuick.Controls 2.1, et les propriétés down.implicitIndicatorWidth et down.implicitIndicatorHeight ont été introduites dans QtQuick.Controls 2.5.

Voir également decrease().

editable : bool

Cette propriété indique si la zone de saisie « spinbox » est modifiable. La valeur par défaut est « false ».

Voir également validator.

from : int

Cette propriété contient la valeur initiale de la plage. La valeur par défaut est 0.

Voir également to et value.

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

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

Pendant la saisie, une méthode de saisie peut s'appuyer sur des événements de souris ou de clavier provenant de la zone de saisie 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 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)]

Cette propriété fournit des indications à la méthode de saisie concernant le contenu attendu de la zone de saisie à valeur fixe et son mode de fonctionnement.

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

La valeur est une combinaison binaire de drapeaux ou de « Qt.ImhNone » si aucune indication n'est définie.

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 de l’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 privilégié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 composés sur un 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 autorisés dans les 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).

live : bool [since 6.6]

Cette propriété détermine si la propriété « value » est mise à jour lorsque l'utilisateur modifie la valeur de « displayText ». La valeur par défaut est « false ». Si cette propriété est définie sur « true » et que la valeur saisie par l'utilisateur est valide et comprise dans les limites de la zone de saisie [from, to], la valeur de la propriété « SpinBox » sera mise à jour. Si cette propriété est définie sur « false » ou si la valeur saisie par l’utilisateur se trouve en dehors de ces limites, la valeur ne sera pas mise à jour tant que les touches Entrée ou Retour n’auront pas été enfoncées, ou que le champ de saisie n’aura pas perdu le focus.

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

Voir également editable et displayText.

stepSize : int

Cette propriété définit la taille du pas. La valeur par défaut est 1.

Voir également increase() et decrease().

textFromValue : function

Cette propriété contient une fonction de rappel qui est appelée chaque fois qu'une valeur entière doit être convertie en texte à afficher.

La fonction par défaut peut être redéfinie pour afficher un texte personnalisé pour une valeur donnée. Cela s'applique aussi bien aux spinboxes modifiables qu'aux spinboxes non modifiables ; par exemple, lorsque vous utilisez les boutons haut et bas ou la molette de la souris pour augmenter ou diminuer la valeur, la nouvelle valeur est convertie en texte d'affichage à l'aide de cette fonction.

La signature de la fonction de rappel est string function(value, locale). La fonction peut avoir un ou deux arguments : le premier argument est la valeur à convertir, et le second argument, facultatif, correspond aux paramètres régionaux à utiliser pour la conversion, le cas échéant.

L’implémentation par défaut effectue la conversion à l’aide de ` Number.toLocaleString()` :

textFromValue: function(value, locale) { return Number(value).toLocaleString(locale, 'f', 0); }

Voir également valueFromText, validator et locale.

to : int

Cette propriété contient la valeur finale de la plage. La valeur par défaut est 99.

Voir également from et value.

up group

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

La propriété up.hovered a été introduite dans QtQuick.Controls 2.1, tandis que les propriétés up.implicitIndicatorWidth et up.implicitIndicatorHeight ont été introduites dans QtQuick.Controls 2.5.

Voir également increase().

validator : Validator

Cette propriété contient le validateur de texte pour les zones de saisie modifiables de type « spinbox ». Par défaut, SpinBox utilise IntValidator pour n'accepter que des nombres entiers.

SpinBox {
    id: control
    validator: IntValidator {
        locale: control.locale.name
        bottom: Math.min(control.from, control.to)
        top: Math.max(control.from, control.to)
    }
}

Voir également editable, textFromValue, valueFromText, locale et Validation du texte saisi.

value : int

Cette propriété prend une valeur comprise entre from et to. La valeur par défaut est 0.

valueFromText : function

Cette propriété contient une fonction de rappel qui est appelée chaque fois que le texte saisi doit être converti en une valeur entière.

Cette fonction ne doit être redéfinie que lorsque la méthode ` textFromValue ` est redéfinie pour une zone de saisie modifiable (spinbox).

La signature de la fonction de rappel est int function(text, locale). La fonction peut prendre un ou deux arguments : le premier correspond au texte à convertir, et le second, facultatif, désigne les paramètres régionaux à utiliser pour la conversion, le cas échéant.

L’implémentation par défaut effectue la conversion à l’aide de ` Number.fromLocaleString()` :

valueFromText: function(text, locale) { return Number.fromLocaleString(locale, text); }

Voir également textFromValue, validator et locale.

wrap : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

Cette propriété détermine si la zone de saisie « spinbox » effectue un retour à la ligne. La valeur par défaut est « false ».

Si wrap est défini sur « true », le fait de dépasser « to » fait passer la valeur à « from » et inversement.

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

Documentation sur les signaux

[since QtQuick.Controls 2.2 (Qt 5.9)] valueModified()

Ce signal est émis lorsque la valeur de la zone de sélection a été modifiée de manière interactive par l'utilisateur, que ce soit par effleurement, à l'aide de la souris, de la molette ou du clavier. En cas d'interaction via le clavier, le signal n'est émis que lorsque le texte a été validé, c'est-à-dire lorsque les touches Entrée ou Retour ont été enfoncées, ou lorsque le champ de saisie perd le focus.

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

Documentation de la méthode

void decrease()

Réduit la valeur de stepSize, ou de 1 si stepSize n'est pas défini.

Voir également stepSize.

void increase()

Augmente la valeur de stepSize, ou de 1 si stepSize n'est pas défini.

Voir également stepSize.