.. 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.EvtHandler:

==========================================================================================================================================
|phoenix_title|  **wx.EvtHandler**
==========================================================================================================================================

A class that can handle events from the windowing system.          

:ref:`wx.Window`  is (and therefore all window classes are) derived from this class. 

When events are received, :ref:`wx.EvtHandler`  invokes the method listed in the event table using itself as the object. When using multiple inheritance  **it is imperative that the** :ref:`wx.EvtHandler` **(-derived) class is the first class inherited**   such that the  ``this``   pointer for the overall object will be identical to the   ``this``   pointer of the  :ref:`wx.EvtHandler`  portion. 







         



.. seealso:: :ref:`How Events are Processed <how events are processed>`, :ref:`wx.EventBlocker`, :ref:`wx.EventLoopBase`    







|

|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>EvtHandler</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.EvtHandler_inheritance.png" alt="Inheritance diagram of EvtHandler" 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.Object.html" title="wx.Object" alt="" coords="5,5,87,35"/> <area shape="rect" id="node2" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="48,83,159,112"/> <area shape="rect" id="node3" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="112,5,213,35"/> </map> 
   </p>

|


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

:ref:`wx.AppConsole`, :ref:`wx.aui.AuiManager`, :ref:`DocManager`, :ref:`Document`, :ref:`wx.EventBlocker`, :ref:`wx.FileSystemWatcher`, :ref:`wx.Menu`, :ref:`wx.MouseEventsManager`, :ref:`wx.adv.NotificationMessage`, :ref:`wx.Process`, :ref:`wx.propgrid.PropertyGridPage`, :ref:`wx.adv.TaskBarIcon`, :ref:`wx.Timer`, :ref:`wx.Validator`, :ref:`View`, :ref:`wx.Window`

|


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

