Add SDL Window text input methods

HexDecimal · HexDecimal · commit ca58a26db8c8 · 2025-07-11T21:12:17.000-07:00
Text input events were missing since version 19.0.0 and had to be added again.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -45,6 +45,7 @@
         "AUDIOREWIND",
         "AUDIOSTOP",
         "autoclass",
+        "AUTOCORRECT",
         "autofunction",
         "autogenerated",
         "automodule",
@@ -200,6 +201,7 @@
         "imageio",
         "imread",
         "INCOL",
+        "INPUTTYPE",
         "INROW",
         "interactable",
         "intersphinx",
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,12 @@ This project adheres to [Semantic Versioning](https://semver.org/) since version
 
 ## [Unreleased]
 
+### Added
+
+- Added text input support to `tcod.sdl.video.Window` which was missing since the SDL3 update.
+  After creating a context use `assert context.sdl_window` or `if context.sdl_window:` to verify that an SDL window exists then use `context.sdl_window.start_text_input` to enable text input events.
+  Keep in mind that this can open an on-screen keyboard.
+
 ## [19.0.2] - 2025-07-11
 
 Resolve wheel deployment issue.
diff --git a/examples/eventget.py b/examples/eventget.py
@@ -22,6 +22,8 @@ def main() -> None:
     joysticks: set[tcod.sdl.joystick.Joystick] = set()
 
     with tcod.context.new(width=WIDTH, height=HEIGHT) as context:
+        if context.sdl_window:
+            context.sdl_window.start_text_input()
         console = context.new_console()
         while True:
             # Display all event items.
diff --git a/tcod/sdl/video.py b/tcod/sdl/video.py
@@ -89,6 +89,56 @@ class FlashOperation(enum.IntEnum):
     """Flash until focus is gained."""
 
 
+class TextInputType(enum.IntEnum):
+    """SDL input types for text input.
+
+    .. seealso::
+        :any:`Window.start_text_input`
+        https://wiki.libsdl.org/SDL3/SDL_TextInputType
+
+    .. versionadded:: Unreleased
+    """
+
+    TEXT = lib.SDL_TEXTINPUT_TYPE_TEXT
+    """The input is text."""
+    TEXT_NAME = lib.SDL_TEXTINPUT_TYPE_TEXT_NAME
+    """The input is a person's name."""
+    TEXT_EMAIL = lib.SDL_TEXTINPUT_TYPE_TEXT_EMAIL
+    """The input is an e-mail address."""
+    TEXT_USERNAME = lib.SDL_TEXTINPUT_TYPE_TEXT_USERNAME
+    """The input is a username."""
+    TEXT_PASSWORD_HIDDEN = lib.SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN
+    """The input is a secure password that is hidden."""
+    TEXT_PASSWORD_VISIBLE = lib.SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE
+    """The input is a secure password that is visible."""
+    NUMBER = lib.SDL_TEXTINPUT_TYPE_NUMBER
+    """The input is a number."""
+    NUMBER_PASSWORD_HIDDEN = lib.SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN
+    """The input is a secure PIN that is hidden."""
+    NUMBER_PASSWORD_VISIBLE = lib.SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE
+    """The input is a secure PIN that is visible."""
+
+
+class Capitalization(enum.IntEnum):
+    """Text capitalization for text input.
+
+    .. seealso::
+        :any:`Window.start_text_input`
+        https://wiki.libsdl.org/SDL3/SDL_Capitalization
+
+    .. versionadded:: Unreleased
+    """
+
+    NONE = lib.SDL_CAPITALIZE_NONE
+    """No auto-capitalization will be done."""
+    SENTENCES = lib.SDL_CAPITALIZE_SENTENCES
+    """The first letter of sentences will be capitalized."""
+    WORDS = lib.SDL_CAPITALIZE_WORDS
+    """The first letter of words will be capitalized."""
+    LETTERS = lib.SDL_CAPITALIZE_LETTERS
+    """All letters will be capitalized."""
+
+
 class _TempSurface:
     """Holds a temporary surface derived from a NumPy array."""
 
@@ -133,6 +183,9 @@ def __eq__(self, other: object) -> bool:
             return NotImplemented
         return bool(self.p == other.p)
 
+    def __hash__(self) -> int:
+        return hash(self.p)
+
     def _as_property_pointer(self) -> Any:  # noqa: ANN401
         return self.p
 
@@ -369,6 +422,67 @@ def relative_mouse_mode(self) -> bool:
     def relative_mouse_mode(self, enable: bool, /) -> None:
         _check(lib.SDL_SetWindowRelativeMouseMode(self.p, enable))
 
+    def start_text_input(
+        self,
+        *,
+        type: TextInputType = TextInputType.TEXT,  # noqa: A002
+        capitalization: Capitalization | None = None,
+        autocorrect: bool = True,
+        multiline: bool | None = None,
+        android_type: int | None = None,
+    ) -> None:
+        """Start receiving text input events supporting Unicode. This may open an on-screen keyboard.
+
+        Args:
+            type: Type of text being inputted, see :any:`TextInputType`
+            capitalization: Capitalization hint, default is based on `type` given, see :any:`Capitalization`.
+            autocorrect: Enable auto completion and auto correction.
+            multiline: Allow multiple lines of text.
+            android_type: Input type for Android, see SDL docs.
+
+        .. seealso::
+            :any:`stop_text_input`
+            :any:`set_text_input_area`
+            https://wiki.libsdl.org/SDL3/SDL_StartTextInputWithProperties
+
+        .. versionadded:: Unreleased
+        """
+        props = Properties()
+        props[("SDL_PROP_TEXTINPUT_TYPE_NUMBER", int)] = int(type)
+        if capitalization is not None:
+            props[("SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER", int)] = int(capitalization)
+        props[("SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN", bool)] = autocorrect
+        if multiline is not None:
+            props[("SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN", bool)] = multiline
+        if android_type is not None:
+            props[("SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER", int)] = int(android_type)
+        _check(lib.SDL_StartTextInputWithProperties(self.p, props.p))
+
+    def set_text_input_area(self, rect: tuple[int, int, int, int], cursor: int) -> None:
+        """Assign the area used for entering Unicode text input.
+
+        Args:
+            rect: `(x, y, width, height)` rectangle used for text input
+            cursor: Cursor X position, relative to `rect[0]`
+
+        .. seealso::
+            :any:`start_text_input`
+            https://wiki.libsdl.org/SDL3/SDL_SetTextInputArea
+
+        .. versionadded:: Unreleased
+        """
+        _check(lib.SDL_SetTextInputArea(self.p, (rect,), cursor))
+
+    def stop_text_input(self) -> None:
+        """Stop receiving text events for this window and close relevant on-screen keyboards.
+
+        .. seealso::
+            :any:`start_text_input`
+
+        .. versionadded:: Unreleased
+        """
+        _check(lib.SDL_StopTextInput(self.p))
+
 
 def new_window(  # noqa: PLR0913
     width: int,
diff --git a/tests/test_sdl.py b/tests/test_sdl.py
@@ -38,6 +38,10 @@ def test_sdl_window(uses_window: None) -> None:
     window.opacity = window.opacity
     window.grab = window.grab
 
+    window.start_text_input(capitalization=tcod.sdl.video.Capitalization.NONE, multiline=False)
+    window.set_text_input_area((0, 0, 8, 8), 0)
+    window.stop_text_input()
+
 
 def test_sdl_window_bad_types() -> None:
     with pytest.raises(TypeError):
