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