1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include <QtGui/qmessagebox.h>

    43 

    44 #ifndef QT_NO_MESSAGEBOX

    45 

    46 #include <QtGui/qdialogbuttonbox.h>

    47 #include "private/qlabel_p.h"

    48 #include "private/qapplication_p.h"

    49 #include <QtCore/qlist.h>

    50 #include <QtCore/qdebug.h>

    51 #include <QtGui/qstyle.h>

    52 #include <QtGui/qstyleoption.h>

    53 #include <QtGui/qgridlayout.h>

    54 #include <QtGui/qdesktopwidget.h>

    55 #include <QtGui/qpushbutton.h>

    56 #include <QtGui/qaccessible.h>

    57 #include <QtGui/qicon.h>

    58 #include <QtGui/qtextdocument.h>

    59 #include <QtGui/qapplication.h>

    60 #include <QtGui/qtextedit.h>

    61 #include <QtGui/qmenu.h>

    62 #include "qdialog_p.h"

    63 #include <QtGui/qfont.h>

    64 #include <QtGui/qfontmetrics.h>

    65 #include <QtGui/qclipboard.h>

    66 

    67 #ifdef Q_WS_WINCE

    68 extern bool qt_wince_is_mobile();    //defined in qguifunctions_wince.cpp

    69 extern bool qt_wince_is_smartphone();//defined in qguifunctions_wince.cpp

    70 extern bool qt_wince_is_pocket_pc(); //defined in qguifunctions_wince.cpp

    71 

    72 #include "qguifunctions_wince.h"

    73 #endif

    74 

    75 QT_BEGIN_NAMESPACE

    76 

    77 enum Button { Old_Ok = 1, Old_Cancel = 2, Old_Yes = 3, Old_No = 4, Old_Abort = 5, Old_Retry = 6,

    78               Old_Ignore = 7, Old_YesAll = 8, Old_NoAll = 9, Old_ButtonMask = 0xFF,

    79               NewButtonMask = 0xFFFFFC00 };

    80 

    81 enum DetailButtonLabel { ShowLabel = 0, HideLabel = 1 };

    82 #ifndef QT_NO_TEXTEDIT

    83 class QMessageBoxDetailsText : public QWidget

    84 {

    85 public:

    86     class TextEdit : public QTextEdit

    87     {

    88     public:

    89         TextEdit(QWidget *parent=0) : QTextEdit(parent) { }

    90         void contextMenuEvent(QContextMenuEvent * e)

    91         {

    92 #ifndef QT_NO_CONTEXTMENU

    93             QMenu *menu = createStandardContextMenu();

    94             menu->exec(e->globalPos());

    95             delete menu;

    96 #else

    97             Q_UNUSED(e);

    98 #endif

    99         }

   100     };

   101 

   102     QMessageBoxDetailsText(QWidget *parent=0)

   103         : QWidget(parent)

   104     {

   105         QVBoxLayout *layout = new QVBoxLayout;

   106         layout->setMargin(0);

   107         QFrame *line = new QFrame(this);

   108         line->setFrameShape(QFrame::HLine);

   109         line->setFrameShadow(QFrame::Sunken);

   110         layout->addWidget(line);

   111         textEdit = new TextEdit();

   112         textEdit->setFixedHeight(100);

   113         textEdit->setFocusPolicy(Qt::NoFocus);

   114         textEdit->setReadOnly(true);

   115         layout->addWidget(textEdit);

   116         setLayout(layout);

   117     }

   118     void setText(const QString &text) { textEdit->setPlainText(text); }

   119     QString text() const { return textEdit->toPlainText(); }

   120     QString label(DetailButtonLabel label)

   121         { return label == ShowLabel ? QMessageBox::tr("Show Details...")

   122                                     : QMessageBox::tr("Hide Details..."); }

   123 private:

   124     TextEdit *textEdit;

   125 };

   126 #endif // QT_NO_TEXTEDIT

   127 

   128 class QMessageBoxPrivate : public QDialogPrivate

   129 {

   130     Q_DECLARE_PUBLIC(QMessageBox)

   131 

   132 public:

   133     QMessageBoxPrivate() : escapeButton(0), defaultButton(0), clickedButton(0), detailsButton(0),

   134 #ifndef QT_NO_TEXTEDIT

   135                            detailsText(0),

   136 #endif

   137                            compatMode(false), autoAddOkButton(true),

   138                            detectedEscapeButton(0), informativeLabel(0) { }

   139 

   140     void init(const QString &title = QString(), const QString &text = QString());

   141     void _q_buttonClicked(QAbstractButton *);

   142 

   143     QAbstractButton *findButton(int button0, int button1, int button2, int flags);

   144     void addOldButtons(int button0, int button1, int button2);

   145 

   146     QAbstractButton *abstractButtonForId(int id) const;

   147     int execReturnCode(QAbstractButton *button);

   148 

   149     void detectEscapeButton();

   150     void updateSize();

   151     int layoutMinimumWidth();

   152     void retranslateStrings();

   153 

   154 #ifdef Q_WS_WINCE

   155     void hideSpecial();

   156 #endif

   157 

   158     static int showOldMessageBox(QWidget *parent, QMessageBox::Icon icon,

   159                                  const QString &title, const QString &text,

   160                                  int button0, int button1, int button2);

   161     static int showOldMessageBox(QWidget *parent, QMessageBox::Icon icon,

   162                                  const QString &title, const QString &text,

   163                                  const QString &button0Text,

   164                                  const QString &button1Text,

   165                                  const QString &button2Text,

   166                                  int defaultButtonNumber,

   167                                  int escapeButtonNumber);

   168 

   169     static QMessageBox::StandardButton showNewMessageBox(QWidget *parent,

   170                 QMessageBox::Icon icon, const QString& title, const QString& text,

   171                 QMessageBox::StandardButtons buttons, QMessageBox::StandardButton defaultButton);

   172 

   173     static QPixmap standardIcon(QMessageBox::Icon icon, QMessageBox *mb);

   174 

   175     QLabel *label;

   176     QMessageBox::Icon icon;

   177     QLabel *iconLabel;

   178     QDialogButtonBox *buttonBox;

   179     QList<QAbstractButton *> customButtonList;

   180     QAbstractButton *escapeButton;

   181     QPushButton *defaultButton;

   182     QAbstractButton *clickedButton;

   183     QPushButton *detailsButton;

   184 #ifndef QT_NO_TEXTEDIT

   185     QMessageBoxDetailsText *detailsText;

   186 #endif

   187     bool compatMode;

   188     bool autoAddOkButton;

   189     QAbstractButton *detectedEscapeButton;

   190     QLabel *informativeLabel;

   191     QPointer<QObject> receiverToDisconnectOnClose;

   192     QByteArray memberToDisconnectOnClose;

   193     QByteArray signalToDisconnectOnClose;

   194 };

   195 

   196 void QMessageBoxPrivate::init(const QString &title, const QString &text)

   197 {

   198     Q_Q(QMessageBox);

   199 

   200     label = new QLabel;

   201     label->setObjectName(QLatin1String("qt_msgbox_label"));

   202     label->setTextInteractionFlags(Qt::TextInteractionFlags(q->style()->styleHint(QStyle::SH_MessageBox_TextInteractionFlags, 0, q)));

   203     label->setAlignment(Qt::AlignVCenter | Qt::AlignLeft);

   204     label->setOpenExternalLinks(true);

   205 #if defined(Q_WS_MAC)

   206     label->setContentsMargins(16, 0, 0, 0);

   207 #elif !defined(Q_WS_QWS)

   208     label->setContentsMargins(2, 0, 0, 0);

   209     label->setIndent(9);

   210 #endif

   211     icon = QMessageBox::NoIcon;

   212     iconLabel = new QLabel;

   213     iconLabel->setObjectName(QLatin1String("qt_msgboxex_icon_label"));

   214     iconLabel->setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Fixed);

   215 

   216     buttonBox = new QDialogButtonBox;

   217     buttonBox->setObjectName(QLatin1String("qt_msgbox_buttonbox"));

   218     buttonBox->setCenterButtons(q->style()->styleHint(QStyle::SH_MessageBox_CenterButtons, 0, q));

   219     QObject::connect(buttonBox, SIGNAL(clicked(QAbstractButton*)),

   220                      q, SLOT(_q_buttonClicked(QAbstractButton*)));

   221 

   222     QGridLayout *grid = new QGridLayout;

   223 #ifndef Q_WS_MAC

   224     grid->addWidget(iconLabel, 0, 0, 2, 1, Qt::AlignTop);

   225     grid->addWidget(label, 0, 1, 1, 1);

   226     // -- leave space for information label --

   227     grid->addWidget(buttonBox, 2, 0, 1, 2);

   228 #else

   229     grid->setMargin(0);

   230     grid->setVerticalSpacing(8);

   231     grid->setHorizontalSpacing(0);

   232     q->setContentsMargins(24, 15, 24, 20);

   233     grid->addWidget(iconLabel, 0, 0, 2, 1, Qt::AlignTop | Qt::AlignLeft);

   234     grid->addWidget(label, 0, 1, 1, 1);

   235     // -- leave space for information label --

   236     grid->setRowStretch(1, 100);

   237     grid->setRowMinimumHeight(2, 6);

   238     grid->addWidget(buttonBox, 3, 1, 1, 1);

   239 #endif

   240 

   241     grid->setSizeConstraint(QLayout::SetNoConstraint);

   242     q->setLayout(grid);

   243 

   244     if (!title.isEmpty() || !text.isEmpty()) {

   245         q->setWindowTitle(title);

   246         q->setText(text);

   247     }

   248     q->setModal(true);

   249 

   250 #ifdef Q_WS_MAC

   251     QFont f = q->font();

   252     f.setBold(true);

   253     label->setFont(f);

   254 #endif

   255     retranslateStrings();

   256 }

   257 

   258 int QMessageBoxPrivate::layoutMinimumWidth()

   259 {

   260     layout->activate();

   261     return layout->totalMinimumSize().width();

   262 }

   263 

   264 void QMessageBoxPrivate::updateSize()

   265 {

   266     Q_Q(QMessageBox);

   267 

   268     if (!q->isVisible())

   269         return;

   270 

   271     QSize screenSize = QApplication::desktop()->availableGeometry(QCursor::pos()).size();

   272 #if defined(Q_WS_QWS) || defined(Q_WS_WINCE) || defined(Q_OS_SYMBIAN)

   273     // the width of the screen, less the window border.

   274     int hardLimit = screenSize.width() - (q->frameGeometry().width() - q->geometry().width());

   275 #else

   276     int hardLimit = qMin(screenSize.width() - 480, 1000); // can never get bigger than this

   277     // on small screens allows the messagebox be the same size as the screen

   278     if (screenSize.width() <= 1024)

   279         hardLimit = screenSize.width();

   280 #endif

   281 #ifdef Q_WS_MAC

   282     int softLimit = qMin(screenSize.width()/2, 420);

   283 #elif defined(Q_WS_QWS)

   284     int softLimit = qMin(hardLimit, 500);

   285 #else

   286     // note: ideally on windows, hard and soft limits but it breaks compat

   287 #ifndef Q_WS_WINCE

   288     int softLimit = qMin(screenSize.width()/2, 500);

   289 #else

   290     int softLimit = qMin(screenSize.width() * 3 / 4, 500);

   291 #endif //Q_WS_WINCE

   292 #endif

   293 

   294     if (informativeLabel)

   295         informativeLabel->setSizePolicy(QSizePolicy::Ignored, QSizePolicy::Ignored);

   296 

   297     label->setWordWrap(false); // makes the label return min size

   298     int width = layoutMinimumWidth();

   299 

   300     if (width > softLimit) {

   301         label->setWordWrap(true);

   302         width = qMax(softLimit, layoutMinimumWidth());

   303 

   304         if (width > hardLimit) {

   305             label->d_func()->ensureTextControl();

   306             if (QTextControl *control = label->d_func()->control) {

   307                 QTextOption opt = control->document()->defaultTextOption();

   308                 opt.setWrapMode(QTextOption::WrapAnywhere);

   309                 control->document()->setDefaultTextOption(opt);

   310             }

   311             width = hardLimit;

   312         }

   313 #ifdef Q_WS_S60

   314         // in S60 portait messageBoxes should always occupy maximum width

   315         if (QApplication::desktop()->size().height() > QApplication::desktop()->size().width()){

   316             width = hardLimit;

   317         } else {

   318             // in landscape the messageBoxes should be of same width as in portrait

   319             width = qMin(QApplication::desktop()->size().height(), hardLimit);

   320         }

   321 #endif

   322     }

   323 

   324     if (informativeLabel) {

   325         label->setSizePolicy(QSizePolicy::Ignored, QSizePolicy::Ignored);

   326         QSizePolicy policy(QSizePolicy::Minimum, QSizePolicy::Preferred);

   327         policy.setHeightForWidth(true);

   328         informativeLabel->setSizePolicy(policy);

   329         width = qMax(width, layoutMinimumWidth());

   330         if (width > hardLimit) { // longest word is really big, so wrap anywhere

   331             informativeLabel->d_func()->ensureTextControl();

   332             if (QTextControl *control = informativeLabel->d_func()->control) {

   333                 QTextOption opt = control->document()->defaultTextOption();

   334                 opt.setWrapMode(QTextOption::WrapAnywhere);

   335                 control->document()->setDefaultTextOption(opt);

   336             }

   337             width = hardLimit;

   338         }

   339         policy.setHeightForWidth(label->wordWrap());

   340         label->setSizePolicy(policy);

   341     }

   342 

   343     QFontMetrics fm(QApplication::font("QWorkspaceTitleBar"));

   344     int windowTitleWidth = qMin(fm.width(q->windowTitle()) + 50, hardLimit);

   345     if (windowTitleWidth > width)

   346         width = windowTitleWidth;

   347 

   348     layout->activate();

   349     int height = (layout->hasHeightForWidth())

   350                      ? layout->totalHeightForWidth(width)

   351                      : layout->totalMinimumSize().height();

   352     q->setFixedSize(width, height);

   353     QCoreApplication::removePostedEvents(q, QEvent::LayoutRequest);

   354 }

   355 

   356 

   357 #ifdef Q_WS_WINCE

   358 /*!

   359   \internal

   360   Hides special buttons which are rather shown in the title bar

   361   on WinCE, to conserve screen space.

   362 */

   363 

   364 void QMessageBoxPrivate::hideSpecial()

   365 {

   366     Q_Q(QMessageBox);

   367     QList<QPushButton*> list = qFindChildren<QPushButton*>(q);

   368         for (int i=0; i<list.size(); ++i) {

   369             QPushButton *pb = list.at(i);

   370             QString text = pb->text();

   371             text.remove(QChar::fromLatin1('&'));

   372             if (text == QApplication::translate("QMessageBox", "OK" ))

   373                 pb->setFixedSize(0,0);

   374         }

   375 }

   376 #endif

   377 

   378 static int oldButton(int button)

   379 {

   380     switch (button & QMessageBox::ButtonMask) {

   381     case QMessageBox::Ok:

   382         return Old_Ok;

   383     case QMessageBox::Cancel:

   384         return Old_Cancel;

   385     case QMessageBox::Yes:

   386         return Old_Yes;

   387     case QMessageBox::No:

   388         return Old_No;

   389     case QMessageBox::Abort:

   390         return Old_Abort;

   391     case QMessageBox::Retry:

   392         return Old_Retry;

   393     case QMessageBox::Ignore:

   394         return Old_Ignore;

   395     case QMessageBox::YesToAll:

   396         return Old_YesAll;

   397     case QMessageBox::NoToAll:

   398         return Old_NoAll;

   399     default:

   400         return 0;

   401     }

   402 }

   403 

   404 int QMessageBoxPrivate::execReturnCode(QAbstractButton *button)

   405 {

   406     int ret = buttonBox->standardButton(button);

   407     if (ret == QMessageBox::NoButton) {

   408         ret = customButtonList.indexOf(button); // if button == 0, correctly sets ret = -1

   409     } else if (compatMode) {

   410         ret = oldButton(ret);

   411     }

   412     return ret;

   413 }

   414 

   415 void QMessageBoxPrivate::_q_buttonClicked(QAbstractButton *button)

   416 {

   417     Q_Q(QMessageBox);

   418 #ifndef QT_NO_TEXTEDIT

   419     if (detailsButton && detailsText && button == detailsButton) {

   420         detailsButton->setText(detailsText->isHidden() ? detailsText->label(HideLabel) : detailsText->label(ShowLabel));

   421         detailsText->setHidden(!detailsText->isHidden());

   422         updateSize();

   423     } else

   424 #endif

   425     {

   426         clickedButton = button;

   427         q->done(execReturnCode(button)); // does not trigger closeEvent

   428         emit q->buttonClicked(button);

   429 

   430         if (receiverToDisconnectOnClose) {

   431             QObject::disconnect(q, signalToDisconnectOnClose, receiverToDisconnectOnClose,

   432                                 memberToDisconnectOnClose);

   433             receiverToDisconnectOnClose = 0;

   434         }

   435         signalToDisconnectOnClose.clear();

   436         memberToDisconnectOnClose.clear();

   437     }

   438 }

   439 

   440 /*!

   441     \class QMessageBox

   442 

   443     \brief The QMessageBox class provides a modal dialog for informing

   444     the user or for asking the user a question and receiving an answer.

   445 

   446     \ingroup standard-dialogs

   447 

   448 

   449     A message box displays a primary \l{QMessageBox::text}{text} to

   450     alert the user to a situation, an \l{QMessageBox::informativeText}

   451     {informative text} to further explain the alert or to ask the user

   452     a question, and an optional \l{QMessageBox::detailedText}

   453     {detailed text} to provide even more data if the user requests

   454     it. A message box can also display an \l{QMessageBox::icon} {icon}

   455     and \l{QMessageBox::standardButtons} {standard buttons} for

   456     accepting a user response.

   457 

   458     Two APIs for using QMessageBox are provided, the property-based

   459     API, and the static functions. Calling one of the static functions

   460     is the simpler approach, but it is less flexible than using the

   461     property-based API, and the result is less informative. Using the

   462     property-based API is recommended.

   463 

   464     \section1 The Property-based API

   465 

   466     To use the property-based API, construct an instance of

   467     QMessageBox, set the desired properties, and call exec() to show

   468     the message. The simplest configuration is to set only the

   469     \l{QMessageBox::text} {message text} property.

   470 

   471     \snippet doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp 5

   472 

   473     The user must click the \gui{OK} button to dismiss the message

   474     box. The rest of the GUI is blocked until the message box is

   475     dismissed.

   476 

   477     \image msgbox1.png

   478 

   479     A better approach than just alerting the user to an event is to

   480     also ask the user what to do about it. Store the question in the

   481     \l{QMessageBox::informativeText} {informative text} property, and

   482     set the \l{QMessageBox::standardButtons} {standard buttons}

   483     property to the set of buttons you want as the set of user

   484     responses. The buttons are specified by combining values from

   485     StandardButtons using the bitwise OR operator. The display order

   486     for the buttons is platform-dependent. For example, on Windows,

   487     \gui{Save} is displayed to the left of \gui{Cancel}, whereas on

   488     Mac OS, the order is reversed.

   489 

   490     Mark one of your standard buttons to be your

   491     \l{QMessageBox::defaultButton()} {default button}.

   492 

   493     \snippet doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp 6

   494 

   495     This is the approach recommended in the

   496     \l{http://developer.apple.com/documentation/UserExperience/Conceptual/AppleHIGuidelines/XHIGWindows/chapter_18_section_7.html}

   497     {Mac OS X Guidlines}. Similar guidlines apply for the other

   498     platforms, but note the different ways the

   499     \l{QMessageBox::informativeText} {informative text} is handled for

   500     different platforms.

   501 

   502     \image msgbox2.png

   503 

   504     The exec() slot returns the StandardButtons value of the button

   505     that was clicked.

   506 

   507     \snippet doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp 7

   508 

   509     To give the user more information to help him answer the question,

   510     set the \l{QMessageBox::detailedText} {detailed text} property. If

   511     the \l{QMessageBox::detailedText} {detailed text} property is set,

   512     the \gui{Show Details...} button will be shown.

   513 

   514     \image msgbox3.png

   515 

   516     Clicking the \gui{Show Details...} button displays the detailed text.

   517 

   518     \image msgbox4.png

   519 

   520     \section2 Rich Text and the Text Format Property

   521 

   522     The \l{QMessageBox::detailedText} {detailed text} property is

   523     always interpreted as plain text. The \l{QMessageBox::text} {main

   524     text} and \l{QMessageBox::informativeText} {informative text}

   525     properties can be either plain text or rich text. These strings

   526     are interpreted according to the setting of the

   527     \l{QMessageBox::textFormat} {text format} property. The default

   528     setting is \l{Qt::AutoText} {auto-text}.

   529 

   530     Note that for some plain text strings containing XML

   531     meta-characters, the auto-text \l{Qt::mightBeRichText()} {rich

   532     text detection test} may fail causing your plain text string to be

   533     interpreted incorrectly as rich text. In these rare cases, use

   534     Qt::convertFromPlainText() to convert your plain text string to a

   535     visually equivalent rich text string, or set the

   536     \l{QMessageBox::textFormat} {text format} property explicitly with

   537     setTextFormat().

   538 

   539     \section2 Severity Levels and the Icon and Pixmap Properties

   540 

   541     QMessageBox supports four predefined message severity levels, or message

   542     types, which really only differ in the predefined icon they each show.

   543     Specify one of the four predefined message types by setting the

   544     \l{QMessageBox::icon}{icon} property to one of the

   545     \l{QMessageBox::Icon}{predefined icons}. The following rules are

   546     guidelines:

   547 

   548     \table

   549     \row

   550     \o \img qmessagebox-quest.png

   551     \o \l Question

   552     \o For asking a question during normal operations.

   553     \row

   554     \o \img qmessagebox-info.png

   555     \o \l Information

   556     \o For reporting information about normal operations.

   557     \row

   558     \o \img qmessagebox-warn.png

   559     \o \l Warning

   560     \o For reporting non-critical errors.

   561     \row

   562     \o \img qmessagebox-crit.png

   563     \o \l Critical

   564     \o For reporting critical errors.

   565     \endtable

   566 

   567     \l{QMessageBox::Icon}{Predefined icons} are not defined by QMessageBox, but

   568     provided by the style. The default value is \l{QMessageBox::NoIcon}

   569     {No Icon}. The message boxes are otherwise the same for all cases. When

   570     using a standard icon, use the one recommended in the table, or use the

   571     one recommended by the style guidelines for your platform. If none of the

   572     standard icons is right for your message box, you can use a custom icon by

   573     setting the \l{QMessageBox::iconPixmap}{icon pixmap} property instead of

   574     setting the \l{QMessageBox::icon}{icon} property.

   575 

   576     In summary, to set an icon, use \e{either} setIcon() for one of the

   577     standard icons, \e{or} setIconPixmap() for a custom icon.

   578 

   579     \section1 The Static Functions API

   580 

   581     Building message boxes with the static functions API, although

   582     convenient, is less flexible than using the property-based API,

   583     because the static function signatures lack parameters for setting

   584     the \l{QMessageBox::informativeText} {informative text} and

   585     \l{QMessageBox::detailedText} {detailed text} properties. One

   586     work-around for this has been to use the \c{title} parameter as

   587     the message box main text and the \c{text} parameter as the

   588     message box informative text. Because this has the obvious

   589     drawback of making a less readable message box, platform

   590     guidelines do not recommend it. The \e{Microsoft Windows User

   591     Interface Guidelines} recommend using the

   592     \l{QCoreApplication::applicationName} {application name} as the

   593     \l{QMessageBox::setWindowTitle()} {window's title}, which means

   594     that if you have an informative text in addition to your main

   595     text, you must concatenate it to the \c{text} parameter.

   596 

   597     Note that the static function signatures have changed with respect

   598     to their button parameters, which are now used to set the

   599     \l{QMessageBox::standardButtons} {standard buttons} and the

   600     \l{QMessageBox::defaultButton()} {default button}.

   601 

   602     Static functions are available for creating information(),

   603     question(), warning(), and critical() message boxes.

   604 

   605     \snippet doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp 0

   606 

   607     The \l{dialogs/standarddialogs}{Standard Dialogs} example shows

   608     how to use QMessageBox and the other built-in Qt dialogs.

   609 

   610     \section1 Advanced Usage

   611 

   612     If the \l{QMessageBox::StandardButtons} {standard buttons} are not

   613     flexible enough for your message box, you can use the addButton()

   614     overload that takes a text and a ButtonRoleto to add custom

   615     buttons. The ButtonRole is used by QMessageBox to determine the

   616     ordering of the buttons on screen (which varies according to the

   617     platform). You can test the value of clickedButton() after calling

   618     exec(). For example,

   619 

   620     \snippet doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp 2

   621 

   622     \section1 Default and Escape Keys

   623 

   624     The default button (i.e., the button activated when \key Enter is

   625     pressed) can be specified using setDefaultButton(). If a default

   626     button is not specified, QMessageBox tries to find one based on

   627     the \l{ButtonRole} {button roles} of the buttons used in the

   628     message box.

   629 

   630     The escape button (the button activated when \key Esc is pressed)

   631     can be specified using setEscapeButton().  If an escape button is

   632     not specified, QMessageBox tries to find one using these rules:

   633 

   634     \list 1

   635 

   636     \o If there is only one button, it is the button activated when

   637     \key Esc is pressed.

   638 

   639     \o If there is a \l Cancel button, it is the button activated when

   640     \key Esc is pressed.

   641 

   642     \o If there is exactly one button having either

   643        \l{QMessageBox::RejectRole} {the Reject role} or the

   644        \l{QMessageBox::NoRole} {the No role}, it is the button

   645        activated when \key Esc is pressed.

   646 

   647     \endlist

   648 

   649     When an escape button can't be determined using these rules,

   650     pressing \key Esc has no effect.

   651 

   652     \sa QDialogButtonBox, {fowler}{GUI Design Handbook: Message Box}, {Standard Dialogs Example}, {Application Example}

   653 */

   654 

   655 /*!

   656     \enum QMessageBox::StandardButton

   657     \since 4.2

   658 

   659     These enums describe flags for standard buttons. Each button has a

   660     defined \l ButtonRole.

   661 

   662     \value Ok An "OK" button defined with the \l AcceptRole.

   663     \value Open A "Open" button defined with the \l AcceptRole.

   664     \value Save A "Save" button defined with the \l AcceptRole.

   665     \value Cancel A "Cancel" button defined with the \l RejectRole.

   666     \value Close A "Close" button defined with the \l RejectRole.

   667     \value Discard A "Discard" or "Don't Save" button, depending on the platform,

   668                     defined with the \l DestructiveRole.

   669     \value Apply An "Apply" button defined with the \l ApplyRole.

   670     \value Reset A "Reset" button defined with the \l ResetRole.

   671     \value RestoreDefaults A "Restore Defaults" button defined with the \l ResetRole.

   672     \value Help A "Help" button defined with the \l HelpRole.

   673     \value SaveAll A "Save All" button defined with the \l AcceptRole.

   674     \value Yes A "Yes" button defined with the \l YesRole.

   675     \value YesToAll A "Yes to All" button defined with the \l YesRole.

   676     \value No A "No" button defined with the \l NoRole.

   677     \value NoToAll A "No to All" button defined with the \l NoRole.

   678     \value Abort An "Abort" button defined with the \l RejectRole.

   679     \value Retry A "Retry" button defined with the \l AcceptRole.

   680     \value Ignore An "Ignore" button defined with the \l AcceptRole.

   681 

   682     \value NoButton An invalid button.

   683 

   684     \omitvalue FirstButton

   685     \omitvalue LastButton

   686 

   687     The following values are obsolete:

   688 

   689     \value YesAll Use YesToAll instead.

   690     \value NoAll Use NoToAll instead.

   691     \value Default Use the \c defaultButton argument of

   692            information(), warning(), etc. instead, or call

   693            setDefaultButton().

   694     \value Escape Call setEscapeButton() instead.

   695     \value FlagMask

   696     \value ButtonMask

   697 

   698     \sa ButtonRole, standardButtons

   699 */

   700 

   701 /*!

   702     \fn void QMessageBox::buttonClicked(QAbstractButton *button)

   703 

   704     This signal is emitted whenever a button is clicked inside the QMessageBox.

   705     The button that was clicked in returned in \a button.

   706 */

   707 

   708 /*!

   709     Constructs a message box with no text and no buttons. \a parent is

   710     passed to the QDialog constructor.

   711 

   712     On Mac OS X, if you want your message box to appear

   713     as a Qt::Sheet of its \a parent, set the message box's

   714     \l{setWindowModality()} {window modality} to Qt::WindowModal or use open().

   715     Otherwise, the message box will be a standard dialog.

   716 

   717 */

   718 QMessageBox::QMessageBox(QWidget *parent)

   719     : QDialog(*new QMessageBoxPrivate, parent, Qt::MSWindowsFixedSizeDialogHint | Qt::WindowTitleHint | Qt::WindowSystemMenuHint | Qt::WindowCloseButtonHint)

   720 {

   721     Q_D(QMessageBox);

   722     d->init();

   723 }

   724 

   725 /*!

   726     Constructs a message box with the given \a icon, \a title, \a

   727     text, and standard \a buttons. Standard or custom buttons can be

   728     added at any time using addButton(). The \a parent and \a f

   729     arguments are passed to the QDialog constructor.

   730 

   731     If \a parent is 0, the message box is an \l{Qt::ApplicationModal}

   732     {application modal} dialog box. If \a parent is a widget, the

   733     message box is \l{Qt::WindowModal} {window modal} relative to \a

   734     parent.

   735 

   736     On Mac OS X, if \a parent is not 0 and you want your message box

   737     to appear as a Qt::Sheet of that parent, set the message box's

   738     \l{setWindowModality()} {window modality} to Qt::WindowModal

   739     (default). Otherwise, the message box will be a standard dialog.

   740 

   741     \sa setWindowTitle(), setText(), setIcon(), setStandardButtons()

   742 */

   743 QMessageBox::QMessageBox(Icon icon, const QString &title, const QString &text,

   744                          StandardButtons buttons, QWidget *parent,

   745                          Qt::WindowFlags f)

   746 : QDialog(*new QMessageBoxPrivate, parent, f | Qt::MSWindowsFixedSizeDialogHint | Qt::WindowTitleHint | Qt::WindowSystemMenuHint | Qt::WindowCloseButtonHint)

   747 {

   748     Q_D(QMessageBox);

   749     d->init(title, text);

   750     setIcon(icon);

   751     if (buttons != NoButton)

   752         setStandardButtons(buttons);

   753 }

   754 

   755 /*!

   756     Destroys the message box.

   757 */

   758 QMessageBox::~QMessageBox()

   759 {

   760 }

   761 

   762 /*!

   763     \since 4.2

   764 

   765     Adds the given \a button to the message box with the specified \a

   766     role.

   767 

   768     \sa removeButton(), button(), setStandardButtons()

   769 */

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

   771 {

   772     Q_D(QMessageBox);

   773     if (!button)

   774         return;

   775     removeButton(button);

   776     d->buttonBox->addButton(button, (QDialogButtonBox::ButtonRole)role);

   777     d->customButtonList.append(button);

   778     d->autoAddOkButton = false;

   779 }

   780 

   781 /*!

   782     \since 4.2

   783     \overload

   784 

   785     Creates a button with the given \a text, adds it to the message box for the

   786     specified \a role, and returns it.

   787 */

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

   789 {

   790     Q_D(QMessageBox);

   791     QPushButton *pushButton = new QPushButton(text);

   792     addButton(pushButton, role);

   793     d->updateSize();

   794     return pushButton;

   795 }

   796 

   797 /*!

   798     \since 4.2

   799     \overload

   800 

   801     Adds a standard \a button to the message box if it is valid to do so, and

   802     returns the push button.

   803 

   804     \sa setStandardButtons()

   805 */

   806 QPushButton *QMessageBox::addButton(StandardButton button)

   807 {

   808     Q_D(QMessageBox);

   809     QPushButton *pushButton = d->buttonBox->addButton((QDialogButtonBox::StandardButton)button);

   810     if (pushButton)

   811         d->autoAddOkButton = false;

   812     return pushButton;

   813 }

   814 

   815 /*!

   816     \since 4.2

   817 

   818     Removes \a button from the button box without deleting it.

   819 

   820     \sa addButton(), setStandardButtons()

   821 */

   822 void QMessageBox::removeButton(QAbstractButton *button)

   823 {

   824     Q_D(QMessageBox);

   825     d->customButtonList.removeAll(button);

   826     if (d->escapeButton == button)

   827         d->escapeButton = 0;

   828     if (d->defaultButton == button)

   829         d->defaultButton = 0;

   830     d->buttonBox->removeButton(button);

   831     d->updateSize();

   832 }

   833 

   834 /*!

   835     \property QMessageBox::standardButtons

   836     \brief collection of standard buttons in the message box

   837     \since 4.2

   838 

   839     This property controls which standard buttons are used by the message box.

   840 

   841     By default, this property contains no standard buttons.

   842 

   843     \sa addButton()

   844 */

   845 void QMessageBox::setStandardButtons(StandardButtons buttons)

   846 {

   847     Q_D(QMessageBox);

   848     d->buttonBox->setStandardButtons(QDialogButtonBox::StandardButtons(int(buttons)));

   849 

   850     QList<QAbstractButton *> buttonList = d->buttonBox->buttons();

   851     if (!buttonList.contains(d->escapeButton))

   852         d->escapeButton = 0;

   853     if (!buttonList.contains(d->defaultButton))

   854         d->defaultButton = 0;

   855     d->autoAddOkButton = false;

   856     d->updateSize();

   857 }

   858 

   859 QMessageBox::StandardButtons QMessageBox::standardButtons() const

   860 {

   861     Q_D(const QMessageBox);

   862     return QMessageBox::StandardButtons(int(d->buttonBox->standardButtons()));

   863 }

   864 

   865 /*!

   866     \since 4.2

   867 

   868     Returns the standard button enum value corresponding to the given \a button,

   869     or NoButton if the given \a button isn't a standard button.

   870 

   871     \sa button(), standardButtons()

   872 */

   873 QMessageBox::StandardButton QMessageBox::standardButton(QAbstractButton *button) const

   874 {

   875     Q_D(const QMessageBox);

   876     return (QMessageBox::StandardButton)d->buttonBox->standardButton(button);

   877 }

   878 

   879 /*!

   880     \since 4.2

   881 

   882     Returns a pointer corresponding to the standard button \a which,

   883     or 0 if the standard button doesn't exist in this message box.

   884 

   885     \sa standardButtons, standardButton()

   886 */

   887 QAbstractButton *QMessageBox::button(StandardButton which) const

   888 {

   889     Q_D(const QMessageBox);

   890     return d->buttonBox->button(QDialogButtonBox::StandardButton(which));

   891 }

   892 

   893 /*!

   894     \since 4.2

   895 

   896     Returns the button that is activated when escape is pressed.

   897 

   898     By default, QMessageBox attempts to automatically detect an

   899     escape button as follows:

   900 

   901     \list 1

   902     \o If there is only one button, it is made the escape button.

   903     \o If there is a \l Cancel button, it is made the escape button.

   904     \o On Mac OS X only, if there is exactly one button with the role

   905        QMessageBox::RejectRole, it is made the escape button.

   906     \endlist

   907 

   908     When an escape button could not be automatically detected, pressing

   909     \key Esc has no effect.

   910 

   911     \sa addButton()

   912 */

   913 QAbstractButton *QMessageBox::escapeButton() const

   914 {

   915     Q_D(const QMessageBox);

   916     return d->escapeButton;

   917 }

   918 

   919 /*!

   920     \since 4.2

   921 

   922     Sets the button that gets activated when the \key Escape key is

   923     pressed to \a button.

   924 

   925     \sa addButton(), clickedButton()

   926 */

   927 void QMessageBox::setEscapeButton(QAbstractButton *button)

   928 {

   929     Q_D(QMessageBox);

   930     if (d->buttonBox->buttons().contains(button))

   931         d->escapeButton = button;

   932 }

   933 

   934 /*!

   935     \since 4.3

   936 

   937     Sets the buttons that gets activated when the \key Escape key is

   938     pressed to \a button.

   939 

   940     \sa addButton(), clickedButton()

   941 */

   942 void QMessageBox::setEscapeButton(QMessageBox::StandardButton button)

   943 {

   944     Q_D(QMessageBox);

   945     setEscapeButton(d->buttonBox->button(QDialogButtonBox::StandardButton(button)));

   946 }

   947 

   948 void QMessageBoxPrivate::detectEscapeButton()

   949 {

   950     if (escapeButton) { // escape button explicitly set

   951         detectedEscapeButton = escapeButton;

   952         return;

   953     }

   954 

   955     // Cancel button automatically becomes escape button

   956     detectedEscapeButton = buttonBox->button(QDialogButtonBox::Cancel);

   957     if (detectedEscapeButton)

   958         return;

   959 

   960     // If there is only one button, make it the escape button

   961     const QList<QAbstractButton *> buttons = buttonBox->buttons();

   962     if (buttons.count() == 1) {

   963         detectedEscapeButton = buttons.first();

   964         return;

   965     }

   966 

   967     // if the message box has one RejectRole button, make it the escape button

   968     for (int i = 0; i < buttons.count(); i++) {

   969         if (buttonBox->buttonRole(buttons.at(i)) == QDialogButtonBox::RejectRole) {

   970             if (detectedEscapeButton) { // already detected!

   971                 detectedEscapeButton = 0;

   972                 break;

   973             }

   974             detectedEscapeButton = buttons.at(i);

   975         }

   976     }

   977     if (detectedEscapeButton)

   978         return;

   979 

   980     // if the message box has one NoRole button, make it the escape button

   981     for (int i = 0; i < buttons.count(); i++) {

   982         if (buttonBox->buttonRole(buttons.at(i)) == QDialogButtonBox::NoRole) {

   983             if (detectedEscapeButton) { // already detected!

   984                 detectedEscapeButton = 0;

   985                 break;

   986             }

   987             detectedEscapeButton = buttons.at(i);

   988         }

   989     }

   990 }

   991 

   992 /*!

   993     \since 4.2

   994 

   995     Returns the button that was clicked by the user,

   996     or 0 if the user hit the \key Esc key and

   997     no \l{setEscapeButton()}{escape button} was set.

   998 

   999     If exec() hasn't been called yet, returns 0.

  1000 

  1001     Example:

  1002 

  1003     \snippet doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp 3

  1004 

  1005     \sa standardButton(), button()

  1006 */

  1007 QAbstractButton *QMessageBox::clickedButton() const

  1008 {

  1009     Q_D(const QMessageBox);

  1010     return d->clickedButton;

  1011 }

  1012 

  1013 /*!

  1014     \since 4.2

  1015 

  1016     Returns the button that should be the message box's

  1017     \l{QPushButton::setDefault()}{default button}. Returns 0

  1018     if no default button was set.

  1019 

  1020     \sa addButton(), QPushButton::setDefault()

  1021 */

  1022 QPushButton *QMessageBox::defaultButton() const

  1023 {

  1024     Q_D(const QMessageBox);

  1025     return d->defaultButton;

  1026 }

  1027 

  1028 /*!

  1029     \since 4.2

  1030 

  1031     Sets the message box's \l{QPushButton::setDefault()}{default button}

  1032     to \a button.

  1033 

  1034     \sa addButton(), QPushButton::setDefault()

  1035 */

  1036 void QMessageBox::setDefaultButton(QPushButton *button)

  1037 {

  1038     Q_D(QMessageBox);

  1039     if (!d->buttonBox->buttons().contains(button))

  1040         return;

  1041     d->defaultButton = button;

  1042     button->setDefault(true);

  1043     button->setFocus();

  1044 }

  1045 

  1046 /*!

  1047     \since 4.3

  1048 

  1049     Sets the message box's \l{QPushButton::setDefault()}{default button}

  1050     to \a button.

  1051 

  1052     \sa addButton(), QPushButton::setDefault()

  1053 */

  1054 void QMessageBox::setDefaultButton(QMessageBox::StandardButton button)

  1055 {

  1056     Q_D(QMessageBox);

  1057     setDefaultButton(d->buttonBox->button(QDialogButtonBox::StandardButton(button)));

  1058 }

  1059 

  1060 /*!

  1061   \property QMessageBox::text

  1062   \brief the message box text to be displayed.

  1063 

  1064   The text will be interpreted either as a plain text or as rich text,

  1065   depending on the text format setting (\l QMessageBox::textFormat).

  1066   The default setting is Qt::AutoText, i.e., the message box will try

  1067   to auto-detect the format of the text.

  1068 

  1069   The default value of this property is an empty string.

  1070 

  1071   \sa textFormat, QMessageBox::informativeText, QMessageBox::detailedText

  1072 */

  1073 QString QMessageBox::text() const

  1074 {

  1075     Q_D(const QMessageBox);

  1076     return d->label->text();

  1077 }

  1078 

  1079 void QMessageBox::setText(const QString &text)

  1080 {

  1081     Q_D(QMessageBox);

  1082     d->label->setText(text);

  1083     d->label->setWordWrap(d->label->textFormat() == Qt::RichText

  1084         || (d->label->textFormat() == Qt::AutoText && Qt::mightBeRichText(text)));

  1085     d->updateSize();

  1086 }

  1087 

  1088 /*!

  1089     \enum QMessageBox::Icon

  1090 

  1091     This enum has the following values:

  1092 

  1093     \value NoIcon the message box does not have any icon.

  1094 

  1095     \value Question an icon indicating that

  1096     the message is asking a question.

  1097 

  1098     \value Information an icon indicating that

  1099     the message is nothing out of the ordinary.

  1100 

  1101     \value Warning an icon indicating that the

  1102     message is a warning, but can be dealt with.

  1103 

  1104     \value Critical an icon indicating that

  1105     the message represents a critical problem.

  1106 

  1107 */

  1108 

  1109 /*!

  1110     \property QMessageBox::icon

  1111     \brief the message box's icon

  1112 

  1113     The icon of the message box can be specified with one of the

  1114     values:

  1115 

  1116     \list

  1117     \o QMessageBox::NoIcon

  1118     \o QMessageBox::Question

  1119     \o QMessageBox::Information

  1120     \o QMessageBox::Warning

  1121     \o QMessageBox::Critical

  1122     \endlist

  1123 

  1124     The default is QMessageBox::NoIcon.

  1125 

  1126     The pixmap used to display the actual icon depends on the current

  1127     \l{QWidget::style()} {GUI style}. You can also set a custom pixmap

  1128     for the icon by setting the \l{QMessageBox::iconPixmap} {icon

  1129     pixmap} property.

  1130 

  1131     \sa iconPixmap

  1132 */

  1133 QMessageBox::Icon QMessageBox::icon() const

  1134 {