Sur cette page

QAbstractSpinBox Class

La classe QAbstractSpinBox fournit une zone de sélection et un champ de saisie pour afficher des valeurs. En savoir plus...

En-tête : #include <QAbstractSpinBox>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets
Hérite de : QWidget
Hérédité :

QDateTimeEdit, QDoubleSpinBox et QSpinBox

Types publics

enum ButtonSymbols { UpDownArrows, PlusMinus, NoButtons }
enum CorrectionMode { CorrectToPreviousValue, CorrectToNearestValue }
flags StepEnabled
enum StepEnabledFlag { StepNone, StepUpEnabled, StepDownEnabled }
enum StepType { DefaultStepType, AdaptiveDecimalStepType }

Propriétés

Fonctions publiques

QAbstractSpinBox(QWidget *parent = nullptr)
virtual ~QAbstractSpinBox()
Qt::Alignment alignment() const
QAbstractSpinBox::ButtonSymbols buttonSymbols() const
QAbstractSpinBox::CorrectionMode correctionMode() const
virtual void fixup(QString &input) const
bool hasAcceptableInput() const
bool hasFrame() const
void interpretText()
bool isAccelerated() const
bool isGroupSeparatorShown() const
bool isReadOnly() const
bool keyboardTracking() const
void setAccelerated(bool on)
void setAlignment(Qt::Alignment flag)
void setButtonSymbols(QAbstractSpinBox::ButtonSymbols bs)
void setCorrectionMode(QAbstractSpinBox::CorrectionMode cm)
void setFrame(bool)
void setGroupSeparatorShown(bool shown)
void setKeyboardTracking(bool kt)
void setReadOnly(bool r)
void setSpecialValueText(const QString &txt)
void setWrapping(bool w)
QString specialValueText() const
virtual void stepBy(int steps)
QString text() const
virtual QValidator::State validate(QString &input, int &pos) const
bool wrapping() const

Fonctions publiques réimplémentées

virtual bool event(QEvent *event) override
virtual QVariant inputMethodQuery(Qt::InputMethodQuery query) const override
virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

Slots publics

virtual void clear()
void selectAll()
void stepDown()
void stepUp()

Signaux

void editingFinished()
(since 6.10) void returnPressed()

Fonctions protégées

virtual void initStyleOption(QStyleOptionSpinBox *option) const
QLineEdit *lineEdit() const
void setLineEdit(QLineEdit *lineEdit)
virtual QAbstractSpinBox::StepEnabled stepEnabled() const

Fonctions protégées réimplémentées

virtual void changeEvent(QEvent *event) override
virtual void closeEvent(QCloseEvent *event) override
virtual void contextMenuEvent(QContextMenuEvent *event) override
virtual void focusInEvent(QFocusEvent *event) override
virtual void focusOutEvent(QFocusEvent *event) override
virtual void hideEvent(QHideEvent *event) override
virtual void keyPressEvent(QKeyEvent *event) override
virtual void keyReleaseEvent(QKeyEvent *event) override
virtual void mouseMoveEvent(QMouseEvent *event) override
virtual void mousePressEvent(QMouseEvent *event) override
virtual void mouseReleaseEvent(QMouseEvent *event) override
virtual void paintEvent(QPaintEvent *event) override
virtual void resizeEvent(QResizeEvent *event) override
virtual void showEvent(QShowEvent *event) override
virtual void timerEvent(QTimerEvent *event) override
virtual void wheelEvent(QWheelEvent *event) override

Description détaillée

Cette classe est conçue comme une super-classe commune pour des widgets tels que QSpinBox, QDoubleSpinBox et QDateTimeEdit

Voici les principales propriétés de la classe :

  1. text: Le texte affiché dans le QAbstractSpinBox.
  2. alignment: L'alignement du texte dans le QAbstractSpinBox.
  3. wrapping: Indique si le QAbstractSpinBox effectue une boucle de la valeur minimale à la valeur maximale et inversement.

