*************
wx.EvtHandler
*************

Inheritance diagram for `wx.EvtHandler`:

|

.. inheritance-diagram:: wx.EvtHandler

|

Description
===========

A class that can handle events from the windowing system. `wx.Window <wx.Window.html>`_ (and therefore all window classes) 
are derived from this class.

When events are received, `wx.EvtHandler` invokes the method listed in the event table using itself as the object. 

When using multiple inheritance it is imperative that the `wx.EvtHandler` (-derived) class be the first class inherited 
such that the "self" pointer for the overall object will be identical to the "self" pointer for the `wx.EvtHandler` portion.


Derived From
^^^^^^^^^^^^^

* `wx.Object <wx.Object.html>`_ 


Known Subclasses
^^^^^^^^^^^^^^^^

`wx.App <wx.App.html>`_, `wx.BitmapButton <wx.BitmapButton.html>`_, `wx.BookCtrlBase`, 
`wx.Button <wx.Button.html>`_, `wx.CheckBox <wx.CheckBox.html>`_, `wx.CheckListBox <wx.CheckListBox.html>`_, 
`wx.Choice <wx.Choice.html>`_, `wx.Choicebook <wx.Choicebook.html>`_, `wx.CollapsiblePane <wx.CollapsiblePane.html>`_, 
`wx.ColourDialog <wx.ColourDialog.html>`_, `wx.ColourPickerCtrl <wx.ColourPickerCtrl.html>`_, 
`wx.ComboBox <wx.ComboBox.html>`_, `wx.ContextHelpButton <wx.ContextHelpButton.html>`_, `wx.Control <wx.Control.html>`_, 
`wx.ControlWithItems <wx.ControlWithItems.html>`_, `wx.DatePickerCtrl <wx.DatePickerCtrl.html>`_, 
`wx.DatePickerCtrlBase`, `wx.Dialog <wx.Dialog.html>`_, `wx.DirDialog <wx.DirDialog.html>`_, 
`wx.DirFilterListCtrl`, `wx.DirPickerCtrl <wx.DirPickerCtrl.html>`_, 
`wx.FileDialog <wx.FileDialog.html>`_, `wx.FilePickerCtrl <wx.FilePickerCtrl.html>`_, 
`wx.FindReplaceDialog <wx.FindReplaceDialog.html>`_, `wx.FontDialog <wx.FontDialog.html>`_, `wx.FontPickerCtrl <wx.FontPickerCtrl.html>`_, 
`wx.Frame <wx.Frame.html>`_, `wx.Gauge <wx.Gauge.html>`_, `wx.GenericDatePickerCtrl`, 
`wx.GenericDirCtrl <wx.GenericDirCtrl.html>`_, `wx.HtmlListBox <wx.HtmlListBox.html>`_, `wx.HyperlinkCtrl <wx.HyperlinkCtrl.html>`_, 
`wx.ListBox <wx.ListBox.html>`_, `wx.ListCtrl <wx.ListCtrl.html>`_, `wx.ListView <wx.ListView.html>`_, 
`wx.Listbook <wx.Listbook.html>`_, `wx.MDIChildFrame <wx.MDIChildFrame.html>`_, `wx.MDIClientWindow <wx.MDIClientWindow.html>`_, 
`wx.MDIParentFrame <wx.MDIParentFrame.html>`_, `wx.Menu <wx.Menu.html>`_, `wx.MenuBar <wx.MenuBar.html>`_, 
`wx.MessageDialog <wx.MessageDialog.html>`_, `wx.MiniFrame <wx.MiniFrame.html>`_, `wx.MultiChoiceDialog <wx.MultiChoiceDialog.html>`_, 
`wx.Notebook <wx.Notebook.html>`_, `wx.NotebookPage`, `wx.NumberEntryDialog`, 
`wx.Panel <wx.Panel.html>`_, `wx.PasswordEntryDialog <wx.PasswordEntryDialog.html>`_, `wx.PickerBase <wx.PickerBase.html>`_, 
`wx.PopupTransientWindow <wx.PopupTransientWindow.html>`_, `wx.PopupWindow <wx.PopupWindow.html>`_, 
`wx.PreviewCanvas <wx.PreviewCanvas.html>`_, `wx.PreviewControlBar <wx.PreviewControlBar.html>`_, 
`wx.PreviewFrame <wx.PreviewFrame.html>`_, `wx.Process <wx.Process.html>`_, `wx.ProgressDialog <wx.ProgressDialog.html>`_, 
`wx.PyApp <wx.PyApp.html>`_, `wx.PyAxBaseWindow <wx.PyAxBaseWindow.html>`_, `wx.PyControl <wx.PyControl.html>`_, 
`wx.PyEvtHandler <wx.PyEvtHandler.html>`_, `wx.PyPanel <wx.PyPanel.html>`_, `wx.PyPreviewControlBar <wx.PyPreviewControlBar.html>`_, 
`wx.PyPreviewFrame <wx.PyPreviewFrame.html>`_, `wx.PyScrolledWindow <wx.PyScrolledWindow.html>`_, `wx.PySimpleApp <wx.PySimpleApp.html>`_, 
`wx.PyTimer <wx.PyTimer.html>`_, `wx.PyValidator <wx.PyValidator.html>`_, `wx.PyWidgetTester <wx.PyWidgetTester.html>`_, 
`wx.PyWindow <wx.PyWindow.html>`_, `wx.RadioBox <wx.RadioBox.html>`_, `wx.RadioButton <wx.RadioButton.html>`_, 
`wx.SashLayoutWindow <wx.SashLayoutWindow.html>`_, `wx.SashWindow <wx.SashWindow.html>`_, `wx.ScrollBar <wx.ScrollBar.html>`_, 
`wx.ScrolledWindow <wx.ScrolledWindow.html>`_, `wx.SearchCtrl <wx.SearchCtrl.html>`_, `wx.SimpleHtmlListBox <wx.SimpleHtmlListBox.html>`_, 
`wx.SingleChoiceDialog <wx.SingleChoiceDialog.html>`_, `wx.Slider <wx.Slider.html>`_, `wx.SpinButton <wx.SpinButton.html>`_, 
`wx.SpinCtrl <wx.SpinCtrl.html>`_, `wx.SplashScreen <wx.SplashScreen.html>`_, `wx.SplashScreenWindow`, 
`wx.SplitterWindow <wx.SplitterWindow.html>`_, `wx.StaticBitmap <wx.StaticBitmap.html>`_, `wx.StaticBox <wx.StaticBox.html>`_, 
`wx.StaticLine <wx.StaticLine.html>`_, `wx.StaticText <wx.StaticText.html>`_, `wx.StatusBar <wx.StatusBar.html>`_, 
`wx.TaskBarIcon <wx.TaskBarIcon.html>`_, `wx.TextCtrl <wx.TextCtrl.html>`_, `wx.TextEntryDialog <wx.TextEntryDialog.html>`_, 
`wx.Timer <wx.Timer.html>`_, `wx.TipWindow <wx.TipWindow.html>`_, `wx.ToggleButton <wx.ToggleButton.html>`_, 
`wx.ToolBar <wx.ToolBar.html>`_, `wx.ToolBarBase`, `wx.Toolbook <wx.Toolbook.html>`_, 
`wx.TopLevelWindow <wx.TopLevelWindow.html>`_, `wx.TreeCtrl <wx.TreeCtrl.html>`_, `wx.Treebook <wx.Treebook.html>`_, 
`wx.VListBox <wx.VListBox.html>`_, `wx.VScrolledWindow <wx.VScrolledWindow.html>`_, `wx.Validator <wx.Validator.html>`_, 
`wx.Window <wx.Window.html>`_

