QStyleOption Class
QStyleOption 类用于存储QStyle 函数所使用的参数。更多内容...
| 头文件： | #include <QStyleOption> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 被继承类： | 16 种类型QStyleOptionButton、QStyleOptionComplex 、QStyleOptionDockWidget 、QStyleOptionFocusRect 、QStyleOptionFrame 、QStyleOptionGraphicsItem 、QStyleOptionHeader 、QStyleOptionMenuItem 、QStyleOptionProgressBar 、QStyleOptionRubberBand 、QStyleOptionTab 、QStyleOptionTabBarBase 、QStyleOptionTabWidgetFrame 、QStyleOptionToolBar 、QStyleOptionToolBox ，以及QStyleOptionViewItem |
公共类型
| enum | OptionType { SO_Button, SO_ComboBox, SO_Complex, SO_Default, SO_DockWidget, …, SO_ComplexCustomBase } |
| enum | StyleOptionType { Type } |
| enum | StyleOptionVersion { Version } |
公共函数
| QStyleOption(int version = QStyleOption::Version, int type = SO_Default) | |
| QStyleOption(const QStyleOption &other) | |
| ~QStyleOption() | |
| void | initFrom(const QWidget *widget) |
| QStyleOption & | operator=(const QStyleOption &other) |
公共变量
| 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) |
详细说明
QStyleOption 及其子类包含了QStyle 函数绘制图形元素所需的所有信息。
出于性能考虑，成员函数较少，且对成员变量的访问是直接的（即使用 `. ` 或 `-> ` 运算符）。这使得这些结构体使用起来非常简单，同时也强调了它们只是样式函数所使用的参数。
QStyle 函数的调用者通常会在栈上创建 QStyleOption 对象。加之 Qt 广泛采用对QString 、QPalette 和QColor 等类型的隐式共享机制，可确保不会发生不必要的内存分配。
以下代码片段演示了如何使用特定的 QStyleOption 子类来绘制一个按钮：
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);
}在本例中，控件是QStyle::CE_PushButton ，根据QStyle::drawControl()的文档，对应的类是QStyleOptionButton 。
在重写那些接受 QStyleOption 参数的QStyle 函数时，通常需要将 QStyleOption 强制转换为子类。为确保安全，可以使用qstyleoption_cast() 来验证指针类型是否正确。例如：
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) {
// ...
}
}
// ...
}如果option 所指向的对象类型不正确，qstyleoption_cast() 函数将返回 0。
另请参阅 QStyle 和QStylePainter 。
成员类型文档
enum QStyleOption::OptionType
该枚举由QStyleOption 、其子类以及qstyleoption_cast()在内部使用，用于确定样式选项的类型。通常情况下，您无需关注这一点，除非您想创建自己的QStyleOption 子类和自定义样式。
| 常量 | 值 | 描述 |
|---|---|---|
QStyleOption::SO_Button | 2 | QStyleOptionButton |
QStyleOption::SO_ComboBox | 0xf0004 | QStyleOptionComboBox |
QStyleOption::SO_Complex | 0xf0000 | QStyleOptionComplex |
QStyleOption::SO_Default | 0 | QStyleOption |
QStyleOption::SO_DockWidget | 9 | QStyleOptionDockWidget |
QStyleOption::SO_FocusRect | 1 | QStyleOptionFocusRect |
QStyleOption::SO_Frame | 5 | QStyleOptionFrame |
QStyleOption::SO_GraphicsItem | 15 | QStyleOptionGraphicsItem |
QStyleOption::SO_GroupBox | 0xf0006 | QStyleOptionGroupBox |
QStyleOption::SO_Header | 8 | QStyleOptionHeader |
QStyleOption::SO_MenuItem | 4 | QStyleOptionMenuItemV2 |
QStyleOption::SO_ProgressBar | 6 | QStyleOptionProgressBar |
QStyleOption::SO_RubberBand | 13 | QStyleOptionRubberBand |
QStyleOption::SO_SizeGrip | 0xf0007 | QStyleOptionSizeGrip |
QStyleOption::SO_Slider | 0xf0001 | QStyleOptionSlider |
QStyleOption::SO_SpinBox | 0xf0002 | QStyleOptionSpinBox |
QStyleOption::SO_Tab | 3 | QStyleOptionTab |
QStyleOption::SO_TabBarBase | 12 | QStyleOptionTabBarBase |
QStyleOption::SO_TabWidgetFrame | 11 | QStyleOptionTabWidgetFrame |
QStyleOption::SO_TitleBar | 0xf0005 | QStyleOptionTitleBar |
QStyleOption::SO_ToolBar | 14 | QStyleOptionToolBar |
QStyleOption::SO_ToolBox | 7 | QStyleOptionToolBox |
QStyleOption::SO_ToolButton | 0xf0003 | QStyleOptionToolButton |
QStyleOption::SO_ViewItem | 10 | QStyleOptionViewItem （用于 Interviews） |
以下值用于自定义控件：
| 常量 | 值 | 描述 |
|---|---|---|
QStyleOption::SO_CustomBase | 0xf00 | 保留给自定义 QStyleOptions 使用；所有自定义控件的值必须大于此值 |
QStyleOption::SO_ComplexCustomBase | 0xf000000 | 保留给自定义 QStyleOptions 使用；所有自定义复合控件的值必须大于此值 |
另请参阅 type 。
enum QStyleOption::StyleOptionType
该枚举用于存储有关样式选项类型的信息，并针对每个QStyleOption 子类分别定义。
| 常量 | 常量值 | 描述 |
|---|---|---|
QStyleOption::Type | SO_Default | 提供的样式选项的类型（对于此类而言为SO_Default ）。 |
该类型由QStyleOption 、其子类以及qstyleoption_cast()在内部使用，用于确定样式选项的类型。通常情况下，除非您想创建自己的QStyleOption 子类和自己的样式，否则无需担心这一点。
另请参阅 StyleOptionVersion 。
enum QStyleOption::StyleOptionVersion
该枚举用于存储样式选项的版本信息，并针对每个QStyleOption 子类分别定义。
| 常量 | 常量值 | 描述 |
|---|---|---|
QStyleOption::Version | 1 | 1 |
QStyleOption 的子类使用该版本号来实现扩展，同时保持兼容性。如果您使用qstyleoption_cast()，通常无需检查该值。
另请参阅 StyleOptionType 。
成员函数文档
QStyleOption::QStyleOption(int version = QStyleOption::Version, int type = SO_Default)
根据指定的version 和type 创建一个QStyleOption。
对于 QStyleOption 而言，版本号没有特殊含义；子类可以使用它来区分同一选项类型的不同版本。
state 成员变量被初始化为QStyle::State_None 。
QStyleOption::QStyleOption(const QStyleOption &other)
创建other 的副本。
[noexcept] QStyleOption::~QStyleOption()
删除此样式选项对象。
void QStyleOption::initFrom(const QWidget *widget)
根据指定的widget 初始化成员变量state 、direction 、rect 、palette 、fontMetrics 和styleObject 。
这是一个便捷函数；成员变量也可以手动初始化。
另请参阅 QWidget::layoutDirection()、QWidget::rect()、QWidget::palette() 和QWidget::fontMetrics()。
QStyleOption &QStyleOption::operator=(const QStyleOption &other)
将other 分配给QStyleOption 。
成员变量文档
Qt::LayoutDirection QStyleOption::direction
该变量存储在控件中绘制文本时应使用的文本布局方向
默认情况下，布局方向为Qt::LeftToRight 。
另请参阅 initFrom()。
QFontMetrics QStyleOption::fontMetrics
该变量存储在控件中绘制文本时应使用的字体度量值
默认情况下，将使用应用程序的默认字体。
另请参阅 initFrom()。
QPalette QStyleOption::palette
该变量存储在绘制控件时应使用的调色板
默认情况下，将使用应用程序的默认调色板。
另请参阅 initFrom()。
QRect QStyleOption::rect
该变量存储用于各种计算和绘制的区域
对于不同类型的控件，该变量的含义可能有所不同。例如，对于QStyle::CE_PushButton 控件，它表示整个按钮的矩形区域；而对于QStyle::CE_PushButtonLabel 控件，它仅表示按键标签所在的区域。
默认值是一个空矩形，即宽度和高度均设为 0 的矩形。
另请参阅 initFrom()。
QStyle::State QStyleOption::state
该变量存储在绘制控件时使用的样式标志
默认值为QStyle::State_None 。
另请参阅 initFrom()、QStyle::drawPrimitive()、QStyle::drawControl()、QStyle::drawComplexControl() 和QStyle::State 。
QObject *QStyleOption::styleObject
该变量存储要应用样式的对象
内置样式支持以下类型：QWidget 、QGraphicsObject 和QQuickItem 。
另请参阅 initFrom()。
int QStyleOption::type
该变量存储样式选项的选项类型
默认值为SO_Default 。
另请参阅 OptionType 。
int QStyleOption::version
该变量存储样式选项的版本号
子类可以使用该值来实现扩展，同时保持兼容性。如果使用qstyleoption_cast()函数，通常无需检查该值。
默认值为 1。
相关的非成员
template <typename T> T qstyleoption_cast(const QStyleOption *option)
根据给定的option 的type 和version ，返回T或nullptr 。
示例：
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) {
// ...
}
}
// ...
}另请参阅 QStyleOption::type 和QStyleOption::version 。
template <typename T> T qstyleoption_cast(QStyleOption *option)
根据给定的option 的类型，返回T或nullptr 。
这是一个重载函数。
© 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.
