added SetStatusText method (avoiding dc.Clear)
[wxWidgets.git] / docs / latex / wx / mouseevt.tex
CommitLineData
a660d684
KB
1\section{\class{wxMouseEvent}}\label{wxmouseevent}
2
fe604ccd
JS
3This event class contains information about mouse events.
4See \helpref{wxWindow::OnMouseEvent}{wxwindowonmouseevent}.
a660d684 5
4aff28fc
VZ
6{\bf NB: } Note that under Windows mouse enter and leave events are not natively supported
7by the system but are generated by wxWindows itself. This has several
8drawbacks: the LEAVE\_WINDOW event might be received some time after the mouse
9left the window and the state variables for it may have changed during this
10time.
11
d2c52078
RD
12{\bf NB: } Note the difference between methods like
13\helpref{LeftDown}{wxmouseeventleftdown} and
f6bcfd97
BP
14\helpref{LeftIsDown}{wxmouseeventleftisdown}: the formet returns {\tt TRUE}
15when the event corresponds to the left mouse button click while the latter
16returns {\tt TRUE} if the left mouse button is currently being pressed. For
d2c52078 17example, when the user is dragging the mouse you can use
f6bcfd97
BP
18\helpref{LeftIsDown}{wxmouseeventleftisdown} to test
19whether the left mouse button is (still) depressed. Also, by convention, if
d2c52078 20\helpref{LeftDown}{wxmouseeventleftdown} returns {\tt TRUE},
f6bcfd97
BP
21\helpref{LeftIsDown}{wxmouseeventleftisdown} will also return {\tt TRUE} in
22wxWindows whatever the underlying GUI behaviour is (which is
23platform-dependent). The same applies, of course, to other mouse buttons as
24well.
25
a660d684
KB
26\wxheading{Derived from}
27
28\helpref{wxEvent}{wxevent}
29
954b8ae6
JS
30\wxheading{Include files}
31
32<wx/event.h>
33
a660d684
KB
34\wxheading{Event table macros}
35
36To process a mouse event, use these event handler macros to direct input to member
37functions that take a wxMouseEvent argument.
38
39\twocolwidtha{7cm}
40\begin{twocollist}\itemsep=0pt
41\twocolitem{{\bf EVT\_LEFT\_DOWN(func)}}{Process a wxEVT\_LEFT\_DOWN event.}
42\twocolitem{{\bf EVT\_LEFT\_UP(func)}}{Process a wxEVT\_LEFT\_UP event.}
43\twocolitem{{\bf EVT\_LEFT\_DCLICK(func)}}{Process a wxEVT\_LEFT\_DCLICK event.}
44\twocolitem{{\bf EVT\_MIDDLE\_DOWN(func)}}{Process a wxEVT\_MIDDLE\_DOWN event.}
45\twocolitem{{\bf EVT\_MIDDLE\_UP(func)}}{Process a wxEVT\_MIDDLE\_UP event.}
46\twocolitem{{\bf EVT\_MIDDLE\_DCLICK(func)}}{Process a wxEVT\_MIDDLE\_DCLICK event.}
47\twocolitem{{\bf EVT\_RIGHT\_DOWN(func)}}{Process a wxEVT\_RIGHT\_DOWN event.}
48\twocolitem{{\bf EVT\_RIGHT\_UP(func)}}{Process a wxEVT\_RIGHT\_UP event.}
49\twocolitem{{\bf EVT\_RIGHT\_DCLICK(func)}}{Process a wxEVT\_RIGHT\_DCLICK event.}
50\twocolitem{{\bf EVT\_MOTION(func)}}{Process a wxEVT\_MOTION event.}
51\twocolitem{{\bf EVT\_ENTER\_WINDOW(func)}}{Process a wxEVT\_ENTER\_WINDOW event.}
52\twocolitem{{\bf EVT\_LEAVE\_WINDOW(func)}}{Process a wxEVT\_LEAVE\_WINDOW event.}
d2c52078 53\twocolitem{{\bf EVT\_MOUSEWHEEL(func)}}{Process a wxEVT\_MOUSEWHEEL event.}
5de76427 54\twocolitem{{\bf EVT\_MOUSE\_EVENTS(func)}}{Process all mouse events.}
a660d684
KB
55\end{twocollist}%
56
57\latexignore{\rtfignore{\wxheading{Members}}}
58
59\membersection{wxMouseEvent::m\_altDown}
60
61\member{bool}{m\_altDown}
62
63TRUE if the Alt key is pressed down.
64
65\membersection{wxMouseEvent::m\_controlDown}
66
67\member{bool}{m\_controlDown}
68
69TRUE if control key is pressed down.
70
71\membersection{wxMouseEvent::m\_leftDown}
72
73\member{bool}{m\_leftDown}
74
75TRUE if the left mouse button is currently pressed down.
76
77\membersection{wxMouseEvent::m\_middleDown}
78
79\member{bool}{m\_middleDown}
80
81TRUE if the middle mouse button is currently pressed down.
82
83\membersection{wxMouseEvent::m\_rightDown}
84
85\member{bool}{m\_rightDown}
86
87TRUE if the right mouse button is currently pressed down.
88
a660d684
KB
89\membersection{wxMouseEvent::m\_metaDown}
90
91\member{bool}{m\_metaDown}
92
93TRUE if the Meta key is pressed down.
94
95\membersection{wxMouseEvent::m\_shiftDown}
96
97\member{bool}{m\_shiftDown}
98
99TRUE if shift is pressed down.
100
101\membersection{wxMouseEvent::m\_x}
102
803ef874 103\member{long}{m\_x}
a660d684
KB
104
105X-coordinate of the event.
106
107\membersection{wxMouseEvent::m\_y}
108
803ef874 109\member{long}{m\_y}
a660d684
KB
110
111Y-coordinate of the event.
112
d2c52078
RD
113\membersection{wxMouseEvent::m\_wheelRotation}
114
115\member{int}{m\_wheelRotation}
116
117The distance the mouse wheel is rotated.
118
119\membersection{wxMouseEvent::m\_wheelDelta}
120
121\member{int}{m\_wheelDelta}
122
123The wheel delta, normally 120.
124
125\membersection{wxMouseEvent::m\_linesPerAction}
126
127\member{int}{m\_linesPerAction}
128
129The configured number of lines (or whatever) to be scrolled per wheel
130action.
131
132
a660d684
KB
133\membersection{wxMouseEvent::wxMouseEvent}
134
135\func{}{wxMouseEvent}{\param{WXTYPE}{ mouseEventType = 0}, \param{int}{ id = 0}}
136
137Constructor. Valid event types are:
138
139\begin{itemize}
140\itemsep=0pt
141\item {\bf wxEVT\_ENTER\_WINDOW}
142\item {\bf wxEVT\_LEAVE\_WINDOW}
143\item {\bf wxEVT\_LEFT\_DOWN}
144\item {\bf wxEVT\_LEFT\_UP}
145\item {\bf wxEVT\_LEFT\_DCLICK}
146\item {\bf wxEVT\_MIDDLE\_DOWN}
147\item {\bf wxEVT\_MIDDLE\_UP}
148\item {\bf wxEVT\_MIDDLE\_DCLICK}
149\item {\bf wxEVT\_RIGHT\_DOWN}
150\item {\bf wxEVT\_RIGHT\_UP}
151\item {\bf wxEVT\_RIGHT\_DCLICK}
152\item {\bf wxEVT\_MOTION}
d2c52078 153\item {\bf wxEVT\_MOUSEWHEEL}
a660d684
KB
154\end{itemize}
155
156\membersection{wxMouseEvent::AltDown}
157
158\func{bool}{AltDown}{\void}
159
160Returns TRUE if the Alt key was down at the time of the event.
161
162\membersection{wxMouseEvent::Button}
163
164\func{bool}{Button}{\param{int}{ button}}
165
166Returns TRUE if the identified mouse button is changing state. Valid
167values of {\it button} are 1, 2 or 3 for left, middle and right
168buttons respectively.
169
170Not all mice have middle buttons so a portable application should avoid
171this one.
172
173\membersection{wxMouseEvent::ButtonDClick}\label{buttondclick}
174
175\func{bool}{ButtonDClick}{\param{int}{ but = -1}}
176
177If the argument is omitted, this returns TRUE if the event was a mouse
178double click event. Otherwise the argument specifies which double click event
179was generated (1, 2 or 3 for left, middle and right buttons respectively).
180
181\membersection{wxMouseEvent::ButtonDown}
182
183\func{bool}{ButtonDown}{\param{int}{ but = -1}}
184
185If the argument is omitted, this returns TRUE if the event was a mouse
186button down event. Otherwise the argument specifies which button-down event
187was generated (1, 2 or 3 for left, middle and right buttons respectively).
188
189\membersection{wxMouseEvent::ButtonUp}
190
191\func{bool}{ButtonUp}{\param{int}{ but = -1}}
192
193If the argument is omitted, this returns TRUE if the event was a mouse
194button up event. Otherwise the argument specifies which button-up event
195was generated (1, 2 or 3 for left, middle and right buttons respectively).
196
197\membersection{wxMouseEvent::ControlDown}
198
199\func{bool}{ControlDown}{\void}
200
201Returns TRUE if the control key was down at the time of the event.
202
203\membersection{wxMouseEvent::Dragging}
204
205\func{bool}{Dragging}{\void}
206
207Returns TRUE if this was a dragging event (motion while a button is depressed).
208
209\membersection{wxMouseEvent::Entering}\label{wxmouseevententering}
210
211\func{bool}{Entering}{\void}
212
ff835f50 213Returns TRUE if the mouse was entering the window.
a660d684
KB
214
215See also \helpref{wxMouseEvent::Leaving}{wxmouseeventleaving}.
216
803ef874
JS
217\membersection{wxMouseEvent::GetPosition}\label{wxmouseeventgetposition}
218
219\constfunc{wxPoint}{GetPosition}{\void}
220
fa482912
JS
221\constfunc{void}{GetPosition}{\param{wxCoord*}{ x}, \param{wxCoord*}{ y}}
222
223\constfunc{void}{GetPosition}{\param{long*}{ x}, \param{long*}{ y}}
803ef874
JS
224
225Sets *x and *y to the position at which the event occurred.
226
227Returns the physical mouse position in pixels.
228
229\membersection{wxMouseEvent::GetLogicalPosition}\label{wxmouseeventgetlogicalposition}
230
231\constfunc{wxPoint}{GetLogicalPosition}{\param{const wxDC\&}{ dc}}
232
233Returns the logical mouse position in pixels (i.e. translated according to the
234translation set for the DC, which usually indicates that the window has been scrolled).
235
d2c52078
RD
236
237\membersection{wxMouseEvent::GetLinesPerAction}\label{wxmouseeventgetlinesperaction}
238
239\constfunc{int}{GetLinesPerAction}{\void}
240
241Returns the configured number of lines (or whatever) to be scrolled per
d13d99aa 242wheel action. Defaults to three.
d2c52078
RD
243
244\membersection{wxMouseEvent::GetWheelRotation}\label{wxmouseeventgetwheelrotation}
245
246\constfunc{int}{GetWheelRotation}{\void}
247
248Get wheel rotation, positive or negative indicates direction of
249rotation. Current devices all send an event when rotation is equal to
250+/-WheelDelta, but this allows for finer resolution devices to be
251created in the future. Because of this you shouldn't assume that one
252event is equal to 1 line or whatever, but you should be able to either
253do partial line scrolling or wait until +/-WheelDelta rotation values
254have been accumulated before scrolling.
255
256\membersection{wxMouseEvent::GetWheelDelta}\label{wxmouseeventgetwheeldelta}
257
258\constfunc{int}{GetWheelDelta}{\void}
259
260Get wheel delta, normally 120. This is the threshold for action to be
261taken, and one such action (for example, scrolling one increment)
262should occur for each delta.
263
a660d684
KB
264\membersection{wxMouseEvent::GetX}\label{wxmouseeventgetx}
265
803ef874 266\constfunc{long}{GetX}{\void}
a660d684 267
803ef874 268Returns X coordinate of the physical mouse event position.
a660d684
KB
269
270\membersection{wxMouseEvent::GetY}\label{wxmouseeventgety}
271
803ef874 272\func{long}{GetY}{\void}
a660d684 273
803ef874 274Returns Y coordinate of the physical mouse event position.
a660d684
KB
275
276\membersection{wxMouseEvent::IsButton}
277
803ef874 278\constfunc{bool}{IsButton}{\void}
a660d684
KB
279
280Returns TRUE if the event was a mouse button event (not necessarily a button down event -
281that may be tested using {\it ButtonDown}).
282
283\membersection{wxMouseEvent::Leaving}\label{wxmouseeventleaving}
284
803ef874 285\constfunc{bool}{Leaving}{\void}
a660d684 286
ff835f50 287Returns TRUE if the mouse was leaving the window.
a660d684
KB
288
289See also \helpref{wxMouseEvent::Entering}{wxmouseevententering}.
290
291\membersection{wxMouseEvent::LeftDClick}
292
803ef874 293\constfunc{bool}{LeftDClick}{\void}
a660d684
KB
294
295Returns TRUE if the event was a left double click.
296
2cdd0d01 297\membersection{wxMouseEvent::LeftDown}\label{wxmouseeventleftdown}
a660d684 298
803ef874 299\constfunc{bool}{LeftDown}{\void}
a660d684
KB
300
301Returns TRUE if the left mouse button changed to down.
302
f6bcfd97 303\membersection{wxMouseEvent::LeftIsDown}\label{wxmouseeventleftisdown}
a660d684 304
803ef874 305\constfunc{bool}{LeftIsDown}{\void}
a660d684
KB
306
307Returns TRUE if the left mouse button is currently down, independent
308of the current event type.
309
d2c52078 310Please notice that it is {\bf not} the same as
2cdd0d01
VZ
311\helpref{LeftDown}{wxmouseeventleftdown} which returns TRUE if the left mouse
312button was just pressed. Rather, it describes the state of the mouse button
313before the event happened.
314
315This event is usually used in the mouse event handlers which process "move
316mouse" messages to determine whether the user is (still) dragging the mouse.
317
a660d684
KB
318\membersection{wxMouseEvent::LeftUp}
319
803ef874 320\constfunc{bool}{LeftUp}{\void}
a660d684
KB
321
322Returns TRUE if the left mouse button changed to up.
323
324\membersection{wxMouseEvent::MetaDown}
325
803ef874 326\constfunc{bool}{MetaDown}{\void}
a660d684
KB
327
328Returns TRUE if the Meta key was down at the time of the event.
329
330\membersection{wxMouseEvent::MiddleDClick}
331
803ef874 332\constfunc{bool}{MiddleDClick}{\void}
a660d684
KB
333
334Returns TRUE if the event was a middle double click.
335
336\membersection{wxMouseEvent::MiddleDown}
337
803ef874 338\constfunc{bool}{MiddleDown}{\void}
a660d684
KB
339
340Returns TRUE if the middle mouse button changed to down.
341
f6bcfd97 342\membersection{wxMouseEvent::MiddleIsDown}\label{wxmouseeventmiddleisdown}
a660d684 343
803ef874 344\constfunc{bool}{MiddleIsDown}{\void}
a660d684
KB
345
346Returns TRUE if the middle mouse button is currently down, independent
347of the current event type.
348
349\membersection{wxMouseEvent::MiddleUp}
350
803ef874 351\constfunc{bool}{MiddleUp}{\void}
a660d684
KB
352
353Returns TRUE if the middle mouse button changed to up.
354
355\membersection{wxMouseEvent::Moving}
356
803ef874 357\constfunc{bool}{Moving}{\void}
a660d684
KB
358
359Returns TRUE if this was a motion event (no buttons depressed).
360
a660d684
KB
361\membersection{wxMouseEvent::RightDClick}
362
803ef874 363\constfunc{bool}{RightDClick}{\void}
a660d684
KB
364
365Returns TRUE if the event was a right double click.
366
367\membersection{wxMouseEvent::RightDown}
368
803ef874 369\constfunc{bool}{RightDown}{\void}
a660d684
KB
370
371Returns TRUE if the right mouse button changed to down.
372
f6bcfd97 373\membersection{wxMouseEvent::RightIsDown}\label{wxmouseeventrightisdown}
a660d684 374
803ef874 375\constfunc{bool}{RightIsDown}{\void}
a660d684
KB
376
377Returns TRUE if the right mouse button is currently down, independent
378of the current event type.
379
380\membersection{wxMouseEvent::RightUp}
381
803ef874 382\constfunc{bool}{RightUp}{\void}
a660d684
KB
383
384Returns TRUE if the right mouse button changed to up.
385
a660d684
KB
386\membersection{wxMouseEvent::ShiftDown}
387
803ef874 388\constfunc{bool}{ShiftDown}{\void}
a660d684
KB
389
390Returns TRUE if the shift key was down at the time of the event.
391