Remarks
^^^^^^^

The difference between sending an event (using the `ProcessEvent <#ProcessEvent>`_ method) and posting it is that in 
the first case the event is processed before the function returns, while in the second case, the function returns 
immediately and the event will be processed sometime later (usually during the next event loop iteration).

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 `wx.Event.Clone <../Events/wx.Event.html#Clone>`_ 
method be implemented by `event` so that it can be duplicated and stored until it gets processed.

This is also the method to call for inter-thread communication - it will post events safely between different threads 
which means that this method is thread-safe by using critical sections where needed. In a multi-threaded program, 
you often need to inform the main GUI thread about the status of other working threads and such notification should 
be done using this method.

This method automatically wakes up idle handling if the underlying window system is currently idle and thus would not 
send any idle events. (Waking up idle handling is done calling `wx.WakeUpIdle <../wxFunctions.html#WakeUpIdle>`_).

The normal order of event table searching is as follows:

1. If the object is disabled (via a call to `SetEvtHandlerEnabled <#SetEvtHandlerEnabled>`_) the function skips to step (6).
2. If the object is a `wx.Window <wx.Window.html>`_, `ProcessEvent <#ProcessEvent>`_ is recursively called on the window's 
   `wx.Validator <wx.Validator.html>`_. If this returns ``True``, the function exits.
3. wxWidgets `SearchEventTable` is called for this event handler. If this fails, the base class table is tried, 
   and so on until no more tables exist or an appropriate function was found, in which case the function exits.
4. The search is applied down the entire chain of event handlers (usually the chain has a length of one). If this succeeds, 
   the function exits.
5. If the object is a `wx.Window <wx.Window.html>`_ and the event is a `wx.CommandEvent <../Events/wx.CommandEvent.html>`_, 
   `ProcessEvent <#ProcessEvent>`_ is recursively applied to the parent window's event handler. If this returns ``True``, 
   the function exits.