QAbstractSpinBox fournit une fonction virtuelle ` stepBy()` qui est appelée chaque fois que l’utilisateur déclenche un pas. Cette fonction prend une valeur entière indiquant le nombre de pas effectués. Par exemple, appuyer sur ` Qt::Key_Down ` déclenchera un appel à ` stepBy` (-1).

Lorsque l’utilisateur déclenche un pas tout en maintenant la touche Qt::ControlModifier enfoncée, QAbstractSpinBox effectue 10 pas au lieu d’un seul. Ce modificateur de pas affecte les événements de molette, les événements de touche et l’interaction avec les boutons de la zone de sélection. Notez que sous macOS, la touche Contrôle correspond à la touche Commande.

Depuis Qt 5.12, la méthode ` QStyle::SH_SpinBox_StepModifier ` permet de sélectionner la touche Qt::KeyboardModifier qui augmente la vitesse d'incrémentation. La méthode ` Qt::NoModifier ` désactive cette fonctionnalité.

QAbstractSpinBox fournit également une fonction virtuelle stepEnabled() permettant de déterminer si l’augmentation ou la diminution par pas est autorisée à un moment donné. Cette fonction renvoie un ensemble de bits correspondant à StepEnabled.

Voir également QAbstractSlider, QSpinBox, QDoubleSpinBox, QDateTimeEdit et l’exemple sur les Spin Boxes.

Documentation sur les types de membres

enum QAbstractSpinBox::ButtonSymbols

Ce type d'énumération décrit les symboles pouvant s'afficher sur les boutons d'une zone de sélection.

Champ de saisie avec les flèches haut et bas Champ de saisie avec les symboles « plus » et « moins »

ConstanteValeurDescription
QAbstractSpinBox::UpDownArrows0Petites flèches de style classique.
QAbstractSpinBox::PlusMinus1Symboles «+ » et « - ».
QAbstractSpinBox::NoButtons2Ne pas afficher les boutons.

Voir aussi QAbstractSpinBox::buttonSymbols.

enum QAbstractSpinBox::CorrectionMode

Ce type d'énumération décrit le mode que la zone de saisie à roue utilisera pour corriger une valeur d'Intermediate ion une fois la modification terminée.

ConstanteValeurDescription
QAbstractSpinBox::CorrectToPreviousValue0La zone de sélection reviendra à la dernière valeur valide.
QAbstractSpinBox::CorrectToNearestValue1La zone de saisie à roue reviendra à la valeur valide la plus proche.

Voir aussi correctionMode.

enum QAbstractSpinBox::StepEnabledFlag
flags QAbstractSpinBox::StepEnabled

ConstanteValeur
QAbstractSpinBox::StepNone0x00
QAbstractSpinBox::StepUpEnabled0x01
QAbstractSpinBox::StepDownEnabled0x02

Le type StepEnabled est un typedef pour QFlags<StepEnabledFlag>. Il stocke une combinaison OR de valeurs StepEnabledFlag.

enum QAbstractSpinBox::StepType

ConstanteValeur
QAbstractSpinBox::DefaultStepType0
QAbstractSpinBox::AdaptiveDecimalStepType1

Documentation sur les propriétés

accelerated : bool

Cette propriété détermine si la zone de sélection accélère la fréquence des incréments lorsque l'on appuie sur les boutons « + » et « - ».

Si cette option est activée, la zone de saisie augmentera ou diminuera la valeur d'autant plus rapidement que vous maintiendrez le bouton enfoncé.

Fonctions d'accès :

bool isAccelerated() const
void setAccelerated(bool on)

[read-only] acceptableInput : bool

Cette propriété indique si la valeur saisie respecte les critères de validation actuels

Fonctions d’accès :

bool hasAcceptableInput() const

Voir également validate(), fixup() et correctionMode.

alignment : Qt::Alignment

Cette propriété définit l'alignement de la zone de saisie à défilement

