En esta página

Estilo de contenedores y ventanas

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 widgets de pestañas y las barras de pestañas

QTabBar dibuja sus pestañas mediante el estilo. Una barra de pestañas puede formar parte de un « QTabWidget » o ser independiente. Una barra independiente dibuja su propia línea de base. En un widget de pestañas, el widget dibuja el marco alrededor del panel y la barra se sitúa encima de él.

QTabWidget Dibuja un « PE_FrameTabWidget » con « QStyleOptionTabWidgetFrame ». Pregunta al estilo dónde colocar la barra de pestañas, el panel, el contenido y los widgets de las esquinas mediante « SE_TabWidgetTabPane », « SE_TabWidgetTabContents », « SE_TabWidgetTabBar », « SE_TabWidgetLeftCorner » y « SE_TabWidgetRightCorner », y superpone la barra y el panel mediante « PM_TabBarBaseOverlap ».

QTabBar se encarga de distribuir las pestañas por sí misma, por lo que el estilo no tiene control sobre la ubicación de las mismas. Durante la distribución, la barra solicita un « CT_TabBarTab », que incluye « PM_TabBarTabHSpace » y « PM_TabBarTabVSpace », es decir, el ancho y la altura adicionales alrededor de la etiqueta. A continuación, dibuja cada pestaña con « CE_TabBarTab » y un « QStyleOptionTab ». La pestaña seleccionada se dibuja en último lugar para que un estilo pueda dibujarla sobre las vecinas.

  • PE_FrameTabBarBase (PM_TabBarBaseHeight, PM_TabBarBaseOverlap), para una barra independiente, con un QStyleOptionTabBarBase
  • CE_TabBarTab, una vez por pestaña
    • CE_TabBarTabShape (PM_TabBarTabOverlap)
    • CE_TabBarTabLabel (SE_TabBarTabText, SE_TabBarTabLeftButton, SE_TabBarTabRightButton, PM_TabBarTabShiftHorizontal, PM_TabBarTabShiftVertical, PM_TabBarIconSize)
  • PE_IndicatorTabClose, activadas al hacer clic en el botón de cierre de una pestaña que se puede cerrar (SH_TabBar_CloseButtonPosition, PM_TabCloseIndicatorWidth, PM_TabCloseIndicatorHeight)
  • PE_IndicatorTabTearLeft y PE_IndicatorTabTearRight, donde las pestañas quedan cortadas por los botones de desplazamiento (SE_TabBarTearIndicatorLeft, SE_TabBarTearIndicatorRight)

Los botones de desplazamiento que aparecen cuando las pestañas no caben son tool buttons; el estilo los coloca con SE_TabBarScrollLeftButton y SE_TabBarScrollRightButton y les asigna un tamaño con PM_TabBarScrollButtonWidth. La barra también consulta SH_TabBar_Alignment, SH_TabBar_ElideMode y SH_TabBar_PreferNoArrows.

Widget de pestañas con tres pestañas y un botón en la esquina, con los rectángulos del panel, el contenido, la barra de pestañas, la esquina, la pestaña y la etiqueta de la pestaña resaltados

QTabBar Establece estos indicadores de estado en cada pestaña:

EstadoSe establece cuando
State_SunkenSe pulsa la pestaña.
State_SelectedLa pestaña es la pestaña actual.
State_HasFocusLa barra de pestañas tiene el foco y la pestaña está seleccionada.
State_MouseOverEl ratón se encuentra sobre la pestaña.

Las pestañas individuales se pueden desactivar incluso cuando la barra de pestañas está activada. La pestaña está activa cuando la barra de pestañas está activa. Los miembros de ` QStyleOptionTab ` son:

MiembroDescripción
formaUn valor de ` QTabBar::Shape `: pestañas redondeadas o triangulares, y el lado del widget en el que se encuentra la barra.
textEl texto de la pestaña.
iconoEl icono de la pestaña.
iconSizeEl tamaño del icono.
rowLa fila en la que se encuentra la pestaña. Las barras de pestañas de Qt tienen una sola fila.
positionUn valor de « TabPosition »: la posición de la pestaña respecto a las demás, o « Moving » mientras el usuario la arrastra.
selectedPositionUn valor de « SelectedPosition » que indica si la pestaña seleccionada está junto a esta pestaña y en qué lado.
cornerWidgetsIndicadores de la enumeración « CornerWidget » que indican qué widgets de esquina tiene la barra de pestañas.
documentModeIndica si la barra de pestañas está en modo « document mode ».
leftButtonSize, rightButtonSizeLos tamaños de los botones situados a la izquierda y a la derecha de la pestaña, como el botón de cierre.
featuresIndicadores de la enumeración « TabFeature »: si la pestaña tiene un marco y si utiliza su sugerencia de tamaño mínimo.
tabIndexEl índice de la pestaña en la barra.