6. Finally, `ProcessEvent <#ProcessEvent>`_ is called on the `wx.App <wx.App.html>`_ object.


Methods Summary
^^^^^^^^^^^^^^^

* `__init__ <#__init__>`_ 
* `AddPendingEvent <#AddPendingEvent>`_ 
* `Bind <#Bind>`_ 
* `Connect <#Connect>`_ 
* `Disconnect <#Disconnect>`_ 
* `GetEvtHandlerEnabled <#GetEvtHandlerEnabled>`_ 
* `GetNextHandler <#GetNextHandler>`_ 
* `GetPreviousHandler <#GetPreviousHandler>`_ 
* `ProcessEvent <#ProcessEvent>`_ 
* `ProcessPendingEvents <#ProcessPendingEvents>`_ 
* `SetEvtHandlerEnabled <#SetEvtHandlerEnabled>`_ 
* `SetNextHandler <#SetNextHandler>`_ 
* `SetPreviousHandler <#SetPreviousHandler>`_ 
* `Unbind <#Unbind>`_ 

Properties Summary
^^^^^^^^^^^^^^^^^^

* `EvtHandlerEnabled <#EvtHandlerEnabled>`_ 
* `NextHandler <#NextHandler>`_ 
* `PreviousHandler <#PreviousHandler>`_ 

Class API
=========

Methods
^^^^^^^


.. method:: __init__()

   `No docstrings found for this method.` 

--------


.. method:: AddPendingEvent(event)

   This function posts an event to be processed later.

   **Parameters:**

   * `event` (`wx.Event <../Events/wx.Event.html>`_): Event to add to process queue.


.. note:: The difference between sending an event (using the `ProcessEvent <#ProcessEvent>`_ method) 
   and posting it is that in the first case the event is processed before the function returns, while in 
   the second case, the function returns immediately and the event will be processed sometime later 
   (usually during the next event loop iteration).
  

--------

.. method:: Bind(event, handler, source=None, id=-1, id2=-1)

   Bind an event to an event handler.

   **Parameters:**

   * `event` (`wx.Event <../Events/wx.Event.html>`_): One of the ``wx.EVT_*`` objects that specifies the type of event to bind,
   * `handler` (PyObject): A callable object to be invoked when the event is delivered to self. Pass ``None`` to disconnect an event handler.
   * `source` (`wx.Window <wx.Window.html>`_): 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.
   * `id` (int): Used to specify the event source by ID instead of instance.
   * `id2` (int): Used when it is desirable to bind a handler to a range of IDs, such as with ``wx.EVT_MENU_RANGE``.
   

--------

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

   Connects the given function dynamically with the event handler, id and event type. This is an alternative to the use 
   of static event tables.

   **Parameters:**

   * `id` (int): The identifier (or first of the identifier range) to be associated with the event handler function. 
     For the version not taking this argument, it defaults to ``wx.ID_ANY``.
   * `lastId` (int): The second part of the identifier range to be associated with the event handler function.
   * `eventType` (`wx.Object <wx.Object.html>`_): The event type to be associated with this event handler.

--------

.. method:: Disconnect(id=wx.EVT_NONE, lastId=None, eventType=None)

   Disconnects the given function dynamically from the event handler, using the specified parameters as search criteria 
   and returning ``True`` if a matching function has been found and removed. This method can only disconnect functions 
   which have been added using the `Connect <#Connect>`_ method. 

   **Parameters:**

   * `id` (int): The identifier (or first of the identifier range) associated with the event handler function.
   * `lastId` (int): The second part of the identifier range associated with the event handler function.
   * `eventType` (`wx.Object <wx.Object.html>`_): The event type associated with this event handler.

   |  

   **Returns:**

   `bool` 

--------

.. method:: GetEvtHandlerEnabled()

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

   |

   **Returns:**

   `bool` 


.. seealso:: `SetEvtHandlerEnabled <#SetEvtHandlerEnabled>`_
  

--------

.. method:: GetNextHandler()

   Gets the pointer to the next handler in the chain.

   |

   **Returns:**

   `wx.EvtHandler <wx.EvtHandler.html>`_
 

.. seealso:: `SetNextHandler <#SetNextHandler>`_, `GetPreviousHandler <#GetPreviousHandler>`_, 
   `SetPreviousHandler <#SetPreviousHandler>`_, `wx.Window.PushEventHandler <wx.Window.html#PushEventHandler>`_, 
   `wx.Window.PopEventHandler <wx.Window.html#PopEventHandler>`_
  

--------

.. method:: GetPreviousHandler()

   Gets the pointer to the previous handler in the chain.

   |

   **Returns:**

   `wx.EvtHandler <wx.EvtHandler.html>`_
 
 
