En esta página

QAbstractSpinBox Class

La clase QAbstractSpinBox proporciona un cuadro de selección y un campo de edición de texto para mostrar valores. Más...

Encabezado: #include <QAbstractSpinBox>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QWidget
Heredado por:

QDateTimeEdit, ` QDoubleSpinBox` y QSpinBox

Tipos públicos

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

Propiedades

Funciones públicas

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

Funciones públicas reimplementadas

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

Ranuras públicas

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

Señales

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

Funciones protegidas

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

Funciones protegidas reimplementadas

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

Descripción detallada

La clase está diseñada como una superclase común para widgets como QSpinBox, QDoubleSpinBox y QDateTimeEdit

Estas son las principales propiedades de la clase:

  1. text: El texto que se muestra en el QAbstractSpinBox.
  2. alignment: La alineación del texto en el QAbstractSpinBox.
  3. wrapping: Indica si el QAbstractSpinBox pasa del valor mínimo al máximo y viceversa.

QAbstractSpinBox proporciona una función virtual stepBy() que se invoca cada vez que el usuario activa un paso. Esta función toma un valor entero que indica cuántos pasos se han dado. Por ejemplo, al pulsar Qt::Key_Down se activará una llamada a stepBy(-1).

Cuando el usuario activa un paso mientras mantiene pulsada la tecla Qt::ControlModifier, QAbstractSpinBox avanza 10 pasos en lugar de dar un solo paso. Este modificador de pasos afecta a los eventos de rueda, a los eventos de teclas y a la interacción con los botones del cuadro giratorio. Ten en cuenta que, en macOS, la tecla Control corresponde a la tecla Comando.

Desde Qt 5.12, se puede utilizar QStyle::SH_SpinBox_StepModifier para seleccionar qué Qt::KeyboardModifier aumenta la velocidad de avance. Qt::NoModifier desactiva esta característica.

QAbstractSpinBox también proporciona una función virtual stepEnabled() para determinar si se permite avanzar o retroceder en cualquier momento. Esta función devuelve un conjunto de bits de StepEnabled.

Véase también QAbstractSlider, QSpinBox, QDoubleSpinBox, QDateTimeEdit y el ejemplo de cuadros giratorios.

Documentación sobre tipos de miembros

enum QAbstractSpinBox::ButtonSymbols

Este tipo de enumeración describe los símbolos que pueden aparecer en los botones de un cuadro giratorio.

Cuadro de selección con los símbolos de las flechas arriba y abajo Cuadro de selección con los símbolos «más» y «menos»

ConstanteValorDescripción
QAbstractSpinBox::UpDownArrows0Pequeñas flechas de estilo clásico.
QAbstractSpinBox::PlusMinus1Símbolos «+ » y «- ».
QAbstractSpinBox::NoButtons2No mostrar botones.

Véase también QAbstractSpinBox::buttonSymbols.

enum QAbstractSpinBox::CorrectionMode

Este tipo de enumeración describe el modo en que el cuadro de selección utilizará para corregir un valor « Intermediate » si finaliza la edición.

ConstanteValorDescripción
QAbstractSpinBox::CorrectToPreviousValue0El cuadro de selección volverá al último valor válido.
QAbstractSpinBox::CorrectToNearestValue1El cuadro de selección volverá al valor válido más cercano.

Véase también correctionMode.

enum QAbstractSpinBox::StepEnabledFlag
flags QAbstractSpinBox::StepEnabled

ConstanteValor
QAbstractSpinBox::StepNone0x00
QAbstractSpinBox::StepUpEnabled0x01
QAbstractSpinBox::StepDownEnabled0x02

El tipo StepEnabled es una definición de tipo (typedef) para QFlags<StepEnabledFlag>. Almacena una combinación OR de valores de StepEnabledFlag.

enum QAbstractSpinBox::StepType

ConstanteValor
QAbstractSpinBox::DefaultStepType0
QAbstractSpinBox::AdaptiveDecimalStepType1

Documentación de la propiedad