Los miembros de ` QStyleOptionTabWidgetFrame ` son:

MiembroDescripción
lineWidthEl ancho de línea para dibujar el panel.
midLineWidthSiempre 0.
shapeLa forma de las pestañas de la barra de pestañas.
tabBarSizeEl tamaño de la barra de pestañas.
tabBarRectEl rectángulo de la barra de pestañas.
selectedTabRectEl rectángulo de la pestaña seleccionada, para que el marco pueda conectarse a ella.
leftCornerWidgetSize, rightCornerWidgetSizeLos tamaños de los widgets de las esquinas, si los hay.

QStyleOptionTabBarBase, utilizado para ` PE_FrameTabBarBase`, tiene los miembros ` shape`, ` tabBarRect`, ` selectedTabRect` y ` documentMode `, todos con el mismo significado.

Los cuadros de grupo

QGroupBox dibuja un control complejo, CC_GroupBox, con un QStyleOptionGroupBox. Calcula su indicación de tamaño a partir de PM_IndicatorWidth, PM_IndicatorHeight y PM_CheckBoxLabelSpacing.

  • CC_GroupBox
    • SC_GroupBoxFrame (PE_FrameGroupBox)
    • SC_GroupBoxLabel, dibujado con drawItemText(), más PE_FrameFocusRect cuando el cuadro tiene el foco
    • SC_GroupBoxCheckBox (PE_IndicatorCheckBox), para una casilla de selección
    • SC_GroupBoxContents, el área para los widgets secundarios

Las sugerencias de estilo SH_GroupBox_TextLabelVerticalAlignment y SH_GroupBox_TextLabelColor controlan el título. Qt no dicta cómo se dibuja la casilla de selección; QCommonStyle utiliza PE_IndicatorCheckBox, por lo que se aplica el árbol de elementos de «Casillas de selección y botones de opción ».

Cuadro de grupo con dos casillas de selección en su interior, en el que se muestran con contorno los subcontroles de marco, casilla de selección, etiqueta y contenido

QGroupBox establece estos indicadores de estado:

EstadoSe establece cuando
State_OnLa casilla de selección está marcada.
State_OffLa casilla de selección está desmarcada. Un cuadro de grupo que no se puede marcar no establece ni State_On ni State_Off.
State_SunkenSe pulsa la casilla de selección o la etiqueta de título.

Los demás miembros de ` QStyleOptionGroupBox ` son:

MiembroDescripción
característicasQStyleOptionFrame::FrameFeatures indicadores que describen el marco, como « Flat » para un cuadro de grupo plano.
lineWidthEl grosor de la línea del marco. Siempre es 1.
midLineWidthSiempre es 0.
textEl título.
textAlignmentLa alineación del título.
textColorEl valor de « SH_GroupBox_TextLabelColor ». El cuadro de grupo solo lo rellena cuando la aplicación no ha establecido un pincel « WindowText » en la paleta; de lo contrario, permanece inválido y « QCommonStyle » utiliza la paleta en su lugar.

Los separadores

QSplitterHandle dibuja un elemento de control, CE_Splitter, con un pincel liso QStyleOption. El divisor ajusta el tamaño de sus tiradores con CT_Splitter y PM_SplitterWidth y solicita SH_Splitter_OpaqueResize para decidir si cambiar el tamaño de los elementos secundarios mientras el usuario arrastra.

Separador con tres paneles de texto y los dos controladores resaltados

El controlador rellena la opción por sí mismo en lugar de llamar a initFrom(). Establece estos indicadores de estado:

EstadoSe establece cuando
State_HorizontalEl divisor es horizontal, por lo que el controlador es vertical.
State_MouseOverEl ratón se encuentra sobre el controlador.
State_SunkenSe pulsa el controlador.
State_EnabledEl controlador está habilitado.

Cajas de herramientas

