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.
Derived from
wxPanel
wxWindow
wxEvtHandler
wxObject
Include files
<wx/dialog.h>
Remarks
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 on other windows is still possible. You specify the type of dialog with the wxDIALOG_MODAL and wxDIALOG_MODELESS window styles.
A dialog may be loaded from a wxWindows resource file (extension wxr), which may itself be created by Dialog Editor. For details, see The wxWindows resource system, wxWindows resource functions and the resource sample.
An application can define an OnCloseWindow handler for the dialog to respond to system close events.
Window styles
wxDIALOG_MODAL | Specifies that the dialog box will be modal. |
wxCAPTION | Puts a caption on the dialog box. |
wxDEFAULT_DIALOG_STYLE | Equivalent to a combination of wxCAPTION, wxSYSTEM_MENU and wxTHICK_FRAME |
wxRESIZE_BORDER | Display a resizeable frame around the window. |
wxSYSTEM_MENU | Display a system menu. |
wxTHICK_FRAME | Display a thick frame around the window. |
wxSTAY_ON_TOP | The dialog stays on top of all other windows (Windows only). |
wxNO_3D | Under Windows, specifies that the child controls should not have 3D borders unless specified in the control. |
Under Unix or Linux, MWM (the Motif Window Manager) or other window managers reckognizing 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, Resources, Validator overview
Members
wxDialog::wxDialog
wxDialog::~wxDialog
wxDialog::Centre
wxDialog::Create
wxDialog::EndModal
wxDialog::GetReturnCode
wxDialog::GetTitle
wxDialog::Iconize
wxDialog::IsIconized
wxDialog::IsModal
wxDialog::OnCharHook
wxDialog::OnApply
wxDialog::OnCancel
wxDialog::OnOK
wxDialog::OnSysColourChanged
wxDialog::SetModal
wxDialog::SetReturnCode
wxDialog::SetTitle
wxDialog::Show
wxDialog::ShowModal
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 = "dialogBox")
Constructor.
Parameters
parent
id
title
pos
size
style
name
See also
~wxDialog()
Destructor. Deletes any child windows before deleting the physical window.
void Centre(int direction = wxBOTH)
Centres the dialog box on the display.
Parameters
direction
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 = "dialogBox")
Used for two-step dialog box construction. See wxDialog::wxDialog for details.
void 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
int 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
wxString GetTitle() const
Returns the title of the dialog box.
void 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).
bool IsIconized() const
Returns TRUE if the dialog box is iconized. Windows only.
Remarks
Always returns FALSE under Windows since dialogs cannot be iconized.
bool IsModal() const
Returns TRUE if the dialog box is modal, FALSE otherwise.
void OnCharHook(wxKeyEvent& event)
This member is called to allow the window to intercept keyboard events before they are processed by child windows.
For more information, see wxWindow::OnCharHook
Remarks
wxDialog implements this handler to fake a cancel command if the escape key has been pressed. This will dismiss the dialog.
void OnApply(wxCommandEvent& event)
The default handler for the wxID_APPLY identifier.
Remarks
This function calls wxWindow::Validate and wxWindow::TransferDataToWindow.
See also
wxDialog::OnOK, wxDialog::OnCancel
void OnCancel(wxCommandEvent& event)
The default handler for the wxID_CANCEL identifier.
Remarks
The function either calls EndModal(wxID_CANCEL) if the dialog is modal, or sets the return value to wxID_CANCEL and calls Show(FALSE) if the dialog is modeless.
See also
wxDialog::OnOK, wxDialog::OnApply
void OnOK(wxCommandEvent& event)
The default handler for the wxID_OK identifier.
Remarks
The function calls wxWindow::Validate, then wxWindow::TransferDataFromWindow. If this returns TRUE, the function either calls EndModal(wxID_OK) if the dialog is modal, or sets the return value to wxID_OK and calls Show(FALSE) if the dialog is modeless.
See also
wxDialog::OnCancel, wxDialog::OnApply
void 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 wxWindow::OnSysColourChanged to propagate the notification to child windows and controls.
See also
void 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
void 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
void SetTitle(const wxString& title)
Sets the title of the dialog box.
Parameters
title
bool 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.
int 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