Upload files to "lib/adafruit_hid"

2026-01-18 11:55:34 +00:00
parent 6e2dba8288
commit 370c9a6b9e
4 changed files with 815 additions and 0 deletions
@@ -0,0 +1,151 @@
+# SPDX-FileCopyrightText: 2017 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+`adafruit_hid.mouse.Mouse`
+====================================================
+
+* Author(s): Dan Halbert
+"""
+from . import find_device
+
+try:
+    from typing import Sequence
+    import usb_hid
+except ImportError:
+    pass
+
+
+class Mouse:
+    """Send USB HID mouse reports."""
+
+    LEFT_BUTTON = 1
+    """Left mouse button."""
+    RIGHT_BUTTON = 2
+    """Right mouse button."""
+    MIDDLE_BUTTON = 4
+    """Middle mouse button."""
+    BACK_BUTTON = 8
+    """Back mouse button."""
+    FORWARD_BUTTON = 16
+    """Forward mouse button."""
+
+    def __init__(self, devices: Sequence[usb_hid.Device], timeout: int = None) -> None:
+        """Create a Mouse object that will send USB mouse HID reports.
+
+        :param timeout: Time in seconds to wait for USB to become ready before timing out.
+          Defaults to None to wait indefinitely.
+
+        Devices can be a sequence of devices that includes a keyboard device or a keyboard device
+        itself. A device is any object that implements ``send_report()``, ``usage_page`` and
+        ``usage``.
+        """
+        self._mouse_device = find_device(
+            devices, usage_page=0x1, usage=0x02, timeout=timeout
+        )
+
+        # Reuse this bytearray to send mouse reports.
+        # report[0] buttons pressed (LEFT, MIDDLE, RIGHT)
+        # report[1] x movement
+        # report[2] y movement
+        # report[3] wheel movement
+        self.report = bytearray(4)
+
+    def press(self, buttons: int) -> None:
+        """Press the given mouse buttons.
+
+        :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``,
+            ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
+
+        Examples::
+
+            # Press the left button.
+            m.press(Mouse.LEFT_BUTTON)
+
+            # Press the left and right buttons simultaneously.
+            m.press(Mouse.LEFT_BUTTON | Mouse.RIGHT_BUTTON)
+        """
+        self.report[0] |= buttons
+        self._send_no_move()
+
+    def release(self, buttons: int) -> None:
+        """Release the given mouse buttons.
+
+        :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``,
+            ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
+        """
+        self.report[0] &= ~buttons
+        self._send_no_move()
+
+    def release_all(self) -> None:
+        """Release all the mouse buttons."""
+        self.report[0] = 0
+        self._send_no_move()
+
+    def click(self, buttons: int) -> None:
+        """Press and release the given mouse buttons.
+
+        :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``,
+            ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
+
+        Examples::
+
+            # Click the left button.
+            m.click(Mouse.LEFT_BUTTON)
+
+            # Double-click the left button.
+            m.click(Mouse.LEFT_BUTTON)
+            m.click(Mouse.LEFT_BUTTON)
+        """
+        self.press(buttons)
+        self.release(buttons)
+
+    def move(self, x: int = 0, y: int = 0, wheel: int = 0) -> None:
+        """Move the mouse and turn the wheel as directed.
+
+        :param x: Move the mouse along the x axis. Negative is to the left, positive
+            is to the right.
+        :param y: Move the mouse along the y axis. Negative is upwards on the display,
+            positive is downwards.
+        :param wheel: Rotate the wheel this amount. Negative is toward the user, positive
+            is away from the user. The scrolling effect depends on the host.
+
+        Examples::
+
+            # Move 100 to the left. Do not move up and down. Do not roll the scroll wheel.
+            m.move(-100, 0, 0)
+            # Same, with keyword arguments.
+            m.move(x=-100)
+
+            # Move diagonally to the upper right.
+            m.move(50, 20)
+            # Same.
+            m.move(x=50, y=-20)
+
+            # Roll the mouse wheel away from the user.
+            m.move(wheel=1)
+        """
+        # Send multiple reports if necessary to move or scroll requested amounts.
+        while x != 0 or y != 0 or wheel != 0:
+            partial_x = self._limit(x)
+            partial_y = self._limit(y)
+            partial_wheel = self._limit(wheel)
+            self.report[1] = partial_x & 0xFF
+            self.report[2] = partial_y & 0xFF
+            self.report[3] = partial_wheel & 0xFF
+            self._mouse_device.send_report(self.report)
+            x -= partial_x
+            y -= partial_y
+            wheel -= partial_wheel
+
+    def _send_no_move(self) -> None:
+        """Send a button-only report."""
+        self.report[1] = 0
+        self.report[2] = 0
+        self.report[3] = 0
+        self._mouse_device.send_report(self.report)
+
+    @staticmethod
+    def _limit(dist: int) -> int:
+        return min(127, max(-127, dist))