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 |
| Status: | Technology preview |
This class is in technology preview and is subject to change.
Properties
- availableThemeNames : QStringList
- customThemeNames : QStringList
- stylePath : QString
- themeName : QString
Public Functions
| 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 |
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 | availableThemeNamesChanged(const QStringList &availableThemeNames) |
| void | customThemeNamesChanged(const QStringList &customThemeNames) |
| void | stylePathChanged(const QString &stylePath) |
| void | themeNameChanged(const QString &themeName) |
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);QStyleKitStyle loads the Style with an internal QQmlEngine that the QStyleKitStyle instance owns. If the path is invalid or the root object is not a Style, QStyleKitStyle emits a warning and keeps the previously loaded style. Until a style loads successfully, the widgets use an empty fallback style.
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 availableThemeNames. 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 visual properties for that widget type, including individual parts of the widget such as its background, indicator, handle, etc. See ControlStyleProperties for the full list of stylable properties. 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 are not yet supported by QStyleKitStyle and will be painted by QCommonStyle. Support for remaining widgets is planned for future releases. Conversely, some control entries in StylableControls have no Qt Widgets equivalent and are not applied when styling widgets.
Sub-controls within a widget
Separate sub-controls within a widget can be styled individually, as each one maps to a separate control entry in the Style:
| Sub-element | StyleKit control |
|---|---|
| QStyledItemDelegate items - the default delegate for all Qt item views, including the QComboBox popup list | itemDelegate |
| The same items, when user-checkable (i.e. showing a check indicator) | checkDelegate; falls back to itemDelegate for anything not set explicitly |
| Individual tabs in a QTabBar | tabButton |
| QMenu items | menuItem |
| Separators in a QMenu | menuSeparator |
| QMenuBar items | menuBarItem |
| Separators in a QToolBar | toolSeparator |
| The QComboBox popup list container | popup |
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.
- Delegate scale above 1.0 on a control's background — a widget cannot paint outside its own rect, so the scaled background is clipped at the widget edge. Use margins to inset the background and reserve room for it to grow. Scaling indicators, handles and foregrounds is unaffected.
- 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] availableThemeNames : QStringList
This property holds the list of theme names exposed by the loaded Style.
This list always includes System, which follows the platform color scheme. It also includes Light and Dark when the Style defines those themes, together with any custom themes that the style author defines. The list is empty when no style is loaded.
Access functions:
| QStringList | availableThemeNames() const |
Notifier signal:
| void | availableThemeNamesChanged(const QStringList &availableThemeNames) |
[read-only] customThemeNames : QStringList
This property holds the list of custom theme names defined by the loaded Style.
Unlike availableThemeNames, this list excludes System, Light, and Dark, and contains only the themes that the style author defines explicitly. The list is empty when no style is loaded.
Access functions:
| QStringList | customThemeNames() const |
Notifier signal:
| void | customThemeNamesChanged(const QStringList &customThemeNames) |
See also availableThemeNames 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 to a file in the resource file system (for example, :/styles/MyStyle.qml). QStyleKitStyle resolves a relative path 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 does not load, QStyleKitStyle emits a warning and keeps the previously loaded style and style path.
Access functions:
| QString | stylePath() const |
| void | setStylePath(const QString &filePath) |
Notifier signal:
| void | stylePathChanged(const QString &stylePath) |
themeName : QString
This property holds the name of the active theme.
The value must be one of the entries in availableThemeNames. That list includes the special name System, which makes the style follow the platform color scheme. The comparison ignores case.
Setting this property repolishes all widgets so that they repaint with the new theme. If the name matches no theme, the Style emits a warning and applies no theme.
Access functions:
| QString | themeName() const |
| void | setThemeName(const QString &themeName) |
Notifier signal:
| void | themeNameChanged(const QString &themeName) |
Member Function Documentation
QStyleKitStyle::QStyleKitStyle()
Constructs a QStyleKitStyle with no style loaded.
Use setStylePath() to load a QML Style after construction. Until a Style loads successfully, the widgets use an empty fallback style.
[explicit] QStyleKitStyle::QStyleKitStyle(const QString &filePath)
Constructs a QStyleKitStyle and loads the QML Style at filePath. See the stylePath property for the accepted path forms.
If the path is invalid or the root object of the loaded component is not a Style, QStyleKitStyle emits a warning and the widgets use an empty fallback style until a valid stylePath is set.
[override virtual noexcept] QStyleKitStyle::~QStyleKitStyle()
Destroys the QStyleKitStyle.
QStringList QStyleKitStyle::availableThemeNames() const
Returns the names of all themes that the loaded Style exposes. The list always includes System, and includes Light and Dark when the Style defines those themes, together with any custom themes that the style author defines. Returns an empty list when no style is loaded.
Note: Getter function for property availableThemeNames.
See also customThemeNames() and themeName().
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 availableThemeNames().
[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 does not load, QStyleKitStyle emits a warning, keeps the previously loaded style active, and does not emit stylePathChanged().
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 availableThemeNames(), which includes the special name System for following the platform color scheme. The comparison ignores case.
If no Style is loaded, this function emits a warning and returns without changing the active theme. If a Style is loaded but themeName matches none of its themes, the Style emits a warning and applies no theme.
Note: Setter function for property themeName.
See also themeName() and availableThemeNames().
[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 most recently set for the QML 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 requested theme, or an empty string when no Style is loaded.
When the theme name is System, this function returns System rather than the Light or Dark theme that the platform color scheme resolves to.
Note: Getter function for property themeName.
See also setThemeName() and availableThemeNames().
[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.
