Struct HotkeyManager 

pub struct HotkeyManager { /* private fields */ }

Public manager API.

Implementations

impl HotkeyManager

pub fn new() -> Result<Self, StartupError>

Create a manager with backend auto-detection.

Errors

Returns an error if the backend cannot be initialized or input devices are not accessible.

pub fn builder() -> HotkeyManagerBuilder

Configure manager startup options.

pub const fn active_backend(&self) -> Backend

Returns the backend this manager is using.

pub fn register<F>( &self, hotkey: impl HotkeyInput, callback: F, ) -> Result<BindingGuard, RegisterError>

where F: Fn() + Send + Sync + 'static,

Register a simple hotkey callback.

Accepts any type implementing HotkeyInput: a Hotkey, a Key, or a string (&str / String).

Errors

Returns RegisterError::Parse when string input conversion fails, RegisterError::AlreadyRegistered if the hotkey is already bound, or RegisterError::ManagerStopped if the engine has shut down.

pub fn register_sequence<F>( &self, sequence: impl SequenceInput, callback: F, ) -> Result<BindingGuard, RegisterError>

where F: Fn() + Send + Sync + 'static,

Register a multi-step sequence callback.

Errors

Returns RegisterError::Parse when sequence input conversion fails, RegisterError::AlreadyRegistered if the sequence is already bound, or RegisterError::ManagerStopped if the engine has shut down.

pub fn register_sequence_with_options( &self, sequence: impl SequenceInput, action: impl Into<Action>, options: SequenceOptions, ) -> Result<BindingGuard, RegisterError>

Register a multi-step sequence with explicit action and options.

Errors

Returns RegisterError::Parse when sequence input conversion fails, RegisterError::AlreadyRegistered if the sequence is already bound, or RegisterError::ManagerStopped if the engine has shut down.

pub fn register_with_options( &self, hotkey: impl HotkeyInput, action: impl Into<Action>, options: BindingOptions, ) -> Result<BindingGuard, RegisterError>

Register a hotkey with an explicit action and binding options.

Accepts any type implementing HotkeyInput: a Hotkey, a Key, or a string (&str / String).

Use when you need metadata (description, overlay visibility) or behavioral options beyond what register() provides.

Errors

Returns RegisterError::Parse when string input conversion fails, RegisterError::AlreadyRegistered if the hotkey is already bound, or RegisterError::ManagerStopped if the engine has shut down.

pub fn is_registered( &self, hotkey: impl HotkeyInput, ) -> Result<bool, QueryError>

Query whether a hotkey is currently registered.

Accepts any type implementing HotkeyInput: a Hotkey, a Key, or a string (&str / String).

Errors

Returns QueryError::Parse when string input conversion fails, or QueryError::ManagerStopped if the engine has shut down.

pub fn is_key_pressed(&self, key: Key) -> Result<bool, ManagerStopped>

Query whether a specific key is currently pressed on any device.

Errors

Returns ManagerStopped if the engine has shut down.

pub fn active_modifiers(&self) -> Result<ModifierSet, ManagerStopped>

Query the set of modifiers currently held, derived from key state.

Left/right variants are canonicalized: if either LeftCtrl or RightCtrl is held, Modifier::Ctrl is in the returned set.

Errors

Returns ManagerStopped if the engine has shut down.

pub fn define_layer(&self, layer: Layer) -> Result<(), LayerError>

Define a named layer.

Sends the layer definition to the engine for storage. The layer is not active until explicitly pushed via push_layer().

Errors

Returns LayerError::AlreadyDefined if a layer with the same name has already been defined, or LayerError::ManagerStopped if the engine has shut down.

pub fn shutdown(self) -> Result<(), ShutdownError>

Stop the manager and join the engine thread.

All registered bindings are dropped. This is also called automatically when the manager is dropped.

Errors

Returns ShutdownError::Engine if the engine thread panicked.

pub fn push_layer(&self, name: impl Into<LayerName>) -> Result<(), LayerError>

Push a named layer onto the layer stack.

The layer must have been previously defined via define_layer. The pushed layer becomes the highest-priority layer for matching.

Errors

Returns LayerError::NotDefined if no layer with the given name exists, or LayerError::ManagerStopped if the engine has shut down.

pub fn pop_layer(&self) -> Result<LayerName, LayerError>

Pop the topmost layer from the layer stack.

Returns the name of the popped layer.

Errors

Returns LayerError::EmptyStack if no layers are active, or LayerError::ManagerStopped if the engine has shut down.

pub fn toggle_layer(&self, name: impl Into<LayerName>) -> Result<(), LayerError>

Toggle a named layer on or off.

If the layer is currently in the stack, it is removed. If the layer is not in the stack, it is pushed.

Errors

Returns LayerError::NotDefined if no layer with the given name exists, or LayerError::ManagerStopped if the engine has shut down.

pub fn list_bindings(&self) -> Result<Vec<BindingInfo>, ManagerStopped>

List all registered bindings with current shadowed status.

Returns global bindings and all layer bindings (active or not). Each entry includes whether the binding is currently reachable or shadowed by a higher-priority layer.

Errors

Returns ManagerStopped if the engine has shut down.

pub fn bindings_for_key( &self, hotkey: impl HotkeyInput, ) -> Result<Option<BindingInfo>, QueryError>

Query what would fire if the given hotkey were pressed now.

Considers the current layer stack. Returns None if no binding matches the hotkey.

Errors

Returns QueryError::Parse when string input conversion fails, or QueryError::ManagerStopped if the engine has shut down.

pub fn active_layers(&self) -> Result<Vec<ActiveLayerInfo>, ManagerStopped>

Query the current layer stack.

Returns layers in stack order (bottom to top).

Errors

Returns ManagerStopped if the engine has shut down.

pub fn pending_sequence( &self, ) -> Result<Option<PendingSequenceInfo>, ManagerStopped>

Return current in-progress sequence state, if any.

Errors

Returns ManagerStopped if the engine has shut down.

pub fn register_tap_hold( &self, key: Key, tap_action: impl Into<Action>, hold_action: impl Into<Action>, options: TapHoldOptions, ) -> Result<BindingGuard, RegisterError>

Register a tap-hold binding for a dual-function key.

The tap_action fires when the key is pressed and released quickly (before the threshold). The hold_action fires when the key is held past the threshold or interrupted by another keypress.

Requires grab mode. Tap-hold must intercept and buffer key events before they reach other applications — without grab, the original key event would be delivered immediately.

Errors

Returns RegisterError::UnsupportedFeature if grab mode is not enabled, RegisterError::AlreadyRegistered if the key already has a tap-hold binding, or RegisterError::ManagerStopped if the engine has shut down.

pub fn conflicts(&self) -> Result<Vec<ConflictInfo>, ManagerStopped>

Find bindings that are shadowed by higher-priority layers.

Returns conflict pairs: each entry shows the shadowed binding and the binding that shadows it.

Errors

Returns ManagerStopped if the engine has shut down.

Trait Implementations

impl Debug for HotkeyManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for HotkeyManager

fn drop(&mut self)

Executes the destructor for this type.