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

属性

公共功能

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 允许开发人员向其中添加按钮,并将自动使用适合用户桌面环境的布局。

对话框的大多数按钮都遵循特定的角色。这些角色包括

  • 接受或拒绝对话框。
  • 寻求帮助。
  • 对对话框本身执行操作(如重置字段或应用更改)。

也可能有其他方法来取消对话框,这可能会导致破坏性结果。

大多数对话框都有几乎可以视为标准的按钮(如OKCancel 按钮)。以标准方式创建这些按钮有时会很方便。

使用 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 水平按钮框水平布局GnomeLayout
KdeLayout 水平水平布局的按钮框KdeLayout
MacLayout 水平水平布局的按钮盒MacLayout
WinLayout 水平按钮框横向布局WinLayout

如果按钮框是垂直的,按钮的布局如下:

此外,只包含带有ActionRoleHelpRole 的按钮的按钮框可视为无模式,在 macOS 上有另一种外观:

无模式水平MacLayout 无模式横向截图MacLayout
无模式垂直MacLayout 无模式垂直截图MacLayout

点击按钮框中的按钮时,会为实际按下的按钮发出clicked() 信号。为方便起见,如果按钮上有AcceptRoleRejectRoleHelpRole ,则会分别发出accepted() 、rejected() 或helpRequested() 信号。

如果您想将某个特定按钮设为默认按钮,则需要在该按钮上调用QPushButton::setDefault() 信号。但是,如果没有设置默认按钮,并且在使用QPushButton::autoDefault 属性时,为了在不同平台上保留哪个按钮为默认按钮,则在显示 QDialogButtonBox 时,第一个具有接受角色的按钮将成为默认按钮、

另请参阅 QMessageBox,QPushButton, 和QDialog

成员类型文档

enum QDialogButtonBox::ButtonLayout

该枚举描述了在排列按钮框中的按钮时使用的布局策略。

常数说明
QDialogButtonBox::WinLayout0使用适合 Windows 应用程序的策略。
QDialogButtonBox::MacLayout1使用适合 macOS 应用程序的策略。
QDialogButtonBox::KdeLayout2使用适合 KDE 应用程序的策略。
QDialogButtonBox::GnomeLayout3使用适合 GNOME 应用程序的策略。
QDialogButtonBox::AndroidLayout4使用适合 Android 应用程序的策略。此枚举值在 Qt 5.10 中添加。

按钮布局由current style 指定。不过,在 X11 平台上,它可能会受到桌面环境的影响。

enum QDialogButtonBox::ButtonRole

该枚举描述了可用于描述按钮框中按钮的角色。这些角色的组合就像标志一样,用于描述按钮行为的不同方面。

常量描述
QDialogButtonBox::InvalidRole-1按钮无效。
QDialogButtonBox::AcceptRole0单击该按钮将接受对话框(如确定)。
QDialogButtonBox::RejectRole1单击按钮会拒绝对话框(如取消)。
QDialogButtonBox::DestructiveRole2单击按钮会导致破坏性更改(例如,丢弃更改)并关闭对话框。
QDialogButtonBox::ActionRole3单击按钮会更改对话框中的元素。
QDialogButtonBox::HelpRole4单击该按钮可以请求帮助。
QDialogButtonBox::YesRole5该按钮类似于 "是 "按钮。
QDialogButtonBox::NoRole6该按钮类似于 "否 "按钮。
QDialogButtonBox::ApplyRole8该按钮可应用当前更改。
QDialogButtonBox::ResetRole7按钮将对话框的字段重置为默认值。

另请参阅 StandardButton

枚举 QDialogButtonBox::StandardButton
标志 QDialogButtonBox::StandardButtons

这些枚举描述了标准按钮的标志。每个按钮都有一个定义的ButtonRole

常量描述
QDialogButtonBox::Ok0x00000400一个 "确定 "按钮,由AcceptRole.
QDialogButtonBox::Open0x00002000通过AcceptRole 定义的 "打开 "按钮。
QDialogButtonBox::Save0x00000800通过AcceptRole 定义的 "保存 "按钮。
QDialogButtonBox::Cancel0x00400000通过RejectRole 定义的 "取消 "按钮。
QDialogButtonBox::Close0x00200000通过RejectRole 定义的 "关闭 "按钮。
QDialogButtonBox::Discard0x00800000通过DestructiveRole 定义的 "丢弃 "或 "不保存 "按钮(取决于平台)。
QDialogButtonBox::Apply0x02000000通过ApplyRole 定义的 "应用 "按钮。
QDialogButtonBox::Reset0x04000000通过ResetRole 定义的 "重置 "按钮。
QDialogButtonBox::RestoreDefaults0x08000000通过ResetRole 定义的 "恢复默认值 "按钮。
QDialogButtonBox::Help0x01000000通过HelpRole 定义的 "帮助 "按钮。
QDialogButtonBox::SaveAll0x00001000通过AcceptRole 定义的 "全部保存 "按钮。
QDialogButtonBox::Yes0x00004000通过YesRole 定义的 "是 "按钮。
QDialogButtonBox::YesToAll0x00008000通过YesRole 定义的 "是全部 "按钮。
QDialogButtonBox::No0x00010000通过NoRole 定义的 "否 "按钮。
QDialogButtonBox::NoToAll0x00020000通过NoRole 定义的 "否全部 "按钮。
QDialogButtonBox::Abort0x00040000通过RejectRole 定义的 "放弃 "按钮。
QDialogButtonBox::Retry0x00080000通过AcceptRole 定义的 "重试 "按钮。
QDialogButtonBox::Ignore0x00100000通过AcceptRole 定义的 "忽略 "按钮。
QDialogButtonBox::NoButton0x00000000无效按钮。

StandardButtons 类型是QFlags<StandardButton> 的类型定义。它存储了 StandardButton 值的 OR 组合。

另请参阅 ButtonRolestandardButtons

属性文档

centerButtons : bool

该属性用于确定按钮框中的按钮是否居中。

默认情况下,该属性为false 。这种行为适合大多数类型的对话框。一个明显的例外是大多数平台(如 Windows)上的消息框,按钮框水平居中。

访问功能:

bool centerButtons() const
void setCenterButtons(bool center)

另请参阅 QMessageBox

orientation : Qt::Orientation

该属性表示按钮框的方向

默认情况下,方向是水平的(即按钮并排排列)。可能的方向为Qt::HorizontalQt::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 构建一个空的水平按钮框。

另请参阅 orientationaddButton() 。

[explicit] QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr)

用给定的parent 构建一个水平按钮框,其中包含buttons 指定的标准按钮。

另请参阅 orientationaddButton() 。

QDialogButtonBox::QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr)

用给定的orientationparent 构造一个空按钮框。

另请参阅 orientationaddButton()。

QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr)

用给定的orientationparent 构建一个按钮框,其中包含buttons 指定的标准按钮。

另请参阅 orientationaddButton()。

[virtual noexcept] QDialogButtonBox::~QDialogButtonBox()

销毁按钮框。

[signal] void QDialogButtonBox::accepted()

当点击按钮框内的按钮时,只要该按钮是用AcceptRoleYesRole 定义的,就会发出该信号。

另请参见 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 的按钮角色。如果buttonnullptr 或尚未添加到按钮框中,则此函数返回InvalidRole

另请参阅 buttons() 和addButton()。

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()

当点击按钮框内的按钮时,只要该按钮是用RejectRoleNoRole 定义的,就会发出该信号。

另请参阅 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.