SDL_SetTextInputRect() has been renamed to SDL_SetTextInputArea()

The new function includes the cursor position so IME UI elements can be placed relative to the cursor, as well as having the whole text area available so on-screen keyboards can avoid it.

docs/README-migration.md

@@ -917,6 +917,7 @@ The following functions have been renamed:
 
 The following functions have been removed:
 * SDL_IsTextInputShown()
+* SDL_SetTextInputRect() - replaced with SDL_SetTextInputArea()
 
 The following structures have been removed:
 * SDL_Keysym

include/SDL3/SDL_keyboard.h

@@ -369,7 +369,7 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_SetTextInputRect
+ * \sa SDL_SetTextInputArea
  * \sa SDL_StopTextInput
  * \sa SDL_TextInputActive
  */
@@ -418,32 +418,39 @@ extern SDL_DECLSPEC int SDLCALL SDL_StopTextInput(SDL_Window *window);
 extern SDL_DECLSPEC int SDLCALL SDL_ClearComposition(SDL_Window *window);
 
 /**
- * Set the rectangle used to type Unicode text inputs.
+ * Set the area used to type Unicode text input.
  *
- * This is often set to the extents of a text field within the window.
+ * Native input methods may place a window with word suggestions near the cursor, without covering the text being entered.
  *
- * Native input methods will place a window with word suggestions near it,
- * without covering the text being inputted.
+ * \param window the window for which to set the text input area.
+ * \param rect the SDL_Rect representing the text input area, in window coordinates, or NULL to clear it.
+ * \param cursor the offset of the current cursor location relative to `rect->x`, in window coordinates.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- * To start text input in a given location, this function is intended to be
- * called before SDL_StartTextInput, although some platforms support moving
- * the rectangle even while text input (and a composition) is active.
+ * \since This function is available since SDL 3.0.0.
  *
- * Note: If you want to use the system native IME window, try setting hint
- * **SDL_HINT_IME_SHOW_UI** to **1**, otherwise this function won't give you
- * any feedback.
+ * \sa SDL_GetTextInputArea
+ * \sa SDL_StartTextInput
+ */
+extern SDL_DECLSPEC int SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor);
+
+/**
+ * Get the area used to type Unicode text input.
  *
- * \param window the window for which to set the text input rectangle.
- * \param rect the SDL_Rect structure representing the rectangle to receive
- *             text (ignored if NULL).
+ * This returns the values previously set by SDL_SetTextInputArea().
+ *
+ * \param window the window for which to query the text input area.
+ * \param rect a pointer to an SDL_Rect filled in with the text input area, may be NULL.
+ * \param cursor a pointer to the offset of the current cursor location relative to `rect->x`, may be NULL.
  * \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_StartTextInput
+ * \sa SDL_SetTextInputArea
  */
-extern SDL_DECLSPEC int SDLCALL SDL_SetTextInputRect(SDL_Window *window, const SDL_Rect *rect);
+extern SDL_DECLSPEC int SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor);
 
 /**
  * Check whether the platform has screen keyboard support.

src/core/linux/SDL_fcitx.c

@@ -211,7 +211,7 @@ static DBusHandlerResult DBus_MessageFilter(DBusConnection *conn, DBusMessage *m
             SDL_SendEditingText("", 0, 0);
         }
 
-        SDL_Fcitx_UpdateTextRect(SDL_GetKeyboardFocus());
+        SDL_Fcitx_UpdateTextInputArea(SDL_GetKeyboardFocus());
         return DBUS_HANDLER_RESULT_HANDLED;
     }
 
@@ -390,15 +390,15 @@ SDL_bool SDL_Fcitx_ProcessKeyEvent(Uint32 keysym, Uint32 keycode, Uint8 state)
                             DBUS_TYPE_UINT32, &keysym, DBUS_TYPE_UINT32, &keycode, DBUS_TYPE_UINT32, &mod_state, DBUS_TYPE_BOOLEAN, &is_release, DBUS_TYPE_UINT32, &event_time, DBUS_TYPE_INVALID,
                             DBUS_TYPE_BOOLEAN, &handled, DBUS_TYPE_INVALID)) {
         if (handled) {
-            SDL_Fcitx_UpdateTextRect(SDL_GetKeyboardFocus());
+            SDL_Fcitx_UpdateTextInputArea(SDL_GetKeyboardFocus());
             return SDL_TRUE;
         }
     }
 
     return SDL_FALSE;
 }
 
-void SDL_Fcitx_UpdateTextRect(SDL_Window *window)
+void SDL_Fcitx_UpdateTextInputArea(SDL_Window *window)
 {
     int x = 0, y = 0;
     SDL_Rect *cursor = &fcitx_client.cursor_rect;
@@ -407,7 +407,11 @@ void SDL_Fcitx_UpdateTextRect(SDL_Window *window)
         return;
     }
 
-    SDL_copyp(cursor, &window->text_input_rect);
+    // We'll use a square at the text input cursor location for the cursor_rect
+    cursor->x = window->text_input_rect.x + window->text_input_cursor;
+    cursor->y = window->text_input_rect.x;
+    cursor->w = window->text_input_rect.h;
+    cursor->h = window->text_input_rect.h;
 
     SDL_GetWindowPosition(window, &x, &y);
 

src/core/linux/SDL_fcitx.h

@@ -29,7 +29,7 @@ extern void SDL_Fcitx_Quit(void);
 extern void SDL_Fcitx_SetFocus(SDL_bool focused);
 extern void SDL_Fcitx_Reset(void);
 extern SDL_bool SDL_Fcitx_ProcessKeyEvent(Uint32 keysym, Uint32 keycode, Uint8 state);
-extern void SDL_Fcitx_UpdateTextRect(SDL_Window *window);
+extern void SDL_Fcitx_UpdateTextInputArea(SDL_Window *window);
 extern void SDL_Fcitx_PumpEvents(void);
 
 #endif /* SDL_fcitx_h_ */

