]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/mouseevt.tex
added null pointer check and assert
[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::GetClickCount}\label{wxmouseeventgetclickcount}
370
371 \constfunc{int}{GetClickCount}{\void}
372
373 Returns the number of mouse clicks for this event: $1$ for a simple click, $2$
374 for a double-click, $3$ for a triple-click and so on.
375
376 Currently this function is implemented only in wxMac and returns $-1$ for the
377 other platforms (you can still distinguish simple clicks from double-clicks as
378 they generate different kinds of events however).
379
380 \newsince{2.9.0}
381
382
383 \membersection{wxMouseEvent::GetPosition}\label{wxmouseeventgetposition}
384
385 \constfunc{wxPoint}{GetPosition}{\void}
386
387 \constfunc{void}{GetPosition}{\param{wxCoord*}{ x}, \param{wxCoord*}{ y}}
388
389 \constfunc{void}{GetPosition}{\param{long*}{ x}, \param{long*}{ y}}
390
391 Sets *x and *y to the position at which the event occurred.
392
393 Returns the physical mouse position in pixels.
394
395 Note that if the mouse event has been artificially generated from a special
396 keyboard combination (e.g. under Windows when the ``menu'' key is pressed), the
397 returned position is \texttt{wxDefaultPosition}.
398
399
400 \membersection{wxMouseEvent::GetLogicalPosition}\label{wxmouseeventgetlogicalposition}
401
402 \constfunc{wxPoint}{GetLogicalPosition}{\param{const wxDC\&}{ dc}}
403
404 Returns the logical mouse position in pixels (i.e. translated according to the
405 translation set for the DC, which usually indicates that the window has been scrolled).
406
407
408
409 \membersection{wxMouseEvent::GetLinesPerAction}\label{wxmouseeventgetlinesperaction}
410
411 \constfunc{int}{GetLinesPerAction}{\void}
412
413 Returns the configured number of lines (or whatever) to be scrolled per
414 wheel action. Defaults to three.
415
416
417 \membersection{wxMouseEvent::GetWheelRotation}\label{wxmouseeventgetwheelrotation}
418
419 \constfunc{int}{GetWheelRotation}{\void}
420
421 Get wheel rotation, positive or negative indicates direction of
422 rotation. Current devices all send an event when rotation is at least
423 +/-WheelDelta, but finer resolution devices can be created in the future.
424 Because of this you shouldn't assume that one event is equal to 1 line, but you
425 should be able to either do partial line scrolling or wait until several
426 events accumulate before scrolling.
427
428
429 \membersection{wxMouseEvent::GetWheelDelta}\label{wxmouseeventgetwheeldelta}
430
431 \constfunc{int}{GetWheelDelta}{\void}
432
433 Get wheel delta, normally $120$. This is the threshold for action to be
434 taken, and one such action (for example, scrolling one increment)
435 should occur for each delta.
436
437
438 \membersection{wxMouseEvent::GetX}\label{wxmouseeventgetx}
439
440 \constfunc{long}{GetX}{\void}
441
442 Returns X coordinate of the physical mouse event position.
443
444
445 \membersection{wxMouseEvent::GetY}\label{wxmouseeventgety}
446
447 \func{long}{GetY}{\void}
448
449 Returns Y coordinate of the physical mouse event position.
450
451
452 \membersection{wxMouseEvent::IsButton}\label{wxmouseeventisbutton}
453
454 \constfunc{bool}{IsButton}{\void}
455
456 Returns true if the event was a mouse button event (not necessarily a button down event -
457 that may be tested using {\it ButtonDown}).
458
459
460 \membersection{wxMouseEvent::IsPageScroll}\label{wxmouseeventispagescroll}
461
462 \constfunc{bool}{IsPageScroll}{\void}
463
464 Returns true if the system has been setup to do page scrolling with
465 the mouse wheel instead of line scrolling.
466
467
468 \membersection{wxMouseEvent::Leaving}\label{wxmouseeventleaving}
469
470 \constfunc{bool}{Leaving}{\void}
471
472 Returns true if the mouse was leaving the window.
473
474 See also \helpref{wxMouseEvent::Entering}{wxmouseevententering}.
475
476
477 \membersection{wxMouseEvent::LeftDClick}\label{wxmouseeventleftdclick}
478
479 \constfunc{bool}{LeftDClick}{\void}
480
481 Returns true if the event was a left double click.
482
483
484 \membersection{wxMouseEvent::LeftDown}\label{wxmouseeventleftdown}
485
486 \constfunc{bool}{LeftDown}{\void}
487
488 Returns true if the left mouse button changed to down.
489
490
491 \membersection{wxMouseEvent::LeftIsDown}\label{wxmouseeventleftisdown}
492
493 \constfunc{bool}{LeftIsDown}{\void}
494
495 Returns true if the left mouse button is currently down, independent
496 of the current event type.
497
498 Please notice that it is \emph{not} the same as
499 \helpref{LeftDown}{wxmouseeventleftdown} which returns \true if the event was
500 generated by the left mouse button being pressed. Rather, it simply describes
501 the state of the left mouse button at the time when the event was generated
502 (so while it will be true for a left click event, it can also be true for
503 a right click if it happened while the left mouse button was pressed).
504
505 This event is usually used in the mouse event handlers which process "move
506 mouse" messages to determine whether the user is (still) dragging the mouse.
507
508
509 \membersection{wxMouseEvent::LeftUp}\label{wxmouseeventleftup}
510
511 \constfunc{bool}{LeftUp}{\void}
512
513 Returns true if the left mouse button changed to up.
514
515
516 \membersection{wxMouseEvent::MetaDown}\label{wxmouseeventmetadown}
517
518 \constfunc{bool}{MetaDown}{\void}
519
520 Returns true if the Meta key was down at the time of the event.
521
522
523 \membersection{wxMouseEvent::MiddleDClick}\label{wxmouseeventmiddledclick}
524
525 \constfunc{bool}{MiddleDClick}{\void}
526
527 Returns true if the event was a middle double click.
528
529
530 \membersection{wxMouseEvent::MiddleDown}\label{wxmouseeventmiddledown}
531
532 \constfunc{bool}{MiddleDown}{\void}
533
534 Returns true if the middle mouse button changed to down.
535
536
537 \membersection{wxMouseEvent::MiddleIsDown}\label{wxmouseeventmiddleisdown}
538
539 \constfunc{bool}{MiddleIsDown}{\void}
540
541 Returns true if the middle mouse button is currently down, independent
542 of the current event type.
543
544
545 \membersection{wxMouseEvent::MiddleUp}\label{wxmouseeventmiddleup}
546
547 \constfunc{bool}{MiddleUp}{\void}
548
549 Returns true if the middle mouse button changed to up.
550
551
552 \membersection{wxMouseEvent::Moving}\label{wxmouseeventmoving}
553
554 \constfunc{bool}{Moving}{\void}
555
556 Returns true if this was a motion event and no mouse buttons were pressed.
557 If any mouse button is held pressed, then this method returns \false and
558 \helpref{Dragging}{wxmouseeventdragging} returns \true.
559
560
561 \membersection{wxMouseEvent::RightDClick}\label{wxmouseeventrightdclick}
562
563 \constfunc{bool}{RightDClick}{\void}
564
565 Returns true if the event was a right double click.
566
567
568 \membersection{wxMouseEvent::RightDown}\label{wxmouseeventrightdown}
569
570 \constfunc{bool}{RightDown}{\void}
571
572 Returns true if the right mouse button changed to down.
573
574
575 \membersection{wxMouseEvent::RightIsDown}\label{wxmouseeventrightisdown}
576
577 \constfunc{bool}{RightIsDown}{\void}
578
579 Returns true if the right mouse button is currently down, independent
580 of the current event type.
581
582
583 \membersection{wxMouseEvent::RightUp}\label{wxmouseeventrightup}
584
585 \constfunc{bool}{RightUp}{\void}
586
587 Returns true if the right mouse button changed to up.
588
589
590 \membersection{wxMouseEvent::ShiftDown}\label{wxmouseeventshiftdown}
591
592 \constfunc{bool}{ShiftDown}{\void}
593
594 Returns true if the shift key was down at the time of the event.
595