En esta página

Creación de widgets sensibles al estilo

Un widget compatible con estilos se ajusta al estilo con el que se dibuja. En lugar de dibujar él mismo marcos, botones e indicadores, solicita al estilo actual que los dibuje y le pide las métricas que necesita para distribuir su contenido. De este modo, el widget tiene un aspecto nativo en todas las plataformas, sigue la paleta de la aplicación y adopta un estilo personalizado o una hoja de estilo, tal y como hacen los propios widgets de Qt.

Crear una opción de estilo

El estilo se basa en la información de un ` QStyleOption`, por lo que el primer paso en un evento de pintura es rellenar uno. Elige la clase de opción que se corresponda con el elemento que deseas dibujar, llama a ` QStyleOption::initFrom()` para establecer los indicadores de estado, el rectángulo, la paleta y las métricas de fuente que comparten todos los widgets, y a continuación configura los miembros específicos de tu elemento.

Los widgets de Qt lo hacen mediante una función virtual protegida ` initStyleOption() `, de modo que las subclases puedan ajustar la opción. Sigue el mismo patrón en tu widget.

Dibuja mediante el estilo

Dibuja los elementos con las funciones de dibujo de ` QStyle`, pasando la opción, un ` QPainter` y el propio widget:

QPainter painter(this);
    ...
style()->drawPrimitive(QStyle::PE_FrameFocusRect, &option, &painter, this);

QStylePainter combina un ` QStyle`, un ` QPainter` y un ` QWidget`. Sus funciones de dibujo solo aceptan el elemento y la opción, lo que acorta el código:

    QStylePainter painter(this);
    ...
painter.drawPrimitive(QStyle::PE_FrameFocusRect, option);

Diagrama que muestra que QStylePainter hereda de QPainter

Utiliza la paleta de la opción, o QWidget::palette(), para cualquier color que dibujes tú mismo, de modo que el widget siga la paleta de la aplicación y funcione tanto en esquemas de color claro como oscuro.

Consulta el estilo para conocer los tamaños

Basa tus funciones ` sizeHint()` y ` minimumSizeHint()` en el estilo. La función ` sizeFromContents()` convierte el tamaño de tu contenido en el tamaño del widget para un tipo de contenido determinado, y ` pixelMetric()` devuelve los anchos del marco, los márgenes y los tamaños de los indicadores del estilo. Utiliza ` subElementRect()` para averiguar dónde coloca el estilo las partes de un elemento, en lugar de calcular tú mismo las posiciones.

Notificar el estado del widget

El estilo dibuja los efectos de desplazamiento y enfoque solo si se establecen los indicadores de estado. Establece el atributo « WA_Hover » en tu widget para recibir eventos de desplazamiento, y añade « State_MouseOver » a la opción mientras el ratón se encuentra sobre el elemento. Establece « State_Sunken » mientras el widget está pulsado, y « State_On », « State_Off » o « State_NoChange » para los elementos marcables. La Referencia de estilos de widgets enumera los indicadores que espera cada elemento.

Seguir los cambios de estilo y paleta

Cuando cambia el estilo o la paleta de la aplicación, el widget recibe un evento QEvent::StyleChange o QEvent::PaletteChange en changeEvent(). Invalida allí cualquier métrica almacenada en caché y llama a updateGeometry() si tu indicación de tamaño depende del estilo.

Compatibilidad con diseños de derecha a izquierda

En un diseño de derecha a izquierda, el estilo refleja los elementos asimétricos. Utiliza visualRect() para convertir un rectángulo de coordenadas lógicas a coordenadas de pantalla y visualAlignment() para reflejar una alineación, y pasa la opción direction al estilo. Prueba con la opción de línea de comandos -reverse.

Véase también QStyle, QStylePainter, QStyleOption, «Cómo dibuja un estilo un widget» y «Referencia de estilos de widgets».

© 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.