.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2018 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.Dialog:

==========================================================================================================================================
|phoenix_title|  **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 :ref:`Automatic Scrolled Dialogs <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 :meth:`~wx.Dialog.SetAffirmativeId`  and :meth:`~wx.Dialog.SetEscapeId`. 

Also notice that the :meth:`~wx.Dialog.CreateButtonSizer`  should be used to create the buttons appropriate for the current platform and positioned correctly (including their order which is platform-dependent). 



|phoenix_title| 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 :meth:`~wx.Dialog.ShowModal`  method while to show a dialog modelessly you simply use :meth:`~wx.Dialog.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



.. _Dialog-styles:

|styles| Window Styles
================================

An application can define a :ref:`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 :ref:`application's top level window <wx.App>`  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  :meth:`~wx.Dialog.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.  

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.




.. _Dialog-events:

|events| Events Emitted by this Class
=====================================

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

- EVT_CLOSE: The dialog is being closed by the user or programmatically (see :meth:`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) or by clicking a button with the   ``ID_CANCEL``   or   ``ID_OK``   ids.   
- EVT_INIT_DIALOG: Process a  ``wxEVT_INIT_DIALOG``   event. See  :ref:`wx.InitDialogEvent`.  






.. seealso:: :ref:`Dialog Overview <dialog overview>`, :ref:`wx.Frame`, :ref:`Validator Overview <validator overview>`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>Dialog</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.Dialog_inheritance.png" alt="Inheritance diagram of Dialog" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="5,5,107,35"/> <area shape="rect" id="node6" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="57,83,168,112"/> <area shape="rect" id="node2" href="wx.Object.html" title="wx.Object" alt="" coords="131,5,212,35"/> <area shape="rect" id="node3" href="wx.NonOwnedWindow.html" title="wx.NonOwnedWindow" alt="" coords="34,237,192,267"/> <area shape="rect" id="node5" href="wx.TopLevelWindow.html" title="wx.TopLevelWindow" alt="" coords="42,315,184,344"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window" alt="" coords="69,160,157,189"/> <area shape="rect" id="node7" href="wx.Dialog.html" title="wx.Dialog" alt="" coords="72,392,153,421"/> </map> 
   </p>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.dialog.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/../no_appearance.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/wx.dialog.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|


|sub_classes| Known Subclasses
==============================

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

|


|method_summary| Methods Summary
================================

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


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.Dialog.AffirmativeId`                                                 See :meth:`~wx.Dialog.GetAffirmativeId` and :meth:`~wx.Dialog.SetAffirmativeId`
:attr:`~wx.Dialog.ContentWindow`                                                 See :meth:`~wx.Dialog.GetContentWindow`
:attr:`~wx.Dialog.EscapeId`                                                      See :meth:`~wx.Dialog.GetEscapeId` and :meth:`~wx.Dialog.SetEscapeId`
:attr:`~wx.Dialog.LayoutAdaptationDone`                                          See :meth:`~wx.Dialog.GetLayoutAdaptationDone` and :meth:`~wx.Dialog.SetLayoutAdaptationDone`
:attr:`~wx.Dialog.LayoutAdaptationLevel`                                         See :meth:`~wx.Dialog.GetLayoutAdaptationLevel` and :meth:`~wx.Dialog.SetLayoutAdaptationLevel`
:attr:`~wx.Dialog.LayoutAdaptationMode`                                          See :meth:`~wx.Dialog.GetLayoutAdaptationMode` and :meth:`~wx.Dialog.SetLayoutAdaptationMode`
:attr:`~wx.Dialog.MainButtonIds`                                                 See :meth:`~wx.Dialog.GetMainButtonIds`
:attr:`~wx.Dialog.ReturnCode`                                                    See :meth:`~wx.Dialog.GetReturnCode` and :meth:`~wx.Dialog.SetReturnCode`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.Dialog(TopLevelWindow)

   **Possible constructors**::

       Dialog()
       
       Dialog(parent, id=ID_ANY, title=EmptyString, pos=DefaultPosition,
              size=DefaultSize, style=DEFAULT_DIALOG_STYLE, name=DialogNameStr)
       
   
   A dialog box is a window with a title bar and sometimes a system menu,
   which can be moved around the screen.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **__init__** `(self)`
      
      Default constructor.                   
      
      
      
      
      **~~~**

      
      **__init__** `(self, parent, id=ID_ANY, title=EmptyString, pos=DefaultPosition, size=DefaultSize, style=DEFAULT_DIALOG_STYLE, name=DialogNameStr)`
      
      Constructor.                  
      
      
      
      
      :param `parent`: Can be ``None``, a frame or another dialog box.   
      :type `parent`: wx.Window
      :param `id`: An identifier for the dialog. A value of -1 is taken to mean a default.   
      :type `id`: wx.WindowID
      :param `title`: The title of the dialog.   
      :type `title`: string
      :param `pos`: The dialog position. The value DefaultPosition indicates a default position, chosen by either the windowing system or wxWidgets, depending on platform.   
      :type `pos`: wx.Point
      :param `size`: The dialog size. The value DefaultSize indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform.   
      :type `size`: wx.Size
      :param `style`: The window style.   
      :type `style`: long
      :param `name`: Used to associate a name with the window, allowing the application user to set Motif resource values for individual dialog boxes.  
      :type `name`: string
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      .. seealso:: :meth:`Create`     
      
      
      
      
      
      
      
      **~~~**






   .. method:: AddMainButtonId(self, id)

      Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog.                  

                


      :param `id`: 
      :type `id`: wx.WindowID






      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: CanDoLayoutAdaptation(self)

      Returns ``True`` if this dialog can and should perform layout adaptation using :meth:`DoLayoutAdaptation` , usually if the dialog is too large to fit on the display.                  

                

      :rtype: `bool`







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: Centre(self, direction=BOTH)

      Centres the dialog box on the display.                  




      :param `direction`: May be ``wx.HORIZONTAL``, ``wx.VERTICAL`` or ``wx.BOTH``.   
      :type `direction`: int




                  





   .. method:: Create(self, parent, id=ID_ANY, title=EmptyString, pos=DefaultPosition, size=DefaultSize, style=DEFAULT_DIALOG_STYLE, name=DialogNameStr)

      Used for two-step dialog box construction.                  

                


      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `title`: 
      :type `title`: string
      :param `pos`: 
      :type `pos`: wx.Point
      :param `size`: 
      :type `size`: wx.Size
      :param `style`: 
      :type `style`: long
      :param `name`: 
      :type `name`: string




      :rtype: `bool`







      .. seealso:: :ref:`wx.Dialog`    








   .. method:: CreateButtonSizer(self, 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.APPLY``, ``wx.CLOSE``, ``wx.HELP``, ``wx.NO_DEFAULT``. 

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

      This function uses :meth:`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.                  


      :param `flags`: 
      :type `flags`: long




      :rtype: :ref:`wx.Sizer`








   .. method:: CreateSeparatedButtonSizer(self, flags)

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


      This is a combination of  :meth:`CreateButtonSizer`   and :meth:`CreateSeparatedSizer` .                  


      :param `flags`: 
      :type `flags`: long




      :rtype: :ref:`wx.Sizer`







      .. note:: 

         Just like :meth:`CreateButtonSizer` , this function may return ``None`` if no buttons were created.  








   .. method:: CreateSeparatedSizer(self, sizer)

      Returns the sizer containing the given one with a separating :ref:`wx.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). 




      :param `sizer`: The sizer to wrap, must be non-NULL.   
      :type `sizer`: wx.Sizer






      :rtype: :ref:`wx.Sizer`



                  



      :returns: 

         The sizer wrapping the input one or possibly the input sizer itself if no wrapping is necessary.   







      .. versionadded:: 2.9.2 
    








   .. method:: CreateStdDialogButtonSizer(self, flags)

      Creates a :ref:`wx.StdDialogButtonSizer`  with standard buttons.                  

      `flags`  is a bit list of the following flags: ``wx.OK``, ``wx.CANCEL``, ``wx.YES``, ``wx.NO``, ``wx.APPLY``, ``wx.CLOSE``, ``wx.HELP``, ``wx.NO_DEFAULT``. 

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


      :param `flags`: 
      :type `flags`: long




      :rtype: :ref:`wx.StdDialogButtonSizer`








   .. method:: CreateTextSizer(self, message)

      Splits text up at newlines and places the lines into :ref:`wx.StaticText`  objects in a vertical :ref:`wx.BoxSizer`.                  


      :param `message`: 
      :type `message`: string




      :rtype: :ref:`wx.Sizer`








   .. method:: DoLayoutAdaptation(self)

      Performs layout adaptation, usually if the dialog is too large to fit on the display.                  

                

      :rtype: `bool`







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. staticmethod:: EnableLayoutAdaptation(enable)

      A static function enabling or disabling layout adaptation for all dialogs.                  

                


      :param `enable`: 
      :type `enable`: bool






      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: EndModal(self, retCode)

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




      :param `retCode`: The value that should be returned by ShowModal.  
      :type `retCode`: int




                  



      .. seealso:: :meth:`ShowModal` , :meth:`GetReturnCode` , :meth:`SetReturnCode`     








   .. method:: GetAffirmativeId(self)

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

                

      :rtype: `int`







      .. seealso:: :meth:`SetAffirmativeId`     








   .. method:: GetContentWindow(self)

      Override this to return a window containing the main content of the dialog.                  

      This is particularly useful when the dialog implements pages, such as :ref:`wx.adv.PropertySheetDialog`, and allows the :ref:`layout adaptation code <layout adaptation code>`  to know that only the pages need to be made scrollable.                  

      :rtype: :ref:`wx.Window`








   .. method:: GetEscapeId(self)

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

                

      :rtype: `int`







      .. seealso:: :meth:`SetEscapeId`     








   .. method:: GetLayoutAdaptationDone(self)

      Returns ``True`` if the dialog has been adapted, usually by making it scrollable to work with a small display.                  

                

      :rtype: `bool`







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: GetLayoutAdaptationLevel(self)

      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. 

                

      :rtype: `int`







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: GetLayoutAdaptationMode(self)

      Gets the adaptation mode, overriding the global adaptation flag.                  

                

      :rtype: :ref:`wx.DialogLayoutAdaptationMode`







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. staticmethod:: GetLayoutAdapter()

      A static function getting the current layout adapter object.                  

                

      :rtype: :ref:`wx.DialogLayoutAdapter`







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: GetMainButtonIds(self)

      Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.                  

                

      :rtype: `list of integers`







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: GetReturnCode(self)

      Gets the return code for this window.                  

                

      :rtype: `int`







      .. note:: 

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







      .. seealso:: :meth:`SetReturnCode` , :meth:`ShowModal` , :meth:`EndModal`     








   .. method:: Iconize(self, iconize=True)

      Iconizes or restores the dialog.                  

      Windows only. 




      :param `iconize`: If ``True``, iconizes the dialog box; if ``False``, shows and restores it.  
      :type `iconize`: bool




                  



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








   .. method:: IsIconized(self)

      Returns ``True`` if the dialog box is iconized.                  

      Windows only. 

                

      :rtype: `bool`







      .. note:: 

         Always returns ``False`` under Windows since dialogs cannot be iconized.   








   .. staticmethod:: IsLayoutAdaptationEnabled()

      A static function returning ``True`` if layout adaptation is enabled for all dialogs.                  

                

      :rtype: `bool`







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: IsMainButtonId(self, id)

      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.                  



                


      :param `id`: 
      :type `id`: wx.WindowID




      :rtype: `bool`







      .. availability:: Only available for MSW.  







      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: IsModal(self)

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

      :rtype: `bool`








   .. method:: SetAffirmativeId(self, id)

      Sets the identifier to be used as ``wx.OK`` button.                  

      When the button with this identifier is pressed, the dialog calls :meth:`wx.Window.Validate`   and :meth:`wx.Window.TransferDataFromWindow`   and, if they both return ``True``, closes the dialog with the affirmative id return code. 

      Also, when the user presses a hardware ``wx.OK`` button on the devices having one or the special ``wx.OK`` button in the PocketPC title bar, an event with this id is generated. 

      By default, the affirmative id is ``wx.ID_OK``. 

                


      :param `id`: 
      :type `id`: int






      .. seealso:: :meth:`GetAffirmativeId` , :meth:`SetEscapeId`     








   .. method:: SetEscapeId(self, 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 :meth:`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. 

                


      :param `id`: 
      :type `id`: int






      .. note:: 

         This method should be used for custom modal dialog implemented in wxWidgets itself, native dialogs such as :ref:`wx.MessageDialog`  or :ref:`wx.FileDialog`, handle  ``ESC``   presses in their own way which cannot be customized.    








   .. method:: SetIcon(self, icon)

      Sets the icon for this dialog.                  




      :param `icon`: The icon to associate with this dialog.  
      :type `icon`: wx.Icon




                  



      .. seealso:: :ref:`wx.Icon`    








   .. method:: SetIcons(self, icons)

      Sets the icons for this dialog.                  




      :param `icons`: The icons to associate with this dialog.  
      :type `icons`: wx.IconBundle




                  



      .. seealso:: :ref:`wx.IconBundle`    








   .. method:: SetLayoutAdaptationDone(self, done)

      Marks the dialog as having been adapted, usually by making it scrollable to work with a small display.                  

                


      :param `done`: 
      :type `done`: bool






      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: SetLayoutAdaptationLevel(self, level)

      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. 

                


      :param `level`: 
      :type `level`: int






      .. seealso:: :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. method:: SetLayoutAdaptationMode(self, mode)

      Sets the adaptation mode, overriding the global adaptation flag.                  

                


      :param `mode`: 
      :type `mode`: wx.DialogLayoutAdaptationMode






      .. seealso:: :ref:`wx.DialogLayoutAdaptationMode`, :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`  (for more on layout adaptation)   








   .. staticmethod:: SetLayoutAdapter(adapter)

      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. 

                


      :param `adapter`: 
      :type `adapter`: wx.DialogLayoutAdapter




      :rtype: :ref:`wx.DialogLayoutAdapter`







      .. seealso:: :ref:`wx.DialogLayoutAdapter`, :ref:`Automatic Scrolled Dialogs <automatic scrolled dialogs>`    








   .. method:: SetReturnCode(self, retCode)

      Sets the return code for this window.                  

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




      :param `retCode`: The integer return code, usually a control identifier.  
      :type `retCode`: int




                  



      .. seealso:: :meth:`GetReturnCode` , :meth:`ShowModal` , :meth:`EndModal`     








   .. method:: Show(self, show=1)

      Hides or shows the dialog.                  

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




      :param `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.   
      :type `show`: bool






      :rtype: `bool`



                  





   .. method:: ShowModal(self)

      Shows an application-modal dialog.                  

      Program flow does not return until the dialog has been dismissed with :meth:`EndModal` . 

      Notice that it is possible to call :meth:`ShowModal`   for a dialog which had been previously shown with :meth:`Show` , this allows to make an existing modeless dialog modal. However :meth:`ShowModal`   can't be called twice without intervening :meth:`EndModal`   calls. 

      Note that this function creates a temporary event loop which takes precedence over the application's main event loop (see :ref:`wx.EventLoopBase`) and which is destroyed when the dialog is dismissed. This also results in a call to :meth:`wx.App.ProcessPendingEvents` . 

                

      :rtype: `int`







      :returns: 

         The value set with :meth:`SetReturnCode` .  







      .. seealso:: :meth:`ShowWindowModal` , :meth:`ShowWindowModalThenDo` , :meth:`EndModal` , :meth:`GetReturnCode` , :meth:`SetReturnCode`     








   .. method:: ShowWindowModal(self)

      Shows a dialog modal to the parent top level window only.                  

      Unlike :meth:`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 :meth:`Show` , and generate a wxEVT_WINDOW_MODAL_DIALOG_CLOSED event (:ref:`wx.WindowModalDialogEvent`) later when the dialog is closed. 

      Currently this function is only fully implemented in wxOSX ports, under the other platforms it behaves like :meth:`ShowModal`   (but also sends the above mentioned event). 

                 



      .. versionadded:: 2.9.0 
     







      .. seealso:: :ref:`wx.WindowModalDialogEvent`, :meth:`ShowWindowModalThenDo`   








   .. method:: __enter__(self)




   .. method:: __exit__(self, exc_type, exc_val, exc_tb)




   .. attribute:: AffirmativeId

      See :meth:`~wx.Dialog.GetAffirmativeId` and :meth:`~wx.Dialog.SetAffirmativeId`


   .. attribute:: ContentWindow

      See :meth:`~wx.Dialog.GetContentWindow`


   .. attribute:: EscapeId

      See :meth:`~wx.Dialog.GetEscapeId` and :meth:`~wx.Dialog.SetEscapeId`


   .. attribute:: LayoutAdaptationDone

      See :meth:`~wx.Dialog.GetLayoutAdaptationDone` and :meth:`~wx.Dialog.SetLayoutAdaptationDone`


   .. attribute:: LayoutAdaptationLevel

      See :meth:`~wx.Dialog.GetLayoutAdaptationLevel` and :meth:`~wx.Dialog.SetLayoutAdaptationLevel`


   .. attribute:: LayoutAdaptationMode

      See :meth:`~wx.Dialog.GetLayoutAdaptationMode` and :meth:`~wx.Dialog.SetLayoutAdaptationMode`


   .. attribute:: MainButtonIds

      See :meth:`~wx.Dialog.GetMainButtonIds`


   .. attribute:: ReturnCode

      See :meth:`~wx.Dialog.GetReturnCode` and :meth:`~wx.Dialog.SetReturnCode`