.. wxPython Phoenix documentation

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

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

.. include:: headings.inc



.. _wx.MouseEventsManager:

==========================================================================================================================================
|phoenix_title|  **wx.MouseEventsManager**
==========================================================================================================================================

Helper for handling mouse input events in windows containing multiple items.          

This class handles mouse events and synthesizes high-level notifications such as clicks and drag events from low level mouse button presses and mouse movement events. It is useful because handling the mouse events is less obvious than might seem at a first glance: for example, clicks on an object should only be generated if the mouse was both pressed and released over it and not just released (so it requires storing the previous state) and dragging shouldn't start before the mouse moves away far enough. 

This class encapsulates all these dull details for controls containing multiple items which can be identified by a positive integer index and you just need to implement its pure virtual functions to use it. 

Notice that this class supposes that all items can be identified by an integer "index" but it doesn't need to be an ordinal index of the item (although this is the most common case) –  it can be any value which can be used to uniquely identify an item. 







|

|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>MouseEventsManager</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.MouseEventsManager_inheritance.png" alt="Inheritance diagram of MouseEventsManager" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.MouseEventsManager.html" title="Helper for handling mouse input events in windows containing multiple items." alt="" coords="14,160,197,189"/> <area shape="rect" id="node2" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="49,83,161,112"/> <area shape="rect" id="node3" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="5,5,88,35"/> <area shape="rect" id="node4" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="113,5,215,35"/> </map> 
   </p>
   </div>

|


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

================================================================================ ================================================================================
:meth:`~wx.MouseEventsManager.__init__`                                          Default constructor.
:meth:`~wx.MouseEventsManager.Create`                                            Finishes initialization of the object created using default constructor.
:meth:`~wx.MouseEventsManager.MouseClickBegin`                                   May be overridden to update the state of an item when it is pressed.
:meth:`~wx.MouseEventsManager.MouseClickCancelled`                               Must be overridden to reset the item appearance changed by :meth:`~MouseEventsManager.MouseClickBegin` .
:meth:`~wx.MouseEventsManager.MouseClicked`                                      Must be overridden to react to mouse clicks.
:meth:`~wx.MouseEventsManager.MouseDragBegin`                                    Must be overridden to allow or deny dragging of the item.
:meth:`~wx.MouseEventsManager.MouseDragCancelled`                                Must be overridden to handle cancellation of mouse dragging.
:meth:`~wx.MouseEventsManager.MouseDragEnd`                                      Must be overridden to handle item drop.
:meth:`~wx.MouseEventsManager.MouseDragging`                                     Must be overridden to provide feed back while an item is being dragged.
:meth:`~wx.MouseEventsManager.MouseHitTest`                                      Must be overridden to return the item at the given position.
================================================================================ ================================================================================


|


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


.. class:: wx.MouseEventsManager(EvtHandler)

   **Possible constructors**::

       MouseEventsManager()
       
       MouseEventsManager(win)
       
   
   Helper for handling mouse input events in windows containing multiple
   items.



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



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor.                  
      
      You must call :meth:`Create`   to finish initializing the mouse events manager. If possible, avoid the use of this constructor in favour of the other one which fully initializes the mouse events manager immediately.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, win)`
      
      Constructor creates the manager for the window.                  
      
      A mouse event manager is always associated with a window and must be destroyed by the window when it is destroyed (it doesn't need to be allocated on the heap however).                  
      
      
      :param `win`: 
      :type `win`: wx.Window
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Create(self, win)

      Finishes initialization of the object created using default constructor.                  

      Currently always returns ``True``.                  


      :param `win`: 
      :type `win`: wx.Window




      :rtype: `bool`








   .. method:: MouseClickBegin(self, item)

      May be overridden to update the state of an item when it is pressed.                  

      This method is called when the item is becomes pressed and can be used to change its appearance when this happens. It is mostly useful for button-like items and doesn't need to be overridden if the items shouldn't change their appearance when pressed. 




      :param `item`: The item being pressed.   
      :type `item`: int




                  





   .. method:: MouseClickCancelled(self, item)

      Must be overridden to reset the item appearance changed by :meth:`MouseClickBegin` .                  

      This method is called if the mouse capture was lost while the item was pressed and must be overridden to restore the default item appearance if it was changed in :meth:`MouseClickBegin` . 

                


      :param `item`: 
      :type `item`: int






      .. seealso:: :meth:`MouseDragCancelled` , :ref:`wx.MouseCaptureLostEvent`    








   .. method:: MouseClicked(self, item)

      Must be overridden to react to mouse clicks.                  

      This method is called when the user clicked (i.e. pressed and released mouse over the `same`  item) and should normally generate a notification about this click and return ``True`` if it was handled or ``False`` otherwise, determining whether the original mouse event is skipped or not. 




      :param `item`: The item which was clicked.   
      :type `item`: int






      :rtype: `bool`



                  



      :returns: 

         ``True`` if the mouse event was processed and ``False`` otherwise.   








   .. method:: MouseDragBegin(self, item, pos)

      Must be overridden to allow or deny dragging of the item.                  

      This method is called when the user attempts to start dragging the given item. 




      :param `item`: The item which is going to be dragged.   
      :type `item`: int
      :param `pos`: The position from where it is being dragged.   
      :type `pos`: wx.Point








      :rtype: `bool`



                  



      :returns: 

         ``True`` to allow the item to be dragged (in which case :meth:`MouseDragging`   and :meth:`MouseDragEnd`   will be called later, unless :meth:`MouseDragCancelled`   is called instead) or ``False`` to forbid it.   








   .. method:: MouseDragCancelled(self, item)

      Must be overridden to handle cancellation of mouse dragging.                  

      This method is called when mouse capture is lost while dragging the item and normally should remove the visual feedback drawn by :meth:`MouseDragging`   as well as reset any internal variables set in :meth:`MouseDragBegin` . 

                


      :param `item`: 
      :type `item`: int






      .. seealso:: :ref:`wx.MouseCaptureLostEvent`    








   .. method:: MouseDragEnd(self, item, pos)

      Must be overridden to handle item drop.                  

      This method is called when the mouse is released after dragging the item. Normally the item should be positioned at the new location. 




      :param `item`: The item which was dragged and now dropped.   
      :type `item`: int
      :param `pos`: The position at which the item was dropped.  
      :type `pos`: wx.Point






                  



      .. seealso:: :meth:`MouseDragBegin` , :meth:`MouseDragging`     








   .. method:: MouseDragging(self, item, pos)

      Must be overridden to provide feed back while an item is being dragged.                  

      This method is called while the item is being dragged and should normally update the feedback shown on screen (usually this is done using :ref:`wx.Overlay`). 

      Notice that this method will never be called for the items for which :meth:`MouseDragBegin`   returns ``False``. Consequently, if :meth:`MouseDragBegin`   always returns ``False`` you can do nothing in this method. 




      :param `item`: The item being dragged.   
      :type `item`: int
      :param `pos`: The current position of the item.  
      :type `pos`: wx.Point






                  



      .. seealso:: :meth:`MouseDragEnd`     








   .. method:: MouseHitTest(self, pos)

      Must be overridden to return the item at the given position.                  




      :param `pos`: The position to test, in physical coordinates.   
      :type `pos`: wx.Point






      :rtype: `int`



                  



      :returns: 

         The index of the item at the given position or ``wx.NOT_FOUND`` if there is no item there.