]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/mouseevt.tex
implemented nested index entries and index entries pointing to multiple documents...
[wxWidgets.git] / docs / latex / wx / mouseevt.tex
... / ...
CommitLineData
1\section{\class{wxMouseEvent}}\label{wxmouseevent}
2
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
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.
11
12{\bf NB:} Note that under Windows mouse enter and leave events are not natively supported
13by the system but are generated by wxWidgets itself. This has several
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
18{\bf NB:} Note the difference between methods like
19\helpref{LeftDown}{wxmouseeventleftdown} and
20\helpref{LeftIsDown}{wxmouseeventleftisdown}: the former returns {\tt true}
21when the event corresponds to the left mouse button click while the latter
22returns {\tt true} if the left mouse button is currently being pressed. For
23example, when the user is dragging the mouse you can use
24\helpref{LeftIsDown}{wxmouseeventleftisdown} to test
25whether the left mouse button is (still) depressed. Also, by convention, if
26\helpref{LeftDown}{wxmouseeventleftdown} returns {\tt true},
27\helpref{LeftIsDown}{wxmouseeventleftisdown} will also return {\tt true} in
28wxWidgets whatever the underlying GUI behaviour is (which is
29platform-dependent). The same applies, of course, to other mouse buttons as
30well.
31
32\wxheading{Derived from}
33
34\helpref{wxEvent}{wxevent}
35
36\wxheading{Include files}
37
38<wx/event.h>
39
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.}
59\twocolitem{{\bf EVT\_MOUSEWHEEL(func)}}{Process a wxEVT\_MOUSEWHEEL event.}
60\twocolitem{{\bf EVT\_MOUSE\_EVENTS(func)}}{Process all mouse events.}
61\end{twocollist}%
62
63\latexignore{\rtfignore{\wxheading{Members}}}
64
65
66\membersection{wxMouseEvent::m\_altDown}
67
68\member{bool}{m\_altDown}
69
70true if the Alt key is pressed down.
71
72
73\membersection{wxMouseEvent::m\_controlDown}
74
75\member{bool}{m\_controlDown}
76
77true if control key is pressed down.
78
79
80\membersection{wxMouseEvent::m\_leftDown}
81
82\member{bool}{m\_leftDown}
83
84true if the left mouse button is currently pressed down.
85
86
87\membersection{wxMouseEvent::m\_middleDown}
88
89\member{bool}{m\_middleDown}
90
91true if the middle mouse button is currently pressed down.
92
93
94\membersection{wxMouseEvent::m\_rightDown}
95
96\member{bool}{m\_rightDown}
97
98true if the right mouse button is currently pressed down.
99
100
101\membersection{wxMouseEvent::m\_metaDown}
102
103\member{bool}{m\_metaDown}
104
105true if the Meta key is pressed down.
106
107
108\membersection{wxMouseEvent::m\_shiftDown}
109
110\member{bool}{m\_shiftDown}
111
112true if shift is pressed down.
113
114
115\membersection{wxMouseEvent::m\_x}
116
117\member{long}{m\_x}
118
119X-coordinate of the event.
120
121
122\membersection{wxMouseEvent::m\_y}
123
124\member{long}{m\_y}
125
126Y-coordinate of the event.
127
128
129\membersection{wxMouseEvent::m\_wheelRotation}
130
131\member{int}{m\_wheelRotation}
132
133The distance the mouse wheel is rotated.
134
135
136\membersection{wxMouseEvent::m\_wheelDelta}
137
138\member{int}{m\_wheelDelta}
139
140The wheel delta, normally $120$.
141
142
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
151
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}
172\item {\bf wxEVT\_MOUSEWHEEL}
173\end{itemize}
174
175
176\membersection{wxMouseEvent::AltDown}
177
178\func{bool}{AltDown}{\void}
179
180Returns true if the Alt key was down at the time of the event.
181
182
183\membersection{wxMouseEvent::Button}\label{wxmouseeventbutton}
184
185\func{bool}{Button}{\param{int}{ button}}
186
187Returns true if the identified mouse button is changing state. Valid
188values of {\it button} are:
189
190\begin{twocollist}\itemsep=0pt
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}
195\end{twocollist}
196
197
198\membersection{wxMouseEvent::ButtonDClick}
199
200\func{bool}{ButtonDClick}{\param{int}{ but = wxMOUSE\_BTN\_ANY}}
201
202If the argument is omitted, this returns true if the event was a mouse
203double click event. Otherwise the argument specifies which double click event
204was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
205values).
206
207
208\membersection{wxMouseEvent::ButtonDown}
209
210\func{bool}{ButtonDown}{\param{int}{ but = -1}}
211
212If the argument is omitted, this returns true if the event was a mouse
213button down event. Otherwise the argument specifies which button-down event
214was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
215values).
216
217
218
219\membersection{wxMouseEvent::ButtonUp}
220
221\func{bool}{ButtonUp}{\param{int}{ but = -1}}
222
223If the argument is omitted, this returns true if the event was a mouse
224button up event. Otherwise the argument specifies which button-up event
225was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
226values).
227
228
229
230\membersection{wxMouseEvent::ControlDown}
231
232\func{bool}{ControlDown}{\void}
233
234Returns true if the control key was down at the time of the event.
235
236
237\membersection{wxMouseEvent::Dragging}\label{wxmouseeventdragging}
238
239\func{bool}{Dragging}{\void}
240
241Returns true if this was a dragging event (motion while a button is depressed).
242
243\wxheading{See also}
244
245\helpref{Moving}{wxmouseeventmoving}
246
247
248\membersection{wxMouseEvent::Entering}\label{wxmouseevententering}
249
250\func{bool}{Entering}{\void}
251
252Returns true if the mouse was entering the window.
253
254See also \helpref{wxMouseEvent::Leaving}{wxmouseeventleaving}.
255
256
257\membersection{wxMouseEvent::GetButton}\label{wxmouseeventgetbutton}
258
259\constfunc{int}{GetButton}{\void}
260
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.
266
267
268\membersection{wxMouseEvent::GetPosition}\label{wxmouseeventgetposition}
269
270\constfunc{wxPoint}{GetPosition}{\void}
271
272\constfunc{void}{GetPosition}{\param{wxCoord*}{ x}, \param{wxCoord*}{ y}}
273
274\constfunc{void}{GetPosition}{\param{long*}{ x}, \param{long*}{ y}}
275
276Sets *x and *y to the position at which the event occurred.
277
278Returns the physical mouse position in pixels.
279
280
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
288
289
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
295wheel action. Defaults to three.
296
297
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
310
311\membersection{wxMouseEvent::GetWheelDelta}\label{wxmouseeventgetwheeldelta}
312
313\constfunc{int}{GetWheelDelta}{\void}
314
315Get wheel delta, normally $120$. This is the threshold for action to be
316taken, and one such action (for example, scrolling one increment)
317should occur for each delta.
318
319
320\membersection{wxMouseEvent::GetX}\label{wxmouseeventgetx}
321
322\constfunc{long}{GetX}{\void}
323
324Returns X coordinate of the physical mouse event position.
325
326
327\membersection{wxMouseEvent::GetY}\label{wxmouseeventgety}
328
329\func{long}{GetY}{\void}
330
331Returns Y coordinate of the physical mouse event position.
332
333
334\membersection{wxMouseEvent::IsButton}
335
336\constfunc{bool}{IsButton}{\void}
337
338Returns true if the event was a mouse button event (not necessarily a button down event -
339that may be tested using {\it ButtonDown}).
340
341
342\membersection{wxMouseEvent::IsPageScroll}
343
344\constfunc{bool}{IsPageScroll}{\void}
345
346Returns true if the system has been setup to do page scrolling with
347the mouse wheel instead of line scrolling.
348
349
350\membersection{wxMouseEvent::Leaving}\label{wxmouseeventleaving}
351
352\constfunc{bool}{Leaving}{\void}
353
354Returns true if the mouse was leaving the window.
355
356See also \helpref{wxMouseEvent::Entering}{wxmouseevententering}.
357
358
359\membersection{wxMouseEvent::LeftDClick}
360
361\constfunc{bool}{LeftDClick}{\void}
362
363Returns true if the event was a left double click.
364
365
366\membersection{wxMouseEvent::LeftDown}\label{wxmouseeventleftdown}
367
368\constfunc{bool}{LeftDown}{\void}
369
370Returns true if the left mouse button changed to down.
371
372
373\membersection{wxMouseEvent::LeftIsDown}\label{wxmouseeventleftisdown}
374
375\constfunc{bool}{LeftIsDown}{\void}
376
377Returns true if the left mouse button is currently down, independent
378of the current event type.
379
380Please notice that it is {\bf not} the same as
381\helpref{LeftDown}{wxmouseeventleftdown} which returns true if the left mouse
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
388
389\membersection{wxMouseEvent::LeftUp}
390
391\constfunc{bool}{LeftUp}{\void}
392
393Returns true if the left mouse button changed to up.
394
395
396\membersection{wxMouseEvent::MetaDown}
397
398\constfunc{bool}{MetaDown}{\void}
399
400Returns true if the Meta key was down at the time of the event.
401
402
403\membersection{wxMouseEvent::MiddleDClick}
404
405\constfunc{bool}{MiddleDClick}{\void}
406
407Returns true if the event was a middle double click.
408
409
410\membersection{wxMouseEvent::MiddleDown}
411
412\constfunc{bool}{MiddleDown}{\void}
413
414Returns true if the middle mouse button changed to down.
415
416
417\membersection{wxMouseEvent::MiddleIsDown}\label{wxmouseeventmiddleisdown}
418
419\constfunc{bool}{MiddleIsDown}{\void}
420
421Returns true if the middle mouse button is currently down, independent
422of the current event type.
423
424
425\membersection{wxMouseEvent::MiddleUp}
426
427\constfunc{bool}{MiddleUp}{\void}
428
429Returns true if the middle mouse button changed to up.
430
431
432\membersection{wxMouseEvent::Moving}\label{wxmouseeventmoving}
433
434\constfunc{bool}{Moving}{\void}
435
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
440
441\membersection{wxMouseEvent::RightDClick}
442
443\constfunc{bool}{RightDClick}{\void}
444
445Returns true if the event was a right double click.
446
447
448\membersection{wxMouseEvent::RightDown}
449
450\constfunc{bool}{RightDown}{\void}
451
452Returns true if the right mouse button changed to down.
453
454
455\membersection{wxMouseEvent::RightIsDown}\label{wxmouseeventrightisdown}
456
457\constfunc{bool}{RightIsDown}{\void}
458
459Returns true if the right mouse button is currently down, independent
460of the current event type.
461
462
463\membersection{wxMouseEvent::RightUp}
464
465\constfunc{bool}{RightUp}{\void}
466
467Returns true if the right mouse button changed to up.
468
469
470\membersection{wxMouseEvent::ShiftDown}
471
472\constfunc{bool}{ShiftDown}{\void}
473
474Returns true if the shift key was down at the time of the event.
475