mirrors/SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Remove legacy SDL2 input grab API

Browse Source
This commit is contained in:
Cameron Gutman 2024-03-24 18:35:40 -05:00 committed by Sam Lantinga
parent cf3cf0e106
commit f14fb979c1
11 changed files with 21 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/README-migration.md
View File

@ -709,6 +709,7 @@ Calling SDL_GetHint() with the name of the hint being changed from within a hint
The following hints have been removed:
* SDL_HINT_ACCELEROMETER_AS_JOYSTICK
* SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS - gamepad buttons are always positional
* SDL_HINT_GRAB_KEYBOARD - use SDL_SetWindowKeyboardGrab() instead
* SDL_HINT_IDLE_TIMER_DISABLED - use SDL_DisableScreenSaver() instead
* SDL_HINT_IME_SUPPORT_EXTENDED_TEXT - the normal text editing event has extended text
* SDL_HINT_MOUSE_RELATIVE_SCALING - mouse coordinates are no longer automatically scaled by the SDL renderer
@ -1718,6 +1719,8 @@ SDL_GL_GetSwapInterval() takes the interval as an output parameter and returns 0
SDL_GL_GetDrawableSize() has been removed. SDL_GetWindowSizeInPixels() can be used in its place.
SDL_SetWindowGrab() and SDL_GetWindowGrab() have been removed. Use SDL_SetWindowMouseGrab()/SDL_GetWindowMouseGrab() or SDL_SetWindowKeyboardGrab()/SDL_GetWindowKeyboardGrab() for grabbing mouse and/or keyboard input respectively.
The SDL_WINDOW_TOOLTIP and SDL_WINDOW_POPUP_MENU window flags are now supported on Windows, Mac (Cocoa), X11, and Wayland. Creating windows with these flags must happen via the `SDL_CreatePopupWindow()` function. This function requires passing in the handle to a valid parent window for the popup, and the popup window is positioned relative to the parent.

13
include/SDL3/SDL_hints.h
View File

@ -654,19 +654,6 @@ extern "C" {
*/
#define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE"
/**
* A variable controlling whether grabbing input grabs the keyboard
*
* The variable can be set to the following values:
* "0" - Grab will affect only the mouse. (default)
* "1" - Grab will affect mouse and keyboard.
*
* By default SDL will not grab the keyboard so system shortcuts still work.
*
* This hint can be set anytime.
*/
#define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD"
/**
* A variable to control whether SDL_hid_enumerate() enumerates all HID devices or only controllers.
*

4
include/SDL3/SDL_mouse.h
View File

@ -285,8 +285,8 @@ extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
* mouse while the user is dragging something, until the user releases a mouse
* button. It is not recommended that you capture the mouse for long periods
* of time, such as the entire time your app is running. For that, you should
* probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending
* on your goals.
* probably use SDL_SetRelativeMouseMode() or SDL_SetWindowMouseGrab(),
* depending on your goals.
*
* While captured, mouse events still report coordinates relative to the
* current (foreground) window, but those coordinates may be outside the

44
include/SDL3/SDL_video.h
View File

@ -1152,7 +1152,7 @@ extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *win
* \sa SDL_MaximizeWindow
* \sa SDL_MinimizeWindow
* \sa SDL_SetWindowFullscreen
* \sa SDL_SetWindowGrab
* \sa SDL_SetWindowMouseGrab
* \sa SDL_ShowWindow
*/
extern DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *window);
@ -1776,28 +1776,6 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, con
*/
extern DECLSPEC int SDLCALL SDL_DestroyWindowSurface(SDL_Window *window);
/**
* Set a window's input grab mode.
*
* 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
* other window loses its grab in favor of the caller's window.
*
* \param window the window for which the input grab mode should be set
* \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetGrabbedWindow
* \sa SDL_GetWindowGrab
*/
extern DECLSPEC int SDLCALL SDL_SetWindowGrab(SDL_Window *window, SDL_bool grabbed);
/**
* Set a window's keyboard grab mode.
*
@ -1826,7 +1804,6 @@ extern DECLSPEC int SDLCALL SDL_SetWindowGrab(SDL_Window *window, SDL_bool grabb
*
* \sa SDL_GetWindowKeyboardGrab
* \sa SDL_SetWindowMouseGrab
* \sa SDL_SetWindowGrab
*/
extern DECLSPEC int SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bool grabbed);
@ -1844,22 +1821,9 @@ extern DECLSPEC int SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bo
*
* \sa SDL_GetWindowMouseGrab
* \sa SDL_SetWindowKeyboardGrab
* \sa SDL_SetWindowGrab
*/
extern DECLSPEC int SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, SDL_bool grabbed);
/**
* Get a window's input grab mode.
*
* \param window the window to query
* \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetWindowGrab
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window *window);
/**
* Get a window's keyboard grab mode.
*
@ -1869,7 +1833,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window *window);
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetWindowKeyboardGrab
* \sa SDL_GetWindowGrab
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window);
@ -1882,7 +1845,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window);
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetWindowKeyboardGrab
* \sa SDL_GetWindowGrab
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window);
@ -1893,8 +1855,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window);
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetWindowGrab
* \sa SDL_SetWindowGrab
* \sa SDL_SetWindowMouseGrab
* \sa SDL_SetWindowKeyboardGrab
*/
extern DECLSPEC SDL_Window *SDLCALL SDL_GetGrabbedWindow(void);

