Refactor events to deprecate mouse tile attributes.

Renamed mouse pixel attributes to position and motion.
Old names have been deprecated.

Context.convert_event now returns an event with tile coordinates active.

Author: HexDecimal

examples/samples_tcod.py

@@ -1105,8 +1105,8 @@ def on_draw(self) -> None:
             "Right button   : %s\n"
             "Middle button  : %s\n"
             % (
-                self.motion.pixel.x,
-                self.motion.pixel.y,
+                self.motion.position.x,
+                self.motion.position.y,
                 self.motion.tile.x,
                 self.motion.tile.y,
                 self.motion.tile_motion.x,
@@ -1489,11 +1489,13 @@ def handle_events() -> None:
         if context.sdl_renderer:
             # Manual handing of tile coordinates since context.present is skipped.
             if isinstance(event, (tcod.event.MouseState, tcod.event.MouseMotion)):
-                event.tile = tcod.event.Point(event.pixel.x // tileset.tile_width, event.pixel.y // tileset.tile_height)
+                event.tile = tcod.event.Point(
+                    event.position.x // tileset.tile_width, event.position.y // tileset.tile_height
+                )
             if isinstance(event, tcod.event.MouseMotion):
                 prev_tile = (
-                    (event.pixel[0] - event.pixel_motion[0]) // tileset.tile_width,
-                    (event.pixel[1] - event.pixel_motion[1]) // tileset.tile_height,
+                    (event.position[0] - event.motion[0]) // tileset.tile_width,
+                    (event.position[1] - event.motion[1]) // tileset.tile_height,
                 )
                 event.tile_motion = tcod.event.Point(event.tile[0] - prev_tile[0], event.tile[1] - prev_tile[1])
         else:

tcod/context.py

@@ -49,11 +49,12 @@
 """  # noqa: E501
 from __future__ import annotations
 
+import copy
 import os
 import pickle
 import sys
 import warnings
-from typing import Any, Iterable, List, Optional, Tuple
+from typing import Any, Iterable, List, Optional, Tuple, TypeVar
 
 from typing_extensions import Literal, NoReturn
 
@@ -87,6 +88,8 @@
     "RENDERER_XTERM",
 )
 
+_Event = TypeVar("_Event", bound=tcod.event.Event)
+
 SDL_WINDOW_FULLSCREEN = lib.SDL_WINDOW_FULLSCREEN
 """Exclusive fullscreen mode.
 
@@ -247,30 +250,38 @@ def pixel_to_subtile(self, x: int, y: int) -> Tuple[float, float]:
             _check(lib.TCOD_context_screen_pixel_to_tile_d(self._context_p, xy, xy + 1))
             return xy[0], xy[1]
 
-    def convert_event(self, event: tcod.event.Event) -> None:
-        """Fill in the tile coordinates of a mouse event using this context.
+    def convert_event(self, event: _Event) -> _Event:
+        """Return an event with mouse pixel coordinates converted into tile coordinates.
 
         Example::
 
             context: tcod.context.Context
             for event in tcod.event.get():
+                event_tile = context.convert_event(event)
                 if isinstance(event, tcod.event.MouseMotion):
-                    # Pixel coordinates are always accessible.
-                    print(f"{event.pixel=}, {event.pixel_motion=}")
-                context.convert_event(event)
-                if isinstance(event, tcod.event.MouseMotion):
-                    # Now tile coordinate attributes can be accessed.
-                    print(f"{event.tile=}, {event.tile_motion=}")
-                    # A warning will be raised if you try to access these without convert_event.
+                    # Events start with pixel coordinates and motion.
+                    print(f"Pixels: {event.position=}, {event.motion=}")
+                if isinstance(event_tile, tcod.event.MouseMotion):
+                    # Tile coordinates are used in the returned event.
+                    print(f"Tiles: {event_tile.position=}, {event_tile.motion=}")
+
+        .. versionchanged:: Unreleased
+            Now returns a new event with the coordinates converted into tiles.
         """
+        event_copy = copy.copy(event)
         if isinstance(event, (tcod.event.MouseState, tcod.event.MouseMotion)):
-            event.tile = tcod.event.Point(*self.pixel_to_tile(*event.pixel))
+            assert isinstance(event_copy, (tcod.event.MouseState, tcod.event.MouseMotion))
+            event_copy.position = event.tile = tcod.event.Point(*self.pixel_to_tile(*event.position))
         if isinstance(event, tcod.event.MouseMotion):
+            assert isinstance(event_copy, tcod.event.MouseMotion)
             prev_tile = self.pixel_to_tile(
-                event.pixel[0] - event.pixel_motion[0],
-                event.pixel[1] - event.pixel_motion[1],
+                event.position[0] - event.motion[0],
+                event.position[1] - event.motion[1],
+            )
+            event_copy.motion = event.tile_motion = tcod.event.Point(
+                event.tile[0] - prev_tile[0], event.tile[1] - prev_tile[1]
             )
-            event.tile_motion = tcod.event.Point(event.tile[0] - prev_tile[0], event.tile[1] - prev_tile[1])
+        return event_copy
 
     def save_screenshot(self, path: Optional[str] = None) -> None:
         """Save a screen-shot to the given file path."""

tcod/event.py

@@ -384,7 +384,7 @@ class MouseState(Event):
     """
     Attributes:
         type (str): Always "MOUSESTATE".
-        pixel (Point): The pixel coordinates of the mouse.
+        position (Point): The position coordinates of the mouse.
         tile (Point): The integer tile coordinates of the mouse on the screen.
         state (int): A bitmask of which mouse buttons are currently held.
 
@@ -397,39 +397,70 @@ class MouseState(Event):
             * tcod.event.BUTTON_X2MASK
 
     .. versionadded:: 9.3
+
+    .. versionchanged:: Unreleased
+        Renamed `pixel` attribute to `position`.
     """
 
     def __init__(
         self,
-        pixel: Tuple[int, int] = (0, 0),
+        position: Tuple[int, int] = (0, 0),
         tile: Optional[Tuple[int, int]] = (0, 0),
         state: int = 0,
     ):
         super().__init__()
-        self.pixel = Point(*pixel)
+        self.position = Point(*position)
         self.__tile = Point(*tile) if tile is not None else None
         self.state = state
 
+    @property
+    def pixel(self) -> Point:
+        warnings.warn(
+            "The mouse.pixel attribute is deprecated.  Use mouse.position instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.position
+
+    @pixel.setter
+    def pixel(self, value: Point) -> None:
+        warnings.warn(
+            "The mouse.pixel attribute is deprecated.  Use mouse.position instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.position = value
+
     @property
     def tile(self) -> Point:
+        warnings.warn(
+            "The mouse.tile attribute is deprecated.  Use mouse.position of the event returned by context.convert_event instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return _verify_tile_coordinates(self.__tile)
 
     @tile.setter
     def tile(self, xy: Tuple[int, int]) -> None:
+        warnings.warn(
+            "The mouse.tile attribute is deprecated.  Use mouse.position of the event returned by context.convert_event instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.__tile = Point(*xy)
 
     def __repr__(self) -> str:
-        return ("tcod.event.%s(pixel=%r, tile=%r, state=%s)") % (
+        return ("tcod.event.%s(position=%r, tile=%r, state=%s)") % (
             self.__class__.__name__,
-            tuple(self.pixel),
+            tuple(self.position),
             tuple(self.tile),
             _describe_bitmask(self.state, _REVERSE_BUTTON_MASK_TABLE_PREFIX),
         )
 
     def __str__(self) -> str:
-        return ("<%s, pixel=(x=%i, y=%i), tile=(x=%i, y=%i), state=%s>") % (
+        return ("<%s, position=(x=%i, y=%i), tile=(x=%i, y=%i), state=%s>") % (
             super().__str__().strip("<>"),
-            *self.pixel,
+            *self.position,
             *self.tile,
             _describe_bitmask(self.state, _REVERSE_BUTTON_MASK_TABLE),
         )
@@ -439,8 +470,8 @@ class MouseMotion(MouseState):
     """
     Attributes:
         type (str): Always "MOUSEMOTION".
-        pixel (Point): The pixel coordinates of the mouse.
-        pixel_motion (Point): The pixel delta.
+        position (Point): The pixel coordinates of the mouse.
+        motion (Point): The pixel delta.
         tile (Point): The integer tile coordinates of the mouse on the screen.
         tile_motion (Point): The integer tile delta.
         state (int): A bitmask of which mouse buttons are currently held.
@@ -452,26 +483,60 @@ class MouseMotion(MouseState):
             * tcod.event.BUTTON_RMASK
             * tcod.event.BUTTON_X1MASK
             * tcod.event.BUTTON_X2MASK
+
+    .. versionchanged:: Unreleased
+        Renamed `pixel` attribute to `position`.
+        Renamed `pixel_motion` attribute to `motion`.
     """
 
     def __init__(
         self,
-        pixel: Tuple[int, int] = (0, 0),
-        pixel_motion: Tuple[int, int] = (0, 0),
+        position: Tuple[int, int] = (0, 0),
+        motion: Tuple[int, int] = (0, 0),
         tile: Optional[Tuple[int, int]] = (0, 0),
         tile_motion: Optional[Tuple[int, int]] = (0, 0),
         state: int = 0,
     ):
-        super().__init__(pixel, tile, state)
-        self.pixel_motion = Point(*pixel_motion)
+        super().__init__(position, tile, state)
+        self.motion = Point(*motion)
         self.__tile_motion = Point(*tile_motion) if tile_motion is not None else None
 
+    @property
+    def pixel_motion(self) -> Point:
+        warnings.warn(
+            "The mouse.pixel_motion attribute is deprecated.  Use mouse.motion instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.motion
+
+    @pixel_motion.setter
+    def pixel_motion(self, value: Point) -> None:
+        warnings.warn(
+            "The mouse.pixel_motion attribute is deprecated.  Use mouse.motion instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.motion = value
+
     @property
     def tile_motion(self) -> Point:
+        warnings.warn(
+            "The mouse.tile_motion attribute is deprecated."
+            "  Use mouse.motion of the event returned by context.convert_event instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return _verify_tile_coordinates(self.__tile_motion)
 
     @tile_motion.setter
     def tile_motion(self, xy: Tuple[int, int]) -> None:
+        warnings.warn(
+            "The mouse.tile_motion attribute is deprecated."
+            "  Use mouse.motion of the event returned by context.convert_event instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.__tile_motion = Point(*xy)
 
     @classmethod
@@ -494,19 +559,19 @@ def from_sdl_event(cls, sdl_event: Any) -> MouseMotion:
         return self
 
     def __repr__(self) -> str:
-        return ("tcod.event.%s(pixel=%r, pixel_motion=%r, " "tile=%r, tile_motion=%r, state=%s)") % (
+        return ("tcod.event.%s(position=%r, motion=%r, tile=%r, tile_motion=%r, state=%s)") % (
             self.__class__.__name__,
-            tuple(self.pixel),
-            tuple(self.pixel_motion),
+            tuple(self.position),
+            tuple(self.motion),
             tuple(self.tile),
             tuple(self.tile_motion),
             _describe_bitmask(self.state, _REVERSE_BUTTON_MASK_TABLE_PREFIX),
         )
 
     def __str__(self) -> str:
-        return ("<%s, pixel_motion=(x=%i, y=%i), tile_motion=(x=%i, y=%i)>") % (
+        return ("<%s, motion=(x=%i, y=%i), tile_motion=(x=%i, y=%i)>") % (
             super().__str__().strip("<>"),
-            *self.pixel_motion,
+            *self.motion,
             *self.tile_motion,
         )
 
@@ -516,7 +581,7 @@ class MouseButtonEvent(MouseState):
     Attributes:
         type (str): Will be "MOUSEBUTTONDOWN" or "MOUSEBUTTONUP",
                     depending on the event.
-        pixel (Point): The pixel coordinates of the mouse.
+        position (Point): The pixel coordinates of the mouse.
         tile (Point): The integer tile coordinates of the mouse on the screen.
         button (int): Which mouse button.
 
@@ -527,6 +592,7 @@ class MouseButtonEvent(MouseState):
             * tcod.event.BUTTON_RIGHT
             * tcod.event.BUTTON_X1
             * tcod.event.BUTTON_X2
+
     """
 
     def __init__(
@@ -559,17 +625,17 @@ def from_sdl_event(cls, sdl_event: Any) -> Any:
         return self
 
     def __repr__(self) -> str:
-        return "tcod.event.%s(pixel=%r, tile=%r, button=%s)" % (
+        return "tcod.event.%s(position=%r, tile=%r, button=%s)" % (
             self.__class__.__name__,
-            tuple(self.pixel),
+            tuple(self.position),
             tuple(self.tile),
             _REVERSE_BUTTON_TABLE_PREFIX[self.button],
         )
 
     def __str__(self) -> str:
-        return "<type=%r, pixel=(x=%i, y=%i), tile=(x=%i, y=%i), button=%s)" % (
+        return "<type=%r, position=(x=%i, y=%i), tile=(x=%i, y=%i), button=%s)" % (
             self.type,
-            *self.pixel,
+            *self.position,
             *self.tile,
             _REVERSE_BUTTON_TABLE[self.button],
         )

tcod/sdl/mouse.py

@@ -189,7 +189,7 @@ def get_global_state() -> tcod.event.MouseState:
     """
     xy = ffi.new("int[2]")
     state = lib.SDL_GetGlobalMouseState(xy, xy + 1)
-    return tcod.event.MouseState(pixel=(xy[0], xy[1]), state=state)
+    return tcod.event.MouseState((xy[0], xy[1]), state=state)
 
 
 def get_relative_state() -> tcod.event.MouseState:
@@ -200,7 +200,7 @@ def get_relative_state() -> tcod.event.MouseState:
     """
     xy = ffi.new("int[2]")
     state = lib.SDL_GetRelativeMouseState(xy, xy + 1)
-    return tcod.event.MouseState(pixel=(xy[0], xy[1]), state=state)
+    return tcod.event.MouseState((xy[0], xy[1]), state=state)
 
 
 def get_state() -> tcod.event.MouseState:
@@ -211,7 +211,7 @@ def get_state() -> tcod.event.MouseState:
     """
     xy = ffi.new("int[2]")
     state = lib.SDL_GetMouseState(xy, xy + 1)
-    return tcod.event.MouseState(pixel=(xy[0], xy[1]), state=state)
+    return tcod.event.MouseState((xy[0], xy[1]), state=state)
 
 
 def get_focus() -> Optional[tcod.sdl.video.Window]: