Modernize QMessageBox documentation and example

Change-Id: Iebcdf53646f1a42c327414edf21ac93a7d1c0a56
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This commit is contained in:
Tor Arne Vestbø 2022-11-15 19:06:26 +01:00 committed by Volker Hilsheimer
parent cbe7cead44
commit 83b31a3d99
7 changed files with 42 additions and 51 deletions

View File

@ -5,17 +5,6 @@
#include "dialog.h"
#define MESSAGE \
Dialog::tr("<p>Message boxes have a caption, a text, " \
"and any number of buttons, each with standard or custom texts.")
#define INFORMATIVE_TEXT \
Dialog::tr("<p>Click a button to close the message box. Pressing the Escape key " \
"will activate the detected escape button (if any).")
#define MESSAGE_DETAILS \
Dialog::tr("Additional detailed text can be provided, which may require user " \
"action to be revealed.")
class DialogOptionsWidget : public QGroupBox
{
public:
@ -415,8 +404,9 @@ void Dialog::setSaveFileName()
void Dialog::criticalMessage()
{
QMessageBox msgBox(QMessageBox::Critical, tr("QMessageBox::critical()"),
MESSAGE, { }, this);
msgBox.setInformativeText(INFORMATIVE_TEXT);
tr("Houston, we have a problem"), { }, this);
msgBox.setInformativeText(tr("Activating the liquid oxygen stirring fans caused an explosion in one of the tanks. " \
"Liquid oxygen levels are getting low. This may jeopardize the moon landing mission."));
msgBox.addButton(QMessageBox::Abort);
msgBox.addButton(QMessageBox::Retry);
msgBox.addButton(QMessageBox::Ignore);
@ -432,8 +422,10 @@ void Dialog::criticalMessage()
void Dialog::informationMessage()
{
QMessageBox msgBox(QMessageBox::Information, tr("QMessageBox::information()"),
MESSAGE, { }, this);
msgBox.setInformativeText(INFORMATIVE_TEXT);
tr("Elvis has left the building."), { }, this);
msgBox.setInformativeText(tr("This phrase was often used by public address announcers at the conclusion " \
"of Elvis Presley concerts in order to disperse audiences who lingered in " \
"hopes of an encore. It has since become a catchphrase and punchline."));
if (msgBox.exec() == QMessageBox::Ok)
informationLabel->setText(tr("OK"));
else
@ -443,8 +435,10 @@ void Dialog::informationMessage()
void Dialog::questionMessage()
{
QMessageBox msgBox(QMessageBox::Question, tr("QMessageBox::question()"),
MESSAGE, { }, this);
msgBox.setInformativeText(INFORMATIVE_TEXT);
tr("Would you like cheese with that?"), { }, this);
msgBox.setInformativeText(tr("A cheeseburger is a hamburger topped with cheese. Traditionally, the slice of " \
"cheese is placed on top of the meat patty. The cheese is usually added to the " \
"cooking hamburger patty shortly before serving, which allows the cheese to melt."));
msgBox.addButton(QMessageBox::Yes);
msgBox.addButton(QMessageBox::No);
msgBox.addButton(QMessageBox::Cancel);
@ -460,15 +454,15 @@ void Dialog::questionMessage()
void Dialog::warningMessage()
{
QMessageBox msgBox(QMessageBox::Warning, tr("QMessageBox::warning()"),
MESSAGE, { }, this);
msgBox.setInformativeText(INFORMATIVE_TEXT);
msgBox.setDetailedText(MESSAGE_DETAILS);
msgBox.addButton(tr("Save &Again"), QMessageBox::AcceptRole);
msgBox.addButton(tr("&Continue"), QMessageBox::RejectRole);
tr("Delete the only copy of your movie manuscript?"), { }, this);
msgBox.setInformativeText(tr("You've been working on this manuscript for 738 days now. Hang in there!"));
msgBox.setDetailedText("\"A long time ago in a galaxy far, far away....\"");
msgBox.addButton(tr("&Keep"), QMessageBox::AcceptRole);
msgBox.addButton(tr("Delete"), QMessageBox::DestructiveRole);
if (msgBox.exec() == QMessageBox::AcceptRole)
warningLabel->setText(tr("Save Again"));
warningLabel->setText(tr("Keep"));
else
warningLabel->setText(tr("Continue"));
warningLabel->setText(tr("Delete"));
}

View File

