********* wx.Dialog ********* Inheritance diagram for `wx.Dialog`: | .. inheritance-diagram:: 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. .. seealso:: `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 <#SetAffirmativeId>`_ and `SetEscapeId <#SetEscapeId>`_. Also notice that the `CreateButtonSizer <#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 Dialogs ^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 <#ShowModal>`_ method while to show a dialog modelessly you simply use `Show <#Show>`_, just as with frames. Derived From ^^^^^^^^^^^^^ * `wx.TopLevelWindow `_ * `wx.Window `_ * `wx.EvtHandler `_ * `wx.Object `_ Known Subclasses ^^^^^^^^^^^^^^^^ `wx.ColourDialog `_, `wx.DirDialog `_, `wx.FileDialog `_, `wx.FindReplaceDialog `_, `wx.FontDialog `_, `wx.MessageDialog `_, `wx.MultiChoiceDialog `_, `wx.NumberEntryDialog `_, `wx.PasswordEntryDialog `_, `wx.ProgressDialog `_, `wx.SingleChoiceDialog `_, `wx.TextEntryDialog `_ 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 <#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. ================================================== ================================================== Methods Summary ^^^^^^^^^^^^^^^ * `__init__ <#__init__>`_ * `CreateButtonSizer <#CreateButtonSizer>`_ * `CreateSeparatedButtonSizer <#CreateSeparatedButtonSizer>`_ * `CreateStdDialogButtonSizer <#CreateStdDialogButtonSizer>`_ * `CreateTextSizer <#CreateTextSizer>`_ * `EndModal <#EndModal>`_ * `GetAffirmativeId <#GetAffirmativeId>`_ * `GetEscapeId <#GetEscapeId>`_ * `GetReturnCode <#GetReturnCode>`_ * `IsModal <#IsModal>`_ * `SetAffirmativeId <#SetAffirmativeId>`_ * `SetEscapeId <#SetEscapeId>`_ * `SetReturnCode <#SetReturnCode>`_ * `Show <#Show>`_ * `ShowModal <#ShowModal>`_ Properties Summary ^^^^^^^^^^^^^^^^^^ * `AffirmativeId <#AffirmativeId>`_ * `EscapeId <#EscapeId>`_ * `ReturnCode <#ReturnCode>`_ Class API ========= Methods ^^^^^^^ .. method:: __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:** * `parent` (`wx.Window `_) * `id` (int) * `title` (string) * `pos` (`wx.Point `_) * `size` (`wx.Size `_) * `style` (long) * `name` (string) | **Returns:** `wx.Dialog `_ -------- .. method:: 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 <#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 `_ -------- .. method:: CreateSeparatedButtonSizer(flags) Creates a sizer with standard buttons using `CreateButtonSizer <#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 <#CreateButtonSizer>`_ this function may return ``None`` if no buttons were created. -------- .. method:: 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 `_ -------- .. method:: CreateTextSizer(message) | **Parameters:** * `message` (string) | **Returns:** `wx.Sizer `_ -------- .. method:: EndModal(retCode) Ends a modal dialog, passing a value to be returned from the `ShowModal <#ShowModal>`_ invocation. **Parameters:** * `retCode` (int): The value that should be returned by `ShowModal <#ShowModal>`_. .. seealso:: `ShowModal <#ShowModal>`_, `GetReturnCode <#GetReturnCode>`_, `SetReturnCode <#SetReturnCode>`_ -------- .. method:: GetAffirmativeId() Gets the identifier of the button which works like standard ``OK`` button in this dialog. | **Returns:** `int` .. seealso:: `SetAffirmativeId <#SetAffirmativeId>`_ -------- .. method:: GetEscapeId() Gets the identifier of the button to map presses of ``ESC`` button to. | **Returns:** `int` .. seealso:: `SetEscapeId <#SetEscapeId>`_ -------- .. method:: GetReturnCode() Gets the return code for this window. | **Returns:** `int` .. note:: A return code is normally associated with a modal dialog, where `ShowModal <#ShowModal>`_ returns a code to the application. .. seealso:: `SetReturnCode <#SetReturnCode>`_, `ShowModal <#ShowModal>`_, `EndModal <#EndModal>`_ -------- .. method:: IsModal() Returns ``True`` if the dialog box is modal, ``False`` otherwise. | **Returns:** `bool` -------- .. method:: 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) .. seealso:: `GetAffirmativeId <#GetAffirmativeId>`_, `SetEscapeId <#SetEscapeId>`_ -------- .. method:: 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 <#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) -------- .. method:: 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 <#ShowModal>`_ returns a code to the application. The function `EndModal <#EndModal>`_ calls `SetReturnCode`. .. seealso:: `GetReturnCode <#GetReturnCode>`_, `ShowModal <#ShowModal>`_, `EndModal <#EndModal>`_ -------- .. method:: 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 <#EndModal>`_. -------- .. method:: ShowModal() Shows a modal dialog. Program flow does not return until the dialog has been dismissed with `EndModal <#EndModal>`_. | **Returns:** `int` -------- Properties ^^^^^^^^^^ .. attribute:: AffirmativeId See `GetAffirmativeId <#GetAffirmativeId>`_ and `SetAffirmativeId <#SetAffirmativeId>`_ .. attribute:: EscapeId See `GetEscapeId <#GetEscapeId>`_ and `SetEscapeId <#SetEscapeId>`_ .. attribute:: ReturnCode See `GetReturnCode <#GetReturnCode>`_ and `SetReturnCode <#SetReturnCode>`_