QSpinBox Class
La classe QSpinBox fournit un widget « spin box ». En savoir plus...
| En-tête : | #include <QSpinBox> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake : | QT += widgets |
| Hérite de : | QAbstractSpinBox |
Propriétés
|
|
Fonctions publiques
| QSpinBox(QWidget *parent = nullptr) | |
| virtual | ~QSpinBox() |
| QString | cleanText() const |
| int | displayIntegerBase() const |
| int | maximum() const |
| int | minimum() const |
| QString | prefix() const |
| void | setDisplayIntegerBase(int base) |
| void | setMaximum(int max) |
| void | setMinimum(int min) |
| void | setPrefix(const QString &prefix) |
| void | setRange(int minimum, int maximum) |
| void | setSingleStep(int val) |
| void | setStepType(QAbstractSpinBox::StepType stepType) |
| void | setSuffix(const QString &suffix) |
| int | singleStep() const |
| QAbstractSpinBox::StepType | stepType() const |
| QString | suffix() const |
| int | value() const |
Emplacements publics
| void | setValue(int val) |
Signaux
| void | textChanged(const QString &text) |
| void | valueChanged(int i) |
Fonctions protégées
| virtual QString | textFromValue(int value) const |
| virtual int | valueFromText(const QString &text) const |
Fonctions protégées réimplémentées
| virtual bool | event(QEvent *event) override |
| virtual void | fixup(QString &input) const override |
| virtual QValidator::State | validate(QString &text, int &pos) const override |
Description détaillée
QSpinBox est conçu pour gérer des entiers et des ensembles discrets de valeurs (par exemple, les noms de mois) ; utilisez QDoubleSpinBox pour les valeurs à virgule flottante.
QSpinBox permet à l’utilisateur de choisir une valeur en cliquant sur les boutons haut/bas ou en appuyant sur les touches haut/bas du clavier pour augmenter ou diminuer la valeur actuellement affichée. L’utilisateur peut également saisir la valeur manuellement. La zone de sélection prend en charge les valeurs entières, mais peut être étendue pour utiliser différentes chaînes de caractères grâce aux fonctions validate(), textFromValue() et valueFromText().
À chaque modification de la valeur, QSpinBox émet les signaux valueChanged() et textChanged(), le premier fournissant un entier (int) et le second une chaîne de caractères ( QString). Le signal textChanged() fournit la valeur à la fois via prefix() et suffix(). La valeur actuelle peut être récupérée avec value() et définie avec setValue().
Cliquer sur les boutons haut/bas ou utiliser les flèches haut et bas du clavier permettra d’augmenter ou de diminuer la valeur actuelle par incréments de taille singleStep(). Si vous souhaitez modifier ce comportement, vous pouvez réimplémenter la fonction virtuelle stepBy(). Les valeurs minimale et maximale ainsi que la taille du pas peuvent être définies à l’aide de l’un des constructeurs, puis modifiées ultérieurement avec setMinimum(), setMaximum() et setSingleStep().
La plupart des champs de sélection sont directionnels, mais QSpinBox peut également fonctionner comme un champ de sélection circulaire : par exemple, si la plage est comprise entre 0 et 99 et que la valeur actuelle est 99, cliquer sur « haut » donnera 0 si wrapping() est défini sur true. Utilisez setWrapping() si vous souhaitez un comportement circulaire.
La valeur affichée peut être précédée ou suivie de chaînes de caractères arbitraires indiquant, par exemple, la devise ou l’unité de mesure. Voir setPrefix() et setSuffix(). Le texte contenu dans la zone de saisie est récupéré avec text() (qui inclut tout prefix() et suffix()), ou avec cleanText() (qui ne contient ni prefix(), ni suffix(), ni d’espaces en début ou en fin de chaîne).
Il est souvent souhaitable de proposer à l’utilisateur un choix spécial (souvent par défaut) en plus de la plage de valeurs numériques. Consultez setSpecialValueText() pour savoir comment procéder avec QSpinBox.
Sous-classer QSpinBox
Si l'utilisation de prefix(), suffix() et specialValueText() ne vous offre pas suffisamment de contrôle, vous pouvez créer une sous-classe de QSpinBox et réimplémenter valueFromText() et textFromValue(). Par exemple, voici le code d’une zone de sélection personnalisée permettant à l’utilisateur de saisir des tailles d’icônes (par exemple, « 32 x 32 ») :
int IconSizeSpinBox::valueFromText(const QString &text) const
{
static const QRegularExpression regExp(tr("(\\d+)(\\s*[xx]\\s*\\d+)?"));
Q_ASSERT(regExp.isValid());
const QRegularExpressionMatch match = regExp.match(text);
if (match.isValid())
return match.captured(1).toInt();
return 0;
}
QString IconSizeSpinBox::textFromValue(int value) const
{
return tr("%1 x %1").arg(value);
}Voir également QDoubleSpinBox, QDateTimeEdit, QSlider et l'exemple sur les spin boxes.
Documentation sur les propriétés
[read-only] cleanText : QString
Cette propriété contient le texte de la zone de saisie, à l'exclusion de tout préfixe, suffixe ou espace en début ou en fin de chaîne.
Fonctions d'accès :
| QString | cleanText() const |
Voir également text, QSpinBox::prefix et QSpinBox::suffix.
displayIntegerBase : int
Cette propriété définit la base utilisée pour afficher la valeur de la zone de saisie à rouleau
La valeur par défaut de displayIntegerBase est 10.
Fonctions d'accès :
| int | displayIntegerBase() const |
| void | setDisplayIntegerBase(int base) |
Voir également textFromValue() et valueFromText().
maximum : int
Cette propriété contient la valeur maximale de la zone de saisie à défilement
Lors de la configuration de cette propriété, la valeur minimale est ajustée si nécessaire, afin de garantir que la plage reste valide.
La valeur maximale par défaut est 99.
Fonctions d'accès :
| int | maximum() const |
| void | setMaximum(int max) |
Voir également setRange() et specialValueText.
minimum : int
Cette propriété contient la valeur minimale de la zone de saisie à sélection
Lors de la configuration de cette propriété, l'maximum e est ajustée si nécessaire afin de garantir que la plage reste valide.
La valeur minimale par défaut est 0.
Fonctions d'accès :
| int | minimum() const |
| void | setMinimum(int min) |
Voir également setRange() et specialValueText.
prefix : QString
Cette propriété contient le préfixe de la zone de saisie à spin
Le préfixe est ajouté au début de la valeur affichée. Il est généralement utilisé pour afficher une unité de mesure ou un symbole monétaire. Par exemple :
sb->setPrefix("$");Pour désactiver l'affichage du préfixe, définissez cette propriété sur une chaîne vide. Par défaut, aucun préfixe n'est affiché. Le préfixe n'est pas affiché lorsque value() == minimum() et que specialValueText() est défini.
Si aucun préfixe n’est défini, la fonction prefix() renvoie une chaîne vide.
Fonctions d’accès :
| QString | prefix() const |
| void | setPrefix(const QString &prefix) |
Voir également suffix(), setSuffix(), specialValueText() et setSpecialValueText().
singleStep : int
Cette propriété détermine la valeur du pas
Lorsque l'utilisateur utilise les flèches pour modifier la valeur de la zone de saisie, celle-ci est incrémentée ou décrémentée de la valeur de « singleStep ». La valeur par défaut est 1. Définir une valeur « singleStep » inférieure à 0 n'a aucun effet.
Fonctions d'accès :
| int | singleStep() const |
| void | setSingleStep(int val) |
stepType : StepType
Cette propriété définit le type de pas.
Le type de pas peut être un pas unique ou un pas décimal adaptatif.
Fonctions d'accès :
| QAbstractSpinBox::StepType | stepType() const |
| void | setStepType(QAbstractSpinBox::StepType stepType) |
suffix : QString
Cette propriété contient le suffixe de la zone de saisie à rouleau
Le suffixe est ajouté à la fin de la valeur affichée. Il est généralement utilisé pour afficher une unité de mesure ou un symbole monétaire. Par exemple :
sb->setSuffix(" km");Pour désactiver l'affichage du suffixe, définissez cette propriété sur une chaîne vide. Par défaut, aucun suffixe n'est affiché. Le suffixe n'est pas affiché pour la fonction ` minimum()` si la fonction ` specialValueText()` est définie.
Si aucun suffixe n’est défini, la fonction suffix() renvoie une chaîne vide.
Fonctions d’accès :
| QString | suffix() const |
| void | setSuffix(const QString &suffix) |
Voir également prefix(), setPrefix(), specialValueText() et setSpecialValueText().
value : int
Cette propriété contient la valeur de la zone de saisie à rouleau
setValue() émettra un signal « valueChanged() » si la nouvelle valeur diffère de l'ancienne. La propriété « value » dispose d'un deuxième signal de notification qui inclut le préfixe et le suffixe de la zone de saisie.
Fonctions d'accès :
| int | value() const |
| void | setValue(int val) |
Signal de notification :
| void | valueChanged(int i) |
Documentation des fonctions membres
[explicit] QSpinBox::QSpinBox(QWidget *parent = nullptr)
Crée une zone de sélection à rouleau dont la valeur minimale est 0 et la valeur maximale 99, avec un pas de 1. La valeur est initialement définie sur 0. Elle est rattachée à parent.
Voir également setMinimum(), setMaximum() et setSingleStep().
[virtual noexcept] QSpinBox::~QSpinBox()
Destructeur.
[override virtual protected] bool QSpinBox::event(QEvent *event)
Réimplémente : QAbstractSpinBox::event(QEvent *event).
[override virtual protected] void QSpinBox::fixup(QString &input) const
Réimplémente : QAbstractSpinBox::fixup(QString &input) const.
void QSpinBox::setRange(int minimum, int maximum)
Fonction pratique permettant de définir les valeurs de ` minimum` et ` maximum ` en un seul appel de fonction.
setRange(minimum, maximum);équivaut à :
setMinimum(minimum);
setMaximum(maximum);Voir également minimum et maximum.
void QSpinBox::setStepType(QAbstractSpinBox::StepType stepType)
Définit le type de pas de la zone de sélection sur « stepType », ce qui correspond à un pas unique ou à un pas décimal adaptatif.
Un pas décimal adaptatif signifie que la taille du pas sera continuellement ajustée à une puissance de dix inférieure à la valeur actuelle de « value ». Ainsi, lorsque la valeur est de 1 100, le pas est défini sur 100 ; une augmentation d’un pas fait donc passer la valeur à 1 200. Pour 1 200, une augmentation d’un pas fait passer la valeur à 1 300. Pour les valeurs négatives, une diminution à partir de -1 100 conduit à -1 200.
Le sens de l’incrément est pris en compte pour gérer les cas limites, de sorte qu’une diminution à partir de 100 ramène la valeur à 99 au lieu de 90. Ainsi, un incrément suivi d’une diminution – ou inversement – ramène toujours la valeur à sa valeur initiale : 99 -> 100 -> 99.
La définition de ce paramètre fera en sorte que la zone de saisie ignore la valeur de ` singleStep`, bien que celle-ci soit conservée afin que ` singleStep ` prenne effet si le pas décimal adaptatif est désactivé ultérieurement.
Remarque : fonctionde définition de la propriété stepType.
Voir également stepType().
[signal] void QSpinBox::textChanged(const QString &text)
Ce signal est émis chaque fois que le texte de la zone de saisie est modifié. Le nouveau texte est transmis via les méthodes ` text `, ` prefix()` et ` suffix()`.
[virtual protected] QString QSpinBox::textFromValue(int value) const
Cette fonction virtuelle est utilisée par la zone de saisie à chaque fois qu’elle doit afficher la valeur value. L’implémentation par défaut renvoie une chaîne contenant value, affichée de manière standard à l’aide de QWidget::locale(),toString(), mais sans le séparateur des milliers, sauf si setGroupSeparatorShown() est défini. Les réimplémentations peuvent renvoyer n’importe quelle valeur. (Voir l’exemple dans la description détaillée.)
Remarque : QSpinBox n’appelle pas cette fonction pour specialValueText() et ni prefix() ni suffix() ne doivent être inclus dans la valeur de retour.
Si vous réimplémentez cette fonction, vous devrez peut-être également réimplémenter valueFromText() et validate()
Voir également valueFromText(), validate() et QLocale::groupSeparator().
[override virtual protected] QValidator::State QSpinBox::validate(QString &text, int &pos) const
Réimplémentation de : QAbstractSpinBox::validate(QString &input, int &pos) const.
[signal] void QSpinBox::valueChanged(int i)
Ce signal est émis chaque fois que la valeur de la zone de sélection est modifiée. La partie entière de la nouvelle valeur est transmise dans ` i`.
Remarque : signalde notification pour la propriété value.
[virtual protected] int QSpinBox::valueFromText(const QString &text) const
Cette fonction virtuelle est utilisée par la zone de sélection chaque fois qu'elle doit interpréter une « text » saisie par l'utilisateur comme une valeur.
Les sous-classes qui doivent afficher les valeurs de la zone de sélection sous une forme non numérique doivent réimplémenter cette fonction.
Remarque : QSpinBox gère specialValueText() séparément ; cette fonction ne concerne que les autres valeurs.
Voir également textFromValue() et validate().
© 2026 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.
