QDialogButtonBox 类

The QDialogButtonBox 类是一个窗口小部件,它在一个适合当前窗口小部件样式的布局中显示按钮。 更多...

头文件 #include <QDialogButtonBox>
CMakefind_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmakeQT += widgets
继承 QWidget

公共类型

枚举ButtonLayout { WinLayout, MacLayout, KdeLayout, GnomeLayout, AndroidLayout }
枚举ButtonRole { InvalidRole, AcceptRole, RejectRole, DestructiveRole, ActionRole, …, ResetRole }
枚举StandardButton { Ok, Open, Save, Cancel, Close, …, NoButton }
标记StandardButtons

属性

公共函数

QDialogButtonBox(QWidget *parent = nullptr)
QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr)
QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr)
QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr)
virtual~QDialogButtonBox()
voidaddButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role)
QPushButton *addButton(const QString &text, QDialogButtonBox::ButtonRole role)
QPushButton *addButton(QDialogButtonBox::StandardButton button)
QPushButton *button(QDialogButtonBox::StandardButton which) const
QDialogButtonBox::ButtonRolebuttonRole(QAbstractButton *button) const
QList<QAbstractButton *>buttons() const
boolcenterButtons() const
voidclear()
Qt::Orientationorientation() const
voidremoveButton(QAbstractButton *button)
voidsetCenterButtons(bool center)
voidsetOrientation(Qt::Orientation orientation)
voidsetStandardButtons(QDialogButtonBox::StandardButtons buttons)
QDialogButtonBox::StandardButtonstandardButton(QAbstractButton *button) const
QDialogButtonBox::StandardButtonsstandardButtons() const

信号

voidaccepted()
voidclicked(QAbstractButton *button)
voidhelpRequested()
voidrejected()

重写的受保护的函数

虚函数 voidchangeEvent(QEvent *event) override
虚函数 boolevent(QEvent *event) override

详细描述

对话框和消息框通常以符合该平台界面指南的布局显示按钮。不可避免的是,不同的平台有不同的布局用于他们的对话框。QDialogButtonBox 允许开发者向其中添加按钮,并将自动使用适合用户桌面环境的适当布局。

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

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

还可能有其他方式退出对话框,这可能会产生破坏性结果。

大多数对话框均有可被视为标准的按钮(例如,确定取消按钮)。有时以标准方式创建这些按钮很方便。

使用QDialogButtonBox的方法有几个。一种方法是自己创建按钮(或按钮文本),并将它们添加到按钮框中,指定其角色。

    QDialogButtonBox *buttonBox = new QDialogButtonBox(Qt::Vertical);
    buttonBox->addButton(findButton, QDialogButtonBox::ActionRole);
    buttonBox->addButton(moreButton, QDialogButtonBox::ActionRole);

或者,QDialogButtonBox提供了几个标准按钮(例如,确定、取消、保存),您可以将其用作标志,在构造函数中将它们进行OR运算。

    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 截图
无模态垂直 Mac布局 无模态垂直 Mac布局 的截图

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

如果您想设置一个特定的按钮为默认按钮,需要自己调用 QPushButton::setDefault()。然而,如果没有设置默认按钮,并且使用 QPushButton::autoDefault 属性来在平台上保持默认按钮,那么当显示 QDialogButtonBox 时,第一个具有接受角色的推送按钮将被设置为默认按钮。

另请参阅 QMessageBoxQPushButtonQDialog

成员类型文档

enum QDialogButtonBox::ButtonLayout

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

常量描述
QDialogButtonBox::WinLayout0使用适用于 Windows 应用的策略。
QDialogButtonBox::MacLayout1使用适用于 macOS 应用的策略。
QDialogButtonBox::KdeLayout2使用适用于 KDE 应用的策略。
QDialogButtonBox::GnomeLayout3使用适用于 GNOME 应用的策略。
QDialogButtonBox::AndroidLayout4使用适用于 Android 应用的策略。此枚举值在 Qt 5.10 中添加。

按钮布局由 当前样式 指定。然而,在 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

enum QDialogButtonBox::StandardButton
flags QDialogButtonBox::StandardButtons

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

常量描述
QDialogButtonBox::Ok0x00000400使用 AcceptRole 定义的“OK”按钮。
QDialogButtonBox::Open0x00002000使用 AcceptRole 定义的“打开”按钮。
QDialogButtonBox::Save0x00000800使用AcceptRole定义的“保存”按钮。
QDialogButtonBox::取消0x00400000使用RejectRole定义的“取消”按钮。
QDialogButtonBox::关闭0x00200000使用RejectRole定义的“关闭”按钮。
QDialogButtonBox::丢弃0x00800000根据平台,使用DestructiveRole定义的“丢弃”或“不保存”按钮。
QDialogButtonBox::应用0x02000000使用ApplyRole定义的“应用”按钮。
QDialogButtonBox::重置0x04000000使用ResetRole定义的“重置”按钮。
QDialogButtonBox::恢复默认值0x08000000使用ResetRole定义的“恢复默认值”按钮。
QDialogButtonBox::帮助0x01000000使用HelpRole定义的“帮助”按钮。
QDialogButtonBox::保存所有0x00001000使用AcceptRole定义的“保存所有”按钮。
QDialogButtonBox::是0x00004000使用YesRole定义的“是”按钮。
QDialogButtonBox::全部是0x00008000使用YesRole定义的“全部是”按钮。
QDialogButtonBox::否0x00010000使用NoRole定义的“否”按钮。
QDialogButtonBox::全部否0x00020000使用NoRole定义的“全部否”按钮。
QDialogButtonBox::中止0x00040000使用RejectRole定义的“中止”按钮。
QDialogButtonBox::重试0x00080000使用AcceptRole定义的“重试”按钮。
QDialogButtonBox::忽略0x00100000使用AcceptRole定义的“忽略”按钮。
QDialogButtonBox::无按钮0x00000000一个无效的按钮。

