Estilo de botones y widgets de entrada
Esta página forma parte de la Referencia de estilos de widgets. Para obtener una explicación sobre los árboles de elementos, las capturas de pantalla y las tablas, consulta esa página. Los indicadores de estado y los miembros comunes que establece cada widget se enumeran en «Cómo dibuja un estilo un widget».
Los botones
QPushButton dibuja un único elemento de control, CE_PushButton, con un QStyleOptionButton. QCommonStyle lo divide en el bisel, la etiqueta y el marco de foco:
CE_PushButtonCE_PushButtonBevel(PM_ButtonDefaultIndicator,PM_MenuButtonIndicator)PE_FrameDefaultButton, para el botón predeterminadoPE_PanelButtonCommandPE_IndicatorArrowDown, para un botón con menú
CE_PushButtonLabel(SE_PushButtonContents,PM_ButtonShiftHorizontal,PM_ButtonShiftVertical,PM_ButtonIconSize)PE_FrameFocusRect(SE_PushButtonFocusRect)
El botón calcula su indicación de tamaño con CT_PushButton y PM_ButtonMargin. Los límites del elemento varían según el estilo. En QCommonStyle, PE_FrameDefaultButton obtiene todo el rectángulo biselado, al igual que PE_PanelButtonCommand, excepto en un botón con valor predeterminado automático, donde el panel se reduce en PM_ButtonDefaultIndicator a cada lado.

QPushButton establece estos indicadores de estado:
| Estado | Se establece cuando |
|---|---|
State_Sunken | Se pulsa el botón o se muestra su menú. |
State_On | El botón está marcado. |
State_Raised | El botón no está plano ni pulsado. |
Los demás miembros de « QStyleOptionButton » son:
| Miembro | Descripción |
|---|---|
| características | Indicadores de la enumeración « QStyleOptionButton::ButtonFeature » que describen el botón: plano, predeterminado, predeterminado automático, con menú o botón de enlace de comando. |
| icono | El QIcon del botón, si lo hay. |
| iconSize | El tamaño del icono. |
| text | El texto del botón. |
Las casillas de selección y los botones de opción
QCheckBox y QRadioButton tienen estructuras idénticas. Ambos utilizan QStyleOptionButton y dibujan un elemento de control, CE_CheckBox o CE_RadioButton. QCommonStyle dibuja el indicador, la etiqueta y el marco de foco:
CE_CheckBoxPE_IndicatorCheckBox(SE_CheckBoxIndicator,PM_IndicatorWidth,PM_IndicatorHeight)CE_CheckBoxLabel(SE_CheckBoxContents,PM_CheckBoxLabelSpacing)PE_FrameFocusRect(SE_CheckBoxFocusRect)
CE_RadioButtonPE_IndicatorRadioButton(SE_RadioButtonIndicator,PM_ExclusiveIndicatorWidth,PM_ExclusiveIndicatorHeight)CE_RadioButtonLabel(SE_RadioButtonContents,PM_RadioButtonLabelSpacing)PE_FrameFocusRect(SE_RadioButtonFocusRect)
Las sugerencias de tamaño utilizan CT_CheckBox y CT_RadioButton. «Estilización de una casilla de selección: un tutorial» describe el proceso de dibujo de una casilla de selección a través del código del widget y de QCommonStyle.

Los botones establecen estos indicadores de estado:
| Estado | Se establece cuando |
|---|---|
State_Sunken | Se pulsa el botón. El área en la que se puede hacer clic es SE_CheckBoxClickRect o SE_RadioButtonClickRect, que en QCommonStyle abarca tanto la etiqueta como el indicador. |
State_NoChange | La casilla de selección está parcialmente marcada (una casilla de selección de tres estados). |
State_On | El botón está marcado. |
State_Off | El botón está desmarcado. |
Los demás elementos de QStyleOptionButton se enumeran en «Botones pulsadores».
Botones de herramientas
QToolButton dibuja un control complejo, « CC_ToolButton », con un « QStyleOptionToolButton ». Tiene dos subcontroles: el propio botón y, en el caso de un botón con « a menu button », el indicador de menú.
CC_ToolButtonSC_ToolButtonPE_PanelButtonTool(PM_DefaultFrameWidth)PE_FrameFocusRectCE_ToolButtonLabel(PM_ButtonShiftHorizontal,PM_ButtonShiftVertical)
SC_ToolButtonMenu(PM_MenuButtonIndicator)PE_IndicatorButtonDropDownPE_IndicatorArrowDown
En el caso de las ventanas emergentes de instant y delayed no hay ningún subcontrol de menú, por lo que QCommonStyle dibuja en su lugar PE_IndicatorArrowDown en la esquina del rectángulo del botón. La indicación de tamaño utiliza CT_ToolButton, y el botón consulta SH_ToolButton_PopupDelay y SH_ToolButtonStyle. Los botones de herramientas de una barra de herramientas toman el tamaño de su icono de la propia barra de herramientas. Los botones independientes utilizan PM_ButtonIconSize.

