Metadata-Version: 2.1
Name: mouse-anywhere
Version: 0.2.5
Summary: A Python package for smooth mouse movement using a C library.
Home-page: https://github.com/wuhplaptop/mouse-anywhere
Author: wuhp
Author-email: wuhp@gmail.com
Project-URL: Bug Reports, https://github.com/wuhplaptop/mouse-anywhere/issues
Project-URL: Source, https://github.com/wuhplaptop/mouse-anywhere
Project-URL: Documentation, https://github.com/wuhplaptop/mouse-anywhere/wiki
Keywords: mouse automation cursor movement DLL
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: dev


Mouse Anywhere Library
=

Overview
--------
Mouse Anywhere is a Python library powered by a DLL for dynamic mouse control on Windows. This library allows you to:
- Move the cursor to any absolute position on the screen.
- Simulate mouse clicks (left, right, middle).
- Perform smooth cursor movements with customizable easing types.
- Dynamically update configuration settings.
- Log mouse interactions at different levels (error, info, debug).

This package is suitable for applications requiring precise mouse control, such as automated testing, custom accessibility solutions, or macro creation.

====================================

Features
--------
- **Cursor Control:** Move the cursor to specified screen coordinates.
- **Mouse Clicks:** Simulate mouse clicks with configurable hold times.
- **Smooth Movements:** Enable smooth cursor movements with easing types like linear, quadratic, sinusoidal, cubic, and exponential.
- **Presets:** Apply predefined configurations for fast, smooth, or default behavior.
- **Logging:** Monitor mouse interactions with adjustable log levels.

====================================

Installation
------------
Install the library using pip:

    pip install mouse-anywhere

====================================

Getting Started
---------------
### Initialization
To use the library, initialize it first:

    from mouse_anywhere import initialize, mouse_shutdown

    # Initialize the library
    initialize()

    # Shutdown the library (when done)
    mouse_shutdown()

### Example Usage

#### Moving the Cursor
    from mouse_anywhere import set_cursor_abs

    # Move the cursor to screen coordinates (100, 200)
    set_cursor_abs(100, 200)

#### Simulating Mouse Clicks
    from mouse_anywhere import click

    # Perform a left mouse click
    click(1)

    # Perform a right mouse click
    click(2)

#### Smooth Movement
    from mouse_anywhere import hold_and_move

    # Hold the left mouse button and move to (300, 400) over 2 seconds
    hold_and_move(300, 400, 1, 2000)

#### Applying Presets
    from mouse_anywhere import apply_preset

    # Apply the "smooth" preset
    apply_preset(3)

#### Custom Configurations
    from mouse_anywhere import set_config

    # Set custom configurations
    set_config(
        strength=70,        # Strength (1-100)
        hold_time_ms=500,   # Hold time in milliseconds
        mouse_speed=10,     # Movement speed in ms per step
        easing_type=2,      # Easing type (1-5)
        smooth_movement=True
    )

#### Adjust Logging Level
    from mouse_anywhere import set_logging_level

    # Set logging to debug level
    set_logging_level(3)

====================================

Configuration Details
----------------------
### Easing Types
Easing types control the smoothness of cursor movement:
- **Linear:** 1
- **Quadratic:** 2
- **Sinusoidal:** 3
- **Cubic:** 4
- **Exponential:** 5

### Presets
Presets offer predefined configurations:
- **Default:** Strength=50, Hold Time=300ms, Speed=5, Easing=Linear
- **Fast:** Strength=80, Hold Time=100ms, Speed=2, Easing=Exponential
- **Smooth:** Strength=30, Hold Time=500ms, Speed=10, Easing=Sinusoidal

### Logging Levels
Control the verbosity of logs:
- **None:** 0 (No logging)
- **Error:** 1 (Log errors only)
- **Info:** 2 (Log informational messages)
- **Debug:** 3 (Log detailed debug messages)

====================================

DLL Integration
---------------
The library uses `mouse_anywhere2.dll` for low-level mouse control. Ensure the DLL is packaged with the library and accessible in the Python module directory.

If you encounter issues:
1. Verify the DLL is present in the installed package directory.
2. Confirm your system is running a compatible version of Windows.

### DLL Methods
Below are the exported methods from the DLL:

- **initialize():** Initializes the mouse library.
- **mouse_shutdown():** Shuts down the library and cleans up resources.
- **set_cursor_abs(x, y):** Moves the cursor to absolute screen coordinates.
- **click(button):** Simulates a mouse click. Acceptable values for `button`:
    - 1: Left click
    - 2: Right click
    - 3: Middle click
- **hold_and_move(x, y, button, duration_ms):** Holds the specified button and moves the cursor to the specified coordinates over the given duration.
- **set_mouse_speed(speed):** Sets the speed for cursor movement. Speed must be greater than 0.
- **set_config(strength, hold_time_ms, mouse_speed, easing_type, smooth_movement):** Dynamically updates the library configuration with detailed parameters.
- **apply_preset(preset_type):** Applies predefined configurations (1: Default, 2: Fast, 3: Smooth).
- **set_logging_level(level):** Adjusts the logging verbosity (0: None, 1: Error, 2: Info, 3: Debug).

====================================

Troubleshooting
---------------
### Common Errors
- **FileNotFoundError:** Ensure the DLL is correctly installed and accessible.
- **ValueError:** Check the input parameters for invalid values.

### Debugging Steps
1. Enable debug logging with `set_logging_level(3)`.
2. Check the log file (`mouse_movement.log`) for detailed information.
3. Use the `initialize()` method to verify proper setup.