QToolBox contiene una colección de widgets y muestra uno cada vez, con un botón de pestaña por widget en una disposición vertical. Cada botón dibuja CE_ToolBoxTab con un QStyleOptionToolBox, y los botones utilizan PM_SmallIconSize para sus iconos.

  • CE_ToolBoxTab, una vez por página
    • CE_ToolBoxTabShape
    • CE_ToolBoxTabLabel (SE_ToolBoxTabContents)

Caja de herramientas con tres pestañas y la primera página abierta; las pestañas y la página actual aparecen resaltadas

El botón de pestaña establece estos indicadores de estado:

EstadoSe establece cuando
State_SelectedLa pestaña es la pestaña activa.
State_SunkenSe pulsa la tecla Tab.

Los demás miembros de ` QStyleOptionToolBox ` son:

MiembroDescripción
iconoEl icono de la pestaña.
textoEl texto de la pestaña.
posiciónUn valor de « TabPosition »: la posición de la pestaña con respecto a las demás.
selectedPositionUn valor de « SelectedPosition » que indica si la pestaña seleccionada está junto a esta pestaña y en qué lado.

Barras de herramientas

Las barras de herramientas forman parte del ` main window framework`. Una ventana principal tiene cuatro áreas de barras de herramientas, una a cada lado, y cada área puede contener varias filas de barras de herramientas. ` QMainWindow ` coloca las barras de herramientas y rellena los miembros de posición de su opción de estilo.

QToolBar Dibuja CE_ToolBar con un QStyleOptionToolBar. Cuando la barra de herramientas flota en su propia ventana, también dibuja PE_FrameMenu a su alrededor. Una barra de herramientas móvil dibuja su controlador, y los separadores entre acciones son pequeños widgets que dibujan PE_IndicatorToolBarSeparator.

  • CE_ToolBar (PM_ToolBarFrameWidth, PM_ToolBarItemMargin, PM_ToolBarItemSpacing)
    • PE_PanelToolBar
  • PE_FrameMenu, para una barra de herramientas flotante
  • PE_IndicatorToolBarHandle (SE_ToolBarHandle, PM_ToolBarHandleExtent)
  • PE_IndicatorToolBarSeparator (PM_ToolBarSeparatorExtent), dibujada por cada separador

Los botones de herramientas de la barra se dibujan con CC_ToolButton; véase Botones de herramientas. El tamaño predeterminado de sus iconos es PM_ToolBarIconSize. Cuando las acciones no caben, la barra muestra un botón de extensión con el icono SP_ToolBarHorizontalExtensionButton o SP_ToolBarVerticalExtensionButton, cuyo tamaño viene determinado por PM_ToolBarExtensionExtent.

Barra de herramientas con un controlador, tres botones de herramientas y un separador, con cada elemento resaltado

QToolBar establece este indicador de estado:

EstadoSe establece cuando
State_HorizontalLa barra de herramientas está en posición horizontal, es decir, en la zona superior o inferior de la barra de herramientas.

Los separadores utilizan un « QStyleOption » sin formato con « State_Horizontal » activado cuando la barra de herramientas está en posición horizontal. Los demás miembros de « QStyleOptionToolBar » son:

MiembroDescripción
característicasToolBarFeature indicadores: Movable si la barra de herramientas se puede mover.
lineWidthEl ancho del marco de la barra de herramientas.
midLineWidthSiempre 0.
positionOfLineUn valor de tipo « ToolBarPosition »: la posición de la línea de la barra de herramientas dentro de su área.
positionWithinLineUn valor de tipo « ToolBarPosition »: la posición de la barra de herramientas dentro de su línea.
toolBarAreaEl Qt::ToolBarArea en el que se encuentra la barra de herramientas.

Widgets acoplables

QDockWidget dibuja su barra de título con « CE_DockWidgetTitle » y « QStyleOptionDockWidget », a menos que la aplicación haya instalado un widget de barra de título personalizado o que el widget del dock flote con decoraciones de ventana nativas. Un widget de dock flotante sin decoraciones nativas también dibuja « PE_FrameDockWidget ». Los botones de flotar y cerrar son botones de herramientas que dibujan « PE_PanelButtonTool » y muestran los iconos « SP_TitleBarNormalButton » y « SP_TitleBarCloseButton ».

  • PE_FrameDockWidget (PM_DockWidgetFrameWidth), cuando está flotando
  • CE_DockWidgetTitle (SE_DockWidgetTitleBarText, SE_DockWidgetIcon, PM_DockWidgetTitleMargin)
  • SE_DockWidgetFloatButton y SE_DockWidgetCloseButton (PM_DockWidgetTitleBarButtonMargin), las posiciones de los botones

