Examples

This page provides practical code examples for common WindMouse usage patterns.

Basic Movement

PyAutoGUI (Cross-Platform)

from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

# Create controller with default parameters
mouse = PyautoguiMouseController()

# Move to target
mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target()

AutoHotkey (Windows)

from ahk import AHK
from windmouse.ahk_controller import AHKMouseController
from windmouse import Coordinate

# Initialize AHK
ahk = AHK()

# Create controller
mouse = AHKMouseController(ahk)

# Move to target
mouse.dest_position = (Coordinate(1920), Coordinate(1080))
mouse.move_to_target()

Custom Physics Parameters

from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

# Customize physics parameters
mouse = PyautoguiMouseController(
    gravity_magnitude=9,    # Attraction strength
    wind_magnitude=3,       # Curvature amount
    max_step=15,            # Maximum speed
    damped_distance=12      # Slowdown distance
)

mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target()

Changing Destination On-The-Fly

You can dynamically change the destination during movement by setting a new target between ticks. When you change dest_position, the algorithm recalculates the path and smoothly redirects to the new target.

import time
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

mouse = PyautoguiMouseController()

# Start with initial target
mouse.dest_position = (Coordinate(800), Coordinate(600))

step_count = 0
while mouse.tick(step_duration=0.1):
    step_count += 1
    time.sleep(0.01)

    # Change destination after 10 steps
    if step_count == 10:
        print("Redirecting to new target!")
        mouse.dest_position = (Coordinate(400), Coordinate(300))

    # Or change based on external condition
    # if target_moved:
    #     mouse.dest_position = get_new_target_position()

    # Can stop early if needed
    if should_abort:
        break

print(f"Movement completed in {step_count} steps")

Note: Setting a new dest_position regenerates the internal path generator, so the mouse will smoothly transition to the new target from its current position.

This technique is useful for:

• Reactive movements - responding to changing targets

• Following moving objects - tracking dynamic positions

• Adaptive behavior - adjusting path based on conditions

• Emergency stops - breaking out of movement early

Drag and Drop

from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate, HoldMouseButton

mouse = PyautoguiMouseController()

# Move to source position
mouse.dest_position = (Coordinate(300), Coordinate(300))
mouse.move_to_target()

# Drag to destination with left button held
mouse.dest_position = (Coordinate(700), Coordinate(500))
mouse.move_to_target(hold_button=HoldMouseButton.LEFT)

Sequential Movements

import time
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

mouse = PyautoguiMouseController()

# Define waypoints
waypoints = [
    (Coordinate(200), Coordinate(200)),
    (Coordinate(600), Coordinate(200)),
    (Coordinate(600), Coordinate(600)),
    (Coordinate(200), Coordinate(600)),
]

# Move through each waypoint
for dest in waypoints:
    mouse.dest_position = dest
    mouse.move_to_target(tick_delay=0.005)
    time.sleep(0.3)  # Pause at each waypoint

Movement Speed Control

Fast Movement

from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

mouse = PyautoguiMouseController(
    gravity_magnitude=12,   # Strong attraction
    wind_magnitude=1,       # Minimal curvature
    max_step=20             # High speed
)

mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target(tick_delay=0, step_duration=0.05)

Natural Movement

mouse = PyautoguiMouseController()  # Default parameters

mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target(tick_delay=0.005, step_duration=0.1)

Slow Movement

mouse = PyautoguiMouseController(
    max_step=8,             # Lower speed
    damped_distance=25      # Early slowdown
)

mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target(tick_delay=0.01, step_duration=0.2)

Manual Control with Tick

import time
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

mouse = PyautoguiMouseController()
mouse.dest_position = (Coordinate(800), Coordinate(600))

# Manual control loop
while mouse.tick(step_duration=0.1):
    time.sleep(0.01)

    # Perform custom logic between steps
    current_pos = pyautogui.position()
    print(f"Current position: {current_pos}")

    # Can break early based on conditions
    if some_condition:
        break

Error Handling

from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

try:
    mouse = PyautoguiMouseController()
    mouse.dest_position = (Coordinate(800), Coordinate(600))
    mouse.move_to_target()
except ValueError as e:
    print(f"Configuration error: {e}")
except ImportError as e:
    print(f"Missing dependency: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Random Offset for Natural Variation

import random
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

def click_with_offset(base_x: int, base_y: int, offset: int = 5):
    """Click with slight random offset for more natural behavior."""
    mouse = PyautoguiMouseController()

    # Add random offset
    dest_x = Coordinate(base_x + random.randint(-offset, offset))
    dest_y = Coordinate(base_y + random.randint(-offset, offset))

    mouse.dest_position = (dest_x, dest_y)
    mouse.move_to_target(tick_delay=0.003)

# Usage
click_with_offset(800, 600)

Reusing Controllers

from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

# Create once
mouse = PyautoguiMouseController()

# Reuse for multiple movements
destinations = [
    (Coordinate(100), Coordinate(100)),
    (Coordinate(500), Coordinate(500)),
    (Coordinate(900), Coordinate(300)),
]

for dest in destinations:
    mouse.dest_position = dest
    mouse.move_to_target()

Resource Management (AHK)

from ahk import AHK
from windmouse.ahk_controller import AHKMouseController
from windmouse import Coordinate

# Create AHK instance once
ahk = AHK()

# Reuse for multiple controllers
mouse1 = AHKMouseController(ahk)
mouse2 = AHKMouseController(ahk)

# Use different controllers
mouse1.dest_position = (Coordinate(100), Coordinate(100))
mouse1.move_to_target()

mouse2.dest_position = (Coordinate(500), Coordinate(500))
mouse2.move_to_target()

See Also

• Usage Guide - Comprehensive usage guide with explanations

• API Reference - API reference documentation

• Quick Reference - Quick reference for common operations

• Algorithm Explained - Algorithm explanation and parameter effects