include/SDL_mouse.h
changeset 8927 be64f5daf64b
parent 8149 681eb46b8ac4
child 8945 04248c700ada
     1.1 --- a/include/SDL_mouse.h	Sat May 24 01:27:19 2014 -0400
     1.2 +++ b/include/SDL_mouse.h	Sat May 24 01:30:37 2014 -0400
     1.3 @@ -117,6 +117,37 @@
     1.4  extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
     1.5  
     1.6  /**
     1.7 + *  \brief Capture the mouse, to track input outside an SDL window.
     1.8 + *
     1.9 + *  \param enabled Whether or not to enable capturing
    1.10 + *
    1.11 + *  Capturing enables your app to obtain mouse events globally, instead of
    1.12 + *  just within your window. Not all video targets support this function.
    1.13 + *  When capturing is enabled, the current window will get all mouse events,
    1.14 + *  but unlike relative mode, no change is made to the cursor and it is
    1.15 + *  not restrained to your window.
    1.16 + *
    1.17 + *  This function may also deny mouse input to other windows--both those in
    1.18 + *  your application and others on the system--so you should use this
    1.19 + *  function sparingly, and in small bursts. For example, you might want to
    1.20 + *  track the mouse while the user is dragging something, until the user
    1.21 + *  releases a mouse button. It is not recommended that you capture the mouse
    1.22 + *  for long periods of time, such as the entire time your app is running.
    1.23 + *
    1.24 + *  While captured, mouse events still report coordinates relative to the
    1.25 + *  current (foreground) window, but those coordinates may be outside the
    1.26 + *  bounds of the window (including negative values). Capturing is only
    1.27 + *  allowed for the foreground window. If the window loses focus while
    1.28 + *  capturing, the capture will be disabled automatically.
    1.29 + *
    1.30 + *  While capturing is enabled, the current window will have the
    1.31 + *  SDL_WINDOW_MOUSE_CAPTURE flag set.
    1.32 + *
    1.33 + *  \return 0 on success, or -1 if not supported.
    1.34 + */
    1.35 +extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
    1.36 +
    1.37 +/**
    1.38   *  \brief Query whether relative mouse mode is enabled.
    1.39   *
    1.40   *  \sa SDL_SetRelativeMouseMode()