Les valeurs possibles sont : « Qt::AlignLeft », « Qt::AlignRight » et « Qt::AlignHCenter ».

Par défaut, l'alignement est Qt::AlignLeft

Tenter de définir l’alignement sur une combinaison de drapeaux non valide n’a aucun effet.

Fonctions d'accès :

Qt::Alignment alignment() const
void setAlignment(Qt::Alignment flag)

Voir également Qt::Alignment.

buttonSymbols : ButtonSymbols

Cette propriété contient le mode actuel du symbole du bouton

Les valeurs possibles sont « UpDownArrows » ou « PlusMinus ». La valeur par défaut est « UpDownArrows ».

Notez que certains styles peuvent afficher « PlusMinus » et « UpDownArrows » de manière identique.

Fonctions d'accès :

QAbstractSpinBox::ButtonSymbols buttonSymbols() const
void setButtonSymbols(QAbstractSpinBox::ButtonSymbols bs)

Voir également ButtonSymbols.

correctionMode : CorrectionMode

Cette propriété définit le mode de correction d'une valeur « Intermediate » une fois la modification terminée

Le mode par défaut est « QAbstractSpinBox::CorrectToPreviousValue ».

Fonctions d'accès :

QAbstractSpinBox::CorrectionMode correctionMode() const
void setCorrectionMode(QAbstractSpinBox::CorrectionMode cm)

Voir également acceptableInput, validate() et fixup().

frame : bool

Cette propriété détermine si la zone de sélection s'affiche avec ou sans cadre

Si cette option est activée (par défaut), la zone de sélection s'affiche à l'intérieur d'un cadre ; sinon, elle s'affiche sans cadre.

Fonctions d'accès :

bool hasFrame() const
void setFrame(bool)

keyboardTracking : bool

Cette propriété indique si le suivi du clavier est activé pour la zone de saisie.

Si le suivi du clavier est activé (par défaut), la zone de saisie émet les signaux `valueChanged()` et `textChanged()` au fur et à mesure que la nouvelle valeur est saisie à partir du clavier.

Par exemple, lorsque l’utilisateur saisit la valeur 600 en tapant 6, 0 et 0, la zone de saisie émet 3 signaux avec les valeurs 6, 60 et 600 respectivement.

Si le suivi du clavier est désactivé, la zone de saisie ne génère pas les signaux `valueChanged()` et `textChanged()` pendant la saisie. Elle génère ces signaux ultérieurement, lorsque la touche Entrée est enfoncée, lorsque le focus du clavier est perdu ou lorsqu’une autre fonctionnalité de la zone de saisie est utilisée, par exemple en appuyant sur une touche fléchée.

Fonctions d’accès :

bool keyboardTracking() const
void setKeyboardTracking(bool kt)

readOnly : bool

Cette propriété s'applique que la zone de saisie soit en lecture seule ou non.

En mode lecture seule, l'utilisateur peut toujours copier le texte dans le presse-papiers ou le glisser-déposer, mais il ne peut pas le modifier.

L'QLineEdit, dans l'QAbstractSpinBox, n'affiche pas de curseur en mode lecture seule.

Fonctions d'accès :

bool isReadOnly() const
void setReadOnly(bool r)

Voir également QLineEdit::readOnly.

showGroupSeparator : bool

Cette propriété indique si le séparateur de milliers est activé. Par défaut, cette propriété a la valeur « false ».

Fonctions d'accès :

bool isGroupSeparatorShown() const
void setGroupSeparatorShown(bool shown)

specialValueText : QString

Cette propriété contient le texte de valeur spéciale

Si elle est définie, la zone de sélection affichera ce texte à la place d’une valeur numérique chaque fois que la valeur actuelle est égale à minimum(). Elle sert généralement à indiquer que ce choix a une signification particulière (par défaut).

