From 6afc9b2a2d892e676104371fbeabccbd76b6ede3 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Mon, 2 Mar 2015 13:59:10 +0100 Subject: Docs: edit MessageBoxHandler docs Move scripting docs to another file and add C++ docs. Edit the C++ docs for grammar and style. Change-Id: I2494c573662687cd107916c06e24b0f528596a7e Reviewed-by: Karsten Heimrich --- src/libs/installer/messageboxhandler.cpp | 222 ++++++++++++++++++++++--------- 1 file changed, 161 insertions(+), 61 deletions(-) (limited to 'src/libs') diff --git a/src/libs/installer/messageboxhandler.cpp b/src/libs/installer/messageboxhandler.cpp index 4a583a15b..a33810938 100644 --- a/src/libs/installer/messageboxhandler.cpp +++ b/src/libs/installer/messageboxhandler.cpp @@ -41,14 +41,13 @@ #include /*! - \qmltype QMessageBox - \inqmlmodule scripting + \inmodule QtInstallerFramework + \class QInstaller::MessageBoxHandler + \brief The MessageBoxHandler class provides a modal dialog for informing the user or asking the + user a question and receiving an answer. - \brief Provides a modal dialog for informing the user or asking the user - a question and receiving an answer. - - \code + \badcode var result = QMessageBox.question("quit.question", "Installer", "Do you want to quit the installer?", QMessageBox.Yes | QMessageBox.No); if (result == QMessageBox.Yes) { @@ -58,74 +57,62 @@ \section2 Buttons in Message Boxes - QMessageBox defines a list of common buttons: + \c QMessageBox defines a list of common buttons: \list - \li QMessageBox.Ok - \li QMessageBox.Open - \li QMessageBox.Save - \li QMessageBox.Cancel - \li QMessageBox.Close - \li QMessageBox.Discard - \li QMessageBox.Apply - \li QMessageBox.Reset - \li QMessageBox.RestoreDefaults - \li QMessageBox.Help - \li QMessageBox.SaveAll - \li QMessageBox.Yes - \li QMessageBox.YesToAll - \li QMessageBox.No - \li QMessageBox.NoToAll - \li QMessageBox.Abort - \li QMessageBox.Retry - \li QMessageBox.Ignore - \li QMessageBox.NoButton + \li \l{QMessageBox::Ok}{OK} + \li \l{QMessageBox::Open}{Open} + \li \l{QMessageBox::Save}{Save} + \li \l{QMessageBox::Cancel}{Cancel} + \li \l{QMessageBox::Close}{Close} + \li \l{QMessageBox::Discard}{Discard} + \li \l{QMessageBox::Apply}{Apply} + \li \l{QMessageBox::Reset}{Reset} + \li \l{QMessageBox::RestoreDefaults}{RestoreDefaults} + \li \l{QMessageBox::Help}{Help} + \li \l{QMessageBox::SaveAll}{SaveAll} + \li \l{QMessageBox::Yes}{Yes} + \li \l{QMessageBox::YesToAll}{YesToAll} + \li \l{QMessageBox::No}{No} + \li \l{QMessageBox::NoToAll}{NoToAll} + \li \l{QMessageBox::Abort}{Abort} + \li \l{QMessageBox::Retry}{Retry} + \li \l{QMessageBox::Ignore}{Ignore} + \li \l{QMessageBox::NoButton}{NoButton} \endlist - - \section2 Scripted Installations - - Sometimes it is useful to automatically close message boxes, for example during a scripted - installation. This can be achieved by calling installer::setMessageBoxAutomaticAnswer, - installer::autoAcceptMessageBoxes or installer::autoRejectMessageBoxes. The \c identifier - argument in the method calls allows to identify specific message boxes for this purpose. - */ - - -/*! - \qmlmethod Button QMessageBox::critical(string identifier, string title, string text, - Buttons buttons = QMessageBox.Ok, Button button - = QMessageBox.NoButton) - - Opens a critical message box with the given \a title and \a text. */ -/*! - \qmlmethod Button QMessageBox::information(string identifier, string title, string text, - Buttons buttons = QMessageBox.Ok, Button button - = QMessageBox.NoButton) +using namespace QInstaller; - Opens an information message box with the given \a title and \a text. -*/ +// -- MessageBoxHandler /*! - \qmlmethod Button QMessageBox::question(string identifier, string title, string text, - Buttons buttons = QMessageBox.Yes | QMessageBox.No, Button button - = QMessageBox.NoButton) + \enum MessageBoxHandler::DefaultAction + + This enum value holds the default action for the message box handler: - Opens a question message box with the given \a title and \a text. + \value AskUser + Ask the end user for confirmation. + \value Accept + Accept the message box. + \value Reject + Reject the message box. */ /*! - \qmlmethod Button QMessageBox::warning(string identifier, string title, string text, - Buttons buttons = QMessageBox.Ok, Button button - = QMessageBox.NoButton) - - Opens a warning message box with the given \a title and \a text. + \enum MessageBoxHandler::MessageType + + This enum value holds the severity level of the message displayed in the message box: + + \value criticalType + Reports critical errors. + \value informationType + Reports information about normal operations. + \value questionType + Asks a question during normal operations. + \value warningType + Reports non-critical errors. */ -using namespace QInstaller; - -// -- MessageBoxHandler - MessageBoxHandler *MessageBoxHandler::m_instance = 0; MessageBoxHandler::MessageBoxHandler(QObject *parent) @@ -134,6 +121,9 @@ MessageBoxHandler::MessageBoxHandler(QObject *parent) { } +/*! + Returns a message box handler instance. +*/ MessageBoxHandler *MessageBoxHandler::instance() { if (m_instance == 0) @@ -141,6 +131,10 @@ MessageBoxHandler *MessageBoxHandler::instance() return m_instance; } +/*! + Returns the widget or window that is most suitable to become the parent of the message box. + Returns \c 0 if an application cannot be found. +*/ QWidget *MessageBoxHandler::currentBestSuitParent() { if (qobject_cast (qApp) == 0) @@ -152,6 +146,9 @@ QWidget *MessageBoxHandler::currentBestSuitParent() return qApp->activeWindow(); } +/*! + Returns an ordered list of buttons to display in the message box. +*/ QList MessageBoxHandler::orderedButtons() { static QList buttons; @@ -165,6 +162,9 @@ QList MessageBoxHandler::orderedButtons() return buttons; } +/*! + Sets the default action for the message box to \a defaultAction. +*/ void MessageBoxHandler::setDefaultAction(DefaultAction defaultAction) { if (m_defaultAction == defaultAction) @@ -183,6 +183,11 @@ void MessageBoxHandler::setDefaultAction(DefaultAction defaultAction) } } +/*! + Sets the button that is used as the default button and that is automatically invoked if a + message box is shown in automatic mode. The string \a identifier is used to identify the + message box that the default button \a answer is associated to. +*/ void MessageBoxHandler::setAutomaticAnswer(const QString &identifier, QMessageBox::StandardButton answer) { m_automaticAnswers.insert(identifier, answer); @@ -190,6 +195,18 @@ void MessageBoxHandler::setAutomaticAnswer(const QString &identifier, QMessageBo // -- static +/*! + Opens a critical message box with the parent \a parent, identifier \a identifier, + title \a title, and text \a text. + + The standard buttons specified by \a buttons are added to the message box. \a button specifies + the button that is used when \key Enter is pressed. \a button must refer to a button that is + specified in \a buttons. If \a button is QMessageBox::NoButton, a suitable default is chosen + automatically. + + Returns the identity of the standard button that was clicked. However, if \key Esc was pressed, + returns the escape button. +*/ QMessageBox::StandardButton MessageBoxHandler::critical(QWidget *parent, const QString &identifier, const QString &title, const QString &text, QMessageBox::StandardButtons buttons, QMessageBox::StandardButton button) @@ -197,6 +214,18 @@ QMessageBox::StandardButton MessageBoxHandler::critical(QWidget *parent, const Q return instance()->showMessageBox(criticalType, parent, identifier, title, text, buttons, button); } +/*! + Opens an information message box with the parent \a parent, identifier \a identifier, + title \a title, and text \a text. + + The standard buttons specified by \a buttons are added to the message box. \a button specifies + the button that is used when \key Enter is pressed. \a button must refer to a button that is + specified in \a buttons. If \a button is QMessageBox::NoButton, a suitable default is chosen + automatically. + + Returns the identity of the standard button that was clicked. However, if \key Esc was pressed, + returns the escape button. +*/ QMessageBox::StandardButton MessageBoxHandler::information(QWidget *parent, const QString &identifier, const QString &title, const QString &text, QMessageBox::StandardButtons buttons, QMessageBox::StandardButton button) @@ -204,6 +233,18 @@ QMessageBox::StandardButton MessageBoxHandler::information(QWidget *parent, cons return instance()->showMessageBox(informationType, parent, identifier, title, text, buttons, button); } +/*! + Opens a question message box with the parent \a parent, identifier \a identifier, + title \a title, and text \a text. + + The standard buttons specified by \a buttons are added to the message box. \a button specifies + the button that is used when \key Enter is pressed. \a button must refer to a button that is + specified in \a buttons. If \a button is QMessageBox::NoButton, a suitable default is chosen + automatically. + + Returns the identity of the standard button that was clicked. However, if \key Esc was pressed, + returns the escape button. +*/ QMessageBox::StandardButton MessageBoxHandler::question(QWidget *parent, const QString &identifier, const QString &title, const QString &text, QMessageBox::StandardButtons buttons, QMessageBox::StandardButton button) @@ -211,6 +252,18 @@ QMessageBox::StandardButton MessageBoxHandler::question(QWidget *parent, const Q return instance()->showMessageBox(questionType, parent, identifier, title, text, buttons, button); } +/*! + Opens a warning message box with the parent \a parent, identifier \a identifier, + title \a title, and text \a text. + + The standard buttons specified by \a buttons are added to the message box. \a button specifies + the button that is used when \key Enter is pressed. \a button must refer to a button that is + specified in \a buttons. If \a button is QMessageBox::NoButton, a suitable default is chosen + automatically. + + Returns the identity of the standard button that was clicked. However, if \key Esc was pressed, + returns the escape button. +*/ QMessageBox::StandardButton MessageBoxHandler::warning(QWidget *parent, const QString &identifier, const QString &title, const QString &text, QMessageBox::StandardButtons buttons, QMessageBox::StandardButton button) @@ -220,6 +273,18 @@ QMessageBox::StandardButton MessageBoxHandler::warning(QWidget *parent, const QS // -- invokable +/*! + Opens a critical message box with the identifier \a identifier, title \a title, and text + \a text. + + The standard buttons specified by \a buttons are added to the message box. \a button specifies + the button that is used when \key Enter is pressed. \a button must refer to a button that is + specified in \a buttons. If \a button is QMessageBox::NoButton, a suitable default is chosen + automatically. + + Returns the identity of the standard button that was clicked. However, if \key Esc was pressed, + returns the escape button. +*/ int MessageBoxHandler::critical(const QString &identifier, const QString &title, const QString &text, int buttons, int button) const { @@ -227,6 +292,18 @@ int MessageBoxHandler::critical(const QString &identifier, const QString &title, QMessageBox::StandardButtons(buttons), QMessageBox::StandardButton(button)); } +/*! + Opens an information message box with the identifier \a identifier, title \a title, and text + \a text. + + The standard buttons specified by \a buttons are added to the message box. \a button specifies + the button that is used when \key Enter is pressed. \a button must refer to a button that is + specified in \a buttons. If \a button is QMessageBox::NoButton, a suitable default is chosen + automatically. + + Returns the identity of the standard button that was clicked. However, if \key Esc was pressed, + returns the escape button. +*/ int MessageBoxHandler::information(const QString &identifier, const QString &title, const QString &text, int buttons, int button) const { @@ -234,6 +311,18 @@ int MessageBoxHandler::information(const QString &identifier, const QString &tit QMessageBox::StandardButtons(buttons), QMessageBox::StandardButton(button)); } +/*! + Opens a question message box with the identifier \a identifier, title \a title, and text + \a text. + + The standard buttons specified by \a buttons are added to the message box. \a button specifies + the button that is used when \key Enter is pressed. \a button must refer to a button that is + specified in \a buttons. If \a button is QMessageBox::NoButton, a suitable default is chosen + automatically. + + Returns the identity of the standard button that was clicked. However, if \key Esc was pressed, + returns the escape button. +*/ int MessageBoxHandler::question(const QString &identifier, const QString &title, const QString &text, int buttons, int button) const { @@ -241,6 +330,17 @@ int MessageBoxHandler::question(const QString &identifier, const QString &title, QMessageBox::StandardButtons(buttons), QMessageBox::StandardButton(button)); } +/*! + Opens a warning message box with the identifier \a identifier, title \a title, and text \a text. + + The standard buttons specified by \a buttons are added to the message box. \a button specifies + the button that is used when \key Enter is pressed. \a button must refer to a button that is + specified in \a buttons. If \a button is QMessageBox::NoButton, a suitable default is chosen + automatically. + + Returns the identity of the standard button that was clicked. However, if \key Esc was pressed, + returns the escape button. +*/ int MessageBoxHandler::warning(const QString &identifier, const QString &title, const QString &text, int buttons, int button) const { -- cgit v1.2.3