QMainWindow dibuja los separadores entre los widgets acoplados con PE_IndicatorDockWidgetResizeHandle, cuyo tamaño viene determinado por PM_DockWidgetSeparatorExtent. La sugerencia SH_DockWidget_ButtonsHaveFrame determina si los botones de la barra de título tienen un marco.

Ventana principal con un widget de dock a la derecha, con la barra de título, el texto del título, los botones de flotación y cierre, y el separador resaltado

La opción de la barra de título no establece ningún indicador de estado más allá de los habituales. Los miembros de ` QStyleOptionDockWidget ` son:

MiembroDescripción
titleEl texto del título.
closableIndica si el widget de acoplamiento se puede cerrar.
movibleIndica si el widget acoplado se puede mover a otra zona.
flotanteSi el widget acoplado puede flotar, es decir, separarse de su ventana principal.
verticalTitleBarSi la barra de título se dibuja verticalmente a lo largo del lado izquierdo.

Barras de título

El control complejo de barra de título, CC_TitleBar, dibuja las barras de título de las subventanas en un QMdiArea. Consta de un título de ventana y del menú del sistema, así como de los botones de minimizar, maximizar y cerrar. Algunos estilos también proporcionan botones para oscurecer la ventana y para obtener ayuda contextual.

  • CC_TitleBar (PM_TitleBarHeight, PM_TitleBarButtonSize, PM_TitleBarButtonIconSize)
    • SC_TitleBarSysMenu
    • SC_TitleBarLabel
    • SC_TitleBarMinButton, SC_TitleBarMaxButton, SC_TitleBarCloseButton, SC_TitleBarNormalButton
    • SC_TitleBarShadeButton, SC_TitleBarUnshadeButton, SC_TitleBarContextHelpButton

QCommonStyle dibuja cada botón con PE_PanelButtonTool y el icono estándar correspondiente, desde SP_TitleBarMenuButton hasta SP_TitleBarContextHelpButton. Cuando se maximiza una subventana, QMdiSubWindow desplaza sus botones a la barra de menús de la ventana principal y los dibuja con CC_MdiControls y los subcontroles SC_MdiMinButton, SC_MdiNormalButton y SC_MdiCloseButton.

Barra de título con un icono, el texto «Ventana secundaria» y los botones de minimizar, maximizar y cerrar, con cada subcontrol resaltado

Los miembros de ` QStyleOptionTitleBar ` son:

MiembroDescripción
textEl texto del título.
iconoEl icono de la ventana.
titleBarFlagsQt::WindowFlags que indican qué botones tiene la barra de título.
titleBarStateEl estado de la barra de título ( QWidget::windowState) de la ventana, que determina si se muestra el botón de maximizar o el de restablecer.

Manejos de tamaño

QSizeGrip dibuja un elemento de control, ` CE_SizeGrip`, con un ` QStyleOptionSizeGrip`, y calcula su indicación de tamaño con ` CT_SizeGrip`. ` QStatusBar ` muestra un controlador de tamaño en su esquina de forma predeterminada.

Barra de estado con el mensaje «Listo» y el controlador de tamaño en la esquina resaltado

El controlador de tamaño no establece ningún indicador de estado más allá de los habituales. ` QStyleOptionSizeGrip ` tiene un miembro propio:

MiembroDescripción
cornerUn valor de ` Qt::Corner `: la esquina de la ventana en la que se encuentra el controlador.

Bandas elásticas

QRubberBand dibuja un elemento de control, ` CE_RubberBand`, con una ` QStyleOptionRubberBand`. El estilo puede definir la forma de la banda mediante la indicación de estilo ` SH_RubberBand_Mask `.

Vista de lista con un rectángulo de selección translúcido, similar a una goma elástica, con contorno

La banda no establece indicadores de estado más allá de los habituales. Los miembros de ` QStyleOptionRubberBand ` son:

MiembroDescripción
shapeUn valor de QRubberBand::Shape: un rectángulo o una línea.
opacoIndica si la banda debe dibujarse de forma opaca.

Véase también Referencia de estilos de widgets, Estilo de botones y widgets de entrada, 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.