.. wxPython Phoenix documentation

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

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

.. include:: headings.inc



.. _wx.ModalDialogHook:

==========================================================================================================================================
|phoenix_title|  **wx.ModalDialogHook**
==========================================================================================================================================

Allows to intercept all modal dialog calls.          

This class can be used to hook into normal modal dialog handling for some special needs. One of the most common use cases is for testing: as automatic tests can't continue if a modal dialog is shown while they run, this class can be used to avoid showing the modal dialogs during unattended execution. :ref:`wx.ModalDialogHook`  can also be used for disabling some background operation while a modal dialog is shown. 

To install a modal dialog hook, you need to derive your own class from this one and implement its pure virtual :meth:`~wx.ModalDialogHook.Enter`  method. Then simply create an object of your class and call :meth:`~wx.ModalDialogHook.Register`  on it to start receiving calls to your overridden :meth:`~wx.ModalDialogHook.Enter`  (and possibly :ref:`wx.Exit`) methods: ::

    class MyModalDialogHook(wx.ModalDialogHook):

        def __init__(self, parent):

            wx.ModalDialogHook.__init__(self, parent)


        def Enter(self, dialog):

            # Just for demonstration purposes, intercept all uses of
            # wx.FileDialog. Notice that self doesn't provide any real
            # sandboxing, of course, the program can still read and write
            # files by not using wx.FileDialog to ask the user for their
            # names.
            if isinstance(dialog, wx.FileDialog):

                wx.LogError("Access to file system disallowed.")

                # Skip showing the file dialog entirely.
                return wx.ID_CANCEL


            self.lastEnter = wx.DateTime.Now()

            # Allow the dialog to be shown as usual.
            return wx.ID_NONE


        def Exit(self, dialog):

            # Again, just for demonstration purposes, show how long did
            # the user take to dismiss the dialog. Notice that we
            # shouldn't use wx.LogMessage() here as self would result in
            # another modal dialog call and hence infinite recursion. In
            # general, the hooks should be as unintrusive as possible.
            wx.LogDebug("%s dialog took %s to be dismissed",
                       dialog.GetClassInfo().GetClassName(),
                       (wx.DateTime.Now() - self.lastEnter).Format())



    if __name__ == '__main__':

        app = wx.App(0)
        self.myHook = MyModalDialogHook(None)
        self.myHook.Register()
        app.MainLoop()



         



.. versionadded:: 2.9.5 
     







|

|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>ModalDialogHook</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.ModalDialogHook_inheritance.png" alt="Inheritance diagram of ModalDialogHook" 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.ModalDialogHook.html" title="wx.ModalDialogHook" alt="" coords="5,5,157,35"/> </map> 
   </p>

|


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

================================================================================ ================================================================================
:meth:`~wx.ModalDialogHook.__init__`                                             Default and trivial constructor.
:meth:`~wx.ModalDialogHook.Enter`                                                Called by wxWidgets before showing any modal dialogs.
:meth:`~wx.ModalDialogHook.Exit`                                                 Called by wxWidgets after dismissing the modal dialog.
:meth:`~wx.ModalDialogHook.Register`                                             Register this hook as being active.
:meth:`~wx.ModalDialogHook.Unregister`                                           Unregister this hook.
================================================================================ ================================================================================


|


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


.. class:: wx.ModalDialogHook(object)

   **Possible constructors**::

       ModalDialogHook()
       
   
   Allows to intercept all modal dialog calls.



   .. method:: __init__(self)

      Default and trivial constructor.                  

      The constructor doesn't do anything, call :meth:`Register`   to make this hook active.                   





   .. method:: Enter(self, dialog)

      Called by wxWidgets before showing any modal dialogs.                  

      Override this to be notified whenever a modal dialog is about to be shown. 

      If the return value of this method is ``ID_NONE``, the dialog is shown as usual and :ref:`wx.Exit`  will be called when it is dismissed. If the return value is anything else, the dialog is not shown at all and its :meth:`wx.Dialog.ShowModal`   simply returns with the given result. In this case, :ref:`wx.Exit`  won't be called neither. 




      :param `dialog`: The dialog about to be shown, never ``None``.   
      :type `dialog`: wx.Dialog






      :rtype: `int`



                  



      :returns: 

         ``wx.ID_NONE`` to continue with showing the dialog or anything else to skip showing the dialog and just return this value from its ShowModal().   








   .. method:: Exit(self, dialog)

      Called by wxWidgets after dismissing the modal dialog.                  

      Notice that it won't be called if :meth:`Enter`   hadn't been called because another modal hook, registered after this one, intercepted the dialog or if our :meth:`Enter`   was called but returned a value different from ``ID_NONE``. 




      :param `dialog`: The dialog that was shown and dismissed, never ``None``.   
      :type `dialog`: wx.Dialog




                  





   .. method:: Register(self)

      Register this hook as being active.                  

      After registering the hook, its :meth:`Enter`   and :ref:`wx.Exit`  methods will be called whenever a modal dialog is shown. 

      Notice that the order of registration matters: the last hook registered is called first, and if its :meth:`Enter`   returns a value different from ``ID_NONE``, the subsequent hooks are skipped. 

      It is an error to register the same hook twice.                   





   .. method:: Unregister(self)

      Unregister this hook.                  

      Notice that is done automatically from the destructor, so usually calling this method explicitly is unnecessary. 

      The hook must be currently registered.                   




