simvx.core.shortcuts

Keyboard shortcut manager for editor use.

Manages named keyboard shortcuts with modifier key support and chord combos. Each shortcut maps a human-readable combo string (e.g. "Ctrl+Shift+S" or "Ctrl+K, Ctrl+C") to a callback that fires when the matching key event arrives.

The manager is decoupled from the :class:Input singleton – callers pass modifier state explicitly so the module stays testable and import-free.

Example::

mgr = ShortcutManager()
mgr.register("save",   "Ctrl+S",       lambda: print("save"))
mgr.register("redo",   "Ctrl+Shift+Z", lambda: print("redo"))
mgr.register("delete", "Delete",       lambda: print("delete"))
mgr.register("comment", "Ctrl+K, Ctrl+C", lambda: print("comment"), description="Toggle comment")

# Called from the key-event handler:
mgr.handle_key("s", modifiers={"ctrl"})          # prints "save"
mgr.handle_key("z", modifiers={"ctrl", "shift"}) # prints "redo"

# Chord: two keystrokes in sequence
mgr.handle_key("k", modifiers={"ctrl"})           # starts chord
mgr.handle_key("c", modifiers={"ctrl"})           # prints "comment"

Module Contents

Classes

Shortcut	Internal representation of a registered shortcut.
ShortcutManager	Registry of named keyboard shortcuts with chord and rebinding support.

API

class simvx.core.shortcuts.Shortcut(name: str, key: str, modifiers: frozenset[str], callback: collections.abc.Callable[[], object], combo: str, chord_key: str | None = None, chord_modifiers: frozenset[str] | None = None, description: str = '', category: str = '')

Internal representation of a registered shortcut.

Initialization

__slots__

(‘name’, ‘key’, ‘modifiers’, ‘callback’, ‘combo’, ‘chord_key’, ‘chord_modifiers’, ‘description’, ‘ca…

class simvx.core.shortcuts.ShortcutManager

Registry of named keyboard shortcuts with chord and rebinding support.

Shortcuts are identified by a unique name. Registering a shortcut with an existing name silently replaces the previous binding.

Initialization

register(name: str, keys: str, callback: collections.abc.Callable[[], object], description: str = '', category: str = '') → None

Register (or replace) a named shortcut.

Parameters

name: Unique identifier for this shortcut (e.g. "save"). keys: Human-readable key combo (e.g. "Ctrl+S", "Ctrl+K, Ctrl+C"). callback: Zero-argument callable invoked when the shortcut fires. description: Human-readable description for search and display. category: Grouping category (e.g. "Editor", "File").

unregister(name: str) → None

Remove a shortcut by name. Raises KeyError if not found.

rebind(name: str, new_keys: str) → None

Update an existing shortcut’s key binding, keeping callback/description/category.

Raises KeyError if name is not registered.

handle_key(key: str, modifiers: dict[str, bool] | set[str] | frozenset[str] | None = None) → bool

Dispatch callbacks for any shortcuts matching key + modifiers.

Handles chord sequences: if a chord’s first keystroke was already matched, this checks for the second keystroke to complete it.

Returns True if a shortcut matched (or a chord started).

tick(dt: float) → None

Advance chord timeout timer. Call once per frame with delta time.

search(query: str) → list[simvx.core.shortcuts.Shortcut]

Return shortcuts whose name, description, or category contain query (case-insensitive).

get_bindings_map() → dict[str, str]

Return {name: combo_string} for serialization.

load_bindings(bindings: dict[str, str]) → None

Rebind existing shortcuts from a {name: combo} mapping.

Entries whose name is not currently registered are silently skipped.

list_shortcuts() → dict[str, str]

Return {name: combo_string} for every registered shortcut.