Modernize QMessageBox documentation and example

Change-Id: Iebcdf53646f1a42c327414edf21ac93a7d1c0a56
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

7 files changed, 42 insertions, 51 deletions

diff --git a/examples/widgets/dialogs/standarddialogs/dialog.cpp b/examples/widgets/dialogs/standarddialogs/dialog.cpp
index c9faea03f6..9f1cc96528 100644
--- a/examples/widgets/dialogs/standarddialogs/dialog.cpp
+++ b/examples/widgets/dialogs/standarddialogs/dialog.cpp
@@ -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"));
 
 }
 
diff --git a/src/corelib/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp b/src/corelib/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp
index afa4c09873..0b307c33c4 100644
--- a/src/corelib/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp
+++ b/src/corelib/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp
@@ -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();
diff --git a/src/widgets/dialogs/qmessagebox.cpp b/src/widgets/dialogs/qmessagebox.cpp
index 52a6d9282e..e38826534a 100644
--- a/src/widgets/dialogs/qmessagebox.cpp
+++ b/src/widgets/dialogs/qmessagebox.cpp
@@ -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.
 
diff --git a/src/widgets/doc/images/msgbox1.png b/src/widgets/doc/images/msgbox1.png
index 1380e20a5f..ded1d295b6 100644
--- a/src/widgets/doc/images/msgbox1.png
+++ b/src/widgets/doc/images/msgbox1.png
diff --git a/src/widgets/doc/images/msgbox2.png b/src/widgets/doc/images/msgbox2.png
index e7946996e4..9afd3282f3 100644
--- a/src/widgets/doc/images/msgbox2.png
+++ b/src/widgets/doc/images/msgbox2.png
diff --git a/src/widgets/doc/images/msgbox3.png b/src/widgets/doc/images/msgbox3.png
index bd81f4d4da..50a4a124c4 100644
--- a/src/widgets/doc/images/msgbox3.png
+++ b/src/widgets/doc/images/msgbox3.png
diff --git a/src/widgets/doc/images/msgbox4.png b/src/widgets/doc/images/msgbox4.png
index dbe6701cdd..337b3553e9 100644
--- a/src/widgets/doc/images/msgbox4.png
+++ b/src/widgets/doc/images/msgbox4.png