QToolButton establece estos indicadores de estado:
| Estado | Se establece cuando |
|---|---|
State_AutoRaise | Se establece la propiedad « autoRaise ». |
State_Raised | El botón no está marcado ni pulsado. A continuación, « QCommonStyle » desactiva de nuevo el indicador si se establece « State_AutoRaise » y el ratón no se encuentra sobre el botón. |
State_Sunken | Se pulsa el botón o se muestra su menú. |
State_On | El botón es marcable y está marcado. |
Los demás miembros de ` QStyleOptionToolButton ` son:
| Miembro | Descripción |
|---|---|
| arrowType | Un valor de « Qt::ArrowType » que indica la dirección de la flecha dibujada en lugar de un icono, si lo hay. |
| features | Indicadores de la enumeración « QStyleOptionToolButton::ToolButtonFeature »: si el botón muestra una flecha, tiene un botón de menú o presenta una ventana emergente con retardo. |
| font | La fuente ( QFont ) de la etiqueta del botón. |
| icono | El tipo de fuente « QIcon » del botón. |
| iconSize | El tamaño del icono. |
| pos | La posición del botón, tal y como la devuelve la función ` QWidget::pos()`. |
| text | El texto del botón. |
| toolButtonStyle | Un valor de ` Qt::ToolButtonStyle ` que determina si el botón muestra el icono, el texto o ambos. |
Cuadros combinados
QComboBox dibuja el botón y la etiqueta con ` CC_ComboBox ` y ` CE_ComboBoxLabel`, ambos con un ` QStyleOptionComboBox`. ` QCommonStyle ` omite el texto de la etiqueta en el caso de un cuadro editable, donde lo dibuja el elemento secundario ` QLineEdit `. La lista emergente es una vista de elemento dibujada por un delegado, pero el estilo controla su tamaño y posición mediante SC_ComboBoxListBoxPopup. En el caso de un cuadro editable, el estilo decide dónde se coloca el campo de edición mediante SC_ComboBoxEditField; el propio campo es un elemento secundario de tipo QLineEdit.
CC_ComboBox(PM_ComboBoxFrameWidth)SC_ComboBoxFrameSC_ComboBoxArrow(PE_IndicatorArrowDown)SC_ComboBoxEditFieldSC_ComboBoxListBoxPopup, para posicionar la ventana emergente
CE_ComboBoxLabel(SC_ComboBoxEditField)
La indicación de tamaño utiliza CT_ComboBox. Las indicaciones de estilo, como SH_ComboBox_Popup, SH_ComboBox_PopupFrameStyle y SH_ComboBox_UseNativePopup, determinan el aspecto y el comportamiento de la ventana emergente.

QComboBox establece estos indicadores de estado:
| Estado | Se establece cuando |
|---|---|
State_Selected | El cuadro no es editable y tiene el foco. |
State_Sunken | SC_ComboBoxArrow está activa. |
State_On | La lista desplegable está visible. |
Los demás miembros de « QStyleOptionComboBox » son:
| Miembro | Descripción |
|---|---|
| currentIcon | El icono del elemento actual. |
| currentText | El texto del elemento actual. |
| editable | Indica si el cuadro combinado es editable. |
| frame | Indica si el cuadro combinado tiene un marco. |
| tamaño del icono | El tamaño del icono del elemento actual. |
| popupRect | El rectángulo delimitador de la lista emergente. |
| textAlignment | La alineación del texto en la etiqueta. |
Cuadros de selección
QSpinBox, « QDoubleSpinBox » y « QDateTimeEdit » dibujan « CC_SpinBox » con un « QStyleOptionSpinBox ». El campo de edición es un elemento secundario de « QLineEdit », cuya geometría devuelve el estilo para « SC_SpinBoxEditField ».
CC_SpinBox(PM_SpinBoxFrameWidth)SC_SpinBoxFrameSC_SpinBoxUpPE_PanelButtonBevelPE_IndicatorSpinUpoPE_IndicatorSpinPlus, dependiendo de buttonSymbols
SC_SpinBoxDownPE_PanelButtonBevelPE_IndicatorSpinDownoPE_IndicatorSpinMinus
SC_SpinBoxEditField
Un estilo no tiene por qué dibujar los paneles del botón con PE_PanelButtonBevel. La sugerencia de tamaño utiliza CT_SpinBox, y el widget consulta sugerencias como SH_SpinBox_ButtonsInsideFrame, SH_SpinBox_StepModifier y SH_SpinControls_DisableOnBounds.