================================================================================ ================================================================================
:meth:`~wx.EvtHandler.__init__`                                                  Constructor.
:meth:`~wx.EvtHandler.AddFilter`                                                 Add an event filter whose FilterEvent() method will be called for each and every event processed by wxWidgets.
:meth:`~wx.EvtHandler.AddPendingEvent`                                           Post an event to be processed later.
:meth:`~wx.EvtHandler.Bind`                                                      Bind an event to an event handler.
:meth:`~wx.EvtHandler.Connect`                                                   Make an entry in the dynamic event table for an event binding.
:meth:`~wx.EvtHandler.DeletePendingEvents`                                       Deletes all events queued on this event handler using :ref:`wx.QueueEvent`  or :meth:`~EvtHandler.AddPendingEvent` .
:meth:`~wx.EvtHandler.Disconnect`                                                Remove an event binding by removing its entry in the dynamic event table.
:meth:`~wx.EvtHandler.GetEvtHandlerEnabled`                                      Returns ``True`` if the event handler is enabled, ``False`` otherwise.
:meth:`~wx.EvtHandler.GetNextHandler`                                            Returns the pointer to the next handler in the chain.
:meth:`~wx.EvtHandler.GetPreviousHandler`                                        Returns the pointer to the previous handler in the chain.
:meth:`~wx.EvtHandler.IsUnlinked`                                                Returns ``True`` if the next and the previous handler pointers of this event handler instance are ``None``.
:meth:`~wx.EvtHandler.ProcessEvent`                                              Processes an event, searching event tables and calling zero or more suitable event handler function(s).
:meth:`~wx.EvtHandler.ProcessEventLocally`                                       Try to process the event in this handler and all those chained to it.
:meth:`~wx.EvtHandler.ProcessPendingEvents`                                      Processes the pending events previously queued using :ref:`wx.QueueEvent`  or :meth:`~EvtHandler.AddPendingEvent` ; you must call this function only if you are sure there are pending events for this handler, otherwise a  ``CHECK``   will fail.
:meth:`~wx.EvtHandler.QueueEvent`                                                Queue event for a later processing.
:meth:`~wx.EvtHandler.RemoveFilter`                                              Remove a filter previously installed with :meth:`~EvtHandler.AddFilter` .
:meth:`~wx.EvtHandler.SafelyProcessEvent`                                        Processes an event by calling :ref:`wx.ProcessEvent`  and handles any exceptions that occur in the process.
:meth:`~wx.EvtHandler.SetEvtHandlerEnabled`                                      Enables or disables the event handler.
:meth:`~wx.EvtHandler.SetNextHandler`                                            Sets the pointer to the next handler.
:meth:`~wx.EvtHandler.SetPreviousHandler`                                        Sets the pointer to the previous handler.
:meth:`~wx.EvtHandler.TryAfter`                                                  Method called by :ref:`wx.ProcessEvent`  as last resort.
:meth:`~wx.EvtHandler.TryBefore`                                                 Method called by :ref:`wx.ProcessEvent`  before examining this object event tables.
:meth:`~wx.EvtHandler.Unbind`                                                    Disconnects the event handler binding for event from `self`.
:meth:`~wx.EvtHandler.Unlink`                                                    Unlinks this event handler from the chain it's part of (if any); then links the "previous" event handler to the "next" one (so that the chain won't be interrupted).
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.EvtHandler.EvtHandlerEnabled`                                         See :meth:`~wx.EvtHandler.GetEvtHandlerEnabled` and :meth:`~wx.EvtHandler.SetEvtHandlerEnabled`
:attr:`~wx.EvtHandler.NextHandler`                                               See :meth:`~wx.EvtHandler.GetNextHandler` and :meth:`~wx.EvtHandler.SetNextHandler`
:attr:`~wx.EvtHandler.PreviousHandler`                                           See :meth:`~wx.EvtHandler.GetPreviousHandler` and :meth:`~wx.EvtHandler.SetPreviousHandler`
================================================================================ ================================================================================


|


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


.. class:: wx.EvtHandler(Object, Trackable)

   **Possible constructors**::

       EvtHandler()
       
   
   A class that can handle events from the windowing system.



   .. method:: __init__(self)

      Constructor.                   





   .. staticmethod:: AddFilter(filter)

      Add an event filter whose FilterEvent() method will be called for each and every event processed by wxWidgets.                  

      The filters are called in ``LIFO`` order and :ref:`wx.App`  is registered as an event filter by default. The pointer must remain valid until it's removed with :meth:`RemoveFilter`   and is not deleted by :ref:`wx.EvtHandler`. 

                


      :param `filter`: 
      :type `filter`: wx.EventFilter






      .. versionadded:: 2.9.3 
     








   .. method:: AddPendingEvent(self, event)

      Post an event to be processed later.                  

      This function is similar to :ref:`wx.QueueEvent`  but can't be used to post events from worker threads for the event objects with :ref:`String`  fields (i.e. in practice most of them) because of an unsafe use of the same :ref:`String`  object which happens because the :ref:`String`  field in the original `event`  object and its copy made internally by this function share the same string buffer internally. Use :ref:`wx.QueueEvent`  to avoid this. 

      A copy of `event`  is made by the function, so the original can be deleted as soon as function returns (it is common that the original is created on the stack). This requires that the :meth:`wx.Event.Clone`   method be implemented by event so that it can be duplicated and stored until it gets processed. 




      :param `event`: Event to add to the pending events queue.   
      :type `event`: wx.Event




                  





   .. method:: Bind(self, event, handler, source=None, id=wx.ID_ANY, id2=wx.ID_ANY)

      Bind an event to an event handler.
      
      :param event: One of the ``EVT_`` event binder objects that
                            specifies the type of event to bind.
      
      :param handler: A callable object to be invoked when the
                                event is delivered to self.  Pass ``None`` to
                                disconnect an event handler.
      
      :param source: Sometimes the event originates from a
                              different window than self, but you still
                              want to catch it in self.  (For example, a
                              button event delivered to a frame.)  By
                              passing the source of the event, the event
                              handling system is able to differentiate
                              between the same event type from different
                              controls.
      
      :param id: Used to spcify the event source by ``ID`` instead
                      of instance.
      
      :param id2: Used when it is desirable to bind a handler
                        to a range of IDs, such as with ``EVT_MENU_RANGE``.



   .. method:: Connect(self, id, lastId, eventType, func)

      Make an entry in the dynamic event table for an event binding.  





   .. method:: DeletePendingEvents(self)

      Deletes all events queued on this event handler using :ref:`wx.QueueEvent`  or :meth:`AddPendingEvent` .                  

      Use with care because the events which are deleted are (obviously) not processed and this may have unwanted consequences (e.g. user actions events will be lost).                   





   .. method:: Disconnect(self, id, lastId=-1, eventType=wxEVT_NULL, func=None)

      Remove an event binding by removing its entry in the dynamic event table. 

      :rtype: `bool`








   .. method:: GetEvtHandlerEnabled(self)

      Returns ``True`` if the event handler is enabled, ``False`` otherwise.                  

                

      :rtype: `bool`







      .. seealso:: :meth:`SetEvtHandlerEnabled`     








   .. method:: GetNextHandler(self)

      Returns the pointer to the next handler in the chain.                  

                

      :rtype: :ref:`wx.EvtHandler`







      .. seealso:: :meth:`SetNextHandler` , :meth:`GetPreviousHandler` , :meth:`SetPreviousHandler` , :meth:`wx.Window.PushEventHandler` , :meth:`wx.Window.PopEventHandler`     








   .. method:: GetPreviousHandler(self)

      Returns the pointer to the previous handler in the chain.                  

                

      :rtype: :ref:`wx.EvtHandler`







      .. seealso:: :meth:`SetPreviousHandler` , :meth:`GetNextHandler` , :meth:`SetNextHandler` , :meth:`wx.Window.PushEventHandler` , :meth:`wx.Window.PopEventHandler`     








   .. method:: IsUnlinked(self)

      Returns ``True`` if the next and the previous handler pointers of this event handler instance are ``None``.                  

                

      :rtype: `bool`







      .. versionadded:: 2.9.0 
    







      .. seealso:: :meth:`SetPreviousHandler` , :meth:`SetNextHandler`     








   .. method:: ProcessEvent(self, event)

      Processes an event, searching event tables and calling zero or more suitable event handler function(s).                  

      Normally, your application would not call this function: it is called in the wxWidgets implementation to dispatch incoming user interface events to the framework (and application). 

      However, you might need to call it if implementing new functionality (such as a new control) where you define new event types, as opposed to allowing the user to override virtual functions. 

      Notice that you don't usually need to override :ref:`wx.ProcessEvent`  to customize the event handling, overriding the specially provided :meth:`TryBefore`   and :meth:`TryAfter`   functions is usually enough. For example, :ref:`wx.MDIParentFrame`  may override :meth:`TryBefore`   to ensure that the menu events are processed in the active child frame before being processed in the parent frame itself. 

      The normal order of event table searching is as follows:

      - :meth:`wx.App.FilterEvent`   is called. If it returns anything but  ``-1``   (default) the processing stops here. 
      - :meth:`TryBefore`   is called (this is where :ref:`wx.Validator`  are taken into account for :ref:`wx.Window`  objects). If this returns ``True``, the function exits. 
      - If the object is disabled (via a call to :meth:`wx.EvtHandler.SetEvtHandlerEnabled` ) the function skips to step (7). 
      - Dynamic event table of the handlers bound using :meth:`Bind<>`   is searched. If a handler is found, it is executed and the function returns ``True`` unless the handler used :meth:`wx.Event.Skip`   to indicate that it didn't handle the event in which case the search continues. 
      - Static events table of the handlers bound using event table macros is searched for this event handler. If this fails, the base class event table is tried, and so on until no more tables exist or an appropriate function was found. If a handler is found, the same logic as in the previous step applies. 
      - The search is applied down the entire chain of event handlers (usually the chain has a length of one). This chain can be formed using :meth:`wx.EvtHandler.SetNextHandler` : 

      .. figure:: _static/images/overviews/overview_events_chain.png
         :align: center


      |


        (referring to the image, if ``A->ProcessEvent``   is called and it doesn't handle the event,   ``B->ProcessEvent``   will be called and so on...). Note that in the case of  :ref:`wx.Window`  you can build a stack of event handlers (see :meth:`wx.Window.PushEventHandler`   for more info). If any of the handlers of the chain return ``True``, the function exits. 
      - :meth:`TryAfter`   is called: for the :ref:`wx.Window`  object this may propagate the event to the window parent (recursively). If the event is still not processed, :ref:`wx.ProcessEvent`  on TheApp object is called as the last step. 




      Notice that steps (2)-(6) are performed in :meth:`ProcessEventLocally`   which is called by this function. 




      :param `event`: Event to process.   
      :type `event`: wx.Event






      :rtype: `bool`



                  



      :returns: 

         ``True`` if a suitable event handler function was found and executed, and the function did not call :meth:`wx.Event.Skip` .  







      .. seealso:: :meth:`SearchEventTable`     








   .. method:: ProcessEventLocally(self, event)

      Try to process the event in this handler and all those chained to it.                  

      As explained in :ref:`wx.ProcessEvent`  documentation, the event handlers may be chained in a doubly-linked list. This function tries to process the event in this handler (including performing any pre-processing done in :meth:`TryBefore` , e.g. applying validators) and all those following it in the chain until the event is processed or the chain is exhausted. 

      This function is called from :ref:`wx.ProcessEvent`  and, in turn, calls :meth:`TryBefore`   and :meth:`TryAfter` . It is not virtual and so cannot be overridden but can, and should, be called to forward an event to another handler instead of :ref:`wx.ProcessEvent`  which would result in a duplicate call to :meth:`TryAfter` , e.g. resulting in all unprocessed events being sent to the application object multiple times. 




      :param `event`: Event to process.   
      :type `event`: wx.Event






      :rtype: `bool`



                  



      :returns: 

         ``True`` if this handler of one of those chained to it processed the event.   







      .. versionadded:: 2.9.1 
    








   .. method:: ProcessPendingEvents(self)

      Processes the pending events previously queued using :ref:`wx.QueueEvent`  or :meth:`AddPendingEvent` ; you must call this function only if you are sure there are pending events for this handler, otherwise a  ``CHECK``   will fail.                   

      The real processing still happens in :ref:`wx.ProcessEvent`  which is called by this function. 

      Note that this function needs a valid application object (see :meth:`wx.AppConsole.GetInstance` ) because :ref:`wx.App`  holds the list of the event handlers with pending events and this function manipulates that list.                   





   .. method:: QueueEvent(self, event)

      Queue event for a later processing.                  

      This method is similar to :ref:`wx.ProcessEvent`  but while the latter is synchronous, i.e. the event is processed immediately, before the function returns, this one is asynchronous and returns immediately while the event will be processed at some later time (usually during the next event loop iteration). 

      Another important difference is that this method takes ownership of the `event`  parameter, i.e. it will delete it itself. This implies that the event should be allocated on the heap and that the pointer can't be used any more after the function returns (as it can be deleted at any moment). 

      :ref:`wx.QueueEvent`  can be used for inter-thread communication from the worker threads to the main thread, it is safe in the sense that it uses locking internally and avoids the problem mentioned in :meth:`AddPendingEvent`   documentation by ensuring that the `event`  object is not used by the calling thread any more. Care should still be taken to avoid that some fields of this object are used by it, notably any :ref:`String`  members of the event object must not be shallow copies of another :ref:`String`  object as this would result in them still using the same string buffer behind the scenes. For example: ::

                      def FunctionInAWorkerThread(strs):

                          evt = wx.CommandEvent()

                          evt.SetString(strs)

                          wx.TheApp.QueueEvent(evt)



      Note that you can use :ref:`ThreadEvent`  instead of :ref:`wx.CommandEvent`  to avoid this problem: ::

                      def FunctionInAWorkerThread(strs):

                          evt = wx.ThreadEvent()
                          evt.SetString(strs)

                          # wx.ThreadEvent.Clone() makes sure that the internal wx.String
                          # member is not shared by other string instances:
                          wx.TheApp.QueueEvent(evt.Clone())



      Finally notice that this method automatically wakes up the event loop if it is currently idle by calling :ref:`wx.WakeUpIdle`  so there is no need to do it manually when using it. 




      :param `event`: A heap-allocated event to be queued, :ref:`wx.QueueEvent`  takes ownership of it. This parameter shouldn't be  ``NULL`` .    
      :type `event`: wx.Event




                  



      .. versionadded:: 2.9.0 
    








   .. staticmethod:: RemoveFilter(filter)

      Remove a filter previously installed with :meth:`AddFilter` .                  

      It's an error to remove a filter that hadn't been previously added or was already removed. 

                


      :param `filter`: 
      :type `filter`: wx.EventFilter






      .. versionadded:: 2.9.3 
     








   .. method:: SafelyProcessEvent(self, event)

      Processes an event by calling :ref:`wx.ProcessEvent`  and handles any exceptions that occur in the process.                  

      If an exception is thrown in event handler, :meth:`wx.App.OnExceptionInMainLoop`   is called. 




      :param `event`: Event to process.  
      :type `event`: wx.Event






      :rtype: `bool`



                  



      :returns: 

         ``True`` if the event was processed, ``False`` if no handler was found or an exception was thrown.  







      .. seealso:: :meth:`wx.Window.HandleWindowEvent`     








   .. method:: SetEvtHandlerEnabled(self, enabled)

      Enables or disables the event handler.                  




      :param `enabled`: ``True`` if the event handler is to be enabled, ``False`` if it is to be disabled.  
      :type `enabled`: bool




                  



      .. note:: 

         You can use this function to avoid having to remove the event handler from the chain, for example when implementing a dialog editor and changing from edit to test mode.  







      .. seealso:: :meth:`GetEvtHandlerEnabled`     








   .. method:: SetNextHandler(self, handler)

      Sets the pointer to the next handler.                  




      :param `handler`: The event handler to be set as the next handler. Cannot be ``None``.  
      :type `handler`: wx.EvtHandler




                  



      .. note:: 

         See :ref:`wx.ProcessEvent`  for more info about how the chains of event handlers are internally used. Also remember that :ref:`wx.EvtHandler`  uses double-linked lists and thus if you use this function, you should also call :meth:`SetPreviousHandler`   on the argument passed to this function: ::

                            handlerA.SetNextHandler(handlerB)
                            handlerB.SetPreviousHandler(handlerA)









      .. seealso:: :ref:`How Events are Processed <how events are processed>`    








   .. method:: SetPreviousHandler(self, handler)

      Sets the pointer to the previous handler.                  

      All remarks about :meth:`SetNextHandler`   apply to this function as well. 




      :param `handler`: The event handler to be set as the previous handler. Cannot be ``None``.  
      :type `handler`: wx.EvtHandler




                  



      .. seealso:: :ref:`How Events are Processed <how events are processed>`    








   .. method:: TryAfter(self, event)

      Method called by :ref:`wx.ProcessEvent`  as last resort.                  

      This method can be overridden to implement post-processing for the events which were not processed anywhere else. 

      The base class version handles forwarding the unprocessed events to :ref:`wx.App`  at :ref:`wx.EvtHandler`  level and propagating them upwards the window child-parent chain at :ref:`wx.Window`  level and so should usually be called when overriding this method: ::

          class MyClass(public BaseClass): # something inheriting from wx.EvtHandler

          ...
              def TryAfter(self, event):
                  if (BaseClass.TryAfter(self, event))
                      return True

                  return self.MyPostProcess(event)



                


      :param `event`: 
      :type `event`: wx.Event




      :rtype: `bool`







      .. seealso:: :ref:`wx.ProcessEvent`    








   .. method:: TryBefore(self, event)

      Method called by :ref:`wx.ProcessEvent`  before examining this object event tables.                  

      This method can be overridden to hook into the event processing logic as early as possible. You should usually call the base class version when overriding this method, even if :ref:`wx.EvtHandler`  itself does nothing here, some derived classes do use this method, e.g. :ref:`wx.Window`  implements support for :ref:`wx.Validator`  in it. 

      Example: ::

          class MyClass(BaseClass):  # something inheriting from wx.EvtHandler

          ...
              def TryBefore(self, event):
                  if (self.MyPreProcess(event)):
                      return True

                  return BaseClass.TryBefore(self, event)



                


      :param `event`: 
      :type `event`: wx.Event




      :rtype: `bool`







      .. seealso:: :ref:`wx.ProcessEvent`    








   .. method:: Unbind(self, event, source=None, id=wx.ID_ANY, id2=wx.ID_ANY, handler=None)

      Disconnects the event handler binding for event from `self`.
      Returns ``True`` if successful.



   .. method:: Unlink(self)

      Unlinks this event handler from the chain it's part of (if any); then links the "previous" event handler to the "next" one (so that the chain won't be interrupted).                  

      E.g. if before calling :meth:`Unlink`   you have the following chain: 

      .. figure:: _static/images/overviews/evthandler_unlink_before.png
         :align: center


      |


        then after calling B->:meth:`Unlink`   you'll have:  

      .. figure:: _static/images/overviews/evthandler_unlink_after.png
         :align: center


      |



                 



      .. versionadded:: 2.9.0 
     








   .. attribute:: EvtHandlerEnabled

      See :meth:`~wx.EvtHandler.GetEvtHandlerEnabled` and :meth:`~wx.EvtHandler.SetEvtHandlerEnabled`


   .. attribute:: NextHandler

      See :meth:`~wx.EvtHandler.GetNextHandler` and :meth:`~wx.EvtHandler.SetNextHandler`


   .. attribute:: PreviousHandler

      See :meth:`~wx.EvtHandler.GetPreviousHandler` and :meth:`~wx.EvtHandler.SetPreviousHandler`