qmessagebox.3qt

Qt/Embedded是一个多平台的C++图形用户界面应用程序框架

.TH QMessageBox 3qt "10 November 2000" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2000 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QMessageBox \- Displays a brief message, an icon, and some buttons
.SH SYNOPSIS
.br
.PP
\fC#include <qmessagebox.h>\fR
.PP
Inherits QDialog.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "enum \fBIcon\fR { NoIcon = 0, Information = 1, Warning = 2, Critical = 3 }"
.br
.ti -1c
.BI "\fBQMessageBox\fR ( QWidget * " "parent" "=0, const char * " "name" "=0 ) "
.br
.ti -1c
.BI "\fBQMessageBox\fR ( const QString & " "caption" ", const QString & " "text" ", Icon " "icon" ", int " "button0" ", int " "button1" ", int " "button2" ", QWidget * " "parent" "=0, const char * " "name" "=0, bool " "modal" "=TRUE, WFlags " "f" "=WStyle_DialogBorder ) "
.br
.ti -1c
.BI "\fB~QMessageBox\fR () "
.br
.ti -1c
.BI "enum { NoButton = 0, Ok = 1, Cancel = 2, Yes = 3, No = 4, Abort = 5, Retry = 6, Ignore = 7, ButtonMask = 0x07, Default = 0x100, Escape = 0x200, FlagMask = 0x300 }"
.br
.ti -1c
.BI "QString \fBtext\fR () const"
.br
.ti -1c
.BI "void \fBsetText\fR ( const QString & ) "
.br
.ti -1c
.BI "Icon \fBicon\fR () const"
.br
.ti -1c
.BI "void \fBsetIcon\fR ( Icon ) "
.br
.ti -1c
.BI "const QPixmap* \fBiconPixmap\fR () const"
.br
.ti -1c
.BI "void \fBsetIconPixmap\fR ( const QPixmap & ) "
.br
.ti -1c
.BI "QString \fBbuttonText\fR ( int button ) const"
.br
.ti -1c
.BI "void \fBsetButtonText\fR ( int " "button" ", const QString & ) "
.br
.ti -1c
.BI "virtual void \fBadjustSize\fR () "
.br
.ti -1c
.BI "TextFormat \fBtextFormat\fR () const"
.br
.ti -1c
.BI "void \fBsetTextFormat\fR ( TextFormat ) "
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "int \fBinformation\fR ( QWidget * " "parent" ", const QString & " "caption" ", const QString & " "text" ", int " "button0" ", int " "button1" "=0, int " "button2" "=0 ) "
.br
.ti -1c
.BI "int \fBinformation\fR ( QWidget * " "parent" ", const QString & " "caption" ", const QString & " "text" ", const QString & button0Text = QString::null, const QString & button1Text = QString::null, const QString & button2Text = QString::null, int " "defaultButtonNumber" " = 0, int " "escapeButtonNumber" " = -1 ) "
.br
.ti -1c
.BI "int \fBwarning\fR ( QWidget * " "parent" ", const QString & " "caption" ", const QString & " "text" ", int " "button0" ", int " "button1" ", int " "button2" "=0 ) "
.br
.ti -1c
.BI "int \fBwarning\fR ( QWidget * " "parent" ", const QString & " "caption" ", const QString & " "text" ", const QString & button0Text = QString::null, const QString & button1Text = QString::null, const QString & button2Text = QString::null, int " "defaultButtonNumber" " = 0, int " "escapeButtonNumber" " = -1 ) "
.br
.ti -1c
.BI "int \fBcritical\fR ( QWidget * " "parent" ", const QString & " "caption" ", const QString & " "text" ", int " "button0" ", int " "button1" ", int " "button2" "=0 ) "
.br
.ti -1c
.BI "int \fBcritical\fR ( QWidget * " "parent" ", const QString & " "caption" ", const QString & " "text" ", const QString & button0Text = QString::null, const QString & button1Text = QString::null, const QString & button2Text = QString::null, int " "defaultButtonNumber" " = 0, int " "escapeButtonNumber" " = -1 ) "
.br
.ti -1c
.BI "void \fBabout\fR ( QWidget * " "parent" ", const QString & " "caption" ", const QString & text ) "
.br
.ti -1c
.BI "void \fBaboutQt\fR ( QWidget * " "parent" ", const QString & caption=QString::null ) "
.br
.ti -1c
.BI "QPixmap \fBstandardIcon\fR ( Icon " "icon" ", GUIStyle style ) "
.br
.in -1c
.SS "Properties"
<table border=1 cellpadding=3 cellspacing=0> <tr><th>Type<th>Name<th>READ<th>WRITE<th>Options <tr><td>QString<td>text<td>text<td>setText<td>&nbsp; <tr><td>Icon<td>icon<td>icon<td>setIcon<td>&nbsp; <tr><td>QPixmap<td>iconPixmap<td>iconPixmap<td>setIconPixmap<td>&nbsp; <tr><td>TextFormat<td>textFormat<td>textFormat<td>setTextFormat<td>&nbsp; </table>
.SH DESCRIPTION
Displays a brief message, an icon, and some buttons.
.PP
A message box is a modal dialog that displays an icon, a text and up to three push buttons. It's used for simple messages and questions.
.PP
QMessageBox provides a range of different messages, arranged roughly along two axes: Severity and complexity.
.PP
Severity is
.TP
\fCInformation\fR - for message boxes that are part of normal operation
.TP
\fCWarning\fR - for message boxes that tell the user about unusual errors
.TP
\fCCritical\fR - as Warning, but for critical errors
.PP
The message box has a different icon for each of the severity levels.
.PP
Complexity is one button (Ok) for a simple messages, or two or even three buttons for questions.
.PP
There are static functions that let you do most of the common jobs, for example:
.PP
If a program is unable to find a supporting file, but can do perfectly well without:
.PP
.nf
.br
  QMessageBox::information( this, "Application name",
.br
                            "Unable to find the user preferences file.\\n"
.br
                            "The factory default will be used instead." );
