[Qt 教程之Widgets模块] —— QDialogButtonBox按钮框

Qt系列教程总目录

0. 简介

QDialogButtongBox是一个包含很多按钮的控件，对话框中有多个需要分组排列的按钮时，可以使用QDialogButtongBox类。
开发人员可以向QDialogButtonBox添加按钮，QDialogButtonBox会根据平台自动使用合适的布局。

Qt Creator 添加新文件的对话框和Photoshop调整曲线的对话框都可以使用QDialogButtonBox来处理：

1. 创建QDialogButtongBox

QDialogButtongBox有4个构造函数，

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

同样可以通过拖动控件创建，也可以使用代码直接创建，控件创建默认使用构造函数QDialogButtonBox(QWidget *parent = nullptr);，控件创建会默认添加cancel和ok两个标准按钮。

对于其他三个构造函数的参数，其中，Qt::Orientation是枚举，可以指定按钮纵向或横向排列（如上图两个例子）；StandardButtons也是枚举，用于指定标准按钮。

如下图创建了四个QDialogButtonBox，其中，第一行通过拖拽控件创建，其余通过代码直接创建，依次使用了上面四个构造函数：

2. 枚举

QDialogButtonBox有用到一些枚举变量，详见下方：

2.1. Qt::Orientation

按钮排列方式

enum Orientation {
    Horizontal = 0x1,
    Vertical = 0x2
};

说明：

Constant	Value	Description
Qt::Horizontal	0x1	水平排列
Qt::Vertical	0x2	垂直排列

2.2. QDialogButtonBox::ButtonRole

描述按钮角色，不同角色的按钮有不同的行为

enum ButtonRole {
    InvalidRole = -1,
    AcceptRole,
    RejectRole,
    DestructiveRole,
    ActionRole,
    HelpRole,
    YesRole,
    NoRole,
    ResetRole,
    ApplyRole,

    NRoles
};

说明：

Constant	Value	Description
QDialogButtonBox::InvalidRole	-1	无效按钮
QDialogButtonBox::AcceptRole	0	单击按钮可接受对话框（如OK按钮）
QDialogButtonBox::RejectRole	1	单击按钮可接受对话框（如Cancel按钮）
QDialogButtonBox::DestructiveRole	2	单击该按钮会导致破坏性更改（例如“放弃更改”）并关闭对话框
QDialogButtonBox::ActionRole	3	单击该按钮将更改对话框中的元素
QDialogButtonBox::HelpRole	4	单击按钮可请求帮助
QDialogButtonBox::YesRole	5	类似于“是”的按钮
QDialogButtonBox::NoRole	6	类似于“否”的按钮
QDialogButtonBox::ResetRole	7	该按钮将对话框的字段重置为默认值
QDialogButtonBox::ApplyRole	8	按钮应用当前更改

2.3. QDialogButtonBox::StandardButton

标准按钮

enum StandardButton {
    NoButton           = 0x00000000,
    Ok                 = 0x00000400,
    Save               = 0x00000800,
    SaveAll            = 0x00001000,
    Open               = 0x00002000,
    Yes                = 0x00004000,
    YesToAll           = 0x00008000,
    No                 = 0x00010000,
    NoToAll            = 0x00020000,
    Abort              = 0x00040000,
    Retry              = 0x00080000,
    Ignore             = 0x00100000,
    Close              = 0x00200000,
    Cancel             = 0x00400000,
    Discard            = 0x00800000,
    Help               = 0x01000000,
    Apply              = 0x02000000,
    Reset              = 0x04000000,
    RestoreDefaults    = 0x08000000,

#ifndef Q_MOC_RUN
    FirstButton        = Ok,
    LastButton         = RestoreDefaults
#endif
};

说明：

