Sur cette page

QStyleKitStyle Class

La classe `QStyleKitStyle` applique un style Qt Labs StyleKit à ` Qt Widgets`. En savoir plus...

En-tête : #include <QStyleKitStyle>
CMake : find_package(Qt6 REQUIRED COMPONENTS LabsStyleKit)
target_link_libraries(mytarget PRIVATE Qt6::LabsStyleKit)
Depuis : Qt 6.12
Hérite de : QCommonStyle

Propriétés

Fonctions publiques

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

Fonctions publiques réimplémentées

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

Signaux

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

Fonctions protégées réimplémentées

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

Description détaillée

QStyleKitStyle est une implémen QStyle e qui utilise un StyleKit Style pour styliser Qt Widgets. Le fichier Style est un fichier QML qui décrit de manière déclarative la conception visuelle (couleurs, tailles, rayons, bordures et autres propriétés) pour chaque type et état de widget. Ces valeurs de propriétés pilotent le dessin, qui est entièrement réalisé à l’aide de QPainter. Qt Quick et le graphe de scène ne jouent aucun rôle dans le rendu.

Cette séparation signifie qu’un même fichier QML Style peut piloter à la fois Qt Quick Controls et Qt Widgets, en partageant une seule définition de conception entre les deux systèmes.

Remarque : StyleKit est un module Qt Labs, et son API est susceptible d’évoluer d’une version de Qt à l’autre.

Chargement d’un style

Un style est un fichier QML dont l’objet racine est un ` Style`. Pour le charger, transmettez le chemin d’accès au fichier au constructeur ou à la méthode ` setStylePath()` :

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

Le style est chargé avec un ` QQmlEngine ` interne appartenant à l’instance `QStyleKitStyle`. Si le chemin d’accès n’est pas valide ou si l’objet racine n’est pas un ` Style`, un avertissement est émis et le style utilise un style de secours par défaut jusqu’à ce qu’un ` stylePath ` valide soit défini.

Thèmes

Un Style peut définir un ou plusieurs themes nommés. Le thème actif est sélectionné via setThemeName() ; la liste des thèmes disponibles est accessible via availableThemeNames. Le nom de thème spécial System fait en sorte que le style suive le jeu de couleurs de la plateforme : lorsque le jeu de couleurs du système d’exploitation change, le thème actif est recréé automatiquement et tous les widgets sont réactualisés.

Mappage entre les widgets et les contrôles StyleKit

Chaque classe ` Qt Widgets ` est mise en correspondance avec un type de contrôle StyleKit, ce qui détermine quelle entrée de contrôle dans le fichier ` Style ` s’applique à celle-ci. Utilisez l’entrée de contrôle correspondante pour configurer les propriétés visuelles de ce type de widget, y compris ses différentes parties telles que l’arrière-plan, l’indicateur, la poignée, etc. Consultez ControlStyleProperties pour obtenir la liste complète des propriétés personnalisables. Les propriétés non définies dans une entrée de contrôle spécifique sont gérées par la hiérarchie des types de contrôle : par exemple, button est gérée par abstractButton, qui est elle-même gérée par control.

Les widgets non répertoriés ci-dessus ne sont pas encore pris en charge par QStyleKitStyle et seront dessinés par QCommonStyle. La prise en charge des widgets restants est prévue pour les prochaines versions. À l’inverse, certaines entrées de contrôle dans StylableControls n’ont pas d’équivalent dans Qt Widgets et ne sont pas appliquées lors de la mise en forme des widgets.

Sous-contrôles au sein d’un widget

Les sous-contrôles distincts au sein d’un widget peuvent être stylisés individuellement, car chacun d’entre eux correspond à une entrée de contrôle distincte dans le fichier Style:

Sous-élémentContrôle StyleKit
QStyledItemDelegate items — le délégué par défaut pour toutes les vues d’éléments Qt, y compris la liste contextuelle « QComboBox »itemDelegate
Ces mêmes éléments, lorsqu'ils sont cochables par l'utilisateur (c'est-à-dire lorsqu'ils affichent un indicateur de sélection)checkDelegate; le contrôle « itemDelegate » est utilisé par défaut pour tout ce qui n’est pas défini explicitement
Onglets individuels dans un QTabBartabButton
QMenu itemsmenuItem
Séparateurs dans un QMenumenuSeparator
QMenuBar élémentsmenuBarItem
Séparateurs dans un QToolBartoolSeparator
Le conteneur de liste déroulante « QComboBox »popup

