Keybind
Capture a keyboard binding and handle Toggle, Hold or Always activation.
Create Keybind#
Capture a keyboard binding and handle Toggle, Hold or Always activation.
The constructor returns a Keybind handle. The snippet assumes section exists, as created in Quick start.
local keybind = section:CreateKeybind({
Name = "Details shortcut", Flag = "shortcut", Default = "H", Mode = "Toggle",
Callback = function(key) print("Binding:", key and key.Name or "None") end,
OnActivate = function(active, key, mode) print(active, key, mode) end,
})
Open full size ↗
Open full size ↗Arguments#
| Option | Type | Default | Meaning |
|---|---|---|---|
| Default | Enum.KeyCode | string? | nil | Enum value or key name; None means unbound. |
| Mode | "Toggle" | "Hold" | "Always" | "Toggle" | Shortcut activation behavior. |
| Callback | function(Enum.KeyCode?) | nil | Binding or notifying mode change; separate from activation. |
| OnActivate | function(boolean, Enum.KeyCode?, string) | nil | Receives active state, current key and mode. |
Also accepts common options: Name, Description, Disabled and Callback; stateful controls additionally support Flag, Persist and Sensitive.
Manage state#
local _, valid = keybind:SetValue("J")
assert(valid)
keybind:SetMode("Hold")
print(keybind:GetValue(), keybind:GetMode(), keybind:GetActive())
local capturing = keybind:BeginCapture()
keybind:CancelCapture()Returned methods#
| Method | Returns | Behavior |
|---|---|---|
| GetValue() | Enum.KeyCode? | Current binding. |
| SetValue(key, notify?) | self, valid:boolean | Invalid setter leaves binding unchanged; default notify=false. |
| GetMode() / SetMode(mode, notify?) | string / self | Toggle, Hold or Always. A changed SetMode(mode, true) also calls Callback(currentKey) and allows activation notifications. |
| GetActive() | boolean | Current shortcut activation. |
| BeginCapture() | boolean | Requests key capture; false if unavailable. |
| CancelCapture() | self | Ends capture. |
| IsCapturing() | boolean | Reads capture state. |
| Close() | self | Cancels capture and active state. |
| SetDisabled(boolean) | self | Changes user availability without discarding the value. |
| IsDisabled() | boolean | Reads the requested disabled state. |
| Destroy() | nil | Removes this control and its subscriptions; safe to repeat. |
Behavior and limitations#
Toggle flips active state on a fresh key press. Hold is active from press until release. Always is active while its control is available and the client has focus, without requiring a bound key press.
Capture is exclusive within the loaded library instance. Escape cancels; Backspace/Delete clears the binding. The captured press does not activate a shortcut. BeginCapture while already capturing cancels and returns false.
Invalid constructor bindings assert; invalid SetValue returns false. Keyboard bindings are not a touch shortcut system. Processed input, text focus or lost client focus prevents ordinary shortcut activation.
Callback reports rebinding or a notifying mode change. OnActivate reports runtime activation. SetValue(key, false) may release an active binding via OnActivate(false).
Modal/hide/minimize suppress input and cancel capture. Toggle/Hold wait for a fresh press after availability returns; Always resumes.
Only key and mode persist. Load/Reset do not replay OnActivate. Capture, pressed and active state are transient.
Supported bindings exclude Unknown, Escape, Backspace, Delete, and gamepad Button/DPad/Thumbstick keys. Those reserved keys cannot be set as ordinary shortcuts. Invalid modes or non-boolean notify values assert.