]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/mouseevt.tex
undefine _DEFINE_LIST before redefining it; also rename it to have WX prefix
[wxWidgets.git] / docs / latex / wx / mouseevt.tex
1 \section{\class{wxMouseEvent}}\label{wxmouseevent}
2
3 This event class contains information about the events generated by the mouse:
4 they include mouse buttons press and release events and mouse move events.
5
6 All mouse events involving the buttons use {\tt wxMOUSE\_BTN\_LEFT} for the
7 left mouse button, {\tt wxMOUSE\_BTN\_MIDDLE} for the middle one and
8 {\tt wxMOUSE\_BTN\_RIGHT} for the right one. And if the system supports more
9 buttons, the \texttt{wxMOUSE\_BTN\_AUX1} and \texttt{wxMOUSE\_BTN\_AUX2} events
10 can also be generated. Note that not all mice have even a middle button so a
11 portable application should avoid relying on the events from it (but the right
12 button click can be emulated using the left mouse button with the control key
13 under Mac platforms with a single button mouse).
14
15 For the \texttt{wxEVT\_ENTER\_WINDOW} and \texttt{wxEVT\_LEAVE\_WINDOW} events
16 purposes, the mouse is considered to be inside the window if it is in the
17 window client area and not inside one of its children. In other words, the
18 parent window receives \texttt{wxEVT\_LEAVE\_WINDOW} event not only when the
19 mouse leaves the window entirely but also when it enters one of its children.
20
21 {\bf NB:} Note that under Windows CE mouse enter and leave events are not natively supported
22 by the system but are generated by wxWidgets itself. This has several
23 drawbacks: the LEAVE\_WINDOW event might be received some time after the mouse
24 left the window and the state variables for it may have changed during this
25 time.
26
27 {\bf NB:} Note the difference between methods like
28 \helpref{LeftDown}{wxmouseeventleftdown} and
29 \helpref{LeftIsDown}{wxmouseeventleftisdown}: the former returns {\tt true}
30 when the event corresponds to the left mouse button click while the latter
31 returns {\tt true} if the left mouse button is currently being pressed. For
32 example, when the user is dragging the mouse you can use
33 \helpref{LeftIsDown}{wxmouseeventleftisdown} to test
34 whether the left mouse button is (still) depressed. Also, by convention, if
35 \helpref{LeftDown}{wxmouseeventleftdown} returns {\tt true},
36 \helpref{LeftIsDown}{wxmouseeventleftisdown} will also return {\tt true} in
37 wxWidgets whatever the underlying GUI behaviour is (which is
38 platform-dependent). The same applies, of course, to other mouse buttons as
39 well.
40
41 \wxheading{Derived from}
42
43 \helpref{wxEvent}{wxevent}\\
44 \helpref{wxObject}{wxobject}
45
46 \wxheading{Include files}
47
48 <wx/event.h>
49
50 \wxheading{Library}
51
52 \helpref{wxCore}{librarieslist}
53
54 \wxheading{Event table macros}
55
56 To process a mouse event, use these event handler macros to direct input to member
57 functions that take a wxMouseEvent argument.
58
59 \twocolwidtha{7cm}
60 \begin{twocollist}\itemsep=0pt
61 \twocolitem{{\bf EVT\_LEFT\_DOWN(func)}}{Process a wxEVT\_LEFT\_DOWN event. The
62 handler of this event should normally call \helpref{event.Skip()}{wxeventskip} to
63 allow the default processing to take place as otherwise the window under mouse
64 wouldn't get the focus.}
65 \twocolitem{{\bf EVT\_LEFT\_UP(func)}}{Process a wxEVT\_LEFT\_UP event.}
66 \twocolitem{{\bf EVT\_LEFT\_DCLICK(func)}}{Process a wxEVT\_LEFT\_DCLICK event.}
67 \twocolitem{{\bf EVT\_MIDDLE\_DOWN(func)}}{Process a wxEVT\_MIDDLE\_DOWN event.}
68 \twocolitem{{\bf EVT\_MIDDLE\_UP(func)}}{Process a wxEVT\_MIDDLE\_UP event.}
69 \twocolitem{{\bf EVT\_MIDDLE\_DCLICK(func)}}{Process a wxEVT\_MIDDLE\_DCLICK event.}
70 \twocolitem{{\bf EVT\_RIGHT\_DOWN(func)}}{Process a wxEVT\_RIGHT\_DOWN event.}
71 \twocolitem{{\bf EVT\_RIGHT\_UP(func)}}{Process a wxEVT\_RIGHT\_UP event.}
72 \twocolitem{{\bf EVT\_RIGHT\_DCLICK(func)}}{Process a wxEVT\_RIGHT\_DCLICK event.}
73 \twocolitem{{\bf EVT\_MOUSE\_AUX1\_DOWN(func)}}{Process a wxEVT\_MOUSE\_AUX1\_DOWN event.}
74 \twocolitem{{\bf EVT\_MOUSE\_AUX1\_UP(func)}}{Process a wxEVT\_MOUSE\_AUX1\_UP event.}
75 \twocolitem{{\bf EVT\_MOUSE\_AUX1\_DCLICK(func)}}{Process a wxEVT\_MOUSE\_AUX1\_DCLICK event.}
76 \twocolitem{{\bf EVT\_MOUSE\_AUX2\_DOWN(func)}}{Process a wxEVT\_MOUSE\_AUX2\_DOWN event.}
77 \twocolitem{{\bf EVT\_MOUSE\_AUX2\_UP(func)}}{Process a wxEVT\_MOUSE\_AUX2\_UP event.}
78 \twocolitem{{\bf EVT\_MOUSE\_AUX2\_DCLICK(func)}}{Process a wxEVT\_MOUSE\_AUX2\_DCLICK event.}
79 \twocolitem{{\bf EVT\_MOTION(func)}}{Process a wxEVT\_MOTION event.}
80 \twocolitem{{\bf EVT\_ENTER\_WINDOW(func)}}{Process a wxEVT\_ENTER\_WINDOW event.}
81 \twocolitem{{\bf EVT\_LEAVE\_WINDOW(func)}}{Process a wxEVT\_LEAVE\_WINDOW event.}
82 \twocolitem{{\bf EVT\_MOUSEWHEEL(func)}}{Process a wxEVT\_MOUSEWHEEL event.}
83 \twocolitem{{\bf EVT\_MOUSE\_EVENTS(func)}}{Process all mouse events.}
84 \end{twocollist}%
85
86 \latexignore{\rtfignore{\wxheading{Members}}}
87
88
89 \membersection{wxMouseEvent::m\_altDown}\label{wxmouseeventmaltdown}
90
91 \member{bool}{m\_altDown}
92
93 true if the Alt key is pressed down.
94
95
96 \membersection{wxMouseEvent::m\_controlDown}\label{wxmouseeventmcontroldown}
97
98 \member{bool}{m\_controlDown}
99
100 true if control key is pressed down.
101
102
103 \membersection{wxMouseEvent::m\_leftDown}\label{wxmouseeventmleftdown}
104
105 \member{bool}{m\_leftDown}
106
107 true if the left mouse button is currently pressed down.
108
109
110 \membersection{wxMouseEvent::m\_middleDown}\label{wxmouseeventmmiddledown}
111
112 \member{bool}{m\_middleDown}
113
114 true if the middle mouse button is currently pressed down.
115
116
117 \membersection{wxMouseEvent::m\_rightDown}\label{wxmouseeventmrightdown}
118
119 \member{bool}{m\_rightDown}
120
121 true if the right mouse button is currently pressed down.
122
123
124 \membersection{wxMouseEvent::m\_metaDown}\label{wxmouseeventmmetadown}
125
126 \member{bool}{m\_metaDown}
127
128 true if the Meta key is pressed down.
129
130
131 \membersection{wxMouseEvent::m\_shiftDown}\label{wxmouseeventmshiftdown}
132
133 \member{bool}{m\_shiftDown}
134
135 true if shift is pressed down.
136
137
138 \membersection{wxMouseEvent::m\_x}\label{wxmouseeventmx}
139
140 \member{long}{m\_x}
141
142 X-coordinate of the event.
143
144
145 \membersection{wxMouseEvent::m\_y}\label{wxmouseeventmy}
146
147 \member{long}{m\_y}
148
149 Y-coordinate of the event.
150
151
152 \membersection{wxMouseEvent::m\_wheelRotation}\label{wxmouseeventmwheelrotation}
153
154 \member{int}{m\_wheelRotation}
155
156 The distance the mouse wheel is rotated.
157
158
159 \membersection{wxMouseEvent::m\_wheelDelta}\label{wxmouseeventmwheeldelta}
160
161 \member{int}{m\_wheelDelta}
162
163 The wheel delta, normally $120$.
164
165
166 \membersection{wxMouseEvent::m\_linesPerAction}\label{wxmouseeventmlinesperaction}
167
168 \member{int}{m\_linesPerAction}
169
170 The configured number of lines (or whatever) to be scrolled per wheel
171 action.
172
173
174
175 \membersection{wxMouseEvent::wxMouseEvent}\label{wxmouseeventctor}
176
177 \func{}{wxMouseEvent}{\param{WXTYPE}{ mouseEventType = 0}}
178
179 Constructor. Valid event types are:
180
181 \begin{itemize}
182 \itemsep=0pt
183 \item {\bf wxEVT\_ENTER\_WINDOW}
184 \item {\bf wxEVT\_LEAVE\_WINDOW}
185 \item {\bf wxEVT\_LEFT\_DOWN}
186 \item {\bf wxEVT\_LEFT\_UP}
187 \item {\bf wxEVT\_LEFT\_DCLICK}
188 \item {\bf wxEVT\_MIDDLE\_DOWN}
189 \item {\bf wxEVT\_MIDDLE\_UP}
190 \item {\bf wxEVT\_MIDDLE\_DCLICK}
191 \item {\bf wxEVT\_RIGHT\_DOWN}
192 \item {\bf wxEVT\_RIGHT\_UP}
193 \item {\bf wxEVT\_RIGHT\_DCLICK}
194 \item {\bf wxEVT\_MOUSE\_AUX1\_DOWN}
195 \item {\bf wxEVT\_MOUSE\_AUX1\_UP}
196 \item {\bf wxEVT\_MOUSE\_AUX1\_DCLICK}
197 \item {\bf wxEVT\_MOUSE\_AUX2\_DOWN}
198 \item {\bf wxEVT\_MOUSE\_AUX2\_UP}
199 \item {\bf wxEVT\_MOUSE\_AUX2\_DCLICK}
200 \item {\bf wxEVT\_MOTION}
201 \item {\bf wxEVT\_MOUSEWHEEL}
202 \end{itemize}
203
204
205 \membersection{wxMouseEvent::AltDown}\label{wxmouseeventaltdown}
206
207 \func{bool}{AltDown}{\void}
208
209 Returns true if the Alt key was down at the time of the event.
210
211
212 \membersection{wxMouseEvent::Aux1DClick}\label{wxmouseeventaux1dclick}
213
214 \constfunc{bool}{Aux1DClick}{\void}
215
216 Returns true if the event was a first extra button double click.
217
218
219 \membersection{wxMouseEvent::Aux1Down}\label{wxmouseeventaux1down}
220
221 \constfunc{bool}{Aux1Down}{\void}
222
223 Returns true if the first extra button mouse button changed to down.
224
225
226 \membersection{wxMouseEvent::Aux1IsDown}\label{wxmouseeventaux1isdown}
227
228 \constfunc{bool}{Aux1IsDown}{\void}
229
230 Returns true if the first extra button mouse button is currently down, independent
231 of the current event type.
232
233
234 \membersection{wxMouseEvent::Aux1Up}\label{wxmouseeventaux1up}
235
236 \constfunc{bool}{Aux1Up}{\void}
237
238 Returns true if the first extra button mouse button changed to up.
239
240
241 \membersection{wxMouseEvent::Aux2DClick}\label{wxmouseeventaux2dclick}
242
243 \constfunc{bool}{Aux2DClick}{\void}
244
245 Returns true if the event was a second extra button double click.
246
247
248 \membersection{wxMouseEvent::Aux2Down}\label{wxmouseeventaux2down}
249
250 \constfunc{bool}{Aux2Down}{\void}
251
252 Returns true if the second extra button mouse button changed to down.
253
254
255 \membersection{wxMouseEvent::Aux2IsDown}\label{wxmouseeventaux2isdown}
256
257 \constfunc{bool}{Aux2IsDown}{\void}
258
259 Returns true if the second extra button mouse button is currently down, independent
260 of the current event type.
261
262
263 \membersection{wxMouseEvent::Aux2Up}\label{wxmouseeventaux2up}
264
265 \constfunc{bool}{Aux2Up}{\void}
266
267 Returns true if the second extra button mouse button changed to up.
268
269
270 \membersection{wxMouseEvent::Button}\label{wxmouseeventbutton}
271
272 \func{bool}{Button}{\param{int}{ button}}
273
274 Returns true if the identified mouse button is changing state. Valid
275 values of {\it button} are:
276
277 \begin{twocollist}\itemsep=0pt
278 \twocolitem{{\tt wxMOUSE\_BTN\_LEFT}}{check if left button was pressed}
279 \twocolitem{{\tt wxMOUSE\_BTN\_MIDDLE}}{check if middle button was pressed}
280 \twocolitem{{\tt wxMOUSE\_BTN\_RIGHT}}{check if right button was pressed}
281 \twocolitem{{\tt wxMOUSE\_BTN\_AUX1}}{check if the first extra button was pressed}
282 \twocolitem{{\tt wxMOUSE\_BTN\_AUX2}}{check if the second extra button was pressed}
283 \twocolitem{{\tt wxMOUSE\_BTN\_ANY}}{check if any button was pressed}
284 \end{twocollist}
285
286
287 \membersection{wxMouseEvent::ButtonDClick}\label{wxmouseeventbuttondclick}
288
289 \func{bool}{ButtonDClick}{\param{int}{ but = wxMOUSE\_BTN\_ANY}}
290
291 If the argument is omitted, this returns true if the event was a mouse
292 double click event. Otherwise the argument specifies which double click event
293 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
294 values).
295
296
297 \membersection{wxMouseEvent::ButtonDown}\label{wxmouseeventbuttondown}
298
299 \func{bool}{ButtonDown}{\param{int}{ but = -1}}
300
301 If the argument is omitted, this returns true if the event was a mouse
302 button down event. Otherwise the argument specifies which button-down event
303 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
304 values).
305
306
307
308 \membersection{wxMouseEvent::ButtonUp}\label{wxmouseeventbuttonup}
309
310 \func{bool}{ButtonUp}{\param{int}{ but = -1}}
311
312 If the argument is omitted, this returns true if the event was a mouse
313 button up event. Otherwise the argument specifies which button-up event
314 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
315 values).
316
317
318
319 \membersection{wxMouseEvent::CmdDown}\label{wxmouseeventcmddown}
320
321 \constfunc{bool}{CmdDown}{\void}
322
323 Same as \helpref{MetaDown}{wxmouseeventmetadown} under Mac, same as
324 \helpref{ControlDown}{wxmouseeventcontroldown} elsewhere.
325
326 \wxheading{See also}
327
328 \helpref{wxKeyEvent::CmdDown}{wxkeyeventcmddown}
329
330
331 \membersection{wxMouseEvent::ControlDown}\label{wxmouseeventcontroldown}
332
333 \func{bool}{ControlDown}{\void}
334
335 Returns true if the control key was down at the time of the event.
336
337
338 \membersection{wxMouseEvent::Dragging}\label{wxmouseeventdragging}
339
340 \func{bool}{Dragging}{\void}
341
342 Returns true if this was a dragging event (motion while a button is depressed).
343
344 \wxheading{See also}
345
346 \helpref{Moving}{wxmouseeventmoving}
347
348
349 \membersection{wxMouseEvent::Entering}\label{wxmouseevententering}
350
351 \func{bool}{Entering}{\void}
352
353 Returns true if the mouse was entering the window.
354
355 See also \helpref{wxMouseEvent::Leaving}{wxmouseeventleaving}.
356
357
358 \membersection{wxMouseEvent::GetButton}\label{wxmouseeventgetbutton}
359
360 \constfunc{int}{GetButton}{\void}
361
362 Returns the mouse button which generated this event or {\tt wxMOUSE\_BTN\_NONE}
363 if no button is involved (for mouse move, enter or leave event, for example).
364 Otherwise {\tt wxMOUSE\_BTN\_LEFT} is returned for the left button down, up and
365 double click events, {\tt wxMOUSE\_BTN\_MIDDLE} and {\tt wxMOUSE\_BTN\_RIGHT}
366 for the same events for the middle and the right buttons respectively.
367
368
369 \membersection{wxMouseEvent::GetPosition}\label{wxmouseeventgetposition}
370
371 \constfunc{wxPoint}{GetPosition}{\void}
372
373 \constfunc{void}{GetPosition}{\param{wxCoord*}{ x}, \param{wxCoord*}{ y}}
374
375 \constfunc{void}{GetPosition}{\param{long*}{ x}, \param{long*}{ y}}
376
377 Sets *x and *y to the position at which the event occurred.
378
379 Returns the physical mouse position in pixels.
380
381 Note that if the mouse event has been artificially generated from a special
382 keyboard combination (e.g. under Windows when the ``menu'' key is pressed), the
383 returned position is \texttt{wxDefaultPosition}.
384
385
386 \membersection{wxMouseEvent::GetLogicalPosition}\label{wxmouseeventgetlogicalposition}
387
388 \constfunc{wxPoint}{GetLogicalPosition}{\param{const wxDC\&}{ dc}}
389
390 Returns the logical mouse position in pixels (i.e. translated according to the
391 translation set for the DC, which usually indicates that the window has been scrolled).
392
393
394
395 \membersection{wxMouseEvent::GetLinesPerAction}\label{wxmouseeventgetlinesperaction}
396
397 \constfunc{int}{GetLinesPerAction}{\void}
398
399 Returns the configured number of lines (or whatever) to be scrolled per
400 wheel action. Defaults to three.
401
402
403 \membersection{wxMouseEvent::GetWheelRotation}\label{wxmouseeventgetwheelrotation}
404
405 \constfunc{int}{GetWheelRotation}{\void}
406
407 Get wheel rotation, positive or negative indicates direction of
408 rotation. Current devices all send an event when rotation is at least
409 +/-WheelDelta, but finer resolution devices can be created in the future.
410 Because of this you shouldn't assume that one event is equal to 1 line, but you
411 should be able to either do partial line scrolling or wait until several
412 events accumulate before scrolling.
413
414
415 \membersection{wxMouseEvent::GetWheelDelta}\label{wxmouseeventgetwheeldelta}
416
417 \constfunc{int}{GetWheelDelta}{\void}
418
419 Get wheel delta, normally $120$. This is the threshold for action to be
420 taken, and one such action (for example, scrolling one increment)
421 should occur for each delta.
422
423
424 \membersection{wxMouseEvent::GetX}\label{wxmouseeventgetx}
425
426 \constfunc{long}{GetX}{\void}
427
428 Returns X coordinate of the physical mouse event position.
429
430
431 \membersection{wxMouseEvent::GetY}\label{wxmouseeventgety}
432
433 \func{long}{GetY}{\void}
434
435 Returns Y coordinate of the physical mouse event position.
436
437
438 \membersection{wxMouseEvent::IsButton}\label{wxmouseeventisbutton}
439
440 \constfunc{bool}{IsButton}{\void}
441
442 Returns true if the event was a mouse button event (not necessarily a button down event -
443 that may be tested using {\it ButtonDown}).
444
445
446 \membersection{wxMouseEvent::IsPageScroll}\label{wxmouseeventispagescroll}
447
448 \constfunc{bool}{IsPageScroll}{\void}
449
450 Returns true if the system has been setup to do page scrolling with
451 the mouse wheel instead of line scrolling.
452
453
454 \membersection{wxMouseEvent::Leaving}\label{wxmouseeventleaving}
455
456 \constfunc{bool}{Leaving}{\void}
457
458 Returns true if the mouse was leaving the window.
459
460 See also \helpref{wxMouseEvent::Entering}{wxmouseevententering}.
461
462
463 \membersection{wxMouseEvent::LeftDClick}\label{wxmouseeventleftdclick}
464
465 \constfunc{bool}{LeftDClick}{\void}
466
467 Returns true if the event was a left double click.
468
469
470 \membersection{wxMouseEvent::LeftDown}\label{wxmouseeventleftdown}
471
472 \constfunc{bool}{LeftDown}{\void}
473
474 Returns true if the left mouse button changed to down.
475
476
477 \membersection{wxMouseEvent::LeftIsDown}\label{wxmouseeventleftisdown}
478
479 \constfunc{bool}{LeftIsDown}{\void}
480
481 Returns true if the left mouse button is currently down, independent
482 of the current event type.
483
484 Please notice that it is \emph{not} the same as
485 \helpref{LeftDown}{wxmouseeventleftdown} which returns \true if the event was
486 generated by the left mouse button being pressed. Rather, it simply describes
487 the state of the left mouse button at the time when the event was generated
488 (so while it will be true for a left click event, it can also be true for
489 a right click if it happened while the left mouse button was pressed).
490
491 This event is usually used in the mouse event handlers which process "move
492 mouse" messages to determine whether the user is (still) dragging the mouse.
493
494
495 \membersection{wxMouseEvent::LeftUp}\label{wxmouseeventleftup}
496
497 \constfunc{bool}{LeftUp}{\void}
498
499 Returns true if the left mouse button changed to up.
500
501
502 \membersection{wxMouseEvent::MetaDown}\label{wxmouseeventmetadown}
503
504 \constfunc{bool}{MetaDown}{\void}
505
506 Returns true if the Meta key was down at the time of the event.
507
508
509 \membersection{wxMouseEvent::MiddleDClick}\label{wxmouseeventmiddledclick}
510
511 \constfunc{bool}{MiddleDClick}{\void}
512
513 Returns true if the event was a middle double click.
514
515
516 \membersection{wxMouseEvent::MiddleDown}\label{wxmouseeventmiddledown}
517
518 \constfunc{bool}{MiddleDown}{\void}
519
520 Returns true if the middle mouse button changed to down.
521
522
523 \membersection{wxMouseEvent::MiddleIsDown}\label{wxmouseeventmiddleisdown}
524
525 \constfunc{bool}{MiddleIsDown}{\void}
526
527 Returns true if the middle mouse button is currently down, independent
528 of the current event type.
529
530
531 \membersection{wxMouseEvent::MiddleUp}\label{wxmouseeventmiddleup}
532
533 \constfunc{bool}{MiddleUp}{\void}
534
535 Returns true if the middle mouse button changed to up.
536
537
538 \membersection{wxMouseEvent::Moving}\label{wxmouseeventmoving}
539
540 \constfunc{bool}{Moving}{\void}
541
542 Returns true if this was a motion event and no mouse buttons were pressed.
543 If any mouse button is held pressed, then this method returns \false and
544 \helpref{Dragging}{wxmouseeventdragging} returns \true.
545
546
547 \membersection{wxMouseEvent::RightDClick}\label{wxmouseeventrightdclick}
548
549 \constfunc{bool}{RightDClick}{\void}
550
551 Returns true if the event was a right double click.
552
553
554 \membersection{wxMouseEvent::RightDown}\label{wxmouseeventrightdown}
555
556 \constfunc{bool}{RightDown}{\void}
557
558 Returns true if the right mouse button changed to down.
559
560
561 \membersection{wxMouseEvent::RightIsDown}\label{wxmouseeventrightisdown}
562
563 \constfunc{bool}{RightIsDown}{\void}
564
565 Returns true if the right mouse button is currently down, independent
566 of the current event type.
567
568
569 \membersection{wxMouseEvent::RightUp}\label{wxmouseeventrightup}
570
571 \constfunc{bool}{RightUp}{\void}
572
573 Returns true if the right mouse button changed to up.
574
575
576 \membersection{wxMouseEvent::ShiftDown}\label{wxmouseeventshiftdown}
577
578 \constfunc{bool}{ShiftDown}{\void}
579
580 Returns true if the shift key was down at the time of the event.
581