Window Enumerator

A powerful Rust library for Windows window enumeration with advanced filtering, sorting, and selection capabilities.

Why Use Window Enumerator?

user case in chinese

Features

🔍 Window Enumeration - Discover all visible windows on the system
🎯 Advanced Filtering - Filter by PID, title, class name, process name, and file path
📊 Multi-criteria Sorting - Sort by PID, title, or position with flexible ordering
🎮 Index Selection - Select specific windows using 1-based indices or ranges
🛡️ Safe API - Memory-safe wrapper around Windows API
⚡ Zero-cost Abstractions - Efficient Rust implementation

Installation

Add this to your Cargo.toml:

[dependencies]
window-enumerator = "0.4"

Or with specific features:

[dependencies]
window-enumerator = { version = "0.4", features = ["sorting", "selection"] }

Quick Start

use window_enumerator::{WindowEnumerator, FilterCriteria};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create enumerator and enumerate windows
    let mut enumerator = WindowEnumerator::new();
    enumerator.enumerate_all_windows()?;
    
    // Print all windows in a formatted table
    enumerator.print_windows_with_indices();
    
    // Find Chrome windows
    let chrome_windows = enumerator.find_by_title("Chrome");
    println!("Found {} Chrome windows:", chrome_windows.len());
    for window in chrome_windows {
        window.print_compact();
    }
    
    Ok(())
}

Usage Examples

Basic Enumeration

use window_enumerator::WindowEnumerator;

let mut enumerator = WindowEnumerator::new();
enumerator.enumerate_all_windows()?;

// Get all windows
let windows = enumerator.get_windows();
println!("Total windows: {}", windows.len());

// Access window by index (1-based)
if let Some(window) = enumerator.get_window_by_index(1) {
    println!("First window: {}", window.title);
}

Advanced Filtering

use window_enumerator::{WindowEnumerator, FilterCriteria};

let mut enumerator = WindowEnumerator::new();
enumerator.enumerate_all_windows()?;

// Filter by multiple criteria
let criteria = FilterCriteria {
    pid: Some(1234),
    title_contains: Some("Notepad".to_string()),
    process_name_contains: Some("notepad.exe".to_string()),
    ..Default::default()
};

let filtered = enumerator.filter_windows(&criteria);
println!("Found {} matching windows", filtered.len());

Sorting (requires `sorting` feature)

use window_enumerator::{WindowEnumerator, SortCriteria, utils};

let mut enumerator = WindowEnumerator::new();
enumerator.enumerate_all_windows()?;

// Sort by PID ascending, then title descending
let sort_criteria = SortCriteria {
    pid: 1,    // Ascending
    title: -1, // Descending
    ..Default::default()
};

let sorted = enumerator.filter_and_sort_windows(&Default::default(), &sort_criteria);

// Sort by position (X then Y coordinates)
let position_sort = utils::parse_position_sort("x1|y1")?;
let pos_sort_criteria = SortCriteria {
    position: position_sort,
    ..Default::default()
};
let position_sorted = enumerator.filter_and_sort_windows(&Default::default(), &pos_sort_criteria);

Selection (requires `selection` feature)

use window_enumerator::{WindowEnumerator, utils};

let mut enumerator = WindowEnumerator::new();
enumerator.enumerate_all_windows()?;

// Select specific indices
let selection = utils::parse_selection("1,3,5")?;
let selected = enumerator.filter_windows_with_selection(&Default::default(), &selection);

// Select range
let range_selection = utils::parse_selection("1-5")?;
let range_selected = enumerator.filter_windows_with_selection(&Default::default(), &range_selection);

// Mixed selection
let mixed_selection = utils::parse_selection("1,3-5,7")?;
let mixed_selected = enumerator.filter_windows_with_selection(&Default::default(), &mixed_selection);

Combined Filtering, Sorting and Selection

use window_enumerator::{WindowEnumerator, FilterCriteria, SortCriteria, utils};

let mut enumerator = WindowEnumerator::new();
enumerator.enumerate_all_windows()?;

let criteria = FilterCriteria {
    title_contains: Some("Microsoft".to_string()),
    ..Default::default()
};

let sort_criteria = SortCriteria {
    pid: 1,
    ..Default::default()
};

let selection = utils::parse_selection("1-10")?;

let results = enumerator.filter_sort_windows_with_selection(
    &criteria,
    &sort_criteria,
    &selection
);

println!("Found {} results", results.len());

API Overview

Main Types

WindowEnumerator - Main entry point for window operations
WindowInfo - Detailed information about a window
FilterCriteria - Criteria for filtering windows
SortCriteria - Criteria for sorting windows (with sorting feature)
Selection - Window selection specification (with selection feature)

Key Methods

enumerate_all_windows() - Discovers all visible windows
filter_windows() - Filters windows based on criteria
filter_and_sort_windows() - Filters and sorts windows
filter_windows_with_selection() - Filters and selects windows
print_windows_with_indices() - Displays windows in a formatted table

Utility Functions

parse_selection() - Parses selection strings ("all", "1,2,3", "1-3")
parse_position_sort() - Parses position sort strings ("x1", "y-1", "x1|y1")

Cargo Features

sorting - Enables window sorting capabilities (enabled by default)
selection - Enables window selection by indices (enabled by default)

Platform Support

⚠️ Windows Only

This crate is specifically designed for Windows and uses Windows-specific APIs. It will not compile on other platforms.

Error Handling

All operations return window_enumerator::Result<T> which can contain various WindowError variants:

use window_enumerator::{WindowEnumerator, WindowError};

let mut enumerator = WindowEnumerator::new();
match enumerator.enumerate_all_windows() {
    Ok(()) => println!("Enumeration successful"),
    Err(WindowError::WindowsApiError(code)) => {
        eprintln!("Windows API error: 0x{:08x}", code);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Performance Notes

Window enumeration is performed on-demand when enumerate_all_windows() is called
Filtering and sorting operations work on the pre-enumerated list for efficiency
The library uses zero-cost abstractions where possible

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.

window-enumerator 0.4.1