accelerated : bool

Esta propiedad determina si el cuadro giratorio acelerará la frecuencia de los pasos al pulsar los botones «Subir» o «Bajar».

Si está activada, el cuadro giratorio aumentará o disminuirá el valor más rápidamente cuanto más tiempo se mantenga pulsado el botón.

Funciones de acceso:

bool isAccelerated() const
void setAccelerated(bool on)

[read-only] acceptableInput : bool

Esta propiedad indica si la entrada cumple con la validación actual

Funciones de acceso:

bool hasAcceptableInput() const

Véase también validate(), fixup() y correctionMode.

alignment : Qt::Alignment

Esta propiedad determina la alineación del cuadro de selección

Los valores posibles son « Qt::AlignLeft », « Qt::AlignRight » y « Qt::AlignHCenter ».

Por defecto, la alineación es Qt::AlignLeft

Si se intenta establecer la alineación en una combinación de indicadores no válida, no ocurre nada.

Funciones de acceso:

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

Véase también Qt::Alignment.

buttonSymbols : ButtonSymbols

Esta propiedad indica el modo de símbolo de botón actual

Los valores posibles pueden ser « UpDownArrows » o « PlusMinus ». El valor predeterminado es « UpDownArrows ».

Ten en cuenta que algunos estilos pueden mostrar « PlusMinus » y « UpDownArrows » de forma idéntica.

Funciones de acceso:

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

Véase también ButtonSymbols.

correctionMode : CorrectionMode

Esta propiedad define el modo de corrección de un valor « Intermediate » al finalizar la edición

El modo predeterminado es « QAbstractSpinBox::CorrectToPreviousValue ».

Funciones de acceso:

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

Véase también « acceptableInput» , « validate()» y « fixup()».

frame : bool

Esta propiedad determina si el cuadro giratorio se dibuja con un marco

Si está activada (valor por defecto), el cuadro giratorio se muestra dentro de un marco; en caso contrario, se muestra sin marco alguno.

Funciones de acceso:

bool hasFrame() const
void setFrame(bool)

keyboardTracking : bool

Esta propiedad indica si el seguimiento del teclado está activado para el cuadro de selección.

Si el seguimiento del teclado está activado (por defecto), el cuadro de selección emite las señales `valueChanged()` y `textChanged()` mientras se introduce el nuevo valor desde el teclado.

Por ejemplo, cuando el usuario introduce el valor 600 tecleando 6, 0 y 0, el cuadro giratorio emite tres señales con los valores 6, 60 y 600, respectivamente.

Si el seguimiento del teclado está desactivado, el cuadro giratorio no emite las señales valueChanged() y textChanged() mientras se teclea. Emite las señales más tarde, al pulsar la tecla Intro, al perder el foco del teclado o al utilizar otras funciones del cuadro giratorio, por ejemplo, al pulsar una tecla de flecha.

Funciones de acceso:

bool keyboardTracking() const
void setKeyboardTracking(bool kt)

readOnly : bool

Esta propiedad determina si el cuadro de selección de valores es de solo lectura.

En modo de solo lectura, el usuario puede seguir copiando el texto al portapapeles o arrastrarlo y soltarlo, pero no puede editarlo.

El cuadro de selección « QLineEdit » del cuadro de diálogo « QAbstractSpinBox » no muestra el cursor en modo de solo lectura.

Funciones de acceso:

bool isReadOnly() const
void setReadOnly(bool r)

Véase también « QLineEdit::readOnly ».

showGroupSeparator : bool

Esta propiedad indica si está activado el separador de miles. Por defecto, esta propiedad tiene el valor «false».

Funciones de acceso:

bool isGroupSeparatorShown() const
void setGroupSeparatorShown(bool shown)

specialValueText : QString

Esta propiedad contiene el texto de valor especial

Si se establece, el cuadro giratorio mostrará este texto en lugar de un valor numérico siempre que el valor actual sea igual a minimum(). Su uso habitual es indicar que esta opción tiene un significado especial (por defecto).

