En esta página

QStyleKitStyle Class

La clase `QStyleKitStyle` aplica un estilo de StyleKit de Qt Labs a ` Qt Widgets`. Más información...

Encabezado: #include <QStyleKitStyle>
CMake: find_package(Qt6 REQUIRED COMPONENTS LabsStyleKit)
target_link_libraries(mytarget PRIVATE Qt6::LabsStyleKit)
Desde: Qt 6.12
Heredan de: QCommonStyle

Propiedades

Funciones públicas

QStyleKitStyle()
QStyleKitStyle(const QString &filePath)
virtual ~QStyleKitStyle() override
QStringList availableThemeNames() const
QStringList customThemeNames() const
void setStylePath(const QString &filePath)
void setThemeName(const QString &themeName)
QString stylePath() const
QString themeName() const

Funciones públicas reimplementadas

virtual void drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *w = nullptr) const override
virtual void drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const override
virtual void drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const override
virtual QStyle::SubControl hitTestComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *w = nullptr) const override
virtual int pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt = nullptr, const QWidget *widget = nullptr) const override
virtual void polish(QApplication *app) override
virtual void polish(QPalette &palette) override
virtual void polish(QWidget *widget) override
virtual QSize sizeFromContents(QStyle::ContentsType ct, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget = nullptr) const override
virtual QPalette standardPalette() const override
virtual int styleHint(QStyle::StyleHint sh, const QStyleOption *opt = nullptr, const QWidget *w = nullptr, QStyleHintReturn *shret = nullptr) const override
virtual QRect subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *w = nullptr) const override
virtual QRect subElementRect(QStyle::SubElement r, const QStyleOption *opt, const QWidget *widget = nullptr) const override
virtual void unpolish(QApplication *app) override
virtual void unpolish(QWidget *widget) override

Señales

void availableThemeNamesChanged(const QStringList &availableThemeNames)
void customThemeNamesChanged(const QStringList &customThemeNames)
void stylePathChanged(const QString &stylePath)
void themeNameChanged(const QString &themeName)

Funciones protegidas reimplementadas

virtual bool event(QEvent *event) override
virtual bool eventFilter(QObject *obj, QEvent *event) override

Descripción detallada

QStyleKitStyle es una implementación de « QStyle » que utiliza un « StyleKit » Style para aplicar estilos a Qt Widgets. El « Style » es un archivo QML que describe de forma declarativa el diseño visual (colores, tamaños, radios, bordes y otras propiedades) para cada tipo de widget y estado. Esos valores de propiedad controlan el dibujo, que se realiza íntegramente con QPainter. Ni Qt Quick ni el grafo de escena intervienen en la representación.

Esta separación significa que el mismo archivo QML Style puede controlar tanto los controles Qt Quick como Qt Widgets, compartiendo una única definición de diseño entre ambos sistemas.

Nota: StyleKit es un módulo de Qt Labs, y su API puede cambiar entre las distintas versiones de Qt.

Carga de un estilo

Un estilo es un archivo QML cuyo objeto raíz es un ` Style`. Para cargarlo, pasa la ruta del archivo al constructor o a ` setStylePath()`:

auto *style = new QStyleKitStyle(QStringLiteral(":/styles/MyStyle.qml"));
QApplication::setStyle(style);

El estilo se carga con un ` QQmlEngine ` interno propiedad de la instancia de `QStyleKitStyle`. Si la ruta no es válida o el objeto raíz no es un ` Style`, se emite una advertencia y el estilo utiliza un estilo predeterminado hasta que se establezca un ` stylePath ` válido.

Temas

Un estilo puede definir uno o varios « themes » con nombre. El tema activo se selecciona con ` setThemeName()`; la lista de temas disponibles se expone a través de ` availableThemeNames`. El nombre de tema especial ` System ` hace que el estilo siga la combinación de colores de la plataforma: cuando cambia la combinación de colores del sistema operativo, el tema activo se recrea automáticamente y se actualiza el aspecto de todos los widgets.

Asignación de widgets a controles de StyleKit

Cada clase de « Qt Widgets » se asigna a un tipo de control de StyleKit, lo que determina qué entrada de control de Style se le aplica. Utiliza la entrada de control correspondiente para configurar las propiedades visuales de ese tipo de widget, incluidas las partes individuales del mismo, como el fondo, el indicador, el controlador, etc. Consulta ControlStyleProperties para ver la lista completa de propiedades personalizables. Las propiedades que no se definan en una entrada de control específica se resuelven mediante la jerarquía de tipos de control: por ejemplo, button se resuelve como abstractButton, que a su vez se resuelve como control.

Los widgets que no aparecen en la lista anterior aún no son compatibles con QStyleKitStyle y serán dibujados por QCommonStyle. Está previsto que los widgets restantes sean compatibles en futuras versiones. Por el contrario, algunas entradas de control de StylableControls no tienen equivalente en Qt Widgets y no se aplican al aplicar estilos a los widgets.

Subcontroles dentro de un widget

Los subcontroles independientes dentro de un widget pueden personalizarse individualmente, ya que cada uno se corresponde con una entrada de control independiente en Style:

