1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDialog
4 // Author: wxWidgets team
6 // Licence: wxWindows license
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.
23 A dialog box is a window with a title bar and sometimes a system menu,
24 which can be moved around the screen. It can contain controls and other
25 windows and is often used to allow the user to make some choice or to
28 Dialogs can be made scrollable, automatically, for computers with low
29 resolution screens: please see @ref overview_dialog_autoscrolling for
32 Dialogs usually contains either a single button allowing to close the
33 dialog or two buttons, one accepting the changes and the other one
34 discarding them (such button, if present, is automatically activated if the
35 user presses the "Esc" key). By default, buttons with the standard wxID_OK
36 and wxID_CANCEL identifiers behave as expected. Starting with wxWidgets 2.7
37 it is also possible to use a button with a different identifier instead,
38 see SetAffirmativeId() and SetEscapeId().
40 Also notice that the CreateButtonSizer() should be used to create the
41 buttons appropriate for the current platform and positioned correctly
42 (including their order which is platform-dependent).
44 @section dialog_modal Modal and Modeless
46 There are two kinds of dialog, modal and modeless. A modal dialog blocks
47 program flow and user input on other windows until it is dismissed, whereas
48 a modeless dialog behaves more like a frame in that program flow continues,
49 and input in other windows is still possible. To show a modal dialog you
50 should use the ShowModal() method while to show a dialog modelessly you
51 simply use Show(), just as with frames.
53 Note that the modal dialog is one of the very few examples of
54 wxWindow-derived objects which may be created on the stack and not on the
55 heap. In other words, while most windows would be created like this:
60 MyAskDialog *dlg = new MyAskDialog(...);
61 if ( dlg->ShowModal() == wxID_OK )
63 //else: dialog was cancelled or some another button pressed
69 You can achieve the same result with dialogs by using simpler code:
75 if ( dlg.ShowModal() == wxID_OK )
78 // no need to call Destroy() here
82 An application can define a wxCloseEvent handler for the dialog to respond
83 to system close events.
87 Puts a caption on the dialog box.
88 @style{wxDEFAULT_DIALOG_STYLE}
89 Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and
90 wxSYSTEM_MENU (the last one is not used under Unix).
91 @style{wxRESIZE_BORDER}
92 Display a resizeable frame around the window.
94 Display a system menu.
96 Displays a close box on the frame.
97 @style{wxMAXIMIZE_BOX}
98 Displays a maximize box on the dialog.
99 @style{wxMINIMIZE_BOX}
100 Displays a minimize box on the dialog.
101 @style{wxTHICK_FRAME}
102 Display a thick frame around the window.
103 @style{wxSTAY_ON_TOP}
104 The dialog stays on top of all other windows.
106 Under Windows, specifies that the child controls should not have 3D
107 borders unless specified in the control.
108 @style{wxDIALOG_NO_PARENT}
109 By default, a dialog created with a @NULL parent window will be
110 given the @ref wxApp::GetTopWindow() "application's top level window"
111 as parent. Use this style to prevent this from happening and create
112 an orphan dialog. This is not recommended for modal dialogs.
113 @style{wxDIALOG_EX_CONTEXTHELP}
114 Under Windows, puts a query button on the caption. When pressed,
115 Windows will go into a context-sensitive help mode and wxWidgets
116 will send a wxEVT_HELP event if the user clicked on an application
117 window. Note that this is an extended style and must be set by
118 calling SetExtraStyle() before Create is called (two-step
120 @style{wxDIALOG_EX_METAL}
121 On Mac OS X, frames with this style will be shown with a metallic
122 look. This is an extra style.
125 Under Unix or Linux, MWM (the Motif Window Manager) or other window
126 managers recognizing the MHM hints should be running for any of these
127 styles to have an effect.
132 @see @ref overview_dialog, wxFrame, @ref overview_validator
134 class wxDialog
: public wxTopLevelWindow
145 Can be @NULL, a frame or another dialog box.
147 An identifier for the dialog. A value of -1 is taken to mean a
150 The title of the dialog.
152 The dialog position. The value wxDefaultPosition indicates a
153 default position, chosen by either the windowing system or
154 wxWidgets, depending on platform.
156 The dialog size. The value wxDefaultSize indicates a default size,
157 chosen by either the windowing system or wxWidgets, depending on
162 Used to associate a name with the window, allowing the application
163 user to set Motif resource values for individual dialog boxes.
167 wxDialog(wxWindow
* parent
, wxWindowID id
, const wxString
& title
,
168 const wxPoint
& pos
= wxDefaultPosition
,
169 const wxSize
& size
= wxDefaultSize
,
170 long style
= wxDEFAULT_DIALOG_STYLE
,
171 const wxString
& name
= "dialogBox");
174 Destructor. Deletes any child windows before deleting the physical
180 Adds an identifier to be regarded as a main button for the
181 non-scrolling area of a dialog.
183 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
185 void AddMainButtonId(wxWindowID id
);
188 Returns @true if this dialog can and should perform layout adaptation
189 using DoLayoutAdaptation(), usually if the dialog is too large to fit
192 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
194 bool CanDoLayoutAdapation();
197 Centres the dialog box on the display.
200 May be wxHORIZONTAL, wxVERTICAL or wxBOTH.
202 void Centre(int direction
= wxBOTH
);
205 Used for two-step dialog box construction.
209 bool Create(wxWindow
* parent
, wxWindowID id
, const wxString
& title
,
210 const wxPoint
& pos
= wxDefaultPosition
,
211 const wxSize
& size
= wxDefaultSize
,
212 long style
= wxDEFAULT_DIALOG_STYLE
,
213 const wxString
& name
= "dialogBox");
216 Creates a sizer with standard buttons. @a flags is a bit list of the
217 following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP,
220 The sizer lays out the buttons in a manner appropriate to the platform.
222 This function uses CreateStdDialogButtonSizer() internally for most
223 platforms but doesn't create the sizer at all for the platforms with
224 hardware buttons (such as smartphones) for which it sets up the
225 hardware buttons appropriately and returns @NULL, so don't forget to
226 test that the return value is valid before using it.
228 wxSizer
* CreateButtonSizer(long flags
);
231 Creates a sizer with standard buttons using CreateButtonSizer()
232 separated from the rest of the dialog contents by a horizontal
235 @note Just like CreateButtonSizer(), this function may return @NULL if
236 no buttons were created.
238 wxSizer
* CreateSeparatedButtonSizer(long flags
);
241 Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a
242 bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY,
243 wxCLOSE, wxHELP, wxNO_DEFAULT.
245 The sizer lays out the buttons in a manner appropriate to the platform.
247 wxStdDialogButtonSizer
* CreateStdDialogButtonSizer(long flags
);
250 Performs layout adaptation, usually if the dialog is too large to fit
253 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
255 bool DoLayoutAdapation();
258 This function is called when the titlebar OK button is pressed
259 (PocketPC only). A command event for the identifier returned by
260 GetAffirmativeId() is sent by default. You can override this function.
261 If the function returns @false, wxWidgets will call Close() for the
267 A static function enabling or disabling layout adaptation for all
270 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
272 static void EnableLayoutAdaptation(bool enable
);
275 Ends a modal dialog, passing a value to be returned from the
276 ShowModal() invocation.
279 The value that should be returned by ShowModal.
281 @see ShowModal(), GetReturnCode(), SetReturnCode()
283 void EndModal(int retCode
);
286 Gets the identifier of the button which works like standard OK button
289 @see SetAffirmativeId()
291 int GetAffirmativeId() const;
294 Override this to return a window containing the main content of the
295 dialog. This is particularly useful when the dialog implements pages,
296 such as wxPropertySheetDialog, and allows the
297 @ref overview_dialog "layout adaptation code" to know that only the
298 pages need to be made scrollable.
300 wxWindow
* GetContentWindow() const;
303 Gets the identifier of the button to map presses of @c ESC button to.
307 int GetEscapeId() const;
310 Returns @true if the dialog has been adapted, usually by making it
311 scrollable to work with a small display.
313 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
315 bool GetLayoutAdaptationDone() const;
318 Gets a value representing the aggressiveness of search for buttons and
319 sizers to be in the non-scrolling part of a layout-adapted dialog. Zero
320 switches off adaptation, and 3 allows search for standard buttons
321 anywhere in the dialog.
323 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
325 int GetLayoutAdaptationLevel();
328 Gets the adaptation mode, overriding the global adaptation flag.
330 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
332 wxDialogLayoutAdaptationMode
GetLayoutAdaptationMode() const;
335 A static function getting the current layout adapter object.
337 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
339 static wxDialogLayoutAdapter
* GetLayoutAdapter();
342 Returns an array of identifiers to be regarded as the main buttons for
343 the non-scrolling area of a dialog.
345 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
347 wxArrayInt
GetMainButtonIds();
350 Gets the return code for this window.
352 @remarks A return code is normally associated with a modal dialog,
353 where ShowModal() returns a code to the application.
355 @see SetReturnCode(), ShowModal(), EndModal()
360 On PocketPC, a dialog is automatically provided with an empty toolbar.
361 This function allows you to access the toolbar and add tools to it.
362 Removing tools and adding arbitrary controls are not currently
365 This function is not available on any other platform.
367 wxToolBar
* GetToolBar() const;
370 Iconizes or restores the dialog. Windows only.
373 If @true, iconizes the dialog box; if @false, shows and restores it.
375 @remarks Note that in Windows, iconization has no effect since dialog
376 boxes cannot be iconized. However, applications may need to
377 explicitly restore dialog boxes under Motif which have
378 user-iconizable frames, and under Windows calling
379 Iconize(@false) will bring the window to the front, as does
382 void Iconize(bool iconize
);
385 Returns @true if the dialog box is iconized. Windows only.
387 @remarks Always returns @false under Windows since dialogs cannot be
390 bool IsIconized() const;
393 A static function returning @true if layout adaptation is enabled for
396 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
398 static bool IsLayoutAdaptationEnabled();
401 Returns @true if @a id is in the array of identifiers to be regarded as
402 the main buttons for the non-scrolling area of a dialog.
404 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
406 bool IsMainButton(wxWindowID
& id
) const;
409 Returns @true if the dialog box is modal, @false otherwise.
411 bool IsModal() const;
414 The default handler for wxEVT_SYS_COLOUR_CHANGED.
417 The colour change event.
419 @remarks Changes the dialog's colour to conform to the current settings
420 (Windows only). Add an event table entry for your dialog class
421 if you wish the behaviour to be different (such as keeping a
422 user-defined background colour). If you do override this
423 function, call wxEvent::Skip() to propagate the notification
424 to child windows and controls.
426 @see wxSysColourChangedEvent
428 void OnSysColourChanged(wxSysColourChangedEvent
& event
);
431 Sets the identifier to be used as OK button. When the button with this
432 identifier is pressed, the dialog calls wxWindow::Validate() and
433 wxWindow::TransferDataFromWindow() and, if they both return @true,
434 closes the dialog with wxID_OK return code.
436 Also, when the user presses a hardware OK button on the devices having
437 one or the special OK button in the PocketPC title bar, an event with
438 this id is generated.
440 By default, the affirmative id is wxID_OK.
442 @see GetAffirmativeId(), SetEscapeId()
444 void SetAffirmativeId(int id
);
447 Sets the identifier of the button which should work like the standard
448 "Cancel" button in this dialog. When the button with this id is
449 clicked, the dialog is closed. Also, when the user presses @c ESC key
450 in the dialog or closes the dialog using the close button in the title
451 bar, this is mapped to the click of the button with the specified id.
453 By default, the escape id is the special value wxID_ANY meaning that
454 wxID_CANCEL button is used if it's present in the dialog and otherwise
455 the button with GetAffirmativeId() is used. Another special value for
456 @a id is wxID_NONE meaning that @c ESC presses should be ignored. If
457 any other value is given, it is interpreted as the id of the button to
458 map the escape key to.
460 void SetEscapeId(int id
);
463 Sets the icon for this dialog.
466 The icon to associate with this dialog.
470 void SetIcon(const wxIcon
& icon
);
473 Sets the icons for this dialog.
476 The icons to associate with this dialog.
480 void SetIcons(const wxIconBundle
& icons
);
483 Marks the dialog as having been adapted, usually by making it
484 scrollable to work with a small display.
486 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
488 void SetLayoutAdaptationDone(bool done
);
491 Sets the aggressiveness of search for buttons and sizers to be in the
492 non-scrolling part of a layout-adapted dialog. Zero switches off
493 adaptation, and 3 allows search for standard buttons anywhere in the
496 @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
498 void SetLayoutAdaptationLevel(int level
);
501 Sets the adaptation mode, overriding the global adaptation flag.
503 @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling
504 (for more on layout adaptation)
506 void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode
);
509 A static function for setting the current layout adapter object,
510 returning the old adapter. If you call this, you should delete the old
513 @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling
515 static wxDialogLayoutAdapter
* SetLayoutAdapter(wxDialogLayoutAdapter
* adapter
);
518 @deprecated This function doesn't work for all ports, just use
519 ShowModal() to show a modal dialog instead.
521 Allows the programmer to specify whether the dialog box is modal
522 (Show() blocks control until the dialog is hidden) or modeless (control
523 returns immediately).
526 If @true, the dialog will be modal, otherwise it will be modeless.
528 void SetModal(bool flag
);
531 Sets the return code for this window.
533 A return code is normally associated with a modal dialog, where
534 ShowModal() returns a code to the application. The function EndModal()
535 calls SetReturnCode().
538 The integer return code, usually a control identifier.
540 @see GetReturnCode(), ShowModal(), EndModal()
542 void SetReturnCode(int retCode
);
545 Hides or shows the dialog. The preferred way of dismissing a modal
546 dialog is to use EndModal().
549 If @true, the dialog box is shown and brought to the front,
550 otherwise the box is hidden. If @false and the dialog is modal,
551 control is returned to the calling program.
553 bool Show(bool show
);
556 Shows a modal dialog.
558 Program flow does not return until the dialog has been dismissed with
561 Notice that it is possible to call ShowModal() for a dialog which had
562 been previously shown with Show(), this allows to make an existing
563 modeless dialog modal. However ShowModal() can't be called twice
564 without intervening EndModal() calls.
566 @return The value set with SetReturnCode().
568 @see EndModal(), GetReturnCode(), SetReturnCode()
576 @class wxDialogLayoutAdapter
579 This abstract class is the base for classes that help wxWidgets peform
580 run-time layout adaptation of dialogs. Principally, this is to cater for
581 small displays by making part of the dialog scroll, but the application
582 developer may find other uses for layout adaption.
584 By default, there is one instance of wxStandardDialogLayoutAdapter which
585 can perform adaptation for most custom dialogs and dialogs with book
586 controls such as wxPropertySheetDialog.
591 @see @ref overview_dialog_autoscrolling
593 class wxDialogLayoutAdapter
599 wxDialogLayoutAdapter();
602 Override this to returns @true if adaptation can and should be done.
604 bool CanDoLayoutAdaptation(wxDialog
* dialog
);
607 Override this to perform layout adaptation, such as making parts of the
608 dialog scroll and resizing the dialog to fit the display. Normally this
609 function will be called just before the dialog is shown.
611 bool DoLayoutAdaptation(wxDialog
* dialog
);