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