interface/msgdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msgdlg.h
   3 // Purpose:     documentation for wxMessageDialog class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMessageDialog
  11     @wxheader{msgdlg.h}
  12
  13     This class represents a dialog that shows a single or multi-line message,
  14     with a choice of OK, Yes, No and Cancel buttons.
  15
  16     @library{wxcore}
  17     @category{cmndlg}
  18
  19     @seealso
  20     @ref overview_wxmessagedialogoverview "wxMessageDialog overview"
  21 */
  22 class wxMessageDialog : public wxDialog
  23 {
  24 public:
  25     /**
  26         Constructor. Use ShowModal() to show the dialog.
  27
  28         @param parent
  29         Parent window.
  30
  31         @param message
  32         Message to show on the dialog.
  33
  34         @param caption
  35         The dialog caption.
  36
  37         @param style
  38         A dialog style (bitlist) containing flags chosen from the following:
  39
  40
  41         wxOK
  42
  43
  44         Show an OK button.
  45
  46         wxCANCEL
  47
  48
  49         Show a Cancel button.
  50
  51         wxYES_NO
  52
  53
  54         Show Yes and No buttons.
  55
  56         wxYES_DEFAULT
  57
  58
  59         Used with wxYES_NO, makes Yes button the default - which is the default
  60         behaviour.
  61
  62         wxNO_DEFAULT
  63
  64
  65         Used with wxYES_NO, makes No button the default.
  66
  67         wxICON_EXCLAMATION
  68
  69
  70         Shows an exclamation mark icon.
  71
  72         wxICON_HAND
  73
  74
  75         Shows an error icon.
  76
  77         wxICON_ERROR
  78
  79
  80         Shows an error icon - the same as wxICON_HAND.
  81
  82         wxICON_QUESTION
  83
  84
  85         Shows a question mark icon.
  86
  87         wxICON_INFORMATION
  88
  89
  90         Shows an information (i) icon.
  91
  92         wxSTAY_ON_TOP
  93
  94
  95         The message box stays on top of all other window, even those of the other
  96         applications (Windows only).
  97
  98         @param pos
  99         Dialog position. Not Windows.
 100     */
 101     wxMessageDialog(wxWindow* parent, const wxString& message,
 102                     const wxString& caption = "Message box",
 103                     long style = wxOK |  wxCANCEL,
 104                     const wxPoint& pos = wxDefaultPosition);
 105
 106     /**
 107         Destructor.
 108     */
 109     ~wxMessageDialog();
 110
 111     /**
 112         Sets the extended message for the dialog: this message is usually an extension
 113         of the short message specified in the constructor or set with
 114         SetMessage(). If it is set, the main message
 115         appears highlighted -- if supported -- and this message appears beneath it in
 116         normal font. On the platforms which don't support extended messages, it is
 117         simply appended to the normal message with a new line separating them.
 118     */
 119     void SetExtendedMessage(const wxString exMsg);
 120
 121     /**
 122         Sets the message shown by the dialog.
 123     */
 124     void SetMessage(const wxString msg);
 125
 126     /**
 127         Overrides the default labels of the OK and Cancel buttons.
 128
 129         Please see the remarks in
 130         SetYesNoLabels() documentation.
 131     */
 132     bool SetOKCancelLabels(const wxString ok, const wxString cancel);
 133
 134     /**
 135         Overrides the default label of the OK button.
 136
 137         Please see the remarks in
 138         SetYesNoLabels() documentation.
 139     */
 140     bool SetOKLabel(const wxString ok);
 141
 142     /**
 143         Overrides the default labels of the Yes, No and Cancel buttons.
 144
 145         Please see the remarks in
 146         SetYesNoLabels() documentation.
 147     */
 148     bool SetYesNoCancelLabels(const wxString yes, const wxString no,
 149                               const wxString cancel);
 150
 151     /**
 152         Overrides the default labels of the Yes and No buttons.
 153
 154         Notice that this function is not currently available on all platforms, so it
 155         may return @false to indicate that the labels couldn't be changed. If it
 156         returns @true (currently only under wxMac), the labels were set successfully.
 157         Typically, if the function was used successfully, the main dialog message may
 158         need to be changed, e.g.:
 159     */
 160     bool SetYesNoLabels(const wxString yes, const wxString no);
 161
 162     /**
 163         Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, wxID_NO.
 164     */
 165     int ShowModal();
 166 };
 167
 168
 169 // ============================================================================
 170 // Global functions/macros
 171 // ============================================================================
 172
 173 /**
 174     General purpose message dialog.  @e style may be a bit list of the
 175     following identifiers:
 176
 177     wxYES_NO
 178
 179
 180     Puts Yes and No buttons on the message box. May be combined with
 181     wxCANCEL.
 182
 183     wxCANCEL
 184
 185
 186     Puts a Cancel button on the message box. May only be combined with
 187     wxYES_NO or wxOK.
 188
 189     wxOK
 190
 191
 192     Puts an Ok button on the message box. May be combined with wxCANCEL.
 193
 194     wxICON_EXCLAMATION
 195
 196
 197     Displays an exclamation mark symbol.
 198
 199     wxICON_HAND
 200
 201
 202     Displays an error symbol.
 203
 204     wxICON_ERROR
 205
 206
 207     Displays an error symbol - the same as wxICON_HAND.
 208
 209     wxICON_QUESTION
 210
 211
 212     Displays a question mark symbol.
 213
 214     wxICON_INFORMATION
 215
 216
 217     Displays an information symbol.
 218
 219     The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
 220
 221     For example:
 222     @code
 223     ...
 224       int answer = wxMessageBox("Quit program?", "Confirm",
 225                                 wxYES_NO | wxCANCEL, main_frame);
 226       if (answer == wxYES)
 227         main_frame-Close();
 228       ...
 229     @endcode
 230
 231     @e message may contain newline characters, in which case the
 232     message will be split into separate lines, to cater for large messages.
 233 */
 234 int wxMessageBox(const wxString& message,
 235                  const wxString& caption = "Message",
 236                  int style = wxOK,
 237                  wxWindow * parent = @NULL,
 238                  int x = -1, int y = -1);
 239