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