文章目录
QMessageBox Class
QMessageBox类提供了一个模式对话框,用于通知用户或询问用户问题并接收答案。
Header | #include < QMessageBox > |
---|---|
qmake | QT += widgets |
Inherits | QDialog |
Inherited By |
详细说明
消息框显示一个基本的文本,用于向用户提示某个情况;一个信息性文本,用于进一步解释警报或向用户提问;一个可选的详细文本,用于在用户请求时提供更多数据。消息框还可以显示图标和用于接受用户响应的标准按钮。
提供了两个用于使用QMessageBox的API:基于属性的API和静态函数。调用其中一个静态函数是一种更简单的方法,但它不如使用基于属性的API灵活,而且结果的信息量也较少。建议使用基于属性的API。
基于属性的API
要使用基于属性的API,请构造QMessageBox的实例,设置所需的属性,然后调用exec() 来显示消息。最简单的配置是只设置message text属性。
QMessageBox msgBox;
msgBox.setText("The document has been modified.");
msgBox.exec();
用户必须单击“确定”按钮以关闭消息框。GUI的其余部分将被阻止,直到消息框被取消。
一个比仅仅提醒用户某个事件更好的方法是同时询问用户该怎么做。将问题存储在informational text属性中,并将standard buttons属性设置为要作为用户响应集的按钮集。这些按钮是通过使用位或运算符组合来自标准按钮的值来指定的。按钮的显示顺序取决于平台。例如,在Windows上,“保存”显示在“取消”的左侧,而在Mac OS上,顺序相反。
将一个标准按钮标记为默认按钮。
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();
这是macOS指南中推荐的方法。类似的指导原则也适用于其他平台,但请注意,不同平台处理信息文本的方式不同。
exec() 槽返回所单击按钮的StandardButtons值。
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;
}
要向用户提供更多信息以帮助他回答问题,请设置detailed text属性。如果设置了详细文本属性,则显示详细信息。。。按钮将显示。
单击“显示详细信息…”按钮显示详细文本。
富文本和文本格式属性
详细文本属性始终解释为纯文本。主文本和信息文本属性可以是纯文本或富文本。这些字符串将根据文本格式属性的设置进行解释。默认设置为“自动文本”。
请注意,对于某些包含XML元字符的纯文本字符串,自动文本富文本检测测试可能会失败,从而导致纯文本字符串被错误地解释为富文本。在这些罕见的情况下,可以使用Qt::convertFromPlainText() 将纯文本字符串转换为视觉上等效的富文本字符串,或者使用setTextFormat() 显式设置text format属性。
严重性级别以及图标和像素映射属性
QMessageBox支持四种预定义的消息严重性级别或消息类型,它们只在各自显示的预定义图标上有所不同。通过将icon属性设置为预定义图标之一,指定四种预定义消息类型之一。以下规则是指导原则:
Icon | 信息类型 | 简介 |
---|---|---|
Question | 在正常操作中提问。 | |
Information | 用于报告有关正常操作的信息。 | |
Warning | 用于报告非关键错误。 | |
Critical | 用于报告严重错误。 |
预定义图标不是由QMessageBox定义的,而是由样式提供的。默认值为“无图标”。消息框在其他方面对于所有情况都是相同的。使用标准图标时,请使用表中建议的图标,或使用您平台的样式指南中建议的图标。如果没有一个标准图标适合您的消息框,您可以通过设置icon pixmap属性而不是icon属性来使用自定义图标。
总之,要设置图标,请对其中一个标准图标使用setIcon() ,或对自定义图标使用setIconPixmap() 。
静态函数API
使用静态函数API构建消息框虽然方便,但不如使用基于属性的API灵活,因为静态函数签名缺少设置信息文本和详细文本属性的参数。解决方法之一是将title参数用作消息框主文本,将text参数用作消息框信息文本。因为这有一个明显的缺点,那就是生成可读性较差的消息框,所以平台指南不建议这样做。Microsoft Windows用户界面指南建议使用应用程序名称作为窗口标题,这意味着如果除了主文本之外还有信息性文本,则必须将其连接到文本参数。
请注意,静态函数签名相对于其按钮参数发生了更改,这些参数现在用于设置标准按钮和默认按钮。
静态函数可用于创建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);
标准对话框示例演示如何使用QMessageBox和其他内置Qt对话框。
高级用法
如果消息框中的标准按钮不够灵活,可以使用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) {
// abort
}
默认和Escape键
可以使用setDefaultButton() 指定默认按钮(即按下Enter时激活的按钮)。如果未指定默认按钮,QMessageBox将尝试根据消息框中使用的按钮的按钮角色查找一个按钮。
可以使用setEscapeButton() 指定escape按钮(按下Esc时激活的按钮)。如果未指定转义按钮,QMessageBox将尝试使用以下规则查找Esc按钮:
- 如果只有一个按钮,则是按下Esc时激活的按钮。
- 如果有一个取消按钮,它是按下Esc时激活的按钮。
- 如果只有一个按钮具有拒绝角色或无角色,则该按钮在按下Esc时激活。
当使用这些规则无法确定转义按钮时,按Esc键没有效果。
公共类型
enum ButtonRole
此枚举描述可用于描述按钮框中的按钮的角色。这些角色的组合作为标志,用于描述其行为的不同方面。
Constant | Value | Description |
---|---|---|
QMessageBox::InvalidRole | -1 | 按钮无效。 |
QMessageBox::AcceptRole | 0 | 单击按钮可接受对话框(例如,确定)。 |
QMessageBox::RejectRole | 1 | 单击按钮会导致对话框被拒绝(例如取消)。 |
QMessageBox::DestructiveRole | 2 | 单击该按钮会导致破坏性更改(例如放弃更改)并关闭对话框。 |
QMessageBox::ActionRole | 3 | 单击该按钮会更改对话框中的元素。 |
QMessageBox::HelpRole | 4 | 可以单击该按钮请求帮助。 |
QMessageBox::YesRole | 5 | 这个按钮是一个类似“是”的按钮。 |
QMessageBox::NoRole | 6 | 这个按钮是一个类似“不”的按钮。 |
QMessageBox::ApplyRole | 8 | 按钮应用当前更改。 |
QMessageBox::ResetRole | 7 | 该按钮将对话框的字段重置为默认值。 |
enum Icon
Constant | Value | Description |
---|---|---|
QMessageBox::NoIcon | 0 | 消息框没有任何图标。 |
QMessageBox::Information | 1 | 一个图标,表示该消息没有任何异常。 |
QMessageBox::Warning | 2 | 一个图标,指示该消息是一个警告,但可以处理。 |
QMessageBox::Critical | 3 | 指示消息表示严重问题的图标。 |
QMessageBox::Question | 4 | 指示消息正在询问问题的图标。 |
enum StandardButton
flags StandardButtons
这些枚举描述标准按钮的标志。每个按钮都有一个已定义的按钮角色。
Constant | Value | Description |
---|---|---|
QMessageBox::NoButton | 0x00000000 | 无效按钮。 |
QMessageBox::Ok | 0x00000400 | 用AcceptRole定义的“OK”按钮。 |
QMessageBox::Save | 0x00000800 | 用AcceptRole定义的“Save”按钮。 |
QMessageBox::SaveAll | 0x00001000 | 用AcceptRole定义的“Save All”按钮。 |
QMessageBox::Open | 0x00002000 | 用AcceptRole定义的“Open”按钮。 |
QMessageBox::Yes | 0x00004000 | 用YesRole定义的“Yes”按钮。 |
QMessageBox::YesToAll | 0x00008000 | 用YesRole定义的“YesToAll”按钮。 |
QMessageBox::No | 0x00010000 | 用NoRole定义的“No”按钮。 |
QMessageBox::NoToAll | 0x00020000 | 用NoRole定义的“拒绝所有”按钮。 |
QMessageBox::Abort | 0x00040000 | 用RejectRole定义的“中止”按钮。 |
QMessageBox::Retry | 0x00080000 | 用AcceptRole定义的“重试”按钮。 |
QMessageBox::Ignore | 0x00100000 | 用AcceptRole定义的“忽略”按钮。 |
QMessageBox::Close | 0x00200000 | 用RejectRole定义的“Close”按钮。 |
QMessageBox::Cancel | 0x00400000 | 用RejectRole定义的“取消”按钮。 |
QMessageBox::Discard | 0x00800000 | “Discard”或“Don’t Save”按钮,取决于平台,由DestructiveRole定义。 |
QMessageBox::Help | 0x01000000 | 用HelpRole定义的“Help”按钮。 |
QMessageBox::Apply | 0x02000000 | 用ApplyRole定义的“Apply”按钮。 |
QMessageBox::Reset | 0x04000000 | 用ResetRole定义的“Reset”按钮。 |
QMessageBox::RestoreDefaults | 0x08000000 | 用ResetRole定义的“恢复默认值”按钮。 |
属性
-
detailedText: QString 保存要在详细信息区域中显示的文本
文本将被解释为纯文本。 默认情况下,此属性包含空字符串。
- QString detailedText() const
- void setDetailedText(const QString &text)
-
icon: Icon 保存消息框的图标
可以使用以下值之一指定消息框的图标:
- QMessageBox::NoIcon
- QMessageBox::Question
- QMessageBox::Information
- QMessageBox::Warning
- QMessageBox::Critical
默认值是QMessageBox::NoIcon。
用于显示实际图标的pixmap取决于当前的GUI样式。也可以通过设置icon pixmap属性为图标设置自定义pixmap。
- QMessageBox::Icon icon() const
- void setIcon(QMessageBox::Icon)
-
iconPixmap: QPixmap 保存当前图标
消息框当前使用的图标。请注意,通常很难绘制一个在所有GUI样式中都合适的pixmap;您可能需要为每个平台提供不同的pixmap。 默认情况下,此属性未定义。
- QPixmap iconPixmap() const
- void setIconPixmap(const QPixmap &pixmap)
-
informativeText: QString 包含为消息提供更完整描述的信息性文本
信息的text可用于展开text() ,以向用户提供更多信息。在Mac上,此文本以系统小字体显示在text() 下方。在其他平台上,它只是附加到现有文本中。 默认情况下,此属性包含空字符串。
- QString informativeText() const
- void setInformativeText(const QString &text)
-
standardButtons: StandardButtons 消息框中的标准按钮集合
此属性控制消息框使用的标准按钮。 默认情况下,此属性不包含标准按钮。
- QMessageBox::StandardButtons standardButtons() const
- void setStandardButtons(QMessageBox::StandardButtons buttons)
-
text: QString 保存要显示的消息框文本
文本将被解释为纯文本或富文本,具体取决于文本格式设置(QMessageBox::textFormat)。默认设置为Qt::自动图文集,即消息框将尝试自动检测文本的格式。此属性的默认值为空字符串。
- QString text() const
- void setText(const QString &text)
-
textFormat: Qt::TextFormat 保存消息框显示的文本格式
消息框使用的当前文本格式。有关可能选项的说明,请参见Qt::TextFormat枚举。
默认格式是Qt::AutoText。- Qt::TextFormat textFormat() const
- void setTextFormat(Qt::TextFormat format)
-
textInteractionFlags: Qt::TextInteractionFlags 指定消息框的标签应如何与用户输入交互
默认值取决于样式。
公共函数
构造和析构
- QMessageBox(QMessageBox::Icon icon, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = NoButton, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint)
- QMessageBox(QWidget *parent = nullptr)
- virtual ~QMessageBox()
属性相关
- QString detailedText() const
void setDetailedText(const QString &text) - QMessageBox::Icon icon() const
void setIcon(QMessageBox::Icon) - QPixmap iconPixmap() const
void setIconPixmap(const QPixmap &pixmap) - QString informativeText() const
void setInformativeText(const QString &text) - QMessageBox::StandardButtons standardButtons() const
void setStandardButtons(QMessageBox::StandardButtons buttons) - QString text() const
void setText(const QString &text) - Qt::TextFormat textFormat() const
void setTextFormat(Qt::TextFormat format) - Qt::TextInteractionFlags textInteractionFlags() const
void setTextInteractionFlags(Qt::TextInteractionFlags flags)
增删查
- void addButton(QAbstractButton *button, QMessageBox::ButtonRole role)
QPushButton * addButton(const QString &text, QMessageBox::ButtonRole role)
QPushButton * addButton(QMessageBox::StandardButton button) - QAbstractButton * button(QMessageBox::StandardButton which) const
- QList<QAbstractButton *> buttons() const
- QMessageBox::ButtonRole buttonRole(QAbstractButton *button) const
- void removeButton(QAbstractButton *button)
- QMessageBox::StandardButton standardButton(QAbstractButton *button) const
常用
-
QCheckBox * checkBox() const
void setCheckBox(QCheckBox *cb) -
Qt::TextInteractionFlags textInteractionFlags() const
void setTextInteractionFlags(Qt::TextInteractionFlags flags) -
QPushButton * defaultButton() const
void setDefaultButton(QPushButton *button)
void setDefaultButton(QMessageBox::StandardButton button) -
QAbstractButton * escapeButton() const
void setEscapeButton(QAbstractButton *button)
void setEscapeButton(QMessageBox::StandardButton button)
其它
-
void open(QObject *receiver, const char *member)
-
QAbstractButton * clickedButton() const
返回用户单击的按钮,如果用户按Esc键但未设置escape按钮,则返回nullptr
如果尚未调用exec() ,则返回nullptr。
例子:QMessageBox messageBox(this); QAbstractButton *disconnectButton = messageBox.addButton(tr("Disconnect"), QMessageBox::ActionRole); ... messageBox.exec(); if (messageBox.clickedButton() == disconnectButton) { ... }
-
void setWindowModality(Qt::WindowModality windowModality)
-
void setWindowTitle(const QString &title)