Replace tri-state functions SDL_EventState(), SDL_GetJoystickEventState(), SDL_GetGamepadEventState(), SDL_ShowCursor()

`SDL_QUERY`, `SDL_IGNORE`, `SDL_ENABLE`, and `SDL_DISABLE` have been removed. SDL_EventState() has been replaced with SDL_SetEventEnabled() SDL_GetEventState() has been replaced with SDL_EventEnabled() SDL_GameControllerEventState has been replaced with SDL_SetGamepadEventsEnabled() and SDL_GamepadEventsEnabled() SDL_JoystickEventState has been replaced with SDL_SetJoystickEventsEnabled() and SDL_JoystickEventsEnabled() SDL_ShowCursor() has been split into three functions: SDL_ShowCursor(), SDL_HideCursor(), and SDL_CursorVisible() Fixes https://github.com/libsdl-org/SDL/issues/6929
2025-12-19 19:10:31 +08:00 · 2022-12-28 17:06:38 -08:00
parent 9b8208c195
commit 66351fd4ba
36 changed files with 357 additions and 319 deletions
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -516,7 +516,7 @@ typedef struct SDL_TouchFingerEvent

 /**
 *  \brief An event used to request a file open by the system (event.drop.*)
- *         This event is enabled by default, you can disable it with SDL_EventState().
+ *         This event is enabled by default, you can disable it with SDL_SetEventEnabled().
 *  \note If this event is enabled, you must free the filename in the event.
 */
 typedef struct SDL_DropEvent
@@ -577,7 +577,7 @@ typedef struct SDL_SysWMmsg SDL_SysWMmsg;

 /**
 *  \brief A video driver dependent system event (event.syswm.*)
- *         This event is disabled by default, you can enable it with SDL_EventState()
+ *         This event is disabled by default, you can enable it with SDL_SetEventEnabled()
 *
 *  \note If you want to use this event, you should include SDL_syswm.h.
 */
@@ -969,7 +969,7 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
 * closed, otherwise the window will remain open if possible.
 *
 * Note: Disabled events never make it to the event filter function; see
- * SDL_EventState().
+ * SDL_SetEventEnabled().
 *
 * Note: If you just want to inspect events without filtering, you should use
 * SDL_AddEventWatch() instead.
@@ -984,7 +984,7 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_AddEventWatch
- * \sa SDL_EventState
+ * \sa SDL_SetEventEnabled
 * \sa SDL_GetEventFilter
 * \sa SDL_PeepEvents
 * \sa SDL_PushEvent
@@ -1074,52 +1074,29 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
                                              void *userdata);

-/* @{ */
-#define SDL_QUERY   -1
-#define SDL_IGNORE   0
-#define SDL_DISABLE  0
-#define SDL_ENABLE   1
-
 /**
- * Set or query the state of processing events by type.
- *
- * `state` may be any of the following:
- *
- * - `SDL_QUERY`: returns the current processing state of the specified event
- * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
- *   from the event queue and will not be filtered
- * - `SDL_ENABLE`: the event will be processed normally
+ * Set the state of processing events by type.
 *
 * \param type the type of event; see SDL_EventType for details
- * \param state how to process the event
- * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
- *          of the event before this function makes any changes to it.
+ * \param state whether to process the event or not
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_GetEventState
+ * \sa SDL_IsEventEnabled
 */
-extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
+extern DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabled);

 /**
 * Query the state of processing events by type.
 *
- * This is equivalent to calling `SDL_EventState(type, SDL_QUERY)`.
- *
- * In SDL3, this is a proper function, but in SDL2, this was a macro.
- *
 * \param type the type of event; see SDL_EventType for details
- * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
- *          of the event before this function makes any changes to it.
+ * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise.
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_EventState
+ * \sa SDL_SetEventEnabled
 */
-extern DECLSPEC Uint8 SDLCALL SDL_GetEventState(Uint32 type);
-
-/* @} */
-
+extern DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type);

 /**
 * Allocate a set of user-defined events, and return the beginning event
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -184,7 +184,7 @@ typedef struct SDL_GamepadBinding
 extern DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mappingString);

 /**
- * Load a set of Game Controller mappings from a seekable SDL data stream.
+ * Load a set of gamepad mappings from a seekable SDL data stream.
 *
 * You can call this function several times, if needed, to load different
 * database files.
@@ -256,7 +256,7 @@ extern DECLSPEC char * SDLCALL SDL_GetGamepadMappingForIndex(int mapping_index);
 extern DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID guid);

 /**
- * Get the current mapping of a Game Controller.
+ * Get the current mapping of a gamepad.
 *
 * The returned string must be freed with SDL_free().
 *
@@ -649,24 +649,34 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsGamepadConnected(SDL_Gamepad *gamepad);
 extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad);

 /**
- * Query or change current state of Game Controller events.
+ * Set the state of gamepad event processing.
 *
 * If gamepad events are disabled, you must call SDL_UpdateGamepads()
 * yourself and check the state of the gamepad when you want gamepad
 * information.
 *
- * Any number can be passed to SDL_GetGamepadEventState(), but only -1, 0,
- * and 1 will have any effect. Other numbers will just be returned.
- *
- * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
- * \returns the same value passed to the function, with exception to -1
- *          (SDL_QUERY), which will return the current state.
+ * \param state whether to process gamepad events or not
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_GetJoystickEventState
+ * \sa SDL_GamepadEventsEnabled
 */
