interface/wx/msgdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msgdlg.h
   3 // Purpose:     interface of wxMessageDialog
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Default message box caption string.
  11 */
  12 const char wxMessageBoxCaptionStr[] = "Message";
  13
  14
  15 /**
  16     @class wxMessageDialog
  17
  18     This class represents a dialog that shows a single or multi-line message,
  19     with a choice of OK, Yes, No and Cancel buttons.
  20
  21     @beginStyleTable
  22     @style{wxOK}
  23         Puts an Ok button in the message box. May be combined with @c wxCANCEL.
  24     @style{wxCANCEL}
  25         Puts a Cancel button in the message box. Must be combined with
  26         either @c wxOK or @c wxYES_NO.
  27     @style{wxYES_NO}
  28         Puts Yes and No buttons in the message box. It is recommended to always
  29         use @c wxCANCEL with this style as otherwise the message box won't have
  30         a close button under wxMSW and the user will be forced to answer it.
  31     @style{wxHELP}
  32         Puts a Help button to the message box. This button can have special
  33         appearance or be specially positioned if its label is not changed from
  34         the default one. Notice that using this button is not supported when
  35         showing a message box from non-main thread in wxOSX/Cocoa and it is not
  36         supported in wxOSX/Carbon at all. @since 2.9.3.
  37     @style{wxNO_DEFAULT}
  38         Makes the "No" button default, can only be used with @c wxYES_NO.
  39     @style{wxCANCEL_DEFAULT}
  40         Makes the "Cancel" button default, can only be used with @c wxCANCEL
  41     @style{wxYES_DEFAULT}
  42         Makes the "Yes" button default, this is the default behaviour and
  43         this flag exists solely for symmetry with @c wxNO_DEFAULT.
  44     @style{wxOK_DEFAULT}
  45         Makes the "OK" button default, this is the default behaviour and
  46         this flag exists solely for symmetry with @c wxCANCEL_DEFAULT.
  47     @style{wxICON_NONE}
  48         Displays no icon in the dialog if possible (an icon might still be
  49         displayed if the current platform mandates its use). This style may be
  50         used to prevent the dialog from using the default icon based on @c
  51         wxYES_NO presence as explained in @c wxICON_QUESTION and @c
  52         wxICON_INFORMATION documentation below.
  53     @style{wxICON_EXCLAMATION}
  54         Displays an exclamation, or warning, icon in the dialog.
  55     @style{wxICON_ERROR}
  56         Displays an error icon in the dialog.
  57     @style{wxICON_HAND}
  58         Displays an error symbol, this is a MSW-inspired synonym for @c wxICON_ERROR.
  59     @style{wxICON_QUESTION}
  60         Displays a question mark symbol. This icon is automatically used
  61         with @c wxYES_NO so it's usually unnecessary to specify it explicitly.
  62         This style is not supported for message dialogs under wxMSW when a task
  63         dialog is used to implement them (i.e. when running under Windows Vista
  64         or later) because <a href="http://msdn.microsoft.com/en-us/library/aa511273.aspx">Microsoft
  65         guidelines</a> indicate that no icon should be used for routine
  66         confirmations. If it is specified, no icon will be displayed.
  67     @style{wxICON_INFORMATION}
  68         Displays an information symbol. This icon is used by default if
  69         @c wxYES_NO is not given so it is usually unnecessary to specify it
  70         explicitly.
  71     @style{wxSTAY_ON_TOP}
  72         Makes the message box stay on top of all other windows and not only
  73         just its parent (currently implemented only under MSW and GTK).
  74     @style{wxCENTRE}
  75         Centre the message box on its parent or on the screen if parent is not
  76         specified.
  77         Setting this style under MSW makes no differences as the dialog is
  78         always centered on the parent.
  79     @endStyleTable
  80
  81     @library{wxcore}
  82     @category{cmndlg}
  83
  84     @see @ref overview_cmndlg_msg
  85     @see wxRichMessageDialog
  86 */
  87 class wxMessageDialog : public wxDialog
  88 {
  89 public:
  90     /**
  91         Helper class allowing to use either stock id or string labels.
  92
  93         This class should never be used explicitly and is not really part of
  94         wxWidgets API but rather is just an implementation helper allowing the
  95         methods such as SetYesNoLabels() and SetOKCancelLabels() below to be
  96         callable with either stock ids (e.g. ::wxID_CLOSE) or strings
  97         ("&Close").
  98      */
  99     class ButtonLabel
 100     {
 101     public:
 102         /// Construct the label from a stock id.
 103         ButtonLabel(int stockId);
 104
 105         /// Construct the label from the specified string.
 106         ButtonLabel(const wxString& label);
 107
 108         /**
 109             Return the associated label as string.
 110
 111             Get the string label, whether it was originally specified directly
 112             or as a stock id -- this is only useful for platforms without native
 113             stock items id support
 114          */
 115         wxString GetAsString() const;
 116
 117         /**
 118             Return the stock id or wxID_NONE if this is not a stock label.
 119          */
 120         int GetStockId() const;
 121     };
 122
 123     /**
 124         Constructor specifying the message box properties.
 125         Use ShowModal() to show the dialog.
 126
 127         @a style may be a bit list of the identifiers described above.
 128
 129         Notice that not all styles are compatible: only one of @c wxOK and
 130         @c wxYES_NO may be specified (and one of them must be specified) and at
 131         most one default button style can be used and it is only valid if the
 132         corresponding button is shown in the message box.
 133
 134         @param parent
 135             Parent window.
 136         @param message
 137             Message to show in the dialog.
 138         @param caption
 139             The dialog title.
 140         @param style
 141             Combination of style flags described above.
 142         @param pos
 143             Dialog position (ignored under MSW).
 144     */
 145     wxMessageDialog(wxWindow* parent, const wxString& message,
 146                     const wxString& caption = wxMessageBoxCaptionStr,
 147                     long style = wxOK | wxCENTRE,
 148                     const wxPoint& pos = wxDefaultPosition);
 149
 150     /**
 151         Sets the extended message for the dialog: this message is usually an
 152         extension of the short message specified in the constructor or set with
 153         SetMessage().
 154
 155         If it is set, the main message appears highlighted -- if supported --
 156         and this message appears beneath it in normal font. On the platforms
 157         which don't support extended messages, it is simply appended to the
 158         normal message with an empty line separating them.
 159
 160         @since 2.9.0
 161     */
 162     virtual void SetExtendedMessage(const wxString& extendedMessage);
 163
 164     /**
 165         Sets the label for the Help button.
 166
 167         Please see the remarks in SetYesNoLabels() documentation.
 168
 169         Notice that changing the label of the help button resets its special
 170         status (if any, this depends on the platform) and it will be treated
 171         just like another button in this case.
 172
 173         @since 2.9.3
 174      */
 175     virtual bool SetHelpLabel(const ButtonLabel& help);
 176
 177     /**
 178         Sets the message shown by the dialog.
 179
 180         @since 2.9.0
 181     */
 182     virtual void SetMessage(const wxString& message);
 183
 184     /**
 185         Overrides the default labels of the OK and Cancel buttons.
 186
 187         Please see the remarks in SetYesNoLabels() documentation.
 188
 189         @since 2.9.0
 190     */
 191     virtual bool SetOKCancelLabels(const ButtonLabel& ok,
 192                                    const ButtonLabel& cancel);
 193
 194     /**
 195         Overrides the default label of the OK button.
 196
 197         Please see the remarks in SetYesNoLabels() documentation.
 198
 199         @since 2.9.0
 200     */
 201     virtual bool SetOKLabel(const ButtonLabel& ok);
 202
 203     /**
 204         Overrides the default labels of the Yes, No and Cancel buttons.
 205
 206         Please see the remarks in SetYesNoLabels() documentation.
 207
 208         @since 2.9.0
 209     */
 210     virtual bool SetYesNoCancelLabels(const ButtonLabel& yes,
 211                                       const ButtonLabel& no,
 212                                       const ButtonLabel& cancel);
 213
 214     /**
 215         Overrides the default labels of the Yes and No buttons.
 216
 217         The arguments of this function can be either strings or one of the
 218         standard identifiers, such as @c wxID_APPLY or @c wxID_OPEN. Notice
 219         that even if the label is specified as an identifier, the return value
 220         of the dialog ShowModal() method still remains one of @c wxID_OK, @c
 221         wxID_CANCEL, @c wxID_YES or @c wxID_NO values, i.e. this identifier
 222         changes only the label appearance but not the return code generated by
 223         the button. It is possible to mix stock identifiers and string labels
 224         in the same function call, for example:
 225         @code
 226         wxMessageDialog dlg(...);
 227         dlg.SetYesNoLabels(wxID_SAVE, _("&Don't save"));
 228         @endcode
 229
 230         Also notice that this function is not currently available on all
 231         platforms (although as of wxWidgets 2.9.0 it is implemented in all
 232         major ports), so it may return @false to indicate that the labels
 233         couldn't be changed. If it returns @true, the labels were set
 234         successfully.
 235
 236         Typically, if the function was used successfully, the main dialog
 237         message may need to be changed, e.g.:
 238         @code
 239         wxMessageDialog dlg(...);
 240         if ( dlg.SetYesNoLabels(_("&Quit"), _("&Don't quit")) )
 241             dlg.SetMessage(_("What do you want to do?"));
 242         else // buttons have standard "Yes"/"No" values, so rephrase the question
 243             dlg.SetMessage(_("Do you really want to quit?"));
 244         @endcode
 245
 246         @since 2.9.0
 247     */
 248     virtual bool SetYesNoLabels(const ButtonLabel& yes, const ButtonLabel& no);
 249
 250     /**
 251         Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES,
 252         wxID_NO or wxID_HELP.
 253
 254         Notice that this method returns the identifier of the button which was
 255         clicked unlike wxMessageBox() function.
 256     */
 257     virtual int ShowModal();
 258
 259
 260     wxString GetCaption() const;
 261     wxString GetMessage() const;
 262     wxString GetExtendedMessage() const;
 263     long GetMessageDialogStyle() const;
 264     bool HasCustomLabels() const;
 265     wxString GetYesLabel() const;
 266     wxString GetNoLabel() const;
 267     wxString GetOKLabel() const;
 268     wxString GetCancelLabel() const;
 269     wxString GetHelpLabel() const;
 270     long GetEffectiveIcon() const;
 271
 272 };
 273
 274
 275
 276 // ============================================================================
 277 // Global functions/macros
 278 // ============================================================================
 279
 280 /** @addtogroup group_funcmacro_dialog */
 281 //@{
 282
 283 /**
 284     Show a general purpose message dialog.
 285
 286     This is a convenient function which is usually used instead of using
 287     wxMessageDialog directly. Notice however that some of the features, such as
 288     extended text and custom labels for the message box buttons, are not
 289     provided by this function but only by wxMessageDialog.
 290
 291     The return value is one of: @c wxYES, @c wxNO, @c wxCANCEL, @c wxOK or @c
 292     wxHELP (notice that this return value is @b different from the return value
 293     of wxMessageDialog::ShowModal()).
 294
 295     For example:
 296     @code
 297     int answer = wxMessageBox("Quit program?", "Confirm",
 298                               wxYES_NO | wxCANCEL, main_frame);
 299     if (answer == wxYES)
 300         main_frame->Close();
 301     @endcode
 302
 303     @a message may contain newline characters, in which case the message will
 304     be split into separate lines, to cater for large messages.
 305
 306     @param message
 307         Message to show in the dialog.
 308     @param caption
 309         The dialog title.
 310     @param parent
 311         Parent window.
 312     @param style
 313         Combination of style flags described in wxMessageDialog documentation.
 314     @param x
 315         Horizontal dialog position (ignored under MSW). Use ::wxDefaultCoord
 316         for @a x and @a y to let the system position the window.
 317     @param y
 318         Vertical dialog position (ignored under MSW).
 319
 320     @header{wx/msgdlg.h}
 321 */
 322 int wxMessageBox(const wxString& message,
 323                  const wxString& caption = wxMessageBoxCaptionStr,
 324                  int style = wxOK | wxCENTRE,
 325                  wxWindow* parent = NULL,
 326                  int x = wxDefaultCoord,
 327                  int y = wxDefaultCoord);
 328
 329 //@}
 330