]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/mousemanager.h
Correct wxID_SEPARATOR description in menu documentation.
[wxWidgets.git] / 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 };