]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/mouseevt.tex
Deprecated SetItemImage with 2 image ids
[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. Note that not all mice have a
9 middle button so a portable application should avoid relying on the events from
10 it.
11
12 {\bf NB:} Note that under Windows mouse enter and leave events are not natively supported
13 by the system but are generated by wxWidgets itself. This has several
14 drawbacks: the LEAVE\_WINDOW event might be received some time after the mouse
15 left the window and the state variables for it may have changed during this
16 time.
17
18 {\bf NB:} Note the difference between methods like
19 \helpref{LeftDown}{wxmouseeventleftdown} and
20 \helpref{LeftIsDown}{wxmouseeventleftisdown}: the former returns {\tt true}
21 when the event corresponds to the left mouse button click while the latter
22 returns {\tt true} if the left mouse button is currently being pressed. For
23 example, when the user is dragging the mouse you can use
24 \helpref{LeftIsDown}{wxmouseeventleftisdown} to test
25 whether 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
28 wxWidgets whatever the underlying GUI behaviour is (which is
29 platform-dependent). The same applies, of course, to other mouse buttons as
30 well.
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
42 To process a mouse event, use these event handler macros to direct input to member
43 functions 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}\label{wxmouseeventmaltdown}
67
68 \member{bool}{m\_altDown}
69
70 true if the Alt key is pressed down.
71
72
73 \membersection{wxMouseEvent::m\_controlDown}\label{wxmouseeventmcontroldown}
74
75 \member{bool}{m\_controlDown}
76
77 true if control key is pressed down.
78
79
80 \membersection{wxMouseEvent::m\_leftDown}\label{wxmouseeventmleftdown}
81
82 \member{bool}{m\_leftDown}
83
84 true if the left mouse button is currently pressed down.
85
86
87 \membersection{wxMouseEvent::m\_middleDown}\label{wxmouseeventmmiddledown}
88
89 \member{bool}{m\_middleDown}
90
91 true if the middle mouse button is currently pressed down.
92
93
94 \membersection{wxMouseEvent::m\_rightDown}\label{wxmouseeventmrightdown}
95
96 \member{bool}{m\_rightDown}
97
98 true if the right mouse button is currently pressed down.
99
100
101 \membersection{wxMouseEvent::m\_metaDown}\label{wxmouseeventmmetadown}
102
103 \member{bool}{m\_metaDown}
104
105 true if the Meta key is pressed down.
106
107
108 \membersection{wxMouseEvent::m\_shiftDown}\label{wxmouseeventmshiftdown}
109
110 \member{bool}{m\_shiftDown}
111
112 true if shift is pressed down.
113
114
115 \membersection{wxMouseEvent::m\_x}\label{wxmouseeventmx}
116
117 \member{long}{m\_x}
118
119 X-coordinate of the event.
120
121
122 \membersection{wxMouseEvent::m\_y}\label{wxmouseeventmy}
123
124 \member{long}{m\_y}
125
126 Y-coordinate of the event.
127
128
129 \membersection{wxMouseEvent::m\_wheelRotation}\label{wxmouseeventmwheelrotation}
130
131 \member{int}{m\_wheelRotation}
132
133 The distance the mouse wheel is rotated.
134
135
136 \membersection{wxMouseEvent::m\_wheelDelta}\label{wxmouseeventmwheeldelta}
137
138 \member{int}{m\_wheelDelta}
139
140 The wheel delta, normally $120$.
141
142
143 \membersection{wxMouseEvent::m\_linesPerAction}\label{wxmouseeventmlinesperaction}
144
145 \member{int}{m\_linesPerAction}
146
147 The configured number of lines (or whatever) to be scrolled per wheel
148 action.
149
150
151
152 \membersection{wxMouseEvent::wxMouseEvent}\label{wxmouseeventctor}
153
154 \func{}{wxMouseEvent}{\param{WXTYPE}{ mouseEventType = 0}, \param{int}{ id = 0}}
155
156 Constructor. 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}\label{wxmouseeventaltdown}
177
178 \func{bool}{AltDown}{\void}
179
180 Returns 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
187 Returns true if the identified mouse button is changing state. Valid
188 values 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}\label{wxmouseeventbuttondclick}
199
200 \func{bool}{ButtonDClick}{\param{int}{ but = wxMOUSE\_BTN\_ANY}}
201
202 If the argument is omitted, this returns true if the event was a mouse
203 double click event. Otherwise the argument specifies which double click event
204 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
205 values).
206
207
208 \membersection{wxMouseEvent::ButtonDown}\label{wxmouseeventbuttondown}
209
210 \func{bool}{ButtonDown}{\param{int}{ but = -1}}
211
212 If the argument is omitted, this returns true if the event was a mouse
213 button down event. Otherwise the argument specifies which button-down event
214 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
215 values).
216
217
218
219 \membersection{wxMouseEvent::ButtonUp}\label{wxmouseeventbuttonup}
220
221 \func{bool}{ButtonUp}{\param{int}{ but = -1}}
222
223 If the argument is omitted, this returns true if the event was a mouse
224 button up event. Otherwise the argument specifies which button-up event
225 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
226 values).
227
228
229
230 \membersection{wxKeyEvent::CmdDown}\label{wxmouseeventcmddown}
231
232 \constfunc{bool}{CmdDown}{\void}
233
234 Same as \helpref{MetaDown}{wxmouseeventmetadown} under Mac, same as
235 \helpref{ControlDown}{wxmouseeventcontroldown} elsewhere.
236
237 \wxheading{See also}
238
239 \helpref{wxKeyEvent::CmdDown}{wxkeyeventcmddown}
240
241
242 \membersection{wxMouseEvent::ControlDown}\label{wxmouseeventcontroldown}
243
244 \func{bool}{ControlDown}{\void}
245
246 Returns true if the control key was down at the time of the event.
247
248
249 \membersection{wxMouseEvent::Dragging}\label{wxmouseeventdragging}
250
251 \func{bool}{Dragging}{\void}
252
253 Returns true if this was a dragging event (motion while a button is depressed).
254
255 \wxheading{See also}
256
257 \helpref{Moving}{wxmouseeventmoving}
258
259
260 \membersection{wxMouseEvent::Entering}\label{wxmouseevententering}
261
262 \func{bool}{Entering}{\void}
263
264 Returns true if the mouse was entering the window.
265
266 See also \helpref{wxMouseEvent::Leaving}{wxmouseeventleaving}.
267
268
269 \membersection{wxMouseEvent::GetButton}\label{wxmouseeventgetbutton}
270
271 \constfunc{int}{GetButton}{\void}
272
273 Returns the mouse button which generated this event or {\tt wxMOUSE\_BTN\_NONE}
274 if no button is involved (for mouse move, enter or leave event, for example).
275 Otherwise {\tt wxMOUSE\_BTN\_LEFT} is returned for the left button down, up and
276 double click events, {\tt wxMOUSE\_BTN\_MIDDLE} and {\tt wxMOUSE\_BTN\_RIGHT}
277 for the same events for the middle and the right buttons respectively.
278
279
280 \membersection{wxMouseEvent::GetPosition}\label{wxmouseeventgetposition}
281
282 \constfunc{wxPoint}{GetPosition}{\void}
283
284 \constfunc{void}{GetPosition}{\param{wxCoord*}{ x}, \param{wxCoord*}{ y}}
285
286 \constfunc{void}{GetPosition}{\param{long*}{ x}, \param{long*}{ y}}
287
288 Sets *x and *y to the position at which the event occurred.
289
290 Returns the physical mouse position in pixels.
291
292 Note that if the mouse event has been artificially generated from a special
293 keyboard combination (e.g. under Windows when the ``menu'' key is pressed), the
294 returned position is \texttt{wxDefaultPosition}.
295
296
297 \membersection{wxMouseEvent::GetLogicalPosition}\label{wxmouseeventgetlogicalposition}
298
299 \constfunc{wxPoint}{GetLogicalPosition}{\param{const wxDC\&}{ dc}}
300
301 Returns the logical mouse position in pixels (i.e. translated according to the
302 translation set for the DC, which usually indicates that the window has been scrolled).
303
304
305
306 \membersection{wxMouseEvent::GetLinesPerAction}\label{wxmouseeventgetlinesperaction}
307
308 \constfunc{int}{GetLinesPerAction}{\void}
309
310 Returns the configured number of lines (or whatever) to be scrolled per
311 wheel action. Defaults to three.
312
313
314 \membersection{wxMouseEvent::GetWheelRotation}\label{wxmouseeventgetwheelrotation}
315
316 \constfunc{int}{GetWheelRotation}{\void}
317
318 Get wheel rotation, positive or negative indicates direction of
319 rotation. Current devices all send an event when rotation is equal to
320 +/-WheelDelta, but this allows for finer resolution devices to be
321 created in the future. Because of this you shouldn't assume that one
322 event is equal to 1 line or whatever, but you should be able to either
323 do partial line scrolling or wait until +/-WheelDelta rotation values
324 have been accumulated before scrolling.
325
326
327 \membersection{wxMouseEvent::GetWheelDelta}\label{wxmouseeventgetwheeldelta}
328
329 \constfunc{int}{GetWheelDelta}{\void}
330
331 Get wheel delta, normally $120$. This is the threshold for action to be
332 taken, and one such action (for example, scrolling one increment)
333 should occur for each delta.
334
335
336 \membersection{wxMouseEvent::GetX}\label{wxmouseeventgetx}
337
338 \constfunc{long}{GetX}{\void}
339
340 Returns X coordinate of the physical mouse event position.
341
342
343 \membersection{wxMouseEvent::GetY}\label{wxmouseeventgety}
344
345 \func{long}{GetY}{\void}
346
347 Returns Y coordinate of the physical mouse event position.
348
349
350 \membersection{wxMouseEvent::IsButton}\label{wxmouseeventisbutton}
351
352 \constfunc{bool}{IsButton}{\void}
353
354 Returns true if the event was a mouse button event (not necessarily a button down event -
355 that may be tested using {\it ButtonDown}).
356
357
358 \membersection{wxMouseEvent::IsPageScroll}\label{wxmouseeventispagescroll}
359
360 \constfunc{bool}{IsPageScroll}{\void}
361
362 Returns true if the system has been setup to do page scrolling with
363 the mouse wheel instead of line scrolling.
364
365
366 \membersection{wxMouseEvent::Leaving}\label{wxmouseeventleaving}
367
368 \constfunc{bool}{Leaving}{\void}
369
370 Returns true if the mouse was leaving the window.
371
372 See also \helpref{wxMouseEvent::Entering}{wxmouseevententering}.
373
374
375 \membersection{wxMouseEvent::LeftDClick}\label{wxmouseeventleftdclick}
376
377 \constfunc{bool}{LeftDClick}{\void}
378
379 Returns true if the event was a left double click.
380
381
382 \membersection{wxMouseEvent::LeftDown}\label{wxmouseeventleftdown}
383
384 \constfunc{bool}{LeftDown}{\void}
385
386 Returns true if the left mouse button changed to down.
387
388
389 \membersection{wxMouseEvent::LeftIsDown}\label{wxmouseeventleftisdown}
390
391 \constfunc{bool}{LeftIsDown}{\void}
392
393 Returns true if the left mouse button is currently down, independent
394 of the current event type.
395
396 Please notice that it is {\bf not} the same as
397 \helpref{LeftDown}{wxmouseeventleftdown} which returns true if the left mouse
398 button was just pressed. Rather, it describes the state of the mouse button
399 before the event happened.
400
401 This event is usually used in the mouse event handlers which process "move
402 mouse" messages to determine whether the user is (still) dragging the mouse.
403
404
405 \membersection{wxMouseEvent::LeftUp}\label{wxmouseeventleftup}
406
407 \constfunc{bool}{LeftUp}{\void}
408
409 Returns true if the left mouse button changed to up.
410
411
412 \membersection{wxMouseEvent::MetaDown}\label{wxmouseeventmetadown}
413
414 \constfunc{bool}{MetaDown}{\void}
415
416 Returns true if the Meta key was down at the time of the event.
417
418
419 \membersection{wxMouseEvent::MiddleDClick}\label{wxmouseeventmiddledclick}
420
421 \constfunc{bool}{MiddleDClick}{\void}
422
423 Returns true if the event was a middle double click.
424
425
426 \membersection{wxMouseEvent::MiddleDown}\label{wxmouseeventmiddledown}
427
428 \constfunc{bool}{MiddleDown}{\void}
429
430 Returns true if the middle mouse button changed to down.
431
432
433 \membersection{wxMouseEvent::MiddleIsDown}\label{wxmouseeventmiddleisdown}
434
435 \constfunc{bool}{MiddleIsDown}{\void}
436
437 Returns true if the middle mouse button is currently down, independent
438 of the current event type.
439
440
441 \membersection{wxMouseEvent::MiddleUp}\label{wxmouseeventmiddleup}
442
443 \constfunc{bool}{MiddleUp}{\void}
444
445 Returns true if the middle mouse button changed to up.
446
447
448 \membersection{wxMouseEvent::Moving}\label{wxmouseeventmoving}
449
450 \constfunc{bool}{Moving}{\void}
451
452 Returns true if this was a motion event and no mouse buttons were pressed.
453 If any mouse button is held pressed, then this method returns \false and
454 \helpref{Dragging}{wxmouseeventdragging} returns \true.
455
456
457 \membersection{wxMouseEvent::RightDClick}\label{wxmouseeventrightdclick}
458
459 \constfunc{bool}{RightDClick}{\void}
460
461 Returns true if the event was a right double click.
462
463
464 \membersection{wxMouseEvent::RightDown}\label{wxmouseeventrightdown}
465
466 \constfunc{bool}{RightDown}{\void}
467
468 Returns true if the right mouse button changed to down.
469
470
471 \membersection{wxMouseEvent::RightIsDown}\label{wxmouseeventrightisdown}
472
473 \constfunc{bool}{RightIsDown}{\void}
474
475 Returns true if the right mouse button is currently down, independent
476 of the current event type.
477
478
479 \membersection{wxMouseEvent::RightUp}\label{wxmouseeventrightup}
480
481 \constfunc{bool}{RightUp}{\void}
482
483 Returns true if the right mouse button changed to up.
484
485
486 \membersection{wxMouseEvent::ShiftDown}\label{wxmouseeventshiftdown}
487
488 \constfunc{bool}{ShiftDown}{\void}
489
490 Returns true if the shift key was down at the time of the event.
491