QStyle Class

./myapplication -style windows

void MyWidget::paintEvent(QPaintEvent * /* event */)
{
    QPainter painter(this);

    QStyleOptionFocusRect option;
    option.initFrom(this);
    option.backgroundColor = palette().color(QPalette::Window);

    style()->drawPrimitive(QStyle::PE_FrameFocusRect, &option, &painter, this);
}

    QStylePainter painter(this);
    ...
painter.drawPrimitive(QStyle::PE_FrameFocusRect, option);

QPainter painter(this);
    ...
style()->drawPrimitive(QStyle::PE_FrameFocusRect, &option, &painter, this);

class CustomStyle : public QProxyStyle
{
    Q_OBJECT

public:
    explicit CustomStyle(const QWidget *widget = nullptr);
    ~CustomStyle() {}

    void drawPrimitive(PrimitiveElement element, const QStyleOption *option,
                       QPainter *painter, const QWidget *widget) const override;
};

void CustomStyle::drawPrimitive(PrimitiveElement element, const QStyleOption *option,
                                QPainter *painter, const QWidget *widget) const
{
    if (element == PE_IndicatorSpinUp || element == PE_IndicatorSpinDown) {
        QPolygon points(3);
        int x = option->rect.x();
        int y = option->rect.y();
        int w = option->rect.width() / 2;
        int h = option->rect.height() / 2;
        x += (option->rect.width() - w) / 2;
        y += (option->rect.height() - h) / 2;

        if (element == PE_IndicatorSpinUp) {
            points[0] = QPoint(x, y + h);
            points[1] = QPoint(x + w, y + h);
            points[2] = QPoint(x + w / 2, y);
        } else { // PE_SpinBoxDown
            points[0] = QPoint(x, y);
            points[1] = QPoint(x + w, y);
            points[2] = QPoint(x + w / 2, y + h);
        }

        if (option->state & State_Enabled) {
            painter->setPen(option->palette.mid().color());
            painter->setBrush(option->palette.buttonText());
        } else {
            painter->setPen(option->palette.buttonText().color());
            painter->setBrush(option->palette.mid());
        }
        painter->drawPolygon(points);
    } else {
        QProxyStyle::drawPrimitive(element, option, painter, widget);
    }
}

const QSpinBox *spinBox = qobject_cast<const QSpinBox *>(widget);
if (spinBox) {
    //...
}

#include <QtWidgets>

#include "customstyle.h"

int main(int argc, char *argv[])
{
    QApplication::setStyle(new CustomStyle);
    QApplication app(argc, argv);
    QSpinBox spinBox;
    spinBox.show();
    return app.exec();
}

./myapplication -style custom

switch (element) {
    case (PE_PanelItemViewItem): {
        painter->save();

        QPoint topLeft = option->rect.topLeft();
        QPoint bottomRight = option->rect.topRight();
        QLinearGradient backgroundGradient(topLeft, bottomRight);
        backgroundGradient.setColorAt(0.0, QColor(Qt::yellow).lighter(190));
        backgroundGradient.setColorAt(1.0, Qt::white);
        painter->fillRect(option->rect, QBrush(backgroundGradient));

        painter->restore();
    break;
    }
    default:
        QProxyStyle::drawPrimitive(element, option, painter, widget);
}

成员函数文档

QStyle::QStyle()

创建一个样式对象。

[virtual noexcept] QStyle::~QStyle()

销毁样式对象。

[static] QRect QStyle::alignedRect(Qt::LayoutDirection direction, Qt::Alignment alignment, const QSize &size, const QRect &rectangle)

返回一个新的矩形，其size 属性为指定值，并根据指定的alignment 和direction ，与给定的rectangle 对齐。

int QStyle::combinedLayoutSpacing(QSizePolicy::ControlTypes controls1, QSizePolicy::ControlTypes controls2, Qt::Orientation orientation, QStyleOption *option = nullptr, QWidget *widget = nullptr) const

返回在布局中controls1 和controls2 之间应使用的间距。orientation 指定控件是并排布局还是垂直堆叠。option 参数可用于传递有关父控件的额外信息。widget 参数是可选的，当option 为nullptr 时也可使用该参数。

controls1 且 `controls2 ` 是零个或多个 `control types` 的“或”组合。

该函数由布局系统调用。仅当PM_LayoutHorizontalSpacing 或PM_LayoutVerticalSpacing 返回负值时才会使用。

另请参阅 layoutSpacing()。

[pure virtual] void QStyle::drawComplexControl(QStyle::ComplexControl control, const QStyleOptionComplex *option, QPainter *painter, const QWidget *widget = nullptr) const

使用提供的painter ，并根据option 中指定的样式选项，绘制给定的control 。

