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