Limitations connues

QStyleKitStyle est en préversion technique. Les fonctionnalités StyleKit suivantes ne sont actuellement pas prises en charge lorsqu'elles sont utilisées avec Qt Widgets:

  • Ombres — les ombres ne sont pas affichées.
  • Échelle de délégation supérieure à 1,0 sur l’arrière-plan d’un contrôle — un widget ne peut pas s’afficher en dehors de son propre rectangle ; l’arrière-plan mis à l’échelle est donc rogné au niveau du bord du widget. Utilisez margins pour décaler l’arrière-plan vers l’intérieur et lui réserver de l’espace pour qu’il puisse s’étendre. La mise à l’échelle des indicateurs, des poignées et des premiers plans n’est pas affectée.
  • Variations — la configuration d’un « StyleVariation » sur une instance de widget n’est pas encore prise en charge.
  • Contrôles personnalisés — la mise en forme des widgets personnalisés à l’aide de ` CustomControl ` n’est pas encore prise en charge.
  • Délégués personnalisés — la propriété ` delegate ` n’est pas utilisée ; le rendu intégré est toujours appliqué.

La prise en charge de ces fonctionnalités est prévue pour une prochaine version.

Voir également QStyle, QCommonStyle, Qt Labs StyleKit, Style et Theme.

Documentation sur les propriétés

[read-only] availableThemeNames : QStringList

Cette propriété contient la liste des noms de thèmes mis à disposition par le fichier ` Style` chargé.

Cette liste comprend les thèmes intégrés « Light » et « Dark », ainsi que tous les thèmes personnalisés définis par le style.

Fonctions d'accès :

QStringList availableThemeNames() const

Signal de notification :

void availableThemeNamesChanged(const QStringList &availableThemeNames)

[read-only] customThemeNames : QStringList

Cette propriété contient la liste des noms de thèmes personnalisés définis par le fichier « Style » chargé.

Contrairement à ` availableThemeNames`, cette liste exclut les thèmes intégrés ` Light ` et ` Dark ` et ne contient que les thèmes explicitement définis par l'auteur du style. Renvoie une liste vide lorsqu'aucun style n'est chargé.

Fonctions d’accès :

QStringList customThemeNames() const

Signal de notification :

void customThemeNamesChanged(const QStringList &customThemeNames)

Voir également availableThemeNames et themeName.

stylePath : QString

Cette propriété contient le chemin d'accès au fichier d'Style QML associé à ce style.

La valeur est un chemin d'accès à un fichier local ou à un fichier situé dans le système de fichiers de ressources (par exemple, :/styles/MyStyle.qml). Un chemin relatif est résolu par rapport au répertoire de travail de l’application. Le fichier doit contenir un composant QML dont l’objet racine est un ` Style`. La définition de cette propriété recharge le style ; si le nouveau fichier ne peut pas être chargé, le style précédemment chargé est conservé et un avertissement est émis.

Fonctions d’accès :

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

Signal du notificateur :

void stylePathChanged(const QString &stylePath)

themeName : QString

Cette propriété contient le nom du thème actif.

La valeur doit correspondre à l'une des entrées de availableThemeNames, ou au nom spécial System pour respecter la palette de couleurs de la plateforme. La définition de cette propriété met à jour tous les widgets afin qu'ils s'affichent selon le nouveau thème.

Fonctions d'accès :

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

Signal de notification :

void themeNameChanged(const QString &themeName)

Documentation des fonctions membres

QStyleKitStyle::QStyleKitStyle()

Construit un objet `QStyleKitStyle` sans style chargé.

Utilisez setStylePath() pour charger un Style QML après la construction. Tant qu'aucun style n'est chargé, le style utilise un style de secours par défaut.

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

