interface/wx/mousemanager.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/mousemanager.h
   3 // Purpose:     documentation of wxMouseEventsManager class
   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 /**
  11     @class wxMouseEventsManager
  12
  13     Helper for handling mouse input events in windows containing multiple
  14     items.
  15
  16     This class handles mouse events and synthesizes high-level notifications
  17     such as clicks and drag events from low level mouse button presses and
  18     mouse movement events. It is useful because handling the mouse events is
  19     less obvious than might seem at a first glance: for example, clicks on an
  20     object should only be generated if the mouse was both pressed and released
  21     over it and not just released (so it requires storing the previous state)
  22     and dragging shouldn't start before the mouse moves away far enough.
  23
  24     This class encapsulates all these dull details for controls containing
  25     multiple items which can be identified by a positive integer index and you
  26     just need to implement its pure virtual functions to use it.
  27
  28     Notice that this class supposes that all items can be identified by an
  29     integer "index" but it doesn't need to be an ordinal index of the item
  30     (although this is the most common case) -- it can be any value which can
  31     be used to uniquely identify an item.
  32
  33     @library{wxcore}
  34     @category{events}
  35  */
  36 class wxMouseEventsManager : public wxEvtHandler
  37 {
  38 public:
  39     /**
  40         Default constructor.
  41
  42         You must call Create() to finish initializing the mouse events manager.
  43         If possible, avoid the use of this constructor in favour of the other
  44         one which fully initializes the mouse events manager immediately.
  45      */
  46     wxMouseEventsManager();
  47
  48     /**
  49         Constructor creates the manager for the window.
  50
  51         A mouse event manager is always associated with a window and must be
  52         destroyed by the window when it is destroyed (it doesn't need to be
  53         allocated on the heap however).
  54      */
  55     wxMouseEventsManager(wxWindow *win);
  56
  57     /**
  58         Finishes initialization of the object created using default
  59         constructor.
  60
  61         Currently always returns @true.
  62      */
  63     bool Create(wxWindow *win);
  64
  65 protected:
  66     /**
  67         Must be overridden to return the item at the given position.
  68
  69         @param pos
  70             The position to test, in physical coordinates.
  71         @return
  72             The index of the item at the given position or wxNOT_FOUND if there
  73             is no item there.
  74      */
  75     virtual int MouseHitTest(const wxPoint& pos) = 0;
  76
  77     /**
  78         Must be overridden to react to mouse clicks.
  79
  80         This method is called when the user clicked (i.e. pressed and released
  81         mouse over the @e same item) and should normally generate a
  82         notification about this click and return true if it was handled or
  83         false otherwise, determining whether the original mouse event is
  84         skipped or not.
  85
  86         @param item
  87             The item which was clicked.
  88         @return
  89             @true if the mouse event was processed and @false otherwise.
  90      */
  91     virtual bool MouseClicked(int item) = 0;
  92
  93     /**
  94         Must be overridden to allow or deny dragging of the item.
  95
  96         This method is called when the user attempts to start dragging the
  97         given item.
  98
  99         @param item
 100             The item which is going to be dragged.
 101         @param pos
 102             The position from where it is being dragged.
 103         @return
 104             @true to allow the item to be dragged (in which case
 105             MouseDragging() and MouseDragEnd() will be called later, unless
 106             MouseDragCancelled() is called instead) or @false to forbid it.
 107      */
 108     virtual bool MouseDragBegin(int item, const wxPoint& pos) = 0;
 109
 110     /**
 111         Must be overridden to provide feed back while an item is being dragged.
 112
 113         This method is called while the item is being dragged and should
 114         normally update the feedback shown on screen (usually this is done
 115         using wxOverlay).
 116
 117         Notice that this method will never be called for the items for which
 118         MouseDragBegin() returns @false. Consequently, if MouseDragBegin()
 119         always returns @false you can do nothing in this method.
 120
 121         @param item
 122             The item being dragged.
 123         @param pos
 124             The current position of the item.
 125
 126         @see MouseDragEnd()
 127      */
 128     virtual void MouseDragging(int item, const wxPoint& pos) = 0;
 129
 130     /**
 131         Must be overridden to handle item drop.
 132
 133         This method is called when the mouse is released after dragging the
 134         item. Normally the item should be positioned at the new location.
 135
 136         @param item
 137             The item which was dragged and now dropped.
 138         @param pos
 139             The position at which the item was dropped.
 140
 141         @see MouseDragBegin(), MouseDragging()
 142      */
 143     virtual void MouseDragEnd(int item, const wxPoint& pos) = 0;
 144
 145     /**
 146         Must be overridden to handle cancellation of mouse dragging.
 147
 148         This method is called when mouse capture is lost while dragging the
 149         item and normally should remove the visual feedback drawn by
 150         MouseDragging() as well as reset any internal variables set in
 151         MouseDragBegin().
 152
 153         @see wxMouseCaptureLostEvent
 154      */
 155     virtual void MouseDragCancelled(int item) = 0;
 156
 157
 158     /**
 159         May be overridden to update the state of an item when it is pressed.
 160
 161         This method is called when the item is becomes pressed and can be used
 162         to change its appearance when this happens. It is mostly useful for
 163         button-like items and doesn't need to be overridden if the items
 164         shouldn't change their appearance when pressed.
 165
 166         @param item
 167             The item being pressed.
 168      */
 169     virtual void MouseClickBegin(int item);
 170
 171     /**
 172         Must be overridden to reset the item appearance changed by
 173         MouseClickBegin().
 174
 175         This method is called if the mouse capture was lost while the item was
 176         pressed and must be overridden to restore the default item appearance
 177         if it was changed in MouseClickBegin().
 178
 179         @see MouseDragCancelled(), wxMouseCaptureLostEvent
 180      */
 181     virtual void MouseClickCancelled(int item);
 182 };