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         @param message
  31             Message to show on the dialog.
  32         @param caption
  33             The dialog caption.
  34         @param style
  35             A dialog style (bitlist) containing flags chosen from the following:
  36
  37
  38
  39
  40
  41
  42
  43             wxOK
  44
  45
  46
  47
  48             Show an OK button.
  49
  50
  51
  52
  53
  54             wxCANCEL
  55
  56
  57
  58
  59             Show a Cancel button.
  60
  61
  62
  63
  64
  65             wxYES_NO
  66
  67
  68
  69
  70             Show Yes and No buttons.
  71
  72
  73
  74
  75
  76             wxYES_DEFAULT
  77
  78
  79
  80
  81             Used with wxYES_NO, makes Yes button the default - which is the default
  82         behaviour.
  83
  84
  85
  86
  87
  88             wxNO_DEFAULT
  89
  90
  91
  92
  93             Used with wxYES_NO, makes No button the default.
  94
  95
  96
  97
  98
  99             wxICON_EXCLAMATION
 100
 101
 102
 103
 104             Shows an exclamation mark icon.
 105
 106
 107
 108
 109
 110             wxICON_HAND
 111
 112
 113
 114
 115             Shows an error icon.
 116
 117
 118
 119
 120
 121             wxICON_ERROR
 122
 123
 124
 125
 126             Shows an error icon - the same as wxICON_HAND.
 127
 128
 129
 130
 131
 132             wxICON_QUESTION
 133
 134
 135
 136
 137             Shows a question mark icon.
 138
 139
 140
 141
 142
 143             wxICON_INFORMATION
 144
 145
 146
 147
 148             Shows an information (i) icon.
 149
 150
 151
 152
 153
 154             wxSTAY_ON_TOP
 155
 156
 157
 158
 159             The message box stays on top of all other window, even those of the other
 160         applications (Windows only).
 161         @param pos
 162             Dialog position. Not Windows.
 163     */
 164     wxMessageDialog(wxWindow* parent, const wxString& message,
 165                     const wxString& caption = "Message box",
 166                     long style = wxOK | wxCANCEL,
 167                     const wxPoint& pos = wxDefaultPosition);
 168
 169     /**
 170         Destructor.
 171     */
 172     ~wxMessageDialog();
 173
 174     /**
 175         Sets the extended message for the dialog: this message is usually an extension
 176         of the short message specified in the constructor or set with
 177         SetMessage(). If it is set, the main message
 178         appears highlighted -- if supported -- and this message appears beneath it in
 179         normal font. On the platforms which don't support extended messages, it is
 180         simply appended to the normal message with a new line separating them.
 181     */
 182     void SetExtendedMessage(const wxString exMsg);
 183
 184     /**
 185         Sets the message shown by the dialog.
 186     */
 187     void SetMessage(const wxString msg);
 188
 189     /**
 190         Overrides the default labels of the OK and Cancel buttons.
 191         Please see the remarks in
 192         SetYesNoLabels() documentation.
 193     */
 194     bool SetOKCancelLabels(const wxString ok, const wxString cancel);
 195
 196     /**
 197         Overrides the default label of the OK button.
 198         Please see the remarks in
 199         SetYesNoLabels() documentation.
 200     */
 201     bool SetOKLabel(const wxString ok);
 202
 203     /**
 204         Overrides the default labels of the Yes, No and Cancel buttons.
 205         Please see the remarks in
 206         SetYesNoLabels() documentation.
 207     */
 208     bool SetYesNoCancelLabels(const wxString yes, const wxString no,
 209                               const wxString cancel);
 210
 211     /**
 212         Overrides the default labels of the Yes and No buttons.
 213         Notice that this function is not currently available on all platforms, so it
 214         may return @false to indicate that the labels couldn't be changed. If it
 215         returns @true (currently only under wxMac), the labels were set successfully.
 216         Typically, if the function was used successfully, the main dialog message may
 217         need to be changed, e.g.:
 218     */
 219     bool SetYesNoLabels(const wxString yes, const wxString no);
 220
 221     /**
 222         Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, wxID_NO.
 223     */
 224     int ShowModal();
 225 };
 226
 227
 228 // ============================================================================
 229 // Global functions/macros
 230 // ============================================================================
 231
 232 /**
 233     General purpose message dialog.  @a style may be a bit list of the
 234     following identifiers:
 235
 236     wxYES_NO
 237
 238     Puts Yes and No buttons on the message box. May be combined with
 239     wxCANCEL.
 240
 241     wxCANCEL
 242
 243     Puts a Cancel button on the message box. May only be combined with
 244     wxYES_NO or wxOK.
 245
 246     wxOK
 247
 248     Puts an Ok button on the message box. May be combined with wxCANCEL.
 249
 250     wxICON_EXCLAMATION
 251
 252     Displays an exclamation mark symbol.
 253
 254     wxICON_HAND
 255
 256     Displays an error symbol.
 257
 258     wxICON_ERROR
 259
 260     Displays an error symbol - the same as wxICON_HAND.
 261
 262     wxICON_QUESTION
 263
 264     Displays a question mark symbol.
 265
 266     wxICON_INFORMATION
 267
 268     Displays an information symbol.
 269
 270     The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
 271     For example:
 272
 273     @code
 274     ...
 275       int answer = wxMessageBox("Quit program?", "Confirm",
 276                                 wxYES_NO | wxCANCEL, main_frame);
 277       if (answer == wxYES)
 278         main_frame-Close();
 279       ...
 280     @endcode
 281
 282     @a message may contain newline characters, in which case the
 283     message will be split into separate lines, to cater for large messages.
 284 */
 285 int wxMessageBox(const wxString& message,
 286                  const wxString& caption = "Message",
 287                  int style = wxOK,
 288                  wxWindow* parent = NULL,
 289                  int x = -1, int y = -1);
 290