QMessageBox

一、描述

QMessageBox 类提供了一个模态对话框，用于通知用户或询问用户问题并接收答案。

提供了两个使用 QMessageBox 的 API，基于属性的 API 和静态函数。 调用其中一个静态函数是一种更简单的方法，但它不如使用基于属性的 API 灵活，结果信息量也更少。 建议使用基于属性的 API。

1.1、基于属性的 API

要使用基于属性的 API，请构建 QMessageBox 的实例，设置所需的属性，然后调用 exec() 来显示消息。最简单的配置是只设置消息文本属性。

QMessageBox msgBox;
msgBox.setText("The document has been modified.");
msgBox.exec();

更好的方法是询问用户如何处理它。将问题存储在信息性文本属性中，并将标准按钮属性设置为想要作为用户响应集的按钮集。这些按钮是通过使用按位 OR 运算符组合来自 StandardButtons 的值来指定的。按钮的显示顺序取决于平台。

将标准按钮之一标记为默认按钮：

QMessageBox msgBox;
msgBox.setText("The document has been modified.");
msgBox.setInformativeText("Do you want to save your changes?");
msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);
msgBox.setDefaultButton(QMessageBox::Save);
int ret = msgBox.exec();

switch (ret) {
  case QMessageBox::Save:
      // Save was clicked
      break;
  case QMessageBox::Discard:
      // Don't Save was clicked
      break;
  case QMessageBox::Cancel:
      // Cancel was clicked
      break;
  default:
      // should never be reached
      break;
}

要为用户提供更多信息可设置 detailedText 属性。 如果设置了详细文本属性，将显示“Show Details... ”按钮。

1.1.2、富文本和文本格式属性

detailedText 属性总是被解释为纯文本。text 和 informativeText 属性可以是纯文本或富文本。这些字符串根据 textFormat 属性的设置进行解释。默认设置是自动文本。

1.1.3、严重级别以及图标和像素图属性

QMessageBox 支持四种预定义的消息严重性级别或消息类型，它们实际上仅在它们各自显示的预定义图标上有所不同。通过设置 icon 属性来指定四种预定义消息类型之一：

也可以使用 setIconPixmap() 设置 iconPixmap 属性自定义图标。

1.2、静态函数 API

静态函数可用于创建 information()、question()、warning() 和 critical() 消息框。

int ret = QMessageBox::warning(this, tr("My Application"),
                               tr("The document has been modified.\n"
                                  "Do you want to save your changes?"),
                               QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel,
                               QMessageBox::Save);

1.3、高级用法

如果标准按钮不够灵活，可以使用带有文本和 ButtonRole 的 addButton() 重载来添加自定义按钮。QMessageBox 使用 ButtonRole 来确定屏幕上按钮的顺序（根据平台而异）。可以在调用 exec() 后测试 clickedButton() 的值。例如：

QMessageBox msgBox;
QPushButton *connectButton = msgBox.addButton(tr("Connect"), QMessageBox::ActionRole);
QPushButton *abortButton = msgBox.addButton(QMessageBox::Abort);

msgBox.exec();

if (msgBox.clickedButton() == connectButton) {
    // connect
} else if (msgBox.clickedButton() == abortButton) {
    // 中止
}

1.4、默认和退出键

可以使用 setDefaultButton() 指定默认按钮（即按下 Enter 时激活的按钮）。如果没有指定默认按钮，QMessageBox 会尝试根据消息框中使用的按钮的 ButtonRole 来查找。

可以使用 setEscapeButton() 指定退出按钮（按下 Esc 时激活的按钮）。如果未指定退出按钮，QMessageBox 会尝试使用以下规则找到一个：

• 如果只有一个按钮，则为按下 Esc 时激活的按钮。
• 如果有一个取消按钮，它是按下 Esc 时激活的按钮。
• 如果只有一个按钮具有 Reject 角色或 No 角色，则它是在按下 Esc 时激活的按钮。

当使用这些规则无法确定退出按钮时，按 Esc 无效。

二、类型成员

1、enum QMessageBox::ButtonRole：可用于描述按钮框中的按钮的角色。这些角色的组合作为用于描述其行为的标志。

