Add Window.mouse_rect.

Fix docs of changed properties.

Author: HexDecimal

tcod/sdl/__init__.py

@@ -58,6 +58,15 @@ def _linked_version() -> Tuple[int, int, int]:
     return int(sdl_version.major), int(sdl_version.minor), int(sdl_version.patch)
 
 
+def _version_at_least(required: Tuple[int, int, int]) -> None:
+    """Raise an error if the compiled version is less than required.  Used to guard recentally defined SDL functions."""
+    if required <= _compiled_version():
+        return
+    raise RuntimeError(
+        f"This feature requires SDL version {required}, but tcod was compiled with version {_compiled_version()}"
+    )
+
+
 def _required_version(required: Tuple[int, int, int]) -> Callable[[T], T]:
     if not lib:  # Read the docs mock object.
         return lambda x: x

tcod/sdl/render.py

@@ -180,7 +180,7 @@ def format(self) -> int:
     def access(self) -> TextureAccess:
         """Texture access mode, read only.
 
-        .. versionadded:: unreleased
+        .. versionchanged:: unreleased
             Property now returns a TextureAccess instance.
         """
         buffer = ffi.new("int*")
@@ -216,7 +216,7 @@ def alpha_mod(self, value: int) -> None:
     def blend_mode(self) -> BlendMode:
         """Texture blend mode, can be set.
 
-        .. versionadded:: unreleased
+        .. versionchanged:: unreleased
             Property now returns a BlendMode instance.
         """
         out = ffi.new("SDL_BlendMode*")

tcod/sdl/video.py

@@ -12,7 +12,7 @@
 from numpy.typing import ArrayLike, NDArray
 
 from tcod.loader import ffi, lib
-from tcod.sdl import _check, _check_p, _required_version
+from tcod.sdl import _check, _check_p, _required_version, _version_at_least
 
 __all__ = (
     "WindowFlags",
@@ -278,6 +278,23 @@ def grab(self) -> bool:
     def grab(self, value: bool) -> None:
         lib.SDL_SetWindowGrab(self.p, value)
 
+    @property
+    def mouse_rect(self) -> Optional[Tuple[int, int, int, int]]:
+        """Get or set the mouse confinement area when the window has mouse focus.
+
+        Setting this will not automatically grab the cursor.
+
+        .. versionadded:: unreleased
+        """
+        _version_at_least((2, 0, 18))
+        rect = lib.SDL_GetWindowMouseRect(self.p)
+        return (rect.x, rect.y, rect.w, rect.h) if rect else None
+
+    @mouse_rect.setter
+    def mouse_rect(self, rect: Optional[Tuple[int, int, int, int]]) -> None:
+        _version_at_least((2, 0, 18))
+        _check(lib.SDL_SetWindowMouseRect(self.p, (rect,) if rect else ffi.NULL))
+
     @_required_version((2, 0, 16))
     def flash(self, operation: FlashOperation = FlashOperation.UNTIL_FOCUSED) -> None:
         """Get the users attention."""