Skip to content

A lightweight, threadsafe and ergonomic rust crate to handle system-wide hotkeys on windows

License

Notifications You must be signed in to change notification settings

dnlmlr/windows-hotkeys

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Windows Hotkeys

Crates.io Crates.io Docs.rs

An opinionated, lightweight crate to handle system-wide hotkeys on windows

The windows-hotkeys crate abstracts and handles all interactions with the winapi, including registering hotkeys and handling the events and providing threadsafe access. A hotkey manager instance is used to register key combinations together with easy callbacks.

Features

  • Usable over multiple threads, bypassing the WinAPI same-thread requirements for the hotkey API
  • Full highlevel abstraction over the winapi functions and events
  • Easy to use
  • Register hotkeys with Key + Modifier
  • Register hotkeys with Key + Modifier and require additional keys to be pressed at the same time
  • Set rust callback functions or closures that are executed on hotkey trigger
  • High level rust abstractions over the Virtual Keys (VK_* constants) and Modifier Keys (MOD_* constants)
  • Create VKeys (Virtual Keys) and ModKeys (Modifier Keys) from key name strings

How to use

  1. Create a HotkeyManager instance
  2. Register a hokey by specifying a VKey and one or more ModKeys, together with a callback
  3. Run the event loop to react to the incomming hotkey triggers
use windows_hotkeys::keys::{ModKey, VKey};
use windows_hotkeys::{HotkeyManager, HotkeyManagerImpl};

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

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

    hkm.event_loop();
}

Threading

Due to limitations in the windows API, hotkey events can only be received and unregistered on the same thread as they were initially registered. This means that a normal singlethreaded::HotkeyManager instance can't be moved between threads.

Using the windows-hotkeys singlethreaded API with multithreading is still possible, but the singlethreaded::HotkeyManager must be created and used on the same thread.

However by the default enabled threadsafe feature add the threadsafe::HotkeyManager implementation which solved this issue and provides the default HotkeyManager implementation.

This is done by launching a background thread when a threadsafe::HotkeyManager is instantiated that is listening for commands on a channel receiver. There is one command for each of the HotkeyManager functions and upon receiving a command, the matching function is called from that same thread. The threadsafe::HotkeyManager is nothing more than a stub that controls the actual backend thread via these channel commands. This way all of the hotkey functions are executed on the same thread, no matter from where the stub functions are called.

About

A lightweight, threadsafe and ergonomic rust crate to handle system-wide hotkeys on windows

Resources

License

Stars

Watchers

Forks

Languages