globalhotkey

stable

Parse, format, validate, and normalize keyboard accelerator strings such as 'Ctrl+Shift+S' for use in global hotkey registration.

use plugin globalhotkey::{parse_accelerator, format_accelerator, is_valid_key, …}

9 functions Systems

/ filter jk navigate Esc clear

Functions (9)

parse_accelerator Parse accelerator string into modifiers + key
format_accelerator Format modifiers list and key into string
is_valid_key Check if a key name is recognized
modifier_names Return all supported modifier names
key_names Return all supported key names
normalize_accelerator Normalize casing and deduplicate modifiers
has_modifier Check if accelerator contains a modifier
is_valid_accelerator Validate a complete accelerator string
modifier_count Count modifiers in an accelerator string

Overview

globalhotkey is a pure string toolkit for working with keyboard accelerators — the +-joined combinations like "Ctrl+Shift+S" that applications bind to global shortcuts. It does not register or listen for hotkeys itself; instead it gives you the parsing, validation, and normalization layer you need before handing an accelerator to a platform registration API or storing it in a config file.

The core concept is that an accelerator is just a string made of zero or more recognized modifier names (Ctrl, Alt, Shift, Super, Meta, Cmd) and exactly one key (letters, digits, function keys, or navigation keys). Every function is case-insensitive and stateless: you pass a string in and get a string, table, bool, or int back. Use it to sanitize user-entered shortcuts, deduplicate and canonicalize stored bindings, or check whether a combination is well-formed before trying to register it.

Common patterns

Validate and canonicalize a user-entered shortcut before storing it:

use plugin globalhotkey::{is_valid_accelerator, normalize_accelerator}

let raw = "shift+ctrl+s"
if is_valid_accelerator(raw) {
  print("stored as: {normalize_accelerator(raw)}")
} else {
  print("not a usable shortcut")
}

Break an accelerator into parts, then rebuild it:

use plugin globalhotkey::{parse_accelerator, format_accelerator}

let parsed = parse_accelerator("Ctrl+Alt+Delete")
print("key is {parsed["key"]}")
let rebuilt = format_accelerator(parsed["modifiers"], parsed["key"])
print(rebuilt)

Inspect a binding to decide how to display it:

use plugin globalhotkey::{modifier_count, has_modifier}

let accel = "Ctrl+Shift+F5"
print("uses {modifier_count(accel)} modifiers")
if has_modifier(accel, "Shift") {
  print("this is a shifted shortcut")
}

parse_accelerator(accelerator) → table

Parse accelerator string into modifiers + key

Splits an accelerator string like "Ctrl+Shift+S" into a table with a modifiers list and a key string. Useful when you need to inspect individual components.

use plugin globalhotkey::{parse_accelerator}

let result = parse_accelerator("Ctrl+Shift+S")
print(result["key"])
print(result["modifiers"][0])

A bare key with no modifiers parses to an empty modifiers list:

use plugin globalhotkey::{parse_accelerator}

let result = parse_accelerator("F5")
print("key: {result["key"]}")

format_accelerator(modifiers, key) → string

Format modifiers list and key into string

Combines a modifiers table and a key string back into an accelerator string joined by +. It is the inverse of parse_accelerator, so the two compose for a round trip.

use plugin globalhotkey::{format_accelerator}

let mods = [0: "Ctrl", 1: "Alt"]
let accel = format_accelerator(mods, "F4")
print(accel)

Feed the output of parse_accelerator straight back in to reconstruct a binding:

use plugin globalhotkey::{parse_accelerator, format_accelerator}

let parts = parse_accelerator("Ctrl+Shift+S")
print(format_accelerator(parts["modifiers"], parts["key"]))

is_valid_key(key) → bool

Check if a key name is recognized

Returns true if the string is a recognized key or modifier name (case-insensitive). Recognized keys include letters A-Z, digits 0-9, function keys F1-F12, and navigation keys.

use plugin globalhotkey::{is_valid_key}

print(is_valid_key("Escape"))
print(is_valid_key("F13"))
print(is_valid_key("ctrl"))

modifier_names() → table

Return all supported modifier names

Returns a table of all supported modifier names: Ctrl, Alt, Shift, Super, Meta, Cmd.

use plugin globalhotkey::{modifier_names}

let mods = modifier_names()
print(mods[0])

Use it to build a picker of allowed modifiers:

use plugin globalhotkey::{modifier_names}

for m in modifier_names() {
  print("modifier: {m}")
}

key_names() → table

Return all supported key names

Returns a table of all supported non-modifier key names including letters, digits, function keys, and navigation keys.

use plugin globalhotkey::{key_names}

let keys = key_names()
print(keys[0])

normalize_accelerator(accelerator) → string

Normalize casing and deduplicate modifiers

Normalizes an accelerator string by fixing casing, removing duplicate modifiers, and sorting modifiers alphabetically before the key. This makes two equivalent bindings compare equal as strings.

use plugin globalhotkey::{normalize_accelerator}

let n = normalize_accelerator("ctrl+shift+ctrl+s")
print(n)

Because the output is canonical, normalizing both sides lets you detect duplicate shortcuts:

use plugin globalhotkey::{normalize_accelerator}

let a = normalize_accelerator("Shift+Ctrl+S")
let b = normalize_accelerator("ctrl+shift+s")
print(a == b)

has_modifier(accelerator, modifier) → bool

Check if accelerator contains a modifier

Returns true if the given accelerator string contains the specified modifier (case-insensitive).

use plugin globalhotkey::{has_modifier}

print(has_modifier("Ctrl+S", "Ctrl"))
print(has_modifier("Ctrl+S", "Alt"))

is_valid_accelerator(accelerator) → bool

Validate a complete accelerator string

Returns true if the accelerator string is valid: it must contain exactly one non-modifier key and all parts must be recognized names.

use plugin globalhotkey::{is_valid_accelerator}

print(is_valid_accelerator("Ctrl+S"))
print(is_valid_accelerator("Ctrl+Alt"))
print(is_valid_accelerator("Ctrl+F13"))

Pair it with normalization to accept only clean, well-formed bindings:

use plugin globalhotkey::{is_valid_accelerator, normalize_accelerator}

let candidate = "alt+shift+tab"
if is_valid_accelerator(candidate) {
  print("ok: {normalize_accelerator(candidate)}")
}

modifier_count(accelerator) → int

Count modifiers in an accelerator string

Counts how many modifier keys appear in the accelerator string.

use plugin globalhotkey::{modifier_count}

print(modifier_count("Ctrl+Alt+Delete"))
print(modifier_count("F5"))

View source code