Constant	Value	Description
QDialogButtonBox::Ok	0x00000400	AcceptRole角色下定义的Ok按钮
QDialogButtonBox::Open	0x00002000	AcceptRole角色下定义的Open按钮
QDialogButtonBox::Save	0x00000800	AcceptRole角色下定义的Save按钮
QDialogButtonBox::Cancel	0x00400000	RejectRole角色下定义的Cancel按钮
QDialogButtonBox::Close	0x00200000	RejectRole角色下定义的Close按钮
QDialogButtonBox::Discard	0x00800000	DestructiveRole角色下定义的Discard或Don’t Save按钮，具体取决于使用的平台
QDialogButtonBox::Apply	0x02000000	ApplyRole角色下定义的Apply按钮
QDialogButtonBox::Reset	0x04000000	ResetRole角色下定义的Reset按钮
QDialogButtonBox::RestoreDefaults	0x08000000	ResetRole角色下定义的RestoreDefaults按钮
QDialogButtonBox::Help	0x01000000	HelpRole角色下定义的Help按钮
QDialogButtonBox::SaveAll	0x00001000	AcceptRole角色下定义的Save All按钮
QDialogButtonBox::Yes	0x00004000	YesRole角色下定义的Yes按钮
QDialogButtonBox::YesToAll	0x00008000	YesRole角色下定义的Yes to All按钮
QDialogButtonBox::No	0x00010000	NoRole角色下定义的No按钮
QDialogButtonBox::NoToAll	0x00020000	NoRole角色下定义的No to All按钮
QDialogButtonBox::Abort	0x00040000	RejectRole角色下定义的Abort按钮
QDialogButtonBox::Retry	0x00080000	AcceptRole角色下定义的Retry按钮
QDialogButtonBox::Ignore	0x00100000	AcceptRole角色下定义的Ignore按钮
QDialogButtonBox::NoButton	0x00000000	无效按钮

3. 成员函数与信号

QDialogButtonBox 公有继承与QWidget，所以QWidget的公有成员函数QDialogButtonBox都能使用。

QDialogButtonBox的成员函数如下：

3.1. 按钮排列方式

函数原型	描述
void setOrientation(Qt::Orientation orientation);	设置按钮排列方式，Qt::Orientation为枚举
Qt::Orientation orientation() const;	获取按钮排列方式

3.2. 添加与删除按钮

函数原型	描述
void addButton(QAbstractButton *button, ButtonRole role);	将给定按钮添加到具有指定角色的按钮框中。如果角色无效，则不添加按钮。 如果已添加按钮，则将其删除并使用新角色再次添加 按钮框拥有按钮的所有权。
QPushButton *addButton(const QString &text, ButtonRole role);	使用给定文本创建一个按钮，将其添加到指定角色的按钮框，并返回相应的按钮。如果角色无效，则不创建按钮，并返回 nullptr。
QPushButton *addButton(StandardButton button);	如果 button 有效，则将标准按钮添加到按钮框，并返回一个按钮。 如果 button 无效，则不添加到按钮框中，返回nullptr。
void removeButton(QAbstractButton *button);	从按钮框中移除按钮而不删除它并将其父级设置为nullptr。
void clear();	清除按钮框，删除其中的所有按钮。

3.3. 按钮与角色

函数原型	描述
QList buttons() const;	返回已添加到按钮框中的所有按钮的对象列表。
ButtonRole buttonRole(QAbstractButton *button) const;	返回指定按钮的按钮角色。 如果按钮为 nullptr 或尚未添加到按钮框，则返回 InvalidRole。按钮角色具体见枚举QDialogButtonBox::ButtonRole

3.4. 标准按钮

函数原型	描述
void setStandardButtons(StandardButtons buttons);	为按钮框添加标准按钮，入参为StandardButton枚举，可多个（使用|拼接）
StandardButtons standardButtons() const;	返回该按钮框已添加的标准按钮
StandardButton standardButton(QAbstractButton *button) const;	返回与给定按钮对应的标准按钮枚举值，如果给定按钮不是标准按钮，则返回 NoButton。
QPushButton *button(StandardButton which) const;	返回一个标准按钮类型的QPushButton按钮对象指针

3.5. 按钮居中

函数原型	描述
void setCenterButtons(bool center);	设置按钮框中的按钮居中
bool centerButtons() const;	返回钮框中的按钮是否设置了居中