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 $1$ for the left mouse button, $2$
   7 for the middle one and $3$ for the right one. Note that not all mice have
   8 a middle button so a portable application should avoid relying on the events
   9 from it.
  10
  11 {\bf NB:} Note that under Windows mouse enter and leave events are not natively supported
  12 by the system but are generated by wxWindows itself. This has several
  13 drawbacks: the LEAVE\_WINDOW event might be received some time after the mouse
  14 left the window and the state variables for it may have changed during this
  15 time.
  16
  17 {\bf NB:} Note the difference between methods like
  18 \helpref{LeftDown}{wxmouseeventleftdown} and
  19 \helpref{LeftIsDown}{wxmouseeventleftisdown}: the format returns {\tt TRUE}
  20 when the event corresponds to the left mouse button click while the latter
  21 returns {\tt TRUE} if the left mouse button is currently being pressed. For
  22 example, when the user is dragging the mouse you can use
  23 \helpref{LeftIsDown}{wxmouseeventleftisdown} to test
  24 whether the left mouse button is (still) depressed. Also, by convention, if
  25 \helpref{LeftDown}{wxmouseeventleftdown} returns {\tt TRUE},
  26 \helpref{LeftIsDown}{wxmouseeventleftisdown} will also return {\tt TRUE} in
  27 wxWindows whatever the underlying GUI behaviour is (which is
  28 platform-dependent). The same applies, of course, to other mouse buttons as
  29 well.
  30
  31 \wxheading{Derived from}
  32
  33 \helpref{wxEvent}{wxevent}
  34
  35 \wxheading{Include files}
  36
  37 <wx/event.h>
  38
  39 \wxheading{Event table macros}
  40
  41 To process a mouse event, use these event handler macros to direct input to member
  42 functions that take a wxMouseEvent argument.
  43
  44 \twocolwidtha{7cm}
  45 \begin{twocollist}\itemsep=0pt
  46 \twocolitem{{\bf EVT\_LEFT\_DOWN(func)}}{Process a wxEVT\_LEFT\_DOWN event.}
  47 \twocolitem{{\bf EVT\_LEFT\_UP(func)}}{Process a wxEVT\_LEFT\_UP event.}
  48 \twocolitem{{\bf EVT\_LEFT\_DCLICK(func)}}{Process a wxEVT\_LEFT\_DCLICK event.}
  49 \twocolitem{{\bf EVT\_MIDDLE\_DOWN(func)}}{Process a wxEVT\_MIDDLE\_DOWN event.}
  50 \twocolitem{{\bf EVT\_MIDDLE\_UP(func)}}{Process a wxEVT\_MIDDLE\_UP event.}
  51 \twocolitem{{\bf EVT\_MIDDLE\_DCLICK(func)}}{Process a wxEVT\_MIDDLE\_DCLICK event.}
  52 \twocolitem{{\bf EVT\_RIGHT\_DOWN(func)}}{Process a wxEVT\_RIGHT\_DOWN event.}
  53 \twocolitem{{\bf EVT\_RIGHT\_UP(func)}}{Process a wxEVT\_RIGHT\_UP event.}
  54 \twocolitem{{\bf EVT\_RIGHT\_DCLICK(func)}}{Process a wxEVT\_RIGHT\_DCLICK event.}
  55 \twocolitem{{\bf EVT\_MOTION(func)}}{Process a wxEVT\_MOTION event.}
  56 \twocolitem{{\bf EVT\_ENTER\_WINDOW(func)}}{Process a wxEVT\_ENTER\_WINDOW event.}
  57 \twocolitem{{\bf EVT\_LEAVE\_WINDOW(func)}}{Process a wxEVT\_LEAVE\_WINDOW event.}
  58 \twocolitem{{\bf EVT\_MOUSEWHEEL(func)}}{Process a wxEVT\_MOUSEWHEEL event.}
  59 \twocolitem{{\bf EVT\_MOUSE\_EVENTS(func)}}{Process all mouse events.}
  60 \end{twocollist}%
  61
  62 \latexignore{\rtfignore{\wxheading{Members}}}
  63
  64 \membersection{wxMouseEvent::m\_altDown}
  65
  66 \member{bool}{m\_altDown}
  67
  68 TRUE if the Alt key is pressed down.
  69
  70 \membersection{wxMouseEvent::m\_controlDown}
  71
  72 \member{bool}{m\_controlDown}
  73
  74 TRUE if control key is pressed down.
  75
  76 \membersection{wxMouseEvent::m\_leftDown}
  77
  78 \member{bool}{m\_leftDown}
  79
  80 TRUE if the left mouse button is currently pressed down.
  81
  82 \membersection{wxMouseEvent::m\_middleDown}
  83
  84 \member{bool}{m\_middleDown}
  85
  86 TRUE if the middle mouse button is currently pressed down.
  87
  88 \membersection{wxMouseEvent::m\_rightDown}
  89
  90 \member{bool}{m\_rightDown}
  91
  92 TRUE if the right mouse button is currently pressed down.
  93
  94 \membersection{wxMouseEvent::m\_metaDown}
  95
  96 \member{bool}{m\_metaDown}
  97
  98 TRUE if the Meta key is pressed down.
  99
 100 \membersection{wxMouseEvent::m\_shiftDown}
 101
 102 \member{bool}{m\_shiftDown}
 103
 104 TRUE if shift is pressed down.
 105
 106 \membersection{wxMouseEvent::m\_x}
 107
 108 \member{long}{m\_x}
 109
 110 X-coordinate of the event.
 111
 112 \membersection{wxMouseEvent::m\_y}
 113
 114 \member{long}{m\_y}
 115
 116 Y-coordinate of the event.
 117
 118 \membersection{wxMouseEvent::m\_wheelRotation}
 119
 120 \member{int}{m\_wheelRotation}
 121
 122 The distance the mouse wheel is rotated.
 123
 124 \membersection{wxMouseEvent::m\_wheelDelta}
 125
 126 \member{int}{m\_wheelDelta}
 127
 128 The wheel delta, normally 120.
 129
 130 \membersection{wxMouseEvent::m\_linesPerAction}
 131
 132 \member{int}{m\_linesPerAction}
 133
 134 The configured number of lines (or whatever) to be scrolled per wheel
 135 action.
 136
 137
 138 \membersection{wxMouseEvent::wxMouseEvent}
 139
 140 \func{}{wxMouseEvent}{\param{WXTYPE}{ mouseEventType = 0}, \param{int}{ id = 0}}
 141
 142 Constructor. Valid event types are:
 143
 144 \begin{itemize}
 145 \itemsep=0pt
 146 \item {\bf wxEVT\_ENTER\_WINDOW}
 147 \item {\bf wxEVT\_LEAVE\_WINDOW}
 148 \item {\bf wxEVT\_LEFT\_DOWN}
 149 \item {\bf wxEVT\_LEFT\_UP}
 150 \item {\bf wxEVT\_LEFT\_DCLICK}
 151 \item {\bf wxEVT\_MIDDLE\_DOWN}
 152 \item {\bf wxEVT\_MIDDLE\_UP}
 153 \item {\bf wxEVT\_MIDDLE\_DCLICK}
 154 \item {\bf wxEVT\_RIGHT\_DOWN}
 155 \item {\bf wxEVT\_RIGHT\_UP}
 156 \item {\bf wxEVT\_RIGHT\_DCLICK}
 157 \item {\bf wxEVT\_MOTION}
 158 \item {\bf wxEVT\_MOUSEWHEEL}
 159 \end{itemize}
 160
 161 \membersection{wxMouseEvent::AltDown}
 162
 163 \func{bool}{AltDown}{\void}
 164
 165 Returns TRUE if the Alt key was down at the time of the event.
 166
 167 \membersection{wxMouseEvent::Button}
 168
 169 \func{bool}{Button}{\param{int}{ button}}
 170
 171 Returns TRUE if the identified mouse button is changing state. Valid
 172 values of {\it button} are 1, 2 or 3 for left, middle and right
 173 buttons respectively.
 174
 175 \membersection{wxMouseEvent::ButtonDClick}\label{buttondclick}
 176
 177 \func{bool}{ButtonDClick}{\param{int}{ but = -1}}
 178
 179 If the argument is omitted, this returns TRUE if the event was a mouse
 180 double click event. Otherwise the argument specifies which double click event
 181 was generated (1, 2 or 3 for left, middle and right buttons respectively).
 182
 183 \membersection{wxMouseEvent::ButtonDown}
 184
 185 \func{bool}{ButtonDown}{\param{int}{ but = -1}}
 186
 187 If the argument is omitted, this returns TRUE if the event was a mouse
 188 button down event. Otherwise the argument specifies which button-down event
 189 was generated (1, 2 or 3 for left, middle and right buttons respectively).
 190
 191 \membersection{wxMouseEvent::ButtonUp}
 192
 193 \func{bool}{ButtonUp}{\param{int}{ but = -1}}
 194
 195 If the argument is omitted, this returns TRUE if the event was a mouse
 196 button up event. Otherwise the argument specifies which button-up event
 197 was generated (1, 2 or 3 for left, middle and right buttons respectively).
 198
 199 \membersection{wxMouseEvent::ControlDown}
 200
 201 \func{bool}{ControlDown}{\void}
 202
 203 Returns TRUE if the control key was down at the time of the event.
 204
 205 \membersection{wxMouseEvent::Dragging}
 206
 207 \func{bool}{Dragging}{\void}
 208
 209 Returns TRUE if this was a dragging event (motion while a button is depressed).
 210
 211 \membersection{wxMouseEvent::Entering}\label{wxmouseevententering}
 212
 213 \func{bool}{Entering}{\void}
 214
 215 Returns TRUE if the mouse was entering the window.
 216
 217 See also \helpref{wxMouseEvent::Leaving}{wxmouseeventleaving}.
 218
 219 \membersection{wxMouseEvent::GetButton}\label{wxmouseeventgetbutton}
 220
 221 \constfunc{int}{GetButton}{\void}
 222
 223 Returns the mouse button which generated this event or $-1$ if no button is
 224 involved (for mouse move, enter or leave event, for example). The value $1$ is
 225 returned for the left button down, up and double click events, $2$ and $3$ for
 226 the same events for the middle and the right buttons respectively.
 227
 228 \membersection{wxMouseEvent::GetPosition}\label{wxmouseeventgetposition}
 229
 230 \constfunc{wxPoint}{GetPosition}{\void}
 231
 232 \constfunc{void}{GetPosition}{\param{wxCoord*}{ x}, \param{wxCoord*}{ y}}
 233
 234 \constfunc{void}{GetPosition}{\param{long*}{ x}, \param{long*}{ y}}
 235
 236 Sets *x and *y to the position at which the event occurred.
 237
 238 Returns the physical mouse position in pixels.
 239
 240 \membersection{wxMouseEvent::GetLogicalPosition}\label{wxmouseeventgetlogicalposition}
 241
 242 \constfunc{wxPoint}{GetLogicalPosition}{\param{const wxDC\&}{ dc}}
 243
 244 Returns the logical mouse position in pixels (i.e. translated according to the
 245 translation set for the DC, which usually indicates that the window has been scrolled).
 246
 247
 248 \membersection{wxMouseEvent::GetLinesPerAction}\label{wxmouseeventgetlinesperaction}
 249
 250 \constfunc{int}{GetLinesPerAction}{\void}
 251
 252 Returns the configured number of lines (or whatever) to be scrolled per
 253 wheel action.  Defaults to three.
 254
 255 \membersection{wxMouseEvent::GetWheelRotation}\label{wxmouseeventgetwheelrotation}
 256
 257 \constfunc{int}{GetWheelRotation}{\void}
 258
 259 Get wheel rotation, positive or negative indicates direction of
 260 rotation.  Current devices all send an event when rotation is equal to
 261 +/-WheelDelta, but this allows for finer resolution devices to be
 262 created in the future.  Because of this you shouldn't assume that one
 263 event is equal to 1 line or whatever, but you should be able to either
 264 do partial line scrolling or wait until +/-WheelDelta rotation values
 265 have been accumulated before scrolling.
 266
 267 \membersection{wxMouseEvent::GetWheelDelta}\label{wxmouseeventgetwheeldelta}
 268
 269 \constfunc{int}{GetWheelDelta}{\void}
 270
 271 Get wheel delta, normally 120.  This is the threshold for action to be
 272 taken, and one such action (for example, scrolling one increment)
 273 should occur for each delta.
 274
 275 \membersection{wxMouseEvent::GetX}\label{wxmouseeventgetx}
 276
 277 \constfunc{long}{GetX}{\void}
 278
 279 Returns X coordinate of the physical mouse event position.
 280
 281 \membersection{wxMouseEvent::GetY}\label{wxmouseeventgety}
 282
 283 \func{long}{GetY}{\void}
 284
 285 Returns Y coordinate of the physical mouse event position.
 286
 287 \membersection{wxMouseEvent::IsButton}
 288
 289 \constfunc{bool}{IsButton}{\void}
 290
 291 Returns TRUE if the event was a mouse button event (not necessarily a button down event -
 292 that may be tested using {\it ButtonDown}).
 293
 294 \membersection{wxMouseEvent::IsPageScroll}
 295
 296 \constfunc{bool}{IsPageScroll}{\void}
 297
 298 Returns TRUE if the system has been setup to do page scrolling with
 299 the mouse wheel instead of line scrolling.
 300
 301 \membersection{wxMouseEvent::Leaving}\label{wxmouseeventleaving}
 302
 303 \constfunc{bool}{Leaving}{\void}
 304
 305 Returns TRUE if the mouse was leaving the window.
 306
 307 See also \helpref{wxMouseEvent::Entering}{wxmouseevententering}.
 308
 309 \membersection{wxMouseEvent::LeftDClick}
 310
 311 \constfunc{bool}{LeftDClick}{\void}
 312
 313 Returns TRUE if the event was a left double click.
 314
 315 \membersection{wxMouseEvent::LeftDown}\label{wxmouseeventleftdown}
 316
 317 \constfunc{bool}{LeftDown}{\void}
 318
 319 Returns TRUE if the left mouse button changed to down.
 320
 321 \membersection{wxMouseEvent::LeftIsDown}\label{wxmouseeventleftisdown}
 322
 323 \constfunc{bool}{LeftIsDown}{\void}
 324
 325 Returns TRUE if the left mouse button is currently down, independent
 326 of the current event type.
 327
 328 Please notice that it is {\bf not} the same as
 329 \helpref{LeftDown}{wxmouseeventleftdown} which returns TRUE if the left mouse
 330 button was just pressed. Rather, it describes the state of the mouse button
 331 before the event happened.
 332
 333 This event is usually used in the mouse event handlers which process "move
 334 mouse" messages to determine whether the user is (still) dragging the mouse.
 335
 336 \membersection{wxMouseEvent::LeftUp}
 337
 338 \constfunc{bool}{LeftUp}{\void}
 339
 340 Returns TRUE if the left mouse button changed to up.
 341
 342 \membersection{wxMouseEvent::MetaDown}
 343
 344 \constfunc{bool}{MetaDown}{\void}
 345
 346 Returns TRUE if the Meta key was down at the time of the event.
 347
 348 \membersection{wxMouseEvent::MiddleDClick}
 349
 350 \constfunc{bool}{MiddleDClick}{\void}
 351
 352 Returns TRUE if the event was a middle double click.
 353
 354 \membersection{wxMouseEvent::MiddleDown}
 355
 356 \constfunc{bool}{MiddleDown}{\void}
 357
 358 Returns TRUE if the middle mouse button changed to down.
 359
 360 \membersection{wxMouseEvent::MiddleIsDown}\label{wxmouseeventmiddleisdown}
 361
 362 \constfunc{bool}{MiddleIsDown}{\void}
 363
 364 Returns TRUE if the middle mouse button is currently down, independent
 365 of the current event type.
 366
 367 \membersection{wxMouseEvent::MiddleUp}
 368
 369 \constfunc{bool}{MiddleUp}{\void}
 370
 371 Returns TRUE if the middle mouse button changed to up.
 372
 373 \membersection{wxMouseEvent::Moving}
 374
 375 \constfunc{bool}{Moving}{\void}
 376
 377 Returns TRUE if this was a motion event (no buttons depressed).
 378
 379 \membersection{wxMouseEvent::RightDClick}
 380
 381 \constfunc{bool}{RightDClick}{\void}
 382
 383 Returns TRUE if the event was a right double click.
 384
 385 \membersection{wxMouseEvent::RightDown}
 386
 387 \constfunc{bool}{RightDown}{\void}
 388
 389 Returns TRUE if the right mouse button changed to down.
 390
 391 \membersection{wxMouseEvent::RightIsDown}\label{wxmouseeventrightisdown}
 392
 393 \constfunc{bool}{RightIsDown}{\void}
 394
 395 Returns TRUE if the right mouse button is currently down, independent
 396 of the current event type.
 397
 398 \membersection{wxMouseEvent::RightUp}
 399
 400 \constfunc{bool}{RightUp}{\void}
 401
 402 Returns TRUE if the right mouse button changed to up.
 403
 404 \membersection{wxMouseEvent::ShiftDown}
 405
 406 \constfunc{bool}{ShiftDown}{\void}
 407
 408 Returns TRUE if the shift key was down at the time of the event.
 409