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