wxDialog

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 usually used to allow the user to make some choice or to answer a question.

Derived from

wxTopLevelWindow
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 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();
    }

    void AskUser()
    {
        MyAskDialog dlg(...);
        if ( dlg.ShowModal() == wxID_OK )
            ...

        // no need to call Destroy() here
    }

Window styles

wxCAPTION	Puts a caption on the dialog box.
wxDEFAULT_DIALOG_STYLE	Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and wxSYSTEM_MENU (the last one is not used under Unix)
wxRESIZE_BORDER	Display a resizeable frame around the window.
wxSYSTEM_MENU	Display a system menu.
wxCLOSE_BOX	Displays a close box on the frame.
wxMAXIMIZE_BOX	Displays a maximize box on the dialog.
wxMINIMIZE_BOX	Displays a minimize box on the dialog.
wxTHICK_FRAME	Display a thick frame around the window.
wxSTAY_ON_TOP	The dialog stays on top of all other windows.
wxNO_3D	Under Windows, specifies that the child controls should not have 3D borders unless specified in the control.
wxDIALOG_NO_PARENT	By default, a dialog created with a NULL parent window will be given the application's top level window as parent. Use this style to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.
wxDIALOG_EX_CONTEXTHELP	Under Windows, puts a query button on the caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send a wxEVT_HELP event if the user clicked on an application window. Note that this is an extended style and must be set by calling SetExtraStyle before Create is called (two-step construction).
wxDIALOG_EX_METAL	On Mac OS X, frames with this style will be shown with a metallic look. This is an extra style.

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::~wxDialog
wxDialog::Centre
wxDialog::Create
wxDialog::CreateButtonSizer
wxDialog::CreateStdDialogButtonSizer
wxDialog::DoOK
wxDialog::EndModal
wxDialog::GetAffirmativeId
wxDialog::GetReturnCode
wxDialog::GetTitle
wxDialog::GetToolBar
wxDialog::Iconize
wxDialog::IsIconized
wxDialog::IsModal
wxDialog::OnApply
wxDialog::OnCancel
wxDialog::OnOK
wxDialog::OnSysColourChanged
wxDialog::SetAffirmativeId
wxDialog::SetIcon
wxDialog::SetIcons
wxDialog::SetModal
wxDialog::SetReturnCode
wxDialog::SetTitle
wxDialog::Show
wxDialog::ShowModal

wxDialog::wxDialog

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

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. A value of (-1, -1) indicates a default position, chosen by either the windowing system or wxWidgets, depending on platform.

size

The dialog size. A value of (-1, -1) indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform.

style

The window style. See wxDialog.

name

Used to associate a name with the window, allowing the application user to set Motif resource values for individual dialog boxes.

See also

wxDialog::Create

wxDialog::~wxDialog

~wxDialog()

Destructor. Deletes any child windows before deleting the physical window.

wxDialog::Centre

void Centre(int direction = wxBOTH)

Centres the dialog box on the display.

Parameters

direction

May be wxHORIZONTAL, wxVERTICAL or wxBOTH.

wxDialog::Create

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.

wxDialog::CreateButtonSizer

wxSizer* 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 simply calls CreateStdDialogButtonSizer.

wxDialog::CreateStdDialogButtonSizer

wxStdDialogButtonSizer* 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::DoOK

virtual 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::EndModal

void EndModal(int retCode)

Ends a modal dialog, passing a value to be returned from the wxDialog::ShowModal invocation.

Parameters

retCode

The value that should be returned by ShowModal.

See also

wxDialog::ShowModal, wxDialog::GetReturnCode, wxDialog::SetReturnCode

wxDialog::GetAffirmativeId

int GetAffirmativeId() const

Gets the identifier to be used when the user presses an OK button in a PocketPC titlebar.

See also

wxDialog::SetAffirmativeId

wxDialog::GetReturnCode

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

wxDialog::GetTitle

wxString GetTitle() const

Returns the title of the dialog box.

wxDialog::GetToolBar

wxToolBar* 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::Iconize

void Iconize(const bool iconize)

Iconizes or restores the dialog. Windows only.

Parameters

iconize

If true, iconizes the dialog box; if false, shows and restores it.

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::IsIconized

bool IsIconized() const

Returns true if the dialog box is iconized. Windows only.

Remarks

Always returns false under Windows since dialogs cannot be iconized.

wxDialog::IsModal

bool IsModal() const

Returns true if the dialog box is modal, false otherwise.

wxDialog::OnApply

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

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

wxDialog::OnOK

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

wxDialog::OnSysColourChanged

void OnSysColourChanged(wxSysColourChangedEvent& event)

The default handler for wxEVT_SYS_COLOUR_CHANGED.

Parameters

event

The colour change 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

wxSysColourChangedEvent

wxDialog::SetAffirmativeId

void SetAffirmativeId(int id)

Sets the identifier to be used when the user presses an OK button in a PocketPC titlebar. By default, this is wxID_OK.

See also

wxDialog::GetAffirmativeId

wxDialog::SetIcon

void SetIcon(const wxIcon& icon)

Sets the icon for this dialog.

Parameters

icon

The icon to associate with this dialog.

See also wxIcon.

wxDialog::SetIcons

void SetIcons(const wxIconBundle& icons)

Sets the icons for this dialog.

Parameters

icons

The icons to associate with this dialog.

See also wxIconBundle.

wxDialog::SetModal

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

If true, the dialog will be modal, otherwise it will be modeless.

wxDialog::SetReturnCode

void SetReturnCode(int retCode)

Sets the return code for this window.

Parameters

retCode

The integer return code, usually a control identifier.

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::SetTitle

void SetTitle(const wxString& title)

Sets the title of the dialog box.

Parameters

title

The dialog box title.

wxDialog::Show

bool Show(const bool show)

Hides or shows the dialog.

Parameters

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.

Remarks

The preferred way of dismissing a modal dialog is to use wxDialog::EndModal.

wxDialog::ShowModal

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