@ -77,8 +77,8 @@ msgBox.exec();
//! [6]
QMessageBox msgBox;
msgBox.setText("The document has been modified.");
msgBox.setInformativeText("Do you want to save your changes?");
msgBox.setText("Do you want to save your changes?");
msgBox.setInformativeText("The document has been modified. It was last saved 5 days ago.");
msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);
msgBox.setDefaultButton(QMessageBox::Save);
int ret = msgBox.exec();

View File

@ -516,10 +516,11 @@ void QMessageBoxPrivate::_q_clicked(QPlatformDialogHelper::StandardButton button
A message box displays a primary \l{QMessageBox::text}{text} to
alert the user to a situation, an \l{QMessageBox::informativeText}
{informative text} to further explain the alert or to ask the user
a question, and an optional \l{QMessageBox::detailedText}
{detailed text} to provide even more data if the user requests
it. A message box can also display an \l{QMessageBox::icon} {icon}
{informative text} to further explain the situation, and an optional
\l{QMessageBox::detailedText} {detailed text} to provide even more data
if the user requests it.
A message box can also display an \l{QMessageBox::icon} {icon}
and \l{QMessageBox::standardButtons} {standard buttons} for
accepting a user response.
@ -545,27 +546,21 @@ void QMessageBoxPrivate::_q_clicked(QPlatformDialogHelper::StandardButton button
\image msgbox1.png
A better approach than just alerting the user to an event is to
also ask the user what to do about it. Store the question in the
\l{QMessageBox::informativeText} {informative text} property, and
set the \l{QMessageBox::standardButtons} {standard buttons}
also ask the user what to do about it.
Set the \l{QMessageBox::standardButtons} {standard buttons}
property to the set of buttons you want as the set of user
responses. The buttons are specified by combining values from
StandardButtons using the bitwise OR operator. The display order
for the buttons is platform-dependent. For example, on Windows,
\uicontrol{Save} is displayed to the left of \uicontrol{Cancel}, whereas on
Mac OS, the order is reversed.
Mark one of your standard buttons to be your
\macos, the order is reversed. Mark one of your standard buttons to be your
\l{QMessageBox::defaultButton()} {default button}.
\snippet code/src_gui_dialogs_qmessagebox.cpp 6
The \l{QMessageBox::informativeText} {informative text} property can
be used to add additional context to help the user choose the appropriate action.
This is the approach recommended in the
\l{http://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/AppleHIGuidelines/Windows/Windows.html#//apple_ref/doc/uid/20000961-BABCAJID}
{\macos Guidelines}. Similar guidelines apply for the other
platforms, but note the different ways the
\l{QMessageBox::informativeText} {informative text} is handled for
different platforms.
\snippet code/src_gui_dialogs_qmessagebox.cpp 6
\image msgbox2.png
@ -574,10 +569,10 @@ void QMessageBoxPrivate::_q_clicked(QPlatformDialogHelper::StandardButton button
\snippet code/src_gui_dialogs_qmessagebox.cpp 7
To give the user more information to help him answer the question,
set the \l{QMessageBox::detailedText} {detailed text} property. If
the \l{QMessageBox::detailedText} {detailed text} property is set,
the \uicontrol{Show Details...} button will be shown.
To give the user more information to help them choose the appropriate,
action, set the \l{QMessageBox::detailedText} {detailed text} property.
Depending on the platform the \l{QMessageBox::detailedText} {detailed text},
may require the user to click a \uicontrol{Show Details...} button to be shown.
\image msgbox3.png
@ -1231,6 +1226,9 @@ QCheckBox* QMessageBox::checkBox() const
\property QMessageBox::text
\brief the message box text to be displayed.
The text should be a brief sentence or phrase that describes the situation,
ideally formulated as a neutral statement, or a call-to-action question.
The text will be interpreted either as a plain text or as rich text,
depending on the text format setting (\l QMessageBox::textFormat).
The default setting is Qt::AutoText, i.e., the message box will try
@ -2564,10 +2562,9 @@ void QMessageBox::setDetailedText(const QString &text)
\since 4.2
Infromative text can be used to expand upon the text() to give more
information to the user. On the Mac, this text appears in small
system font below the text(). On other platforms, it is simply
appended to the existing text.
Informative text can be used to expand upon the text() to give more
information to the user, for example describing the consequences of
the situation, or suggestion alternative solutions.
By default, this property contains an empty string.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.4 KiB

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 9.0 KiB

After

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 9.4 KiB

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 24 KiB