include/SDL_mouse.h
changeset 8953 dc80dc0bd22e
parent 8815 c6d0a457f3b2
parent 8952 4bb098814ec4
child 9257 6f41196c2d6b
     1.1 --- a/include/SDL_mouse.h	Wed Jun 25 02:08:37 2014 -0700
     1.2 +++ b/include/SDL_mouse.h	Wed Jun 25 17:06:12 2014 -0400
     1.3 @@ -78,6 +78,31 @@
     1.4  extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
     1.5  
     1.6  /**
     1.7 + *  \brief Get the current state of the mouse, in relation to the desktop
     1.8 + *
     1.9 + *  This works just like SDL_GetMouseState(), but the coordinates will be
    1.10 + *  reported relative to the top-left of the desktop. This can be useful if
    1.11 + *  you need to track the mouse outside of a specific window and
    1.12 + *  SDL_CaptureMouse() doesn't fit your needs. For example, it could be
    1.13 + *  useful if you need to track the mouse while dragging a window, where
    1.14 + *  coordinates relative to a window might not be in sync at all times.
    1.15 + *
    1.16 + *  \note SDL_GetMouseState() returns the mouse position as SDL understands
    1.17 + *        it from the last pump of the event queue. This function, however,
    1.18 + *        queries the OS for the current mouse position, and as such, might
    1.19 + *        be a slightly less efficient function. Unless you know what you're
    1.20 + *        doing and have a good reason to use this function, you probably want
    1.21 + *        SDL_GetMouseState() instead.
    1.22 + *
    1.23 + *  \param x Returns the current X coord, relative to the desktop. Can be NULL.
    1.24 + *  \param y Returns the current Y coord, relative to the desktop. Can be NULL.
    1.25 + *  \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
    1.26 + *
    1.27 + *  \sa SDL_GetMouseState
    1.28 + */
    1.29 +extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
    1.30 +
    1.31 +/**
    1.32   *  \brief Retrieve the relative state of the mouse.
    1.33   *
    1.34   *  The current button state is returned as a button bitmask, which can
    1.35 @@ -127,6 +152,37 @@
    1.36  extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
    1.37  
    1.38  /**
    1.39 + *  \brief Capture the mouse, to track input outside an SDL window.
    1.40 + *
    1.41 + *  \param enabled Whether or not to enable capturing
    1.42 + *
    1.43 + *  Capturing enables your app to obtain mouse events globally, instead of
    1.44 + *  just within your window. Not all video targets support this function.
    1.45 + *  When capturing is enabled, the current window will get all mouse events,
    1.46 + *  but unlike relative mode, no change is made to the cursor and it is
    1.47 + *  not restrained to your window.
    1.48 + *
    1.49 + *  This function may also deny mouse input to other windows--both those in
    1.50 + *  your application and others on the system--so you should use this
    1.51 + *  function sparingly, and in small bursts. For example, you might want to
    1.52 + *  track the mouse while the user is dragging something, until the user
    1.53 + *  releases a mouse button. It is not recommended that you capture the mouse
    1.54 + *  for long periods of time, such as the entire time your app is running.
    1.55 + *
    1.56 + *  While captured, mouse events still report coordinates relative to the
    1.57 + *  current (foreground) window, but those coordinates may be outside the
    1.58 + *  bounds of the window (including negative values). Capturing is only
    1.59 + *  allowed for the foreground window. If the window loses focus while
    1.60 + *  capturing, the capture will be disabled automatically.
    1.61 + *
    1.62 + *  While capturing is enabled, the current window will have the
    1.63 + *  SDL_WINDOW_MOUSE_CAPTURE flag set.
    1.64 + *
    1.65 + *  \return 0 on success, or -1 if not supported.
    1.66 + */
    1.67 +extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
    1.68 +
    1.69 +/**
    1.70   *  \brief Query whether relative mouse mode is enabled.
    1.71   *
    1.72   *  \sa SDL_SetRelativeMouseMode()