# The MIT License (MIT)
#
# Copyright (c) 2017 Dan Halbert
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
#
"""
`adafruit_hid.mouse.Mouse`
====================================================
* Author(s): Dan Halbert
"""
import time
import usb_hid
[docs]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."""
def __init__(self):
"""Create a Mouse object that will send USB mouse HID reports."""
self.hid_mouse = None
for device in usb_hid.devices:
if device.usage_page == 0x1 and device.usage == 0x02:
self.hid_mouse = device
break
if not self.hid_mouse:
raise IOError("Could not find an HID mouse device.")
# 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)
# Do a no-op to test if HID device is ready.
# If not, wait a bit and try once more.
try:
self._send_no_move()
except OSError:
time.sleep(1)
self._send_no_move()
[docs] def press(self, buttons):
"""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()
[docs] def release(self, buttons):
"""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()
[docs] def release_all(self):
"""Release all the mouse buttons."""
self.report[0] = 0
self._send_no_move()
[docs] def click(self, buttons):
"""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)
[docs] def move(self, x=0, y=0, wheel=0):
"""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.hid_mouse.send_report(self.report)
x -= partial_x
y -= partial_y
wheel -= partial_wheel
def _send_no_move(self):
"""Send a button-only report."""
self.report[1] = 0
self.report[2] = 0
self.report[3] = 0
self.hid_mouse.send_report(self.report)
@staticmethod
def _limit(dist):
return min(127, max(-127, dist))