Sur cette page

QStyleOption Class

La classe `QStyleOption` stocke les paramètres utilisés par les fonctions ` QStyle `. En savoir plus...

En-tête : #include <QStyleOption>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets
Hérité par :
16 types

QStyleOptionButton, QStyleOptionComplex, QStyleOptionDockWidget, QStyleOptionFocusRect, QStyleOptionFrame, QStyleOptionGraphicsItem, QStyleOptionHeader, QStyleOptionMenuItem, QStyleOptionProgressBar, QStyleOptionRubberBand, QStyleOptionTab, QStyleOptionTabBarBase, QStyleOptionTabWidgetFrame, QStyleOptionToolBar, QStyleOptionToolBox, et QStyleOptionViewItem

Types publics

enum OptionType { SO_Button, SO_ComboBox, SO_Complex, SO_Default, SO_DockWidget, …, SO_ComplexCustomBase }
enum StyleOptionType { Type }
enum StyleOptionVersion { Version }

Fonctions publiques

QStyleOption(int version = QStyleOption::Version, int type = SO_Default)
QStyleOption(const QStyleOption &other)
~QStyleOption()
void initFrom(const QWidget *widget)
QStyleOption &operator=(const QStyleOption &other)

Variables publiques

Qt::LayoutDirection direction
QFontMetrics fontMetrics
QPalette palette
QRect rect
QStyle::State state
QObject *styleObject
int type
int version
T qstyleoption_cast(const QStyleOption *option)
T qstyleoption_cast(QStyleOption *option)

Description détaillée

QStyleOption et ses sous-classes contiennent toutes les informations dont les fonctions d'QStyle s ont besoin pour dessiner un élément graphique.

Pour des raisons de performances, il y a peu de fonctions membres et l'accès aux variables membres est direct (c'est-à-dire à l'aide des opérateurs . ou -> ). Cela rend ces structures simples à utiliser et souligne le fait qu'il s'agit simplement de paramètres utilisés par les fonctions de style.

L'appelant d'une fonction de type QStyle crée généralement des objets QStyleOption sur la pile. Combiné à l'utilisation intensive par Qt du partage implicite pour des types tels que QString, QPalette et QColor, cela garantit qu'aucune allocation de mémoire inutile n'a lieu.

L'extrait de code suivant montre comment utiliser une sous-classe spécifique de `QStyleOption` pour dessiner un bouton :

void MyPushButton::paintEvent(QPaintEvent *)
{
    QStyleOptionButton option;
    option.initFrom(this);
    option.state = isDown() ? QStyle::State_Sunken : QStyle::State_Raised;
    if (isDefault())
        option.features |= QStyleOptionButton::DefaultButton;
    option.text = text();
    option.icon = icon();

    QPainter painter(this);
    style()->drawControl(QStyle::CE_PushButton, &option, &painter, this);
}

Dans notre exemple, le contrôle est un « QStyle::CE_PushButton », et selon la documentation de la fonction QStyle::drawControl(), la classe correspondante est QStyleOptionButton.

Lors de la réimplémentation des fonctions de ` QStyle ` qui prennent un paramètre `QStyleOption`, il est souvent nécessaire de convertir le `QStyleOption` en une sous-classe. Par mesure de sécurité, vous pouvez utiliser ` qstyleoption_cast()` pour vous assurer que le type du pointeur est correct. Par exemple :

void MyStyle::drawPrimitive(PrimitiveElement element,
                            const QStyleOption *option,
                            QPainter *painter,
                            const QWidget *widget)
{
    if (element == PE_FrameFocusRect) {
        const QStyleOptionFocusRect *focusRectOption =
                qstyleoption_cast<const QStyleOptionFocusRect *>(option);
        if (focusRectOption) {
            // ...
        }
    }
    // ...
}

La fonction qstyleoption_cast() renvoie 0 si l’objet pointé par option n’est pas du type correct.

Voir également QStyle et QStylePainter.

Documentation sur les types de membres

enum QStyleOption::OptionType

