QPalette Class
QPalette 类包含每个 widget 状态的颜色组。更多
Header: | #include <QPalette> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
qmake: | QT += gui |
- 所有成员(包括继承成员)的列表
- 已废弃成员
- QPalette 属于隐式共享类。
公共类型
enum | ColorGroup { Disabled, Active, Inactive, Normal } |
enum | ColorRole { Window, WindowText, Base, AlternateBase, ToolTipBase, …, NoRole } |
公共函数
QPalette() | |
QPalette(Qt::GlobalColor button) | |
QPalette(const QColor &button) | |
QPalette(const QColor &button, const QColor &window) | |
QPalette(const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window) | |
QPalette(const QPalette &p) | |
QPalette(QPalette &&other) | |
~QPalette() | |
(since 6.6) const QBrush & | accent() const |
const QBrush & | alternateBase() const |
const QBrush & | base() const |
const QBrush & | brightText() const |
const QBrush & | brush(QPalette::ColorGroup group, QPalette::ColorRole role) const |
const QBrush & | brush(QPalette::ColorRole role) const |
const QBrush & | button() const |
const QBrush & | buttonText() const |
qint64 | cacheKey() const |
const QColor & | color(QPalette::ColorGroup group, QPalette::ColorRole role) const |
const QColor & | color(QPalette::ColorRole role) const |
QPalette::ColorGroup | currentColorGroup() const |
const QBrush & | dark() const |
const QBrush & | highlight() const |
const QBrush & | highlightedText() const |
bool | isBrushSet(QPalette::ColorGroup cg, QPalette::ColorRole cr) const |
bool | isCopyOf(const QPalette &p) const |
bool | isEqual(QPalette::ColorGroup cg1, QPalette::ColorGroup cg2) const |
const QBrush & | light() const |
const QBrush & | link() const |
const QBrush & | linkVisited() const |
const QBrush & | mid() const |
const QBrush & | midlight() const |
const QBrush & | placeholderText() const |
QPalette | resolve(const QPalette &other) const |
void | setBrush(QPalette::ColorRole role, const QBrush &brush) |
void | setBrush(QPalette::ColorGroup group, QPalette::ColorRole role, const QBrush &brush) |
void | setColor(QPalette::ColorGroup group, QPalette::ColorRole role, const QColor &color) |
void | setColor(QPalette::ColorRole role, const QColor &color) |
void | setColorGroup(QPalette::ColorGroup cg, const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window) |
void | setCurrentColorGroup(QPalette::ColorGroup cg) |
const QBrush & | shadow() const |
void | swap(QPalette &other) |
const QBrush & | text() const |
const QBrush & | toolTipBase() const |
const QBrush & | toolTipText() const |
const QBrush & | window() const |
const QBrush & | windowText() const |
QVariant | operator QVariant() const |
bool | operator!=(const QPalette &p) const |
QPalette & | operator=(QPalette &&other) |
QPalette & | operator=(const QPalette &p) |
(since 6.6) bool | operator==(const QPalette &p) const |
相关非成员
QDataStream & | operator<<(QDataStream &s, const QPalette &p) |
QDataStream & | operator>>(QDataStream &s, QPalette &p) |
详细描述
调色板由三个颜色组组成:激活、禁用和非激活。Qt 中的所有 Widget 都包含一个调色板,并使用它们的调色板来绘制自己。这使得用户界面易于配置,也更容易保持一致。
如果您要创建一个新的部件,我们强烈建议您使用调色板中的颜色,而不是硬编码特定的颜色。
颜色组
- 活动组用于键盘焦点所在的窗口。
- 非活动组用于其他窗口。
- 禁用组用于因某种原因被禁用的部件(而非窗口)。
活动和非活动窗口都可以包含禁用的窗口部件。(禁用的窗口小部件通常被称为不可访问的或灰色的)。
在大多数样式中,活动和非活动的外观是一样的。
通过setColor() 和setBrush() 可以在调色板的任何颜色组中为特定角色设置颜色和笔刷。颜色组包含部件用于绘制自身的一组颜色。我们建议部件使用调色板中的颜色组角色,如 "前景 "和 "底色",而不是 "红色 "或 "绿松石色 "等字面颜色。ColorRole 文档中列举并定义了颜色角色。
我们强烈建议您使用当前样式的默认调色板(由QGuiApplication::palette() 返回),并在必要时进行修改。在绘制 Qt Widget 时,Qt Widget 会完成这项工作。
要修改颜色组,您需要调用setColor() 和setBrush() 函数,这取决于您需要的是纯色还是像素图图案。
此外,还有相应的color() 和brush() 获取器,以及一个常用的方便函数来获取当前ColorGroup 的ColorRole :window(),windowText(),base() 等。
您可以使用复制构造函数复制调色板,并使用isCopyOf() 测试两个调色板是否相同。
QPalette 通过使用隐式共享进行了优化,因此将 QPalette 对象作为参数传递非常高效。
警告 某些样式不会在所有绘图中使用调色板,例如,如果它们使用本地主题引擎。Windows Vista 和 macOS 风格都属于这种情况。
另请参阅 QApplication::setPalette(),QWidget::setPalette() 和QColor 。
成员类型文档
enum QPalette::ColorGroup
常数 | 值 | 描述 |
---|---|---|
QPalette::Disabled | 1 | |
QPalette::Active | 0 | |
QPalette::Inactive | 2 | |
QPalette::Normal | Active | 活动的同义词 |
enum QPalette::ColorRole
ColorRole 枚举定义了当前图形用户界面中使用的不同符号颜色角色。
主要角色有
常量 | 值 | 描述 |
---|---|---|
QPalette::Window | 10 | 一般背景色。 |
QPalette::WindowText | 0 | 一般前景色。 |
QPalette::Base | 9 | 主要用作文本输入部件的背景色,但也可用于其他绘画,如组合框下拉菜单和工具栏手柄的背景色。通常是白色或其他浅色。 |
QPalette::AlternateBase | 16 | 在具有交替行颜色的视图中用作备用背景色(请参阅QAbstractItemView::setAlternatingRowColors() )。 |
QPalette::ToolTipBase | 18 | 用作QToolTip 和QWhatsThis 的背景色。工具提示使用QPalette 的非活动颜色组,因为工具提示不是活动窗口。 |
QPalette::ToolTipText | 19 | 用作QToolTip 和QWhatsThis 的前景色。工具提示使用QPalette 的非活动颜色组,因为工具提示不是活动窗口。 |
QPalette::PlaceholderText | 20 | 用作各种文本输入部件的占位符颜色。该枚举值已在 Qt 5.12 中引入。 |
QPalette::Text | 6 | 与Base 一起使用的前景色。它通常与WindowText 相同,在这种情况下,它必须与Window 和Base 形成良好的对比。 |
QPalette::Button | 1 | 一般按钮背景色。该背景可能与Window 不同,因为某些样式要求按钮使用不同的背景色。 |
QPalette::ButtonText | 8 | 与Button 颜色一起使用的前景色。 |
QPalette::BrightText | 7 | 与WindowText 有很大不同的文字颜色,可与Dark 等形成鲜明对比。通常用于需要绘制文本的地方,如按下按钮时,Text 或WindowText 的对比度较低。请注意,文本颜色可以用于文字以外的其他内容;文本颜色通常用于文本,但将文本颜色角色用于线条、图标等也很常见。 |
还有一些颜色角色主要用于 3D 斜面和阴影效果。所有这些角色通常都来自Window
,使用方式也依赖于这种关系。例如,按钮依靠它使斜面看起来美观,Motif 滚动条依靠Mid
使其与Window
略有不同。
常量 | 值 | 说明 |
---|---|---|
QPalette::Light | 2 | 比Button 颜色浅。 |
QPalette::Midlight | 3 | 介于Button 和Light 之间。 |
QPalette::Dark | 4 | 颜色比Button 深。 |
QPalette::Mid | 5 | 介于Button 和Dark 之间。 |
QPalette::Shadow | 11 | 非常深的颜色。默认情况下,阴影颜色为Qt::black 。 |
选中(标记)的项目有两种作用:
常量 | 值 | 说明 |
---|---|---|
QPalette::Highlight | 12 | 一种颜色,用于显示选中的项目或当前项目。默认情况下,高亮颜色为Qt::darkBlue 。 |
QPalette::Accent (since Qt 6.6) | 21 | 通常与基本色、窗口色和按钮色形成对比或互补的颜色。它通常代表用户对桌面个性化的选择。交互式组件的样式是一个典型的使用案例。除非明确设置,否则默认为高亮。 |
QPalette::HighlightedText | 13 | 与Highlight 形成对比的文本颜色。默认情况下,高亮文本颜色为Qt::white 。 |
有两种颜色角色与超链接有关:
常量 | 值 | 说明 |
---|---|---|
QPalette::Link | 14 | 用于未访问超链接的文本颜色。默认情况下,链接颜色为Qt::blue 。 |
QPalette::LinkVisited | 15 | 用于已访问过的超链接的文本颜色。默认情况下,已访问链接的颜色是Qt::magenta 。 |
请注意,在 Qt 中呈现富文本时,我们不使用Link
和LinkVisited
角色,我们建议您使用 CSS 和QTextDocument::setDefaultStyleSheet() 函数来改变链接的外观。例如
QTextBrowser browser; QColor linkColor(Qt::red); QString sheet = QString::fromLatin1("a { text-decoration: underline; color: %1 }").arg(linkColor.name()); browser.document()->setDefaultStyleSheet(sheet);
常量 | 值 | 说明 |
---|---|---|
QPalette::NoRole | 17 | 无角色;这一特殊角色通常用于表示尚未分配角色。 |
成员函数文档
QPalette::QPalette()
构造一个未设置颜色角色的空调色板对象。
当用作QWidget 的调色板时,颜色将按照QWidget::setPalette() 所描述的方式进行解析。
另请参阅 QApplication::setPalette() 和QApplication::palette()。
QPalette::QPalette(Qt::GlobalColor button)
根据button 颜色构建调色板。Window
也将成为按钮的颜色。
QPalette::QPalette(const QColor &button)
根据button 颜色构建调色板。Window
也将成为按钮颜色。
QPalette::QPalette(const QColor &button, const QColor &window)
根据button 颜色和window 构建调色板。其他颜色将根据这些颜色自动计算。
QPalette::QPalette(const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)
构造调色板。您可以为windowText,button,light,dark,mid,text,bright_text,base 和window 传递笔刷、像素图或纯色。
另请参见 QBrush 。
QPalette::QPalette(const QPalette &p)
构造p 的副本。
由于采用了隐式共享,该构造函数的运行速度很快。
[noexcept]
QPalette::QPalette(QPalette &&other)
Move- 构造一个 QPalette 实例,使其指向other 所指向的同一对象。
移动后,只能对other 进行赋值或销毁。任何其他操作都将导致未定义的行为。
[noexcept]
QPalette::~QPalette()
破坏调色板。
[since 6.6]
const QBrush &QPalette::accent() const
返回当前颜色组的重点笔刷。
此函数在 Qt 6.6 中引入。
const QBrush &QPalette::alternateBase() const
返回当前颜色组的备用基本笔刷。
const QBrush &QPalette::base() const
返回当前颜色组的基本笔刷。
const QBrush &QPalette::brightText() const
返回当前颜色组的明亮文本前景笔刷。
const QBrush &QPalette::brush(QPalette::ColorGroup group, QPalette::ColorRole role) const
返回指定颜色的笔刷group ,用于给定的颜色role 。
另请参阅 color(),setBrush() 和ColorRole 。
const QBrush &QPalette::brush(QPalette::ColorRole role) const
这是一个重载函数。
返回当前ColorGroup 中为给定颜色role 设置的笔刷。
另请参阅 color(),setBrush() 和ColorRole 。
const QBrush &QPalette::button() const
返回当前颜色组的按钮刷。
const QBrush &QPalette::buttonText() const
返回当前颜色组的按钮文本前景笔刷。
qint64 QPalette::cacheKey() const
返回一个数字,用于标识此QPalette 对象的内容。如果不同的QPalette 对象指向相同的内容,它们可以拥有相同的键。
调色板更改时,cacheKey() 也会随之更改。
const QColor &QPalette::color(QPalette::ColorGroup group, QPalette::ColorRole role) const
返回指定颜色group 中的颜色,用于给定的颜色role 。
另请参阅 brush(),setColor() 和ColorRole 。
const QColor &QPalette::color(QPalette::ColorRole role) const
这是一个重载函数。
返回当前ColorGroup 中已为给定颜色role 设置的颜色。
QPalette::ColorGroup QPalette::currentColorGroup() const
返回调色板的当前颜色组。
另请参见 setCurrentColorGroup()。
const QBrush &QPalette::dark() const
返回当前颜色组的深色笔刷。
const QBrush &QPalette::highlight() const
返回当前颜色组的高光笔刷。
const QBrush &QPalette::highlightedText() const
返回当前颜色组的高亮文本笔刷。
bool QPalette::isBrushSet(QPalette::ColorGroup cg, QPalette::ColorRole cr) const
如果之前已在此调色板上设置了ColorGroup cg 和ColorRole cr ,则返回true
;否则返回false
。
ColorGroup cg 应小于QPalette::NColorGroups ,但也可以使用QPalette::Current 。在这种情况下,将使用先前设置的当前颜色组。
ColorRole cr 应小于QPalette::NColorRoles 。
另请参阅 setBrush() 和currentColorGroup()。
bool QPalette::isCopyOf(const QPalette &p) const
如果该调色板和p 是彼此的副本,即其中一个是作为另一个的副本创建的,且随后都未修改,则返回true
;否则返回false
。这比相等严格得多。
另请参见 operator=() 和operator==()。
bool QPalette::isEqual(QPalette::ColorGroup cg1, QPalette::ColorGroup cg2) const
如果颜色组cg1 等于cg2 ,则返回true
(通常很快);否则返回false
。
const QBrush &QPalette::light() const
返回当前颜色组的光刷。
const QBrush &QPalette::link() const
返回当前颜色组的未访问链接文本刷。
const QBrush &QPalette::linkVisited() const
返回当前颜色组的已访问链接文本刷。
const QBrush &QPalette::mid() const
返回当前颜色组的中间画笔。
const QBrush &QPalette::midlight() const
返回当前颜色组的中间光笔刷。
const QBrush &QPalette::placeholderText() const
返回当前颜色组的占位符文本笔刷。
注意: 在 Qt 5.12 之前,占位符文本颜色是硬编码为QPalette::text().color() 并应用 128 的 Alpha 值。在 Qt 6 中,它是一种独立的颜色。
QPalette QPalette::resolve(const QPalette &other) const
返回一个新的QPalette ,它是此实例和other 的结合。本实例中设置的颜色角色优先。本实例中未设置的角色将从other 中获取。
另请参见 isBrushSet 。
void QPalette::setBrush(QPalette::ColorRole role, const QBrush &brush)
将给定颜色role 的笔刷设置为调色板中所有组的指定brush 。
另请参阅 brush(),setColor() 和ColorRole 。
void QPalette::setBrush(QPalette::ColorGroup group, QPalette::ColorRole role, const QBrush &brush)
这是一个重载函数。
设置指定颜色group 的笔刷,用于给定颜色role ,并将其设置为brush 。
另请参阅 brush(),setColor() 和ColorRole 。
void QPalette::setColor(QPalette::ColorGroup group, QPalette::ColorRole role, const QColor &color)
将指定颜色group 中的颜色,用于给定颜色role ,设置为指定的纯色color 。
另请参阅 setBrush(),color() 和ColorRole 。
void QPalette::setColor(QPalette::ColorRole role, const QColor &color)
这是一个重载函数。
将给定颜色role 在所有颜色组中使用的颜色设置为指定的纯色color 。
另请参阅 brush(),setColor() 和ColorRole 。
void QPalette::setColorGroup(QPalette::ColorGroup cg, const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)
设置cg 的组。您可以为windowText,button,light,dark,mid,text,bright_text,base 和window 传递笔刷、像素图或纯色。
另请参阅 QBrush 。
void QPalette::setCurrentColorGroup(QPalette::ColorGroup cg)
将调色板的当前颜色组设置为cg 。
另请参阅 currentColorGroup() 。
const QBrush &QPalette::shadow() const
返回当前颜色组的阴影刷。
[noexcept]
void QPalette::swap(QPalette &other)
将此调色板实例与other 互换。该操作速度非常快,从未出现过故障。
const QBrush &QPalette::text() const
返回当前颜色组的文本前景笔刷。
const QBrush &QPalette::toolTipBase() const
返回当前颜色组的工具提示基本画笔。该笔刷由QToolTip 和QWhatsThis 使用。
注: 工具提示使用QPalette 的非活动颜色组,因为工具提示不是活动窗口。
const QBrush &QPalette::toolTipText() const
返回当前颜色组的工具提示文本笔刷。QToolTip 和QWhatsThis 使用此笔刷。
注: 工具提示使用QPalette 的非活动颜色组,因为工具提示不是活动窗口。
const QBrush &QPalette::window() const
返回当前颜色组的窗口(一般背景)画笔。
const QBrush &QPalette::windowText() const
返回当前颜色组的窗口文本(一般前景)画笔。
QVariant QPalette::operator QVariant() const
bool QPalette::operator!=(const QPalette &p) const
如果调色板与p 不同,则返回true
(缓慢);否则返回false
(通常很快)。
注意: 比较调色板时不考虑当前的ColorGroup 。
另请参阅 operator==().
[noexcept]
QPalette &QPalette::operator=(QPalette &&other)
Move-assignsother 到此QPalette 实例。
QPalette &QPalette::operator=(const QPalette &p)
将p 指定给该调色板,并返回对该调色板的引用。
由于采用了隐式共享,该操作速度很快。
[since 6.6]
bool QPalette::operator==(const QPalette &p) const
如果调色板等于p ,则返回true
(通常较快);否则返回false
(较慢)。
注意: 比较调色板时不考虑以下因素:
current
ColorGroup- ColorRole NoRole
此函数在 Qt 6.6 中引入。
另请参阅 operator!=() 。
相关非成员
QDataStream &operator<<(QDataStream &s, const QPalette &p)
将调色板p 写入数据流s ,并返回对数据流的引用。
另请参阅 QDataStream 操作符的格式。
QDataStream &operator>>(QDataStream &s, QPalette &p)
从数据流中读取调色板,s 到调色板p ,并返回对数据流的引用。
另请参阅 QDataStream 操作符的格式。
© 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.