• InvalidRole：按钮无效。
• AcceptRole：接受。
• RejectRole：拒绝。
• DestructiveRole：放弃更改并关闭对话框。
• ActionRole：对话框中的元素发生变化。
• HelpRole：请求帮助。
• YesRole：“是”按钮。
• NoRole：“否”按钮。
• ApplyRole：应用。
• ResetRole：重置。

2、enum QMessageBox::Icon：图标，见1.1.3的图。

• NoIcon：没有任何图标。
• Question：正在提问。
• Information：没有异常。
• Warning：警告，但可以处理。
• Critical：严重问题。

3、enum QMessageBox::StandardButton：标准按钮的标志。每个按钮都有一个已定义的 ButtonRole。

• Ok：使用 AcceptRole 定义的 “确定” 按钮。
• Open：使用 AcceptRole 定义的 “打开” 按钮。
• Save：使用 AcceptRole 定义的 “保存” 按钮。
• Cancel：使用 RejectRole 定义的 “取消” 按钮。
• Close：使用 RejectRole 定义的 “关闭” 按钮。
• Discard：使用 DestructiveRole 定义的 “放弃” 或 “不保存” 按钮，取决于平台。
• Apply：使用 ApplyRole 定义的 “应用” 按钮。
• Reset：使用 ResetRole 定义的 “重置” 按钮。
• RestoreDefaults：使用 ResetRole 定义的 “恢复默认值” 按钮。
• Help：使用 HelpRole 定义的 “帮助” 按钮。
• SaveAll：使用 AcceptRole 定义的 “全部保存” 按钮。
• Yes：使用 YesRole 定义的 “是” 按钮。
• YesToAll：使用 YesRole 定义的 “全部同意” 按钮。
• No：使用 NoRole 定义的 “否” 按钮。
• NoToAll：使用 NoRole 定义的 “拒绝所有” 按钮。
• Abort：使用 RejectRole 定义的 “中止” 按钮。
• Retry：使用 AcceptRole 定义的 “重试” 按钮。
• Ignore：使用 AcceptRole 定义的 “忽略” 按钮。
• NoButton：无效按钮。

三、属性成员

1、detailedText : QString

要在详细信息区域中显示的文本。文本将被解释为纯文本。

2、icon : Icon

图标。默认值为 QMessageBox::NoIcon。

3、iconPixmap : QPixmap

自定义的像素图图标。

4、informativeText : QString

为消息提供更完整描述的信息文本。

信息性文本可用于扩展 text() 以向用户提供更多信息。在 Mac 上，此文本以小系统字体显示在 text() 下方。在其他平台上，它只是简单地附加到现有文本中。

5、standardButtons : StandardButtons

标准按钮的集合。控制消息框使用哪些标准按钮。默认不包含标准按钮。

6、text : QString

要显示的消息框文本。文本将被解释为纯文本或富文本，具体取决于 textFormat。

7、textFormat : Qt::TextFormat

消息框显示的文本格式。默认为 Qt::AutoText。

• Qt::PlainText：纯文本字符串。
• Qt::RichText：富文本字符串。
• Qt::AutoText：自动检测。
• Qt::MarkdownText：Markdown 格式的文本。

8、textInteractionFlags : Qt::TextInteractionFlags

消息框的标签应如何与用户输入交互。默认值取决于样式。

• Qt::NoTextInteraction：不与文本交互。
• Qt::TextSelectableByMouse：可以使用鼠标选择文本并使用上下文菜单或快捷键将文本复制到剪贴板。
• Qt::TextSelectableByKeyboard：可以使用键盘上的光标键选择文本。显示文本光标。
• Qt::LinksAccessibleByMouse：可以用鼠标突出显示和激活链接。
• Qt::LinksAccessibleByKeyboard：链接可以使用 tab 聚焦并使用 Enter 激活。
• Qt::TextEditable：文本可编辑。
• Qt::TextEditorInteraction：TextSelectableByMouse | TextSelectableByKeyboard | TextEditable）
• Qt::TextBrowserInteraction：TextSelectableByMouse | LinksAccessibleByMouse | LinksAccessibleByKeyboard

四、成员函数