src/core/linux/SDL_ibus.c

@@ -261,7 +261,7 @@ static DBusHandlerResult IBus_MessageHandler(DBusConnection *conn, DBusMessage *
             }
         }
 
-        SDL_IBus_UpdateTextRect(SDL_GetKeyboardFocus());
+        SDL_IBus_UpdateTextInputArea(SDL_GetKeyboardFocus());
 
         return DBUS_HANDLER_RESULT_HANDLED;
     }
@@ -483,7 +483,7 @@ static SDL_bool IBus_SetupConnection(SDL_DBusContext *dbus, const char *addr)
     SDL_Window *window = SDL_GetKeyboardFocus();
     if (SDL_TextInputActive(window)) {
         SDL_IBus_SetFocus(SDL_TRUE);
-        SDL_IBus_UpdateTextRect(window);
+        SDL_IBus_UpdateTextInputArea(window);
     } else {
         SDL_IBus_SetFocus(SDL_FALSE);
     }
@@ -674,12 +674,12 @@ SDL_bool SDL_IBus_ProcessKeyEvent(Uint32 keysym, Uint32 keycode, Uint8 state)
         }
     }
 
-    SDL_IBus_UpdateTextRect(SDL_GetKeyboardFocus());
+    SDL_IBus_UpdateTextInputArea(SDL_GetKeyboardFocus());
 
     return (result != 0);
 }
 
-void SDL_IBus_UpdateTextRect(SDL_Window *window)
+void SDL_IBus_UpdateTextInputArea(SDL_Window *window)
 {
     int x = 0, y = 0;
     SDL_DBusContext *dbus;
@@ -688,7 +688,11 @@ void SDL_IBus_UpdateTextRect(SDL_Window *window)
         return;
     }
 
-    SDL_copyp(&ibus_cursor_rect, &window->text_input_rect);
+    // We'll use a square at the text input cursor location for the ibus_cursor
+    ibus_cursor_rect.x = window->text_input_rect.x + window->text_input_cursor;
+    ibus_cursor_rect.y = window->text_input_rect.x;
+    ibus_cursor_rect.w = window->text_input_rect.h;
+    ibus_cursor_rect.h = window->text_input_rect.h;
 
     SDL_GetWindowPosition(window, &x, &y);
 

src/core/linux/SDL_ibus.h

