En esta página

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_PushButton
    • CE_PushButtonBevel (PM_ButtonDefaultIndicator, PM_MenuButtonIndicator)
      • PE_FrameDefaultButton, para el botón predeterminado
      • PE_PanelButtonCommand
      • PE_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.

Dos botones con el bisel, la etiqueta y el rectángulo de enfoque resaltados

QPushButton establece estos indicadores de estado:

EstadoSe establece cuando
State_SunkenSe pulsa el botón o se muestra su menú.
State_OnEl botón está marcado.
State_RaisedEl botón no está plano ni pulsado.

Los demás miembros de « QStyleOptionButton » son:

MiembroDescripción
característicasIndicadores 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.
iconoEl QIcon del botón, si lo hay.
iconSizeEl tamaño del icono.
textEl 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_CheckBox
    • PE_IndicatorCheckBox (SE_CheckBoxIndicator, PM_IndicatorWidth, PM_IndicatorHeight)
    • CE_CheckBoxLabel (SE_CheckBoxContents, PM_CheckBoxLabelSpacing)
    • PE_FrameFocusRect (SE_CheckBoxFocusRect)
  • CE_RadioButton
    • PE_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.

Casilla de selección y botón de opción con el indicador, la etiqueta y el rectángulo de selección resaltados

Los botones establecen estos indicadores de estado:

EstadoSe establece cuando
State_SunkenSe 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_NoChangeLa casilla de selección está parcialmente marcada (una casilla de selección de tres estados).
State_OnEl botón está marcado.
State_OffEl 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_ToolButton
    • SC_ToolButton
      • PE_PanelButtonTool (PM_DefaultFrameWidth)
      • PE_FrameFocusRect
      • CE_ToolButtonLabel (PM_ButtonShiftHorizontal, PM_ButtonShiftVertical)
    • SC_ToolButtonMenu (PM_MenuButtonIndicator)
      • PE_IndicatorButtonDropDown
      • PE_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.

Botón de herramienta con un icono, texto y un indicador de menú, con el botón y el subcontrol del menú resaltados

QToolButton establece estos indicadores de estado:

EstadoSe establece cuando
State_AutoRaiseSe establece la propiedad « autoRaise ».
State_RaisedEl 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_SunkenSe pulsa el botón o se muestra su menú.
State_OnEl botón es marcable y está marcado.

Los demás miembros de ` QStyleOptionToolButton ` son:

MiembroDescripción
arrowTypeUn valor de « Qt::ArrowType » que indica la dirección de la flecha dibujada en lugar de un icono, si lo hay.
featuresIndicadores 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.
fontLa fuente ( QFont ) de la etiqueta del botón.
iconoEl tipo de fuente « QIcon » del botón.
iconSizeEl tamaño del icono.
posLa posición del botón, tal y como la devuelve la función ` QWidget::pos()`.
textEl texto del botón.
toolButtonStyleUn 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_ComboBoxFrame
    • SC_ComboBoxArrow (PE_IndicatorArrowDown)
    • SC_ComboBoxEditField
    • SC_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.

Cuadro combinado con el marco, el campo de edición y los subcontroles de flecha resaltados

QComboBox establece estos indicadores de estado:

EstadoSe establece cuando
State_SelectedEl cuadro no es editable y tiene el foco.
State_SunkenSC_ComboBoxArrow está activa.
State_OnLa lista desplegable está visible.

Los demás miembros de « QStyleOptionComboBox » son:

MiembroDescripción
currentIconEl icono del elemento actual.
currentTextEl texto del elemento actual.
editableIndica si el cuadro combinado es editable.
frameIndica si el cuadro combinado tiene un marco.
tamaño del iconoEl tamaño del icono del elemento actual.
popupRectEl rectángulo delimitador de la lista emergente.
textAlignmentLa 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_SpinBoxFrame
    • SC_SpinBoxUp
      • PE_PanelButtonBevel
      • PE_IndicatorSpinUp o PE_IndicatorSpinPlus, dependiendo de buttonSymbols
    • SC_SpinBoxDown
      • PE_PanelButtonBevel
      • PE_IndicatorSpinDown o PE_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.

Cuadro de selección con el marco, el campo de edición y los subcontroles «botón arriba» y «botón abajo» resaltados

El cuadro de selección establece este indicador de estado:

EstadoSe establece cuando
State_SunkenSe pulsa el subcontrol « SC_SpinBoxUp » o « SC_SpinBoxDown ».

Los demás elementos de QStyleOptionSpinBox son:

MiembroDescripción
frameIndica si el cuadro de selección muestra un marco.
buttonSymbolsUn valor de tipo « QAbstractSpinBox::ButtonSymbols » que selecciona los símbolos de los botones: flechas, signo más y signo menos, o ninguno.
stepEnabledQAbstractSpinBox::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_SliderGroove
    • SC_SliderHandle
    • SC_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.

Control deslizante horizontal con marcas de graduación, en el que se muestran con contorno los subcontroles de la ranura, el tirador y las marcas de graduación

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:

EstadoSe establece cuando
State_HorizontalEl control deslizante está en posición horizontal.
State_SunkenSe pulsa cualquier subcontrol, incluida la ranura. activeSubControls indica cuál.

QStyleOptionSlider Sirve a todos los « QAbstractSlider». Sus miembros son:

MiembroDescripción
orientationUn valor de « Qt::Orientation »: vertical u horizontal.
mínimoEl valor mínimo.
máximoEl valor máximo.
tickPositionUn valor de « QSlider::TickPosition » que indica dónde se dibujan las marcas de graduación.
tickIntervalLa distancia entre las marcas de graduación, expresada en valores del control deslizante.
upsideDownLa dirección en la que aumenta el valor. Todos los controles deslizantes abstractos utilizan este miembro en lugar de ` QStyleOption::direction`.
sliderPositionLa 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.
sliderValueEl valor actual.
singleStepLa cantidad en que cambia el valor en un solo paso, como al pulsar una tecla de flecha.
pageStepLa cantidad en que cambia el valor en un paso de página, como al hacer clic en la ranura.
notchTargetLa distancia preferida entre muescas, en píxeles. Utilizada por QDial.
dialWrappingIndica si el dial se envuelve. Utilizado por QDial.
keyboardModifiersLas 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_ScrollBarGroove
    • SC_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.

Barra de desplazamiento horizontal con la ranura, los botones de línea, las áreas de página y los subcontroles deslizantes resaltados

QScrollBar establece estos indicadores de estado:

EstadoSe establece cuando
State_HorizontalLa barra de desplazamiento es horizontal.
State_SunkenSe ha pulsado un subcontrol y el puntero no lo ha abandonado.
State_OnLa 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_ProgressBar
    • CE_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.

Barra de progreso al 40 %, con el surco, el contenido y la etiqueta esbozados

QProgressBar establece este indicador de estado:

EstadoSe establece cuando
State_HorizontalLa barra es horizontal.

Los demás miembros de « QStyleOptionProgressBar » son:

MiembroDescripción
mínimoEl valor mínimo.
máximoEl valor máximo.
progresoEl valor actual.
textoEl texto de la etiqueta.
textAlignmentLa alineación del texto en la etiqueta.
textVisibleSi se muestra la etiqueta.
invertedAppearanceIndica si la barra se rellena desde el extremo opuesto; por ejemplo, de derecha a izquierda en una barra horizontal.
de abajo hacia arribaSi 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.