DOCSEARCHbyAlgolia
Submit Docs

mouse

repository·master·Indexed 21 days ago

https://github.com/boppreh/mouse

A lightweight Python library for global mouse control across Windows, Linux, and MacOS. It provides functionality to simulate mouse movements and clicks, hook global mouse events, and record and replay mouse sequences.

Tokens
1.3K
Snippets
2
Records
9
Agent score
26%

What's inside mouse

  1. Install the mouse library

    master

    You can install the mouse package via PyPI using pip. On Linux, you may need to use sudo because the library reads raw device files from /dev/input/ to avoid dependencies on X.

    $ sudo pip install mouse

    Alternatively, you can clone the repository and use the source files directly without installation:

    $ git clone https://github.com/boppreh/mouse
    $ sudo pip install mouse

  2. Record and replay mouse sequences

    master

    The library includes high-level functions to record a sequence of mouse actions and play them back later.

    • mouse.record(button='right', target_types=('down',)): A blocking function that records all mouse events until the specified button is pressed. It returns a list of recorded events.
    • mouse.play(events, speed_factor=1.0, include_clicks=True, include_moves=True, include_wheel=True): Plays back a list of events. If speed_factor is <= 0, actions are replayed as fast as the OS allows. You can filter which event types are included in the replay using the include_* flags.
    import mouse

# Record events until the right button is pressed
events = mouse.record(button='right')

# Play them back
mouse.play(events)

  3. Register specific mouse button callbacks

    master

    If you only want to react to specific button actions rather than all events, use these convenience functions:

    • mouse.on_click(callback, args=()): Invokes callback when the left button is clicked.
    • mouse.on_double_click(callback, args=()): Invokes callback when the left button is double clicked.
    • mouse.on_right_click(callback, args=()): Invokes callback when the right button is clicked.
    • mouse.on_middle_click(callback, args=()): Invokes callback when the middle button is clicked.
    • mouse.on_button(callback, args=(), buttons=('left', 'middle', 'right', 'x', 'x2'), types=('up', 'down', 'double')): A more granular way to trigger a callback based on specific buttons and event types (up, down, or double).

  4. Listen for mouse events using hooks

    master

    You can intercept global mouse events (movement, button presses, and wheel scrolls) by using mouse.hook(callback). The callback will receive an event object which is one of mouse.ButtonEvent, mouse.MoveEvent, or mouse.WheelEvent.

    To stop listening, use mouse.unhook(callback) or mouse.unhook_all() to remove all registered hooks.

    import mouse

def callback(event):
    print(event)

# Install the hook
mouse.hook(callback)

# ... do something ...

# Remove the hook
mouse.unhook_all()

  5. Simulate mouse movement and clicks

    master

    The mouse library provides several high-level functions to control the mouse cursor and simulate button actions:

    • mouse.move(x, y, absolute=True, duration=0, steps_per_second=120.0): Moves the mouse. If absolute is True, it moves to the specific (x, y) coordinate. If False, it moves relative to the current position. If duration is non-zero, the movement is animated.
    • mouse.click(button='left'): Sends a click with the specified button.
    • mouse.double_click(button='left'): Sends a double click.
    • mouse.right_click(): Sends a right click.
    • mouse.press(button='left'): Presses the button without releasing it.
    • mouse.release(button='left'): Releases the specified button.
    • mouse.wheel(delta=1): Scrolls the wheel. The sign of delta indicates the direction.
    • mouse.drag(start_x, start_y, end_x, end_y, absolute=True, duration=0): Holds the left button, moves from start to end, and then releases.
    • mouse.is_pressed(button='left'): Returns True if the button is currently pressed.
    • mouse.get_position(): Returns the current (x, y) position.
    import mouse

mouse.move(100, 100, absolute=True)
mouse.click('left')
mouse.wheel(1)
pos = mouse.get_position()

  7. WheelEvent object properties

    master

    A mouse.WheelEvent is generated when the mouse wheel is spun. It contains:

    • delta: The scroll amount.
    • time: The timestamp of the event.

    Methods available on WheelEvent:

    • count(value): Returns the number of occurrences of value.
    • index(value, start=0, stop=...): Returns the first index of value. Raises ValueError if not found.

  8. MoveEvent object properties

    master

    A mouse.MoveEvent is generated when the mouse moves. It contains:

    • x: The x-coordinate.
    • y: The y-coordinate.
    • time: The timestamp of the event.

    Methods available on MoveEvent:

    • count(value): Returns the number of occurrences of value.
    • index(value, start=0, stop=...): Returns the first index of value. Raises ValueError if not found.

  9. ButtonEvent object properties

    master

    A mouse.ButtonEvent is generated when a mouse button is pressed or released. It contains the following information:

    • event_type: The type of event (e.g., mouse.DOWN, mouse.UP, mouse.DOUBLE).
    • button: The button involved (e.g., mouse.LEFT, mouse.RIGHT, mouse.MIDDLE, mouse.X, mouse.X2).
    • time: The timestamp of the event.

    Methods available on ButtonEvent:

    • count(value): Returns the number of occurrences of value in the event sequence.
    • index(value, start=0, stop=...): Returns the first index of value. Raises ValueError if not found.