Metadata-Version: 2.4
Name: bgautogui
Version: 0.1.0
Summary: Windows background mouse automation using Win32 window messages.
Author: HaiDuong
License-Expression: MIT
Project-URL: Homepage, https://github.com/Hiroshimeow/bgautogui
Project-URL: Repository, https://github.com/Hiroshimeow/bgautogui
Project-URL: Issues, https://github.com/Hiroshimeow/bgautogui/issues
Keywords: windows,automation,mouse,win32,background-click,ctypes
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: vision
Requires-Dist: mss>=9; extra == "vision"
Requires-Dist: Pillow>=10; extra == "vision"
Requires-Dist: pyautogui>=0.9.54; extra == "vision"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# bgautogui

`bgautogui` is a small Windows-only Python package for background mouse automation using Win32 window messages.

It provides a PyAutoGUI-like API for sending click and scroll messages to windows under a screen coordinate, without moving the physical mouse cursor.

> Status: alpha. This package is useful for local desktop automation and testing, but some applications may ignore posted Win32 messages.

## Features

- Windows background click without moving the real cursor.
- Screen-coordinate based API: `click(x, y)`, `scroll(clicks, x, y)`.
- Multiple target modes: first N window candidates, specific candidate indices, or specific Win32 class names.
- Optional visual click ring for debugging coordinates.
- No required runtime dependencies outside the Python standard library.
- Optional `vision` extra for screenshot/image-detection workflows.

## Installation

After publishing to PyPI:

```powershell
pip install bgautogui
```

With optional vision dependencies:

```powershell
pip install "bgautogui[vision]"
```

For local editable development:

```powershell
pip install -e .
```

or with `uv`:

```powershell
uv pip install -e .
```

## Quick start

```python
from bgautogui import BackgroundAutoGUI

bg = BackgroundAutoGUI()

# Click at the current cursor position.
bg.click()

# Click at a fixed screen coordinate.
bg.click(1500, 300)

# Scroll down at a fixed screen coordinate.
bg.scroll(-3, 1500, 300)
```

By default, `BackgroundAutoGUI()` sends each logical click to the first 4 window candidates under the coordinate.

```python
bg = BackgroundAutoGUI(max_targets=4)
```

## Target modes

```python
# Default: first 4 candidates
bg = BackgroundAutoGUI()

# Only candidate 1
bg = BackgroundAutoGUI(max_targets=1)

# Specific candidate indices, 1-based
bg = BackgroundAutoGUI(target_indices=[1, 3])

# Specific Win32 class names
bg = BackgroundAutoGUI(target_classes=["IHWindowClass"])
```

Examples that may be useful depending on the application:

```python
# Remote Desktop Connection input window, depending on environment.
BackgroundAutoGUI(target_classes=["IHWindowClass"])

# Chrome/Edge web content, depending on environment.
BackgroundAutoGUI(target_classes=["Chrome_RenderWidgetHostHWND"])

# Excel worksheet area, depending on environment.
BackgroundAutoGUI(target_classes=["EXCEL7"])
```

## Visual click ring

Visual effects are disabled by default. Enable a small ring at the clicked coordinate:

```python
bg = BackgroundAutoGUI(show_click_effect=True)
bg.click()
```

Enable it for a single click:

```python
bg = BackgroundAutoGUI()
bg.click(show_click_effect=True)
```

Show the ring without sending any click message:

```python
bg.showClickEffect()
bg.showClickEffect(1500, 300)
```

Customize the ring:

```python
bg = BackgroundAutoGUI(
    show_click_effect=True,
    click_effect_radius=22,
    click_effect_duration=0.4,
    click_effect_color="#00AEEF",
    click_effect_width=3,
)
```

## API overview

```python
bg.position()
bg.size()
bg.center()
bg.virtual_screen()

bg.click()
bg.doubleClick()
bg.rightClick()
bg.middleClick()
bg.mouseDown()
bg.mouseUp()
bg.scroll()

bg.candidateWindowInfo()
bg.targetWindowInfo()
bg.windowInfo()
bg.probe()

bg.isPressed()
bg.is_mouse_button_held()

bg.set_click_effect()
bg.showClickEffect()
```

## Inspecting candidates

```python
from bgautogui import BackgroundAutoGUI

bg = BackgroundAutoGUI()

for info in bg.candidateWindowInfo():
    print(info.index, info.hwnd, info.class_name, info.title)
```

Debug by clicking each candidate one by one:

```python
bg.probe(delay=2)
```

## Low-interference configuration

```python
from bgautogui import BackgroundAutoGUI

bg = BackgroundAutoGUI(
    target_indices=[1],
    show_click_effect=False,
    verbose=False,
    skip_when_mouse_button_held=True,
    hover_delay=0,
    mouse_down_up_delay=0.01,
)
```

## Notes and limitations

`bgautogui` uses posted Win32 messages. A successful `PostMessageW` call does not guarantee that the target application will perform the UI action.

It may not work with:

- games and anti-cheat protected applications;
- some UWP/WinUI/custom-rendered applications;
- minimized windows;
- applications running as administrator when Python is not elevated;
- applications that ignore posted Win32 mouse messages.

`bgautogui` intentionally does not provide `moveTo()` or reliable background drag support. It is designed to avoid moving the physical cursor.

## Responsible use

This package is intended for legitimate local desktop automation and testing. Do not use it to bypass access controls, anti-cheat systems, user consent, or software terms of service.

## License

MIT License. See [LICENSE](LICENSE).
