Cómo dibuja un estilo un widget
La API de QStyle cuenta con tres tipos de funciones: funciones que dibujan los widgets, ayudantes estáticos para tareas comunes y complejas —como calcular la posición del control deslizante— y funciones para los cálculos que los widgets necesitan durante el dibujo, por ejemplo, para calcular sus indicaciones de tamaño. El estilo también ayuda a algunos widgets a distribuir su contenido y puede ajustar el « QPalette » con el que se dibujan los widgets.
Esta página describe los componentes básicos con los que trabaja una implementación de estilos. La Referencia de estilos de widgets enumera cuáles de ellos utiliza cada widget.
Elementos de estilo
QStyle dibuja elementos gráficos. Un elemento es un widget o una parte de un widget, como el bisel de un botón pulsador, el marco de una ventana o una barra de desplazamiento. La mayoría de las funciones de dibujo admiten cuatro argumentos:
- Un valor de enumeración que especifica qué elemento gráfico se va a dibujar.
- Un objeto « QStyleOption » que especifica cómo y dónde renderizar ese elemento.
- Un ` QPainter ` con el que dibujar el elemento.
- El « QWidget » sobre el que se realiza el dibujo. Este argumento es opcional.
Cuando un widget solicita a un estilo que dibuje un elemento, le proporciona un « QStyleOption », una clase que contiene la información necesaria para el dibujo. Dado que la opción contiene todo lo que el estilo necesita, este puede dibujar widgets sin necesidad de vincular ningún código de widget. Se puede dibujar un cuadro combinado en cualquier dispositivo de pintura, no solo en un « QComboBox ».
El widget se pasa como último argumento por si el estilo lo necesita para efectos especiales, como los botones predeterminados animados en macOS, pero el estilo no puede contar con ello. Los widgets que dibujan varios elementos por sí mismos se pasan a sí mismos, al igual que ` QStylePainter`. El código que dibuja directamente en un dispositivo de pintura puede pasar ` nullptr`.
Un widget consta de una jerarquía, o árbol, de elementos de estilo. Por ejemplo, cuando un estilo recibe una solicitud para dibujar un botón pulsador, dibuja una etiqueta (texto e icono), un bisel de botón y un marco de foco. El bisel del botón, a su vez, consta de un marco alrededor del bisel y del panel. El siguiente árbol conceptual muestra los elementos del botón pulsador en orden de dibujo, con los elementos anidados dibujados por el elemento situado encima de ellos:
- Botón
- Bisel del botón
- Marco predeterminado del botón
- Panel del botón
- Etiqueta (icono y texto)
- Marco de foco
- Bisel del botón
Los botones de la referencia muestran el árbol real de QPushButton, con los nombres de los elementos.
Los widgets no solicitan necesariamente al estilo que dibuje un solo elemento. Un widget puede realizar varias llamadas al estilo para dibujar diferentes elementos. Un ejemplo es QTabWidget, que dibuja sus pestañas y su marco de forma individual.
Existen tres tipos de elementos: elementos primitivos, elementos de control y elementos de control complejos. Las enumeraciones ` PrimitiveElement`, ` ControlElement` y ` ComplexControl ` los definen. Los valores de cada enumeración tienen un prefijo que identifica su tipo: ` PE_ ` para elementos primitivos, ` CE_ ` para elementos de control y ` CC_ ` para elementos de control complejos. La documentación de la clase ` QStyle ` enumera estos elementos y sus funciones en el estilo de los widgets.
Elementos primitivos
Los elementos primitivos son elementos de la interfaz gráfica de usuario (GUI) que son comunes y suelen utilizarse en varios widgets. Algunos ejemplos son los marcos, los biseles de los botones y las flechas de los cuadros de selección, las barras de desplazamiento y los cuadros combinados. Los elementos primitivos no pueden existir por sí solos; siempre forman parte de una estructura más amplia. No participan en la interacción con el usuario, sino que son elementos decorativos pasivos de la interfaz gráfica de usuario.
Elementos de control
Un elemento de control realiza una acción o muestra información al usuario. Ejemplos de elementos de control son los botones, las casillas de selección y las secciones de encabezado en tablas y vistas de árbol. Un elemento de control no siempre es un widget completo, como un botón pulsador; también puede ser una parte de un widget, como una pestaña de una barra de pestañas o el control deslizante de una barra de desplazamiento. Los elementos de control se diferencian de los elementos primitivos en que no son pasivos: participan en la interacción con el usuario.
Los controles que constan de varios elementos suelen utilizar el estilo para calcular los rectángulos delimitadores de los elementos. La enumeración « SubElement » define los subelementos disponibles. Esta enumeración solo se utiliza para calcular rectángulos delimitadores. Los subelementos no son elementos gráficos que deban dibujarse como los elementos primitivos, de control y complejos.
Elementos de control complejos
Los elementos de control complejos contienen subcontroles. Los controles complejos se comportan de forma diferente según el lugar en el que el usuario los maneje con el ratón y las teclas del teclado que se pulsen. Esto depende de sobre qué subcontrol, si lo hay, se sitúe el cursor del ratón o se pulse. Algunos ejemplos de controles complejos son las barras de desplazamiento y los cuadros combinados. En una barra de desplazamiento, se puede utilizar el ratón para mover el control deslizante y pulsar los botones de subir y bajar. La enumeración « SubControl » define los subcontroles disponibles.
Además de dibujar, el estilo indica a los widgets qué subcontrol, si lo hay, ha pulsado el usuario. Por ejemplo, un ` QScrollBar ` necesita saber si el usuario ha pulsado el control deslizante, la ranura del control deslizante o uno de los botones.
Los subcontroles no son lo mismo que los elementos de control. No se puede utilizar el estilo para dibujar un subcontrol; el estilo solo calcula el rectángulo delimitador en el que debe dibujarse el subcontrol. Sin embargo, es habitual que los elementos complejos utilicen elementos de control y primitivos para dibujar sus subcontroles. Los estilos integrados de Qt lo hacen con frecuencia. Por ejemplo, QCommonStyle utiliza PE_IndicatorCheckBox para dibujar la casilla de selección en los cuadros de grupo, que es un subcontrol de CC_GroupBox. Algunos subcontroles tienen un elemento de control equivalente; por ejemplo, el control deslizante de la barra de desplazamiento (SC_ScrollBarSlider y CE_ScrollBarSlider).
Subelementos, subcontroles y métricas de píxeles
Los elementos de estilo y los widgets utilizan el estilo para calcular los rectángulos delimitadores de los subelementos y subcontroles. Las métricas de píxeles, que son tamaños dependientes del estilo expresados en píxeles de pantalla, también se utilizan para las mediciones al dibujar. Tres enumeraciones de QStyle representan los rectángulos y métricas de píxeles disponibles: SubElement, SubControl y PixelMetric. Sus valores comienzan por SE_, SC_ y PM_.
Sugerencias de estilo
El estilo también responde a un conjunto de sugerencias de estilo, representadas por los valores de la enumeración « StyleHint ». No todos los widgets tienen la misma funcionalidad ni el mismo aspecto en los distintos estilos. Por ejemplo, cuando los elementos de un menú no caben en una sola columna en la pantalla, algunos estilos admiten el desplazamiento, mientras que otros dibujan más de una columna para que quepan todos los elementos. Los widgets consultan las sugerencias mediante styleHint().
Iconos estándar
Un estilo suele tener un conjunto de iconos estándar, como imágenes de advertencia, pregunta y error, para cuadros de mensaje, cuadros de diálogo de archivos y botones de la barra de título. La enumeración ` StandardPixmap ` los nombra, y ` standardIcon()` devuelve el ` QIcon ` correspondiente a un valor. Los widgets de Qt utilizan estos iconos, por lo que, al implementar un estilo, debes proporcionarlos.
Espaciado en los diseños
El estilo calcula el espaciado entre los widgets en los diseños. Hay dos formas de gestionar estos cálculos. Puedes obtener el espaciado mediante ` pixelMetric()` para ` PM_LayoutHorizontalSpacing ` y ` PM_LayoutVerticalSpacing`, tal y como hace ` QCommonStyle `. Como alternativa, puedes reimplementar ` layoutSpacing()` si necesitas un mayor control. En esa función, puedes calcular el espaciado basándote en los tipos de control (`QSizePolicy::ControlType`) de los dos widgets adyacentes, sus políticas de tamaño (`QSizePolicy::Policy`) y la opción de estilo del widget en cuestión.
Opciones de estilo
Las subclases de QStyleOption contienen toda la información necesaria para aplicar estilos a los elementos individuales. Quien invoca la función QStyle crea una instancia de una opción de estilo, normalmente en la pila, y la rellena. Dependiendo de lo que se dibuje, el estilo espera una clase de opción de estilo diferente. Por ejemplo, el elemento PE_FrameFocusRect espera un argumento de tipo QStyleOptionFocusRect. También puedes crear tus propias subclases para utilizar un estilo personalizado. Las opciones de estilo mantienen variables públicas por motivos de rendimiento.
Los widgets pueden encontrarse en varios estados diferentes, definidos por la enumeración State. Algunas de las banderas de estado tienen significados distintos según el widget, pero otras son comunes a todos los widgets, como State_Enabled. QStyleOption::initFrom() establece los estados comunes; los widgets individuales establecen el resto.
Cabe destacar que las opciones de estilo contienen la paleta y el rectángulo delimitador del widget que se va a dibujar. La mayoría de los widgets tienen opciones de estilo especializadas. QPushButton y QCheckBox, por ejemplo, utilizan QStyleOptionButton, que contiene el texto, el icono y el tamaño del icono. La Referencia de estilos de widgets describe el contenido exacto de cada opción.
Al reimplementar funciones de ` QStyle ` que admiten un parámetro ` QStyleOption `, a menudo es necesario convertir la opción a una subclase, como ` QStyleOptionFocusRect`. Utilice ` qstyleoption_cast()` para asegurarse de que el tipo del puntero es correcto. Si el objeto no es del tipo adecuado, ` qstyleoption_cast()` devuelve ` nullptr`:
const QStyleOptionFocusRect *focusRectOption =
qstyleoption_cast<const QStyleOptionFocusRect *>(option);
if (focusRectOption) {
//...
}Indicadores de estado y miembros comunes
Algunos estados y variables son comunes a todos los widgets. Los widgets los establecen mediante QStyleOption::initFrom(). No todos los elementos utilizan esta función. Los widgets crean las opciones de estilo y, para algunos elementos, la información de initFrom() no es necesaria.
| Estado | Se establece cuando |
|---|---|
State_Enabled | El widget no está desactivado (véase QWidget::isEnabled()). |
State_HasFocus | El widget tiene el foco (véase QWidget::hasFocus()). |
State_KeyboardFocusChange | El usuario ha cambiado el foco con el teclado (véase WA_KeyboardFocusChange). |
State_MouseOver | El cursor del ratón se encuentra sobre el widget. |
State_Active | El widget es un elemento secundario de la ventana activa. |
Los demás miembros comunes son:
| Miembro | Descripción |
|---|---|
| rect | El rectángulo delimitador del elemento que se va a dibujar. initFrom() lo establece en el rectángulo delimitador del widget (QWidget::rect()). |
| direction | La dirección de diseño, un valor de la enumeración ` Qt::LayoutDirection `. |
| palette | La enumeración « QPalette » que se utilizará al dibujar el elemento. « initFrom() » lo establece en la paleta del widget (QWidget::palette()). |
| fontMetrics | El ` QFontMetrics ` que se utilizará al dibujar texto en el widget. |
| styleObject | El objeto que describe la opción, normalmente el widget. Los estilos lo utilizan para almacenar el estado de la animación. |
Las opciones de estilo complejas (clases que heredan de ` QStyleOptionComplex`) comparten dos variables más: ` subControls ` y ` activeSubControls`. Ambas son combinaciones OR de valores de ` QStyle::SubControl `. Indican de qué subcontroles se compone el control complejo y cuáles de ellos están activos actualmente.
Funciones de QStyle
QStyle define tres funciones para dibujar los elementos primitivos, de control y complejos: ` drawPrimitive()`, ` drawControl()` y ` drawComplexControl()`. Estas funciones aceptan los argumentos enumerados en la sección «Elementos de estilo».
No todos los widgets pasan un puntero a sí mismos. Si la opción de estilo enviada a la función no contiene la información que necesitas, comprueba la implementación del widget para ver si se pasa a sí mismo.
QStyle También proporciona funciones auxiliares para dibujar elementos. drawItemText() dibuja texto dentro de un rectángulo especificado, tomando un QPalette como parámetro. drawItemPixmap() alinea un mapa de píxeles dentro de un rectángulo delimitador especificado.
Otras funciones de ` QStyle ` realizan cálculos para las funciones de dibujo. Los widgets también las utilizan para calcular las indicaciones de tamaño y los rectángulos delimitadores cuando dibujan ellos mismos varios elementos de estilo. Estas funciones suelen tomar los mismos argumentos que las funciones de dibujo.
- subElementRect() toma un valor de ` SubElement ` y calcula el rectángulo delimitador de un subelemento. El estilo utiliza esta función para saber dónde dibujar las diferentes partes de un elemento. Si creas un nuevo estilo, puedes reutilizar las posiciones de los subelementos de la clase base.
- subControlRect() calcula los rectángulos delimitadores de los subcontroles en controles complejos. Al implementar un nuevo estilo, vuelve a implementarla para los rectángulos que difieran de los de la clase base.
- pixelMetric() devuelve una métrica de píxeles, un tamaño dependiente del estilo expresado en píxeles de pantalla. Toma un valor de la enumeración PixelMetric. Las métricas de píxeles no tienen por qué ser medidas estáticas; puedes calcularlas a partir de la opción de estilo.
- sizeFromContents() devuelve el tamaño de un widget para un tamaño de contenido dado. Los widgets lo utilizan para calcular sus indicaciones de tamaño.
- hitTestComplexControl() devuelve el subcontrol sobre el que se encuentra el puntero del ratón en un control complejo. Por lo general, basta con utilizar subControlRect() para obtener los rectángulos delimitadores de los subcontroles y localizar aquel que contenga la posición del cursor.
QStyle También dispone de las funciones ` polish()` y ` unpolish()`. Qt «pulimenta» cada widget antes de mostrarlo por primera vez y de nuevo cuando cambia el estilo, y deja de «pulimentarlo» cuando cambia el estilo o se destruye el widget. Utiliza estas funciones para establecer atributos en los widgets o para realizar otras tareas que requiera tu estilo. Por ejemplo, si necesitas saber cuándo el ratón se encuentra sobre un widget, establece el atributo del widget ` WA_Hover ` en ` polish()`. A continuación, el widget establece ` State_MouseOver ` en sus opciones de estilo. Las sobrecargas de ` polish() ` también permiten al estilo preparar el ` QApplication ` y ajustar la paleta de la aplicación; consulta «La paleta».
Por último, QStyle dispone de funciones auxiliares estáticas para tareas comunes y complejas. sliderPositionFromValue() y sliderValueFromPosition() convierten los valores del control deslizante en posiciones de píxeles y viceversa. visualRect(), visualPos() y visualAlignment() traducen las coordenadas lógicas y las alineaciones a sus equivalentes reflejadas en diseños de derecha a izquierda, y alignedRect() alinea un rectángulo según la dirección actual. Para más detalles, véase Right-to-Left Desktops en la documentación de la clase QStyle.
Al reimplementar las funciones virtuales de ` QStyle `, gestiona los elementos que difieren de la clase base y llama a la implementación de la clase base para todo lo demás.
La paleta
Cada estilo dibuja con una paleta de pinceles, proporcionada por QPalette. Existe un conjunto de colores, un QPalette::ColorGroup, para cada estado de widget: «activo» para los widgets de la ventana que tiene el foco del teclado, «inactivo» para los widgets de otras ventanas y «desactivado» para los widgets que están desactivados. Los indicadores de estado State_Active y State_Enabled indican qué grupo se debe utilizar. Cada grupo contiene las funciones de color que define QPalette::ColorRole. Las funciones describen las situaciones para las que están pensados los colores, como pintar fondos de widgets, texto o botones.
Cada estilo decide cómo utilizar los roles de color. Por ejemplo, si el estilo utiliza degradados, puede tomar un color de la paleta y oscurecerlo o aclararlo con QColor::darker() y QColor::lighter() para crear el degradado. En general, si necesitas un pincel que la paleta no proporciona, dérivalo de uno que sí esté disponible.
Cuando se establece un estilo en la aplicación, Qt crea la paleta de la aplicación a partir de la función ` standardPalette()` del estilo, permite que el tema de la plataforma anule los roles que proporciona y pasa el resultado a ` QStyle::polish()`. Reimplementa esa sobrecarga para ajustar los colores que necesita tu estilo. Qt no anula una paleta que la aplicación haya establecido explícitamente con ` QApplication::setPalette()`.
No codifiques los colores de forma rígida. Las aplicaciones y los widgets individuales pueden establecer su propia paleta, y un estilo que utilice dicha paleta seguirá esas configuraciones. Además, obtiene una variante clara y otra oscura a partir de dos paletas, sin necesidad de código adicional. El estilo Fusion de Qt funciona de esta manera:
|
|
Un estilo no tiene por qué quedar bien con todas las paletas imaginables, pero debe respetar la paleta que se le proporcione.
Vistas de elementos
Los delegados se encargan de dibujar los elementos en las vistas de elementos. El delegado predeterminado de Qt, QStyledItemDelegate, dibuja CE_ItemViewItem y calcula los tamaños de los elementos con CT_ItemViewItem, por lo que un estilo controla el aspecto de los elementos sin necesidad de un delegado asociado. El estilo dibuja directamente los encabezados de la vista de elementos, los indicadores de las ramas del árbol y los fondos de las filas. Para admitir nuevos tipos de datos o funciones de datos de los elementos, necesitas un delegado personalizado; consulta Programación Modelo/Vista.
Consejos de implementación
Al implementar un estilo, lee el código de los widgets y de la clase base. Los widgets utilizan el estilo de diferentes maneras, y la implementación de la clase base puede afectar al estado del dibujo, por ejemplo, alterando el estado de QPainter sin restaurarlo, o dibujando algunos elementos sin utilizar las métricas de píxeles y los subelementos adecuados.
No modifiques el tamaño propuesto de los widgets en ` sizeFromContents()` a menos que sea necesario; deja que la implementación de ` QCommonStyle ` se encargue de ello. Si realizas cambios, que sean mínimos. El desarrollo de aplicaciones resulta complicado cuando el diseño de los widgets difiere considerablemente entre estilos.
Prueba tu estilo con la opción de línea de comandos -reverse o con QGuiApplication::setLayoutDirection(), para que los elementos asimétricos también se vean correctamente en un diseño de derecha a izquierda.
Véase también QStyle, QStyleOption, QStylePainter, Referencia de estilos de widgets y Estilización de una casilla de selección: guía paso a paso.
© 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.

