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.
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
27 Dialogs can be made scrollable, automatically, for computers with low
28 resolution screens: please see @ref overview_dialog_autoscrolling for
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().
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).
43 @section dialog_modal Modal and Modeless
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.
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:
59 MyAskDialog *dlg = new MyAskDialog(...);
60 if ( dlg->ShowModal() == wxID_OK )
62 //else: dialog was cancelled or some another button pressed
68 You can achieve the same result with dialogs by using simpler code:
74 if ( dlg.ShowModal() == wxID_OK )
77 // no need to call Destroy() here
81 An application can define a wxCloseEvent handler for the dialog to respond
82 to system close events.
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.
93 Display a system menu.
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.
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
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.
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.
129 @beginEventEmissionTable{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 @event{EVT_INIT_DIALOG(func)}
137 Process a @c wxEVT_INIT_DIALOG event. See wxInitDialogEvent.
143 @see @ref overview_dialog, wxFrame, @ref overview_validator
145 class wxDialog
: public wxTopLevelWindow
156 Can be @NULL, a frame or another dialog box.
158 An identifier for the dialog. A value of -1 is taken to mean a
161 The title of the dialog.
163 The dialog position. The value wxDefaultPosition indicates a
164 default position, chosen by either the windowing system or
165 wxWidgets, depending on platform.
167 The dialog size. The value wxDefaultSize indicates a default size,
168 chosen by either the windowing system or wxWidgets, depending on
173 Used to associate a name with the window, allowing the application
174 user to set Motif resource values for individual dialog boxes.
178 wxDialog(wxWindow
* parent
, wxWindowID id
, const wxString
& title
,
179 const wxPoint
& pos
= wxDefaultPosition
,
180 const wxSize
& size
= wxDefaultSize
,
181 long style
= wxDEFAULT_DIALOG_STYLE
,
182 const wxString
& name
= wxDialogNameStr
);
187 Deletes any child windows before deleting the physical window.
189 See @ref overview_windowdeletion for more info.
194 Adds an identifier to be regarded as a main button for the
195 non-scrolling area of a dialog.
197 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
199 void AddMainButtonId(wxWindowID id
);
202 Returns @true if this dialog can and should perform layout adaptation
203 using DoLayoutAdaptation(), usually if the dialog is too large to fit
206 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
208 virtual bool CanDoLayoutAdaptation();
211 Centres the dialog box on the display.
214 May be wxHORIZONTAL, wxVERTICAL or wxBOTH.
216 void Centre(int direction
= wxBOTH
);
219 Used for two-step dialog box construction.
223 bool Create(wxWindow
* parent
, wxWindowID id
, const wxString
& title
,
224 const wxPoint
& pos
= wxDefaultPosition
,
225 const wxSize
& size
= wxDefaultSize
,
226 long style
= wxDEFAULT_DIALOG_STYLE
,
227 const wxString
& name
= wxDialogNameStr
);
230 Creates a sizer with standard buttons. @a flags is a bit list of the
231 following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP,
234 The sizer lays out the buttons in a manner appropriate to the platform.
236 This function uses CreateStdDialogButtonSizer() internally for most
237 platforms but doesn't create the sizer at all for the platforms with
238 hardware buttons (such as smartphones) for which it sets up the
239 hardware buttons appropriately and returns @NULL, so don't forget to
240 test that the return value is valid before using it.
242 wxSizer
* CreateButtonSizer(long flags
);
245 Creates a sizer with standard buttons using CreateButtonSizer()
246 separated from the rest of the dialog contents by a horizontal
249 @note Just like CreateButtonSizer(), this function may return @NULL if
250 no buttons were created.
252 This is a combination of CreateButtonSizer() and
253 CreateSeparatedSizer().
255 wxSizer
* CreateSeparatedButtonSizer(long flags
);
258 Returns the sizer containing the given one with a separating
259 wxStaticLine if necessarily.
261 This function is useful for creating the sizer containing footer-like
262 contents in dialog boxes. It will add a separating static line only if
263 it conforms to the current platform convention (currently it is not
264 added under Mac where the use of static lines for grouping is
265 discouraged and is added elsewhere).
269 @param sizer The sizer to wrap, must be non-@NULL.
270 @return The sizer wrapping the input one or possibly the input sizer
271 itself if no wrapping is necessary.
273 wxSizer
*CreateSeparatedSizer(wxSizer
*sizer
);
276 Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a
277 bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY,
278 wxCLOSE, wxHELP, wxNO_DEFAULT.
280 The sizer lays out the buttons in a manner appropriate to the platform.
282 wxStdDialogButtonSizer
* CreateStdDialogButtonSizer(long flags
);
285 Performs layout adaptation, usually if the dialog is too large to fit
288 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
290 virtual bool DoLayoutAdaptation();
293 This function is called when the titlebar OK button is pressed
294 (PocketPC only). A command event for the identifier returned by
295 GetAffirmativeId() is sent by default. You can override this function.
296 If the function returns @false, wxWidgets will call Close() for the
304 A static function enabling or disabling layout adaptation for all
307 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
309 static void EnableLayoutAdaptation(bool enable
);
312 Ends a modal dialog, passing a value to be returned from the
313 ShowModal() invocation.
316 The value that should be returned by ShowModal.
318 @see ShowModal(), GetReturnCode(), SetReturnCode()
320 virtual void EndModal(int retCode
);
323 Gets the identifier of the button which works like standard OK button
326 @see SetAffirmativeId()
328 int GetAffirmativeId() const;
331 Override this to return a window containing the main content of the
332 dialog. This is particularly useful when the dialog implements pages,
333 such as wxPropertySheetDialog, and allows the
334 @ref overview_dialog "layout adaptation code" to know that only the
335 pages need to be made scrollable.
337 virtual wxWindow
* GetContentWindow() const;
340 Gets the identifier of the button to map presses of @c ESC button to.
344 int GetEscapeId() const;
347 Returns @true if the dialog has been adapted, usually by making it
348 scrollable to work with a small display.
350 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
352 bool GetLayoutAdaptationDone() const;
355 Gets a value representing the aggressiveness of search for buttons and
356 sizers to be in the non-scrolling part of a layout-adapted dialog. Zero
357 switches off adaptation, and 3 allows search for standard buttons
358 anywhere in the dialog.
360 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
362 int GetLayoutAdaptationLevel() const;
365 Gets the adaptation mode, overriding the global adaptation flag.
367 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
369 wxDialogLayoutAdaptationMode
GetLayoutAdaptationMode() const;
372 A static function getting the current layout adapter object.
374 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
376 static wxDialogLayoutAdapter
* GetLayoutAdapter();
379 Returns an array of identifiers to be regarded as the main buttons for
380 the non-scrolling area of a dialog.
382 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
384 wxArrayInt
& GetMainButtonIds();
387 Gets the return code for this window.
389 @remarks A return code is normally associated with a modal dialog,
390 where ShowModal() returns a code to the application.
392 @see SetReturnCode(), ShowModal(), EndModal()
394 int GetReturnCode() const;
397 On PocketPC, a dialog is automatically provided with an empty toolbar.
398 This function allows you to access the toolbar and add tools to it.
399 Removing tools and adding arbitrary controls are not currently
402 This function is not available on any other platform.
406 wxToolBar
* GetToolBar() const;
409 Iconizes or restores the dialog. Windows only.
412 If @true, iconizes the dialog box; if @false, shows and restores it.
414 @remarks Note that in Windows, iconization has no effect since dialog
415 boxes cannot be iconized. However, applications may need to
416 explicitly restore dialog boxes under Motif which have
417 user-iconizable frames, and under Windows calling
418 Iconize(@false) will bring the window to the front, as does
421 virtual void Iconize(bool iconize
= true);
424 Returns @true if the dialog box is iconized. Windows only.
426 @remarks Always returns @false under Windows since dialogs cannot be
429 virtual bool IsIconized() const;
432 A static function returning @true if layout adaptation is enabled for
435 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
437 static bool IsLayoutAdaptationEnabled();
440 Returns @true if @a id is in the array of identifiers to be regarded as
441 the main buttons for the non-scrolling area of a dialog.
445 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
447 bool IsMainButtonId(wxWindowID id
) const;
450 Returns @true if the dialog box is modal, @false otherwise.
452 virtual bool IsModal() const;
455 The default handler for wxEVT_SYS_COLOUR_CHANGED.
458 The colour change event.
460 @remarks Changes the dialog's colour to conform to the current settings
461 (Windows only). Add an event table entry for your dialog class
462 if you wish the behaviour to be different (such as keeping a
463 user-defined background colour). If you do override this
464 function, call wxEvent::Skip() to propagate the notification
465 to child windows and controls.
467 @see wxSysColourChangedEvent
469 void OnSysColourChanged(wxSysColourChangedEvent
& event
);
472 Sets the identifier to be used as OK button. When the button with this
473 identifier is pressed, the dialog calls wxWindow::Validate() and
474 wxWindow::TransferDataFromWindow() and, if they both return @true,
475 closes the dialog with wxID_OK return code.
477 Also, when the user presses a hardware OK button on the devices having
478 one or the special OK button in the PocketPC title bar, an event with
479 this id is generated.
481 By default, the affirmative id is wxID_OK.
483 @see GetAffirmativeId(), SetEscapeId()
485 void SetAffirmativeId(int id
);
488 Sets the identifier of the button which should work like the standard
489 "Cancel" button in this dialog. When the button with this id is
490 clicked, the dialog is closed. Also, when the user presses @c ESC key
491 in the dialog or closes the dialog using the close button in the title
492 bar, this is mapped to the click of the button with the specified id.
494 By default, the escape id is the special value wxID_ANY meaning that
495 wxID_CANCEL button is used if it's present in the dialog and otherwise
496 the button with GetAffirmativeId() is used. Another special value for
497 @a id is wxID_NONE meaning that @c ESC presses should be ignored. If
498 any other value is given, it is interpreted as the id of the button to
499 map the escape key to.
501 void SetEscapeId(int id
);
504 Sets the icon for this dialog.
507 The icon to associate with this dialog.
511 void SetIcon(const wxIcon
& icon
);
514 Sets the icons for this dialog.
517 The icons to associate with this dialog.
521 void SetIcons(const wxIconBundle
& icons
);
524 Marks the dialog as having been adapted, usually by making it
525 scrollable to work with a small display.
527 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
529 void SetLayoutAdaptationDone(bool done
);
532 Sets the aggressiveness of search for buttons and sizers to be in the
533 non-scrolling part of a layout-adapted dialog. Zero switches off
534 adaptation, and 3 allows search for standard buttons anywhere in the
537 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
539 void SetLayoutAdaptationLevel(int level
);
542 Sets the adaptation mode, overriding the global adaptation flag.
544 @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling
545 (for more on layout adaptation)
547 void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode
);
550 A static function for setting the current layout adapter object,
551 returning the old adapter. If you call this, you should delete the old
554 @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling
556 static wxDialogLayoutAdapter
* SetLayoutAdapter(wxDialogLayoutAdapter
* adapter
);
559 @deprecated This function doesn't work for all ports, just use
560 ShowModal() to show a modal dialog instead.
562 Allows the programmer to specify whether the dialog box is modal
563 (Show() blocks control until the dialog is hidden) or modeless (control
564 returns immediately).
567 If @true, the dialog will be modal, otherwise it will be modeless.
569 void SetModal(bool flag
);
572 Sets the return code for this window.
574 A return code is normally associated with a modal dialog, where
575 ShowModal() returns a code to the application. The function EndModal()
576 calls SetReturnCode().
579 The integer return code, usually a control identifier.
581 @see GetReturnCode(), ShowModal(), EndModal()
583 void SetReturnCode(int retCode
);
586 Hides or shows the dialog. The preferred way of dismissing a modal
587 dialog is to use EndModal().
590 If @true, the dialog box is shown and brought to the front,
591 otherwise the box is hidden. If @false and the dialog is modal,
592 control is returned to the calling program.
594 virtual bool Show(bool show
= 1);
597 Shows a modal dialog.
599 Program flow does not return until the dialog has been dismissed with
602 Notice that it is possible to call ShowModal() for a dialog which had
603 been previously shown with Show(), this allows to make an existing
604 modeless dialog modal. However ShowModal() can't be called twice
605 without intervening EndModal() calls.
607 Note that this function creates a temporary event loop which takes
608 precedence over the application's main event loop (see wxEventLoopBase)
609 and which is destroyed when the dialog is dismissed.
610 This also results in a call to wxApp::ProcessPendingEvents().
612 @return The value set with SetReturnCode().
614 @see EndModal(), GetReturnCode(), SetReturnCode()
616 virtual int ShowModal();
622 @class wxDialogLayoutAdapter
624 This abstract class is the base for classes that help wxWidgets peform
625 run-time layout adaptation of dialogs. Principally, this is to cater for
626 small displays by making part of the dialog scroll, but the application
627 developer may find other uses for layout adaption.
629 By default, there is one instance of wxStandardDialogLayoutAdapter which
630 can perform adaptation for most custom dialogs and dialogs with book
631 controls such as wxPropertySheetDialog.
636 @see @ref overview_dialog_autoscrolling
638 class wxDialogLayoutAdapter
644 wxDialogLayoutAdapter();
647 Override this to returns @true if adaptation can and should be done.
649 virtual bool CanDoLayoutAdaptation(wxDialog
* dialog
) = 0;
652 Override this to perform layout adaptation, such as making parts of the
653 dialog scroll and resizing the dialog to fit the display. Normally this
654 function will be called just before the dialog is shown.
656 virtual bool DoLayoutAdaptation(wxDialog
* dialog
) = 0;