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 wxWindows 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 wxWindows 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 \membersection{wxMouseEvent::m\_altDown}
  66
  67 \member{bool}{m\_altDown}
  68
  69 true if the Alt key is pressed down.
  70
  71 \membersection{wxMouseEvent::m\_controlDown}
  72
  73 \member{bool}{m\_controlDown}
  74
  75 true if control key is pressed down.
  76
  77 \membersection{wxMouseEvent::m\_leftDown}
  78
  79 \member{bool}{m\_leftDown}
  80
  81 true if the left mouse button is currently pressed down.
  82
  83 \membersection{wxMouseEvent::m\_middleDown}
  84
  85 \member{bool}{m\_middleDown}
  86
  87 true if the middle mouse button is currently pressed down.
  88
  89 \membersection{wxMouseEvent::m\_rightDown}
  90
  91 \member{bool}{m\_rightDown}
  92
  93 true if the right mouse button is currently pressed down.
  94
  95 \membersection{wxMouseEvent::m\_metaDown}
  96
  97 \member{bool}{m\_metaDown}
  98
  99 true if the Meta key is pressed down.
 100
 101 \membersection{wxMouseEvent::m\_shiftDown}
 102
 103 \member{bool}{m\_shiftDown}
 104
 105 true if shift is pressed down.
 106
 107 \membersection{wxMouseEvent::m\_x}
 108
 109 \member{long}{m\_x}
 110
 111 X-coordinate of the event.
 112
 113 \membersection{wxMouseEvent::m\_y}
 114
 115 \member{long}{m\_y}
 116
 117 Y-coordinate of the event.
 118
 119 \membersection{wxMouseEvent::m\_wheelRotation}
 120
 121 \member{int}{m\_wheelRotation}
 122
 123 The distance the mouse wheel is rotated.
 124
 125 \membersection{wxMouseEvent::m\_wheelDelta}
 126
 127 \member{int}{m\_wheelDelta}
 128
 129 The wheel delta, normally $120$.
 130
 131 \membersection{wxMouseEvent::m\_linesPerAction}
 132
 133 \member{int}{m\_linesPerAction}
 134
 135 The configured number of lines (or whatever) to be scrolled per wheel
 136 action.
 137
 138
 139 \membersection{wxMouseEvent::wxMouseEvent}
 140
 141 \func{}{wxMouseEvent}{\param{WXTYPE}{ mouseEventType = 0}, \param{int}{ id = 0}}
 142
 143 Constructor. Valid event types are:
 144
 145 \begin{itemize}
 146 \itemsep=0pt
 147 \item {\bf wxEVT\_ENTER\_WINDOW}
 148 \item {\bf wxEVT\_LEAVE\_WINDOW}
 149 \item {\bf wxEVT\_LEFT\_DOWN}
 150 \item {\bf wxEVT\_LEFT\_UP}
 151 \item {\bf wxEVT\_LEFT\_DCLICK}
 152 \item {\bf wxEVT\_MIDDLE\_DOWN}
 153 \item {\bf wxEVT\_MIDDLE\_UP}
 154 \item {\bf wxEVT\_MIDDLE\_DCLICK}
 155 \item {\bf wxEVT\_RIGHT\_DOWN}
 156 \item {\bf wxEVT\_RIGHT\_UP}
 157 \item {\bf wxEVT\_RIGHT\_DCLICK}
 158 \item {\bf wxEVT\_MOTION}
 159 \item {\bf wxEVT\_MOUSEWHEEL}
 160 \end{itemize}
 161
 162 \membersection{wxMouseEvent::AltDown}
 163
 164 \func{bool}{AltDown}{\void}
 165
 166 Returns true if the Alt key was down at the time of the event.
 167
 168 \membersection{wxMouseEvent::Button}\label{wxmouseeventbutton}
 169
 170 \func{bool}{Button}{\param{int}{ button}}
 171
 172 Returns true if the identified mouse button is changing state. Valid
 173 values of {\it button} are:
 174
 175 \begin{twocollist}\itemsep=0pt
 176 \twocolitem{{\tt wxMOUSE\_BTN\_LEFT}{check if left button was pressed}}
 177 \twocolitem{{\tt wxMOUSE\_BTN\_MIDDLE}{check if left button was pressed}}
 178 \twocolitem{{\tt wxMOUSE\_BTN\_RIGHT}{check if left button was pressed}}
 179 \twocolitem{{\tt wxMOUSE\_BTN\_ANY}{check if any button was pressed}}
 180 \end{twocollist}
 181
 182 \membersection{wxMouseEvent::ButtonDClick}
 183
 184 \func{bool}{ButtonDClick}{\param{int}{ but = wxMOUSE\_BTN\_ANY}}
 185
 186 If the argument is omitted, this returns true if the event was a mouse
 187 double click event. Otherwise the argument specifies which double click event
 188 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
 189 values).
 190
 191 \membersection{wxMouseEvent::ButtonDown}
 192
 193 \func{bool}{ButtonDown}{\param{int}{ but = -1}}
 194
 195 If the argument is omitted, this returns true if the event was a mouse
 196 button down event. Otherwise the argument specifies which button-down event
 197 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
 198 values).
 199
 200
 201 \membersection{wxMouseEvent::ButtonUp}
 202
 203 \func{bool}{ButtonUp}{\param{int}{ but = -1}}
 204
 205 If the argument is omitted, this returns true if the event was a mouse
 206 button up event. Otherwise the argument specifies which button-up event
 207 was generated (see \helpref{Button}{wxmouseeventbutton} for the possible
 208 values).
 209
 210
 211 \membersection{wxMouseEvent::ControlDown}
 212
 213 \func{bool}{ControlDown}{\void}
 214
 215 Returns true if the control key was down at the time of the event.
 216
 217 \membersection{wxMouseEvent::Dragging}\label{wxmouseeventdragging}
 218
 219 \func{bool}{Dragging}{\void}
 220
 221 Returns true if this was a dragging event (motion while a button is depressed).
 222
 223 \wxheading{See also}
 224
 225 \helpref{Moving}{wxmouseeventmoving}
 226
 227 \membersection{wxMouseEvent::Entering}\label{wxmouseevententering}
 228
 229 \func{bool}{Entering}{\void}
 230
 231 Returns true if the mouse was entering the window.
 232
 233 See also \helpref{wxMouseEvent::Leaving}{wxmouseeventleaving}.
 234
 235 \membersection{wxMouseEvent::GetButton}\label{wxmouseeventgetbutton}
 236
 237 \constfunc{int}{GetButton}{\void}
 238
 239 Returns the mouse button which generated this event or {\tt wxMOUSE\_BTN\_NONE}
 240 if no button is involved (for mouse move, enter or leave event, for example).
 241 Otherwise {\tt wxMOUSE\_BTN\_LEFT} is returned for the left button down, up and
 242 double click events, {\tt wxMOUSE\_BTN\_MIDDLE} and {\tt wxMOUSE\_BTN\_RIGHT}
 243 for the same events for the middle and the right buttons respectively.
 244
 245 \membersection{wxMouseEvent::GetPosition}\label{wxmouseeventgetposition}
 246
 247 \constfunc{wxPoint}{GetPosition}{\void}
 248
 249 \constfunc{void}{GetPosition}{\param{wxCoord*}{ x}, \param{wxCoord*}{ y}}
 250
 251 \constfunc{void}{GetPosition}{\param{long*}{ x}, \param{long*}{ y}}
 252
 253 Sets *x and *y to the position at which the event occurred.
 254
 255 Returns the physical mouse position in pixels.
 256
 257 \membersection{wxMouseEvent::GetLogicalPosition}\label{wxmouseeventgetlogicalposition}
 258
 259 \constfunc{wxPoint}{GetLogicalPosition}{\param{const wxDC\&}{ dc}}
 260
 261 Returns the logical mouse position in pixels (i.e. translated according to the
 262 translation set for the DC, which usually indicates that the window has been scrolled).
 263
 264
 265 \membersection{wxMouseEvent::GetLinesPerAction}\label{wxmouseeventgetlinesperaction}
 266
 267 \constfunc{int}{GetLinesPerAction}{\void}
 268
 269 Returns the configured number of lines (or whatever) to be scrolled per
 270 wheel action.  Defaults to three.
 271
 272 \membersection{wxMouseEvent::GetWheelRotation}\label{wxmouseeventgetwheelrotation}
 273
 274 \constfunc{int}{GetWheelRotation}{\void}
 275
 276 Get wheel rotation, positive or negative indicates direction of
 277 rotation.  Current devices all send an event when rotation is equal to
 278 +/-WheelDelta, but this allows for finer resolution devices to be
 279 created in the future.  Because of this you shouldn't assume that one
 280 event is equal to 1 line or whatever, but you should be able to either
 281 do partial line scrolling or wait until +/-WheelDelta rotation values
 282 have been accumulated before scrolling.
 283
 284 \membersection{wxMouseEvent::GetWheelDelta}\label{wxmouseeventgetwheeldelta}
 285
 286 \constfunc{int}{GetWheelDelta}{\void}
 287
 288 Get wheel delta, normally $120$.  This is the threshold for action to be
 289 taken, and one such action (for example, scrolling one increment)
 290 should occur for each delta.
 291
 292 \membersection{wxMouseEvent::GetX}\label{wxmouseeventgetx}
 293
 294 \constfunc{long}{GetX}{\void}
 295
 296 Returns X coordinate of the physical mouse event position.
 297
 298 \membersection{wxMouseEvent::GetY}\label{wxmouseeventgety}
 299
 300 \func{long}{GetY}{\void}
 301
 302 Returns Y coordinate of the physical mouse event position.
 303
 304 \membersection{wxMouseEvent::IsButton}
 305
 306 \constfunc{bool}{IsButton}{\void}
 307
 308 Returns true if the event was a mouse button event (not necessarily a button down event -
 309 that may be tested using {\it ButtonDown}).
 310
 311 \membersection{wxMouseEvent::IsPageScroll}
 312
 313 \constfunc{bool}{IsPageScroll}{\void}
 314
 315 Returns true if the system has been setup to do page scrolling with
 316 the mouse wheel instead of line scrolling.
 317
 318 \membersection{wxMouseEvent::Leaving}\label{wxmouseeventleaving}
 319
 320 \constfunc{bool}{Leaving}{\void}
 321
 322 Returns true if the mouse was leaving the window.
 323
 324 See also \helpref{wxMouseEvent::Entering}{wxmouseevententering}.
 325
 326 \membersection{wxMouseEvent::LeftDClick}
 327
 328 \constfunc{bool}{LeftDClick}{\void}
 329
 330 Returns true if the event was a left double click.
 331
 332 \membersection{wxMouseEvent::LeftDown}\label{wxmouseeventleftdown}
 333
 334 \constfunc{bool}{LeftDown}{\void}
 335
 336 Returns true if the left mouse button changed to down.
 337
 338 \membersection{wxMouseEvent::LeftIsDown}\label{wxmouseeventleftisdown}
 339
 340 \constfunc{bool}{LeftIsDown}{\void}
 341
 342 Returns true if the left mouse button is currently down, independent
 343 of the current event type.
 344
 345 Please notice that it is {\bf not} the same as
 346 \helpref{LeftDown}{wxmouseeventleftdown} which returns true if the left mouse
 347 button was just pressed. Rather, it describes the state of the mouse button
 348 before the event happened.
 349
 350 This event is usually used in the mouse event handlers which process "move
 351 mouse" messages to determine whether the user is (still) dragging the mouse.
 352
 353 \membersection{wxMouseEvent::LeftUp}
 354
 355 \constfunc{bool}{LeftUp}{\void}
 356
 357 Returns true if the left mouse button changed to up.
 358
 359 \membersection{wxMouseEvent::MetaDown}
 360
 361 \constfunc{bool}{MetaDown}{\void}
 362
 363 Returns true if the Meta key was down at the time of the event.
 364
 365 \membersection{wxMouseEvent::MiddleDClick}
 366
 367 \constfunc{bool}{MiddleDClick}{\void}
 368
 369 Returns true if the event was a middle double click.
 370
 371 \membersection{wxMouseEvent::MiddleDown}
 372
 373 \constfunc{bool}{MiddleDown}{\void}
 374
 375 Returns true if the middle mouse button changed to down.
 376
 377 \membersection{wxMouseEvent::MiddleIsDown}\label{wxmouseeventmiddleisdown}
 378
 379 \constfunc{bool}{MiddleIsDown}{\void}
 380
 381 Returns true if the middle mouse button is currently down, independent
 382 of the current event type.
 383
 384 \membersection{wxMouseEvent::MiddleUp}
 385
 386 \constfunc{bool}{MiddleUp}{\void}
 387
 388 Returns true if the middle mouse button changed to up.
 389
 390 \membersection{wxMouseEvent::Moving}\label{wxmouseeventmoving}
 391
 392 \constfunc{bool}{Moving}{\void}
 393
 394 Returns true if this was a motion event (whether some buttons are currently
 395 pressed or not, use \helpref{Dragging}{wxmouseeventdragging} if you need to
 396 distinguish between these situations).
 397
 398 \membersection{wxMouseEvent::RightDClick}
 399
 400 \constfunc{bool}{RightDClick}{\void}
 401
 402 Returns true if the event was a right double click.
 403
 404 \membersection{wxMouseEvent::RightDown}
 405
 406 \constfunc{bool}{RightDown}{\void}
 407
 408 Returns true if the right mouse button changed to down.
 409
 410 \membersection{wxMouseEvent::RightIsDown}\label{wxmouseeventrightisdown}
 411
 412 \constfunc{bool}{RightIsDown}{\void}
 413
 414 Returns true if the right mouse button is currently down, independent
 415 of the current event type.
 416
 417 \membersection{wxMouseEvent::RightUp}
 418
 419 \constfunc{bool}{RightUp}{\void}
 420
 421 Returns true if the right mouse button changed to up.
 422
 423 \membersection{wxMouseEvent::ShiftDown}
 424
 425 \constfunc{bool}{ShiftDown}{\void}
 426
 427 Returns true if the shift key was down at the time of the event.
 428