@@ -44,7 +44,7 @@ extern SDL_bool SDL_IBus_ProcessKeyEvent(Uint32 keysym, Uint32 keycode, Uint8 st
 
 /* Update the position of IBus' candidate list. If rect is NULL then this will
    just reposition it relative to the focused window's new position. */
-extern void SDL_IBus_UpdateTextRect(SDL_Window *window);
+extern void SDL_IBus_UpdateTextInputArea(SDL_Window *window);
 
 /* Checks DBus for new IBus events, and calls SDL_SendKeyboardText /
    SDL_SendEditingText for each event it finds */

src/core/linux/SDL_ime.c

@@ -29,15 +29,15 @@ typedef void (*SDL_IME_Quit_t)(void);
 typedef void (*SDL_IME_SetFocus_t)(SDL_bool);
 typedef void (*SDL_IME_Reset_t)(void);
 typedef SDL_bool (*SDL_IME_ProcessKeyEvent_t)(Uint32, Uint32, Uint8 state);
-typedef void (*SDL_IME_UpdateTextRect_t)(SDL_Window *window);
+typedef void (*SDL_IME_UpdateTextInputArea_t)(SDL_Window *window);
 typedef void (*SDL_IME_PumpEvents_t)(void);
 
 static SDL_IME_Init_t SDL_IME_Init_Real = NULL;
 static SDL_IME_Quit_t SDL_IME_Quit_Real = NULL;
 static SDL_IME_SetFocus_t SDL_IME_SetFocus_Real = NULL;
 static SDL_IME_Reset_t SDL_IME_Reset_Real = NULL;
 static SDL_IME_ProcessKeyEvent_t SDL_IME_ProcessKeyEvent_Real = NULL;
-static SDL_IME_UpdateTextRect_t SDL_IME_UpdateTextRect_Real = NULL;
+static SDL_IME_UpdateTextInputArea_t SDL_IME_UpdateTextInputArea_Real = NULL;
 static SDL_IME_PumpEvents_t SDL_IME_PumpEvents_Real = NULL;
 
 static void InitIME(void)
@@ -64,7 +64,7 @@ static void InitIME(void)
         SDL_IME_SetFocus_Real = SDL_Fcitx_SetFocus;
         SDL_IME_Reset_Real = SDL_Fcitx_Reset;
         SDL_IME_ProcessKeyEvent_Real = SDL_Fcitx_ProcessKeyEvent;
-        SDL_IME_UpdateTextRect_Real = SDL_Fcitx_UpdateTextRect;
+        SDL_IME_UpdateTextInputArea_Real = SDL_Fcitx_UpdateTextInputArea;
         SDL_IME_PumpEvents_Real = SDL_Fcitx_PumpEvents;
     }
 #endif /* HAVE_FCITX */
@@ -77,7 +77,7 @@ static void InitIME(void)
         SDL_IME_SetFocus_Real = SDL_IBus_SetFocus;
         SDL_IME_Reset_Real = SDL_IBus_Reset;
         SDL_IME_ProcessKeyEvent_Real = SDL_IBus_ProcessKeyEvent;
-        SDL_IME_UpdateTextRect_Real = SDL_IBus_UpdateTextRect;
+        SDL_IME_UpdateTextInputArea_Real = SDL_IBus_UpdateTextInputArea;
         SDL_IME_PumpEvents_Real = SDL_IBus_PumpEvents;
     }
 #endif /* HAVE_IBUS_IBUS_H */
@@ -98,7 +98,7 @@ SDL_bool SDL_IME_Init(void)
         SDL_IME_SetFocus_Real = NULL;
         SDL_IME_Reset_Real = NULL;
         SDL_IME_ProcessKeyEvent_Real = NULL;
-        SDL_IME_UpdateTextRect_Real = NULL;
+        SDL_IME_UpdateTextInputArea_Real = NULL;
         SDL_IME_PumpEvents_Real = NULL;
     }
 
@@ -135,10 +135,10 @@ SDL_bool SDL_IME_ProcessKeyEvent(Uint32 keysym, Uint32 keycode, Uint8 state)
     return SDL_FALSE;
 }
 