1、【信号】void buttonClicked(QAbstractButton *button）

每当单击 QMessageBox 内的按钮时，都会发出此信号。 

2、int exec()

重新实现：QDialog::exec()。

将消息框显示为模态对话框，在用户关闭它之前一直处于阻塞状态。

• 当使用带有标准按钮的 QMessageBox 时，此函数返回一个 StandardButton 值，指示被单击的标准按钮。
• 当使用带有自定义按钮的 QMessageBox 时，不能根据返回值确定按下的按钮，这时候使用 clickedButton() 来确定单击了哪个按钮。

注意：result() （QDialog::result()）也返回 StandardButton 值而不是 QDialog::DialogCode。

3、【static】void about(QWidget *parent, const QString &title, const QString &text)

弹出一个简单对话框显示信息。

4、void aboutQt(QWidget *parent, const QString &title = QString())

显示一个关于 Qt 的简单消息框，该消息包括应用程序正在使用的 Qt 的版本号。

5、void addButton(QAbstractButton *button, QMessageBox::ButtonRole role)

添加按钮到具有指定角色的消息框中。

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

使用给定文本创建一个按钮，将其添加到指定角色的消息框中，然后返回它。

      QPushButton *addButton(QMessageBox::StandardButton button)

将标准按钮添加到消息框，并返回按钮。

6、QAbstractButton * button(QMessageBox::StandardButton which)

返回与标准按钮对应的指针。

7、QMessageBox::ButtonRole buttonRole(QAbstractButton *button)

返回指定按钮的按钮角色。如果按钮为 nullptr 或尚未添加到消息框，则返回 InvalidRole。

8、QList<QAbstractButton *> buttons()

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

9、void setCheckBox(QCheckBox *cb) / QCheckBox *checkBox()

常量设置消息对话框上的复选框。消息框拥有复选框的所有权。参数 cb 可以是 nullptr 以从消息框中删除现有复选框。

10、QAbstractButton * clickedButton()

返回用户单击的按钮，如果用户按 Esc 键且未设置转义按钮，则返回 nullptr。

如果尚未调用 exec()，则返回 nullptr。

QMessageBox messageBox(this);
QAbstractButton *disconnectButton =
      messageBox.addButton(tr("Disconnect"), QMessageBox::ActionRole);
...
messageBox.exec();
if (messageBox.clickedButton() == disconnectButton) {
    ...
}

11、【static】QMessageBox::StandardButton critical(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

        【static】QMessageBox::StandardButton information(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

       【static】QMessageBox::StandardButton question(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = StandardButtons(Yes | No), QMessageBox::StandardButton defaultButton = NoButton)

        【static】QMessageBox::StandardButton warning(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

打开一个带有给定标题和文本的相应类型的消息框。

defaultButton 指定按下 Enter 时使用的按钮。defaultButton 必须引用 buttons 中给出的按钮。如果 defaultButton 是 QMessageBox::NoButton，QMessageBox 会自动选择一个合适的默认值。

12、QAbstractButton * escapeButton()

        void setEscapeButton(QAbstractButton *button)

        void setEscapeButton(QMessageBox::StandardButton button)

按下 Esc 时激活的按钮。

默认情况下，QMessageBox 会尝试自动检测退出按钮：

• 如果只有一个按钮，则将其设为退出按钮。
• 如果有 Cancel 按钮，则将其设为退出按钮。

13、void open(QObject *receiver, const char *member)

重新实现 QDialog::open()。

打开对话框并将其 finished() 或 buttonClicked() 信号连接到 receiver 和member 指定的槽。如果成员中的插槽具有指向其第一个参数的指针，则连接到 buttonClicked()，否则连接到 finished()。

当对话框关闭时，信号将与插槽断开连接。

14、void removeButton(QAbstractButton *button)

移除按钮而不删除它。

15、void setDefaultButton(QPushButton *button) / QPushButton *defaultButton()

        void setDefaultButton(QMessageBox::StandardButton button)

设置消息框的默认按钮，即按下回车键会触发的按钮。

16、void setWindowModality(Qt::WindowModality windowModality)

设置消息框的模态。

在 macOS 上，如果模态设置为 Qt::WindowModal 并且消息框有父级，则消息框将是 Qt::Sheet，否则消息框将是标准对话框。

17、QMessageBox::StandardButton standardButton(QAbstractButton *button)

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