global-hotkey

To register a global hotkey, you must first initialize a GlobalHotKeyManager, construct a HotKey using specific Modifiers and a Code, and then call register on the manager.

Platform Requirements:

• Windows: A win32 event loop must be running on the thread. The GlobalHotKeyManager must be created on the same thread as that event loop (not necessarily the main thread).
• macOS: An event loop must be running on the main thread. You must create the GlobalHotKeyManager on the main thread.
• Linux: Supported on X11 only.

use global_hotkey::{GlobalHotKeyManager, hotkey::{HotKey, Modifiers, Code}};

// initialize the hotkeys manager
let manager = GlobalHotKeyManager::new().unwrap();

// construct the hotkey
let hotkey = HotKey::new(Some(Modifiers::SHIFT), Code::KeyD);

// register it
manager.register(hotkey);

There are two ways to consume global hotkey events:

1. Using a Receiver: Use GlobalHotKeyEvent::receiver() to get a GlobalHotKeyEventReceiver (a crossbeam channel receiver). This is the default method.
2. Using an Event Handler: Use GlobalHotKeyEvent::set_event_handler(Some(callback)) to register a custom closure that is called whenever a hotkey event occurs.

Important: If you set a custom event handler using set_event_handler, the channel accessed via GlobalHotKeyEvent::receiver() will not receive any new events.

use global_hotkey::GlobalHotKeyEvent;

// Try to receive an event from the global channel
if let Ok(event) = GlobalHotKeyEvent::receiver().try_recv() {
    println!("{:?}", event);
}

Use GlobalHotKeyManager to manage the lifecycle of global hotkeys. You must first initialize the manager, then you can register or unregister specific HotKey instances or batches of hotkeys.

Platform Requirements

• Windows: A Win32 event loop must be running on the thread where the GlobalHotKeyManager is created. It does not have to be the main thread.
• macOS: An event loop must be running on the main thread, so the GlobalHotKeyManager must also be created on the main thread.
• Linux: Supported on X11 only.

use global_hotkey::{GlobalHotKeyManager, hotkey::{HotKey, Modifiers, Code}};

// initialize the hotkeys manager
let manager = GlobalHotKeyManager::new().unwrap();

// construct the hotkey
let hotkey = HotKey::new(Some(Modifiers::SHIFT), Code::KeyD);

// register it
manager.register(hotkey);

To handle hotkey press events, use GlobalHotKeyEvent::receiver() to obtain a receiver. You can then use try_recv() to non-blockingly check for new events in your application loop.

use global_hotkey::GlobalHotKeyEvent;

if let Ok(event) = GlobalHotKeyEvent::receiver().try_recv() {
    println!("{:?}", event);
}

You can create a HotKey programmatically by providing an optional set of Modifiers and a specific Code (the main key).

Note that Modifiers::SUPER is automatically converted to Modifiers::META during construction.

# use global_hotkey::hotkey::{HotKey, Modifiers, Code};
let hotkey = HotKey::new(Some(Modifiers::SHIFT), Code::KeyQ);
let hotkey_without_mods = HotKey::new(None, Code::KeyQ);

Represents a global hotkey event emitted when a HotKey is pressed or released.

Methods

• id(&self) -> u32: Returns the unique ID of the associated HotKey.
• state(&self) -> HotKeyState: Returns whether the key was Pressed or Released.
• receiver() -> &'static GlobalHotKeyEventReceiver: Returns a reference to the event channel's receiver. Note: This stops receiving events if a custom event handler is set.
• set_event_handler<F>(f: Option<F>): Sets a custom handler for new events. If Some(f) is passed, the handler is called directly instead of sending events to the channel. If None is passed, it reverts to the default channel behavior.

Manages the registration and unregistration of global hotkeys on the host platform.

Methods

• new() -> crate::Result<Self>: Creates a new instance of the manager.
• register(&self, hotkey: HotKey) -> crate::Result<()>: Registers a single hotkey.
• unregister(&self, hotkey: HotKey) -> crate::Result<()>: Unregisters a single hotkey.
• register_all(&self, hotkeys: &[HotKey]) -> crate::Result<()>: Registers multiple hotkeys at once.
• unregister_all(&self, hotkeys: &[HotKey]) -> crate::Result<()>: Unregisters multiple hotkeys at once.

Use the matches method to determine if a given combination of Modifiers and Code corresponds to a specific HotKey.

# use global_hotkey::hotkey::{HotKey, Modifiers, Code};
let hotkey = HotKey::new(Some(Modifiers::SHIFT), Code::KeyQ);
// Returns true if the provided modifiers and key match the hotkey
let is_match = hotkey.matches(Modifiers::SHIFT, Code::KeyQ);

HotKeyState

An enum describing the state of a HotKey:

• Pressed: The key is down.
• Released: The key is up.

GlobalHotKeyEvent

Struct containing event data:

• id: u32: The ID of the associated HotKey.
• state: HotKeyState: The state of the key.

When parsing a string into a HotKey, you may encounter the following errors:

• UnsupportedKey(String): The provided key string could not be recognized as a valid Code.
• EmptyToken(String): The hotkey string contained an empty token (e.g., Shift++KeyA).
• InvalidFormat(String): The hotkey format is incorrect, such as having multiple main keys or having modifiers listed after the main key.