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 so if it is created using the
  38     // default ctor Create() must be called later
  39     wxMouseEventsManager() { Init(); }
  40     wxMouseEventsManager(wxWindow *win) { Init(); Create(win); }
  41     bool Create(wxWindow *win);
  42
  43     virtual ~wxMouseEventsManager();
  44
  45 protected:
  46     // called to find the item at the given position: return wxNOT_FOUND (-1)
  47     // if there is no item here
  48     virtual int MouseHitTest(const wxPoint& pos) = 0;
  49
  50     // called when the user clicked (i.e. pressed and released mouse over the
  51     // same item), should normally generate a notification about this click and
  52     // return true if it was handled or false otherwise, determining whether
  53     // the original mouse event is skipped or not
  54     virtual bool MouseClicked(int item) = 0;
  55
  56     // called to start dragging the given item, should generate the appropriate
  57     // BEGIN_DRAG event and return false if dragging this item was forbidden
  58     virtual bool MouseDragBegin(int item, const wxPoint& pos) = 0;
  59
  60     // called while the item is being dragged, should normally update the
  61     // feedback on screen (usually using wxOverlay)
  62     virtual void MouseDragging(int item, const wxPoint& pos) = 0;
  63
  64     // called when the mouse is released after dragging the item
  65     virtual void MouseDragEnd(int item, const wxPoint& pos) = 0;
  66
  67     // called when mouse capture is lost while dragging the item, should remove
  68     // the visual feedback drawn by MouseDragging()
  69     virtual void MouseDragCancelled(int item) = 0;
  70
  71
  72     // you don't need to override those but you will want to do if it your
  73     // control renders pressed items differently
  74
  75     // called when the item is becomes pressed, can be used to change its
  76     // appearance
  77     virtual void MouseClickBegin(int WXUNUSED(item)) { }
  78
  79     // called if the mouse capture was lost while the item was pressed, can be
  80     // used to restore the default item appearance if it was changed in
  81     // MouseClickBegin()
  82     virtual void MouseClickCancelled(int WXUNUSED(item)) { }
  83
  84 private:
  85     /*
  86         Here is a small diagram explaining the switches between different
  87         states:
  88
  89
  90                 /---------->NORMAL<--------------- Drag end
  91                /     /   /    |                      event
  92               /     /    |    |                        ^
  93              /     /     |    |                        |
  94            Click  /    N |    | mouse                  | mouse up
  95            event /       |    | down                   |
  96              |  /        |    |                     DRAGGING
  97              | /         |    |                        ^
  98             Y|/ N        \    v                        |Y
  99       +-------------+     +--------+           N +-----------+
 100       |On same item?|     |On item?|  -----------|Begin drag?|
 101       +-------------+     +--------+ /           +-----------+
 102              ^                |     /                  ^
 103              |                |    /                   |
 104               \      mouse    |   /   mouse moved      |
 105                 \     up      v  v     far enough     /
 106                   \--------PRESSED-------------------/
 107
 108
 109         There are also transitions from PRESSED and DRAGGING to NORMAL in case
 110         the mouse capture is lost or Escape key is pressed which are not shown.
 111      */
 112     enum State
 113     {
 114         State_Normal,   // initial, default state
 115         State_Pressed,  // mouse was pressed over an item
 116         State_Dragging  // the item is being dragged
 117     };
 118
 119     // common part of both ctors
 120     void Init();
 121
 122     // various event handlers
 123     void OnCaptureLost(wxMouseCaptureLostEvent& event);
 124     void OnLeftDown(wxMouseEvent& event);
 125     void OnLeftUp(wxMouseEvent& event);
 126     void OnMove(wxMouseEvent& event);
 127
 128
 129     // the associated window, never NULL except between the calls to the
 130     // default ctor and Create()
 131     wxWindow *m_win;
 132
 133     // the current state
 134     State m_state;
 135
 136     // the details of the operation currently in progress, only valid if
 137     // m_state is not normal
 138
 139     // the item being pressed or dragged (always valid, i.e. != wxNOT_FOUND if
 140     // m_state != State_Normal)
 141     int m_item;
 142
 143     // the position of the last mouse event of interest: either mouse press in
 144     // State_Pressed or last movement event in State_Dragging
 145     wxPoint m_posLast;
 146
 147
 148     DECLARE_EVENT_TABLE()
 149
 150     wxDECLARE_NO_COPY_CLASS(wxMouseEventsManager);
 151 };
 152
 153 #endif // _WX_MOUSEMANAGER_H_
 154