-extern DECLSPEC int SDLCALL SDL_GetGamepadEventState(int state);
+extern DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled);
+
+/**
+ * Query the state of gamepad event processing.
+ *
+ * If gamepad events are disabled, you must call SDL_UpdateGamepads()
+ * yourself and check the state of the gamepad when you want gamepad
+ * information.
+ *
+ * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetGamepadEventsEnabled
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);

 /**
 * Manually pump gamepad updates if not using the loop.
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -107,6 +107,9 @@ typedef enum
    SDL_JOYSTICK_POWER_MAX
 } SDL_JoystickPowerLevel;

+#define SDL_JOYSTICK_AXIS_MAX   32767
+#define SDL_JOYSTICK_AXIS_MIN   -32768
+
 /* Set max recognized G-force from accelerometer
   See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed
 */
@@ -716,6 +719,36 @@ extern DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick);
 */
 extern DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick);

+/**
+ * Set the state of joystick event processing.
+ *
+ * If joystick events are disabled, you must call SDL_UpdateJoysticks()
+ * yourself and check the state of the joystick when you want joystick
+ * information.
+ *
+ * \param state whether to process joystick events or not
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_JoystickEventsEnabled
+ */
+extern DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled);
+
+/**
+ * Query the state of joystick event processing.
+ *
+ * If joystick events are disabled, you must call SDL_UpdateJoysticks()
+ * yourself and check the state of the joystick when you want joystick
+ * information.
+ *
+ * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetJoystickEventsEnabled
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void);
+
 /**
 * Update the current state of the open joysticks.
 *
@@ -723,39 +756,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick);
 * enabled.
 *
 * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_GetJoystickEventState
 */
 extern DECLSPEC void SDLCALL SDL_UpdateJoysticks(void);

-/**
- * Enable/disable joystick event polling.
- *
- * If joystick events are disabled, you must call SDL_UpdateJoysticks()
- * yourself and manually check the state of the joystick when you want
- * joystick information.
- *
- * It is recommended that you leave joystick event handling enabled.
- *
- * **WARNING**: Calling this function may delete all events currently in SDL's
- * event queue.
- *
- * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
- * \returns 1 if enabled, 0 if disabled, or a negative error code on failure;
- *          call SDL_GetError() for more information.
- *
- *          If `state` is `SDL_QUERY` then the current state is returned,
- *          otherwise the new processing state is returned.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_GetGamepadEventState
- */
-extern DECLSPEC int SDLCALL SDL_GetJoystickEventState(int state);
-
-#define SDL_JOYSTICK_AXIS_MAX   32767
-#define SDL_JOYSTICK_AXIS_MIN   -32768
-
 /**
 * Get the current state of an axis control on a joystick.
 *
--- a/include/SDL3/SDL_mouse.h
+++ b/include/SDL3/SDL_mouse.h
@@ -318,7 +318,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
 *
 * \sa SDL_FreeCursor
 * \sa SDL_SetCursor
- * \sa SDL_ShowCursor
 */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
                                                     const Uint8 * mask,
@@ -370,7 +369,6 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
 *
 * \sa SDL_CreateCursor
 * \sa SDL_GetCursor
- * \sa SDL_ShowCursor
 */
 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);

@@ -419,26 +417,43 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);

 /**
- * Toggle whether or not the cursor is shown.
+ * Show the cursor.
 *
- * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE`
- * displays the cursor and passing `SDL_DISABLE` hides it.
- *
- * The current state of the mouse cursor can be queried by passing
- * `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
- *
- * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
- *               `SDL_QUERY` to query the current state without changing it.
- * \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the
- *          cursor is hidden, or a negative error code on failure; call
+ * \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_CreateCursor
- * \sa SDL_SetCursor
+ * \sa SDL_CursorVisible
+ * \sa SDL_HideCursor
 */
-extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
+extern DECLSPEC int SDLCALL SDL_ShowCursor(void);
+
+/**
+ * Hide the cursor.
+ *
+ * \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_CursorVisible
+ * \sa SDL_ShowCursor
+ */
+extern DECLSPEC int SDLCALL SDL_HideCursor(void);
+
+/**
+ * Return whether the cursor is currently being shown.
+ *
+ * \returns `SDL_TRUE` if the cursor is being shown, or `SDL_FALSE` if the
+ *          cursor is hidden.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_HideCursor
+ * \sa SDL_ShowCursor
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void);

 /**
 * Used as a mask when testing buttons in buttonstate.
--- a/include/SDL3/SDL_oldnames.h
+++ b/include/SDL3/SDL_oldnames.h
@@ -125,7 +125,6 @@
 #define SDL_GameControllerButton SDL_GamepadButton
 #define SDL_GameControllerButtonBind SDL_GamepadBinding
 #define SDL_GameControllerClose SDL_CloseGamepad
-#define SDL_GameControllerEventState SDL_GetGamepadEventState
 #define SDL_GameControllerFromInstanceID SDL_GetGamepadFromInstanceID
 #define SDL_GameControllerFromPlayerIndex SDL_GetGamepadFromPlayerIndex
 #define SDL_GameControllerGetAppleSFSymbolsNameForAxis SDL_GetGamepadAppleSFSymbolsNameForAxis
@@ -184,7 +183,6 @@
 #define SDL_JoystickClose SDL_CloseJoystick
 #define SDL_JoystickCurrentPowerLevel SDL_GetJoystickPowerLevel
 #define SDL_JoystickDetachVirtual SDL_DetachVirtualJoystick
-#define SDL_JoystickEventState SDL_GetJoystickEventState
 #define SDL_JoystickFromInstanceID SDL_GetJoystickFromInstanceID
 #define SDL_JoystickFromPlayerIndex SDL_GetJoystickFromPlayerIndex
 #define SDL_JoystickGetAttached SDL_IsJoystickConnected
@@ -437,7 +435,6 @@
 #define SDL_GameControllerButton SDL_GameControllerButton_renamed_SDL_GamepadButton
 #define SDL_GameControllerButtonBind SDL_GameControllerButtonBind_renamed_SDL_GamepadBinding
 #define SDL_GameControllerClose SDL_GameControllerClose_renamed_SDL_CloseGamepad
-#define SDL_GameControllerEventState SDL_GameControllerEventState_renamed_SDL_GetGamepadEventState
 #define SDL_GameControllerFromInstanceID SDL_GameControllerFromInstanceID_renamed_SDL_GetGamepadFromInstanceID
 #define SDL_GameControllerFromPlayerIndex SDL_GameControllerFromPlayerIndex_renamed_SDL_GetGamepadFromPlayerIndex
 #define SDL_GameControllerGetAppleSFSymbolsNameForAxis SDL_GameControllerGetAppleSFSymbolsNameForAxis_renamed_SDL_GetGamepadAppleSFSymbolsNameForAxis
@@ -500,7 +497,6 @@
 #define SDL_JoystickClose SDL_JoystickClose_renamed_SDL_CloseJoystick
 #define SDL_JoystickCurrentPowerLevel SDL_JoystickCurrentPowerLevel_renamed_SDL_GetJoystickPowerLevel
 #define SDL_JoystickDetachVirtual SDL_JoystickDetachVirtual_renamed_SDL_DetachVirtualJoystick
-#define SDL_JoystickEventState SDL_JoystickEventState_renamed_SDL_GetJoystickEventState
 #define SDL_JoystickFromInstanceID SDL_JoystickFromInstanceID_renamed_SDL_GetJoystickFromInstanceID
 #define SDL_JoystickFromPlayerIndex SDL_JoystickFromPlayerIndex_renamed_SDL_GetJoystickFromPlayerIndex
 #define SDL_JoystickGetAttached SDL_JoystickGetAttached_renamed_SDL_IsJoystickConnected
--- a/include/SDL3/SDL_syswm.h
+++ b/include/SDL3/SDL_syswm.h
@@ -39,7 +39,7 @@
 *  Your application has access to a special type of event ::SDL_SYSWMEVENT,
 *  which contains window-manager specific information and arrives whenever
 *  an unhandled window event occurs.  This event is ignored by default, but
- *  you can enable it with SDL_EventState().
+ *  you can enable it with SDL_SetEventEnabled().
 *
 *  As of SDL 3.0, this file no longer includes the platform specific headers
 *  and types. You should include the headers you need and define one or more