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, andQStyleOptionViewItem |
公共类型
| 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(QStyleOption *option) |
| T | qstyleoption_cast(const QStyleOption *option) |
详细说明
QStyleOption 及其子类包含QStyle 函数绘制图形元素所需的所有信息。
出于性能考虑，成员函数很少，对成员变量的访问是直接的（即使用. 或-> 操作符）。这使得这些结构使用起来非常简单，并强调这些结构只是样式函数使用的参数。
QStyle 函数的调用者通常会在堆栈中创建 QStyleOption 对象。这与 Qt XML 对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 | QStyleOptionMenuItem |
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 (用于访谈） |
以下值用于自定义控件：
| 常量 | 值 | 说明 |
|---|---|---|
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(QStyleOption *option)
这是一个重载函数。
根据给定option 的类型，返回一个 T 或nullptr 。
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) { // ... } } // ... }
© 2025 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.