The StandardButtons 类型是 QFlags<StandardButton> 的 typedef。它存储 StandardButton 值的 OR 组合。

另请参阅 ButtonRolestandardButtons

属性文档

centerButtons : bool

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

默认情况下,此属性为 false。这种行为对于大多数类型的对话框都是合适的。一个值得注意的例外是大多数平台上的消息框(例如 Windows),其中按钮框在水平方向上居中。

访问函数

boolcenterButtons() const
voidsetCenterButtons(bool center)

另请参阅 QMessageBox

orientation : Qt::Orientation

此属性用于确定按钮框的排列方向

默认情况下,方向是水平的(即按钮并排显示)。可能的方向是 Qt::HorizontalQt::Vertical

访问函数

Qt::Orientationorientation() const
voidsetOrientation(Qt::Orientation orientation)

standardButtons : StandardButtons

按钮框中的标准按钮集合

此属性用于控制哪些标准按钮被按钮框使用。

访问函数

QDialogButtonBox::StandardButtonsstandardButtons() const
voidsetStandardButtons(QDialogButtonBox::StandardButtons buttons)

另请参阅 addButton

成员函数文档

QDialogButtonBox::QDialogButtonBox(QWidget *parent = nullptr)

构建一个具有指定 parent 的空水平按钮盒。

另请参阅orientationaddButton()。

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

构建一个具有指定 orientationparent 的空按钮盒。

另请参阅orientationaddButton()。

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

构建一个具有指定 parent 的水平按钮盒,其中包含由 buttons 指定的标准按钮。

另请参阅orientationaddButton()。

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

构建一个具有指定 orientationparent 的按钮盒,其中包含由 buttons 指定标准按钮。

另请参阅orientationaddButton()。

[虚函数 noexcept] QDialogButtonBox::~QDialogButtonBox()

销毁按钮盒。

[信号] void QDialogButtonBox::accepted()

当按钮盒中的按钮被点击时(只要它是用 AcceptRoleYesRole 定义的),则发出该信号。

另请参阅rejected(), clicked(),和 helpRequested()。

void QDialogButtonBox::addButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role)

将给定的 button 添加到按钮盒中,具有指定的 role。如果角色无效,则按钮不会被添加。

如果按钮已经添加,则删除并使用新的角色重新添加。

注意:按钮盒会获取按钮的所有权。

另请参阅removeButton() 和 clear()。

QPushButton *QDialogButtonBox::addButton(const QString &text, QDialogButtonBox::ButtonRole role)

创建一个具有给定 text 的按钮,将其添加到按钮盒的指定 role,并返回相应的按钮。如果 role 无效,则不会创建按钮,并返回零。

另请参阅removeButton() 和 clear()。

QPushButton *QDialogButtonBox::addButton(QDialogButtonBox::StandardButton button)

如果可以添加,则将标准按钮添加到按钮框,并返回一个推钮。如果按钮不合法,则不会添加到按钮框,并返回零。

另请参阅removeButton() 和 clear()。

QPushButton *QDialogButtonBox::button(QDialogButtonBox::StandardButton which) const

返回对应于标准按钮 whichQPushButton,或者如果按钮框中不存在该标准按钮,则返回 nullptr

另请参阅standardButton()、standardButtons() 和 buttons()。

QDialogButtonBox::ButtonRole QDialogButtonBox::buttonRole(QAbstractButton *button) const

返回所指定 button 的按钮角色。如果 buttonnullptr 或尚未添加到按钮框,则此函数返回 InvalidRole

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

QList<QAbstractButton *> QDialogButtonBox::buttons() const

返回已添加到按钮框的所有按钮的列表。

另请参阅buttonRole()、addButton() 和 removeButton()。

[重载虚保护] void QDialogButtonBox::changeEvent(QEvent *event)

重新实现:QWidget::changeEvent(QEvent *event)。

void QDialogButtonBox::clear()

清除按钮框,删除其中的所有按钮。

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

[信号] void QDialogButtonBox::clicked(QAbstractButton *button)

按钮框内的按钮被点击时,会发出此信号。被按下的具体按钮由 button 指定。

另请参阅accepted()、rejected() 和 helpRequested()。

[重载虚保护] bool QDialogButtonBox::event(QEvent *event)

重新实现:QWidget::event(QEvent *event)。

[信号] void QDialogButtonBox::helpRequested()

当按钮框中的按钮被点击时,只要它定义为 HelpRole,就会发出此信号。

参见accepted(),rejected(),以及clicked

[信号] void QDialogButtonBox::rejected()

当按钮框中的按钮被点击时,只要它定义为 RejectRoleNoRole,就会发出此信号。

参见accepted(),helpRequested(),以及clicked

void QDialogButtonBox::removeButton(QAbstractButton *button)

从按钮框中移除 button 而不删除它,并将它的父对象设置为 zero。

参见clear(),buttons(),以及addButton

QDialogButtonBox::StandardButton QDialogButtonBox::standardButton(QAbstractButton *button) const

返回与给定 button 对应的标准按钮枚举值,或者如果给定 button 不是标准按钮,则返回 NoButton

参见button(),buttons(),以及standardButtons

© 2024 The Qt Company Ltd. 本文档中包含的贡献文档的版权归其所有者所有。此处提供的文档是根据由自由软件基金会发布的 GNU 自由文档许可协议版本 1.3 许可的。Qt及其相应的标志是芬兰及/或其他国家/地区的The Qt Company Ltd的商标。所有其他商标均为其所有者的财产。