1 \section{\class{wxMouseEvent
}}\label{wxmouseevent
}
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.
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).
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.
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
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
41 \wxheading{Derived from
}
43 \helpref{wxEvent
}{wxevent
}\\
44 \helpref{wxObject
}{wxobject
}
46 \wxheading{Include files
}
52 \helpref{wxCore
}{librarieslist
}
54 \wxheading{Event table macros
}
56 To process a mouse event, use these event handler macros to direct input to member
57 functions that take a wxMouseEvent argument.
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.
}
86 \latexignore{\rtfignore{\wxheading{Members
}}}
89 \membersection{wxMouseEvent::m
\_altDown}\label{wxmouseeventmaltdown
}
91 \member{bool
}{m
\_altDown}
93 true if the Alt key is pressed down.
96 \membersection{wxMouseEvent::m
\_controlDown}\label{wxmouseeventmcontroldown
}
98 \member{bool
}{m
\_controlDown}
100 true if control key is pressed down.
103 \membersection{wxMouseEvent::m
\_leftDown}\label{wxmouseeventmleftdown
}
105 \member{bool
}{m
\_leftDown}
107 true if the left mouse button is currently pressed down.
110 \membersection{wxMouseEvent::m
\_middleDown}\label{wxmouseeventmmiddledown
}
112 \member{bool
}{m
\_middleDown}
114 true if the middle mouse button is currently pressed down.
117 \membersection{wxMouseEvent::m
\_rightDown}\label{wxmouseeventmrightdown
}
119 \member{bool
}{m
\_rightDown}
121 true if the right mouse button is currently pressed down.
124 \membersection{wxMouseEvent::m
\_metaDown}\label{wxmouseeventmmetadown
}
126 \member{bool
}{m
\_metaDown}
128 true if the Meta key is pressed down.
131 \membersection{wxMouseEvent::m
\_shiftDown}\label{wxmouseeventmshiftdown
}
133 \member{bool
}{m
\_shiftDown}
135 true if shift is pressed down.
138 \membersection{wxMouseEvent::m
\_x}\label{wxmouseeventmx
}
142 X-coordinate of the event.
145 \membersection{wxMouseEvent::m
\_y}\label{wxmouseeventmy
}
149 Y-coordinate of the event.
152 \membersection{wxMouseEvent::m
\_wheelRotation}\label{wxmouseeventmwheelrotation
}
154 \member{int
}{m
\_wheelRotation}
156 The distance the mouse wheel is rotated.
159 \membersection{wxMouseEvent::m
\_wheelDelta}\label{wxmouseeventmwheeldelta
}
161 \member{int
}{m
\_wheelDelta}
163 The wheel delta, normally $
120$.
166 \membersection{wxMouseEvent::m
\_linesPerAction}\label{wxmouseeventmlinesperaction
}
168 \member{int
}{m
\_linesPerAction}
170 The configured number of lines (or whatever) to be scrolled per wheel
175 \membersection{wxMouseEvent::wxMouseEvent
}\label{wxmouseeventctor
}
177 \func{}{wxMouseEvent
}{\param{WXTYPE
}{ mouseEventType =
0}}
179 Constructor. Valid event types are:
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}
205 \membersection{wxMouseEvent::AltDown
}\label{wxmouseeventaltdown
}
207 \func{bool
}{AltDown
}{\void}
209 Returns true if the Alt key was down at the time of the event.
212 \membersection{wxMouseEvent::Aux1DClick
}\label{wxmouseeventaux1dclick
}
214 \constfunc{bool
}{Aux1DClick
}{\void}
216 Returns true if the event was a first extra button double click.
219 \membersection{wxMouseEvent::Aux1Down
}\label{wxmouseeventaux1down
}
221 \constfunc{bool
}{Aux1Down
}{\void}
223 Returns true if the first extra button mouse button changed to down.
226 \membersection{wxMouseEvent::Aux1IsDown
}\label{wxmouseeventaux1isdown
}
228 \constfunc{bool
}{Aux1IsDown
}{\void}
230 Returns true if the first extra button mouse button is currently down, independent
231 of the current event type.
234 \membersection{wxMouseEvent::Aux1Up
}\label{wxmouseeventaux1up
}
236 \constfunc{bool
}{Aux1Up
}{\void}
238 Returns true if the first extra button mouse button changed to up.
241 \membersection{wxMouseEvent::Aux2DClick
}\label{wxmouseeventaux2dclick
}
243 \constfunc{bool
}{Aux2DClick
}{\void}
245 Returns true if the event was a second extra button double click.
248 \membersection{wxMouseEvent::Aux2Down
}\label{wxmouseeventaux2down
}
250 \constfunc{bool
}{Aux2Down
}{\void}
252 Returns true if the second extra button mouse button changed to down.
255 \membersection{wxMouseEvent::Aux2IsDown
}\label{wxmouseeventaux2isdown
}
257 \constfunc{bool
}{Aux2IsDown
}{\void}
259 Returns true if the second extra button mouse button is currently down, independent
260 of the current event type.
263 \membersection{wxMouseEvent::Aux2Up
}\label{wxmouseeventaux2up
}
265 \constfunc{bool
}{Aux2Up
}{\void}
267 Returns true if the second extra button mouse button changed to up.
270 \membersection{wxMouseEvent::Button
}\label{wxmouseeventbutton
}
272 \func{bool
}{Button
}{\param{int
}{ button
}}
274 Returns true if the identified mouse button is changing state. Valid
275 values of
{\it button
} are:
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
}
287 \membersection{wxMouseEvent::ButtonDClick
}\label{wxmouseeventbuttondclick
}
289 \func{bool
}{ButtonDClick
}{\param{int
}{ but = wxMOUSE
\_BTN\_ANY}}
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
297 \membersection{wxMouseEvent::ButtonDown
}\label{wxmouseeventbuttondown
}
299 \func{bool
}{ButtonDown
}{\param{int
}{ but = -
1}}
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
308 \membersection{wxMouseEvent::ButtonUp
}\label{wxmouseeventbuttonup
}
310 \func{bool
}{ButtonUp
}{\param{int
}{ but = -
1}}
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
319 \membersection{wxMouseEvent::CmdDown
}\label{wxmouseeventcmddown
}
321 \constfunc{bool
}{CmdDown
}{\void}
323 Same as
\helpref{MetaDown
}{wxmouseeventmetadown
} under Mac, same as
324 \helpref{ControlDown
}{wxmouseeventcontroldown
} elsewhere.
328 \helpref{wxKeyEvent::CmdDown
}{wxkeyeventcmddown
}
331 \membersection{wxMouseEvent::ControlDown
}\label{wxmouseeventcontroldown
}
333 \func{bool
}{ControlDown
}{\void}
335 Returns true if the control key was down at the time of the event.
338 \membersection{wxMouseEvent::Dragging
}\label{wxmouseeventdragging
}
340 \func{bool
}{Dragging
}{\void}
342 Returns true if this was a dragging event (motion while a button is depressed).
346 \helpref{Moving
}{wxmouseeventmoving
}
349 \membersection{wxMouseEvent::Entering
}\label{wxmouseevententering
}
351 \func{bool
}{Entering
}{\void}
353 Returns true if the mouse was entering the window.
355 See also
\helpref{wxMouseEvent::Leaving
}{wxmouseeventleaving
}.
358 \membersection{wxMouseEvent::GetButton
}\label{wxmouseeventgetbutton
}
360 \constfunc{int
}{GetButton
}{\void}
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.
369 \membersection{wxMouseEvent::GetClickCount
}\label{wxmouseeventgetclickcount
}
371 \constfunc{int
}{GetClickCount
}{\void}
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.
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).
383 \membersection{wxMouseEvent::GetPosition
}\label{wxmouseeventgetposition
}
385 \constfunc{wxPoint
}{GetPosition
}{\void}
387 \constfunc{void
}{GetPosition
}{\param{wxCoord*
}{ x
},
\param{wxCoord*
}{ y
}}
389 \constfunc{void
}{GetPosition
}{\param{long*
}{ x
},
\param{long*
}{ y
}}
391 Sets *x and *y to the position at which the event occurred.
393 Returns the physical mouse position in pixels.
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
}.
400 \membersection{wxMouseEvent::GetLogicalPosition
}\label{wxmouseeventgetlogicalposition
}
402 \constfunc{wxPoint
}{GetLogicalPosition
}{\param{const wxDC\&
}{ dc
}}
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).
409 \membersection{wxMouseEvent::GetLinesPerAction
}\label{wxmouseeventgetlinesperaction
}
411 \constfunc{int
}{GetLinesPerAction
}{\void}
413 Returns the configured number of lines (or whatever) to be scrolled per
414 wheel action. Defaults to three.
417 \membersection{wxMouseEvent::GetWheelRotation
}\label{wxmouseeventgetwheelrotation
}
419 \constfunc{int
}{GetWheelRotation
}{\void}
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.
429 \membersection{wxMouseEvent::GetWheelDelta
}\label{wxmouseeventgetwheeldelta
}
431 \constfunc{int
}{GetWheelDelta
}{\void}
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.
438 \membersection{wxMouseEvent::GetX
}\label{wxmouseeventgetx
}
440 \constfunc{long
}{GetX
}{\void}
442 Returns X coordinate of the physical mouse event position.
445 \membersection{wxMouseEvent::GetY
}\label{wxmouseeventgety
}
447 \func{long
}{GetY
}{\void}
449 Returns Y coordinate of the physical mouse event position.
452 \membersection{wxMouseEvent::IsButton
}\label{wxmouseeventisbutton
}
454 \constfunc{bool
}{IsButton
}{\void}
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
}).
460 \membersection{wxMouseEvent::IsPageScroll
}\label{wxmouseeventispagescroll
}
462 \constfunc{bool
}{IsPageScroll
}{\void}
464 Returns true if the system has been setup to do page scrolling with
465 the mouse wheel instead of line scrolling.
468 \membersection{wxMouseEvent::Leaving
}\label{wxmouseeventleaving
}
470 \constfunc{bool
}{Leaving
}{\void}
472 Returns true if the mouse was leaving the window.
474 See also
\helpref{wxMouseEvent::Entering
}{wxmouseevententering
}.
477 \membersection{wxMouseEvent::LeftDClick
}\label{wxmouseeventleftdclick
}
479 \constfunc{bool
}{LeftDClick
}{\void}
481 Returns true if the event was a left double click.
484 \membersection{wxMouseEvent::LeftDown
}\label{wxmouseeventleftdown
}
486 \constfunc{bool
}{LeftDown
}{\void}
488 Returns true if the left mouse button changed to down.
491 \membersection{wxMouseEvent::LeftIsDown
}\label{wxmouseeventleftisdown
}
493 \constfunc{bool
}{LeftIsDown
}{\void}
495 Returns true if the left mouse button is currently down, independent
496 of the current event type.
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).
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.
509 \membersection{wxMouseEvent::LeftUp
}\label{wxmouseeventleftup
}
511 \constfunc{bool
}{LeftUp
}{\void}
513 Returns true if the left mouse button changed to up.
516 \membersection{wxMouseEvent::MetaDown
}\label{wxmouseeventmetadown
}
518 \constfunc{bool
}{MetaDown
}{\void}
520 Returns true if the Meta key was down at the time of the event.
523 \membersection{wxMouseEvent::MiddleDClick
}\label{wxmouseeventmiddledclick
}
525 \constfunc{bool
}{MiddleDClick
}{\void}
527 Returns true if the event was a middle double click.
530 \membersection{wxMouseEvent::MiddleDown
}\label{wxmouseeventmiddledown
}
532 \constfunc{bool
}{MiddleDown
}{\void}
534 Returns true if the middle mouse button changed to down.
537 \membersection{wxMouseEvent::MiddleIsDown
}\label{wxmouseeventmiddleisdown
}
539 \constfunc{bool
}{MiddleIsDown
}{\void}
541 Returns true if the middle mouse button is currently down, independent
542 of the current event type.
545 \membersection{wxMouseEvent::MiddleUp
}\label{wxmouseeventmiddleup
}
547 \constfunc{bool
}{MiddleUp
}{\void}
549 Returns true if the middle mouse button changed to up.
552 \membersection{wxMouseEvent::Moving
}\label{wxmouseeventmoving
}
554 \constfunc{bool
}{Moving
}{\void}
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.
561 \membersection{wxMouseEvent::RightDClick
}\label{wxmouseeventrightdclick
}
563 \constfunc{bool
}{RightDClick
}{\void}
565 Returns true if the event was a right double click.
568 \membersection{wxMouseEvent::RightDown
}\label{wxmouseeventrightdown
}
570 \constfunc{bool
}{RightDown
}{\void}
572 Returns true if the right mouse button changed to down.
575 \membersection{wxMouseEvent::RightIsDown
}\label{wxmouseeventrightisdown
}
577 \constfunc{bool
}{RightIsDown
}{\void}
579 Returns true if the right mouse button is currently down, independent
580 of the current event type.
583 \membersection{wxMouseEvent::RightUp
}\label{wxmouseeventrightup
}
585 \constfunc{bool
}{RightUp
}{\void}
587 Returns true if the right mouse button changed to up.
590 \membersection{wxMouseEvent::ShiftDown
}\label{wxmouseeventshiftdown
}
592 \constfunc{bool
}{ShiftDown
}{\void}
594 Returns true if the shift key was down at the time of the event.