Cette énumération est utilisée en interne par QStyleOption, ses sous-classes et qstyleoption_cast() pour déterminer le type d'option de style. En général, vous n'avez pas à vous en soucier, sauf si vous souhaitez créer votre propre sous-classe de QStyleOption et vos propres styles.

ConstanteValeurDescription
QStyleOption::SO_Button2QStyleOptionButton
QStyleOption::SO_ComboBox0xf0004QStyleOptionComboBox
QStyleOption::SO_Complex0xf0000QStyleOptionComplex
QStyleOption::SO_Default0QStyleOption
QStyleOption::SO_DockWidget9QStyleOptionDockWidget
QStyleOption::SO_FocusRect1QStyleOptionFocusRect
QStyleOption::SO_Frame5QStyleOptionFrame
QStyleOption::SO_GraphicsItem15QStyleOptionGraphicsItem
QStyleOption::SO_GroupBox0xf0006QStyleOptionGroupBox
QStyleOption::SO_Header8QStyleOptionHeader
QStyleOption::SO_MenuItem4QStyleOptionMenuItemV2
QStyleOption::SO_ProgressBar6QStyleOptionProgressBar
QStyleOption::SO_RubberBand13QStyleOptionRubberBand
QStyleOption::SO_SizeGrip0xf0007QStyleOptionSizeGrip
QStyleOption::SO_Slider0xf0001QStyleOptionSlider
QStyleOption::SO_SpinBox0xf0002QStyleOptionSpinBox
QStyleOption::SO_Tab3QStyleOptionTab
QStyleOption::SO_TabBarBase12QStyleOptionTabBarBase
QStyleOption::SO_TabWidgetFrame11QStyleOptionTabWidgetFrame
QStyleOption::SO_TitleBar0xf0005QStyleOptionTitleBar
QStyleOption::SO_ToolBar14QStyleOptionToolBar
QStyleOption::SO_ToolBox7QStyleOptionToolBox
QStyleOption::SO_ToolButton0xf0003QStyleOptionToolButton
QStyleOption::SO_ViewItem10QStyleOptionViewItem (utilisées dans les entretiens)

Les valeurs suivantes sont utilisées pour les contrôles personnalisés :

ConstanteValeurDescription
QStyleOption::SO_CustomBase0xf00Réservé aux QStyleOptions personnalisées ; toutes les valeurs des contrôles personnalisés doivent être supérieures à cette valeur
QStyleOption::SO_ComplexCustomBase0xf000000Réservé aux QStyleOptions personnalisées ; toutes les valeurs des contrôles complexes personnalisés doivent être supérieures à cette valeur

Voir aussi type.

enum QStyleOption::StyleOptionType

Cette énumération sert à stocker des informations sur le type de l'option de style et est définie pour chaque sous-classe de ` QStyleOption `.

ConstanteValeurDescription
QStyleOption::TypeSO_DefaultLe type de l’option de style fournie (SO_Default pour cette classe).

Ce type est utilisé en interne par ` QStyleOption`, ses sous-classes et la méthode ` qstyleoption_cast()` pour déterminer le type d’option de style. En général, vous n’avez pas à vous en soucier, sauf si vous souhaitez créer votre propre sous-classe de ` QStyleOption ` et vos propres styles.

Voir également StyleOptionVersion.

enum QStyleOption::StyleOptionVersion

Cette énumération sert à stocker des informations sur la version de l'option de style et est définie pour chaque sous-classe de ` QStyleOption `.

ConstanteValeurDescription
QStyleOption::Version11

Cette version est utilisée par les sous-classes de ` QStyleOption ` pour implémenter des extensions sans rompre la compatibilité. Si vous utilisez ` qstyleoption_cast()`, vous n’avez généralement pas besoin de la vérifier.

Voir aussi StyleOptionType.

Documentation sur les fonctions membres

QStyleOption::QStyleOption(int version = QStyleOption::Version, int type = SO_Default)

Crée un objet QStyleOption avec les paramètres ` version ` et ` type` spécifiés.

La version n'a pas de signification particulière pour QStyleOption ; elle peut être utilisée par les sous-classes pour distinguer différentes versions d'un même type d'option.

