Sync SDL3 header -> wiki

libsdl-org · Jun 24, 2024 · 3ee066c · 3ee066c
1 parent 37630f4
commit 3ee066c
Show file tree

Hide file tree

Showing 6 changed files with 64 additions and 19 deletions.
diff --git a/SDL3/README/migration.md b/SDL3/README/migration.md
@@ -907,6 +907,8 @@ The following symbols have been removed:
 
 Text input is no longer automatically enabled when initializing video, you should call SDL_StartTextInput() when you want to receive text input and call SDL_StopTextInput() when you are done. Starting text input may shown an input method editor (IME) and cause key up/down events to be skipped, so should only be enabled when the application wants text input.
 
+The text input state hase been changed to be window-specific. SDL_StartTextInput(), SDL_StopTextInput(), SDL_TextInputActive(), and SDL_ClearComposition() all now take a window parameter.
+
 SDL_GetDefaultKeyFromScancode(), SDL_GetKeyFromScancode(), and SDL_GetScancodeFromKey() take an SDL_Keymod parameter and use that to provide the correct result based on keyboard modifier state.
 
 The following functions have been renamed:

diff --git a/SDL3/SDL_ClearComposition.md b/SDL3/SDL_ClearComposition.md
@@ -10,9 +10,20 @@ Defined in [<SDL3/SDL_keyboard.h>](https://github.com/libsdl-org/SDL/blob/main/i
 ## Syntax
 
 ```c
-void SDL_ClearComposition(void);
+int SDL_ClearComposition(SDL_Window *window);
 ```
 
+## Function Parameters
+
+|                            |            |                       |
+| -------------------------- | ---------- | --------------------- |
+| [SDL_Window](SDL_Window) * | **window** | the window to affect. |
+
+## Return Value
+
+(int) Returns 0 on success or a negative error code on failure; call
+[SDL_GetError](SDL_GetError)() for more information.
+
 ## Version
 
 This function is available since SDL 3.0.0.

diff --git a/SDL3/SDL_SetTextInputRect.md b/SDL3/SDL_SetTextInputRect.md
@@ -10,14 +10,15 @@ Defined in [<SDL3/SDL_keyboard.h>](https://github.com/libsdl-org/SDL/blob/main/i
 ## Syntax
 
 ```c
-int SDL_SetTextInputRect(const SDL_Rect *rect);
+int SDL_SetTextInputRect(SDL_Window *window, const SDL_Rect *rect);
 ```
 
 ## Function Parameters
 
-|                              |          |                                                                                                  |
-| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
-| const [SDL_Rect](SDL_Rect) * | **rect** | the [SDL_Rect](SDL_Rect) structure representing the rectangle to receive text (ignored if NULL). |
+|                              |            |                                                                                                  |
+| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------ |
+| [SDL_Window](SDL_Window) *   | **window** | the window for which to set the text input rectangle.                                            |
+| const [SDL_Rect](SDL_Rect) * | **rect**   | the [SDL_Rect](SDL_Rect) structure representing the rectangle to receive text (ignored if NULL). |
 
 ## Return Value
 
@@ -26,6 +27,8 @@ int SDL_SetTextInputRect(const SDL_Rect *rect);
 
 ## Remarks
 
+This is often set to the extents of a text field within the window.
+
 Native input methods will place a window with word suggestions near it,
 without covering the text being inputted.
 

diff --git a/SDL3/SDL_StartTextInput.md b/SDL3/SDL_StartTextInput.md
@@ -1,7 +1,7 @@
 ###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
 # SDL_StartTextInput
 
-Start accepting Unicode text input events.
+Start accepting Unicode text input events in a window.
 
 ## Header File
 
@@ -10,21 +10,31 @@ Defined in [<SDL3/SDL_keyboard.h>](https://github.com/libsdl-org/SDL/blob/main/i
 ## Syntax
 
 ```c
-void SDL_StartTextInput(void);
+int SDL_StartTextInput(SDL_Window *window);
 ```
 
+## Function Parameters
+
+|                            |            |                                  |
+| -------------------------- | ---------- | -------------------------------- |
+| [SDL_Window](SDL_Window) * | **window** | the window to enable text input. |
+
+## Return Value
+
+(int) Returns 0 on success or a negative error code on failure; call
+[SDL_GetError](SDL_GetError)() for more information.
+
 ## Remarks
 
-This function will start accepting Unicode text input events in the focused
-SDL window, and start emitting [SDL_TextInputEvent](SDL_TextInputEvent)
-([SDL_EVENT_TEXT_INPUT](SDL_EVENT_TEXT_INPUT)) and
-[SDL_TextEditingEvent](SDL_TextEditingEvent)
-([SDL_EVENT_TEXT_EDITING](SDL_EVENT_TEXT_EDITING)) events. Please use this
-function in pair with [SDL_StopTextInput](SDL_StopTextInput)().
+This function will enable text input
+([SDL_EVENT_TEXT_INPUT](SDL_EVENT_TEXT_INPUT) and
+[SDL_EVENT_TEXT_EDITING](SDL_EVENT_TEXT_EDITING) events) in the specified
+window. Please use this function paired with
+[SDL_StopTextInput](SDL_StopTextInput)().
 
 Text input events are not received by default.
 
-On some platforms using this function activates the screen keyboard.
+On some platforms using this function shows the screen keyboard.
 
 ## Version
 
@@ -34,6 +44,7 @@ This function is available since SDL 3.0.0.
 
 - [SDL_SetTextInputRect](SDL_SetTextInputRect)
 - [SDL_StopTextInput](SDL_StopTextInput)
+- [SDL_TextInputActive](SDL_TextInputActive)
 
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryKeyboard](CategoryKeyboard)

diff --git a/SDL3/SDL_StopTextInput.md b/SDL3/SDL_StopTextInput.md
@@ -1,7 +1,7 @@
 ###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
 # SDL_StopTextInput
 
-Stop receiving any text input events.
+Stop receiving any text input events in a window.
 
 ## Header File
 
@@ -10,12 +10,24 @@ Defined in [<SDL3/SDL_keyboard.h>](https://github.com/libsdl-org/SDL/blob/main/i
 ## Syntax
 
 ```c
-void SDL_StopTextInput(void);
+int SDL_StopTextInput(SDL_Window *window);
 ```
 
+## Function Parameters
+
+|                            |            |                                   |
+| -------------------------- | ---------- | --------------------------------- |
+| [SDL_Window](SDL_Window) * | **window** | the window to disable text input. |
+
+## Return Value
+
+(int) Returns 0 on success or a negative error code on failure; call
+[SDL_GetError](SDL_GetError)() for more information.
+
 ## Remarks
 
-Text input events are not received by default.
+If [SDL_StartTextInput](SDL_StartTextInput)() showed the screen keyboard,
+this function will hide it.
 
 ## Version
 

diff --git a/SDL3/SDL_TextInputActive.md b/SDL3/SDL_TextInputActive.md
@@ -1,7 +1,7 @@
 ###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
 # SDL_TextInputActive
 
-Check whether or not Unicode text input events are enabled.
+Check whether or not Unicode text input events are enabled for a window.
 
 ## Header File
 
@@ -10,9 +10,15 @@ Defined in [<SDL3/SDL_keyboard.h>](https://github.com/libsdl-org/SDL/blob/main/i
 ## Syntax
 
 ```c
-SDL_bool SDL_TextInputActive(void);
+SDL_bool SDL_TextInputActive(SDL_Window *window);
 ```
 
+## Function Parameters
+
+|                            |            |                      |
+| -------------------------- | ---------- | -------------------- |
+| [SDL_Window](SDL_Window) * | **window** | the window to check. |
+
 ## Return Value
 
 ([SDL_bool](SDL_bool)) Returns [SDL_TRUE](SDL_TRUE) if text input events