En esta página

QSpinBox Class

La clase QSpinBox proporciona un widget de cuadro giratorio. Más información...

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

Propiedades

Funciones públicas

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

Ranuras públicas

void setValue(int val)

Señales

void textChanged(const QString &text)
void valueChanged(int i)

Funciones protegidas

virtual QString textFromValue(int value) const
virtual int valueFromText(const QString &text) const

Funciones protegidas reimplementadas

virtual bool event(QEvent *event) override
virtual void fixup(QString &input) const override
virtual QValidator::State validate(QString &text, int &pos) const override

Descripción detallada

Widget de cuadro giratorio que muestra un número entero

QSpinBox está diseñado para manejar números enteros y conjuntos discretos de valores (por ejemplo, nombres de meses); utiliza QDoubleSpinBox para valores de punto flotante.

QSpinBox permite al usuario seleccionar un valor haciendo clic en los botones de arriba/abajo o pulsando las teclas de arriba/abajo del teclado para aumentar o disminuir el valor que se muestra actualmente. El usuario también puede introducir el valor manualmente. El cuadro giratorio admite valores enteros, pero puede ampliarse para utilizar diferentes cadenas mediante validate(), textFromValue() y valueFromText().

Cada vez que cambia el valor, QSpinBox emite las señales valueChanged() y textChanged(), proporcionando la primera un entero (int) y la segunda un valor de tipo QString. La señal textChanged() proporciona el valor tanto con prefix() como con suffix(). El valor actual se puede obtener con value() y establecer con setValue().

Al hacer clic en los botones de subir/bajar o al utilizar las flechas arriba y abajo del teclado, se incrementará o disminuirá el valor actual en pasos de tamaño singleStep(). Si deseas modificar este comportamiento, puedes reimplementar la función virtual stepBy(). Los valores mínimo y máximo, así como el tamaño del incremento, se pueden establecer mediante uno de los constructores y modificarse posteriormente con setMinimum(), setMaximum() y setSingleStep().

La mayoría de los cuadros giratorios son direccionales, pero QSpinBox también puede funcionar como un cuadro giratorio circular; es decir, si el rango es 0-99 y el valor actual es 99, al hacer clic en «arriba» se obtendrá 0 si se establece wrapping() en true. Utiliza setWrapping() si deseas un comportamiento circular.

El valor mostrado puede ir precedido o seguido de cadenas arbitrarias que indiquen, por ejemplo, la moneda o la unidad de medida. Consulta setPrefix() y setSuffix(). El texto del cuadro giratorio se recupera con text() (que incluye cualquier prefix() y suffix()), o con cleanText() (que no incluye prefix(), ni suffix(), ni espacios en blanco al principio ni al final).

A menudo resulta conveniente ofrecer al usuario una opción especial (normalmente predeterminada) además del rango de valores numéricos. Consulta setSpecialValueText() para saber cómo hacerlo con QSpinBox.

Subclasificación de QSpinBox

Si el uso de prefix(), suffix() y specialValueText() no ofrece suficiente control, se puede crear una subclase de QSpinBox y reimplementar valueFromText() y textFromValue(). Por ejemplo, este es el código para un cuadro giratorio personalizado que permite al usuario introducir tamaños de iconos (p. ej., «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);
}

Véase también QDoubleSpinBox, QDateTimeEdit, QSlider y el ejemplo de cuadros de selección.

Documentación de propiedades

[read-only] cleanText : QString

Esta propiedad contiene el texto del cuadro de selección, sin incluir ningún prefijo, sufijo ni espacios en blanco al principio o al final.

Funciones de acceso:

QString cleanText() const

Véase también text, QSpinBox::prefix y QSpinBox::suffix.

displayIntegerBase : int

Esta propiedad define la base que se utiliza para mostrar el valor del cuadro de selección

El valor predeterminado de «displayIntegerBase» es 10.

Funciones de acceso:

int displayIntegerBase() const
void setDisplayIntegerBase(int base)

Véase también textFromValue() y valueFromText().

maximum : int

Esta propiedad contiene el valor máximo del cuadro de selección

Al configurar esta propiedad, el valor mínimo se ajusta si es necesario, para garantizar que el rango siga siendo válido.

El valor máximo por defecto es 99.

Funciones de acceso:

int maximum() const
void setMaximum(int max)

Véase también setRange() y specialValueText.

minimum : int

Esta propiedad contiene el valor mínimo del cuadro de selección

Al configurar esta propiedad, el valor « maximum » se ajusta si es necesario para garantizar que el rango siga siendo válido.

El valor mínimo por defecto es 0.

Funciones de acceso:

int minimum() const
void setMinimum(int min)

Véase también « setRange()» y « specialValueText ».

prefix : QString

Esta propiedad contiene el prefijo del cuadro de selección

El prefijo se añade al principio del valor mostrado. Se suele utilizar para mostrar una unidad de medida o un símbolo monetario. Por ejemplo:

sb->setPrefix("$");

Para desactivar la visualización del prefijo, establece esta propiedad en una cadena vacía. El valor por defecto es sin prefijo. El prefijo no se muestra cuando value() == minimum() y specialValueText() está activado.

Si no se ha establecido ningún prefijo, prefix() devuelve una cadena vacía.

Funciones de acceso:

QString prefix() const
void setPrefix(const QString &prefix)

Véanse también suffix(), setSuffix(), specialValueText() y setSpecialValueText().

singleStep : int

Esta propiedad contiene el valor del paso