SubelementoControl de StyleKit
QStyledItemDelegate items: el delegado predeterminado para todas las vistas de elementos de Qt, incluida la lista emergente de QComboBox itemDelegate
Esos mismos elementos, cuando el usuario puede marcarlos (es decir, cuando muestran un indicador de selección)checkDelegate; se recurre a itemDelegate para todo lo que no se haya establecido explícitamente
Pestañas individuales en un QTabBartabButton
QMenu elementosmenuItem
Separadores en un QMenumenuSeparator
QMenuBar elementosmenuBarItem
Separadores en un QToolBartoolSeparator
El contenedor de lista desplegable « QComboBox »popup

Limitaciones conocidas

QStyleKitStyle se encuentra en fase de vista previa técnica. Las siguientes características de StyleKit no son compatibles actualmente cuando se utilizan con Qt Widgets:

  • Sombras: las sombras no se representan.
  • Escala de delegado superior a 1,0 en el fondo de un control: un widget no puede dibujar fuera de su propio rectángulo, por lo que el fondo escalado se recorta en el borde del widget. Utiliza margins para insertar el fondo y reservar espacio para que pueda expandirse. Los indicadores de escala, los controladores y los primeros planos no se ven afectados.
  • Variaciones: aún no se admite la configuración de un « StyleVariation » en una instancia de widget.
  • Controles personalizados: aún no se admite la aplicación de estilos a widgets personalizados mediante ` CustomControl `.
  • Delegados personalizados: no se utiliza la propiedad delegate; siempre se aplica el renderizado integrado.

Está previsto que estas características se incluyan en una versión futura.

Véase también QStyle, QCommonStyle, Qt Labs StyleKit, Style y Theme.

Documentación de propiedades

[read-only] availableThemeNames : QStringList

Esta propiedad contiene la lista de nombres de temas que muestra el archivo « Style » cargado.

Esta lista incluye los temas integrados « Light » y « Dark », así como cualquier tema personalizado definido por el estilo.

Funciones de acceso:

QStringList availableThemeNames() const

Señal de notificación:

void availableThemeNamesChanged(const QStringList &availableThemeNames)

[read-only] customThemeNames : QStringList

Esta propiedad contiene la lista de nombres de temas personalizados definidos por el archivo « Style » cargado.

A diferencia de ` availableThemeNames`, esta lista excluye los temas integrados ` Light ` y ` Dark `, y solo contiene los temas definidos explícitamente por el autor del estilo. Devuelve una lista vacía cuando no se ha cargado ningún estilo.

Funciones de acceso:

QStringList customThemeNames() const

Señal de notificador:

void customThemeNamesChanged(const QStringList &customThemeNames)

Véase también availableThemeNames y themeName.

stylePath : QString

Esta propiedad contiene la ruta al archivo QML Style que define este estilo.

El valor es una ruta a un archivo local o a un archivo del sistema de archivos de recursos (por ejemplo, :/styles/MyStyle.qml). Una ruta relativa se resuelve con respecto al directorio de trabajo de la aplicación. El archivo debe contener un componente QML cuyo objeto raíz sea un ` Style`. Al establecer esta propiedad, se recarga el estilo; si no se puede cargar el nuevo archivo, se mantiene el estilo cargado anteriormente y se emite una advertencia.

Funciones de acceso:

QString stylePath() const
void setStylePath(const QString &filePath)

Señal del notificador:

void stylePathChanged(const QString &stylePath)

themeName : QString

Esta propiedad contiene el nombre del tema activo.

El valor debe ser una de las entradas de availableThemeNames, o el nombre especial System para seguir la combinación de colores de la plataforma. Al configurar esta propiedad, todos los widgets se actualizan para redibujarse con el nuevo tema.

Funciones de acceso:

QString themeName() const
void setThemeName(const QString &themeName)

Señal del notificador:

void themeNameChanged(const QString &themeName)

Documentación de funciones de miembro

QStyleKitStyle::QStyleKitStyle()

Crea un objeto `QStyleKitStyle` sin ningún estilo cargado.

Utiliza setStylePath() para cargar un estilo QML Style tras la creación. Hasta que se cargue un estilo, se utiliza un estilo predeterminado.

[explicit] QStyleKitStyle::QStyleKitStyle(const QString &filePath)

Crea un objeto `QStyleKitStyle` y carga el archivo QML « Style » disponible en filePath.

filePath es una ruta a un archivo local o a un archivo del sistema de recursos; las rutas relativas se resuelven con respecto al directorio de trabajo de la aplicación. Si la ruta no es válida o el objeto raíz del componente cargado no es un ` Style`, se emite una advertencia y el estilo creado utiliza un estilo predeterminado hasta que se establezca un ` stylePath ` válido.

[override virtual noexcept] QStyleKitStyle::~QStyleKitStyle()

Destruye el « QStyleKitStyle ».

QStringList QStyleKitStyle::availableThemeNames() const

