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{wxICON_AUTH_NEEDED}
  72         Displays an authentication needed symbol. This style is only supported
  73         for message dialogs under wxMSW when a task dialog is used to implement
  74         them (i.e. when running under Windows Vista or later). In other cases
  75         the default icon selection logic will be used. Note this can be
  76         combined with other styles to provide a fallback. For instance, using
  77         wxICON_AUTH_NEEDED | wxICON_QUESTION will show a shield symbol on
  78         Windows Vista or above and a question symbol on other platforms.
  79         @since 2.9.5
  80     @style{wxSTAY_ON_TOP}
  81         Makes the message box stay on top of all other windows and not only
  82         just its parent (currently implemented only under MSW and GTK).
  83     @style{wxCENTRE}
  84         Centre the message box on its parent or on the screen if parent is not
  85         specified.
  86         Setting this style under MSW makes no differences as the dialog is
  87         always centered on the parent.
  88     @endStyleTable
  89
  90     @library{wxcore}
  91     @category{cmndlg}
  92
  93     @see @ref overview_cmndlg_msg
  94     @see wxRichMessageDialog
  95 */
  96 class wxMessageDialog : public wxDialog
  97 {
  98 public:
  99     /**
 100         Helper class allowing to use either stock id or string labels.
 101
 102         This class should never be used explicitly and is not really part of
 103         wxWidgets API but rather is just an implementation helper allowing the
 104         methods such as SetYesNoLabels() and SetOKCancelLabels() below to be
 105         callable with either stock ids (e.g. ::wxID_CLOSE) or strings
 106         ("&Close").
 107      */
 108     class ButtonLabel
 109     {
 110     public:
 111         /// Construct the label from a stock id.
 112         ButtonLabel(int stockId);
 113
 114         /// Construct the label from the specified string.
 115         ButtonLabel(const wxString& label);
 116
 117         /**
 118             Return the associated label as string.
 119
 120             Get the string label, whether it was originally specified directly
 121             or as a stock id -- this is only useful for platforms without native
 122             stock items id support
 123          */
 124         wxString GetAsString() const;
 125
 126         /**
 127             Return the stock id or wxID_NONE if this is not a stock label.
 128          */
 129         int GetStockId() const;
 130     };
 131
 132     /**
 133         Constructor specifying the message box properties.
 134         Use ShowModal() to show the dialog.
 135
 136         @a style may be a bit list of the identifiers described above.
 137
 138         Notice that not all styles are compatible: only one of @c wxOK and
 139         @c wxYES_NO may be specified (and one of them must be specified) and at
 140         most one default button style can be used and it is only valid if the
 141         corresponding button is shown in the message box.
 142
 143         @param parent
 144             Parent window.
 145         @param message
 146             Message to show in the dialog.
 147         @param caption
 148             The dialog title.
 149         @param style
 150             Combination of style flags described above.
 151         @param pos
 152             Dialog position (ignored under MSW).
 153     */
 154     wxMessageDialog(wxWindow* parent, const wxString& message,
 155                     const wxString& caption = wxMessageBoxCaptionStr,
 156                     long style = wxOK | wxCENTRE,
 157                     const wxPoint& pos = wxDefaultPosition);
 158
 159     /**
 160         Sets the extended message for the dialog: this message is usually an
 161         extension of the short message specified in the constructor or set with
 162         SetMessage().
 163
 164         If it is set, the main message appears highlighted -- if supported --
 165         and this message appears beneath it in normal font. On the platforms
 166         which don't support extended messages, it is simply appended to the
 167         normal message with an empty line separating them.
 168
 169         @since 2.9.0
 170     */
 171     virtual void SetExtendedMessage(const wxString& extendedMessage);
 172
 173     /**
 174         Sets the label for the Help button.
 175
 176         Please see the remarks in SetYesNoLabels() documentation.
 177
 178         Notice that changing the label of the help button resets its special
 179         status (if any, this depends on the platform) and it will be treated
 180         just like another button in this case.
 181
 182         @since 2.9.3
 183      */
 184     virtual bool SetHelpLabel(const ButtonLabel& help);
 185
 186     /**
 187         Sets the message shown by the dialog.
 188
 189         @since 2.9.0
 190     */
 191     virtual void SetMessage(const wxString& message);
 192
 193     /**
 194         Overrides the default labels of the OK and Cancel buttons.
 195
 196         Please see the remarks in SetYesNoLabels() documentation.
 197
 198         @since 2.9.0
 199     */
 200     virtual bool SetOKCancelLabels(const ButtonLabel& ok,
 201                                    const ButtonLabel& cancel);
 202
 203     /**
 204         Overrides the default label of the OK button.
 205
 206         Please see the remarks in SetYesNoLabels() documentation.
 207
 208         @since 2.9.0
 209     */
 210     virtual bool SetOKLabel(const ButtonLabel& ok);
 211
 212     /**
 213         Overrides the default labels of the Yes, No and Cancel buttons.
 214
 215         Please see the remarks in SetYesNoLabels() documentation.
 216
 217         @since 2.9.0
 218     */
 219     virtual bool SetYesNoCancelLabels(const ButtonLabel& yes,
 220                                       const ButtonLabel& no,
 221                                       const ButtonLabel& cancel);
 222
 223     /**
 224         Overrides the default labels of the Yes and No buttons.
 225
 226         The arguments of this function can be either strings or one of the
 227         standard identifiers, such as @c wxID_APPLY or @c wxID_OPEN. Notice
 228         that even if the label is specified as an identifier, the return value
 229         of the dialog ShowModal() method still remains one of @c wxID_OK, @c
 230         wxID_CANCEL, @c wxID_YES or @c wxID_NO values, i.e. this identifier
 231         changes only the label appearance but not the return code generated by
 232         the button. It is possible to mix stock identifiers and string labels
 233         in the same function call, for example:
 234         @code
 235         wxMessageDialog dlg(...);
 236         dlg.SetYesNoLabels(wxID_SAVE, _("&Don't save"));
 237         @endcode
 238
 239         Also notice that this function is not currently available on all
 240         platforms (although as of wxWidgets 2.9.0 it is implemented in all
 241         major ports), so it may return @false to indicate that the labels
 242         couldn't be changed. If it returns @true, the labels were set
 243         successfully.
 244
 245         Typically, if the function was used successfully, the main dialog
 246         message may need to be changed, e.g.:
 247         @code
 248         wxMessageDialog dlg(...);
 249         if ( dlg.SetYesNoLabels(_("&Quit"), _("&Don't quit")) )
 250             dlg.SetMessage(_("What do you want to do?"));
 251         else // buttons have standard "Yes"/"No" values, so rephrase the question
 252             dlg.SetMessage(_("Do you really want to quit?"));
 253         @endcode
 254
 255         @since 2.9.0
 256     */
 257     virtual bool SetYesNoLabels(const ButtonLabel& yes, const ButtonLabel& no);
 258
 259     /**
 260         Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES,
 261         wxID_NO or wxID_HELP.
 262
 263         Notice that this method returns the identifier of the button which was
 264         clicked unlike wxMessageBox() function.
 265     */
 266     virtual int ShowModal();
 267
 268
 269     wxString GetCaption() const;
 270     wxString GetMessage() const;
 271     wxString GetExtendedMessage() const;
 272     long GetMessageDialogStyle() const;
 273     bool HasCustomLabels() const;
 274     wxString GetYesLabel() const;
 275     wxString GetNoLabel() const;
 276     wxString GetOKLabel() const;
 277     wxString GetCancelLabel() const;
 278     wxString GetHelpLabel() const;
 279     long GetEffectiveIcon() const;
 280
 281 };
 282
 283
 284
 285 // ============================================================================
 286 // Global functions/macros
 287 // ============================================================================
 288
 289 /** @addtogroup group_funcmacro_dialog */
 290 //@{
 291
 292 /**
 293     Show a general purpose message dialog.
 294
 295     This is a convenient function which is usually used instead of using
 296     wxMessageDialog directly. Notice however that some of the features, such as
 297     extended text and custom labels for the message box buttons, are not
 298     provided by this function but only by wxMessageDialog.
 299
 300     The return value is one of: @c wxYES, @c wxNO, @c wxCANCEL, @c wxOK or @c
 301     wxHELP (notice that this return value is @b different from the return value
 302     of wxMessageDialog::ShowModal()).
 303
 304     For example:
 305     @code
 306     int answer = wxMessageBox("Quit program?", "Confirm",
 307                               wxYES_NO | wxCANCEL, main_frame);
 308     if (answer == wxYES)
 309         main_frame->Close();
 310     @endcode
 311
 312     @a message may contain newline characters, in which case the message will
 313     be split into separate lines, to cater for large messages.
 314
 315     @param message
 316         Message to show in the dialog.
 317     @param caption
 318         The dialog title.
 319     @param parent
 320         Parent window.
 321     @param style
 322         Combination of style flags described in wxMessageDialog documentation.
 323     @param x
 324         Horizontal dialog position (ignored under MSW). Use ::wxDefaultCoord
 325         for @a x and @a y to let the system position the window.
 326     @param y
 327         Vertical dialog position (ignored under MSW).
 328
 329     @header{wx/msgdlg.h}
 330 */
 331 int wxMessageBox(const wxString& message,
 332                  const wxString& caption = wxMessageBoxCaptionStr,
 333                  int style = wxOK | wxCENTRE,
 334                  wxWindow* parent = NULL,
 335                  int x = wxDefaultCoord,
 336                  int y = wxDefaultCoord);
 337
 338 //@}
 339