-void SDL_IME_UpdateTextRect(SDL_Window *window)
+void SDL_IME_UpdateTextInputArea(SDL_Window *window)
 {
-    if (SDL_IME_UpdateTextRect_Real) {
-        SDL_IME_UpdateTextRect_Real(window);
+    if (SDL_IME_UpdateTextInputArea_Real) {
+        SDL_IME_UpdateTextInputArea_Real(window);
     }
 }
 

src/core/linux/SDL_ime.h

@@ -29,7 +29,7 @@ extern void SDL_IME_Quit(void);
 extern void SDL_IME_SetFocus(SDL_bool focused);
 extern void SDL_IME_Reset(void);
 extern SDL_bool SDL_IME_ProcessKeyEvent(Uint32 keysym, Uint32 keycode, Uint8 state);
-extern void SDL_IME_UpdateTextRect(SDL_Window *window);
+extern void SDL_IME_UpdateTextInputArea(SDL_Window *window);
 extern void SDL_IME_PumpEvents(void);
 
 #endif /* SDL_ime_h_ */

src/dynapi/SDL_dynapi.sym

@@ -437,6 +437,7 @@ SDL3_0.0.0 {
     SDL_GetSystemRAM;
     SDL_GetSystemTheme;
     SDL_GetTLS;
+    SDL_GetTextInputArea;
     SDL_GetTextureAlphaMod;
     SDL_GetTextureAlphaModFloat;
     SDL_GetTextureBlendMode;
@@ -745,7 +746,7 @@ SDL3_0.0.0 {
     SDL_SetSurfacePalette;
     SDL_SetSurfaceRLE;
     SDL_SetTLS;
-    SDL_SetTextInputRect;
+    SDL_SetTextInputArea;
     SDL_SetTextureAlphaMod;
     SDL_SetTextureAlphaModFloat;
     SDL_SetTextureBlendMode;

src/dynapi/SDL_dynapi_overrides.h

@@ -462,6 +462,7 @@
 #define SDL_GetSystemRAM SDL_GetSystemRAM_REAL
 #define SDL_GetSystemTheme SDL_GetSystemTheme_REAL
 #define SDL_GetTLS SDL_GetTLS_REAL
+#define SDL_GetTextInputArea SDL_GetTextInputArea_REAL
 #define SDL_GetTextureAlphaMod SDL_GetTextureAlphaMod_REAL
 #define SDL_GetTextureAlphaModFloat SDL_GetTextureAlphaModFloat_REAL
 #define SDL_GetTextureBlendMode SDL_GetTextureBlendMode_REAL
@@ -770,7 +771,7 @@
 #define SDL_SetSurfacePalette SDL_SetSurfacePalette_REAL
 #define SDL_SetSurfaceRLE SDL_SetSurfaceRLE_REAL
 #define SDL_SetTLS SDL_SetTLS_REAL
-#define SDL_SetTextInputRect SDL_SetTextInputRect_REAL
+#define SDL_SetTextInputArea SDL_SetTextInputArea_REAL
 #define SDL_SetTextureAlphaMod SDL_SetTextureAlphaMod_REAL
 #define SDL_SetTextureAlphaModFloat SDL_SetTextureAlphaModFloat_REAL
 #define SDL_SetTextureBlendMode SDL_SetTextureBlendMode_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -482,6 +482,7 @@ SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetSurfaceProperties,(SDL_Surface *a),(a),r
 SDL_DYNAPI_PROC(int,SDL_GetSystemRAM,(void),(),return)
 SDL_DYNAPI_PROC(SDL_SystemTheme,SDL_GetSystemTheme,(void),(),return)
 SDL_DYNAPI_PROC(void*,SDL_GetTLS,(SDL_TLSID a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_GetTextInputArea,(SDL_Window *a, SDL_Rect *b, int *c),(a,b,c),return)
 SDL_DYNAPI_PROC(int,SDL_GetTextureAlphaMod,(SDL_Texture *a, Uint8 *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_GetTextureAlphaModFloat,(SDL_Texture *a, float *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_GetTextureBlendMode,(SDL_Texture *a, SDL_BlendMode *b),(a,b),return)
@@ -780,7 +781,7 @@ SDL_DYNAPI_PROC(int,SDL_SetSurfaceColorspace,(SDL_Surface *a, SDL_Colorspace b),
 SDL_DYNAPI_PROC(int,SDL_SetSurfacePalette,(SDL_Surface *a, SDL_Palette *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_SetSurfaceRLE,(SDL_Surface *a, int b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_SetTLS,(SDL_TLSID a, const void *b, SDL_TLSDestructorCallback c),(a,b,c),return)
-SDL_DYNAPI_PROC(int,SDL_SetTextInputRect,(SDL_Window *a, const SDL_Rect *b),(a,b),return)
+SDL_DYNAPI_PROC(int,SDL_SetTextInputArea,(SDL_Window *a, const SDL_Rect *b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(int,SDL_SetTextureAlphaMod,(SDL_Texture *a, Uint8 b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_SetTextureAlphaModFloat,(SDL_Texture *a, float b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_SetTextureBlendMode,(SDL_Texture *a, SDL_BlendMode b),(a,b),return)

src/video/SDL_sysvideo.h

@@ -103,6 +103,7 @@ struct SDL_Window
 
     SDL_bool text_input_active;
     SDL_Rect text_input_rect;
+    int text_input_cursor;
 
     SDL_Rect mouse_rect;
 
@@ -327,7 +328,7 @@ struct SDL_VideoDevice
     /* Text input */
     int (*StartTextInput)(SDL_VideoDevice *_this, SDL_Window *window);
     int (*StopTextInput)(SDL_VideoDevice *_this, SDL_Window *window);
-    int (*UpdateTextInputRect)(SDL_VideoDevice *_this, SDL_Window *window);
+    int (*UpdateTextInputArea)(SDL_VideoDevice *_this, SDL_Window *window);
     int (*ClearComposition)(SDL_VideoDevice *_this, SDL_Window *window);
 
     /* Screen keyboard */

src/video/SDL_video.c

@@ -5074,24 +5074,39 @@ int SDL_StopTextInput(SDL_Window *window)
     return 0;
 }
 
-int SDL_SetTextInputRect(SDL_Window *window, const SDL_Rect *rect)
+int SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor)
 {
     CHECK_WINDOW_MAGIC(window, -1);
 
     if (rect) {
         SDL_copyp(&window->text_input_rect, rect);
+        window->text_input_cursor = cursor;
     } else {
         SDL_zero(window->text_input_rect);
+        window->text_input_cursor = 0;
     }
 
-    if (_this && _this->UpdateTextInputRect) {
-        if (_this->UpdateTextInputRect(_this, window) < 0) {
+    if (_this && _this->UpdateTextInputArea) {
+        if (_this->UpdateTextInputArea(_this, window) < 0) {
             return -1;
         }
     }
     return 0;
 }
 
+int SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor)
+{
+    CHECK_WINDOW_MAGIC(window, -1);
+
+    if (rect) {
+        SDL_copyp(rect, &window->text_input_rect);
+    }
+    if (cursor) {
+        *cursor = window->text_input_cursor;
+    }
+    return 0;
+}
+
 int SDL_ClearComposition(SDL_Window *window)
 {
     CHECK_WINDOW_MAGIC(window, -1);

src/video/cocoa/SDL_cocoakeyboard.h

@@ -29,7 +29,7 @@ extern void Cocoa_QuitKeyboard(SDL_VideoDevice *_this);
 
 extern int Cocoa_StartTextInput(SDL_VideoDevice *_this, SDL_Window *window);
 extern int Cocoa_StopTextInput(SDL_VideoDevice *_this, SDL_Window *window);
-extern int Cocoa_UpdateTextInputRect(SDL_VideoDevice *_this, SDL_Window *window);
+extern int Cocoa_UpdateTextInputArea(SDL_VideoDevice *_this, SDL_Window *window);
 
 extern int Cocoa_SetWindowKeyboardGrab(SDL_VideoDevice *_this, SDL_Window *window, SDL_bool grabbed);
 

src/video/cocoa/SDL_cocoakeyboard.m

@@ -368,7 +368,7 @@ int Cocoa_StartTextInput(SDL_VideoDevice *_this, SDL_Window *window)
             [nswindow makeFirstResponder:data.fieldEdit];
         }
     }
-    return Cocoa_UpdateTextInputRect(_this, window);
+    return Cocoa_UpdateTextInputArea(_this, window);
 }
 
 int Cocoa_StopTextInput(SDL_VideoDevice *_this, SDL_Window *window)
@@ -384,7 +384,7 @@ int Cocoa_StopTextInput(SDL_VideoDevice *_this, SDL_Window *window)
     return 0;
 }
 
-int Cocoa_UpdateTextInputRect(SDL_VideoDevice *_this, SDL_Window *window)
+int Cocoa_UpdateTextInputArea(SDL_VideoDevice *_this, SDL_Window *window)
 {
     SDL_CocoaVideoData *data = (__bridge SDL_CocoaVideoData *)_this->driverdata;
     if (data.fieldEdit) {

src/video/cocoa/SDL_cocoavideo.m

@@ -172,7 +172,7 @@ static void Cocoa_DeleteDevice(SDL_VideoDevice *device)
 
         device->StartTextInput = Cocoa_StartTextInput;
         device->StopTextInput = Cocoa_StopTextInput;
-        device->UpdateTextInputRect = Cocoa_UpdateTextInputRect;
+        device->UpdateTextInputArea = Cocoa_UpdateTextInputArea;
 
         device->SetClipboardData = Cocoa_SetClipboardData;
         device->GetClipboardData = Cocoa_GetClipboardData;

src/video/gdk/SDL_gdktextinput.cpp

@@ -200,7 +200,7 @@ int GDK_StopTextInput(SDL_VideoDevice *_this, SDL_Window *window)
     return 0;
 }
 
-int GDK_UpdateTextInputRect(SDL_VideoDevice *_this, SDL_Window *window)
+int GDK_UpdateTextInputArea(SDL_VideoDevice *_this, SDL_Window *window)
 {
     /*
      * XGameUiShowTextEntryAsync does not allow you to set