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
- availableThemeNames : QStringList
- customThemeNames : QStringList
- stylePath : QString
- themeName : QString
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:
| Subelemento | Control 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 QTabBar | tabButton |
| QMenu elementos | menuItem |
| Separadores en un QMenu | menuSeparator |
| QMenuBar elementos | menuBarItem |
| Separadores en un QToolBar | toolSeparator |
| 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.