Handling the mouse

The package pynput.mouse contains classes for controlling and monitoring the mouse.

Controlling the mouse

Use pynput.mouse.Controller like this:

from pynput.mouse import Button, Controller

mouse = Controller()

# Read pointer position
print('The current pointer position is {0}'.format(
    mouse.position))

# Set pointer position
mouse.position = (10, 20)
print('Now we have moved it to {0}'.format(
    mouse.position))

# Move pointer relative to current position
mouse.move(5, -5)

# Press and release
mouse.press(Button.left)
mouse.release(Button.left)

# Double click; this is different from pressing and releasing
# twice on Mac OSX
mouse.click(Button.left, 2)

# Scroll two steps down
mouse.scroll(0, 2)

Monitoring the mouse

Use pynput.mouse.Listener like this:

from pynput.mouse import Listener

def on_move(x, y):
    print('Pointer moved to {0}'.format(
        (x, y)))

def on_click(x, y, button, pressed):
    print('{0} at {1}'.format(
        'Pressed' if pressed else 'Released',
        (x, y)))
    if not pressed:
        # Stop listener
        return False

def on_scroll(x, y, dx, dy):
    print('Scrolled {0}'.format(
        (x, y)))

# Collect events until released
with Listener(
        on_move=on_move,
        on_click=on_click,
        on_scroll=on_scroll) as listener:
    listener.join()

A mouse listener is a threading.Thread, and all callbacks will be invoked from the thread.

Call pynput.mouse.Listener.stop from anywhere, or raise pynput.mouse.Listener.StopException or return False from a callback to stop the listener.

On Windows, virtual events sent by other processes may not be received. This library takes precautions, however, to dispatch any virtual events generated to all currently running listeners of the current process.

Reference

class pynput.mouse.Controller

A controller for sending virtual mouse events to the system.

click(button, count=1)

Emits a button click event at the current position.

The default implementation sends a series of press and release events.

Parameters:

• button (Button) – The button to click.
• count (int) – The number of clicks to send.

move(dx, dy)

Moves the mouse pointer a number of pixels from its current position.

Parameters:

• x (int) – The horizontal offset.
• dy (int) – The vertical offset.

position

The current position of the mouse pointer.

This is the tuple (x, y), and setting it will move the pointer.

press(button)

Emits a button press event at the current position.

Parameters:button (Button) – The button to press.

release(button)

Emits a button release event at the current position.

Parameters:button (Button) – The button to release.

scroll(dx, dy)

Sends scroll events.

Parameters:

• dx (int) – The horizontal scroll. The units of scrolling is undefined.
• dy (int) – The vertical scroll. The units of scrolling is undefined.

class pynput.mouse.Listener(on_move=None, on_click=None, on_scroll=None)

A listener for mouse events.

Instances of this class can be used as context managers. This is equivalent to the following code:

listener.start()
try:
    with_statements()
finally:
    listener.stop()

This class inherits from threading.Thread and supports all its methods. It will set daemon to True when created.

Parameters:

• on_move (callable) –

  The callback to call when mouse move events occur.

  It will be called with the arguments (x, y), which is the new pointer position. If this callback raises StopException or returns False, the listener is stopped.

• on_click (callable) –

  The callback to call when a mouse button is clicked.

  It will be called with the arguments (x, y, button, pressed), where (x, y) is the new pointer position, button is one of the Button values and pressed is whether the button was pressed.

  If this callback raises StopException or returns False, the listener is stopped.

• on_scroll (callable) –

  The callback to call when mouse scroll events occur.

  It will be called with the arguments (x, y, dx, dy), where (x, y) is the new pointer position, and (dx, dy) is the scroll vector.

  If this callback raises StopException or returns False, the listener is stopped.

running

Whether the listener is currently running.

start()

Start the thread’s activity.

It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

This method will raise a RuntimeError if called more than once on the same thread object.

stop()

Stops listening for mouse events.

When this method returns, no more events will be delivered.

wait()

Waits for this listener to become ready.