win-hotkey

win-hotkey is a lightweight and opinionated Rust crate designed for handling system-wide hotkeys on Windows. It provides an easy-to-use abstraction over the Windows API, enabling thread-safe hotkey registration and callback execution.

🚀 Features

Thread-Safe Hotkeys: Handles Windows API's single-thread limitation seamlessly.
High-Level Abstraction: Simple interface to register and manage hotkeys.
Customizable Callbacks: Assign functions or closures to execute on hotkey triggers.
Flexible Key Combination Support: Register hotkeys with:
- Modifier + Key (e.g., Alt + A)
- Modifier + Key + Additional Keys
Rust-Friendly: Uses high-level abstractions for Virtual Keys (VK_*) and Modifier Keys (MOD_*).
String-Based Keys: Create virtual keys (VirtualKey) and modifiers keys (ModifiersKey) from human-readable strings.

📖 Usage

Quick Start

Create a HotkeyManager instance.
Register a hotkey with a VirtualKey, one or more ModifiersKeys, and a callback.
Run the event loop to listen for hotkey triggers.

use win_hotkey::keys::{ModifiersKey, VirtualKey};
use win_hotkey::{HotkeyManager, HotkeyManagerImpl};

fn main() {
    let mut hkm = HotkeyManager::new();

    hkm.register(VirtualKey::A, &[ModifiersKey::Alt], || {
        println!("Hotkey ALT + A was pressed");
    })
    .unwrap();

    hkm.event_loop();
}

🧵Threading Support

The Challenge

Windows hotkey events must be registered and unregistered on the same thread. This limitation makes traditional multi-threaded hotkey management cumbersome.

The Solution

win-hotkey provides two hotkey manager implementations:

Single-Thread (single_thread::HotkeyManager)

Must remain on the same thread where it was created.
Works well for single-threaded applications.

Thread-Safe (thread_safe::HotkeyManager) (Default)

Launches a background thread to handle all hotkey-related operations.
Uses a command-receiver model, ensuring all hotkey operations run on the same thread regardless of where the API is called.

With the thread_safe feature enabled (default), the crate automatically provides the thread-safe implementation.

🔑 License

This project is licensed under the MIT License See the LICENSE file for details

win-hotkey 0.2.4