Devuelve los nombres de todos los temas expuestos por el archivo « Style » cargado, incluidos los temas integrados « Light » y « Dark », así como cualquier tema personalizado definido por el estilo. Devuelve una lista vacía cuando no se ha cargado ningún estilo.

Nota: Funcióngetter para la propiedad availableThemeNames.

Véase también customThemeNames() y themeName().

QStringList QStyleKitStyle::customThemeNames() const

Devuelve los nombres de los temas personalizados definidos por el archivo ` Style` cargado, excluyendo los temas integrados ` Light ` y ` Dark `. Devuelve una lista vacía cuando no se ha cargado ningún estilo.

Nota: Funcióngetter para la propiedad customThemeNames.

Véase también availableThemeNames().

[override virtual] void QStyleKitStyle::drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *w = nullptr) const

Reimplementa: ` QCommonStyle::drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const`.

[override virtual] void QStyleKitStyle::drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const

Reimplementa: QCommonStyle::drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *widget) const.

[override virtual] void QStyleKitStyle::drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const

Reimplementa: QCommonStyle::drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *widget) const.

[override virtual protected] bool QStyleKitStyle::event(QEvent *event)

Reimplementa: ` QObject::event(QEvent *e)`.

[override virtual protected] bool QStyleKitStyle::eventFilter(QObject *obj, QEvent *event)

Reimplementa: QObject::eventFilter(QObject *watched, QEvent *event).

[override virtual] QStyle::SubControl QStyleKitStyle::hitTestComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *w = nullptr) const

Reimplementa: ` QCommonStyle::hitTestComplexControl` (QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const.

[override virtual] int QStyleKitStyle::pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt = nullptr, const QWidget *widget = nullptr) const

Reimplementa: ` QCommonStyle::pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt, const QWidget *widget) const`.

[override virtual] void QStyleKitStyle::polish(QApplication *app)

Reimplementa: QCommonStyle::polish(QApplication *app).

[override virtual] void QStyleKitStyle::polish(QPalette &palette)

Reimplementa: QCommonStyle::polish(QPalette y &pal).

[override virtual] void QStyleKitStyle::polish(QWidget *widget)

Reimplementa: QCommonStyle::polish(QWidget *widget).

void QStyleKitStyle::setStylePath(const QString &filePath)

Carga el archivo QML « Style » desde filePath y lo aplica a todos los widgets.

filePath es una ruta a un archivo local o a un archivo del sistema de archivos de recursos; consulta la propiedad stylePath para conocer los formatos admitidos. Si coincide con el stylePath actual, esta función no realiza ninguna acción. Si no se puede cargar el nuevo estilo, el estilo cargado anteriormente permanece activo y se emite una advertencia; se sigue emitiendo stylePathChanged() para reflejar el cambio en el valor de la propiedad.

Nota: Funciónde asignación para la propiedad stylePath.

Véase también stylePath().

void QStyleKitStyle::setThemeName(const QString &themeName)

Activa el tema denominado « themeName ».

themeName Debe ser una de las entradas de availableThemeNames(), o el nombre especial System para seguir la combinación de colores de la plataforma. Si no se ha cargado ningún Style, esta función emite una advertencia y vuelve sin cambiar el tema activo.

Nota: Funciónde configuración para la propiedad themeName.

Véase también themeName() y availableThemeNames().

[override virtual] QSize QStyleKitStyle::sizeFromContents(QStyle::ContentsType ct, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget = nullptr) const

Reimplementa: ` QCommonStyle::sizeFromContents` (`QStyle::ContentsType contentsType, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget) const`.

[override virtual] QPalette QStyleKitStyle::standardPalette() const

Reimplementa: ` QStyle::standardPalette()` const.

[override virtual] int QStyleKitStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt = nullptr, const QWidget *w = nullptr, QStyleHintReturn *shret = nullptr) const

Reimplementa: QCommonStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt, const QWidget *widget, QStyleHintReturn *hret) const.

QString QStyleKitStyle::stylePath() const

Devuelve la ruta del archivo « Style » cargado actualmente.

Nota: Funcióngetter para la propiedad stylePath.

Véase también setStylePath().

[override virtual] QRect QStyleKitStyle::subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *w = nullptr) const

Reimplementa: QCommonStyle::subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *widget) const.

[override virtual] QRect QStyleKitStyle::subElementRect(QStyle::SubElement r, const QStyleOption *opt, const QWidget *widget = nullptr) const

Reimplementa: ` QCommonStyle::subElementRect(QStyle::SubElement sr, const QStyleOption *opt, const QWidget *widget) const`.

QString QStyleKitStyle::themeName() const

Devuelve el nombre del tema actualmente activo, o una cadena vacía si no se ha cargado ningún tema ( Style ).

Nota: Funcióngetter para la propiedad themeName.

Véase también setThemeName() y availableThemeNames().

[override virtual] void QStyleKitStyle::unpolish(QApplication *app)

Reimplementa: ` QCommonStyle::unpolish(QApplication *application)`.

[override virtual] void QStyleKitStyle::unpolish(QWidget *widget)

Reimplementa: QCommonStyle::unpolish(QWidget *widget).

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