QStyleKitStyle Class
The QStyleKitStyle class applies a Qt Labs StyleKit style to Qt Widgets. More...
| Header: | #include <QStyleKitStyle> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS LabsStyleKit)target_link_libraries(mytarget PRIVATE Qt6::LabsStyleKit) |
| Since: | Qt 6.12 |
| Inherits: | QCommonStyle |
Properties
- customThemeNames : QStringList
- stylePath : QString
- themeName : QString
- themeNames : QStringList
Public Functions
| QStyleKitStyle() | |
| QStyleKitStyle(const QString &filePath) | |
| virtual | ~QStyleKitStyle() override |
| QStringList | customThemeNames() const |
| void | setStylePath(const QString &filePath) |
| void | setThemeName(const QString &themeName) |
| QString | stylePath() const |
| QString | themeName() const |
| QStringList | themeNames() const |
Reimplemented Public Functions
| 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 |
Signals
| void | stylePathChanged() |
| void | themeNameChanged() |
Reimplemented Protected Functions
| virtual bool | event(QEvent *event) override |
| virtual bool | eventFilter(QObject *obj, QEvent *event) override |
Detailed Description
QStyleKitStyle is a QStyle implementation that uses a StyleKit Style to style Qt Widgets. The Style is a QML file that declaratively describes the visual design (colors, sizes, radii, borders, and other properties) for each widget type and state. Those property values drive the painting, which is done entirely with QPainter. Qt Quick and the scene graph play no part in the rendering.
This separation means the same Style QML file can drive both Qt Quick Controls and Qt Widgets, sharing one design definition across both systems.
Note: StyleKit is a Qt Labs module, and its API may change between Qt releases.
Loading a Style
A style is a QML file whose root object is a Style. To load it, pass the file path to the constructor or to setStylePath():
auto *style = new QStyleKitStyle(QStringLiteral(":/styles/MyStyle.qml"));
QApplication::setStyle(style);The Style is loaded with an internal QQmlEngine owned by the QStyleKitStyle instance. If the path is invalid or the root object is not a Style, a warning is emitted and the style uses a default fallback style until a valid stylePath is set.
Themes
A Style may define one or more named themes. The active theme is selected with setThemeName(); the list of available themes is exposed through themeNames. The special theme name System makes the style follow the platform color scheme: when the OS color scheme changes, the active theme is recreated automatically and all widgets are repolished.
Widget to StyleKit Control Mapping
Each Qt Widgets class is mapped to a StyleKit control type, which determines which control entry in the Style applies to it. Use the corresponding control entry to configure colors, sizes, and other visual properties for that widget type. Properties not set in a specific control entry fall back through the control type hierarchy: for example, button falls back to abstractButton, which falls back to control.
Widgets not listed above fall back to the control type. Notably, QMenuBar, QMenu, and item view containers such as QListView and QTreeView are not yet specifically mapped; only the individual items inside item views are styled via the itemDelegate control. Dedicated mappings for these widgets are planned for a future release. Conversely, control entries with no Qt Widgets equivalent — switchControl, rangeSlider, scrollIndicator, roundButton, and page — have no corresponding widget type and are not applied.
Known Limitations
QStyleKitStyle is in Tech Preview. The following StyleKit features are currently not supported when used with Qt Widgets:
- Shadows — shadows are not rendered.
- Variations — setting a StyleVariation on a widget instance is not yet supported.
- Custom controls — styling custom widgets using CustomControl is not yet supported.
- Custom delegates — the delegate property is not used; the built-in rendering is always applied.
Support for these features is planned for a future release.
See also QStyle, QCommonStyle, Qt Labs StyleKit, Style, and Theme.
Property Documentation
[read-only] customThemeNames : QStringList
This property holds the list of custom theme names defined by the loaded Style.
Unlike themeNames, this list excludes the built-in Light and Dark themes and contains only the themes explicitly defined by the style author. Returns an empty list when no style is loaded.
Access functions:
| QStringList | customThemeNames() const |
Notifier signal:
| void | stylePathChanged() |
See also themeNames and themeName.
stylePath : QString
This property holds the path to the QML Style file driving this style.
The value is a path to a local file or a path to a file in the resource file system (for example, :/styles/MyStyle.qml). A relative path is resolved against the application's working directory. The file must contain a QML component whose root object is a Style. Setting this property reloads the style; if the new file cannot be loaded, the previously loaded style is kept and a warning is emitted.
Access functions:
| QString | stylePath() const |
| void | setStylePath(const QString &filePath) |
Notifier signal:
| void | stylePathChanged() |
themeName : QString
This property holds the name of the active theme.
The value must be one of the entries in themeNames, or the special name System to follow the platform color scheme. Setting this property updates all widgets to repaint with the new theme.
Access functions:
| QString | themeName() const |
| void | setThemeName(const QString &themeName) |
Notifier signal:
| void | themeNameChanged() |
[read-only] themeNames : QStringList
This property holds the list of theme names exposed by the loaded Style.
This list includes the built-in Light and Dark themes as well as any custom themes defined by the style.
Access functions:
| QStringList | themeNames() const |
Notifier signal:
| void | stylePathChanged() |
Member Function Documentation
QStyleKitStyle::QStyleKitStyle()
Constructs a QStyleKitStyle with no style loaded.
Use setStylePath() to load a QML Style after construction. Until a style is loaded, the style uses a default fallback style.
[explicit] QStyleKitStyle::QStyleKitStyle(const QString &filePath)
Constructs a QStyleKitStyle and loads the QML Style at filePath.
filePath is a path to a local file or a path to a file in the resource file system; a relative path is resolved against the application's working directory. If the path is invalid or the root object of the loaded component is not a Style, a warning is emitted and the constructed style uses a default fallback style until a valid stylePath is set.
[override virtual noexcept] QStyleKitStyle::~QStyleKitStyle()
Destroys the QStyleKitStyle.
QStringList QStyleKitStyle::customThemeNames() const
Returns the names of the custom themes defined by the loaded Style, excluding the built-in Light and Dark themes. Returns an empty list when no style is loaded.
Note: Getter function for property customThemeNames.
See also themeNames().
[override virtual] void QStyleKitStyle::drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *w = nullptr) const
Reimplements: 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
Reimplements: 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
Reimplements: QCommonStyle::drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *widget) const.
[override virtual protected] bool QStyleKitStyle::event(QEvent *event)
Reimplements: QObject::event(QEvent *e).
[override virtual protected] bool QStyleKitStyle::eventFilter(QObject *obj, QEvent *event)
Reimplements: 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
Reimplements: 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
Reimplements: QCommonStyle::pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt, const QWidget *widget) const.
[override virtual] void QStyleKitStyle::polish(QApplication *app)
Reimplements: QCommonStyle::polish(QApplication *app).
[override virtual] void QStyleKitStyle::polish(QPalette &palette)
Reimplements: QCommonStyle::polish(QPalette &pal).
[override virtual] void QStyleKitStyle::polish(QWidget *widget)
Reimplements: QCommonStyle::polish(QWidget *widget).
void QStyleKitStyle::setStylePath(const QString &filePath)
Loads the QML Style at filePath and applies it to all widgets.
filePath is a path to a local file or a path to a file in the resource file system; see the stylePath property for the accepted forms. If it is the same as the current stylePath, this function does nothing. If the new style cannot be loaded, the previously loaded style remains active and a warning is emitted; stylePathChanged() is still emitted to reflect the changed property value.
Note: Setter function for property stylePath.
See also stylePath().
void QStyleKitStyle::setThemeName(const QString &themeName)
Activates the theme named themeName.
themeName must be one of the entries in themeNames(), or the special name System to follow the platform color scheme. If no Style has been loaded, this function emits a warning and returns without changing the active theme.
Note: Setter function for property themeName.
See also themeName() and themeNames().
[override virtual] QSize QStyleKitStyle::sizeFromContents(QStyle::ContentsType ct, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget = nullptr) const
Reimplements: QCommonStyle::sizeFromContents(QStyle::ContentsType contentsType, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget) const.
[override virtual] QPalette QStyleKitStyle::standardPalette() const
Reimplements: QStyle::standardPalette() const.
[override virtual] int QStyleKitStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt = nullptr, const QWidget *w = nullptr, QStyleHintReturn *shret = nullptr) const
Reimplements: QCommonStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt, const QWidget *widget, QStyleHintReturn *hret) const.
QString QStyleKitStyle::stylePath() const
Returns the path of the currently loaded Style file.
Note: Getter function for property stylePath.
See also setStylePath().
[override virtual] QRect QStyleKitStyle::subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *w = nullptr) const
Reimplements: 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
Reimplements: QCommonStyle::subElementRect(QStyle::SubElement sr, const QStyleOption *opt, const QWidget *widget) const.
QString QStyleKitStyle::themeName() const
Returns the name of the currently active theme, or an empty string if no Style has been loaded.
Note: Getter function for property themeName.
See also setThemeName() and themeNames().
QStringList QStyleKitStyle::themeNames() const
Returns the names of all themes exposed by the loaded Style, including the built-in Light and Dark themes and any custom themes defined by the style. Returns an empty list when no style is loaded.
Note: Getter function for property themeNames.
See also customThemeNames() and themeName().
[override virtual] void QStyleKitStyle::unpolish(QApplication *app)
Reimplements: QCommonStyle::unpolish(QApplication *application).
[override virtual] void QStyleKitStyle::unpolish(QWidget *widget)
Reimplements: 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.