.. seealso::  `SetPreviousHandler <#SetPreviousHandler>`_ , `GetNextHandler <#GetNextHandler>`_ , `SetNextHandler <#SetNextHandler>`_ , 
    `wx.Window.PushEventHandler <wx.Window.html#PushEventHandler>`_ , `wx.Window.PopEventHandler <wx.Window.html#PopEventHandler>`_
  

--------

.. method:: ProcessEvent(event)

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

   **Parameters:**

   * `event` (`wx.Event <../Events/wx.Event.html>`_): Event to process.

   |  

   **Returns:**

   `bool` 


.. note:: 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  functions.
   
   An instance where you might actually override the `ProcessEvent <#ProcessEvent>`_ function is where you want to direct event 
   processing to event handlers not normally noticed by wxWidgets. For example, in the document/view architecture, documents and 
   views are potential event handlers. When an event reaches a frame, `ProcessEvent <#ProcessEvent>`_ will need to be called on 
   the associated document and view in case event handler functions are associated with these objects. 

   The normal order of event table searching is as follows:

   1. If the object is disabled (via a call to `SetEvtHandlerEnabled <#SetEvtHandlerEnabled>`_) the function skips to step (6).
   2. If the object is a `wx.Window <wx.Window.html>`_, `ProcessEvent <#ProcessEvent>`_ is recursively called on the window's 
      `wx.Validator <wx.Validator.html>`_. If this returns ``True``, the function exits.
   3. wxWidgets `SearchEventTable` is called for this event handler. If this fails, the base class table is tried, 
      and so on until no more tables exist or an appropriate function was found, in which case the function exits.
   4. The search is applied down the entire chain of event handlers (usually the chain has a length of one). If this succeeds, 
      the function exits.
   5. If the object is a `wx.Window <wx.Window.html>`_ and the event is a `wx.CommandEvent <../Events/wx.CommandEvent.html>`_, 
      `ProcessEvent <#ProcessEvent>`_ is recursively applied to the parent window's event handler. If this returns ``True``, 
      the function exits.
   6. Finally, `ProcessEvent <#ProcessEvent>`_ is called on the `wx.App <wx.App.html>`_ object.
  

--------

.. method:: ProcessPendingEvents()

   `No docstrings found for this method.` 

--------


.. method:: SetEvtHandlerEnabled(enabled)

   Enables or disables the event handler.

   **Parameters:**

   * `enabled` (bool): ``True`` if the event handler is to be enabled, ``False`` if it is to be disabled.


.. note:: You can use this function to a having to remove the event handler from the chain, for example when implementing a dialog 
   editor and changing from edit to test mode.
  
.. seealso:: `GetEvtHandlerEnabled <#GetEvtHandlerEnabled>`_
  

--------

.. method:: SetNextHandler(handler)

   Sets the pointer to the next handler.

   **Parameters:**

   * `handler` (`wx.EvtHandler <wx.EvtHandler.html>`_): Event handler to be set as the next handler.


.. seealso:: `GetNextHandler <#GetNextHandler>`_, `SetPreviousHandler <#SetPreviousHandler>`_, 
   `GetPreviousHandler <#GetPreviousHandler>`_, `wx.Window.PushEventHandler <wx.Window.html#PushEventHandler>`_, 
   `wx.Window.PopEventHandler <wx.Window.html#PopEventHandler>`_
  

--------

.. method:: SetPreviousHandler(handler)

   Sets the pointer to the previous handler.

   **Parameters:**

   * `handler` (`wx.EvtHandler <wx.EvtHandler.html>`_): Event handler to be set as the previous handler.


--------

.. method:: Unbind(event, source=None, id=-1, id2=-1)

   Disconnects the event handler binding for event from self.
   Returns True if successful.
   
   **Parameters:**

   * `event` (`wx.Event <../Events/wx.Event.html>`_): Event to process.
   * `source` (`wx.Window <wx.Window.html>`_): 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.
   * `id` (int): Used to specify the event source by ID instead of instance.
   * `id2` (int): Used when it is desirable to bind a handler to a range of IDs, such as with ``wx.EVT_MENU_RANGE``.


--------

Properties
^^^^^^^^^^


.. attribute:: EvtHandlerEnabled

   See `GetEvtHandlerEnabled <#GetEvtHandlerEnabled>`_ and `SetEvtHandlerEnabled <#SetEvtHandlerEnabled>`_
   
.. attribute:: NextHandler

   See `GetNextHandler <#GetNextHandler>`_ and `SetNextHandler <#SetNextHandler>`_
   
.. attribute:: PreviousHandler

   See `GetPreviousHandler <#GetPreviousHandler>`_ and `SetPreviousHandler <#SetPreviousHandler>`_