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

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.