# ScreenshotTools Usage Guide

The ScreenshotTools module provides reliable screenshot capture capabilities using PIL.ImageGrab for cross-platform image capture without complex automation dependencies.

## ✅ Security Notice

ScreenshotTools include only **SAFE** operations that are read-only and cannot modify the user's system:

- **SAFE Tools**: Screenshot capture, clipboard image capture, screen info (always available)
- **No Destructive Operations**: Removed all keyboard, mouse, and dialog automation for security
- **Reliable Dependencies**: Uses maintained PIL.ImageGrab instead of unmaintained pyautogui

## Available Tools

### 📸 Screenshot Capture (SAFE)
```python
# Take a full screenshot
screenshot_take_screenshot(save_path="/tmp/screenshot.png", format="PNG")

# Take a region screenshot
screenshot_take_screenshot(bbox=[100, 100, 800, 600], return_base64=True)

# Capture image from clipboard
screenshot_capture_clipboard(save_path="/tmp/clipboard.png", format="PNG")

# Get screen information
screenshot_get_screen_info()
```




## 🛡️ Safety Features

### ✅ Safe by Design
```python
# All tools are SAFE - no destructive operations available
# No enablement required - tools work immediately
screenshot_take_screenshot(save_path="/tmp/screenshot.png")

# Graceful error handling for unsupported environments
result = screenshot_capture_clipboard()
if not result.get('success'):
    print(f"Clipboard not available: {result.get('error')}")
```

## 🔧 Bulk Operations Integration

ScreenshotTools are integrated with BulkToolCaller for workflow automation:

```python
# Create a screenshot workflow
bulk_operations_create_bulk_workflow(
    name="Screenshot Workflow",
    description="Take multiple screenshots and analyze",
    operations=[
        {
            "tool_name": "screenshot_take_screenshot",
            "arguments": {"save_path": "/tmp/screen1.png"},
            "description": "Take full screenshot"
        },
        {
            "tool_name": "screenshot_get_screen_info",
            "arguments": {},
            "description": "Get screen information"
        },
        {
            "tool_name": "screenshot_capture_clipboard",
            "arguments": {"save_path": "/tmp/clipboard.png"},
            "description": "Capture clipboard image"
        }
    ],
    mode="sequential"
)
```

## 🖥️ Environment Requirements

- **GUI Environment**: Requires active display (X11 on Linux, native on Windows/macOS)
- **Headless Systems**: Tools gracefully degrade with informative error messages
- **Dependencies**: Only PIL/Pillow (lightweight and maintained)
- **Clipboard**: Linux requires wl-paste or xclip for clipboard image capture

## 🎯 Use Cases

1. **Documentation**: Capture workflow screenshots, create tutorials
2. **System Monitoring**: Periodic screen captures for debugging
3. **Visual Debugging**: Capture screenshots at specific points
4. **Content Creation**: Automated screenshot capture for demos
5. **Clipboard Integration**: Capture and process clipboard images

## 🔍 Example: Screenshot Capture Workflow

```python
# 1. Take full screenshot
result = screenshot_take_screenshot(save_path="/tmp/fullscreen.png", return_base64=True)

# 2. Take region screenshot
region_result = screenshot_take_screenshot(
    bbox=[100, 100, 800, 600],
    save_path="/tmp/region.png"
)

# 3. Get screen information for context
screen_info = screenshot_get_screen_info()

# 4. Try to capture clipboard image
clipboard_result = screenshot_capture_clipboard(save_path="/tmp/clipboard.png")

# 5. Process results
if result.get('success'):
    print(f"Screenshot captured: {result['size']} pixels")
if clipboard_result.get('success'):
    print(f"Clipboard image captured: {clipboard_result['size']}")
else:
    print(f"Clipboard capture: {clipboard_result.get('error')}")
```

The ScreenshotTools provide reliable screenshot capture capabilities using modern, maintained dependencies with built-in safety through read-only operations.