Home · All Classes · Main Classes · Grouped Classes · Modules · Functions

QMessageBoxEx Class Reference
[QtGui module]

The QMessageBoxEx class provides a modal dialog with a short message, an icon, and buttons laid out depending on the current style. More...

#include <QMessageBoxEx>

Inherits QDialog.

This class was introduced in Qt 4.2.

Public Types

Properties

Public Functions

Static Public Members

Additional Inherited Members


Detailed Description

The QMessageBoxEx class provides a modal dialog with a short message, an icon, and buttons laid out depending on the current style.

Message boxes are used to provide informative messages and to ask simple questions. QMessageBoxEx provides all the functionality of QMessageBox. In addition, QMessageBoxEx has the capability to add any number of buttons to the message box. The buttons in the box are laid out depending on the platform.

Like QMessageBox, QMessageBoxEx provides a range of different messages depending on the severity of the message. The message box has a different icon for each of the severity levels.You can use the static functions, QMessageBox::information(), QMessageBox::question(), QMessageBox::critical and QMessageBox::warning() for the most common cases.

The text part of all message box messages can be either rich text or plain text. With certain strings that contain XML meta characters, the auto-rich text detection may fail, interpreting plain text incorrectly as rich text. In these rare cases, use Qt::convertFromPlainText() to convert your plain text string to a visually equivalent rich text string or set the text format explicitly with setTextFormat().

Note that the Microsoft Windows User Interface Guidelines recommend using the application name as the window's caption.

If none of the standard message boxes is suitable, you can create a QMessageBoxEx from scratch. You can use QMessageBoxEx::addButton() to add the standard buttons in QMessageBox::StandardButton. QMessageBoxEx::addButton() has an additional overload, that takes a custom text and the button role as an argument. The button role is used to automatically determine the position of the button within the dialog box.

The text(), icon() and iconPixmap() functions provide access to the current text and pixmap of the message box. The setText(), setIcon() and setIconPixmap() let you change it. The difference between setIcon() and setIconPixmap() is that the former accepts a QMessageBoxEx::Icon and can be used to set standard icons, whereas the latter accepts a QPixmap and can be used to set custom icons.

setButtonText() and buttonText() provide access to the buttons.

QMessageBoxEx has no signals or slots.

The Standard Dialogs example shows how to use QMessageBoxEx as well as other built-in Qt dialogs.

See also QDialogButtonBox, QMessageBox, GUI Design Handbook: Message Box, Standard Dialogs Example, and Application Example.


Member Type Documentation

enum QMessageBoxEx::ButtonRole

This enum describes the roles that can be used to describe buttons in the message box. Combinations of these roles are as flags used to describe different aspects of their behavior.

ConstantValueDescription
QMessageBoxEx::InvalidRole-1The button is invalid.
QMessageBoxEx::AcceptRole0Clicking the button causes the dialog to be accepted (e.g. OK).
QMessageBoxEx::RejectRole1Clicking the button causes the dialog to be rejected (e.g. Cancel).
QMessageBoxEx::DestructiveRole2Clicking the button causes a destructive change (e.g. for Discarding Changes).
QMessageBoxEx::ActionRole3Clicking the button causes changes to the elements in the dialog (e.g. reset all the values or read defaults).
QMessageBoxEx::HelpRole4The button can be clicked to request help.

enum QMessageBoxEx::Icon

This enum has the following values:

ConstantValueDescription
QMessageBoxEx::NoIcon0the message box does not have any icon.
QMessageBoxEx::Question4an icon indicating that the message is asking a question.
QMessageBoxEx::Information1an icon indicating that the message is nothing out of the ordinary.
QMessageBoxEx::Warning2an icon indicating that the message is a warning, but can be dealt with.
QMessageBoxEx::Critical3an icon indicating that the message represents a critical problem.

enum QMessageBoxEx::StandardButton
flags QMessageBoxEx::StandardButtons

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

