docs/latex/wx/mouseevt.tex

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