wx.Dialog

Inheritance diagram for wx.Dialog:



Description

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.

See also

wx.Frame

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 wx.ID_OK and wx.ID_CANCEL identifiers behave as expected. Starting with wxPython 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).

Window Styles

Window Style Description
wx.CAPTION Puts a caption on the dialog box.
wx.DEFAULT_DIALOG_STYLE Equivalent to a combination of wx.CAPTION, wx.CLOSE_BOX and wx.SYSTEM_MENU (the last one is not used under Unix)
wx.RESIZE_BORDER Display a resizeable frame around the window.
wx.SYSTEM_MENU Display a system menu.
wx.CLOSE_BOX Displays a close box on the frame.
wx.MAXIMIZE_BOX Displays a maximize box on the dialog.
wx.MINIMIZE_BOX Displays a minimize box on the dialog.
wx.THICK_FRAME Display a thick frame around the window.
wx.STAY_ON_TOP The dialog stays on top of all other windows.
wx.NO_3D Under Windows, specifies that the child controls should not have 3D borders unless specified in the control.
wx.DIALOG_NO_PARENT By default, a dialog created with a None 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.
wx.DIALOG_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 wx.EVT_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).
wx.DIALOG_EX_METAL On Mac OS X, frames with this style will be shown with a metallic look. This is an extra style.

Properties Summary

Class API

Methods

__init__(parent, id=-1, title="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_DIALOG_STYLE, name=wx.DialogNameStr)

Constructor. Creates a wx.Dialog.

Parameters:


Returns:

wx.Dialog


CreateButtonSizer(flags)

Creates a sizer with standard buttons. flags is a bit list of the following flags: wx.OK, wx.CANCEL, wx.YES, wx.NO, wx.HELP, wx.NO_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 None, so don’t forget to test that the return value is valid before using it.

Parameters:

  • flags (long)

Returns:

wx.Sizer


CreateSeparatedButtonSizer(flags)

Creates a sizer with standard buttons using CreateButtonSizer separated from the rest of the dialog contents by a horizontal wx.StaticLine.

Parameters:

  • flags (long)

Returns:

wx.Sizer

Note

Please notice that just like CreateButtonSizer this function may return None if no buttons were created.


CreateStdDialogButtonSizer(flags)

Creates a wx.StdDialogButtonSizer with standard buttons. flags is a bit list of the following flags: wx.OK, wx.CANCEL, wx.YES, wx.NO, wx.HELP, wx.NO_DEFAULT.

The sizer lays out the buttons in a manner appropriate to the platform.

Parameters:

  • flags (long)

Returns:

wx.StdDialogButtonSizer


CreateTextSizer(message)

Parameters:

  • message (string)

Returns:

wx.Sizer


EndModal(retCode)

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

Parameters:

  • retCode (int): The value that should be returned by ShowModal.

GetAffirmativeId()

Gets the identifier of the button which works like standard OK button in this dialog.


Returns:

int

See also

SetAffirmativeId


GetEscapeId()

Gets the identifier of the button to map presses of ESC button to.


Returns:

int

See also

SetEscapeId


GetReturnCode()

Gets the return code for this window.


Returns:

int

Note

A return code is normally associated with a modal dialog, where ShowModal returns a code to the application.


IsModal()

Returns True if the dialog box is modal, False otherwise.


Returns:

bool


SetAffirmativeId(id)

Sets the identifier to be used as OK button. When the button with this identifier is pressed, the dialog calls Validate and wx.Window.TransferDataFromWindow and, if they both return True, closes the dialog with wx.ID_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 wx.ID_OK.

Parameters:

  • id (int)

SetEscapeId(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 wx.ID_ANY meaning that wx.ID_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 wx.ID_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.

Parameters:

  • id (int)

SetReturnCode(returnCode)

Sets the return code for this window.

Parameters:

  • returnCode (int)

Note

A return code is normally associated with a modal dialog, where ShowModal returns a code to the application. The function EndModal calls SetReturnCode.


Show(show=True)

Hides or shows the dialog.

Parameters:

  • show (bool): 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.

Note

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


ShowModal()

Shows a modal dialog. Program flow does not return until the dialog has been dismissed with EndModal.


Returns:

int


Properties

AffirmativeId
See GetAffirmativeId and SetAffirmativeId
EscapeId
See GetEscapeId and SetEscapeId
ReturnCode
See GetReturnCode and SetReturnCode