El cuadro de selección establece este indicador de estado:
| Estado | Se establece cuando |
|---|---|
State_Sunken | Se pulsa el subcontrol « SC_SpinBoxUp » o « SC_SpinBoxDown ». |
Los demás elementos de QStyleOptionSpinBox son:
| Miembro | Descripción |
|---|---|
| frame | Indica si el cuadro de selección muestra un marco. |
| buttonSymbols | Un valor de tipo « QAbstractSpinBox::ButtonSymbols » que selecciona los símbolos de los botones: flechas, signo más y signo menos, o ninguno. |
| stepEnabled | QAbstractSpinBox::StepEnabled Indicadores que señalan cuáles de los botones pueden modificar el valor paso a paso. Un botón que no permite modificar el valor paso a paso se muestra desactivado. |
Control deslizante
QSlider Dibuja un ` CC_Slider ` con un ` QStyleOptionSlider`. Calcula su indicación de tamaño a partir de ` PM_SliderThickness ` y ` CT_Slider`, y su indicación de tamaño mínimo a partir de ` PM_SliderLength`.
CC_Slider(PM_SliderLength,PM_SliderControlThickness,PM_SliderTickmarkOffset,PM_SliderSpaceAvailable)SC_SliderGrooveSC_SliderHandleSC_SliderTickmarks
QCommonStyle solo dibuja las marcas de graduación; la ranura y el controlador siempre dependen del estilo. Los estilos no tienen por qué devolver un rectángulo para SC_SliderTickmarks. Fusion devuelve uno vacío y dibuja las marcas de graduación debajo del controlador, en el área que se muestra en la captura de pantalla. El widget consulta SH_Slider_AbsoluteSetButtons, SH_Slider_PageSetButtons y SH_Slider_SnapToValue.

