Add basic joystick port of SDL2.

Author: HexDecimal

CHANGELOG.md

@@ -4,6 +4,9 @@ Changes relevant to the users of python-tcod are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/) since version `2.0.0`.
 
 ## [Unreleased]
+### Added
+- Ported SDL2 joystick handing as `tcod.sdl.joystick`.
+- New joystick related events.
 
 ## [13.7.0] - 2022-08-07
 ### Added

docs/index.rst

@@ -40,6 +40,7 @@ Contents:
     tcod/tileset
     libtcodpy
     sdl/audio
+    sdl/joystick
     sdl/render
     sdl/mouse
     sdl/video

docs/sdl/joystick.rst

@@ -0,0 +1,6 @@
+tcod.sdl.joystick - SDL Joystick Support
+========================================
+
+.. automodule:: tcod.sdl.joystick
+    :members:
+    :member-order: bysource

examples/eventget.py

@@ -8,6 +8,8 @@
 from typing import List
 
 import tcod
+import tcod.sdl.joystick
+import tcod.sdl.sys
 
 WIDTH, HEIGHT = 720, 480
 
@@ -17,6 +19,7 @@ def main() -> None:
 
     event_log: List[str] = []
     motion_desc = ""
+    joysticks = tcod.sdl.joystick.get_joysticks()
 
     with tcod.context.new(width=WIDTH, height=HEIGHT) as context:
         console = context.new_console()

tcod/event.py

@@ -93,6 +93,7 @@
 from tcod.event_constants import *  # noqa: F4
 from tcod.event_constants import KMOD_ALT, KMOD_CTRL, KMOD_GUI, KMOD_SHIFT
 from tcod.loader import ffi, lib
+from tcod.sdl.joystick import _HAT_DIRECTIONS
 
 T = TypeVar("T")
 
@@ -303,7 +304,7 @@ def from_sdl_event(cls, sdl_event: Any) -> Event:
         raise NotImplementedError()
 
     def __str__(self) -> str:
-        return "<type=%r>" % (self.type,)
+        return f"<type={self.type!r}>"
 
 
 class Quit(Event):
@@ -779,6 +780,199 @@ def __str__(self) -> str:
         )
 
 