widget 参数是可选的，可用于辅助绘制该控件。

option 参数是一个指向QStyleOptionComplex 对象的指针，该对象可通过qstyleoption_cast()函数转换为正确的子类。请注意，指定option 的rect 成员必须为逻辑坐标。此函数的重写版本应在调用drawPrimitive()或drawControl()函数之前，使用visualRect()将逻辑坐标转换为屏幕坐标。

下表列出了复合控件及其关联的样式选项子类。样式选项包含绘制控件所需的所有参数，包括QStyleOption::state ，该参数包含绘制时使用的style flags 。该表还描述了将给定的option 转换为相应子类时设置的标志。

另请参阅 drawPrimitive() 和drawControl()。

[pure virtual] void QStyle::drawControl(QStyle::ControlElement element, const QStyleOption *option, QPainter *painter, const QWidget *widget = nullptr) const

使用提供的painter 绘制给定的element ，并采用由option 指定的样式选项。

widget 参数是可选的，可用于辅助控件的绘制。option 参数是一个指向QStyleOption 对象的指针，可通过qstyleoption_cast()函数将其强制转换为正确的子类。

下表列出了控件元素及其关联的样式选项子类。样式选项包含绘制控件所需的所有参数，包括QStyleOption::state ，它存储了绘制时使用的样式标志。该表还说明了将给定选项转换为相应子类时会设置哪些标志。

请注意，如果某个控件未在此处列出，那是因为它使用的是普通的QStyleOption 对象。

另请参阅 drawPrimitive() 和drawComplexControl()。

[virtual] void QStyle::drawItemPixmap(QPainter *painter, const QRect &rectangle, int alignment, const QPixmap &pixmap) const

根据指定的alignment ，使用提供的painter ，在指定的rectangle 中绘制给定的pixmap 。

另请参阅 drawItemText()。

[virtual] void QStyle::drawItemText(QPainter *painter, const QRect &rectangle, int alignment, const QPalette &palette, bool enabled, const QString &text, QPalette::ColorRole textRole = QPalette::NoRole) const

使用提供的painter 和palette ，在指定的rectangle 中绘制给定的text 。

文本使用绘图器的画笔绘制，并根据指定的alignment 进行对齐和换行。如果显式指定了textRole ，则文本将使用palette 中为给定角色设定的颜色进行绘制。enabled 参数指示该项是否启用；在重写此函数时，enabled 参数应影响该项的绘制方式。

另请参阅 Qt::Alignment 和drawItemPixmap()。

[pure virtual] void QStyle::drawPrimitive(QStyle::PrimitiveElement element, const QStyleOption *option, QPainter *painter, const QWidget *widget = nullptr) const

使用由option 指定的样式选项，通过提供的painter 绘制给定的基元element 。

widget 参数是可选的，其中可能包含一个有助于绘制基元元素的小部件。

下表列出了基本元素及其关联的样式选项子类。样式选项包含绘制元素所需的所有参数，包括QStyleOption::state ——该参数保存绘制时使用的样式标志。该表还描述了将给定选项转换为相应子类时会设置哪些标志。

请注意，如果某个基本元素未在此处列出，那是因为它使用了一个普通的 `QStyleOption ` 对象。

另请参阅 drawComplexControl() 和drawControl()。

[pure virtual] QPixmap QStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap, const QStyleOption *option) const

返回给定pixmap 的副本，其样式将按照指定的iconMode 进行调整，并考虑由option 指定的配色方案。

option 参数可以传递额外信息，但必须包含调色板。

请注意，并非所有像素图都能符合要求，在这种情况下，返回的像素图将是一个普通的副本。

另请参阅 QIcon 。

[pure virtual] QStyle::SubControl QStyle::hitTestComplexControl(QStyle::ComplexControl control, const QStyleOptionComplex *option, const QPoint &position, const QWidget *widget = nullptr) const

返回位于指定position 处的子控件，并将其设置为指定的复合control （样式选项由option 指定）。

请注意，position 以屏幕坐标表示。

option 参数是一个指向QStyleOptionComplex 对象（或其子类之一）的指针。该对象可使用qstyleoption_cast()函数转换为适当的类型。详情请参阅drawComplexControl()。widget 参数是可选的，可包含该函数的附加信息。

另请参阅 drawComplexControl() 和subControlRect()。

[virtual] QRect QStyle::itemPixmapRect(const QRect &rectangle, int alignment, const QPixmap &pixmap) const

返回给定rectangle 内的区域，该区域将根据定义的alignment ，绘制指定的pixmap 。

[virtual] QRect QStyle::itemTextRect(const QFontMetrics &metrics, const QRect &rectangle, int alignment, bool enabled, const QString &text) const

