QDialogButtonBox Class
QDialogButtonBox 类是一个窗口部件,它能以适合当前窗口部件样式的布局显示按钮。更多
Header: | #include <QDialogButtonBox> |
CMake.QDialogButtonBox 类 | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
qmake: | QT += widgets |
继承: | QWidget |
公共类型
enum | ButtonLayout { WinLayout, MacLayout, KdeLayout, GnomeLayout, AndroidLayout } |
enum | ButtonRole { InvalidRole, AcceptRole, RejectRole, DestructiveRole, ActionRole, …, ResetRole } |
enum | StandardButton { Ok, Open, Save, Cancel, Close, …, NoButton } |
flags | StandardButtons |
属性
- centerButtons : bool
- orientation : Qt::Orientation
- standardButtons : StandardButtons
公共功能
QDialogButtonBox(QWidget *parent = nullptr) | |
QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr) | |
QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr) | |
QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr) | |
virtual | ~QDialogButtonBox() |
QPushButton * | addButton(QDialogButtonBox::StandardButton button) |
void | addButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role) |
QPushButton * | addButton(const QString &text, QDialogButtonBox::ButtonRole role) |
QPushButton * | button(QDialogButtonBox::StandardButton which) const |
QDialogButtonBox::ButtonRole | buttonRole(QAbstractButton *button) const |
QList<QAbstractButton *> | buttons() const |
bool | centerButtons() const |
void | clear() |
Qt::Orientation | orientation() const |
void | removeButton(QAbstractButton *button) |
void | setCenterButtons(bool center) |
void | setOrientation(Qt::Orientation orientation) |
void | setStandardButtons(QDialogButtonBox::StandardButtons buttons) |
QDialogButtonBox::StandardButton | standardButton(QAbstractButton *button) const |
QDialogButtonBox::StandardButtons | standardButtons() const |
信号
void | accepted() |
void | clicked(QAbstractButton *button) |
void | helpRequested() |
void | rejected() |
重新实现的受保护函数
virtual void | changeEvent(QEvent *event) override |
virtual bool | event(QEvent *event) override |
详细说明
对话框和消息框通常以符合该平台界面指南的布局显示按钮。不同平台的对话框通常有不同的布局。QDialogButtonBox 允许开发人员向其中添加按钮,并将自动使用适合用户桌面环境的布局。
对话框的大多数按钮都遵循特定的角色。这些角色包括
- 接受或拒绝对话框。
- 寻求帮助。
- 对对话框本身执行操作(如重置字段或应用更改)。
也可能有其他方法来取消对话框,这可能会导致破坏性结果。
大多数对话框都有几乎可以视为标准的按钮(如OK 和Cancel 按钮)。以标准方式创建这些按钮有时会很方便。
使用 QDialogButtonBox 有几种方法。一种方法是自己创建按钮(或按钮文本)并将它们添加到按钮框中,同时指定它们的作用。
QDialogButtonBox *buttonBox = new QDialogButtonBox(Qt::Vertical); buttonBox->addButton(findButton, QDialogButtonBox::ActionRole); buttonBox->addButton(moreButton, QDialogButtonBox::ActionRole);
另外,QDialogButtonBox 提供了几个标准按钮(如确定、取消、保存)供您使用。它们以标志的形式存在,因此您可以在构造函数中将它们组合在一起。
buttonBox = new QDialogButtonBox(QDialogButtonBox::Ok | QDialogButtonBox::Cancel); connect(buttonBox, &QDialogButtonBox::accepted, this, &QDialog::accept); connect(buttonBox, &QDialogButtonBox::rejected, this, &QDialog::reject);
您可以混合使用普通按钮和标准按钮。
目前,如果按钮框是水平的,按钮的布局如下:
![]() | 按钮框水平布局GnomeLayout |
![]() | 水平布局的按钮框KdeLayout |
![]() | 水平布局的按钮盒MacLayout |
![]() | 按钮框横向布局WinLayout |
如果按钮框是垂直的,按钮的布局如下:
此外,只包含带有ActionRole 或HelpRole 的按钮的按钮框可视为无模式,在 macOS 上有另一种外观:
点击按钮框中的按钮时,会为实际按下的按钮发出clicked() 信号。为方便起见,如果按钮上有AcceptRole 、RejectRole 或HelpRole ,则会分别发出accepted() 、rejected() 或helpRequested() 信号。
如果您想将某个特定按钮设为默认按钮,则需要在该按钮上调用QPushButton::setDefault() 信号。但是,如果没有设置默认按钮,并且在使用QPushButton::autoDefault 属性时,为了在不同平台上保留哪个按钮为默认按钮,则在显示 QDialogButtonBox 时,第一个具有接受角色的按钮将成为默认按钮、
另请参阅 QMessageBox,QPushButton, 和QDialog 。
成员类型文档
enum QDialogButtonBox::ButtonLayout
该枚举描述了在排列按钮框中的按钮时使用的布局策略。
常数 | 值 | 说明 |
---|---|---|
QDialogButtonBox::WinLayout | 0 | 使用适合 Windows 应用程序的策略。 |
QDialogButtonBox::MacLayout | 1 | 使用适合 macOS 应用程序的策略。 |
QDialogButtonBox::KdeLayout | 2 | 使用适合 KDE 应用程序的策略。 |
QDialogButtonBox::GnomeLayout | 3 | 使用适合 GNOME 应用程序的策略。 |
QDialogButtonBox::AndroidLayout | 4 | 使用适合 Android 应用程序的策略。此枚举值在 Qt 5.10 中添加。 |
按钮布局由current style 指定。不过,在 X11 平台上,它可能会受到桌面环境的影响。
enum QDialogButtonBox::ButtonRole
该枚举描述了可用于描述按钮框中按钮的角色。这些角色的组合就像标志一样,用于描述按钮行为的不同方面。
常量 | 值 | 描述 |
---|---|---|
QDialogButtonBox::InvalidRole | -1 | 按钮无效。 |
QDialogButtonBox::AcceptRole | 0 | 单击该按钮将接受对话框(如确定)。 |
QDialogButtonBox::RejectRole | 1 | 单击按钮会拒绝对话框(如取消)。 |
QDialogButtonBox::DestructiveRole | 2 | 单击按钮会导致破坏性更改(例如,丢弃更改)并关闭对话框。 |
QDialogButtonBox::ActionRole | 3 | 单击按钮会更改对话框中的元素。 |
QDialogButtonBox::HelpRole | 4 | 单击该按钮可以请求帮助。 |
QDialogButtonBox::YesRole | 5 | 该按钮类似于 "是 "按钮。 |
QDialogButtonBox::NoRole | 6 | 该按钮类似于 "否 "按钮。 |
QDialogButtonBox::ApplyRole | 8 | 该按钮可应用当前更改。 |
QDialogButtonBox::ResetRole | 7 | 按钮将对话框的字段重置为默认值。 |
另请参阅 StandardButton 。
枚举 QDialogButtonBox::StandardButton
标志 QDialogButtonBox::StandardButtons
这些枚举描述了标准按钮的标志。每个按钮都有一个定义的ButtonRole 。
常量 | 值 | 描述 |
---|---|---|
QDialogButtonBox::Ok | 0x00000400 | 一个 "确定 "按钮,由AcceptRole. |
QDialogButtonBox::Open | 0x00002000 | 通过AcceptRole 定义的 "打开 "按钮。 |
QDialogButtonBox::Save | 0x00000800 | 通过AcceptRole 定义的 "保存 "按钮。 |
QDialogButtonBox::Cancel | 0x00400000 | 通过RejectRole 定义的 "取消 "按钮。 |
QDialogButtonBox::Close | 0x00200000 | 通过RejectRole 定义的 "关闭 "按钮。 |
QDialogButtonBox::Discard | 0x00800000 | 通过DestructiveRole 定义的 "丢弃 "或 "不保存 "按钮(取决于平台)。 |
QDialogButtonBox::Apply | 0x02000000 | 通过ApplyRole 定义的 "应用 "按钮。 |
QDialogButtonBox::Reset | 0x04000000 | 通过ResetRole 定义的 "重置 "按钮。 |
QDialogButtonBox::RestoreDefaults | 0x08000000 | 通过ResetRole 定义的 "恢复默认值 "按钮。 |
QDialogButtonBox::Help | 0x01000000 | 通过HelpRole 定义的 "帮助 "按钮。 |
QDialogButtonBox::SaveAll | 0x00001000 | 通过AcceptRole 定义的 "全部保存 "按钮。 |
QDialogButtonBox::Yes | 0x00004000 | 通过YesRole 定义的 "是 "按钮。 |
QDialogButtonBox::YesToAll | 0x00008000 | 通过YesRole 定义的 "是全部 "按钮。 |
QDialogButtonBox::No | 0x00010000 | 通过NoRole 定义的 "否 "按钮。 |
QDialogButtonBox::NoToAll | 0x00020000 | 通过NoRole 定义的 "否全部 "按钮。 |
QDialogButtonBox::Abort | 0x00040000 | 通过RejectRole 定义的 "放弃 "按钮。 |
QDialogButtonBox::Retry | 0x00080000 | 通过AcceptRole 定义的 "重试 "按钮。 |
QDialogButtonBox::Ignore | 0x00100000 | 通过AcceptRole 定义的 "忽略 "按钮。 |
QDialogButtonBox::NoButton | 0x00000000 | 无效按钮。 |
StandardButtons 类型是QFlags<StandardButton> 的类型定义。它存储了 StandardButton 值的 OR 组合。
另请参阅 ButtonRole 和standardButtons 。
属性文档
centerButtons : bool
该属性用于确定按钮框中的按钮是否居中。
默认情况下,该属性为false
。这种行为适合大多数类型的对话框。一个明显的例外是大多数平台(如 Windows)上的消息框,按钮框水平居中。
访问功能:
bool | centerButtons() const |
void | setCenterButtons(bool center) |
另请参阅 QMessageBox 。
orientation : Qt::Orientation
该属性表示按钮框的方向
默认情况下,方向是水平的(即按钮并排排列)。可能的方向为Qt::Horizontal 和Qt::Vertical 。
访问功能:
Qt::Orientation | orientation() const |
void | setOrientation(Qt::Orientation orientation) |
standardButtons : StandardButtons
按钮框中的标准按钮集合
该属性控制按钮框使用哪些标准按钮。
访问功能:
QDialogButtonBox::StandardButtons | standardButtons() const |
void | setStandardButtons(QDialogButtonBox::StandardButtons buttons) |
另请参阅 addButton().
成员函数文档
QDialogButtonBox::QDialogButtonBox(QWidget *parent = nullptr)
用给定的parent 构建一个空的水平按钮框。
另请参阅 orientation 和addButton() 。
[explicit]
QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr)
用给定的parent 构建一个水平按钮框,其中包含buttons 指定的标准按钮。
另请参阅 orientation 和addButton() 。
QDialogButtonBox::QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr)
用给定的orientation 和parent 构造一个空按钮框。
另请参阅 orientation 和addButton()。
QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr)
用给定的orientation 和parent 构建一个按钮框,其中包含buttons 指定的标准按钮。
另请参阅 orientation 和addButton()。
[virtual noexcept]
QDialogButtonBox::~QDialogButtonBox()
销毁按钮框。
[signal]
void QDialogButtonBox::accepted()
当点击按钮框内的按钮时,只要该按钮是用AcceptRole 或YesRole 定义的,就会发出该信号。
另请参见 rejected()、clicked() 和helpRequested()。
QPushButton *QDialogButtonBox::addButton(QDialogButtonBox::StandardButton button)
将标准button 添加到按钮框(如果有效),并返回一个按钮。如果button 无效,则不会添加到按钮框中,并返回 0。
另请参阅 removeButton() 和clear()。
void QDialogButtonBox::addButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role)
将给定的button 添加到指定role 的按钮框中。如果角色无效,则不会添加按钮。
如果按钮已被添加,则会被移除,然后用新角色重新添加。
注: 按钮框拥有按钮的所有权。
另请参阅 removeButton() 和clear()。
QPushButton *QDialogButtonBox::addButton(const QString &text, QDialogButtonBox::ButtonRole role)
使用给定的text 创建一个按钮,将其添加到指定role 的按钮框中,并返回相应的按钮。如果role 无效,则不会创建按钮,并返回 0。
另请参阅 removeButton() 和clear()。
QPushButton *QDialogButtonBox::button(QDialogButtonBox::StandardButton which) const
返回与标准按钮which 对应的QPushButton ,如果该按钮框中不存在标准按钮,则返回nullptr
。
另请参阅 standardButton()、standardButtons() 和buttons()。
QDialogButtonBox::ButtonRole QDialogButtonBox::buttonRole(QAbstractButton *button) const
返回指定button 的按钮角色。如果button 是nullptr
或尚未添加到按钮框中,则此函数返回InvalidRole 。
QList<QAbstractButton *> QDialogButtonBox::buttons() const
返回已添加到按钮框中的所有按钮的列表。
另请参阅 buttonRole()、addButton() 和removeButton()。
[override virtual protected]
void QDialogButtonBox::changeEvent(QEvent *event)
重实现:QWidget::changeEvent(QEvent *event).
void QDialogButtonBox::clear()
清除按钮框,删除其中的所有按钮。
另请参阅 removeButton() 和addButton()。
[signal]
void QDialogButtonBox::clicked(QAbstractButton *button)
当点击按钮框内的按钮时会发出该信号。被点击的具体按钮由button 指定。
另请参见 accepted()、rejected() 和helpRequested()。
[override virtual protected]
bool QDialogButtonBox::event(QEvent *event)
重实现:QWidget::event(QEvent *event).
[signal]
void QDialogButtonBox::helpRequested()
当点击按钮框内的按钮时,只要该按钮是用HelpRole 定义的,就会发出该信号。
另请参见 accepted()、rejected() 和clicked()。
[signal]
void QDialogButtonBox::rejected()
当点击按钮框内的按钮时,只要该按钮是用RejectRole 或NoRole 定义的,就会发出该信号。
另请参阅 accepted()、helpRequested() 和clicked()。
void QDialogButtonBox::removeButton(QAbstractButton *button)
从按钮框中删除button ,但不删除它,并将其父级设置为 0。
另请参阅 clear()、buttons() 和addButton()。
QDialogButtonBox::StandardButton QDialogButtonBox::standardButton(QAbstractButton *button) const
返回与给定的button 对应的标准按钮枚举值,如果给定的button 不是标准按钮,则返回NoButton 。
另请参阅 button()、buttons() 和standardButtons()。
© 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.