+class JoystickEvent(Event):
+    """A base class for joystick events.
+
+    .. versionadded:: Unreleased
+    """
+
+    def __init__(self, type: str, which: int):
+        super().__init__(type)
+        self.which = which
+        """The ID of the joystick this event is for."""
+
+    def __repr__(self) -> str:
+        return f"tcod.event.{self.__class__.__name__}" f"(type={self.type!r}, which={self.which})"
+
+    def __str__(self) -> str:
+        prefix = super().__str__().strip("<>")
+        return f"<{prefix}, which={self.which}>"
+
+
+class JoystickAxis(JoystickEvent):
+    """When a joystick axis changes in value.
+
+    .. versionadded:: Unreleased
+
+    .. seealso::
+        :any:`tcod.sdl.joystick`
+    """
+
+    which: int
+    """The ID of the joystick this event is for."""
+
+    def __init__(self, type: str, which: int, axis: int, value: int):
+        super().__init__(type, which)
+        self.axis = axis
+        """The index of the changed axis."""
+        self.value = value
+        """The raw value of the axis in the range -32768 to 32767."""
+
+    @classmethod
+    def from_sdl_event(cls, sdl_event: Any) -> JoystickAxis:
+        return cls("JOYAXISMOTION", sdl_event.jaxis.which, sdl_event.jaxis.axis, sdl_event.jaxis.value)
+
+    def __repr__(self) -> str:
+        return (
+            f"tcod.event.{self.__class__.__name__}"
+            f"(type={self.type!r}, which={self.which}, axis={self.axis}, value={self.value})"
+        )
+
+    def __str__(self) -> str:
+        prefix = super().__str__().strip("<>")
+        return f"<{prefix}, axis={self.axis}, value={self.value}>"
+
+
+class JoystickBall(JoystickEvent):
+    """When a joystick ball is moved.
+
+    .. versionadded:: Unreleased
+
+    .. seealso::
+        :any:`tcod.sdl.joystick`
+    """
+
+    which: int
+    """The ID of the joystick this event is for."""
+
+    def __init__(self, type: str, which: int, ball: int, dx: int, dy: int):
+        super().__init__(type, which)
+        self.ball = ball
+        """The index of the moved ball."""
+        self.dx = dx
+        """The X motion of the ball."""
+        self.dy = dy
+        """The Y motion of the ball."""
+
+    @classmethod
+    def from_sdl_event(cls, sdl_event: Any) -> JoystickBall:
+        return cls(
+            "JOYBALLMOTION", sdl_event.jball.which, sdl_event.jball.ball, sdl_event.jball.xrel, sdl_event.jball.yrel
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"tcod.event.{self.__class__.__name__}"
+            f"(type={self.type!r}, which={self.which}, ball={self.ball}, dx={self.dx}, dy={self.dy})"
+        )
+
+    def __str__(self) -> str:
+        prefix = super().__str__().strip("<>")
+        return f"<{prefix}, ball={self.ball}, dx={self.dx}, dy={self.dy}>"
+
+
+class JoystickHat(JoystickEvent):
+    """When a joystick hat changes direction.
+
+    .. versionadded:: Unreleased
+
+    .. seealso::
+        :any:`tcod.sdl.joystick`
+    """
+
+    which: int
+    """The ID of the joystick this event is for."""
+
+    def __init__(self, type: str, which: int, x: Literal[-1, 0, 1], y: Literal[-1, 0, 1]):
+        super().__init__(type, which)
+        self.x = x
+        """The new X direction of the hat."""
+        self.y = y
+        """The new Y direction of the hat."""
+
+    @classmethod
+    def from_sdl_event(cls, sdl_event: Any) -> JoystickHat:
+        return cls("JOYHATMOTION", sdl_event.jhat.which, *_HAT_DIRECTIONS[sdl_event.jhat.hat])
+
+    def __repr__(self) -> str:
+        return (
+            f"tcod.event.{self.__class__.__name__}" f"(type={self.type!r}, which={self.which}, x={self.x}, y={self.y})"
+        )
+
+    def __str__(self) -> str:
+        prefix = super().__str__().strip("<>")
+        return f"<{prefix}, x={self.x}, y={self.y}>"
+
+
+class JoystickButton(JoystickEvent):
+    """When a joystick button is pressed or released.
+
+    .. versionadded:: Unreleased
+
+    Example::
+
+        for event in tcod.event.get():
+            match event:
+                case JoystickButton(which=which, button=button, pressed=True):
+                    print(f"Pressed {button=} on controller {which}.")
+                case JoystickButton(which=which, button=button, pressed=False):
+                    print(f"Released {button=} on controller {which}.")
+    """
+
+    which: int
+    """The ID of the joystick this event is for."""
+
+    def __init__(self, type: str, which: int, button: int):
+        super().__init__(type, which)
+        self.button = button
+        """The index of the button this event is for."""
+
+    @property
+    def pressed(self) -> bool:
+        """True if the joystick button has been pressed, False when the button was released."""
+        return self.type == "JOYBUTTONDOWN"
+
+    @classmethod
+    def from_sdl_event(cls, sdl_event: Any) -> JoystickButton:
+        type = {lib.SDL_JOYBUTTONDOWN: "JOYBUTTONDOWN", lib.SDL_JOYBUTTONUP: "JOYBUTTONUP"}[sdl_event.type]
+        return cls(type, sdl_event.jbutton.which, sdl_event.jbutton.button)
+
+    def __repr__(self) -> str:
+        return f"tcod.event.{self.__class__.__name__}" f"(type={self.type!r}, which={self.which}, button={self.button})"
+
+    def __str__(self) -> str:
+        prefix = super().__str__().strip("<>")
+        return f"<{prefix}, button={self.button}>"
+
+
+class JoystickDevice(JoystickEvent):
+    """An event for when a joystick is added or removed.
+
+    .. versionadded:: Unreleased
+
+    Example::
+
+        joysticks: dict[int, tcod.sdl.joystick.Joystick] = {}
+        for event in tcod.event.get():
+            match event:
+                case tcod.event.JoystickDevice(type="JOYDEVICEADDED", which=device_id):
+                    new_joystick = tcod.sdl.joystick.Joystick(device_id)
+                    joysticks[new_joystick.id] = new_joystick
+                case tcod.event.JoystickDevice(type="JOYDEVICEREMOVED", which=which):
+                    del joysticks[which]
+    """
+
+    which: int
+    """When type="JOYDEVICEADDED" this is the device ID.
+    When type="JOYDEVICEREMOVED" this is the instance ID.
+    """
+
+    @classmethod
+    def from_sdl_event(cls, sdl_event: Any) -> JoystickDevice:
+        type = {lib.SDL_JOYDEVICEADDED: "JOYDEVICEADDED", lib.SDL_JOYDEVICEREMOVED: "JOYDEVICEREMOVED"}[sdl_event.type]
+        return cls(type, sdl_event.jdevice.which)
+
+
 class Undefined(Event):
     """This class is a place holder for SDL events without their own tcod.event
     class.
@@ -809,6 +1003,13 @@ def __str__(self) -> str:
     lib.SDL_MOUSEWHEEL: MouseWheel,
     lib.SDL_TEXTINPUT: TextInput,
     lib.SDL_WINDOWEVENT: WindowEvent,
+    lib.SDL_JOYAXISMOTION: JoystickAxis,
+    lib.SDL_JOYBALLMOTION: JoystickBall,
+    lib.SDL_JOYHATMOTION: JoystickHat,
+    lib.SDL_JOYBUTTONDOWN: JoystickButton,
+    lib.SDL_JOYBUTTONUP: JoystickButton,
+    lib.SDL_JOYDEVICEADDED: JoystickDevice,
+    lib.SDL_JOYDEVICEREMOVED: JoystickDevice,
 }
 
 
@@ -1076,6 +1277,41 @@ def ev_windowtakefocus(self, event: tcod.event.WindowEvent) -> Optional[T]:
     def ev_windowhittest(self, event: tcod.event.WindowEvent) -> Optional[T]:
         pass
 
+    def ev_joyaxismotion(self, event: tcod.event.JoystickAxis) -> Optional[T]:
+        """
+        .. versionadded:: Unreleased
+        """
+
+    def ev_joyballmotion(self, event: tcod.event.JoystickBall) -> Optional[T]:
+        """
+        .. versionadded:: Unreleased
+        """
+
+    def ev_joyhatmotion(self, event: tcod.event.JoystickHat) -> Optional[T]:
+        """
+        .. versionadded:: Unreleased
+        """
+
+    def ev_joybuttondown(self, event: tcod.event.JoystickButton) -> Optional[T]:
+        """
+        .. versionadded:: Unreleased
+        """
+
+    def ev_joybuttonup(self, event: tcod.event.JoystickButton) -> Optional[T]:
+        """
+        .. versionadded:: Unreleased
+        """
+
+    def ev_joydeviceadded(self, event: tcod.event.JoystickDevice) -> Optional[T]:
+        """
+        .. versionadded:: Unreleased
+        """
+
+    def ev_joydeviceremoved(self, event: tcod.event.JoystickDevice) -> Optional[T]:
+        """
+        .. versionadded:: Unreleased
+        """
+
     def ev_(self, event: Any) -> Optional[T]:
         pass
 
@@ -2326,6 +2562,12 @@ def __repr__(self) -> str:
     "WindowEvent",
     "WindowMoved",
     "WindowResized",
+    "JoystickEvent",
+    "JoystickAxis",
+    "JoystickBall",
+    "JoystickHat",
+    "JoystickButton",
+    "JoystickDevice",
     "Undefined",
     "get",
     "wait",