include/wx/mousemanager.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/mousemanager.h
   3 // Purpose:     wxMouseEventsManager class declaration
   4 // Author:      Vadim Zeitlin
   5 // Created:     2009-04-20
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_MOUSEMANAGER_H_
  12 #define _WX_MOUSEMANAGER_H_
  13
  14 #include "wx/event.h"
  15
  16 // ----------------------------------------------------------------------------
  17 // wxMouseEventsManager
  18 // ----------------------------------------------------------------------------
  19
  20 /*
  21     This class handles mouse events and synthesizes high-level notifications
  22     such as clicks and drag events from low level mouse button presses and
  23     mouse movement events. It is useful because handling the mouse events is
  24     less obvious than might seem at a first glance: for example, clicks on an
  25     object should only be generated if the mouse was both pressed and released
  26     over it and not just released (so it requires storing the previous state)
  27     and dragging shouldn't start before the mouse moves away far enough.
  28
  29     This class encapsulates all these dull details for controls containing
  30     multiple items which can be identified by a positive integer index and you
  31     just need to implement its pure virtual functions to use it.
  32  */
  33 class WXDLLIMPEXP_CORE wxMouseEventsManager : public wxEvtHandler
  34 {
  35 public:
  36     // a mouse event manager is always associated with a window and must be
  37     // deleted by the window when it is destroyed
  38     wxMouseEventsManager(wxWindow *win);
  39
  40     virtual ~wxMouseEventsManager();
  41
  42 protected:
  43     // called to find the item at the given position: return wxNOT_FOUND (-1)
  44     // if there is no item here
  45     virtual int MouseHitTest(const wxPoint& pos) = 0;
  46
  47     // called when the user clicked (i.e. pressed and released mouse over the
  48     // same item), should normally generate a notification about this click and
  49     // return true if it was handled or false otherwise, determining whether
  50     // the original mouse event is skipped or not
  51     virtual bool MouseClicked(int item) = 0;
  52
  53     // called to start dragging the given item, should generate the appropriate
  54     // BEGIN_DRAG event and return false if dragging this item was forbidden
  55     virtual bool MouseDragBegin(int item, const wxPoint& pos) = 0;
  56
  57     // called while the item is being dragged, should normally update the
  58     // feedback on screen (usually using wxOverlay)
  59     virtual void MouseDragging(int item, const wxPoint& pos) = 0;
  60
  61     // called when the mouse is released after dragging the item
  62     virtual void MouseDragEnd(int item, const wxPoint& pos) = 0;
  63
  64     // called when mouse capture is lost while dragging the item, should remove
  65     // the visual feedback drawn by MouseDragging()
  66     virtual void MouseDragCancelled(int item) = 0;
  67
  68
  69     // you don't need to override those but you will want to do if it your
  70     // control renders pressed items differently
  71
  72     // called when the item is becomes pressed, can be used to change its
  73     // appearance
  74     virtual void MouseClickBegin(int WXUNUSED(item)) { }
  75
  76     // called if the mouse capture was lost while the item was pressed, can be
  77     // used to restore the default item appearance if it was changed in
  78     // MouseClickBegin()
  79     virtual void MouseClickCancelled(int WXUNUSED(item)) { }
  80
  81 private:
  82     /*
  83         Here is a small diagram explaining the switches between different
  84         states:
  85
  86
  87                 /---------->NORMAL<--------------- Drag end
  88                /     /   /    |                      event
  89               /     /    |    |                        ^
  90              /     /     |    |                        |
  91            Click  /    N |    | mouse                  | mouse up
  92            event /       |    | down                   |
  93              |  /        |    |                     DRAGGING
  94              | /         |    |                        ^
  95             Y|/ N        \    v                        |Y
  96       +-------------+     +--------+           N +-----------+
  97       |On same item?|     |On item?|  -----------|Begin drag?|
  98       +-------------+     +--------+ /           +-----------+
  99              ^                |     /                  ^
 100              |                |    /                   |
 101               \      mouse    |   /   mouse moved      |
 102                 \     up      v  v     far enough     /
 103                   \--------PRESSED-------------------/
 104
 105
 106         There are also transitions from PRESSED and DRAGGING to NORMAL in case
 107         the mouse capture is lost or Escape key is pressed which are not shown.
 108      */
 109     enum State
 110     {
 111         State_Normal,   // initial, default state
 112         State_Pressed,  // mouse was pressed over an item
 113         State_Dragging  // the item is being dragged
 114     };
 115
 116
 117     // various event handlers
 118     void OnCaptureLost(wxMouseCaptureLostEvent& event);
 119     void OnLeftDown(wxMouseEvent& event);
 120     void OnLeftUp(wxMouseEvent& event);
 121     void OnMove(wxMouseEvent& event);
 122
 123
 124     // the associated window, never NULL
 125     wxWindow * const m_win;
 126
 127     // the current state
 128     State m_state;
 129
 130     // the details of the operation currently in progress, only valid if
 131     // m_state is not normal
 132
 133     // the item being pressed or dragged (always valid, i.e. != wxNOT_FOUND if
 134     // m_state != State_Normal)
 135     int m_item;
 136
 137     // the position of the last mouse event of interest: either mouse press in
 138     // State_Pressed or last movement event in State_Dragging
 139     wxPoint m_posLast;
 140
 141
 142     DECLARE_EVENT_TABLE()
 143
 144     wxDECLARE_NO_COPY_CLASS(wxMouseEventsManager);
 145 };
 146
 147 #endif // _WX_MOUSEMANAGER_H_
 148