wxDialogA 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. Dialog Buttons The dialog 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).
Derived from
wxTopLevelWindow Include files <wx/dialog.h> Modal and modeless dialogs 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, although this code snippet:
void AskUser() { MyAskDialog *dlg = new MyAskDialog(...); if ( dlg->ShowModal() == wxID_OK ) ... //else: dialog was cancelled or some another button pressed dlg->Destroy(); }works, you can also achieve the same result by using a simpler code fragment below:
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. Window 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. See also Generic window styles. See also wxDialog overview, wxFrame, Validator overview Members
wxDialog::wxDialog
wxDialog::wxDialogwxDialog() 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 = "dialogBox") Constructor. Parameters parent
id
title
pos
size
style
name
See also
wxDialog::~wxDialog~wxDialog() Destructor. Deletes any child windows before deleting the physical window.
wxDialog::Centrevoid Centre(int direction = wxBOTH) Centres the dialog box on the display. Parameters direction
wxDialog::Createbool Create(wxWindow* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE, const wxString& name = "dialogBox") Used for two-step dialog box construction. See wxDialog::wxDialog for details.
wxDialog::CreateButtonSizerwxSizer* CreateButtonSizer(long flags) Creates a sizer with standard buttons. flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, 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.
wxDialog::CreateSeparatedButtonSizerwxSizer* CreateSeparatedButtonSizer(long flags) Creates a sizer with standard buttons using CreateButtonSizer separated from the rest of the dialog contents by a horizontal wxStaticLine. Please notice that just like CreateButtonSizer() this function may return NULL if no buttons were created.
wxDialog::CreateStdDialogButtonSizerwxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags) Creates a wxStdDialogButtonSizer with standard buttons. flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO_DEFAULT. The sizer lays out the buttons in a manner appropriate to the platform.
wxDialog::DoOKvirtual bool DoOK() 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.
wxDialog::EndModalvoid EndModal(int retCode) Ends a modal dialog, passing a value to be returned from the wxDialog::ShowModal invocation. Parameters retCode
See also wxDialog::ShowModal, wxDialog::GetReturnCode, wxDialog::SetReturnCode
wxDialog::GetAffirmativeIdint GetAffirmativeId() const Gets the identifier of the button which works like standard OK button in this dialog. See also
wxDialog::GetEscapeIdint GetEscapeId() const Gets the identifier of the button to map presses of ESC button to. See also
wxDialog::GetReturnCodeint GetReturnCode() Gets the return code for this window. Remarks A return code is normally associated with a modal dialog, where wxDialog::ShowModal returns a code to the application. See also wxDialog::SetReturnCode, wxDialog::ShowModal, wxDialog::EndModal
wxDialog::GetToolBarwxToolBar* GetToolBar() const On PocketPC, a dialog is automatically provided with an empty toolbar. GetToolBar 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.
wxDialog::Iconizevoid Iconize(const bool iconize) Iconizes or restores the dialog. Windows only. Parameters iconize
Remarks Note that in Windows, iconization has no effect since dialog boxes cannot be iconized. However, applications may need to explicitly restore dialog boxes under Motif which have user-iconizable frames, and under Windows calling Iconize(false) will bring the window to the front, as does Show(true).
wxDialog::IsIconizedbool IsIconized() const Returns true if the dialog box is iconized. Windows only. Remarks Always returns false under Windows since dialogs cannot be iconized.
wxDialog::IsModalbool IsModal() const Returns true if the dialog box is modal, false otherwise.
wxDialog::OnSysColourChangedvoid OnSysColourChanged(wxSysColourChangedEvent& event) The default handler for wxEVT_SYS_COLOUR_CHANGED. Parameters event
Remarks Changes the dialog's colour to conform to the current settings (Windows only). Add an event table entry for your dialog class if you wish the behaviour to be different (such as keeping a user-defined background colour). If you do override this function, call wxEvent::Skip to propagate the notification to child windows and controls. See also
wxDialog::SetAffirmativeIdvoid SetAffirmativeId(int id) Sets the identifier to be used as OK button. When the button with this identifier is pressed, the dialog calls 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. See also wxDialog::GetAffirmativeId, wxDialog::SetEscapeId
wxDialog::SetEscapeIdvoid 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.
wxDialog::SetIconvoid SetIcon(const wxIcon& icon) Sets the icon for this dialog. Parameters icon
See also wxIcon.
wxDialog::SetIconsvoid SetIcons(const wxIconBundle& icons) Sets the icons for this dialog. Parameters icons
See also wxIconBundle.
wxDialog::SetModalvoid SetModal(const bool flag) NB: This function is deprecated and doesn't work for all ports, just use ShowModal to show a modal dialog instead. Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control until the dialog is hidden) or modeless (control returns immediately). Parameters flag
wxDialog::SetReturnCodevoid SetReturnCode(int retCode) Sets the return code for this window. Parameters retCode
Remarks A return code is normally associated with a modal dialog, where wxDialog::ShowModal returns a code to the application. The function wxDialog::EndModal calls SetReturnCode. See also wxDialog::GetReturnCode, wxDialog::ShowModal, wxDialog::EndModal
wxDialog::Showbool Show(const bool show) Hides or shows the dialog. Parameters show
Remarks The preferred way of dismissing a modal dialog is to use wxDialog::EndModal.
wxDialog::ShowModalint ShowModal() Shows a modal dialog. Program flow does not return until the dialog has been dismissed with wxDialog::EndModal. Return value The return value is the value set with wxDialog::SetReturnCode. See also wxDialog::EndModal, wxDialog:GetReturnCode, wxDialog::SetReturnCode
|