Por ejemplo, si tu cuadro de selección permite al usuario elegir un factor de escala (o nivel de zoom) para mostrar una imagen, y tu aplicación es capaz de elegir automáticamente uno que permita que la imagen quepa por completo en la ventana de visualización, puedes configurar el cuadro de selección de la siguiente manera:

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

De este modo, el usuario podrá elegir una escala del 1 % al 1000 % o seleccionar «Auto» para dejar que sea la aplicación la que elija. A continuación, tu código deberá interpretar el valor 0 del cuadro giratorio como una solicitud del usuario para escalar la imagen de modo que quepa dentro de la ventana.

Todos los valores se muestran con el prefijo y el sufijo (si se han establecido), excepto el valor especial, que solo muestra el texto correspondiente a dicho valor. Este texto especial se pasa a través de la señal « QSpinBox::textChanged()», que transmite un objeto « QString ».

Para desactivar la visualización del texto de valor especial, llama a esta función con una cadena vacía. Por defecto no se muestra ningún texto de valor especial, es decir, el valor numérico se muestra como de costumbre.

Si no se ha establecido ningún texto de valor especial, specialValueText() devuelve una cadena vacía.

Funciones de acceso:

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

[read-only] text : QString

Esta propiedad contiene el texto del cuadro de selección, incluidos cualquier prefijo y sufijo

No hay ningún texto predeterminado.

Funciones de acceso:

QString text() const

wrapping : bool

Esta propiedad determina si el cuadro de selección giratorio es circular.

Si la opción «wrapping» está activada, al aumentar el valor desde «maximum()» se llegará al valor «minimum()» y viceversa. La opción «wrapping» solo tiene sentido si se han establecido los valores «minimum()» y «maximum()».

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

Funciones de acceso:

bool wrapping() const
void setWrapping(bool w)

Véase también QSpinBox::minimum() y QSpinBox::maximum().

Documentación de funciones de miembro

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

Crea un cuadro de selección de espín abstracto con el parent especificado, con las propiedades predeterminadas wrapping y de alineación.

[virtual noexcept] QAbstractSpinBox::~QAbstractSpinBox()

Se llama cuando se destruye el objeto ` QAbstractSpinBox `.

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

Reimplementa: QWidget::changeEvent(QEvent *event).

[virtual slot] void QAbstractSpinBox::clear()

Borra todo el texto de la línea de edición, excepto el prefijo y el sufijo.

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

Reimplementa: ` QWidget::closeEvent(QCloseEvent *event)`.

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

Reimplementa: QWidget::contextMenuEvent(QContextMenuEvent *event).

[signal] void QAbstractSpinBox::editingFinished()

Esta señal se emite cuando finaliza la edición. Esto ocurre cuando el cuadro de selección pierde el foco y cuando se pulsa la tecla «Intro».

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

Reimplementa: ` QWidget::event(QEvent *event)`.

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

La función virtual « QAbstractSpinBox » llama a esta función si el campo « input » no cumple con el formato « QValidator::Acceptable » al pulsar la tecla «Return» o al llamar a « interpretText()». Intentará modificar el texto para que sea válido. Se reimplementa en las distintas subclases.

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

Reimplementa: QWidget::focusInEvent(QFocusEvent *event).

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

Reimplementa: QWidget::focusOutEvent(QFocusEvent *event).

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

Reimplementa: QWidget::hideEvent(QHideEvent *event).

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