返回给定rectangle 内的区域，用于根据指定的字体metrics 和alignment 绘制提供的text 。enabled 参数用于指示相关项是否已启用。

如果给定的rectangle 大于渲染text 所需的区域，则返回的矩形将在rectangle 内根据指定的alignment 进行偏移。例如，如果alignment 为Qt::AlignCenter ，则返回的矩形将居中于rectangle 内。如果给定的rectangle 小于所需区域，则返回的矩形将是足以渲染text 的最小矩形。

另请参阅 Qt::Alignment 。

[pure virtual] int QStyle::layoutSpacing(QSizePolicy::ControlType control1, QSizePolicy::ControlType control2, Qt::Orientation orientation, const QStyleOption *option = nullptr, const QWidget *widget = nullptr) const

返回在布局中control1 和control2 之间应使用的间距。orientation 指定控件是并排布局还是垂直堆叠。option 参数可用于传递有关父控件的额外信息。widget 参数是可选的，当option 的值为nullptr 时也可使用该参数。

此函数由布局系统调用。仅当PM_LayoutHorizontalSpacing 或PM_LayoutVerticalSpacing 返回负值时才会使用该函数。

另请参阅 combinedLayoutSpacing()。

[since 6.1] QString QStyle::name() const

返回样式的名称。

该值可用于通过 `QStyleFactory::create()` 创建样式。

该函数在 Qt 6.1 中引入。

另请参阅 QStyleFactory::create()。

[pure virtual] int QStyle::pixelMetric(QStyle::PixelMetric metric, const QStyleOption *option = nullptr, const QWidget *widget = nullptr) const

返回给定像素的值metric 。

指定的option 和widget 可用于计算度量值。option 可通过qstyleoption_cast()函数转换为适当的类型。请注意，即使对于能够使用option 的PixelMetrics，该值也可能为零。请参阅下表了解相应的option 类型转换：

某些像素度量由小部件调用，而有些仅由样式在内部调用。如果该度量未被小部件调用，则是否使用该度量由样式作者自行决定。对于某些样式而言，这可能并不合适。

[virtual] void QStyle::polish(QWidget *widget)

初始化给定widget 的外观。

该函数会在每个小部件完全创建完成之后、但首次显示之前某个时刻被调用。

请注意，默认实现不执行任何操作。在此函数中合理的操作可能是为该小部件调用 QWidget::setBackgroundMode() 函数。 请勿使用该函数来设置几何属性等。重写此函数会提供一个后门，通过它可以更改小部件的外观，但在 Qt 的样式引擎中，很少有必要实现此函数；请改重写drawItemPixmap()、drawItemText()、drawPrimitive() 等函数。

QWidget::inherits() 函数可能提供足够的信息，以支持针对特定类的自定义。但由于期望新的QStyle 子类能够与所有当前和未来的控件合理兼容，因此建议限制使用硬编码的自定义。

另请参阅 unpolish()。

[virtual] void QStyle::polish(QApplication *application)

给定的application 对象初始化过晚。

[virtual] void QStyle::polish(QPalette &palette)

根据配色方案的特定样式要求（如有）修改palette 。

另请参阅 QPalette 和QApplication::setPalette()。

const QStyle *QStyle::proxy() const

该函数返回此样式当前的代理。默认情况下，大多数样式会返回其自身。但是，当使用代理样式时，该样式将能够回调其代理。

[pure virtual] QSize QStyle::sizeFromContents(QStyle::ContentsType type, const QStyleOption *option, const QSize &contentsSize, const QWidget *widget = nullptr) const

根据提供的contentsSize ，返回由指定的option 和type 所描述的元素的大小。

option 参数是QStyleOption 或其子类的指针。option 可以使用qstyleoption_cast() 函数转换为相应的类型。widget 是可选参数，其中可能包含用于计算大小的额外信息。

请参阅下表了解相应的option 类型转换：

另请参阅 ContentsType 和QStyleOption 。

[static] int QStyle::sliderPositionFromValue(int min, int max, int logicalValue, int span, bool upsideDown = false)

将给定的logicalValue 转换为像素位置。min 参数映射到0，max 映射到span ，其余值则在两者之间均匀分布。

只要span 小于4096，该函数即可处理整个整数范围而不会发生溢出。

默认情况下，该函数假设水平项的最大值位于右侧，垂直项的最大值位于底部。将upsideDown 参数设置为 true 可反转此行为。

另请参阅 sliderValueFromPosition()。

[static] int QStyle::sliderValueFromPosition(int min, int max, int position, int span, bool upsideDown = false)

