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