ConstantValueDescription
QMessageBoxEx::Ok0x00000001An "OK" button defined with the AcceptRole.
QMessageBoxEx::Open0x00000008A "Open" button defined with the AcceptRole.
QMessageBoxEx::Save0x00000002A "Save" button defined with the AcceptRole.
QMessageBoxEx::Cancel0x00001000A "Cancel" button defined with the RejectRole.
QMessageBoxEx::Close0x00000800A "Close" button defined with the RejectRole.
QMessageBoxEx::Discard0x00002000A "Discard" or "Don't Save" button, depending on the platform, defined with the DestructiveRole.
QMessageBoxEx::Apply0x00008000An "Apply" button defined with the ActionRole.
QMessageBoxEx::Reset0x00010000A "Reset" button defined with the ActionRole.
QMessageBoxEx::Help0x00004000A "Help" button defined with the HelpRole.
QMessageBoxEx::SaveAll0x00000004A "Save All" button defined with the AcceptRole
QMessageBoxEx::Yes0x00000010A "Yes" button defined with the AcceptRole
QMessageBoxEx::YesToAll0x00000020A "Yes to All" button defined with the AcceptRole
QMessageBoxEx::No0x00000040A "No" button defined with the RejectRole
QMessageBoxEx::NoToAll0x00000080A "No to All" button defined with the RejectRole
QMessageBoxEx::Abort0x00000100An "Abort" button defined with the RejectRole
QMessageBoxEx::Retry0x00000200A "Retry" button defined with the ActionRole
QMessageBoxEx::Ignore0x00000400An "Ignore" button defined with the ActionRole

The StandardButtons type is a typedef for QFlags<StandardButton>. It stores an OR combination of StandardButton values.


Property Documentation

icon : Icon

This property holds the message box's icon.

The icon of the message box can be one of the following predefined icons:

The actual pixmap used for displaying the icon depends on the current GUI style. You can also set a custom pixmap icon using the QMessageBoxEx::iconPixmap property. The default icon is QMessageBoxEx::NoIcon.

Access functions:

See also iconPixmap.

iconPixmap : QPixmap

This property holds the current icon.

The icon currently used by the message box. Note that it's often hard to draw one pixmap that looks appropriate in all GUI styles; you may want to supply a different pixmap for each platform.

Access functions:

See also icon.

text : QString

This property holds the message box text to be displayed.

The text will be interpreted either as a plain text or as rich text, depending on the text format setting (QMessageBoxEx::textFormat). The default setting is Qt::AutoText, i.e. the message box will try to auto-detect the format of the text.

The default value of this property is an empty string.

Access functions:

See also textFormat.

textFormat : Qt::TextFormat

This property holds the format of the text displayed by the message box.

The current text format used by the message box. See the Qt::TextFormat enum for an explanation of the possible options.

The default format is Qt::AutoText.

Access functions:

See also setText().


Member Function Documentation

QMessageBoxEx::QMessageBoxEx ( QWidget * parent = 0 )

Constructs a message box with no text and no buttons.

If parent is 0, the message box becomes an application-global modal dialog box. If parent is a widget, the message box becomes modal relative to parent.

The parent argument is passed to the QDialog constructor.

QMessageBoxEx::QMessageBoxEx ( const QString & caption, const QString & text, Icon icon, QWidget * parent = 0, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint )

Constructs a message box with a caption, a text and an icon. Buttons to the message box can be added using addButton().

If parent is 0, the message box becomes an application-global modal dialog box. If parent is a widget, the message box becomes modal relative to parent.

The parent and f arguments are passed to the QDialog constructor.

See also setWindowTitle(), setText(), and setIcon().

QMessageBoxEx::~QMessageBoxEx ()

Destroys the message box.

void QMessageBoxEx::about ( QWidget * parent, const QString & caption, const QString & text )   [static]

Displays a simple about box with caption caption and text text. The about box's parent is parent.

about() looks for a suitable icon in four locations:

  1. It prefers parent->icon() if that exists.
  2. If not, it tries the top-level widget containing parent.
  3. If that fails, it tries the active window.
  4. As a last resort it uses the Information icon.

The about box has a single button labelled "OK".

See also QWidget::windowIcon() and QApplication::activeWindow().

void QMessageBoxEx::aboutQt ( QWidget * parent, const QString & caption = QString() )   [static]

Displays a simple message box about Qt, with caption caption and centered over parent (if parent is not 0). The message includes the version number of Qt being used by the application.

This is useful for inclusion in the Help menu of an application. See the examples/menu/menu.cpp example.

