1  # The MIT License (MIT)
  2  #
  3  # Copyright (c) 2017 Dan Halbert
  4  #
  5  # Permission is hereby granted, free of charge, to any person obtaining a copy
  6  # of this software and associated documentation files (the "Software"), to deal
  7  # in the Software without restriction, including without limitation the rights
  8  # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9  # copies of the Software, and to permit persons to whom the Software is
 10  # furnished to do so, subject to the following conditions:
 11  #
 12  # The above copyright notice and this permission notice shall be included in
 13  # all copies or substantial portions of the Software.
 14  #
 15  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16  # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17  # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18  # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19  # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20  # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 21  # THE SOFTWARE.
 22  #
 23  
 24  """
 25  `adafruit_hid.mouse.Mouse`
 26  ====================================================
 27  
 28  * Author(s): Dan Halbert
 29  """
 30  import time
 31  
 32  from . import find_device
 33  
 34  
 35  class Mouse:
 36      """Send USB HID mouse reports."""
 37  
 38      LEFT_BUTTON = 1
 39      """Left mouse button."""
 40      RIGHT_BUTTON = 2
 41      """Right mouse button."""
 42      MIDDLE_BUTTON = 4
 43      """Middle mouse button."""
 44  
 45      def __init__(self, devices):
 46          """Create a Mouse object that will send USB mouse HID reports.
 47  
 48          Devices can be a list of devices that includes a keyboard device or a keyboard device
 49          itself. A device is any object that implements ``send_report()``, ``usage_page`` and
 50          ``usage``.
 51          """
 52          self._mouse_device = find_device(devices, usage_page=0x1, usage=0x02)
 53  
 54          # Reuse this bytearray to send mouse reports.
 55          # report[0] buttons pressed (LEFT, MIDDLE, RIGHT)
 56          # report[1] x movement
 57          # report[2] y movement
 58          # report[3] wheel movement
 59          self.report = bytearray(4)
 60  
 61          # Do a no-op to test if HID device is ready.
 62          # If not, wait a bit and try once more.
 63          try:
 64              self._send_no_move()
 65          except OSError:
 66              time.sleep(1)
 67              self._send_no_move()
 68  
 69      def press(self, buttons):
 70          """Press the given mouse buttons.
 71  
 72          :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``,
 73              ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
 74  
 75          Examples::
 76  
 77              # Press the left button.
 78              m.press(Mouse.LEFT_BUTTON)
 79  
 80              # Press the left and right buttons simultaneously.
 81              m.press(Mouse.LEFT_BUTTON | Mouse.RIGHT_BUTTON)
 82          """
 83          self.report[0] |= buttons
 84          self._send_no_move()
 85  
 86      def release(self, buttons):
 87          """Release the given mouse buttons.
 88  
 89          :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``,
 90              ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
 91          """
 92          self.report[0] &= ~buttons
 93          self._send_no_move()
 94  
 95      def release_all(self):
 96          """Release all the mouse buttons."""
 97          self.report[0] = 0
 98          self._send_no_move()
 99  
100      def click(self, buttons):
101          """Press and release the given mouse buttons.
102  
103          :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``,
104              ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
105  
106          Examples::
107  
108              # Click the left button.
109              m.click(Mouse.LEFT_BUTTON)
110  
111              # Double-click the left button.
112              m.click(Mouse.LEFT_BUTTON)
113              m.click(Mouse.LEFT_BUTTON)
114          """
115          self.press(buttons)
116          self.release(buttons)
117  
118      def move(self, x=0, y=0, wheel=0):
119          """Move the mouse and turn the wheel as directed.
120  
121          :param x: Move the mouse along the x axis. Negative is to the left, positive
122              is to the right.
123          :param y: Move the mouse along the y axis. Negative is upwards on the display,
124              positive is downwards.
125          :param wheel: Rotate the wheel this amount. Negative is toward the user, positive
126              is away from the user. The scrolling effect depends on the host.
127  
128          Examples::
129  
130              # Move 100 to the left. Do not move up and down. Do not roll the scroll wheel.
131              m.move(-100, 0, 0)
132              # Same, with keyword arguments.
133              m.move(x=-100)
134  
135              # Move diagonally to the upper right.
136              m.move(50, 20)
137              # Same.
138              m.move(x=50, y=-20)
139  
140              # Roll the mouse wheel away from the user.
141              m.move(wheel=1)
142          """
143          # Send multiple reports if necessary to move or scroll requested amounts.
144          while x != 0 or y != 0 or wheel != 0:
145              partial_x = self._limit(x)
146              partial_y = self._limit(y)
147              partial_wheel = self._limit(wheel)
148              self.report[1] = partial_x & 0xFF
149              self.report[2] = partial_y & 0xFF
150              self.report[3] = partial_wheel & 0xFF
151              self._mouse_device.send_report(self.report)
152              x -= partial_x
153              y -= partial_y
154              wheel -= partial_wheel
155  
156      def _send_no_move(self):
157          """Send a button-only report."""
158          self.report[1] = 0
159          self.report[2] = 0
160          self.report[3] = 0
161          self._mouse_device.send_report(self.report)
162  
163      @staticmethod
164      def _limit(dist):
165          return min(127, max(-127, dist))