将给定的像素值position 转换为逻辑值。0映射到min 参数，span 映射到max ，其余值则均匀分布于两者之间。

该函数可处理整个整数范围，且不会发生溢出。

默认情况下，该函数假设水平元素的最大值位于右侧，垂直元素的最大值位于底部。将upsideDown 参数设置为 true 可反转此行为。

另请参阅 sliderPositionFromValue()。

[pure virtual] QIcon QStyle::standardIcon(QStyle::StandardPixmap standardIcon, const QStyleOption *option = nullptr, const QWidget *widget = nullptr) const

返回给定standardIcon 的图标。

standardIcon 是一个标准位图，可遵循某些现有的 GUI 样式或规范。option 参数可用于传递定义相应图标时所需的额外信息。widget 参数是可选的，也可用于辅助确定图标。

[virtual] QPalette QStyle::standardPalette() const

返回该样式的标准调色板。

请注意，在支持系统颜色的系统上，不会使用该样式的标准调色板。特别是，Windows Vista 和 Mac 样式不使用标准调色板，而是利用原生主题引擎。对于这些样式，不应使用 `QApplication::setPalette()` 设置调色板。

另请参阅 QApplication::setPalette()。

[pure virtual] int QStyle::styleHint(QStyle::StyleHint hint, const QStyleOption *option = nullptr, const QWidget *widget = nullptr, QStyleHintReturn *returnData = nullptr) const

返回一个整数，该整数表示针对给定的widget （由提供的样式option 描述）所对应的指定样式hint 。

returnData 当查询控件需要比 styleHint() 返回的整数值更详细的数据时，应使用此方法。详情请参阅QStyleHintReturn 类的说明。

[pure virtual] QRect QStyle::subControlRect(QStyle::ComplexControl control, const QStyleOptionComplex *option, QStyle::SubControl subControl, const QWidget *widget = nullptr) const

返回包含给定复数control （其样式由option 指定）中指定subControl 的矩形。该矩形以屏幕坐标定义。

option 参数是QStyleOptionComplex 或其子类的指针，可使用qstyleoption_cast() 函数将其强制转换为相应类型。详情请参阅drawComplexControl()。widget 是可选的，可包含该函数的附加信息。

另请参阅 drawComplexControl()。

[pure virtual] QRect QStyle::subElementRect(QStyle::SubElement element, const QStyleOption *option, const QWidget *widget = nullptr) const

返回给定element 的子区域，该子区域符合提供的样式option 中的描述。返回的矩形以屏幕坐标定义。

widget 参数是可选的，可用于辅助确定该区域。QStyleOption 对象可通过qstyleoption_cast()函数转换为相应类型。请参阅下表了解相应的option 类型转换：

[virtual] void QStyle::unpolish(QWidget *widget)

取消初始化给定的widget 的外观。

该函数是 `polish()` 的对应函数。每当样式发生动态变化时，对于每个已应用样式的小部件都会调用此函数；旧样式必须先重置其设置，新样式才能再次对其应用样式。

请注意，unpolish() 仅在小部件被销毁时才会被调用。在某些情况下这可能会导致问题，例如，如果您将小部件从用户界面中移除、将其缓存，然后在样式发生变化后将其重新插入；Qt Widgets 中的某些类会缓存其小部件。

另请参阅 polish()。

[virtual] void QStyle::unpolish(QApplication *application)

取消对给定的application 的初始化。

[static] Qt::Alignment QStyle::visualAlignment(Qt::LayoutDirection direction, Qt::Alignment alignment)

将一个alignment （其属性为Qt::AlignLeft 或Qt::AlignRight ，且不包含Qt::AlignAbsolute ）转换为Qt::AlignLeft 或Qt::AlignRight ，并设置Qt::AlignAbsolute ，同时遵循布局direction 。其他对齐标志保持不变。

如果未指定水平对齐方式，该函数将返回给定布局的默认对齐方式：direction 。

QWidget::layoutDirection

[static] QPoint QStyle::visualPos(Qt::LayoutDirection direction, const QRect &boundingRectangle, const QPoint &logicalPosition)

返回根据指定的direction 将给定的logicalPosition 转换为屏幕坐标后的结果。在执行平移操作时会使用boundingRectangle 。

另请参阅 QWidget::layoutDirection 。

[static] QRect QStyle::visualRect(Qt::LayoutDirection direction, const QRect &boundingRectangle, const QRect &logicalRectangle)

返回将给定的logicalRectangle 转换为屏幕坐标的坐标，转换基于指定的direction 。在执行平移操作时会使用boundingRectangle 。

提供此函数是为了支持从右向左的桌面环境，通常用于实现subControlRect()函数。

另请参阅 QWidget::layoutDirection 。