Hook and simulate mouse events on Windows and Linux
Project description
mouse
This version of mouse is published from a forked repository. It is reproduced under the MIT license. For the original mouse project, please look here.
Take full control of your mouse with this small Python library. Hook global events, register hotkeys, simulate mouse movement and clicks, and much more.
Huge thanks to Kirill Pavlov for donating the package name. If you are looking for the Cheddargetter.com client implementation, pip install mouse==0.5.0
.
Features
- Global event hook on all mice devices (captures events regardless of focus).
- Listen and sends mouse events.
- Works with Windows and Linux as mouse, not MacMouse. This is a seperate project (the original) and can be installed via
sudo pip install mouse
- Works with MacOS (requires granting accessibility permissions to terminal/python in System Preferences -> Security & Privacy)
- Pure Python, no C modules to be compiled.
- Python 2 and 3.
- Includes high level API (e.g. record and play.
- Events automatically captured in separate thread, doesn't block main program.
- Tested and documented.
This program makes no attempt to hide itself, so don't use it for keyloggers.
Usage
Install the PyPI package:
$ pip install macmouse
or clone the repository (no installation required, source files are sufficient):
$ git clone https://github.com/gansel51/mouse
Known limitations:
- Other applications, such as some games, may register hooks that swallow all key events. In this case
mouse
will be unable to report events.
API
Table of Contents
- mouse.ButtonEvent
- mouse.DOUBLE
- mouse.DOWN
- mouse.LEFT
- mouse.MIDDLE
- mouse.MoveEvent
- mouse.RIGHT
- mouse.UP
- mouse.WheelEvent
- mouse.X
- mouse.X2
- mouse.version
- mouse.is_pressed
- mouse.press (aliases:
hold
) - mouse.release
- mouse.click
- mouse.double_click
- mouse.right_click
- mouse.wheel
- mouse.move
- mouse.drag
- mouse.on_button
- mouse.on_click
- mouse.on_double_click
- mouse.on_right_click
- mouse.on_middle_click
- mouse.wait
- mouse.get_position
- mouse.hook
- mouse.unhook
- mouse.unhook_all
- mouse.record
- mouse.play (aliases:
replay
)
class mouse.ButtonEvent
ButtonEvent(event_type, button, time)
ButtonEvent.button
Alias for field number 1
ButtonEvent.count(self, value, /)
Return number of occurrences of value.
ButtonEvent.event_type
Alias for field number 0
ButtonEvent.index(self, value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
ButtonEvent.time
Alias for field number 2
mouse.DOUBLE
= 'double'
mouse.DOWN
= 'down'
mouse.LEFT
= 'left'
mouse.MIDDLE
= 'middle'
class mouse.MoveEvent
MoveEvent(x, y, time)
MoveEvent.count(self, value, /)
Return number of occurrences of value.
MoveEvent.index(self, value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
MoveEvent.time
Alias for field number 2
MoveEvent.x
Alias for field number 0
MoveEvent.y
Alias for field number 1
mouse.RIGHT
= 'right'
mouse.UP
= 'up'
class mouse.WheelEvent
WheelEvent(delta, time)
WheelEvent.count(self, value, /)
Return number of occurrences of value.
WheelEvent.delta
Alias for field number 0
WheelEvent.index(self, value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
WheelEvent.time
Alias for field number 1
mouse.X
= 'x'
mouse.X2
= 'x2'
mouse.version
= '0.7.1'
mouse.is_pressed(button='left')
Returns True if the given button is currently pressed.
mouse.press(button='left')
Presses the given button (but doesn't release).
mouse.release(button='left')
Releases the given button.
mouse.click(button='left')
Sends a click with the given button.
mouse.double_click(button='left')
Sends a double click with the given button.
mouse.right_click()
Sends a right click with the given button.
mouse.wheel(delta=1)
Scrolls the wheel delta
clicks. Sign indicates direction.
mouse.move(x, y, absolute=True, duration=0, steps_per_second=120.0)
Moves the mouse. If absolute
, to position (x, y), otherwise move relative
to the current position. If duration
is non-zero, animates the movement.
The fps of the animation is determined by 'steps_per_second', default is 120.
mouse.drag(start_x, start_y, end_x, end_y, absolute=True, duration=0)
Holds the left mouse button, moving from start to end position, then
releases. absolute
and duration
are parameters regarding the mouse
movement.
mouse.on_button(callback, args=(), buttons=('left', 'middle', 'right', 'x', 'x2'), types=('up', 'down', 'double'))
Invokes callback
with args
when the specified event happens.
mouse.on_click(callback, args=())
Invokes callback
with args
when the left button is clicked.
mouse.on_double_click(callback, args=())
Invokes callback
with args
when the left button is double clicked.
mouse.on_right_click(callback, args=())
Invokes callback
with args
when the right button is clicked.
mouse.on_middle_click(callback, args=())
Invokes callback
with args
when the middle button is clicked.
mouse.wait(button='left', target_types=('up', 'down', 'double'))
Blocks program execution until the given button performs an event.
mouse.get_position()
Returns the (x, y) mouse position.
mouse.hook(callback)
Installs a global listener on all available mouses, invoking callback
each time it is moved, a key status changes or the wheel is spun. A mouse
event is passed as argument, with type either mouse.ButtonEvent
,
mouse.WheelEvent
or mouse.MoveEvent
.
Returns the given callback for easier development.
mouse.unhook(callback)
Removes a previously installed hook.
mouse.unhook_all()
Removes all hooks registered by this application. Note this may include
hooks installed by high level functions, such as record
.
mouse.record(button='right', target_types=('down',))
Records all mouse events until the user presses the given button.
Then returns the list of events recorded. Pairs well with play(events)
.
Note: this is a blocking function.
Note: for more details on the mouse hook and events see hook
.
mouse.play(events, speed_factor=1.0, include_clicks=True, include_moves=True, include_wheel=True)
Plays a sequence of recorded events, maintaining the relative time
intervals. If speed_factor is <= 0 then the actions are replayed as fast
as the OS allows. Pairs well with record()
.
The parameters include_*
define if events of that type should be inluded
in the replay or ignored.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for macmouse-0.7.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b79183c53b358658d8df8db2eb748395211a656cd97c5e3703406b5f7dde17cf |
|
MD5 | f99916668dac4b3fdb66def7cf745e47 |
|
BLAKE2b-256 | 3b97e7ddfac3df0d8ad113cc3e24605f9ada792f5eab128b7a0ecde45b3bcfb4 |