Par exemple, si votre champ de sélection permet à l'utilisateur de choisir un facteur d'échelle (ou un niveau de zoom) pour l'affichage d'une image, et que votre application est capable de choisir automatiquement celui qui permettra à l'image de s'afficher entièrement dans la fenêtre d'affichage, vous pouvez configurer le champ de sélection comme suit :

    QSpinBox *zoomSpinBox = new QSpinBox;
    zoomSpinBox->setRange(0, 1000);
    zoomSpinBox->setSingleStep(10);
    zoomSpinBox->setSuffix("%");
    zoomSpinBox->setSpecialValueText(tr("Automatic"));
    zoomSpinBox->setValue(100);

L’utilisateur pourra alors choisir un facteur d’échelle compris entre 1 % et 1 000 % ou sélectionner « Auto » pour laisser l’application choisir à sa place. Votre code doit alors interpréter la valeur 0 de la zone de sélection comme une demande de l’utilisateur visant à redimensionner l’image pour qu’elle s’adapte à la fenêtre.

Toutes les valeurs s’affichent avec le préfixe et le suffixe (s’ils sont définis), à l’exception de la valeur spéciale, qui n’affiche que le texte correspondant à cette valeur. Ce texte spécial est transmis via le signal ` QSpinBox::textChanged()` qui transmet un objet ` QString`.

Pour désactiver l’affichage du texte de valeur spéciale, appelez cette fonction avec une chaîne vide. Par défaut, aucun texte de valeur spéciale n’est affiché, c’est-à-dire que la valeur numérique s’affiche comme d’habitude.

Si aucun texte de valeur spéciale n’est défini, specialValueText() renvoie une chaîne vide.

Fonctions d'accès :

QString specialValueText() const
void setSpecialValueText(const QString &txt)

[read-only] text : QString

Cette propriété contient le texte de la zone de saisie à spin, y compris tout préfixe et suffixe

Il n'y a pas de texte par défaut.

Fonctions d'accès :

QString text() const

wrapping : bool

Cette propriété détermine si la zone de saisie à défilement est circulaire.

Si l'option « wrapping » est activée, le fait de dépasser la valeur « maximum() » vous ramènera à la valeur « minimum() », et inversement. L'option « wrapping » n'a de sens que si les valeurs « minimum() » et « maximum() » sont définies.

QSpinBox *spinBox = new QSpinBox(this);
spinBox->setRange(0, 100);
spinBox->setWrapping(true);
spinBox->setValue(100);
spinBox->stepBy(1);
// value is 0

Fonctions d'accès :

bool wrapping() const
void setWrapping(bool w)

Voir également QSpinBox::minimum() et QSpinBox::maximum().

Documentation des fonctions membres

[explicit] QAbstractSpinBox::QAbstractSpinBox(QWidget *parent = nullptr)

Crée une spinbox abstraite avec l'parent, les valeurs par défaut wrapping et les propriétés d'alignement indiquées.

[virtual noexcept] QAbstractSpinBox::~QAbstractSpinBox()

Appelée lorsque l'QAbstractSpinBox est détruite.

[override virtual protected] void QAbstractSpinBox::changeEvent(QEvent *event)

Réimplémente : QWidget::changeEvent(QEvent *event).

[virtual slot] void QAbstractSpinBox::clear()

Efface tout le texte de la ligne éditée, à l'exception du préfixe et du suffixe.

[override virtual protected] void QAbstractSpinBox::closeEvent(QCloseEvent *event)

Réimplémente : ` QWidget::closeEvent(QCloseEvent *event)`.

[override virtual protected] void QAbstractSpinBox::contextMenuEvent(QContextMenuEvent *event)

Réimplémente : QWidget::contextMenuEvent(QContextMenuEvent *event).

[signal] void QAbstractSpinBox::editingFinished()

Ce signal est émis une fois la saisie terminée. Cela se produit lorsque la zone de saisie perd le focus et lorsque l'on appuie sur la touche Entrée.

[override virtual] bool QAbstractSpinBox::event(QEvent *event)

