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

     2 **

     3 ** Copyright (C) 2010 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/qtextbrowser.h>

    62 #include <QtGui/qmenu.h>

    63 #include "qdialog_p.h"

    64 #include <QtGui/qfont.h>

    65 #include <QtGui/qfontmetrics.h>

    66 #include <QtGui/qclipboard.h>

    67 

    68 #ifndef QT_NO_STYLE_S60

    69 #include <qs60style.h>

    70 #endif

    71 

    72 #ifdef Q_WS_WINCE

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

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

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

    76 

    77 #include "qguifunctions_wince.h"

    78 #endif

    79 

    80 QT_BEGIN_NAMESPACE

    81 

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

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

    84               NewButtonMask = 0xFFFFFC00 };

    85 

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

    87 #ifndef QT_NO_TEXTEDIT

    88 class QMessageBoxDetailsText : public QWidget

    89 {

    90 public:

    91     class TextEdit : public QTextEdit

    92     {

    93     public:

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

    95         void contextMenuEvent(QContextMenuEvent * e)

    96         {

    97 #ifndef QT_NO_CONTEXTMENU

    98             QMenu *menu = createStandardContextMenu();

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

   100             delete menu;

   101 #else

   102             Q_UNUSED(e);

   103 #endif

   104         }

   105     };

   106 

   107     QMessageBoxDetailsText(QWidget *parent=0)

   108         : QWidget(parent)

   109     {

   110         QVBoxLayout *layout = new QVBoxLayout;

   111         layout->setMargin(0);

   112         QFrame *line = new QFrame(this);

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

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

   115         layout->addWidget(line);

   116         textEdit = new TextEdit();

   117         textEdit->setFixedHeight(100);

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

   119         textEdit->setReadOnly(true);

   120         layout->addWidget(textEdit);

   121         setLayout(layout);

   122     }

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

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

   125     QString label(DetailButtonLabel label)

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

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

   128 private:

   129     TextEdit *textEdit;

   130 };

   131 #endif // QT_NO_TEXTEDIT

   132 

   133 class QMessageBoxPrivate : public QDialogPrivate

   134 {

   135     Q_DECLARE_PUBLIC(QMessageBox)

   136 

   137 public:

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

   139 #ifndef QT_NO_TEXTEDIT

   140                            detailsText(0),

   141 #endif

   142                            compatMode(false), autoAddOkButton(true),

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

   144 

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

   146     void _q_buttonClicked(QAbstractButton *);

   147 

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

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

   150 

   151     QAbstractButton *abstractButtonForId(int id) const;

   152     int execReturnCode(QAbstractButton *button);

   153 

   154     void detectEscapeButton();

   155     void updateSize();

   156     int layoutMinimumWidth();

   157     void retranslateStrings();

   158 

   159 #ifdef Q_WS_WINCE

   160     void hideSpecial();

   161 #endif

   162 

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

   164                                  const QString &title, const QString &text,

   165                                  int button0, int button1, int button2);

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

   167                                  const QString &title, const QString &text,

   168                                  const QString &button0Text,

   169                                  const QString &button1Text,

   170                                  const QString &button2Text,

   171                                  int defaultButtonNumber,

   172                                  int escapeButtonNumber);

   173 

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

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

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

   177 

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

   179 

   180     QLabel *label;

   181     QMessageBox::Icon icon;

   182     QLabel *iconLabel;

   183     QDialogButtonBox *buttonBox;

   184     QList<QAbstractButton *> customButtonList;

   185     QAbstractButton *escapeButton;

   186     QPushButton *defaultButton;

   187     QAbstractButton *clickedButton;

   188     QPushButton *detailsButton;

   189 #ifndef QT_NO_TEXTEDIT

   190     QMessageBoxDetailsText *detailsText;

   191 #endif

   192     bool compatMode;

   193     bool autoAddOkButton;

   194     QAbstractButton *detectedEscapeButton;

   195     QLabel *informativeLabel;

   196 #if defined(Q_OS_SYMBIAN) || defined(Q_WS_MAEMO_5)

   197     QTextBrowser *textBrowser;

   198 #endif

   199     QPointer<QObject> receiverToDisconnectOnClose;

   200     QByteArray memberToDisconnectOnClose;

   201     QByteArray signalToDisconnectOnClose;

   202 };

   203 

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

   205 {

   206     Q_Q(QMessageBox);

   207 

   208     label = new QLabel;

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

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

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

   212     label->setOpenExternalLinks(true);

   213 #if defined(Q_WS_MAC)

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

   215 #elif !defined(Q_WS_QWS)

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

   217     label->setIndent(9);

   218 #endif

   219     icon = QMessageBox::NoIcon;

   220     iconLabel = new QLabel;

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

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

   223 

   224     buttonBox = new QDialogButtonBox;

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

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

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

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

   229 

   230     QGridLayout *grid = new QGridLayout;

   231 #ifndef Q_WS_MAC

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

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

   234     // -- leave space for information label --

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

   236 #else

   237     grid->setMargin(0);

   238     grid->setVerticalSpacing(8);

   239     grid->setHorizontalSpacing(0);

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

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

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

   243     // -- leave space for information label --

   244     grid->setRowStretch(1, 100);

   245     grid->setRowMinimumHeight(2, 6);

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

   247 #endif

   248 

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

   250     q->setLayout(grid);

   251 

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

   253         q->setWindowTitle(title);

   254         q->setText(text);

   255     }

   256     q->setModal(true);

   257 

   258 #ifdef Q_WS_MAC

   259     QFont f = q->font();

   260     f.setBold(true);

   261     label->setFont(f);

   262 #endif

   263     retranslateStrings();

   264 }

   265 

   266 int QMessageBoxPrivate::layoutMinimumWidth()

   267 {

   268     layout->activate();

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

   270 }

   271 

   272 void QMessageBoxPrivate::updateSize()

   273 {

   274     Q_Q(QMessageBox);

   275 

   276     if (!q->isVisible())

   277         return;

   278 

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

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

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

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

   283 #else

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

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

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

   287         hardLimit = screenSize.width();

   288 #endif

   289 #ifdef Q_WS_MAC

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

   291 #elif defined(Q_WS_QWS)

   292     int softLimit = qMin(hardLimit, 500);

   293 #else

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

   295 #ifndef Q_WS_WINCE

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

   297 #else

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

   299 #endif //Q_WS_WINCE

   300 #endif

   301 

   302     if (informativeLabel)

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

   304 

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

   306     int width = layoutMinimumWidth();

   307 

   308     if (width > softLimit) {

   309         label->setWordWrap(true);

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

   311 

   312         if (width > hardLimit) {

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

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

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

   316                 opt.setWrapMode(QTextOption::WrapAnywhere);

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

   318             }

   319             width = hardLimit;

   320         }

   321     }

   322 #ifdef Q_WS_S60

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

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

   325             width = hardLimit;

   326         } else {

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

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

   329         }

   330 #endif

   331 

   332     if (informativeLabel) {

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

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

   335         policy.setHeightForWidth(true);

   336         informativeLabel->setSizePolicy(policy);

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

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

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

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

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

   342                 opt.setWrapMode(QTextOption::WrapAnywhere);

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

   344             }

   345             width = hardLimit;

   346         }

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

   348         label->setSizePolicy(policy);

   349     }

   350 

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

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

   353     if (windowTitleWidth > width)

   354         width = windowTitleWidth;

   355 

   356     layout->activate();

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

   358                      ? layout->totalHeightForWidth(width)

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

   360 

   361 #ifndef QT_NO_STYLE_S60

   362         QS60Style *s60Style = 0;

   363         s60Style = qobject_cast<QS60Style *>(QApplication::style());

   364 

   365         //use custom pixel metric to deduce the minimum height of the messagebox

   366         if (s60Style)

   367             height = qMax(height, s60Style->pixelMetric((QStyle::PixelMetric)PM_MessageBoxHeight));

   368 #endif

   369 

   370     q->setFixedSize(width, height);

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

   372 }

   373 

   374 

   375 #ifdef Q_WS_WINCE

   376 /*!

   377   \internal

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

   379   on WinCE, to conserve screen space.

   380 */

   381 

   382 void QMessageBoxPrivate::hideSpecial()

   383 {

   384     Q_Q(QMessageBox);

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

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

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

   388             QString text = pb->text();

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

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

   391                 pb->setFixedSize(0,0);

   392         }

   393 }

   394 #endif

   395 

   396 static int oldButton(int button)

   397 {

   398     switch (button & QMessageBox::ButtonMask) {

   399     case QMessageBox::Ok:

   400         return Old_Ok;

   401     case QMessageBox::Cancel:

   402         return Old_Cancel;

   403     case QMessageBox::Yes:

   404         return Old_Yes;

   405     case QMessageBox::No:

   406         return Old_No;

   407     case QMessageBox::Abort:

   408         return Old_Abort;

   409     case QMessageBox::Retry:

   410         return Old_Retry;

   411     case QMessageBox::Ignore:

   412         return Old_Ignore;

   413     case QMessageBox::YesToAll:

   414         return Old_YesAll;

   415     case QMessageBox::NoToAll:

   416         return Old_NoAll;

   417     default:

   418         return 0;

   419     }

   420 }

   421 

   422 int QMessageBoxPrivate::execReturnCode(QAbstractButton *button)

   423 {

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

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

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

   427     } else if (compatMode) {

   428         ret = oldButton(ret);

   429     }

   430     return ret;

   431 }

   432 

   433 void QMessageBoxPrivate::_q_buttonClicked(QAbstractButton *button)

   434 {

   435     Q_Q(QMessageBox);

   436 #ifndef QT_NO_TEXTEDIT

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

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

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

   440         updateSize();

   441     } else

   442 #endif

   443     {

   444         clickedButton = button;

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

   446         emit q->buttonClicked(button);

   447 

   448         if (receiverToDisconnectOnClose) {

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

   450                                 memberToDisconnectOnClose);

   451             receiverToDisconnectOnClose = 0;

   452         }

   453         signalToDisconnectOnClose.clear();

   454         memberToDisconnectOnClose.clear();

   455     }

   456 }

   457 

   458 /*!

   459     \class QMessageBox

   460 

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

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

   463 

   464     \ingroup standard-dialogs

   465 

   466 

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

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

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

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

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

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

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

   474     accepting a user response.

   475 

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

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

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

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

   480     property-based API is recommended.

   481 

   482     \section1 The Property-based API

   483 

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

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

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

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

   488 

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

   490 

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

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

   493     dismissed.

   494 

   495     \image msgbox1.png

   496 

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

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

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

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

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

   502     responses. The buttons are specified by combining values from

   503     StandardButtons using the bitwise OR operator. The display order

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

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

   506     Mac OS, the order is reversed.

   507 

   508     Mark one of your standard buttons to be your

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

   510 

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

   512 

   513     This is the approach recommended in the

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

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

   516     platforms, but note the different ways the

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

   518     different platforms.

   519 

   520     \image msgbox2.png

   521 

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

   523     that was clicked.

   524 

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

   526 

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

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

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

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

   531 

   532     \image msgbox3.png

   533 

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

   535 

   536     \image msgbox4.png

   537 

   538     \section2 Rich Text and the Text Format Property

   539 

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

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

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

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

   544     are interpreted according to the setting of the

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

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

   547 

   548     Note that for some plain text strings containing XML

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

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

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

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

   553     visually equivalent rich text string, or set the

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

   555     setTextFormat().

   556 

   557     \section2 Severity Levels and the Icon and Pixmap Properties

   558 

   559     QMessageBox supports four predefined message severity levels, or message

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

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

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

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

   564     guidelines:

   565 

   566     \table

   567     \row

   568     \o \img qmessagebox-quest.png

   569     \o \l Question

   570     \o For asking a question during normal operations.

   571     \row

   572     \o \img qmessagebox-info.png

   573     \o \l Information

   574     \o For reporting information about normal operations.

   575     \row

   576     \o \img qmessagebox-warn.png

   577     \o \l Warning

   578     \o For reporting non-critical errors.

   579     \row

   580     \o \img qmessagebox-crit.png

   581     \o \l Critical

   582     \o For reporting critical errors.

   583     \endtable

   584 

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

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

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

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

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

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

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

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

   593 

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

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

   596 

   597     \section1 The Static Functions API

   598 

   599     Building message boxes with the static functions API, although

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

   601     because the static function signatures lack parameters for setting

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

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

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

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

   606     message box informative text. Because this has the obvious

   607     drawback of making a less readable message box, platform

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

   609     Interface Guidelines} recommend using the

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

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

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

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

   614 

   615     Note that the static function signatures have changed with respect

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

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

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

   619 

   620     Static functions are available for creating information(),

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

   622 

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

   624 

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

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

   627 

   628     \section1 Advanced Usage

   629 

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

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

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

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

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

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

   636     exec(). For example,

   637 

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

   639 

   640     \section1 Default and Escape Keys

   641 

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

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

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

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

   646     message box.

   647 

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

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

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

   651 

   652     \list 1

   653 

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

   655     \key Esc is pressed.

   656 

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

   658     \key Esc is pressed.

   659 

   660     \o If there is exactly one button having either

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

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

   663        activated when \key Esc is pressed.

   664 

   665     \endlist

   666 

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

   668     pressing \key Esc has no effect.

   669 

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

   671 */

   672 

   673 /*!

   674     \enum QMessageBox::StandardButton

   675     \since 4.2

   676 

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

   678     defined \l ButtonRole.

   679 

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

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

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

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

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

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

   686                     defined with the \l DestructiveRole.

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

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

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

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

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

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

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

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

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

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

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

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

   699 

   700     \value NoButton An invalid button.

   701 

   702     \omitvalue FirstButton

   703     \omitvalue LastButton

   704 

   705     The following values are obsolete:

   706 

   707     \value YesAll Use YesToAll instead.

   708     \value NoAll Use NoToAll instead.

   709     \value Default Use the \c defaultButton argument of

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

   711            setDefaultButton().

   712     \value Escape Call setEscapeButton() instead.

   713     \value FlagMask

   714     \value ButtonMask

   715 

   716     \sa ButtonRole, standardButtons

   717 */

   718 

   719 /*!

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

   721 

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

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

   724 */

   725 

   726 /*!

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

   728     passed to the QDialog constructor.

   729 

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

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

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

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

   734 

   735 */

   736 QMessageBox::QMessageBox(QWidget *parent)

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

   738 {

   739     Q_D(QMessageBox);

   740     d->init();

   741 }

   742 

   743 /*!

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

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

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

   747     arguments are passed to the QDialog constructor.

   748 

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

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

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

   752     parent.

   753 

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

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

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

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

   758 

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

   760 */

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

   762                          StandardButtons buttons, QWidget *parent,

   763                          Qt::WindowFlags f)

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

   765 {

   766     Q_D(QMessageBox);

   767     d->init(title, text);

   768     setIcon(icon);

   769     if (buttons != NoButton)

   770         setStandardButtons(buttons);

   771 }

   772 

   773 /*!

   774     Destroys the message box.

   775 */

   776 QMessageBox::~QMessageBox()

   777 {

   778 }

   779 

   780 /*!

   781     \since 4.2

   782 

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

   784     role.

   785 

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

   787 */

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

   789 {

   790     Q_D(QMessageBox);

   791     if (!button)

   792         return;

   793     removeButton(button);

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

   795     d->customButtonList.append(button);

   796     d->autoAddOkButton = false;

   797 }

   798 

   799 /*!

   800     \since 4.2

   801     \overload

   802 

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

   804     specified \a role, and returns it.

   805 */

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

   807 {

   808     Q_D(QMessageBox);

   809     QPushButton *pushButton = new QPushButton(text);

   810     addButton(pushButton, role);

   811     d->updateSize();

   812     return pushButton;

   813 }

   814 

   815 /*!

   816     \since 4.2

   817     \overload

   818 

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

   820     returns the push button.

   821 

   822     \sa setStandardButtons()

   823 */

   824 QPushButton *QMessageBox::addButton(StandardButton button)

   825 {

   826     Q_D(QMessageBox);

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

   828     if (pushButton)

   829         d->autoAddOkButton = false;

   830     return pushButton;

   831 }

   832 

   833 /*!

   834     \since 4.2

   835 

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

   837 

   838     \sa addButton(), setStandardButtons()

   839 */

   840 void QMessageBox::removeButton(QAbstractButton *button)

   841 {

   842     Q_D(QMessageBox);

   843     d->customButtonList.removeAll(button);

   844     if (d->escapeButton == button)

   845         d->escapeButton = 0;

   846     if (d->defaultButton == button)

   847         d->defaultButton = 0;

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

   849     d->updateSize();

   850 }

   851 

   852 /*!

   853     \property QMessageBox::standardButtons

   854     \brief collection of standard buttons in the message box

   855     \since 4.2

   856 

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

   858 

   859     By default, this property contains no standard buttons.

   860 

   861     \sa addButton()

   862 */

   863 void QMessageBox::setStandardButtons(StandardButtons buttons)

   864 {

   865     Q_D(QMessageBox);

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

   867 

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

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

   870         d->escapeButton = 0;

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

   872         d->defaultButton = 0;

   873     d->autoAddOkButton = false;

   874     d->updateSize();

   875 }

   876 

   877 QMessageBox::StandardButtons QMessageBox::standardButtons() const

   878 {

   879     Q_D(const QMessageBox);

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

   881 }

   882 

   883 /*!

   884     \since 4.2

   885 

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

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

   888 

   889     \sa button(), standardButtons()

   890 */

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

   892 {

   893     Q_D(const QMessageBox);

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

   895 }

   896 

   897 /*!

   898     \since 4.2

   899 

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

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

   902 

   903     \sa standardButtons, standardButton()

   904 */

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

   906 {

   907     Q_D(const QMessageBox);

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

   909 }

   910 

   911 /*!

   912     \since 4.2

   913 

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

   915 

   916     By default, QMessageBox attempts to automatically detect an

   917     escape button as follows:

   918 

   919     \list 1

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

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

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

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

   924     \endlist

   925 

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

   927     \key Esc has no effect.

   928 

   929     \sa addButton()

   930 */

   931 QAbstractButton *QMessageBox::escapeButton() const

   932 {

   933     Q_D(const QMessageBox);

   934     return d->escapeButton;

   935 }

   936 

   937 /*!

   938     \since 4.2

   939 

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

   941     pressed to \a button.

   942 

   943     \sa addButton(), clickedButton()

   944 */

   945 void QMessageBox::setEscapeButton(QAbstractButton *button)

   946 {

   947     Q_D(QMessageBox);

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

   949         d->escapeButton = button;

   950 }

   951 

   952 /*!

   953     \since 4.3

   954 

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

   956     pressed to \a button.

   957 

   958     \sa addButton(), clickedButton()

   959 */

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

   961 {

   962     Q_D(QMessageBox);

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

   964 }

   965 

   966 void QMessageBoxPrivate::detectEscapeButton()

   967 {

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

   969         detectedEscapeButton = escapeButton;

   970         return;

   971     }

   972 

   973     // Cancel button automatically becomes escape button

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

   975     if (detectedEscapeButton)

   976         return;

   977 

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

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

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

   981         detectedEscapeButton = buttons.first();

   982         return;

   983     }

   984 

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

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

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

   988             if (detectedEscapeButton) { // already detected!

   989                 detectedEscapeButton = 0;

   990                 break;

   991             }

   992             detectedEscapeButton = buttons.at(i);

   993         }

   994     }

   995     if (detectedEscapeButton)

   996         return;

   997 

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

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

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

  1001             if (detectedEscapeButton) { // already detected!

  1002                 detectedEscapeButton = 0;

  1003                 break;

  1004             }

  1005             detectedEscapeButton = buttons.at(i);

  1006         }

  1007     }

  1008 }

  1009 

  1010 /*!

  1011     \since 4.2

  1012 

  1013     Returns the button that was clicked by the user,

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

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

  1016 

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

  1018 

  1019     Example:

  1020 

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

  1022 

  1023     \sa standardButton(), button()

  1024 */

  1025 QAbstractButton *QMessageBox::clickedButton() const

  1026 {

  1027     Q_D(const QMessageBox);

  1028     return d->clickedButton;

  1029 }

  1030 

  1031 /*!

  1032     \since 4.2

  1033 

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

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

  1036     if no default button was set.

  1037 

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

  1039 */

  1040 QPushButton *QMessageBox::defaultButton() const

  1041 {

  1042     Q_D(const QMessageBox);

  1043     return d->defaultButton;

  1044 }

  1045 

  1046 /*!

  1047     \since 4.2

  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(QPushButton *button)

  1055 {

  1056     Q_D(QMessageBox);

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

  1058         return;

  1059     d->defaultButton = button;

  1060     button->setDefault(true);

  1061     button->setFocus();

  1062 }

  1063 

  1064 /*!

  1065     \since 4.3

  1066 

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

  1068     to \a button.

  1069 

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

  1071 */

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

  1073 {

  1074     Q_D(QMessageBox);

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

  1076 }

  1077 

  1078 /*!

  1079   \property QMessageBox::text

  1080   \brief the message box text to be displayed.

  1081 

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

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

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

  1085   to auto-detect the format of the text.

  1086 

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

  1088 

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

  1090 */

  1091 QString QMessageBox::text() const

  1092 {

  1093     Q_D(const QMessageBox);

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

  1095 }

  1096 

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

  1098 {

  1099     Q_D(QMessageBox);

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

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

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

  1103     d->updateSize();

  1104 }

  1105 

  1106 /*!

  1107     \enum QMessageBox::Icon

  1108 

  1109     This enum has the following values:

  1110 

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

  1112 

  1113     \value Question an icon indicating that

  1114     the message is asking a question.

  1115 

  1116     \value Information an icon indicating that

  1117     the message is nothing out of the ordinary.

  1118 

  1119     \value Warning an icon indicating that the

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

  1121 

  1122     \value Critical an icon indicating that

  1123     the message represents a critical problem.

  1124 

  1125 */

  1126 

  1127 /*!

  1128     \property QMessageBox::icon

  1129     \brief the message box's icon

  1130 

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

  1132     values:

  1133 

  1134     \list

  1135     \o QMessageBox::NoIcon