encounter
/
SDL
mirror of https://github.com/encounter/SDL.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve documentation for input grabbing functions

This commit is contained in:
Cameron Gutman 2021-11-25 16:49:57 +03:00
parent 2fa35757a9
commit 57520cbde6
1 changed files with 18 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
include/SDL_video.h
View File

@ -1282,7 +1282,9 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window,
/** /**
* Set a window's input grab mode. * Set a window's input grab mode.
* *
* When input is grabbed the mouse is confined to the window. * When input is grabbed, the mouse is confined to the window. This function
* will also grab the keyboard if `SDL_HINT_GRAB_KEYBOARD` is set. To grab the
* keyboard without also grabbing the mouse, use SDL_SetWindowKeyboardGrab().
* *
* If the caller enables a grab while another window is currently grabbed, the * If the caller enables a grab while another window is currently grabbed, the
* other window loses its grab in favor of the caller's window. * other window loses its grab in favor of the caller's window.
@ -1301,6 +1303,18 @@ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
/** /**
* Set a window's keyboard grab mode. * Set a window's keyboard grab mode.
* *
* Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or
* the Meta/Super key. Note that not all system keyboard shortcuts can be
* captured by applications (one example is Ctrl+Alt+Del on Windows).
*
* This is primarily intended for specialized applications such as VNC clients
* or VM frontends. Normal games should not use keyboard grab.
*
* When keyboard grab is enabled, SDL will continue to handle Alt+Tab when the
* window is full-screen to ensure the user is not trapped in your application.
* If you have a custom keyboard shortcut to exit fullscreen mode, you may
* suppress this behavior with `SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED`.
*
* If the caller enables a grab while another window is currently grabbed, the * If the caller enables a grab while another window is currently grabbed, the
* other window loses its grab in favor of the caller's window. * other window loses its grab in favor of the caller's window.
* *
@ -1319,6 +1333,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window,
/** /**
* Set a window's mouse grab mode. * Set a window's mouse grab mode.
* *
* Mouse grab confines the mouse cursor to the window.
*
* \param window The window for which the mouse grab mode should be set. * \param window The window for which the mouse grab mode should be set.
* *
* \since This function is available since SDL 2.0.16. * \since This function is available since SDL 2.0.16.
@ -1395,7 +1411,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
* \since This function is available since SDL 2.0.18. * \since This function is available since SDL 2.0.18.
* *
* \sa SDL_GetWindowMouseRect * \sa SDL_GetWindowMouseRect
* \sa SDL_SetWindowGrab * \sa SDL_SetWindowMouseGrab
*/ */
extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SDL_Rect * rect); extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SDL_Rect * rect);