1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDialog
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 Modes used for wxDialog::SetLayoutAdaptationMode().
12 enum wxDialogLayoutAdaptationMode
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.
19 #define wxDIALOG_NO_PARENT 0x00000020 ///< Don't make owned by apps top window
21 #define wxDEFAULT_DIALOG_STYLE (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX)
24 #define wxDIALOG_ADAPTATION_NONE 0 ///< Don't do any layout adaptation
25 #define wxDIALOG_ADAPTATION_STANDARD_SIZER 1 ///< Only look for wxStdDialogButtonSizer for non-scrolling part
26 #define wxDIALOG_ADAPTATION_ANY_SIZER 2 ///< Also look for any suitable sizer for non-scrolling part
27 #define wxDIALOG_ADAPTATION_LOOSE_BUTTONS 3 ///< Also look for 'loose' standard buttons for non-scrolling part
32 A dialog box is a window with a title bar and sometimes a system menu,
33 which can be moved around the screen. It can contain controls and other
34 windows and is often used to allow the user to make some choice or to
37 Dialogs can be made scrollable, automatically, for computers with low
38 resolution screens: please see @ref overview_dialog_autoscrolling for
41 Dialogs usually contains either a single button allowing to close the
42 dialog or two buttons, one accepting the changes and the other one
43 discarding them (such button, if present, is automatically activated if the
44 user presses the "Esc" key). By default, buttons with the standard wxID_OK
45 and wxID_CANCEL identifiers behave as expected. Starting with wxWidgets 2.7
46 it is also possible to use a button with a different identifier instead,
47 see SetAffirmativeId() and SetEscapeId().
49 Also notice that the CreateButtonSizer() should be used to create the
50 buttons appropriate for the current platform and positioned correctly
51 (including their order which is platform-dependent).
53 @section dialog_modal Modal and Modeless
55 There are two kinds of dialog, modal and modeless. A modal dialog blocks
56 program flow and user input on other windows until it is dismissed, whereas
57 a modeless dialog behaves more like a frame in that program flow continues,
58 and input in other windows is still possible. To show a modal dialog you
59 should use the ShowModal() method while to show a dialog modelessly you
60 simply use Show(), just as with frames.
62 Note that the modal dialog is one of the very few examples of
63 wxWindow-derived objects which may be created on the stack and not on the
64 heap. In other words, while most windows would be created like this:
69 MyAskDialog *dlg = new MyAskDialog(...);
70 if ( dlg->ShowModal() == wxID_OK )
72 //else: dialog was cancelled or some another button pressed
78 You can achieve the same result with dialogs by using simpler code:
84 if ( dlg.ShowModal() == wxID_OK )
87 // no need to call Destroy() here
91 An application can define a wxCloseEvent handler for the dialog to respond
92 to system close events.
96 Puts a caption on the dialog box.
97 @style{wxDEFAULT_DIALOG_STYLE}
98 Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and
99 wxSYSTEM_MENU (the last one is not used under Unix).
100 @style{wxRESIZE_BORDER}
101 Display a resizable frame around the window.
102 @style{wxSYSTEM_MENU}
103 Display a system menu.
105 Displays a close box on the frame.
106 @style{wxMAXIMIZE_BOX}
107 Displays a maximize box on the dialog.
108 @style{wxMINIMIZE_BOX}
109 Displays a minimize box on the dialog.
110 @style{wxTHICK_FRAME}
111 Display a thick frame around the window.
112 @style{wxSTAY_ON_TOP}
113 The dialog stays on top of all other windows.
115 This style is obsolete and doesn't do anything any more, don't use
117 @style{wxDIALOG_NO_PARENT}
118 By default, a dialog created with a @NULL parent window will be
119 given the @ref wxApp::GetTopWindow() "application's top level window"
120 as parent. Use this style to prevent this from happening and create
121 an orphan dialog. This is not recommended for modal dialogs.
122 @style{wxDIALOG_EX_CONTEXTHELP}
123 Under Windows, puts a query button on the caption. When pressed,
124 Windows will go into a context-sensitive help mode and wxWidgets
125 will send a @c wxEVT_HELP event if the user clicked on an application
126 window. Note that this is an extended style and must be set by
127 calling SetExtraStyle() before Create is called (two-step
129 @style{wxDIALOG_EX_METAL}
130 On Mac OS X, frames with this style will be shown with a metallic
131 look. This is an extra style.
134 Under Unix or Linux, MWM (the Motif Window Manager) or other window
135 managers recognizing the MHM hints should be running for any of these
136 styles to have an effect.
139 @beginEventEmissionTable{wxCloseEvent}
140 @event{EVT_CLOSE(func)}
141 The dialog is being closed by the user or programmatically (see wxWindow::Close).
142 The user may generate this event clicking the close button
143 (typically the 'X' on the top-right of the title bar) if it's present
144 (see the @c wxCLOSE_BOX style) or by clicking a button with the
145 @c wxID_CANCEL or @c wxID_OK ids.
146 @event{EVT_INIT_DIALOG(func)}
147 Process a @c wxEVT_INIT_DIALOG event. See wxInitDialogEvent.
153 @see @ref overview_dialog, wxFrame, @ref overview_validator
155 class wxDialog
: public wxTopLevelWindow
166 Can be @NULL, a frame or another dialog box.
168 An identifier for the dialog. A value of -1 is taken to mean a
171 The title of the dialog.
173 The dialog position. The value wxDefaultPosition indicates a
174 default position, chosen by either the windowing system or
175 wxWidgets, depending on platform.
177 The dialog size. The value wxDefaultSize indicates a default size,
178 chosen by either the windowing system or wxWidgets, depending on
183 Used to associate a name with the window, allowing the application
184 user to set Motif resource values for individual dialog boxes.
188 wxDialog(wxWindow
* parent
, wxWindowID id
, const wxString
& title
,
189 const wxPoint
& pos
= wxDefaultPosition
,
190 const wxSize
& size
= wxDefaultSize
,
191 long style
= wxDEFAULT_DIALOG_STYLE
,
192 const wxString
& name
= wxDialogNameStr
);
197 Deletes any child windows before deleting the physical window.
199 See @ref overview_windowdeletion for more info.
204 Adds an identifier to be regarded as a main button for the
205 non-scrolling area of a dialog.
207 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
209 void AddMainButtonId(wxWindowID id
);
212 Returns @true if this dialog can and should perform layout adaptation
213 using DoLayoutAdaptation(), usually if the dialog is too large to fit
216 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
218 virtual bool CanDoLayoutAdaptation();
221 Centres the dialog box on the display.
224 May be wxHORIZONTAL, wxVERTICAL or wxBOTH.
226 void Centre(int direction
= wxBOTH
);
229 Used for two-step dialog box construction.
233 bool Create(wxWindow
* parent
, wxWindowID id
, const wxString
& title
,
234 const wxPoint
& pos
= wxDefaultPosition
,
235 const wxSize
& size
= wxDefaultSize
,
236 long style
= wxDEFAULT_DIALOG_STYLE
,
237 const wxString
& name
= wxDialogNameStr
);
240 Creates a sizer with standard buttons. @a flags is a bit list of the
241 following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP,
244 The sizer lays out the buttons in a manner appropriate to the platform.
246 This function uses CreateStdDialogButtonSizer() internally for most
247 platforms but doesn't create the sizer at all for the platforms with
248 hardware buttons (such as smartphones) for which it sets up the
249 hardware buttons appropriately and returns @NULL, so don't forget to
250 test that the return value is valid before using it.
252 wxSizer
* CreateButtonSizer(long flags
);
255 Creates a sizer with standard buttons using CreateButtonSizer()
256 separated from the rest of the dialog contents by a horizontal
259 @note Just like CreateButtonSizer(), this function may return @NULL if
260 no buttons were created.
262 This is a combination of CreateButtonSizer() and
263 CreateSeparatedSizer().
265 wxSizer
* CreateSeparatedButtonSizer(long flags
);
268 Returns the sizer containing the given one with a separating
269 wxStaticLine if necessarily.
271 This function is useful for creating the sizer containing footer-like
272 contents in dialog boxes. It will add a separating static line only if
273 it conforms to the current platform convention (currently it is not
274 added under Mac where the use of static lines for grouping is
275 discouraged and is added elsewhere).
279 @param sizer The sizer to wrap, must be non-@NULL.
280 @return The sizer wrapping the input one or possibly the input sizer
281 itself if no wrapping is necessary.
283 wxSizer
*CreateSeparatedSizer(wxSizer
*sizer
);
286 Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a
287 bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY,
288 wxCLOSE, wxHELP, wxNO_DEFAULT.
290 The sizer lays out the buttons in a manner appropriate to the platform.
292 wxStdDialogButtonSizer
* CreateStdDialogButtonSizer(long flags
);
295 Splits text up at newlines and places the lines into wxStaticText
296 objects in a vertical wxBoxSizer.
298 wxSizer
*CreateTextSizer( const wxString
& message
);
301 Performs layout adaptation, usually if the dialog is too large to fit
304 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
306 virtual bool DoLayoutAdaptation();
309 This function is called when the titlebar OK button is pressed
310 (PocketPC only). A command event for the identifier returned by
311 GetAffirmativeId() is sent by default. You can override this function.
312 If the function returns @false, wxWidgets will call Close() for the
320 A static function enabling or disabling layout adaptation for all
323 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
325 static void EnableLayoutAdaptation(bool enable
);
328 Ends a modal dialog, passing a value to be returned from the
329 ShowModal() invocation.
332 The value that should be returned by ShowModal.
334 @see ShowModal(), GetReturnCode(), SetReturnCode()
336 virtual void EndModal(int retCode
);
339 Gets the identifier of the button which works like standard OK button
342 @see SetAffirmativeId()
344 int GetAffirmativeId() const;
347 Override this to return a window containing the main content of the
348 dialog. This is particularly useful when the dialog implements pages,
349 such as wxPropertySheetDialog, and allows the
350 @ref overview_dialog "layout adaptation code" to know that only the
351 pages need to be made scrollable.
353 virtual wxWindow
* GetContentWindow() const;
356 Gets the identifier of the button to map presses of @c ESC button to.
360 int GetEscapeId() const;
363 Returns @true if the dialog has been adapted, usually by making it
364 scrollable to work with a small display.
366 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
368 bool GetLayoutAdaptationDone() const;
371 Gets a value representing the aggressiveness of search for buttons and
372 sizers to be in the non-scrolling part of a layout-adapted dialog. Zero
373 switches off adaptation, and 3 allows search for standard buttons
374 anywhere in the dialog.
376 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
378 int GetLayoutAdaptationLevel() const;
381 Gets the adaptation mode, overriding the global adaptation flag.
383 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
385 wxDialogLayoutAdaptationMode
GetLayoutAdaptationMode() const;
388 A static function getting the current layout adapter object.
390 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
392 static wxDialogLayoutAdapter
* GetLayoutAdapter();
395 Returns an array of identifiers to be regarded as the main buttons for
396 the non-scrolling area of a dialog.
398 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
400 wxArrayInt
& GetMainButtonIds();
403 Gets the return code for this window.
405 @remarks A return code is normally associated with a modal dialog,
406 where ShowModal() returns a code to the application.
408 @see SetReturnCode(), ShowModal(), EndModal()
410 int GetReturnCode() const;
413 On PocketPC, a dialog is automatically provided with an empty toolbar.
414 This function allows you to access the toolbar and add tools to it.
415 Removing tools and adding arbitrary controls are not currently
418 This function is not available on any other platform.
422 wxToolBar
* GetToolBar() const;
425 Iconizes or restores the dialog. Windows only.
428 If @true, iconizes the dialog box; if @false, shows and restores it.
430 @remarks Note that in Windows, iconization has no effect since dialog
431 boxes cannot be iconized. However, applications may need to
432 explicitly restore dialog boxes under Motif which have
433 user-iconizable frames, and under Windows calling
434 Iconize(@false) will bring the window to the front, as does
437 virtual void Iconize(bool iconize
= true);
440 Returns @true if the dialog box is iconized. Windows only.
442 @remarks Always returns @false under Windows since dialogs cannot be
445 virtual bool IsIconized() const;
448 A static function returning @true if layout adaptation is enabled for
451 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
453 static bool IsLayoutAdaptationEnabled();
456 Returns @true if @a id is in the array of identifiers to be regarded as
457 the main buttons for the non-scrolling area of a dialog.
461 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
463 bool IsMainButtonId(wxWindowID id
) const;
466 Returns @true if the dialog box is modal, @false otherwise.
468 virtual bool IsModal() const;
471 Sets the identifier to be used as OK button. When the button with this
472 identifier is pressed, the dialog calls wxWindow::Validate() and
473 wxWindow::TransferDataFromWindow() and, if they both return @true,
474 closes the dialog with the affirmative id return code.
476 Also, when the user presses a hardware OK button on the devices having
477 one or the special OK button in the PocketPC title bar, an event with
478 this id is generated.
480 By default, the affirmative id is wxID_OK.
482 @see GetAffirmativeId(), SetEscapeId()
484 void SetAffirmativeId(int id
);
487 Sets the identifier of the button which should work like the standard
488 "Cancel" button in this dialog. When the button with this id is
489 clicked, the dialog is closed. Also, when the user presses @c ESC key
490 in the dialog or closes the dialog using the close button in the title
491 bar, this is mapped to the click of the button with the specified id.
493 By default, the escape id is the special value wxID_ANY meaning that
494 wxID_CANCEL button is used if it's present in the dialog and otherwise
495 the button with GetAffirmativeId() is used. Another special value for
496 @a id is wxID_NONE meaning that @c ESC presses should be ignored. If
497 any other value is given, it is interpreted as the id of the button to
498 map the escape key to.
500 void SetEscapeId(int id
);
503 Sets the icon for this dialog.
506 The icon to associate with this dialog.
510 void SetIcon(const wxIcon
& icon
);
513 Sets the icons for this dialog.
516 The icons to associate with this dialog.
520 void SetIcons(const wxIconBundle
& icons
);
523 Marks the dialog as having been adapted, usually by making it
524 scrollable to work with a small display.
526 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
528 void SetLayoutAdaptationDone(bool done
);
531 Sets the aggressiveness of search for buttons and sizers to be in the
532 non-scrolling part of a layout-adapted dialog. Zero switches off
533 adaptation, and 3 allows search for standard buttons anywhere in the
536 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
538 void SetLayoutAdaptationLevel(int level
);
541 Sets the adaptation mode, overriding the global adaptation flag.
543 @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling
544 (for more on layout adaptation)
546 void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode
);
549 A static function for setting the current layout adapter object,
550 returning the old adapter. If you call this, you should delete the old
553 @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling
555 static wxDialogLayoutAdapter
* SetLayoutAdapter(wxDialogLayoutAdapter
* adapter
);
558 @deprecated This function doesn't work for all ports, just use
559 ShowModal() to show a modal dialog instead.
561 Allows the programmer to specify whether the dialog box is modal
562 (Show() blocks control until the dialog is hidden) or modeless (control
563 returns immediately).
566 If @true, the dialog will be modal, otherwise it will be modeless.
568 void SetModal(bool flag
);
571 Sets the return code for this window.
573 A return code is normally associated with a modal dialog, where
574 ShowModal() returns a code to the application. The function EndModal()
575 calls SetReturnCode().
578 The integer return code, usually a control identifier.
580 @see GetReturnCode(), ShowModal(), EndModal()
582 void SetReturnCode(int retCode
);
585 Hides or shows the dialog. The preferred way of dismissing a modal
586 dialog is to use EndModal().
589 If @true, the dialog box is shown and brought to the front,
590 otherwise the box is hidden. If @false and the dialog is modal,
591 control is returned to the calling program.
593 virtual bool Show(bool show
= 1);
596 Shows an application-modal dialog.
598 Program flow does not return until the dialog has been dismissed with
601 Notice that it is possible to call ShowModal() for a dialog which had
602 been previously shown with Show(), this allows to make an existing
603 modeless dialog modal. However ShowModal() can't be called twice
604 without intervening EndModal() calls.
606 Note that this function creates a temporary event loop which takes
607 precedence over the application's main event loop (see wxEventLoopBase)
608 and which is destroyed when the dialog is dismissed.
609 This also results in a call to wxApp::ProcessPendingEvents().
611 @return The value set with SetReturnCode().
613 @see ShowWindowModal(), EndModal(), GetReturnCode(), SetReturnCode()
615 virtual int ShowModal();
618 Shows a dialog modal to the parent top level window only.
620 Unlike ShowModal(), dialogs shown with this function only prevent the
621 user from interacting with their parent frame only but not with the
622 rest of the application. They also don't block the program execution
623 but instead return immediately, as Show(), and generate a
624 wxEVT_WINDOW_MODAL_DIALOG_CLOSED event later when the dialog is closed.
626 Currently this function is only fully implemented in wxOSX ports, under
627 the other platforms it behaves like ShowModal() (but also sends the
628 above mentioned event).
632 void ShowWindowModal();
638 @class wxDialogLayoutAdapter
640 This abstract class is the base for classes that help wxWidgets perform
641 run-time layout adaptation of dialogs. Principally, this is to cater for
642 small displays by making part of the dialog scroll, but the application
643 developer may find other uses for layout adaption.
645 By default, there is one instance of wxStandardDialogLayoutAdapter which
646 can perform adaptation for most custom dialogs and dialogs with book
647 controls such as wxPropertySheetDialog.
652 @see @ref overview_dialog_autoscrolling
654 class wxDialogLayoutAdapter
660 wxDialogLayoutAdapter();
663 Override this to returns @true if adaptation can and should be done.
665 virtual bool CanDoLayoutAdaptation(wxDialog
* dialog
) = 0;
668 Override this to perform layout adaptation, such as making parts of the
669 dialog scroll and resizing the dialog to fit the display. Normally this
670 function will be called just before the dialog is shown.
672 virtual bool DoLayoutAdaptation(wxDialog
* dialog
) = 0;
676 class wxWindowModalDialogEvent
: public wxCommandEvent
679 wxWindowModalDialogEvent (wxEventType commandType
= wxEVT_NULL
, int id
= 0);
681 wxDialog
*GetDialog() const;
682 int GetReturnCode() const;
683 virtual wxEvent
*Clone() const;