wx.Dialog

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 Scrolled Dialogs for further details.

Dialogs usually contain 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 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).

Modal and Modeless

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

# In Python we don't have to worry about the stack vs. the heap, however
# that means that dialogs do need to be destroyed. The typical pattern for
# dialog usage looks something like this:
def AskUser(self):
    try:
        dlg = MyAskDialog(self)
        if dlg.ShowModal() == wx.ID_OK:
            # do something here
            print('Hello')
        else:
            # handle dialog being cancelled or ended by some other button
            ...
    finally:
        # explicitly cause the dialog to destroy itself
        dlg.Destroy()

You can achieve the same result with dialogs by using simpler code:

# Things can be made a little simpler in Python by using the dialog as a
# context manager, using the with statement, like this:
def AskUser(self):
    with MyAskDialog(self) as dlg:
        if dlg.ShowModal() == wx.ID_OK:
            # do something here
            print('Hello')
        else:
            # handle dialog being cancelled or ended by some other button
            ...

    # The dialog is automatically destroyed on exit from the context manager

Window Styles

An application can define a wx.CloseEvent handler for the dialog to respond to system close events. This class supports the following styles:

• 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 resizable 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.

• THICK_FRAME: Display a thick frame around the window.

• wx.STAY_ON_TOP: The dialog stays on top of all other windows.

• NO_3D: This style is obsolete and doesn’t do anything any more, don’t use it in any new code.

• 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 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).

• wx.DIALOG_EX_METAL: On macOS, 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.

Events Emitted by this Class

Handlers bound for the following event types will receive one of the wx.CloseEvent parameters.

• EVT_CLOSE: The dialog is being closed by the user or programmatically (see wx.Window.Close ). The user may generate this event clicking the close button (typically the ‘X’ on the top-right of the title bar) if it’s present (see the CLOSE_BOX style).

• EVT_INIT_DIALOG: Process a wxEVT_INIT_DIALOG event. See wx.InitDialogEvent.

See also

Dialog Overview, wx.Frame, Validator Overview

Class Hierarchy

Inheritance diagram for class Dialog:

Control Appearance

wxMSW

wxMAC

wxGTK

Known Subclasses

wx.ColourDialog, wx.CredentialEntryDialog , wx.DirDialog, wx.FileDialog, wx.FindReplaceDialog, wx.FontDialog, wx.GenericProgressDialog, wx.html.HtmlHelpDialog, wx.MessageDialog, wx.MultiChoiceDialog, wx.NumberEntryDialog, wx.propgrid.PGArrayEditorDialog, wx.PrintAbortDialog, wx.adv.PropertySheetDialog, wx.RearrangeDialog, wx.richtext.RichTextStyleOrganiserDialog, wx.SingleChoiceDialog, wx.richtext.SymbolPickerDialog, wx.TextEntryDialog, wx.adv.Wizard

Methods Summary

__init__	Default constructor.
AddMainButtonId	Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog.
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.
Centre	Centres the dialog box on the display.
Create	Used for two-step dialog box construction.
CreateButtonSizer	Creates a sizer with standard buttons.
CreateSeparatedButtonSizer	Creates a sizer with standard buttons using CreateButtonSizer separated from the rest of the dialog contents by a horizontal wx.StaticLine.
CreateSeparatedSizer	Returns the sizer containing the given one with a separating wx.StaticLine if necessarily.
CreateStdDialogButtonSizer	Creates a wx.StdDialogButtonSizer with standard buttons.
CreateTextSizer	Splits text up at newlines and places the lines into wx.StaticText objects with the specified maximum width in a vertical wx.BoxSizer.
DoLayoutAdaptation	Performs layout adaptation, usually if the dialog is too large to fit on the display.
EnableLayoutAdaptation	A static function enabling or disabling layout adaptation for all dialogs.
EndModal	Ends a modal dialog, passing a value to be returned from the ShowModal invocation.
GetAffirmativeId	Gets the identifier of the button which works like standard wx.OK button in this dialog.
GetClassDefaultAttributes
GetContentWindow	Override this to return a window containing the main content of the dialog.
GetEscapeId	Gets the identifier of the button to map presses of ESC button to.
GetLayoutAdaptationDone	Returns True if the dialog has been adapted, usually by making it scrollable to work with a small display.
GetLayoutAdaptationLevel	Gets a value representing the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.
GetLayoutAdaptationMode	Gets the adaptation mode, overriding the global adaptation flag.
GetLayoutAdapter	A static function getting the current layout adapter object.
GetMainButtonIds	Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.
GetReturnCode	Gets the return code for this window.
Iconize	Iconizes or restores the dialog.
IsIconized	Returns True if the dialog box is iconized.
IsLayoutAdaptationEnabled	A static function returning True if layout adaptation is enabled for all dialogs.
IsMainButtonId	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.
IsModal	Returns True if the dialog box is modal, False otherwise.
SetAffirmativeId	Sets the identifier to be used as wx.OK button.
SetEscapeId	Sets the identifier of the button which should work like the standard “Cancel” button in this dialog.
SetIcon	Sets the icon for this dialog.
SetIcons	Sets the icons for this dialog.
SetLayoutAdaptationDone	Marks the dialog as having been adapted, usually by making it scrollable to work with a small display.
SetLayoutAdaptationLevel