QApplication provides this functionality as a slot.

See also QApplication::aboutQt().

int QMessageBoxEx::addButton ( const QString & text, ButtonRole role )

Creates a button with the given text, adds it to the message box for the specified role, and returns the corresponding button id. If role is invalid, no button is created, and -1 is returned.

Button id's start from 0. Id's are guaranteed to be in the order in which they were added.

int QMessageBoxEx::addButton ( StandardButton button )

This is an overloaded member function, provided for convenience.

Adds a standard button to the message box if it is valid to do so, and returns the button id. If button is invalid, it is not added to the button box, and -1 is returned.

QPushButton * QMessageBoxEx::button ( int id ) const

Returns the QPushButton associated with the button id id

StandardButton QMessageBoxEx::critical ( QWidget * parent, const QString & caption, const QString & text, StandardButtons buttons = Ok, StandardButton defaultButton = NoButton )   [static]

Opens a critical message box with the caption caption and the text text. The standard buttons buttons is added to the message box. defaultButton specifies the button be used as the defaultButton. If the defaultButton is set to QMessageBoxEx::NoButton, QMessageBoxEx picks a suitable default automatically.

Returns the identity of the standard button that was activated. If escape was pressed, returns QMessageBoxEx::Cancel.

If parent is 0, the message box becomes an application-global modal dialog box. If parent is a widget, the message box becomes modal relative to parent.

See also question(), warning(), and information().

int QMessageBoxEx::defaultButton () const

Returns the button id that gets activated by default. Returns -1 if no default button was set.

See also addButton() and setDefaultButton().

int QMessageBoxEx::escapeButton () const

Returns the button id that gets activated when escape is presed. Returns -1 if no escape button was set.

See also addButton() and setEscapeButton().

StandardButton QMessageBoxEx::information ( QWidget * parent, const QString & caption, const QString & text, StandardButtons buttons = Ok, StandardButton defaultButton = NoButton )   [static]

Opens an information message box with the caption caption and the text text. The standard buttons buttons is added to the message box. defaultButton specifies the button be used as the defaultButton. If the defaultButton is set to QMessageBoxEx::NoButton, QMessageBoxEx picks a suitable default automatically.

Returns the identity of the standard button that was activated. If escape was pressed, returns QMessageBoxEx::Cancel.

If parent is 0, the message box becomes an application-global modal dialog box. If parent is a widget, the message box becomes modal relative to parent.

See also question(), warning(), and critical().

StandardButton QMessageBoxEx::question ( QWidget * parent, const QString & caption, const QString & text, StandardButtons buttons = Ok, StandardButton defaultButton = NoButton )   [static]

Opens a question message box with the caption caption and the text text. The standard buttons buttons is added to the message box. defaultButton specifies the button be used as the defaultButton. If the defaultButton is set to QMessageBoxEx::NoButton, QMessageBoxEx picks a suitable default automatically.

Returns the identity of the standard button that was activated. If escape was pressed, returns QMessageBoxEx::Cancel.

If parent is 0, the message box becomes an application-global modal dialog box. If parent is a widget, the message box becomes modal relative to parent.

See also information(), warning(), and critical().

void QMessageBoxEx::setDefaultButton ( int id )

Sets the button that gets activated by default id.

See also addButton() and defaultButton().

void QMessageBoxEx::setEscapeButton ( int id )

Sets the button that gets activated when escape key is pressed to id.

See also escapeButton() and addButton().

StandardButton QMessageBoxEx::warning ( QWidget * parent, const QString & caption, const QString & text, StandardButtons buttons = Ok, StandardButton defaultButton = NoButton )   [static]

Opens a warning message box with the caption caption and the text text. The standard buttons buttons is added to the message box. defaultButton specifies the button be used as the defaultButton. If the defaultButton is set to QMessageBoxEx::NoButton, QMessageBoxEx picks a suitable default automatically.

Returns the identity of the standard button that was activated. If escape was pressed, returns QMessageBoxEx::Cancel.

If parent is 0, the message box becomes an application-global modal dialog box. If parent is a widget, the message box becomes modal relative to parent.

See also question(), information(), and critical().


Copyright © 2006 Trolltech Trademarks
Qt 4.2.0-snapshot-20060701