]> git.saurik.com Git - wxWidgets.git/blob - interface/dialog.h
Update Unicode overview to 3.0
[wxWidgets.git] / interface / dialog.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: dialog.h
3 // Purpose: interface of wxDialog
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxDialog
11 @wxheader{dialog.h}
12
13 A dialog box is a window with a title bar and sometimes a system menu, which
14 can be moved around the screen. It can contain controls and other windows and
15 is often used to allow the user to make some choice or to answer a question.
16
17 Dialogs can be made scrollable, automatically: please see @ref
18 overview_autoscrollingdialogs "Automatic scrolling dialogs" for further details.
19
20 @beginStyleTable
21 @style{wxCAPTION}
22 Puts a caption on the dialog box.
23 @style{wxDEFAULT_DIALOG_STYLE}
24 Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and
25 wxSYSTEM_MENU (the last one is not used under Unix)
26 @style{wxRESIZE_BORDER}
27 Display a resizeable frame around the window.
28 @style{wxSYSTEM_MENU}
29 Display a system menu.
30 @style{wxCLOSE_BOX}
31 Displays a close box on the frame.
32 @style{wxMAXIMIZE_BOX}
33 Displays a maximize box on the dialog.
34 @style{wxMINIMIZE_BOX}
35 Displays a minimize box on the dialog.
36 @style{wxTHICK_FRAME}
37 Display a thick frame around the window.
38 @style{wxSTAY_ON_TOP}
39 The dialog stays on top of all other windows.
40 @style{wxNO_3D}
41 Under Windows, specifies that the child controls should not have 3D
42 borders unless specified in the control.
43 @style{wxDIALOG_NO_PARENT}
44 By default, a dialog created with a @NULL parent window will be
45 given the application's top level window as parent. Use this style
46 to prevent this from happening and create an orphan dialog. This is
47 not recommended for modal dialogs.
48 @style{wxDIALOG_EX_CONTEXTHELP}
49 Under Windows, puts a query button on the caption. When pressed,
50 Windows will go into a context-sensitive help mode and wxWidgets
51 will send a wxEVT_HELP event if the user clicked on an application
52 window. Note that this is an extended style and must be set by
53 calling SetExtraStyle before Create is called (two-step
54 construction).
55 @style{wxDIALOG_EX_METAL}
56 On Mac OS X, frames with this style will be shown with a metallic
57 look. This is an extra style.
58 @endStyleTable
59
60 @library{wxcore}
61 @category{cmndlg}
62
63 @see @ref overview_wxdialogoverview, wxFrame, @ref overview_validatoroverview
64 "Validator overview"
65 */
66 class wxDialog : public wxTopLevelWindow
67 {
68 public:
69 //@{
70 /**
71 Constructor.
72
73 @param parent
74 Can be @NULL, a frame or another dialog box.
75 @param id
76 An identifier for the dialog. A value of -1 is taken to mean a default.
77 @param title
78 The title of the dialog.
79 @param pos
80 The dialog position. The value wxDefaultPosition indicates a default position,
81 chosen by
82 either the windowing system or wxWidgets, depending on platform.
83 @param size
84 The dialog size. The value wxDefaultSize indicates a default size, chosen by
85 either the windowing system or wxWidgets, depending on platform.
86 @param style
87 The window style. See wxDialog.
88 @param name
89 Used to associate a name with the window,
90 allowing the application user to set Motif resource values for
91 individual dialog boxes.
92
93 @see Create()
94 */
95 wxDialog();
96 wxDialog(wxWindow* parent, wxWindowID id,
97 const wxString& title,
98 const wxPoint& pos = wxDefaultPosition,
99 const wxSize& size = wxDefaultSize,
100 long style = wxDEFAULT_DIALOG_STYLE,
101 const wxString& name = "dialogBox");
102 //@}
103
104 /**
105 Destructor. Deletes any child windows before deleting the physical window.
106 */
107 ~wxDialog();
108
109 /**
110 Adds an identifier to be regarded as a main button for the non-scrolling area
111 of a dialog.
112 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
113 more on layout adaptation.
114 */
115 void AddMainButtonId(wxWindowID id);
116
117 /**
118 Returns @true if this dialog can and should perform layout adaptation using
119 DoLayoutAdaptation(), usually if
120 the dialog is too large to fit on the display.
121 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
122 more on layout adaptation.
123 */
124 bool CanDoLayoutAdapation();
125
126 /**
127 Centres the dialog box on the display.
128
129 @param direction
130 May be wxHORIZONTAL, wxVERTICAL or wxBOTH.
131 */
132 void Centre(int direction = wxBOTH);
133
134 /**
135 Used for two-step dialog box construction. See wxDialog()
136 for details.
137 */
138 bool Create(wxWindow* parent, wxWindowID id,
139 const wxString& title,
140 const wxPoint& pos = wxDefaultPosition,
141 const wxSize& size = wxDefaultSize,
142 long style = wxDEFAULT_DIALOG_STYLE,
143 const wxString& name = "dialogBox");
144
145 /**
146 Creates a sizer with standard buttons. @a flags is a bit list
147 of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE,
148 wxHELP, wxNO_DEFAULT.
149 The sizer lays out the buttons in a manner appropriate to the platform.
150 This function uses CreateStdDialogButtonSizer()
151 internally for most platforms but doesn't create the sizer at all for the
152 platforms with hardware buttons (such as smartphones) for which it sets up the
153 hardware buttons appropriately and returns @NULL, so don't forget to test that
154 the return value is valid before using it.
155 */
156 wxSizer* CreateButtonSizer(long flags);
157
158 /**
159 Creates a sizer with standard buttons using
160 CreateButtonSizer() separated from the rest
161 of the dialog contents by a horizontal wxStaticLine.
162 Please notice that just like CreateButtonSizer() this function may return @c
163 @NULL
164 if no buttons were created.
165 */
166 wxSizer* CreateSeparatedButtonSizer(long flags);
167
168 /**
169 Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a bit list
170 of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE,
171 wxHELP, wxNO_DEFAULT.
172 The sizer lays out the buttons in a manner appropriate to the platform.
173 */
174 wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags);
175
176 /**
177 Performs layout adaptation, usually if the dialog is too large to fit on the
178 display.
179 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
180 more on layout adaptation.
181 */
182 bool DoLayoutAdapation();
183
184 /**
185 This function is called when the titlebar OK button is pressed (PocketPC only).
186 A command event for the identifier returned by GetAffirmativeId is sent by
187 default. You can override this function. If the function returns @false,
188 wxWidgets
189 will call Close() for the dialog.
190 */
191 virtual bool DoOK();
192
193 /**
194 A static function enabling or disabling layout adaptation for all dialogs.
195 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
196 more on layout adaptation.
197 */
198 static void EnableLayoutAdaptation(bool enable);
199
200 /**
201 Ends a modal dialog, passing a value to be returned from the ShowModal()
202 invocation.
203
204 @param retCode
205 The value that should be returned by ShowModal.
206
207 @see ShowModal(), GetReturnCode(), SetReturnCode()
208 */
209 void EndModal(int retCode);
210
211 /**
212 Gets the identifier of the button which works like standard OK button in this
213 dialog.
214
215 @see SetAffirmativeId()
216 */
217 int GetAffirmativeId() const;
218
219 /**
220 Override this to return a window containing the main content of the dialog.
221 This is
222 particularly useful when the dialog implements pages, such as
223 wxPropertySheetDialog,
224 and allows the @ref overview_wxdialogoverview "layout adaptation code" to know
225 that only the pages need to be made scrollable.
226 */
227 wxWindow* GetContentWindow() const;
228
229 /**
230 Gets the identifier of the button to map presses of @c ESC
231 button to.
232
233 @see SetEscapeId()
234 */
235 int GetEscapeId() const;
236
237 /**
238 Returns @true if the dialog has been adapted, usually by making it scrollable
239 to work with a small display.
240 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
241 more on layout adaptation.
242 */
243 bool GetLayoutAdaptationDone() const;
244
245 /**
246 Gets a value representing the aggressiveness of search for buttons and sizers
247 to be in the non-scrolling part of a layout-adapted dialog.
248 Zero switches off adaptation, and 3 allows search for standard buttons anywhere
249 in the dialog.
250 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
251 more on layout adaptation.
252 */
253 int GetLayoutAdaptationLevel();
254
255 /**
256 Gets the adaptation mode, overriding the global adaptation flag.
257 See also SetLayoutAdaptationMode() and @ref overview_autoscrollingdialogs
258 "Automatic scrolling dialogs".
259 */
260 wxDialogLayoutAdaptationMode GetLayoutAdaptationMode() const;
261
262 /**
263 A static function getting the current layout adapter object.
264 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
265 more on layout adaptation.
266 */
267 static wxDialogLayoutAdapter* GetLayoutAdapter();
268
269 /**
270 Returns an array of identifiers to be regarded as the main buttons for the
271 non-scrolling area of a dialog.
272 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
273 more on layout adaptation.
274 */
275 wxArrayInt GetMainButtonIds();
276
277 /**
278 Gets the return code for this window.
279
280 @remarks A return code is normally associated with a modal dialog, where
281 ShowModal() returns a code to the application.
282
283 @see SetReturnCode(), ShowModal(), EndModal()
284 */
285 int GetReturnCode();
286
287 /**
288 On PocketPC, a dialog is automatically provided with an empty toolbar.
289 GetToolBar
290 allows you to access the toolbar and add tools to it. Removing tools and adding
291 arbitrary controls are not currently supported.
292 This function is not available on any other platform.
293 */
294 wxToolBar* GetToolBar() const;
295
296 /**
297 Iconizes or restores the dialog. Windows only.
298
299 @param iconize
300 If @true, iconizes the dialog box; if @false, shows and restores it.
301
302 @remarks Note that in Windows, iconization has no effect since dialog
303 boxes cannot be iconized. However, applications may
304 need to explicitly restore dialog boxes under Motif
305 which have user-iconizable frames, and under Windows
306 calling Iconize(@false) will bring the window to the
307 front, as does Show(@true).
308 */
309 void Iconize(bool iconize);
310
311 /**
312 Returns @true if the dialog box is iconized. Windows only.
313
314 @remarks Always returns @false under Windows since dialogs cannot be
315 iconized.
316 */
317 bool IsIconized() const;
318
319 /**
320 A static function returning @true if layout adaptation is enabled for all
321 dialogs.
322 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
323 more on layout adaptation.
324 */
325 static bool IsLayoutAdaptationEnabled();
326
327 /**
328 Returns @true if @a id is in the array of identifiers to be regarded as the
329 main buttons for the non-scrolling area of a dialog.
330 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
331 more on layout adaptation.
332 */
333 bool IsMainButton(wxWindowID& id) const;
334
335 /**
336 Returns @true if the dialog box is modal, @false otherwise.
337 */
338 bool IsModal() const;
339
340 /**
341 The default handler for wxEVT_SYS_COLOUR_CHANGED.
342
343 @param event
344 The colour change event.
345
346 @remarks Changes the dialog's colour to conform to the current settings
347 (Windows only). Add an event table entry for your
348 dialog class if you wish the behaviour to be different
349 (such as keeping a user-defined background colour). If
350 you do override this function, call wxEvent::Skip to
351 propagate the notification to child windows and
352 controls.
353
354 @see wxSysColourChangedEvent
355 */
356 void OnSysColourChanged(wxSysColourChangedEvent& event);
357
358 /**
359 Sets the identifier to be used as OK button. When the button with this
360 identifier is pressed, the dialog calls wxWindow::Validate
361 and wxWindow::TransferDataFromWindow
362 and, if they both return @true, closes the dialog with @c wxID_OK return
363 code.
364 Also, when the user presses a hardware OK button on the devices having one or
365 the special OK button in the PocketPC title bar, an event with this id is
366 generated.
367 By default, the affirmative id is wxID_OK.
368
369 @see GetAffirmativeId(), SetEscapeId()
370 */
371 void SetAffirmativeId(int id);
372
373 /**
374 Sets the identifier of the button which should work like the standard
375 @c CANCEL button in this dialog. When the button with this id is
376 clicked, the dialog is closed. Also, when the user presses @c ESC
377 key in the dialog or closes the dialog using the close button in the title bar,
378 this is mapped to the click of the button with the specified id.
379 By default, the escape id is the special value @c wxID_ANY meaning that
380 @c wxID_CANCEL button is used if it's present in the dialog and
381 otherwise the button with GetAffirmativeId()
382 is used. Another special value for @a id is @c wxID_NONE meaning that
383 @c ESC presses should be ignored. If any other value is given, it
384 is interpreted as the id of the button to map the escape key to.
385 */
386 void SetEscapeId(int id);
387
388 /**
389 Sets the icon for this dialog.
390
391 @param icon
392 The icon to associate with this dialog.
393 */
394 void SetIcon(const wxIcon& icon);
395
396 /**
397 Sets the icons for this dialog.
398
399 @param icons
400 The icons to associate with this dialog.
401 */
402 void SetIcons(const wxIconBundle& icons);
403
404 /**
405 Marks the dialog as having been adapted, usually by making it scrollable to
406 work with a small display.
407 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
408 more on layout adaptation.
409 */
410 void SetLayoutAdaptationDone(bool done);
411
412 /**
413 Sets the aggressiveness of search for buttons and sizers to be in the
414 non-scrolling part of a layout-adapted dialog.
415 Zero switches off adaptation, and 3 allows search for standard buttons anywhere
416 in the dialog.
417 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
418 more on layout adaptation.
419 */
420 void SetLayoutAdaptationLevel(int level);
421
422 /**
423 Sets the adaptation mode, overriding the global adaptation flag. @a mode may be
424 one of the following values:
425
426 See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for
427 more on layout adaptation.
428 */
429 void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode);
430
431 /**
432 A static function for setting the current layout adapter object, returning the
433 old adapter. If you call this, you should
434 delete the old adapter object.
435 See also wxDialogLayoutAdapter and @ref overview_autoscrollingdialogs
436 "Automatic scrolling dialogs".
437 */
438 static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter);
439
440 /**
441 @note This function is deprecated and doesn't work for all ports, just use
442 ShowModal() to show a modal dialog instead.
443 Allows the programmer to specify whether the dialog box is modal (Show() blocks
444 control
445 until the dialog is hidden) or modeless (control returns immediately).
446
447 @param flag
448 If @true, the dialog will be modal, otherwise it will be modeless.
449 */
450 void SetModal(bool flag);
451
452 /**
453 Sets the return code for this window.
454
455 @param retCode
456 The integer return code, usually a control identifier.
457
458 @remarks A return code is normally associated with a modal dialog, where
459 ShowModal() returns a code to the application.
460 The function EndModal() calls SetReturnCode.
461
462 @see GetReturnCode(), ShowModal(), EndModal()
463 */
464 void SetReturnCode(int retCode);
465
466 /**
467 Hides or shows the dialog.
468
469 @param show
470 If @true, the dialog box is shown and brought to the front;
471 otherwise the box is hidden. If @false and the dialog is
472 modal, control is returned to the calling program.
473
474 @remarks The preferred way of dismissing a modal dialog is to use
475 EndModal().
476 */
477 bool Show(bool show);
478
479 /**
480 Shows a modal dialog. Program flow does not return until the dialog has been
481 dismissed with
482 EndModal().
483
484 @returns The return value is the value set with SetReturnCode().
485 */
486 int ShowModal();
487 };
488
489
490
491 /**
492 @class wxDialogLayoutAdapter
493 @wxheader{dialog.h}
494
495 This abstract class is the base for classes that help wxWidgets peform run-time
496 layout adaptation of dialogs. Principally,
497 this is to cater for small displays by making part of the dialog scroll, but
498 the application developer may find other
499 uses for layout adaption.
500
501 By default, there is one instance of wxStandardDialogLayoutAdapter
502 which can perform adaptation for most custom dialogs and dialogs with book
503 controls
504 such as wxPropertySheetDialog.
505
506 @library{wxcore}
507 @category{FIXME}
508
509 @see @ref overview_autoscrollingdialogs "Automatic scrolling dialogs"
510 */
511 class wxDialogLayoutAdapter
512 {
513 public:
514 /**
515 Default constructor.
516 */
517 wxDialogLayoutAdapter();
518
519 /**
520 Override this to returns @true if adaptation can and should be done.
521 */
522 bool CanDoLayoutAdaptation(wxDialog* dialog);
523
524 /**
525 Override this to perform layout adaptation, such as making parts of the dialog
526 scroll and resizing the dialog to fit the display.
527 Normally this function will be called just before the dialog is shown.
528 */
529 bool DoLayoutAdaptation(wxDialog* dialog);
530 };
531