QDial utiliza la misma opción y dibuja CC_Dial con los subcontroles SC_DialGroove, SC_DialHandle y SC_DialTickmarks.
QSlider establece estos indicadores de estado:
| Estado | Se establece cuando |
|---|---|
State_Horizontal | El control deslizante está en posición horizontal. |
State_Sunken | Se pulsa cualquier subcontrol, incluida la ranura. activeSubControls indica cuál. |
QStyleOptionSlider Sirve a todos los « QAbstractSlider». Sus miembros son:
| Miembro | Descripción |
|---|---|
| orientation | Un valor de « Qt::Orientation »: vertical u horizontal. |
| mínimo | El valor mínimo. |
| máximo | El valor máximo. |
| tickPosition | Un valor de « QSlider::TickPosition » que indica dónde se dibujan las marcas de graduación. |
| tickInterval | La distancia entre las marcas de graduación, expresada en valores del control deslizante. |
| upsideDown | La dirección en la que aumenta el valor. Todos los controles deslizantes abstractos utilizan este miembro en lugar de ` QStyleOption::direction`. |
| sliderPosition | La posición del controlador, expresada como valor del control deslizante. Es igual a ` sliderValue ` mientras ` tracking ` está activado; en caso contrario, el valor solo se actualiza cuando se suelta el controlador. |
| sliderValue | El valor actual. |
| singleStep | La cantidad en que cambia el valor en un solo paso, como al pulsar una tecla de flecha. |
| pageStep | La cantidad en que cambia el valor en un paso de página, como al hacer clic en la ranura. |
| notchTarget | La distancia preferida entre muescas, en píxeles. Utilizada por QDial. |
| dialWrapping | Indica si el dial se envuelve. Utilizado por QDial. |
| keyboardModifiers | Las teclas modificadoras que se mantuvieron pulsadas durante el último evento del ratón, para estilos en los que los modificadores cambian el comportamiento del arrastre. |
Barras de desplazamiento
QScrollBar Dibuja CC_ScrollBar con un QStyleOptionSlider. Mientras el usuario arrastra el control deslizante, la barra devuelve el valor a su posición original si el puntero se desplaza más allá de PM_MaximumDragDistance fuera de la barra.
CC_ScrollBar(PM_ScrollBarExtent,PM_ScrollBarSliderMin)SC_ScrollBarGrooveSC_ScrollBarSubLine(CE_ScrollBarSubLine)SC_ScrollBarAddLine(CE_ScrollBarAddLine)SC_ScrollBarSubPage(CE_ScrollBarSubPage)SC_ScrollBarAddPage(CE_ScrollBarAddPage)SC_ScrollBarFirst(CE_ScrollBarFirst)SC_ScrollBarLast(CE_ScrollBarLast)SC_ScrollBarSlider(CE_ScrollBarSlider)PE_FrameFocusRect
QCommonStyle dibuja cada subcontrol con el elemento de control del mismo nombre. Algunos estilos dibujan los indicadores de línea con PE_IndicatorArrowUp y las demás primitivas de flecha, y las áreas de página con PE_PanelButtonBevel; esto depende de cada estilo concreto. SC_ScrollBarFirst y SC_ScrollBarLast son botones opcionales que permiten saltar a los extremos; la mayoría de los estilos devuelven un rectángulo vacío para ellos. La sugerencia de tamaño utiliza CT_ScrollBar, y las sugerencias de comportamiento incluyen SH_ScrollBar_LeftClickAbsolutePosition, SH_ScrollBar_ContextMenu y SH_ScrollBar_Transient.

QScrollBar establece estos indicadores de estado:
| Estado | Se establece cuando |
|---|---|
State_Horizontal | La barra de desplazamiento es horizontal. |
State_Sunken | Se ha pulsado un subcontrol y el puntero no lo ha abandonado. |
State_On | La barra es una barra de desplazamiento transitoria que se muestra actualmente. |
Los miembros de ` QStyleOptionSlider ` se enumeran en la sección «Controladores deslizantes». ` sliderPosition`, ` sliderValue`, ` pageStep` y ` upsideDown ` determinan el tamaño y la posición del controlador.
Barras de progreso
QProgressBar dibuja un elemento de control, CE_ProgressBar, con un QStyleOptionProgressBar. QCommonStyle lo divide en la ranura, el contenido y la etiqueta:
CE_ProgressBarCE_ProgressBarGroove(SE_ProgressBarGroove)CE_ProgressBarContents(SE_ProgressBarContents,PM_ProgressBarChunkWidth)CE_ProgressBarLabel(SE_ProgressBarLabel)
Los estilos que dibujan el contenido como una fila de fragmentos utilizan PE_IndicatorProgressChunk. En QCommonStyle y Fusion, el espacio, el contenido y la etiqueta ocupan toda la barra; la etiqueta es texto centrado que se dibuja sobre el contenido, por lo que su rectángulo no es un área separada. La sugerencia de tamaño utiliza CT_ProgressBar. Un indicador de actividad, una barra cuyos valores mínimo y máximo son ambos cero, se anima mediante el estilo.

QProgressBar establece este indicador de estado:
| Estado | Se establece cuando |
|---|---|
State_Horizontal | La barra es horizontal. |
Los demás miembros de « QStyleOptionProgressBar » son:
| Miembro | Descripción |
|---|---|
| mínimo | El valor mínimo. |
| máximo | El valor máximo. |
| progreso | El valor actual. |
| texto | El texto de la etiqueta. |
| textAlignment | La alineación del texto en la etiqueta. |
| textVisible | Si se muestra la etiqueta. |
| invertedAppearance | Indica si la barra se rellena desde el extremo opuesto; por ejemplo, de derecha a izquierda en una barra horizontal. |
| de abajo hacia arriba | Si la etiqueta de una barra vertical se gira para que se lea de abajo hacia arriba. |
Véase también Referencia de estilos de widgets, Estilo de contenedores y ventanas, y Estilo de menús y vistas de elementos.
© 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.