focus-tracker

A cross-platform focus tracker for Linux (X11), macOS, and Windows that monitors window focus changes and provides detailed information about the currently focused window.

Features

• Cross-platform support (Linux X11, macOS, Windows)
• Real-time focus tracking
• Window information (title, process name, PID)
• Icon extraction with configurable sizes
• Sync and async APIs
• Configurable polling intervals
• Graceful shutdown with stop signals

Installation

Add to your Cargo.toml:

[dependencies]
focus-tracker = "*"

For async support:

[dependencies]
focus-tracker = { version = "*", features = ["async"] }
tokio = { version = "1", features = ["full"] }

Quick Start - Channel-Based

Subscribe to focus changes and receive them via a channel:

use focus_tracker::subscribe_focus_changes;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let receiver = subscribe_focus_changes()?;

    while let Ok(window) = receiver.recv() {
        println!("Focused: {}",
            window.window_title.as_deref().unwrap_or("Unknown"));

        if let Some(process) = &window.process_name {
            println!("Process: {}", process);
        }
    }

    Ok(())
}

Async Usage

For async/await workflows, use the async API with tokio:

use focus_tracker::FocusTracker;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tracker = FocusTracker::new();
    let stop_signal = Arc::new(AtomicBool::new(false));

    tracker.track_focus_async_with_stop(
        |window| async move {
            println!("Focused: {}",
                window.window_title.as_deref().unwrap_or("Unknown"));

            // Perform async operations here
            some_async_function().await?;

            Ok(())
        },
        &stop_signal,
    ).await?;

    Ok(())
}

Configuration

Customize behavior with FocusTrackerConfig:

use focus_tracker::{FocusTracker, FocusTrackerConfig, IconConfig};

let config = FocusTrackerConfig::new()
    .with_poll_interval_ms(50)           // Faster polling (default: 100ms)
    .with_icon_config(
        IconConfig::new().with_size(128) // Custom icon size
    );

let tracker = FocusTracker::with_config(config);

Examples

Run the included examples:

# Channel-based focus tracking
cargo run --example basic

# Async focus tracking (requires async feature)
cargo run --example async --features async

# Advanced example with icon saving and statistics
cargo run --example advanced

Platform Support

Platform Notes

• Linux X11: Full support
• Linux Wayland: Not supported (technical limitations)
• macOS: Requires accessibility permissions
• Windows: Full support on Windows 7+

System Requirements

macOS

Accessibility permissions required. Grant in: System Preferences > Security & Privacy > Accessibility

Linux

X11 development libraries required (pre-installed on most distributions)

Windows

No additional requirements

API Documentation

For detailed API documentation, visit docs.rs/focus-tracker.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.