Inicializa ` option ` con los valores de esta página: QSpinBox. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionSpinBox`, pero no quieren rellenar toda la información ellas mismas.

Véase también QStyleOption::initFrom().

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

Reimplementa: ` QWidget::inputMethodQuery` (conste `Qt::InputMethodQuery query`).

void QAbstractSpinBox::interpretText()

Esta función interpreta el texto del cuadro de selección. Si el valor ha cambiado desde la última interpretación, emitirá señales.

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

Reimplementa: ` QWidget::keyPressEvent(QKeyEvent *event)`.

Esta función gestiona las entradas del teclado.

Se gestionan específicamente las siguientes teclas:

Intro/RetornoEsto reinterpretará el texto y emitirá una señal incluso si el valor no ha cambiado desde la última vez que se emitió una señal.
ArribaEsto invocará « stepBy » (1)
AbajoEsto invocará ` stepBy` (-1)
Página arribaEsto activará stepBy(10)
Página abajoEsto invocará stepBy(-10)

Véase también stepBy().

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

Reimplementa: ` QWidget::keyReleaseEvent(QKeyEvent *event)`.

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

Esta función devuelve un puntero al campo de edición de la casilla giratoria.

Véase también setLineEdit().

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

Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.

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

Reimplementa: ` QWidget::mouseMoveEvent(QMouseEvent *event)`.

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

Reimplementa: ` QWidget::mousePressEvent(QMouseEvent *event)`.

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

Reimplementa: QWidget::mouseReleaseEvent(QMouseEvent *event).

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

Reimplementa: QWidget::paintEvent(QPaintEvent *event).

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

Reimplementa: QWidget::resizeEvent(QResizeEvent *event).

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

Esta señal se emite cuando se pulsa la tecla «Retorno» o «Intro».

Esta función se introdujo en Qt 6.10.

[slot] void QAbstractSpinBox::selectAll()

Selecciona todo el texto del cuadro de selección, excepto el prefijo y el sufijo.

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

Establece el control de edición de línea del cuadro de selección como « lineEdit » en lugar del control de edición de línea actual. « lineEdit » no puede ser « nullptr ».

QAbstractSpinBox asume la propiedad del nuevo lineEdit

Si QLineEdit::validator() para el lineEdit devuelve nullptr, el validador interno del cuadro giratorio se establecerá en el cuadro de edición de línea.

Véase también lineEdit().

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

Reimplementa: ` QWidget::showEvent` (`QShowEvent *event)`.

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

Reimplementa una función de acceso para la propiedad: QWidget::sizeHint.

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

Función virtual que se invoca cada vez que el usuario activa un paso. El parámetro ` steps ` indica cuántos pasos se han dado. Por ejemplo, al pulsar ` Qt::Key_Down ` se invocará ` stepBy(-1)`, mientras que al pulsar ` Qt::Key_PageUp ` se invocará ` stepBy(10)`.

Si se crea una subclase de ` QAbstractSpinBox `, se debe reimplementar esta función. Tenga en cuenta que esta función se invoca incluso si el valor resultante se encuentra fuera de los límites mínimo y máximo. Es tarea de esta función gestionar estas situaciones.

Véase también stepUp(), stepDown() y keyPressEvent().

[slot] void QAbstractSpinBox::stepDown()

Desciende un paso de línea. Llamar a esta ranura es análogo a llamar a ` stepBy(-1);`;

Véase también stepBy() y stepUp().

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

Función virtual que determina si es válido subir o bajar de nivel en un momento dado.

La flecha hacia arriba se mostrará como desactivada a menos que (stepEnabled() & StepUpEnabled) != 0.

La implementación por defecto devolverá (StepUpEnabled| StepDownEnabled) si el modo de envoltura está activado. En caso contrario, devolverá StepDownEnabled si el valor es mayor que minimum(), o StepUpEnabled si el valor es menor que maximum().

Si creas una subclase de ` QAbstractSpinBox `, tendrás que reimplementar esta función.

Véase también QSpinBox::minimum(), QSpinBox::maximum() y wrapping().

[slot] void QAbstractSpinBox::stepUp()

Aumenta en un paso de línea. Llamar a esta ranura es análogo a llamar a stepBy(1);

Véanse también stepBy() y stepDown().

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

Reimplementa: QObject::timerEvent(QTimerEvent *event).

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

QAbstractSpinBox llama a esta función virtual para determinar si input es válido. El parámetro pos indica la posición en la cadena. Se reimplementa en las distintas subclases.

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

Reimplementa: 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.