Réimplémente : QWidget::event(QEvent *event).

[virtual] void QAbstractSpinBox::fixup(QString &input) const

Cette fonction virtuelle est appelée par ` QAbstractSpinBox ` si la valeur ` input ` n'est pas validée selon ` QValidator::Acceptable ` lorsque l'on appuie sur la touche Retour ou que l'on appelle ` interpretText()`. Elle tentera de modifier le texte afin qu'il soit valide. Réimplémentée dans les différentes sous-classes.

[override virtual protected] void QAbstractSpinBox::focusInEvent(QFocusEvent *event)

Réimplémente : QWidget::focusInEvent(QFocusEvent *event).

[override virtual protected] void QAbstractSpinBox::focusOutEvent(QFocusEvent *event)

Réimplémente : QWidget::focusOutEvent(QFocusEvent *event).

[override virtual protected] void QAbstractSpinBox::hideEvent(QHideEvent *event)

Réimplémente : QWidget::hideEvent(QHideEvent *event).

[virtual protected] void QAbstractSpinBox::initStyleOption(QStyleOptionSpinBox *option) const

Initialisez ` option ` avec les valeurs fournies à l'adresse suivante : QSpinBox. Cette méthode est utile pour les sous-classes qui ont besoin d'un ` QStyleOptionSpinBox`, mais ne souhaitent pas renseigner elles-mêmes toutes les informations.

Voir également QStyleOption::initFrom().

[override virtual] QVariant QAbstractSpinBox::inputMethodQuery(Qt::InputMethodQuery query) const

Réimplémente : ` QWidget::inputMethodQuery` (requête `Qt::InputMethodQuery`) const.

void QAbstractSpinBox::interpretText()

Cette fonction analyse le texte de la zone de sélection. Si la valeur a changé depuis la dernière analyse, elle émettra des signaux.

[override virtual protected] void QAbstractSpinBox::keyPressEvent(QKeyEvent *event)

Réimplémente : QWidget::keyPressEvent(QKeyEvent *event).

Cette fonction gère les entrées clavier.

Les touches suivantes sont gérées spécifiquement :

Entrée/RetourCela réinterprète le texte et émet un signal même si la valeur n’a pas changé depuis la dernière émission d’un signal.
Flèche vers le hautCela appelle la fonction ` stepBy(1)`
Flèche vers le basCela appellera la fonction ` stepBy` (-1)
Page précédenteCela lancera stepBy(10)
Page suivanteCela appellera la fonction stepBy(-10)

Voir aussi stepBy().

[override virtual protected] void QAbstractSpinBox::keyReleaseEvent(QKeyEvent *event)

Réimplémente : QWidget::keyReleaseEvent(QKeyEvent *event).

[protected] QLineEdit *QAbstractSpinBox::lineEdit() const

Cette fonction renvoie un pointeur vers la zone de saisie de la liste déroulante.

Voir également setLineEdit().

[override virtual] QSize QAbstractSpinBox::minimumSizeHint() const

Réimplémente une fonction d'accès pour la propriété : QWidget::minimumSizeHint.

[override virtual protected] void QAbstractSpinBox::mouseMoveEvent(QMouseEvent *event)

Réimplémente : QWidget::mouseMoveEvent(QMouseEvent *event).

[override virtual protected] void QAbstractSpinBox::mousePressEvent(QMouseEvent *event)

Réimplémente : QWidget::mousePressEvent(QMouseEvent *event).

[override virtual protected] void QAbstractSpinBox::mouseReleaseEvent(QMouseEvent *event)

Réimplémente : QWidget::mouseReleaseEvent(QMouseEvent *event).

[override virtual protected] void QAbstractSpinBox::paintEvent(QPaintEvent *event)

Réimplémente : QWidget::paintEvent(QPaintEvent *event).

[override virtual protected] void QAbstractSpinBox::resizeEvent(QResizeEvent *event)

Réimplémente : QWidget::resizeEvent(QResizeEvent *event).

