#include <wx/dialog.h>
A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the screen.
It can contain controls and other windows and is often used to allow the user to make some choice or to answer a question.
Dialogs can be made scrollable, automatically, for computers with low resolution screens: please see Automatic scrolling dialogs for further details.
Dialogs usually contains either a single button allowing to close the dialog or two buttons, one accepting the changes and the other one discarding them (such button, if present, is automatically activated if the user presses the "Esc" key). By default, buttons with the standard wxID_OK and wxID_CANCEL identifiers behave as expected. Starting with wxWidgets 2.7 it is also possible to use a button with a different identifier instead, see SetAffirmativeId() and SetEscapeId().
Also notice that the CreateButtonSizer() should be used to create the buttons appropriate for the current platform and positioned correctly (including their order which is platform-dependent).
There are two kinds of dialog, modal and modeless. A modal dialog blocks program flow and user input on other windows until it is dismissed, whereas a modeless dialog behaves more like a frame in that program flow continues, and input in other windows is still possible. To show a modal dialog you should use the ShowModal() method while to show a dialog modelessly you simply use Show(), just as with frames.
Note that the modal dialog is one of the very few examples of wxWindow-derived objects which may be created on the stack and not on the heap. In other words, while most windows would be created like this:
void AskUser() { MyAskDialog *dlg = new MyAskDialog(...); if ( dlg->ShowModal() == wxID_OK ) // ... //else: dialog was cancelled or some another button pressed dlg->Destroy(); }
You can achieve the same result with dialogs by using simpler code:
void AskUser() { MyAskDialog dlg(...); if ( dlg.ShowModal() == wxID_OK ) // ... // no need to call Destroy() here }
An application can define a wxCloseEvent handler for the dialog to respond to system close events.
This class supports the following styles:
Under Unix or Linux, MWM (the Motif Window Manager) or other window managers recognizing the MHM hints should be running for any of these styles to have an effect.
The following event handler macros redirect the events to member function handlers 'func' with prototypes like:
Event macros for events emitted by this class:
wxCLOSE_BOX
style) or by clicking a button with the wxID_CANCEL
or wxID_OK
ids. wxEVT_INIT_DIALOG
event. See wxInitDialogEvent. Public Member Functions | |
wxDialog () | |
Default constructor. | |
wxDialog (wxWindow *parent, wxWindowID id, const wxString &title, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=wxDEFAULT_DIALOG_STYLE, const wxString &name=wxDialogNameStr) | |
Constructor. | |
virtual | ~wxDialog () |
Destructor. | |
void | AddMainButtonId (wxWindowID id) |
Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog. | |
virtual bool | CanDoLayoutAdaptation () |
Returns true if this dialog can and should perform layout adaptation using DoLayoutAdaptation(), usually if the dialog is too large to fit on the display. | |
void | Centre (int direction=wxBOTH) |
Centres the dialog box on the display. | |
bool | Create (wxWindow *parent, wxWindowID id, const wxString &title, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=wxDEFAULT_DIALOG_STYLE, const wxString &name=wxDialogNameStr) |
Used for two-step dialog box construction. | |
wxSizer * | CreateButtonSizer (long flags) |
Creates a sizer with standard buttons. | |
wxSizer * | CreateSeparatedButtonSizer (long flags) |
Creates a sizer with standard buttons using CreateButtonSizer() separated from the rest of the dialog contents by a horizontal wxStaticLine. | |
wxStdDialogButtonSizer * | CreateStdDialogButtonSizer (long flags) |
Creates a wxStdDialogButtonSizer with standard buttons. | |
virtual bool | DoLayoutAdaptation () |
Performs layout adaptation, usually if the dialog is too large to fit on the display. | |
virtual bool | DoOK () |
This function is called when the titlebar OK button is pressed (PocketPC only). | |
virtual void | EndModal (int retCode) |
Ends a modal dialog, passing a value to be returned from the ShowModal() invocation. | |
int | GetAffirmativeId () const |
Gets the identifier of the button which works like standard OK button in this dialog. | |
virtual wxWindow * | GetContentWindow () const |
Override this to return a window containing the main content of the dialog. | |
int | GetEscapeId () const |
Gets the identifier of the button to map presses of ESC button to. | |
bool | GetLayoutAdaptationDone () const |
Returns true if the dialog has been adapted, usually by making it scrollable to work with a small display. | |
int | GetLayoutAdaptationLevel () const |
Gets a value representing the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog. | |
wxDialogLayoutAdaptationMode | GetLayoutAdaptationMode () const |
Gets the adaptation mode, overriding the global adaptation flag. | |
wxArrayInt & | GetMainButtonIds () |
Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. | |
int | GetReturnCode () const |
Gets the return code for this window. | |
wxToolBar * | GetToolBar () const |
On PocketPC, a dialog is automatically provided with an empty toolbar. | |
virtual void | Iconize (bool iconize=true) |
Iconizes or restores the dialog. | |
virtual bool | IsIconized () const |
Returns true if the dialog box is iconized. | |
bool | IsMainButtonId (wxWindowID id) const |
Returns true if id is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. | |
virtual bool | IsModal () const |
Returns true if the dialog box is modal, false otherwise. | |
void | OnSysColourChanged (wxSysColourChangedEvent &event) |
The default handler for wxEVT_SYS_COLOUR_CHANGED. | |
void | SetAffirmativeId (int id) |
Sets the identifier to be used as OK button. | |
void | SetEscapeId (int id) |
Sets the identifier of the button which should work like the standard "Cancel" button in this dialog. | |
void | SetIcon (const wxIcon &icon) |
Sets the icon for this dialog. | |
void | SetIcons (const wxIconBundle &icons) |
Sets the icons for this dialog. | |
void | SetLayoutAdaptationDone (bool done) |
Marks the dialog as having been adapted, usually by making it scrollable to work with a small display. | |
void | SetLayoutAdaptationLevel (int level) |
Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog. | |
void | SetLayoutAdaptationMode (wxDialogLayoutAdaptationMode mode) |
Sets the adaptation mode, overriding the global adaptation flag. | |
void | SetModal (bool flag) |
void | SetReturnCode (int retCode) |
Sets the return code for this window. | |
virtual bool | Show (bool show=1) |
Hides or shows the dialog. | |
virtual int | ShowModal () |
Shows a modal dialog. | |
Static Public Member Functions | |
static void | EnableLayoutAdaptation (bool enable) |
A static function enabling or disabling layout adaptation for all dialogs. | |
static wxDialogLayoutAdapter * | GetLayoutAdapter () |
A static function getting the current layout adapter object. | |
static bool | IsLayoutAdaptationEnabled () |
A static function returning true if layout adaptation is enabled for all dialogs. | |
static wxDialogLayoutAdapter * | SetLayoutAdapter (wxDialogLayoutAdapter *adapter) |
A static function for setting the current layout adapter object, returning the old adapter. |
wxDialog::wxDialog | ( | ) |
Default constructor.
wxDialog::wxDialog | ( | wxWindow * | parent, | |
wxWindowID | id, | |||
const wxString & | title, | |||
const wxPoint & | pos = wxDefaultPosition , |
|||
const wxSize & | size = wxDefaultSize , |
|||
long | style = wxDEFAULT_DIALOG_STYLE , |
|||
const wxString & | name = wxDialogNameStr | |||
) |
Constructor.
parent | Can be NULL, a frame or another dialog box. | |
id | An identifier for the dialog. A value of -1 is taken to mean a default. | |
title | The title of the dialog. | |
pos | The dialog position. The value wxDefaultPosition indicates a default position, chosen by either the windowing system or wxWidgets, depending on platform. | |
size | The dialog size. The value wxDefaultSize indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform. | |
style | The window style. | |
name | Used to associate a name with the window, allowing the application user to set Motif resource values for individual dialog boxes. |
virtual wxDialog::~wxDialog | ( | ) | [virtual] |
Destructor.
Deletes any child windows before deleting the physical window.
See Window Deletion for more info.
void wxDialog::AddMainButtonId | ( | wxWindowID | id | ) |
Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog.
virtual bool wxDialog::CanDoLayoutAdaptation | ( | ) | [virtual] |
Returns true if this dialog can and should perform layout adaptation using DoLayoutAdaptation(), usually if the dialog is too large to fit on the display.
void wxDialog::Centre | ( | int | direction = wxBOTH |
) |
Centres the dialog box on the display.
direction | May be wxHORIZONTAL, wxVERTICAL or wxBOTH. |
Reimplemented from wxWindow.
bool wxDialog::Create | ( | wxWindow * | parent, | |
wxWindowID | id, | |||
const wxString & | title, | |||
const wxPoint & | pos = wxDefaultPosition , |
|||
const wxSize & | size = wxDefaultSize , |
|||
long | style = wxDEFAULT_DIALOG_STYLE , |
|||
const wxString & | name = wxDialogNameStr | |||
) |
Used for two-step dialog box construction.
Reimplemented from wxTopLevelWindow.
Reimplemented in wxPropertySheetDialog.
wxSizer* wxDialog::CreateButtonSizer | ( | long | flags | ) |
Creates a sizer with standard buttons.
flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, wxNO_DEFAULT.
The sizer lays out the buttons in a manner appropriate to the platform.
This function uses CreateStdDialogButtonSizer() internally for most platforms but doesn't create the sizer at all for the platforms with hardware buttons (such as smartphones) for which it sets up the hardware buttons appropriately and returns NULL, so don't forget to test that the return value is valid before using it.
wxSizer* wxDialog::CreateSeparatedButtonSizer | ( | long | flags | ) |
Creates a sizer with standard buttons using CreateButtonSizer() separated from the rest of the dialog contents by a horizontal wxStaticLine.
wxStdDialogButtonSizer* wxDialog::CreateStdDialogButtonSizer | ( | long | flags | ) |
Creates a wxStdDialogButtonSizer with standard buttons.
flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, wxNO_DEFAULT.
The sizer lays out the buttons in a manner appropriate to the platform.
virtual bool wxDialog::DoLayoutAdaptation | ( | ) | [virtual] |
Performs layout adaptation, usually if the dialog is too large to fit on the display.
virtual bool wxDialog::DoOK | ( | ) | [virtual] |
This function is called when the titlebar OK button is pressed (PocketPC only).
A command event for the identifier returned by GetAffirmativeId() is sent by default. You can override this function. If the function returns false, wxWidgets will call Close() for the dialog.
static void wxDialog::EnableLayoutAdaptation | ( | bool | enable | ) | [static] |
A static function enabling or disabling layout adaptation for all dialogs.
virtual void wxDialog::EndModal | ( | int | retCode | ) | [virtual] |
Ends a modal dialog, passing a value to be returned from the ShowModal() invocation.
retCode | The value that should be returned by ShowModal. |
int wxDialog::GetAffirmativeId | ( | ) | const |
Gets the identifier of the button which works like standard OK button in this dialog.
virtual wxWindow* wxDialog::GetContentWindow | ( | ) | const [virtual] |
Override this to return a window containing the main content of the dialog.
This is particularly useful when the dialog implements pages, such as wxPropertySheetDialog, and allows the layout adaptation code to know that only the pages need to be made scrollable.
int wxDialog::GetEscapeId | ( | ) | const |
Gets the identifier of the button to map presses of ESC
button to.
bool wxDialog::GetLayoutAdaptationDone | ( | ) | const |
Returns true if the dialog has been adapted, usually by making it scrollable to work with a small display.
int wxDialog::GetLayoutAdaptationLevel | ( | ) | const |
Gets a value representing the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.
Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog.
wxDialogLayoutAdaptationMode wxDialog::GetLayoutAdaptationMode | ( | ) | const |
Gets the adaptation mode, overriding the global adaptation flag.
static wxDialogLayoutAdapter* wxDialog::GetLayoutAdapter | ( | ) | [static] |
A static function getting the current layout adapter object.
wxArrayInt& wxDialog::GetMainButtonIds | ( | ) |
Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.
int wxDialog::GetReturnCode | ( | ) | const |
Gets the return code for this window.
wxToolBar* wxDialog::GetToolBar | ( | ) | const |
On PocketPC, a dialog is automatically provided with an empty toolbar.
This function allows you to access the toolbar and add tools to it. Removing tools and adding arbitrary controls are not currently supported.
This function is not available on any other platform.
virtual void wxDialog::Iconize | ( | bool | iconize = true |
) | [virtual] |
Iconizes or restores the dialog.
Windows only.
iconize | If true, iconizes the dialog box; if false, shows and restores it. |
Reimplemented from wxTopLevelWindow.
virtual bool wxDialog::IsIconized | ( | ) | const [virtual] |
Returns true if the dialog box is iconized.
Windows only.
Reimplemented from wxTopLevelWindow.
static bool wxDialog::IsLayoutAdaptationEnabled | ( | ) | [static] |
A static function returning true if layout adaptation is enabled for all dialogs.
bool wxDialog::IsMainButtonId | ( | wxWindowID | id | ) | const |
Returns true if id is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.
virtual bool wxDialog::IsModal | ( | ) | const [virtual] |
Returns true if the dialog box is modal, false otherwise.
void wxDialog::OnSysColourChanged | ( | wxSysColourChangedEvent & | event | ) |
The default handler for wxEVT_SYS_COLOUR_CHANGED.
event | The colour change event. |
void wxDialog::SetAffirmativeId | ( | int | id | ) |
Sets the identifier to be used as OK button.
When the button with this identifier is pressed, the dialog calls wxWindow::Validate() and wxWindow::TransferDataFromWindow() and, if they both return true, closes the dialog with wxID_OK return code.
Also, when the user presses a hardware OK button on the devices having one or the special OK button in the PocketPC title bar, an event with this id is generated.
By default, the affirmative id is wxID_OK.
void wxDialog::SetEscapeId | ( | int | id | ) |
Sets the identifier of the button which should work like the standard "Cancel" button in this dialog.
When the button with this id is clicked, the dialog is closed. Also, when the user presses ESC
key in the dialog or closes the dialog using the close button in the title bar, this is mapped to the click of the button with the specified id.
By default, the escape id is the special value wxID_ANY meaning that wxID_CANCEL button is used if it's present in the dialog and otherwise the button with GetAffirmativeId() is used. Another special value for id is wxID_NONE meaning that ESC
presses should be ignored. If any other value is given, it is interpreted as the id of the button to map the escape key to.
void wxDialog::SetIcon | ( | const wxIcon & | icon | ) |
Sets the icon for this dialog.
icon | The icon to associate with this dialog. |
Reimplemented from wxTopLevelWindow.
void wxDialog::SetIcons | ( | const wxIconBundle & | icons | ) | [virtual] |
Sets the icons for this dialog.
icons | The icons to associate with this dialog. |
Reimplemented from wxTopLevelWindow.
void wxDialog::SetLayoutAdaptationDone | ( | bool | done | ) |
Marks the dialog as having been adapted, usually by making it scrollable to work with a small display.
void wxDialog::SetLayoutAdaptationLevel | ( | int | level | ) |
Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.
Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog.
void wxDialog::SetLayoutAdaptationMode | ( | wxDialogLayoutAdaptationMode | mode | ) |
Sets the adaptation mode, overriding the global adaptation flag.
static wxDialogLayoutAdapter* wxDialog::SetLayoutAdapter | ( | wxDialogLayoutAdapter * | adapter | ) | [static] |
A static function for setting the current layout adapter object, returning the old adapter.
If you call this, you should delete the old adapter object.
void wxDialog::SetModal | ( | bool | flag | ) |
Allows the programmer to specify whether the dialog box is modal (Show() blocks control until the dialog is hidden) or modeless (control returns immediately).
flag | If true, the dialog will be modal, otherwise it will be modeless. |
void wxDialog::SetReturnCode | ( | int | retCode | ) |
Sets the return code for this window.
A return code is normally associated with a modal dialog, where ShowModal() returns a code to the application. The function EndModal() calls SetReturnCode().
retCode | The integer return code, usually a control identifier. |
virtual bool wxDialog::Show | ( | bool | show = 1 |
) | [virtual] |
Hides or shows the dialog.
The preferred way of dismissing a modal dialog is to use EndModal().
show | If true, the dialog box is shown and brought to the front, otherwise the box is hidden. If false and the dialog is modal, control is returned to the calling program. |
Reimplemented from wxWindow.
virtual int wxDialog::ShowModal | ( | ) | [virtual] |
Shows a modal dialog.
Program flow does not return until the dialog has been dismissed with EndModal().
Notice that it is possible to call ShowModal() for a dialog which had been previously shown with Show(), this allows to make an existing modeless dialog modal. However ShowModal() can't be called twice without intervening EndModal() calls.
Note that this function creates a temporary event loop which takes precedence over the application's main event loop (see wxEventLoopBase) and which is destroyed when the dialog is dismissed. This also results in a call to wxApp::ProcessPendingEvents().
Reimplemented in wxMultiChoiceDialog, wxSingleChoiceDialog, wxColourDialog, wxDirDialog, wxFileDialog, wxFontDialog, wxMessageDialog, wxPrintDialog, wxPageSetupDialog, and wxTextEntryDialog.
![]() |
[ top ] |