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