Cuando el usuario utilice las flechas para modificar el valor del cuadro de selección, este se incrementará o disminuirá en la cantidad especificada en singleStep. El valor predeterminado es 1. Establecer un valor de singleStep inferior a 0 no tiene ningún efecto.

Funciones de acceso:

int singleStep() const
void setSingleStep(int val)

stepType : StepType

Esta propiedad indica el tipo de paso.

El tipo de paso puede ser un paso único o un paso decimal adaptativo.

Funciones de acceso:

QAbstractSpinBox::StepType stepType() const
void setStepType(QAbstractSpinBox::StepType stepType)

suffix : QString

Esta propiedad contiene el sufijo del cuadro de selección

El sufijo se añade al final del valor mostrado. Su uso habitual es mostrar una unidad de medida o un símbolo monetario. Por ejemplo:

sb->setSuffix(" km");

Para desactivar la visualización del sufijo, establece esta propiedad en una cadena vacía. El valor por defecto es «sin sufijo». El sufijo no se muestra en el cuadro de selección de valores ( minimum()) si se ha establecido la opción « specialValueText()».

Si no se establece ningún sufijo, suffix() devuelve una cadena vacía.

Funciones de acceso:

QString suffix() const
void setSuffix(const QString &suffix)

Véase también prefix(), setPrefix(), specialValueText() y setSpecialValueText().

value : int

Esta propiedad contiene el valor del cuadro de selección

setValue() emitirá un evento « valueChanged()» si el nuevo valor es diferente del anterior. La propiedad «value» tiene una segunda señal de notificación que incluye el prefijo y el sufijo del cuadro de selección.

Funciones de acceso:

int value() const
void setValue(int val)

Señal de notificación:

void valueChanged(int i)

Documentación de funciones de miembro

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

Crea un cuadro de selección con un valor mínimo de 0 y un valor máximo de 99, con un incremento de 1. El valor inicial es 0. Está vinculado a parent.

Véase también setMinimum(), setMaximum() y setSingleStep().

[virtual noexcept] QSpinBox::~QSpinBox()

Destructor.

[override virtual protected] bool QSpinBox::event(QEvent *event)

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

[override virtual protected] void QSpinBox::fixup(QString &input) const

Reimplementa: ` QAbstractSpinBox::fixup(QString &input) const`.

void QSpinBox::setRange(int minimum, int maximum)

Función práctica para establecer los valores de « minimum » y « maximum » con una sola llamada a la función.

setRange(minimum, maximum);

equivale a:

setMinimum(minimum);
setMaximum(maximum);

Véase también minimum y maximum.

void QSpinBox::setStepType(QAbstractSpinBox::StepType stepType)

Establece el tipo de paso del cuadro de selección en « stepType », que corresponde a un paso único o a un paso decimal adaptativo.

El paso decimal adaptativo significa que el tamaño del paso se ajustará continuamente a una potencia de diez inferior a la value actual. Así, cuando el valor es 1100, el paso se establece en 100, por lo que al aumentar un paso se pasa a 1200. Si el valor es 1200, al aumentar un paso se pasa a 1300. En el caso de los valores negativos, al reducir el paso desde -1100, el valor pasa a -1200.

Se tiene en cuenta la dirección del paso para gestionar los casos límite, de modo que al bajar desde 100 el valor pasa a 99 en lugar de a 90. Así, un paso hacia arriba seguido de uno hacia abajo —o viceversa— siempre vuelve al valor inicial: 99 -> 100 -> 99.

Al configurar esto, el cuadro de selección ignorará el valor de « singleStep », aunque este se conserva para que « singleStep » surta efecto si posteriormente se desactiva el paso decimal adaptativo.

Nota: Funciónde asignación para la propiedad stepType.

Véase también stepType().

[signal] void QSpinBox::textChanged(const QString &text)

Esta señal se emite cada vez que se modifica el texto del cuadro de selección. El nuevo texto se transmite mediante ` text ` con ` prefix()` y ` suffix()`.

[virtual protected] QString QSpinBox::textFromValue(int value) const

El cuadro de selección utiliza esta función virtual cada vez que necesita mostrar el valor dado en value. La implementación por defecto devuelve una cadena que contiene value, mostrada de la forma estándar mediante QWidget::locale().toString(), pero sin el separador de miles, a menos que se haya establecido setGroupSeparatorShown(). Las reimplementaciones pueden devolver cualquier valor. (Véase el ejemplo en la descripción detallada.)

Nota: QSpinBox no llama a esta función para specialValueText() y ni prefix() ni suffix() deben incluirse en el valor de retorno.

Si reimplementas esto, es posible que también tengas que reimplementar valueFromText() y validate()

Véase también valueFromText(), validate() y QLocale::groupSeparator().

[override virtual protected] QValidator::State QSpinBox::validate(QString &text, int &pos) const

Reimplementa: ` QAbstractSpinBox::validate` (`QString &input, int &pos) const`.

[signal] void QSpinBox::valueChanged(int i)

Esta señal se emite cada vez que se modifica el valor del cuadro de selección. El valor entero del nuevo valor se transmite en i.

Nota: Señalde notificación para la propiedad « value ».

[virtual protected] int QSpinBox::valueFromText(const QString &text) const

El cuadro de selección utiliza esta función virtual cada vez que necesita interpretar un valor introducido por el usuario en el cuadro de selecció text.

Las subclases que necesiten mostrar los valores del cuadro de selección de forma no numérica deben reimplementar esta función.

Nota: ` QSpinBox ` gestiona ` specialValueText()` por separado; esta función solo se ocupa de los demás valores.

Véase también textFromValue() y 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.