]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/msgdlg.h
Add missing interface items for Phoenix
[wxWidgets.git] / 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