interface/msgdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msgdlg.h
   3 // Purpose:     interface of wxMessageDialog
   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     @see @ref overview_wxmessagedialogoverview "wxMessageDialog overview"
  20 */
  21 class wxMessageDialog : public wxDialog
  22 {
  23 public:
  24     /**
  25         Constructor specifying the message box properties.
  26
  27         Use ShowModal() to show the dialog.
  28
  29         @a style may be a bit list of the following identifiers:
  30
  31         @beginStyleTable
  32         @style{wxOK}
  33             Puts an Ok button in the message box. May be combined with @c
  34             wxCANCEL.
  35         @style{wxCANCEL}
  36             Puts a Cancel button in the message box. Must be combined with
  37             either @c wxOK or @c wxYES_NO.
  38         @style{wxYES_NO}
  39             Puts Yes and No buttons in the message box. May be combined with
  40             @c wxCANCEL.
  41         @style{wxNO_DEFAULT}
  42             Makes the "No" button default, can only be used with @c wxYES_NO.
  43         @style{wxYES_DEFAULT}
  44             Makes the "Yes" button default, this is the default behaviour and
  45             this flag exists solely for symmetry with @c wxNO_DEFAULT.
  46         @style{wxICON_EXCLAMATION}
  47             Displays an exclamation mark symbol.
  48         @style{wxICON_ERROR}
  49             Displays an error symbol.
  50         @style{wxICON_HAND}
  51             Displays an error symbol, this is a MSW-inspired synonym for @c
  52             wxICON_ERROR.
  53         @style{wxICON_QUESTION}
  54             Displays a question mark symbol. This icon is automatically used
  55             with @c wxYES_NO so it's usually unnecessary to specify it
  56             explicitly.
  57         @style{wxICON_INFORMATION}
  58             Displays an information symbol. This icon is used by default if @c
  59             wxYES_NO is not given so it is usually unnecessary to specify it
  60             explicitly.
  61         @style{wxSTAY_ON_TOP}
  62             Makes the message box stay on top of all other windows (currently
  63             implemented only under MSW).
  64         @endStyleTable
  65
  66         @param parent
  67             Parent window.
  68         @param message
  69             Message to show in the dialog.
  70         @param caption
  71             The dialog title.
  72         @param style
  73             Combination of style flags described above.
  74         @param pos
  75             Dialog position (ignored under MSW).
  76     */
  77     wxMessageDialog(wxWindow* parent, const wxString& message,
  78                     const wxString& caption = "Message box",
  79                     long style = wxOK | wxCANCEL,
  80                     const wxPoint& pos = wxDefaultPosition);
  81
  82     /**
  83         Sets the extended message for the dialog: this message is usually an
  84         extension of the short message specified in the constructor or set with
  85         SetMessage().
  86
  87         If it is set, the main message appears highlighted -- if supported --
  88         and this message appears beneath it in normal font. On the platforms
  89         which don't support extended messages, it is simply appended to the
  90         normal message with a new line separating them.
  91     */
  92     void SetExtendedMessage(const wxString extendedMessage);
  93
  94     /**
  95         Sets the message shown by the dialog.
  96     */
  97     void SetMessage(const wxString msg);
  98
  99     /**
 100         Overrides the default labels of the OK and Cancel buttons.
 101
 102         Please see the remarks in SetYesNoLabels() documentation.
 103     */
 104     bool SetOKCancelLabels(const wxString ok, const wxString cancel);
 105
 106     /**
 107         Overrides the default label of the OK button.
 108
 109         Please see the remarks in SetYesNoLabels() documentation.
 110     */
 111     bool SetOKLabel(const wxString ok);
 112
 113     /**
 114         Overrides the default labels of the Yes, No and Cancel buttons.
 115
 116         Please see the remarks in SetYesNoLabels() documentation.
 117     */
 118     bool SetYesNoCancelLabels(const wxString yes, const wxString no,
 119                               const wxString cancel);
 120
 121     /**
 122         Overrides the default labels of the Yes and No buttons.
 123
 124         Notice that this function is not currently available on all platforms,
 125         so it may return @false to indicate that the labels couldn't be
 126         changed. If it returns @true (currently only under wxMac), the labels
 127         were set successfully. Typically, if the function was used
 128         successfully, the main dialog message may need to be changed, e.g.:
 129         @code
 130         wxMessageDialog dlg(...);
 131         if ( dlg.SetYesNoLabels(_("&Quit"), _("&Don't quit")) )
 132             dlg.SetMessage(_("What do you want to do?"));
 133         else // buttons have standard "Yes"/"No" values, so rephrase the question
 134             dlg.SetMessage(_("Do you really want to quit?"));
 135         @endcode
 136     */
 137     bool SetYesNoLabels(const wxString yes, const wxString no);
 138
 139     /**
 140         Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES,
 141         wxID_NO.
 142
 143         Notice that this method returns the identifier of the button which was
 144         clicked unlike wxMessageBox() function.
 145     */
 146     int ShowModal();
 147 };
 148
 149
 150
 151 // ============================================================================
 152 // Global functions/macros
 153 // ============================================================================
 154
 155 /** @ingroup group_funcmacro_dialog */
 156 //@{
 157
 158 /**
 159     Show a general purpose message dialog.
 160
 161     This is a convenient function which is usually used instead of using
 162     wxMessageDialog directly. Notice however that some of the features, such as
 163     extended text and custom labels for the message box buttons, are not
 164     provided by this function but only by wxMessageDialog.
 165
 166     The return value is one of: @c wxYES, @c wxNO, @c wxCANCEL or @c wxOK
 167     (notice that this return value is @b different from the return value of
 168     wxMessageDialog::ShowModal()).
 169
 170     For example:
 171     @code
 172     int answer = wxMessageBox("Quit program?", "Confirm",
 173                               wxYES_NO | wxCANCEL, main_frame);
 174     if (answer == wxYES)
 175         main_frame->Close();
 176     @endcode
 177
 178     @a message may contain newline characters, in which case the message will
 179     be split into separate lines, to cater for large messages.
 180
 181     @param message
 182         Message to show in the dialog.
 183     @param caption
 184         The dialog title.
 185     @param parent
 186         Parent window.
 187     @param style
 188         Combination of style flags described in wxMessageDialog documentation.
 189     @param x
 190         Horizontal dialog position (ignored under MSW). Use @c wxDefaultCoord
 191         for @a x and @a y to let the system position the window.
 192     @param y
 193         Vertical dialog position (ignored under MSW).
 194     @header{wx/msgdlg.h}
 195 */
 196 int wxMessageBox(const wxString& message,
 197                  const wxString& caption = "Message",
 198                  int style = wxOK,
 199                  wxWindow* parent = NULL,
 200                  int x = wxDefaultCoord,
 201                  int y = wxDefaultCoord);
 202
 203 //@}
 204