.fi
.PP
warning() can be used to tell the user about unusual errors, or errors which can't be easily fixed:
.PP
.nf
.br
  switch( QMessageBox::warning( this, "Application name",
.br
                                "Could not connect to the <mumble> server.\\n"
.br
                          "This program can't function correctly "
.br
                          "without the server.\\n\\n",
.br
                          "Try again", "Quit", 0,
.br
                          0, 1 );
.br
  case 0: // Try again or Enter
.br
      // try again
.br
      break;
.br
  case 1: // Quit or Escape
.br
      // exit
.br
      break;
.br
  }
.fi
.PP
Finally,
.PP
The text part of all message box messages can be either rich text or plain text. If you specify a rich text formatted string, it will be rendered using the default stylesheet. See QStyleSheet::defaultSheet() for details. With certain strings that contain XML meta characters, the auto-rich text detection may fail, interpreting plain text falsely as rich text. In these rare cases, use QStyleSheet::convertFromPlainText() to convert your plain text string to a visually equivalent rich text string or set the text format explicitly with setTextFormat().
.PP
Here are some examples of how to use the static member functions. After these examples you will find an overview of the non-static member functions.
.PP
If a program is unable to find a supporting file, it may perhaps do:
.PP
.nf
.br
    QMessageBox::information( this, "Application name here",
.br
                              "Unable to find the file \\"index.html\\".\\n"
.br
                              "The factory default will be used instead." );
.fi
.PP
The Microsoft Windows User Interface Guidelines strongly recommends using the application name as window caption. The message box has just one button, OK, and its text tells the user both what happened and what the program will do about it. Since the application is able to make do, the message box is just information, not a warning or a critical error.
.PP
Exiting a program is part of its normal operation, and if there are unsaved data the user probably should be asked what to do, for example like this:
.PP
.nf
.br
    switch( QMessageBox::information( this, "Application name here",
.br
                                      "The document contains unsaved work\\n"
.br
                                      "Do you want to save it before exiting?",
.br
                                      "&Save", "&Don't Save", "&Cancel",
.br
                                      0,      // Enter == button 0
.br
                                      2 ) ) { // Escape == button 2
.br
    case 0: // Save clicked, Alt-S or Enter pressed.
.br
        // save
.br
        break;
.br
    case 1: // Don't Save clicked or Alt-D pressed
.br
        // don't save but exit
.br
        break;
.br
    case 2: // Cancel clicked, Alt-C or Escape pressed
.br
        // don't exit
.br
        break;
.br
    }
.fi
.PP
Again, the application name is used as window caption, as Microsoft recommends. The Escape button cancels the entire Exit operation, and Enter/Return saves the document and exits.
.PP
Disk full errors are unusual (in a perfect world, they are) and they certainly can be hard to correct. This example uses predefined buttons instead of hardcoded button texts:
.PP
.nf
.br
    switch( QMessageBox::warning( this, "Application name here",
.br
                                  "Could not save the the user preferences,\\n"
.br
                                  "because the disk is full.  You can delete\\n"
.br
                                  "some files and press Retry, or you can\\n"
.br
                                  "abort the Save Preferences operation.",
.br
                                  QMessageBox::Retry | QMessageBox::Default,
.br
                                  QMessageBox::Abort | QMessageBox::Escape )) {
.br
    case QMessageBox::Retry: // Retry or Enter
.br
        // try again
.br
        break;
.br
    case QMessageBox::Abort: // Abort or Cancel
.br
        // abort
.br
        break;
.br
    }
.fi
.PP
The critical() function should be reserved for critical errors. In this example, errorDetails is a QString or const char*, and QString is used to concatenate several strings:
.PP
.nf
.br
    QMessageBox::critical( 0, "Application name here",
.br
                           QString("An internal error occurred. Please ") +
.br
                           "call technical support at 123456789 and report\\n"+
.br
                           "these numbers:\\n\\n" + errorDetails +
.br
                           "\\n\\n<Application> will now exit." );
.fi
.PP
QMessageBox provides a very simple About box, which displays an appropriate icon and the string you give it:
.PP
.nf
.br
     QMessageBox::about( this, "About <Application>",
.br
                         "<Application> is a <one-paragraph blurb>\\n\\n"
.br
                         "Copyright 1951-1997 Such-and-such.  "
.br
                         "<License words here.>\\n\\n"
.br
                         "For technical support, call 123456789 or see\\n"
.br
                         "http://www.such-and-such.com/Application/\\n" );
.fi
.PP
See about() for more information.
.PP
Finally, you can make a QMessageBox from scratch and set custom button texts:
.PP
.nf
.br
    QMessageBox mb( "Application name here",
.br
                    "Saving the file will overwrite the old file on disk.\\n"
.br
                    "Do you really want to save?",
.br
                    QMessageBox::Information,
.br
                    QMessageBox::Yes | QMessageBox::Default,
.br
                    QMessageBox::No,
.br
                    QMessageBox::Cancel | QMessageBox::Escape );
.br
    mb.setButtonText( QMessageBox::Yes, "Save" );
.br
    mb.setButtonText( QMessageBox::No, "Don't Save" );
.br
    switch( mb.exec() ) {
.br
        case QMessageBox::Yes:
.br