QStyleOption Class

The QStyleOption class stores the parameters used by QStyle functions. More...

Header: #include <QStyleOption>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Inherited By:
16 types

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

Public Types

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

Public Functions

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

Public Variables

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)

Detailed Description

QStyleOption and its subclasses contain all the information that QStyle functions need to draw a graphical element.

For performance reasons, there are few member functions and the access to the member variables is direct (i.e., using the . or -> operator). This makes the structures straightforward to use and emphasizes that these are simply parameters used by the style functions.

The caller of a QStyle function usually creates QStyleOption objects on the stack. This combined with Qt's extensive use of implicit sharing for types such as QString, QPalette, and QColor ensures that no memory allocation needlessly takes place.

The following code snippet shows how to use a specific QStyleOption subclass to paint a push button:

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);
}

In our example, the control is a QStyle::CE_PushButton, and according to the QStyle::drawControl() documentation the corresponding class is QStyleOptionButton.

When reimplementing QStyle functions that take a QStyleOption parameter, you often need to cast the QStyleOption to a subclass. For safety, you can use qstyleoption_cast() to ensure that the pointer type is correct. For example:

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) {
            // ...
        }
    }
    // ...
}

The qstyleoption_cast() function will return 0 if the object to which option points is not of the correct type.

See also QStyle and QStylePainter.

Member Type Documentation

enum QStyleOption::OptionType

This enum is used internally by QStyleOption, its subclasses, and qstyleoption_cast() to determine the type of style option. In general you do not need to worry about this unless you want to create your own QStyleOption subclass and your own styles.

ConstantValueDescription
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_MenuItem4QStyleOptionMenuItem
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 (used in Interviews)

The following values are used for custom controls:

ConstantValueDescription
QStyleOption::SO_CustomBase0xf00Reserved for custom QStyleOptions; all custom controls values must be above this value
QStyleOption::SO_ComplexCustomBase0xf000000Reserved for custom QStyleOptions; all custom complex controls values must be above this value

See also type.

enum QStyleOption::StyleOptionType

This enum is used to hold information about the type of the style option, and is defined for each QStyleOption subclass.

ConstantValueDescription
QStyleOption::TypeSO_DefaultThe type of style option provided (SO_Default for this class).

The type is used internally by QStyleOption, its subclasses, and qstyleoption_cast() to determine the type of style option. In general you do not need to worry about this unless you want to create your own QStyleOption subclass and your own styles.

See also StyleOptionVersion.

enum QStyleOption::StyleOptionVersion

This enum is used to hold information about the version of the style option, and is defined for each QStyleOption subclass.

ConstantValueDescription
QStyleOption::Version11

The version is used by QStyleOption subclasses to implement extensions without breaking compatibility. If you use qstyleoption_cast(), you normally do not need to check it.

See also StyleOptionType.

Member Function Documentation

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

Constructs a QStyleOption with the specified version and type.

The version has no special meaning for QStyleOption; it can be used by subclasses to distinguish between different version of the same option type.

The state member variable is initialized to QStyle::State_None.

See also version and type.

QStyleOption::QStyleOption(const QStyleOption &other)

Constructs a copy of other.

[noexcept] QStyleOption::~QStyleOption()

Destroys this style option object.

void QStyleOption::initFrom(const QWidget *widget)

Initializes the state, direction, rect, palette, fontMetrics and styleObject member variables based on the specified widget.

This is a convenience function; the member variables can also be initialized manually.

See also QWidget::layoutDirection(), QWidget::rect(), QWidget::palette(), and QWidget::fontMetrics().

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

Assign other to this QStyleOption.

Member Variable Documentation

Qt::LayoutDirection QStyleOption::direction

This variable holds the text layout direction that should be used when drawing text in the control

By default, the layout direction is Qt::LeftToRight.

See also initFrom().

QFontMetrics QStyleOption::fontMetrics

This variable holds the font metrics that should be used when drawing text in the control

By default, the application's default font is used.

See also initFrom().

QPalette QStyleOption::palette

This variable holds the palette that should be used when painting the control

By default, the application's default palette is used.

See also initFrom().

QRect QStyleOption::rect

This variable holds the area that should be used for various calculations and painting

This can have different meanings for different types of elements. For example, for a QStyle::CE_PushButton element it would be the rectangle for the entire button, while for a QStyle::CE_PushButtonLabel element it would be just the area for the push button label.

The default value is a null rectangle, i.e. a rectangle with both the width and the height set to 0.

See also initFrom().

QStyle::State QStyleOption::state

This variable holds the style flags that are used when drawing the control

The default value is QStyle::State_None.

See also initFrom(), QStyle::drawPrimitive(), QStyle::drawControl(), QStyle::drawComplexControl(), and QStyle::State.

QObject *QStyleOption::styleObject

This variable holds the object being styled

The built-in styles support the following types: QWidget, QGraphicsObject and QQuickItem.

See also initFrom().

int QStyleOption::type

This variable holds the option type of the style option

The default value is SO_Default.

See also OptionType.

int QStyleOption::version

This variable holds the version of the style option

This value can be used by subclasses to implement extensions without breaking compatibility. If you use the qstyleoption_cast() function, you normally do not need to check it.

The default value is 1.

Related Non-Members

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

Returns a T or nullptr depending on the type and version of the given option.

Example:

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) {
            // ...
        }
    }
    // ...
}

See also QStyleOption::type and QStyleOption::version.

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

This is an overloaded function.

Returns a T or nullptr depending on the type of the given option.

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