[signal, since 6.10] void QAbstractSpinBox::returnPressed()

Ce signal est émis lorsque l'on appuie sur la touche Retour ou Entrée.

Cette fonction a été introduite dans Qt 6.10.

[slot] void QAbstractSpinBox::selectAll()

Sélectionne tout le texte contenu dans la zone de saisie à rouleau, à l'exception du préfixe et du suffixe.

[protected] void QAbstractSpinBox::setLineEdit(QLineEdit *lineEdit)

Définit le champ de saisie de la zone de sélection comme étant « lineEdit » à la place du widget de saisie actuel. « lineEdit » ne peut pas être « nullptr ».

QAbstractSpinBox prend possession du nouveau lineEdit

Si la méthode ` QLineEdit::validator()` de ` lineEdit ` renvoie ` nullptr`, le validateur interne de la zone de saisie à défilement sera défini sur la zone de saisie.

Voir également lineEdit().

[override virtual protected] void QAbstractSpinBox::showEvent(QShowEvent *event)

Réimplémente : QWidget::showEvent(QShowEvent *event).

[override virtual] QSize QAbstractSpinBox::sizeHint() const

Réimplémente une fonction d'accès pour la propriété : QWidget::sizeHint.

[virtual] void QAbstractSpinBox::stepBy(int steps)

Fonction virtuelle appelée chaque fois que l'utilisateur déclenche un pas. Le paramètre ` steps ` indique le nombre de pas effectués. Par exemple, en appuyant sur ` Qt::Key_Down `, on déclenche un appel à ` stepBy(-1)`, tandis qu'en appuyant sur ` Qt::Key_PageUp `, on déclenche un appel à ` stepBy(10)`.

Si vous créez une sous-classe de ` QAbstractSpinBox `, vous devez réimplémenter cette fonction. Notez que cette fonction est appelée même si la valeur résultante se situe en dehors des limites minimale et maximale. C’est à cette fonction qu’il revient de gérer ces situations.

Voir également stepUp(), stepDown() et keyPressEvent().

[slot] void QAbstractSpinBox::stepDown()

Diminue la valeur d'un pas de ligne. L'appel de ce slot est analogue à l'appel de ` stepBy(-1) ;`

Voir également stepBy() et stepUp().

[virtual protected] QAbstractSpinBox::StepEnabled QAbstractSpinBox::stepEnabled() const

Fonction virtuelle qui détermine si les incréments et les décréments sont autorisés à un moment donné.

La flèche vers le haut sera affichée comme désactivée à moins que (stepEnabled() & StepUpEnabled) != 0.

L'implémentation par défaut renverra (StepUpEnabled| StepDownEnabled) si le bouclage est activé. Sinon, elle renverra StepDownEnabled si la valeur est supérieure à minimum(), ou StepUpEnabled si la valeur est inférieure à maximum().

Si vous créez une sous-classe de ` QAbstractSpinBox `, vous devrez réimplémenter cette fonction.

Voir également QSpinBox::minimum(), QSpinBox::maximum() et wrapping().

[slot] void QAbstractSpinBox::stepUp()

Augmente la valeur d'un pas de ligne. L'appel de ce slot revient à appeler ` stepBy(1)` ;

Voir également stepBy() et stepDown().

[override virtual protected] void QAbstractSpinBox::timerEvent(QTimerEvent *event)

Réimplémente : QObject::timerEvent(QTimerEvent *event).

[virtual] QValidator::State QAbstractSpinBox::validate(QString &input, int &pos) const

Cette fonction virtuelle est appelée par la classe ` QAbstractSpinBox ` afin de déterminer si ` input ` est valide. Le paramètre ` pos ` indique la position dans la chaîne. Réimplémentée dans les différentes sous-classes.

[override virtual protected] void QAbstractSpinBox::wheelEvent(QWheelEvent *event)

Réimplémente : QWidget::wheelEvent(QWheelEvent *event).

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