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