win-hotkeys

Crates.iowin-hotkeys
lib.rswin-hotkeys
version
sourcesrc
created_at2024-12-27 20:57:08.309541
updated_at2025-02-02 02:19:51.512822
descriptionA lightweight, thread-safe rust library for system-wide hotkey management on Windows
homepagehttps://github.com/iholston/win-hotkeys
repositoryhttps://github.com/iholston/win-hotkeys
max_upload_size
id1496646
Cargo.toml error:TOML parse error at line 17, column 1 | 17 | autolib = false | ^^^^^^^ unknown field `autolib`, expected one of `name`, `version`, `edition`, `authors`, `description`, `readme`, `license`, `repository`, `homepage`, `documentation`, `build`, `resolver`, `links`, `default-run`, `default_dash_run`, `rust-version`, `rust_dash_version`, `rust_version`, `license-file`, `license_dash_file`, `license_file`, `licenseFile`, `license_capital_file`, `forced-target`, `forced_dash_target`, `autobins`, `autotests`, `autoexamples`, `autobenches`, `publish`, `metadata`, `keywords`, `categories`, `exclude`, `include`
size0
Isaac Holston (iholston)

documentation

https://docs.rs/win-hotkeys

README

win-hotkeys

Crates.io License Documentation

A lightweight, thread-safe Rust library for managing system-wide hotkeys on Windows

The win-hotkeys crate simplifies hotkey management on Windows by abstracting interactions with the Windows API. It leverages the WH_KEYBOARD_LL low-level keyboard hook to provide a robust and flexible solution for global hotkeys, including full support for the WIN key as a modifier.

[dependencies]
win-hotkeys = "0.4.2"

Features

  • Thread Safe: Built with safety in mind, ensuring reliable operation across multiple threads.
  • Easy Hotkey Management: Simple process of creating, registering, and managing hotkeys.
  • Flexible Key Combinations: Register any set of keys (single or multiple) as a hotkey including the WIN key.
  • Rust Callbacks and Closures: Assign Rust functions or closures to run when a hotkey is triggered.
  • Human-Readable Key Names: Create VKey instances from intuitive string representations.
  • Efficient Performance: Optimized to handle hotkey events with minimal overhead.

Usage

use win_hotkeys::HotkeyManager;
use win_hotkeys::VKey;

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

    hkm.register_hotkey(VKey::A, &[VKey::from_keyname("ctrl").unwrap()], || {
        println!("Hotkey CTRL + A was pressed");
    }).unwrap();

    hkm.register_hotkey(VKey::B, &[VKey::LWin, VKey::Shift], || {
        println!("Hotkey WIN + SHIFT + B was pressed");
    }).unwrap();

    hkm.event_loop();
}

Virtual Keys

The VKey enum in this library is based on the Microsoft Virtual-Key Codes, which define key codes for a wide range of keyboard keys. This provides a comprehensive and standardized set of keys that can be used to define hotkeys.

A small list of common alias names are also supported:

  • Ctrl: Control(VK_CONTROL)
  • LCtrl : LControl(VK_LCONTROL)
  • RCtrl: RControl(VK_RCONTROL)
  • Alt: Menu(VK_MENU)
  • LAlt: LMenu(VK_LMENU)
  • RAlt: RMenu(VK_RMENU)
  • Win: LWin(VK_LWIN)

For keys that have distinct left and right versions, the default key will work with either key when used as a modifier. For example, using Shift as a modifier will trigger the hotkey when either LShift or RShift is pressed, but if used as a trigger key it will only respond if Shift is pressed (which is not present on most keyboards).

use win_hotkeys::HotkeyManager;
use win_hotkeys::VKey;

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

    let key1 = VKey::from_keyname("VK_MENU").unwrap(); // Official name
    let key2 = VKey::from_keyname("alt").unwrap();     // Alias for VK_MENU
    let key3 = VKey::from_keyname("MENU").unwrap();    // Omitted VK_

    assert_eq!(key1, key2);
    assert_eq!(key1, key3);

    hkm.register_hotkey(VKey::A, &[key1, VKey::Shift], || {
        println!("Hotkey ALT + SHIFT (LSHIFT or RSHIFT) + A was pressed");
    }).unwrap();

    hkm.register_hotkey(VKey::B, &[VKey::LShift], || {
        println!("Hotkey LSHIFT + B was pressed"); // will not trigger on RSHIFT + B
    }).unwrap();

    hkm.event_loop();
}

Examples

Up-to-date examples can always be found in the examples directory

License

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

Commit count: 44

cargo fmt