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