Crée un objet `QStyleKitStyle` et charge l'Style QML disponible à l'adresse filePath.

filePath Il s'agit d'un chemin vers un fichier local ou vers un fichier situé dans le système de fichiers de ressources ; un chemin relatif est résolu par rapport au répertoire de travail de l'application. Si le chemin n'est pas valide ou si l'objet racine du composant chargé n'est pas une Style, un avertissement est émis et le style créé utilise un style de secours par défaut jusqu'à ce qu'une stylePath valide soit définie.

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

Supprime l'QStyleKitStyle.

QStringList QStyleKitStyle::availableThemeNames() const

Renvoie les noms de tous les thèmes exposés par l’ Style chargé, y compris les thèmes intégrés Light et Dark, ainsi que tous les thèmes personnalisés définis par le style. Renvoie une liste vide si aucun style n’est chargé.

Remarque : fonctiongetter pour la propriété availableThemeNames.

Voir également customThemeNames() et themeName().

QStringList QStyleKitStyle::customThemeNames() const

Renvoie les noms des thèmes personnalisés définis par le fichier Style chargé, à l'exception des thèmes intégrés Light et Dark. Renvoie une liste vide si aucun style n'est chargé.

Remarque : fonctiongetter pour la propriété customThemeNames.

Voir aussi availableThemeNames().

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

Réimplémente : 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

Réimplémente : 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

Réimplémente : QCommonStyle::drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *widget) const.

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

Réimplémente : QObject::event(QEvent *e).

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

Réimplémente : 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

Réimplémente : 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

Réimplémente : QCommonStyle::pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt, const QWidget *widget) const.

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

Réimplémente : QCommonStyle::polish(QApplication *app).

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

Réimplémente : QCommonStyle::polish(QPalette &pal).

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

Réimplémente : QCommonStyle::polish(QWidget *widget).

void QStyleKitStyle::setStylePath(const QString &filePath)

Charge l'Style QML disponible à l'adresse filePath et l'applique à tous les widgets.

filePath Il s'agit d'un chemin d'accès à un fichier local ou d'un chemin d'accès à un fichier dans le système de fichiers de ressources ; voir la propriété stylePath pour connaître les formats acceptés. Si ce chemin est identique à celui de l'stylePath actuel, cette fonction ne fait rien. Si le nouveau style ne peut pas être chargé, le style précédemment chargé reste actif et un avertissement est émis ; la méthode stylePathChanged() est tout de même appelée pour refléter la modification de la valeur de la propriété.

Remarque : fonction de définition (setter ) pour la propriété stylePath.

Voir également stylePath().

void QStyleKitStyle::setThemeName(const QString &themeName)

Active le thème nommé « themeName ».

themeName Doit correspondre à l'une des entrées de availableThemeNames(), ou au nom spécial System pour suivre le schéma de couleurs de la plateforme. Si aucun fichier Style n’a été chargé, cette fonction émet un avertissement et retourne sans modifier le thème actif.

Remarque : fonctionde définition de la propriété themeName.

Voir également themeName() et availableThemeNames().

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

Réimplémente : QCommonStyle::sizeFromContents(QStyle::ContentsType contentsType, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget) const.

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

Réimplémente : QStyle::standardPalette() const.

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

Réimplémente : QCommonStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt, const QWidget *widget, QStyleHintReturn *hret) const.

QString QStyleKitStyle::stylePath() const

Renvoie le chemin d'accès du fichier « Style » actuellement chargé.

Remarque : fonctionde lecture pour la propriété stylePath.

Voir aussi setStylePath().

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

Réimplémente : 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

Réimplémente : QCommonStyle::subElementRect(QStyle::SubElement sr, const QStyleOption *opt, const QWidget *widget) const.

QString QStyleKitStyle::themeName() const

Renvoie le nom du thème actuellement actif, ou une chaîne vide si aucun thème n'a été chargé ( Style ).

Remarque : fonction de lecture (getter ) pour la propriété themeName.

Voir aussi setThemeName() et availableThemeNames().

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

Réimplémente : QCommonStyle::unpolish(QApplication *application).

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

Réimplémente : 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.