La variable membre ` state ` est initialisée à ` QStyle::State_None`.

Voir également version et type.

QStyleOption::QStyleOption(const QStyleOption &other)

Crée une copie de other.

[noexcept] QStyleOption::~QStyleOption()

Supprime cet objet d'option de style.

void QStyleOption::initFrom(const QWidget *widget)

Initialise les variables membres state, direction, rect, palette, fontMetrics et styleObject en fonction de la valeur spécifiée dans widget.

Il s’agit d’une fonction de commodité ; les variables membres peuvent également être initialisées manuellement.

Voir également QWidget::layoutDirection(), QWidget::rect(), QWidget::palette() et QWidget::fontMetrics().

QStyleOption &QStyleOption::operator=(const QStyleOption &other)

Attribuez l'other à cette QStyleOption.

Documentation sur les variables membres

Qt::LayoutDirection QStyleOption::direction

Cette variable contient le sens de mise en page du texte à utiliser lors de l'affichage du texte dans le contrôle

Par défaut, la direction de mise en page est Qt::LeftToRight.

Voir également initFrom().

QFontMetrics QStyleOption::fontMetrics

Cette variable contient les paramètres de police à utiliser lors de l'affichage du texte dans le contrôle

Par défaut, c'est la police par défaut de l'application qui est utilisée.

Voir également initFrom().

QPalette QStyleOption::palette

Cette variable contient la palette à utiliser pour colorer le contrôle

Par défaut, c'est la palette par défaut de l'application qui est utilisée.

Voir également initFrom().

QRect QStyleOption::rect

Cette variable contient la zone à utiliser pour divers calculs et opérations de dessin

Cela peut avoir des significations différentes selon les types d’éléments. Par exemple, pour un élément de type « QStyle::CE_PushButton », il s’agirait du rectangle correspondant à l’ensemble du bouton, tandis que pour un élément de type « QStyle::CE_PushButtonLabel », il s’agirait uniquement de la zone correspondant au libellé du bouton.

La valeur par défaut est un rectangle nul, c'est-à-dire un rectangle dont la largeur et la hauteur sont toutes deux définies sur 0.

Voir également initFrom().

QStyle::State QStyleOption::state

Cette variable contient les indicateurs de style utilisés lors du tracé du contrôle

La valeur par défaut est QStyle::State_None.

Voir également initFrom(), QStyle::drawPrimitive(), QStyle::drawControl(), QStyle::drawComplexControl() et QStyle::State.

QObject *QStyleOption::styleObject

Cette variable contient l'objet dont le style est défini

Les styles intégrés prennent en charge les types suivants : QWidget, QGraphicsObject et QQuickItem.

Voir également initFrom().

int QStyleOption::type

Cette variable contient le type de l'option de style

La valeur par défaut est « SO_Default ».

Voir également OptionType.

int QStyleOption::version

Cette variable contient la version de l'option de style

Cette valeur peut être utilisée par les sous-classes pour implémenter des extensions sans rompre la compatibilité. Si vous utilisez la fonction qstyleoption_cast(), vous n’avez normalement pas besoin de la vérifier.

La valeur par défaut est 1.

Éléments non membres associés

template <typename T> T qstyleoption_cast(const QStyleOption *option)

Renvoie un T ou un nullptr, selon les propriétés type et version de l’ option donné.

Exemple :

void MyStyle::drawPrimitive(PrimitiveElement element,
                            const QStyleOption *option,
                            QPainter *painter,
                            const QWidget *widget)
{
    if (element == PE_FrameFocusRect) {
        const QStyleOptionFocusRect *focusRectOption =
                qstyleoption_cast<const QStyleOptionFocusRect *>(option);
        if (focusRectOption) {
            // ...
        }
    }
    // ...
}

Voir également QStyleOption::type et QStyleOption::version.

template <typename T> T qstyleoption_cast(QStyleOption *option)

Renvoie un T ou un ` nullptr `, selon le type de l'option.

Il s'agit d'une fonction surchargée.

© 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.