Druid Hotkey Component

Description

The Hotkey component provides a way to handle keyboard shortcuts in your UI. It allows you to define specific key combinations that trigger actions, making your UI more accessible and efficient for keyboard users.

Features

Support for single key and key combination shortcuts
Customizable callback functions
Optional key modifiers (shift, ctrl, alt)
Ability to enable/disable hotkeys
Events for hotkey triggers

Basic Usage

-- Create a hotkey for the 'Enter' key
local hotkey = self.druid:new_hotkey("key_enter", function(self)
    -- Handle Enter key press
    print("Enter key pressed!")
end)

-- Create a hotkey with modifiers (Ctrl+S)
local save_hotkey = self.druid:new_hotkey({
    key = "key_s",
    modifier = "key_ctrl"
}, function(self)
    -- Handle Ctrl+S key combination
    print("Ctrl+S pressed - saving...")
end)

Parameters

key_trigger: The key or key combination to trigger the hotkey
- Can be a string for a single key (e.g., "key_enter")
- Can be a table for key combinations (e.g., {key = "key_s", modifier = "key_ctrl"})
callback: (optional) Function to call when the hotkey is triggered

Methods

-- Enable the hotkey
hotkey:set_enabled(true)

-- Disable the hotkey
hotkey:set_enabled(false)

-- Check if hotkey is enabled
local is_enabled = hotkey:is_enabled()

-- Trigger the hotkey programmatically
hotkey:trigger()

Events

-- Subscribe to hotkey trigger event
hotkey.on_pressed:subscribe(function(self)
    print("Hotkey was triggered")
end)

Key Combinations

The component supports various key combinations:

-- Single key
local hotkey1 = self.druid:new_hotkey("key_space", callback)

-- Key with modifier
local hotkey2 = self.druid:new_hotkey({
    key = "key_s",
    modifier = "key_ctrl"
}, callback)

-- Key with multiple modifiers
local hotkey3 = self.druid:new_hotkey({
    key = "key_s",
    modifier = {"key_ctrl", "key_shift"}
}, callback)

Examples

-- Create navigation hotkeys
local next_hotkey = self.druid:new_hotkey("key_right", function()
    navigate_to_next_page()
end)

local prev_hotkey = self.druid:new_hotkey("key_left", function()
    navigate_to_previous_page()
end)

-- Create application shortcuts
local save_hotkey = self.druid:new_hotkey({
    key = "key_s",
    modifier = "key_ctrl"
}, function()
    save_document()
end)

local undo_hotkey = self.druid:new_hotkey({
    key = "key_z",
    modifier = "key_ctrl"
}, function()
    undo_last_action()
end)

-- Create a help dialog hotkey
local help_hotkey = self.druid:new_hotkey("key_f1", function()
    show_help_dialog()
end)

Notes

The Hotkey component requires proper key triggers setup in your input.binding file
Hotkeys are global by default and will trigger regardless of UI focus
You can enable/disable hotkeys based on context (e.g., disable certain hotkeys when a dialog is open)
Key names should match the action IDs defined in your input bindings
Common key names include:
- Navigation: "key_up", "key_down", "key_left", "key_right"
- Modifiers: "key_ctrl", "key_shift", "key_alt"
- Function keys: "key_f1", "key_f2", etc.
- Special keys: "key_enter", "key_space", "key_escape", "key_backspace"
The component handles both key press and key release events
Hotkeys are a great way to improve accessibility and user experience for keyboard users

3.4 KiB Raw Blame History