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 scrolling dialogs for further details.
Dialogs 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 ID_OK and 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).
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:
def AskUser(self):
dlg = MyAskDialog(self)
if dlg.ShowModal() == wx.ID_OK:
# do something here
print 'Hello'
# else: dialog was cancelled or some another button pressed
dlg.Destroy()
You can achieve the same result with dialogs by using simpler code:
def AskUser(self):
dlg = MyAskDialog(self)
if dlg.ShowModal() == wx.ID_OK:
# do something here
print 'Hello'
# no need to call Destroy() here
An application can define a CloseEvent handler for the dialog to respond to system close events. This class supports the following 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.
Handlers bound for the following event types will receive a CloseEvent parameter.
See also
ColourDialog, DirDialog, FileDialog, FindReplaceDialog, FontDialog, GenericProgressDialog, MessageDialog, MultiChoiceDialog, PropertySheetDialog, RichTextStyleOrganiserDialog, SingleChoiceDialog, SymbolPickerDialog, TextEntryDialog, Wizard
__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 StaticLine. |
CreateSeparatedSizer | Returns the sizer containing the given one with a separating StaticLine if necessarily. |
CreateStdDialogButtonSizer | Creates a StdDialogButtonSizer with standard buttons. |
CreateTextSizer | Splits text up at newlines and places the lines into StaticText objects in a vertical 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 OK button in this dialog. |
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 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 | Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog. |
SetLayoutAdaptationMode | Sets the adaptation mode, overriding the global adaptation flag. |
SetLayoutAdapter | A static function for setting the current layout adapter object, returning the old adapter. |
SetReturnCode | Sets the return code for this window. |
Show | Hides or shows the dialog. |
ShowModal | Shows an application-modal dialog. |
ShowWindowModal | Shows a dialog modal to the parent top level window only. |
__enter__ | |
__exit__ |
A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the screen.
Possible constructors:
Dialog()
Dialog(parent, id=ID_ANY, title='', pos=DefaultPosition,
size=DefaultSize, style=DEFAULT_DIALOG_STYLE, name=DialogNameStr)
Overloaded Implementations:
__init__ (self)
Default constructor.
__init__ (self, parent, id=ID_ANY, title=’‘, pos=DefaultPosition, size=DefaultSize, style=DEFAULT_DIALOG_STYLE, name=DialogNameStr)
Constructor.
Parameters: |
|
---|
See also
Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog.
Parameters: | id (int) – |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
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.
Return type: | bool |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
Centres the dialog box on the display.
Parameters: | direction (int) – May be HORIZONTAL, VERTICAL or BOTH. |
---|
Used for two-step dialog box construction.
Parameters: | |
---|---|
Return type: | bool |
See also
Creates a sizer with standard buttons.
flags is a bit list of the following flags: OK, CANCEL, YES, NO, APPLY, CLOSE, HELP, 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) – |
---|---|
Return type: | Sizer |
Creates a sizer with standard buttons using CreateButtonSizer separated from the rest of the dialog contents by a horizontal StaticLine.
This is a combination of CreateButtonSizer and CreateSeparatedSizer .
Parameters: | flags (long) – |
---|---|
Return type: | Sizer |
Note
Just like CreateButtonSizer , this function may return None if no buttons were created.
Returns the sizer containing the given one with a separating StaticLine if necessarily.
This function is useful for creating the sizer containing footer-like contents in dialog boxes. It will add a separating static line only if it conforms to the current platform convention (currently it is not added under Mac where the use of static lines for grouping is discouraged and is added elsewhere).
Parameters: | sizer (Sizer) – The sizer to wrap, must be not None. |
---|---|
Return type: | Sizer |
Returns: | The sizer wrapping the input one or possibly the input sizer itself if no wrapping is necessary. |
New in version 2.9.2.
Creates a StdDialogButtonSizer with standard buttons.
flags is a bit list of the following flags: OK, CANCEL, YES, NO, APPLY, CLOSE, HELP, NO_DEFAULT.
The sizer lays out the buttons in a manner appropriate to the platform.
Parameters: | flags (long) – |
---|---|
Return type: | StdDialogButtonSizer |
Splits text up at newlines and places the lines into StaticText objects in a vertical BoxSizer.
Parameters: | message (string) – |
---|---|
Return type: | Sizer |
Performs layout adaptation, usually if the dialog is too large to fit on the display.
Return type: | bool |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
A static function enabling or disabling layout adaptation for all dialogs.
Parameters: | enable (bool) – |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
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. |
---|
See also
Gets the identifier of the button which works like standard OK button in this dialog.
Return type: | int |
---|
See also
Override this to return a window containing the main content of the dialog.
This is particularly useful when the dialog implements pages, such as PropertySheetDialog, and allows the layout adaptation code to know that only the pages need to be made scrollable.
Return type: | Window |
---|
Gets the identifier of the button to map presses of ESC button to.
Return type: | int |
---|
See also
Returns True if the dialog has been adapted, usually by making it scrollable to work with a small display.
Return type: | bool |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
Gets a value representing the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.
Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog.
Return type: | int |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
Gets the adaptation mode, overriding the global adaptation flag.
Return type: | DialogLayoutAdaptationMode |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
A static function getting the current layout adapter object.
Return type: | DialogLayoutAdapter |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.
Return type: | list of integers |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
Gets the return code for this window.
Return type: | int |
---|
Note
A return code is normally associated with a modal dialog, where ShowModal returns a code to the application.
See also
Iconizes or restores the dialog.
Windows only.
Parameters: | iconize (bool) – If True, iconizes the dialog box; if False, shows and restores it. |
---|
Note
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).
Returns True if the dialog box is iconized.
Windows only.
Return type: | bool |
---|
Note
Always returns False under Windows since dialogs cannot be iconized.
A static function returning True if layout adaptation is enabled for all dialogs.
Return type: | bool |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
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.
Parameters: | id (int) – |
---|---|
Return type: | bool |
Availability
Only available for MSW.
See also
Automatic scrolling dialogs (for more on layout adaptation)
Returns True if the dialog box is modal, False otherwise.
Return type: | bool |
---|
Sets the identifier to be used as OK button.
When the button with this identifier is pressed, the dialog calls Window.Validate and Window.TransferDataFromWindow and, if they both return True, closes the dialog with the affirmative id 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 ID_OK.
Parameters: | id (int) – |
---|
See also
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 ID_ANY meaning that 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 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) – |
---|
Sets the icon for this dialog.
Parameters: | icon (Icon) – The icon to associate with this dialog. |
---|
See also
Sets the icons for this dialog.
Parameters: | icons (IconBundle) – The icons to associate with this dialog. |
---|
See also
Marks the dialog as having been adapted, usually by making it scrollable to work with a small display.
Parameters: | done (bool) – |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.
Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog.
Parameters: | level (int) – |
---|
See also
Automatic scrolling dialogs (for more on layout adaptation)
Sets the adaptation mode, overriding the global adaptation flag.
Parameters: | mode (DialogLayoutAdaptationMode) – |
---|
See also
DialogLayoutAdaptationMode , Automatic scrolling dialogs (for more on layout adaptation)
A static function for setting the current layout adapter object, returning the old adapter.
If you call this, you should delete the old adapter object.
Parameters: | adapter (DialogLayoutAdapter) – |
---|---|
Return type: | DialogLayoutAdapter |
Sets the return code for this window.
A return code is normally associated with a modal dialog, where ShowModal returns a code to the application. The function EndModal calls SetReturnCode .
Parameters: | retCode (int) – The integer return code, usually a control identifier. |
---|
See also
Hides or shows the dialog.
The preferred way of dismissing a modal dialog is to use EndModal .
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. |
---|---|
Return type: | bool |
Shows an application-modal dialog.
Program flow does not return until the dialog has been dismissed with EndModal .
Notice that it is possible to call ShowModal for a dialog which had been previously shown with Show , this allows to make an existing modeless dialog modal. However ShowModal can’t be called twice without intervening EndModal calls.
Note that this function creates a temporary event loop which takes precedence over the application’s main event loop (see EventLoopBase) and which is destroyed when the dialog is dismissed. This also results in a call to App.ProcessPendingEvents .
Return type: | int |
---|---|
Returns: | The value set with SetReturnCode . |
See also
Shows a dialog modal to the parent top level window only.
Unlike ShowModal , dialogs shown with this function only prevent the user from interacting with their parent frame only but not with the rest of the application. They also don’t block the program execution but instead return immediately, as Show , and generate a wxEVT_WINDOW_MODAL_DIALOG_CLOSED event later when the dialog is closed.
Currently this function is only fully implemented in wxOSX ports, under the other platforms it behaves like ShowModal (but also sends the above mentioned event).
New in version 2.9.0.
See GetAffirmativeId and SetAffirmativeId
See GetContentWindow
See GetEscapeId and SetEscapeId
See GetMainButtonIds
See GetReturnCode and SetReturnCode