PySide6.QtLabsStyleKit.QStyleKitStyle

class QStyleKitStyle

The QStyleKitStyle class applies a Qt-Labs-StyleKit style to Qt Widgets. More…

Inheritance diagram of PySide6.QtLabsStyleKit.QStyleKitStyle

Synopsis

Properties

Methods

Signals

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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() :

style = QStyleKitStyle(":/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 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.

Qt Widgets class

StyleKit control

QPushButton (flat)

flatButton

QPushButton

button

QCheckBox

checkBox

QRadioButton

radioButton

QComboBox

comboBox

QSlider

slider

QScrollBar

scrollBar

QSpinBox, QDoubleSpinBox

spinBox

QProgressBar

progressBar

QLineEdit

textField

QTextEdit, QPlainTextEdit

textArea

QTabBar

tabBar

QTabWidget

page

QToolBar

toolBar

QToolButton

toolButton

QGroupBox

groupBox

QFrame

frame

QLabel

label

QMenu

menu

QMenuBar

menuBar

Everything else

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

Qt-Labs-StyleKit Style Theme

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property availableThemeNamesᅟ: list of strings

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:
property customThemeNamesᅟ: list of strings

This property holds the list of custom theme names defined by the loaded Style ..

Unlike availableThemeNames() , 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:
property stylePathᅟ: str

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:
property themeNameᅟ: str

This property holds the name of the active theme..

The value must be one of the entries in availableThemeNames() , 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:
__init__()

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.

__init__(filePath)
Parameters:

filePath – str

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.

availableThemeNames()
Return type:

list of strings

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.

Getter of property availableThemeNamesᅟ .

availableThemeNamesChanged(availableThemeNames)
Parameters:

availableThemeNames – list of strings

Notification signal of property availableThemeNamesᅟ .

customThemeNames()
Return type:

list of strings

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.

Getter of property customThemeNamesᅟ .

customThemeNamesChanged(customThemeNames)
Parameters:

customThemeNames – list of strings

Notification signal of property customThemeNamesᅟ .

setStylePath(filePath)
Parameters:

filePath – str

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.

See also

stylePath()

Setter of property stylePathᅟ .

setThemeName(themeName)
Parameters:

themeName – str

Activates the theme named themeName.

themeName must be one of the entries in availableThemeNames() , 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.

Setter of property themeNameᅟ .

stylePath()
Return type:

str

Returns the path of the currently loaded Style file.

See also

setStylePath()

Getter of property stylePathᅟ .

stylePathChanged(stylePath)
Parameters:

stylePath – str

Notification signal of property stylePathᅟ .

themeName()
Return type:

str

Returns the name of the currently active theme, or an empty string if no Style has been loaded.

Getter of property themeNameᅟ .

themeNameChanged(themeName)
Parameters:

themeName – str

Notification signal of property themeNameᅟ .