2
src/dynapi/SDL_dynapi.sym
View File

@ -462,7 +462,6 @@ SDL3_0.0.0 {
SDL_GetWindowFlags;
SDL_GetWindowFromID;
SDL_GetWindowFullscreenMode;
SDL_GetWindowGrab;
SDL_GetWindowICCProfile;
SDL_GetWindowID;
SDL_GetWindowKeyboardGrab;
@ -752,7 +751,6 @@ SDL3_0.0.0 {
SDL_SetWindowFocusable;
SDL_SetWindowFullscreen;
SDL_SetWindowFullscreenMode;
SDL_SetWindowGrab;
SDL_SetWindowHitTest;
SDL_SetWindowIcon;
SDL_SetWindowInputFocus;

2
src/dynapi/SDL_dynapi_overrides.h
View File

@ -487,7 +487,6 @@
#define SDL_GetWindowFlags SDL_GetWindowFlags_REAL
#define SDL_GetWindowFromID SDL_GetWindowFromID_REAL
#define SDL_GetWindowFullscreenMode SDL_GetWindowFullscreenMode_REAL
#define SDL_GetWindowGrab SDL_GetWindowGrab_REAL
#define SDL_GetWindowICCProfile SDL_GetWindowICCProfile_REAL
#define SDL_GetWindowID SDL_GetWindowID_REAL
#define SDL_GetWindowKeyboardGrab SDL_GetWindowKeyboardGrab_REAL
@ -776,7 +775,6 @@
#define SDL_SetWindowFocusable SDL_SetWindowFocusable_REAL
#define SDL_SetWindowFullscreen SDL_SetWindowFullscreen_REAL
#define SDL_SetWindowFullscreenMode SDL_SetWindowFullscreenMode_REAL
#define SDL_SetWindowGrab SDL_SetWindowGrab_REAL
#define SDL_SetWindowHitTest SDL_SetWindowHitTest_REAL
#define SDL_SetWindowIcon SDL_SetWindowIcon_REAL
#define SDL_SetWindowInputFocus SDL_SetWindowInputFocus_REAL

2
src/dynapi/SDL_dynapi_procs.h
View File

@ -518,7 +518,6 @@ SDL_DYNAPI_PROC(float,SDL_GetWindowDisplayScale,(SDL_Window *a),(a),return)
SDL_DYNAPI_PROC(Uint32,SDL_GetWindowFlags,(SDL_Window *a),(a),return)
SDL_DYNAPI_PROC(SDL_Window*,SDL_GetWindowFromID,(Uint32 a),(a),return)
SDL_DYNAPI_PROC(const SDL_DisplayMode*,SDL_GetWindowFullscreenMode,(SDL_Window *a),(a),return)
SDL_DYNAPI_PROC(SDL_bool,SDL_GetWindowGrab,(SDL_Window *a),(a),return)
SDL_DYNAPI_PROC(void*,SDL_GetWindowICCProfile,(SDL_Window *a, size_t *b),(a,b),return)
SDL_DYNAPI_PROC(Uint32,SDL_GetWindowID,(SDL_Window *a),(a),return)
SDL_DYNAPI_PROC(SDL_bool,SDL_GetWindowKeyboardGrab,(SDL_Window *a),(a),return)
@ -796,7 +795,6 @@ SDL_DYNAPI_PROC(int,SDL_SetWindowBordered,(SDL_Window *a, SDL_bool b),(a,b),retu
SDL_DYNAPI_PROC(int,SDL_SetWindowFocusable,(SDL_Window *a, SDL_bool b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_SetWindowFullscreen,(SDL_Window *a, SDL_bool b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_SetWindowFullscreenMode,(SDL_Window *a, const SDL_DisplayMode *b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_SetWindowGrab,(SDL_Window *a, SDL_bool b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_SetWindowHitTest,(SDL_Window *a, SDL_HitTest b, void *c),(a,b,c),return)
SDL_DYNAPI_PROC(int,SDL_SetWindowIcon,(SDL_Window *a, SDL_Surface *b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_SetWindowInputFocus,(SDL_Window *a),(a),return)

2
src/test/SDL_test_common.c
View File

@ -2300,7 +2300,7 @@ int SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event
/* Ctrl-G toggle mouse grab */
SDL_Window *window = SDL_GetWindowFromID(event->key.windowID);
if (window) {
SDL_SetWindowGrab(window, !SDL_GetWindowGrab(window));
SDL_SetWindowMouseGrab(window, !SDL_GetWindowMouseGrab(window));
}
}
break;

29
src/video/SDL_video.c
View File

@ -1911,12 +1911,7 @@ static void ApplyWindowFlags(SDL_Window *window, SDL_WindowFlags flags)
}
if (flags & SDL_WINDOW_MOUSE_GRABBED) {
/* We must specifically call SDL_SetWindowGrab() and not
SDL_SetWindowMouseGrab() here because older applications may use
this flag plus SDL_HINT_GRAB_KEYBOARD to indicate that they want
the keyboard grabbed too and SDL_SetWindowMouseGrab() won't do that.
*/
SDL_SetWindowGrab(window, SDL_TRUE);
SDL_SetWindowMouseGrab(window, SDL_TRUE);
}
if (flags & SDL_WINDOW_KEYBOARD_GRABBED) {
SDL_SetWindowKeyboardGrab(window, SDL_TRUE);
@ -3311,23 +3306,6 @@ void SDL_UpdateWindowGrab(SDL_Window *window)
}
}
int SDL_SetWindowGrab(SDL_Window *window, SDL_bool grabbed)
{
int ret_mouse_grab = 0;
int ret_keyboard_grab = 0;
CHECK_WINDOW_MAGIC(window, -1);
CHECK_WINDOW_NOT_POPUP(window, -1);
ret_mouse_grab = SDL_SetWindowMouseGrab(window, grabbed);
if (SDL_GetHintBoolean(SDL_HINT_GRAB_KEYBOARD, SDL_FALSE)) {
ret_keyboard_grab = SDL_SetWindowKeyboardGrab(window, grabbed);
}
return (!ret_mouse_grab && !ret_keyboard_grab) ? 0 : -1;
}
int SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bool grabbed)
{
CHECK_WINDOW_MAGIC(window, -1);
@ -3388,11 +3366,6 @@ int SDL_SetWindowMouseGrab(SDL_Window *window, SDL_bool grabbed)
return 0;
}
SDL_bool SDL_GetWindowGrab(SDL_Window *window)
{
return SDL_GetWindowKeyboardGrab(window) || SDL_GetWindowMouseGrab(window);
}
SDL_bool SDL_GetWindowKeyboardGrab(SDL_Window *window)
{
CHECK_WINDOW_MAGIC(window, SDL_FALSE);

2
test/testautomation_hints.c
View File

@ -9,7 +9,6 @@
static const char *HintsEnum[] = {
SDL_HINT_FRAMEBUFFER_ACCELERATION,
SDL_HINT_GAMECONTROLLERCONFIG,
SDL_HINT_GRAB_KEYBOARD,
SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS,
SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK,
SDL_HINT_MOUSE_RELATIVE_MODE_WARP,
@ -28,7 +27,6 @@ static const char *HintsEnum[] = {
static const char *HintsVerbose[] = {
"SDL_FRAMEBUFFER_ACCELERATION",
"SDL_GAMECONTROLLERCONFIG",
"SDL_GRAB_KEYBOARD",
"SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS",
"SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK",
"SDL_MOUSE_RELATIVE_MODE_WARP",

73
test/testautomation_video.c
View File

@ -491,9 +491,6 @@ static void setAndCheckWindowMouseGrabState(SDL_Window *window, SDL_bool desired
SDLTest_AssertCheck(
SDL_GetGrabbedWindow() == window,
"Grabbed window should be to our window");
SDLTest_AssertCheck(
SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_TRUE");
SDLTest_AssertCheck(
SDL_GetWindowFlags(window) & SDL_WINDOW_MOUSE_GRABBED,
"SDL_WINDOW_MOUSE_GRABBED should be set");
@ -526,9 +523,6 @@ static void setAndCheckWindowKeyboardGrabState(SDL_Window *window, SDL_bool desi
SDLTest_AssertCheck(
SDL_GetGrabbedWindow() == window,
"Grabbed window should be set to our window");
SDLTest_AssertCheck(
SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_TRUE");
SDLTest_AssertCheck(
SDL_GetWindowFlags(window) & SDL_WINDOW_KEYBOARD_GRABBED,
"SDL_WINDOW_KEYBOARD_GRABBED should be set");
@ -542,8 +536,10 @@ static void setAndCheckWindowKeyboardGrabState(SDL_Window *window, SDL_bool desi
/**
* Tests keyboard and mouse grab support
*
* \sa SDL_GetWindowGrab
* \sa SDL_SetWindowGrab
* \sa SDL_GetWindowMouseGrab
* \sa SDL_GetWindowKeyboardGrab
* \sa SDL_SetWindowMouseGrab
* \sa SDL_SetWindowKeyboardGrab
*/
static int video_getSetWindowGrab(void *arg)
{
@ -589,8 +585,6 @@ static int video_getSetWindowGrab(void *arg)
/* F */
setAndCheckWindowKeyboardGrabState(window, SDL_FALSE);
setAndCheckWindowMouseGrabState(window, SDL_FALSE);
SDLTest_AssertCheck(!SDL_GetWindowGrab(window),
"SDL_GetWindowGrab should return SDL_FALSE");
SDLTest_AssertCheck(SDL_GetGrabbedWindow() == NULL,
"Expected NULL grabbed window");
@ -603,92 +597,47 @@ static int video_getSetWindowGrab(void *arg)
/* F --> T */
setAndCheckWindowMouseGrabState(window, SDL_TRUE);
setAndCheckWindowKeyboardGrabState(window, SDL_TRUE);
SDLTest_AssertCheck(SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_TRUE");
/* T --> T */
setAndCheckWindowKeyboardGrabState(window, SDL_TRUE);
setAndCheckWindowMouseGrabState(window, SDL_TRUE);
SDLTest_AssertCheck(SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_TRUE");
/* M: T --> F */
/* K: T --> T */
setAndCheckWindowKeyboardGrabState(window, SDL_TRUE);
setAndCheckWindowMouseGrabState(window, SDL_FALSE);
SDLTest_AssertCheck(SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_TRUE");
/* M: F --> T */
/* K: T --> F */
setAndCheckWindowMouseGrabState(window, SDL_TRUE);
setAndCheckWindowKeyboardGrabState(window, SDL_FALSE);
SDLTest_AssertCheck(SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_TRUE");
/* M: T --> F */
/* K: F --> F */
setAndCheckWindowMouseGrabState(window, SDL_FALSE);
setAndCheckWindowKeyboardGrabState(window, SDL_FALSE);
SDLTest_AssertCheck(!SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_FALSE");
SDLTest_AssertCheck(SDL_GetGrabbedWindow() == NULL,
"Expected NULL grabbed window");
/* Using the older SDL_SetWindowGrab API should only grab mouse by default */
SDL_SetWindowGrab(window, SDL_TRUE);
SDLTest_AssertPass("Call to SDL_SetWindowGrab(SDL_TRUE)");
SDLTest_AssertCheck(SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_TRUE");
SDLTest_AssertCheck(SDL_GetWindowMouseGrab(window),
"SDL_GetWindowMouseGrab() should return SDL_TRUE");
SDLTest_AssertCheck(!SDL_GetWindowKeyboardGrab(window),
"SDL_GetWindowKeyboardGrab() should return SDL_FALSE");
SDL_SetWindowGrab(window, SDL_FALSE);
SDLTest_AssertCheck(!SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_FALSE");
SDLTest_AssertCheck(!SDL_GetWindowMouseGrab(window),
"SDL_GetWindowMouseGrab() should return SDL_FALSE");
SDLTest_AssertCheck(!SDL_GetWindowKeyboardGrab(window),
"SDL_GetWindowKeyboardGrab() should return SDL_FALSE");
/* Now test with SDL_HINT_GRAB_KEYBOARD set. We should get keyboard grab now. */
SDL_SetHint(SDL_HINT_GRAB_KEYBOARD, "1");
SDL_SetWindowGrab(window, SDL_TRUE);
SDLTest_AssertPass("Call to SDL_SetWindowGrab(SDL_TRUE)");
SDLTest_AssertCheck(SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_TRUE");
SDLTest_AssertCheck(SDL_GetWindowMouseGrab(window),
"SDL_GetWindowMouseGrab() should return SDL_TRUE");
SDLTest_AssertCheck(SDL_GetWindowKeyboardGrab(window),
"SDL_GetWindowKeyboardGrab() should return SDL_TRUE");
SDL_SetWindowGrab(window, SDL_FALSE);
SDLTest_AssertCheck(!SDL_GetWindowGrab(window),
"SDL_GetWindowGrab() should return SDL_FALSE");
SDLTest_AssertCheck(!SDL_GetWindowMouseGrab(window),
"SDL_GetWindowMouseGrab() should return SDL_FALSE");
SDLTest_AssertCheck(!SDL_GetWindowKeyboardGrab(window),
"SDL_GetWindowKeyboardGrab() should return SDL_FALSE");
/* Negative tests */
SDL_GetWindowGrab(NULL);
SDLTest_AssertPass("Call to SDL_GetWindowGrab(window=NULL)");
SDL_GetWindowMouseGrab(NULL);
SDLTest_AssertPass("Call to SDL_GetWindowMouseGrab(window=NULL)");
checkInvalidWindowError();
SDL_GetWindowKeyboardGrab(NULL);
SDLTest_AssertPass("Call to SDL_GetWindowKeyboardGrab(window=NULL)");
checkInvalidWindowError();
SDL_SetWindowGrab(NULL, SDL_FALSE);
SDLTest_AssertPass("Call to SDL_SetWindowGrab(window=NULL,SDL_FALSE)");
SDL_SetWindowMouseGrab(NULL, SDL_FALSE);
SDLTest_AssertPass("Call to SDL_SetWindowMouseGrab(window=NULL,SDL_FALSE)");
checkInvalidWindowError();
SDL_SetWindowKeyboardGrab(NULL, SDL_FALSE);
SDLTest_AssertPass("Call to SDL_SetWindowKeyboardGrab(window=NULL,SDL_FALSE)");
checkInvalidWindowError();
SDL_SetWindowGrab(NULL, SDL_TRUE);
SDLTest_AssertPass("Call to SDL_SetWindowGrab(window=NULL,SDL_TRUE)");
SDL_SetWindowMouseGrab(NULL, SDL_TRUE);
SDLTest_AssertPass("Call to SDL_SetWindowMouseGrab(window=NULL,SDL_TRUE)");
checkInvalidWindowError();
SDL_SetWindowKeyboardGrab(NULL, SDL_TRUE);
@ -2319,7 +2268,7 @@ static const SDLTest_TestCaseReference videoTest9 = {
};
static const SDLTest_TestCaseReference videoTest10 = {
(SDLTest_TestCaseFp)video_getSetWindowGrab, "video_getSetWindowGrab", "Checks SDL_GetWindowGrab and SDL_SetWindowGrab positive and negative cases", TEST_ENABLED
(SDLTest_TestCaseFp)video_getSetWindowGrab, "video_getSetWindowGrab", "Checks input grab positive and negative cases", TEST_ENABLED
};
static const SDLTest_TestCaseReference videoTest11 = {