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