exlab_wizard.ui.keyboard#

Keyboard-shortcut registry (Frontend Spec §3.7).

The bindings are intentionally small and central. Adding a new shortcut is a deliberate spec change to §3.7 plus a registry entry here; bypassing the registry to bind directly on a NiceGUI element is a code-review reject.

The registry exposes the canonical macOS and Windows / Linux key combos for each Shortcut. Per-shortcut handlers are looked up at runtime so the pages don’t need to import the registry’s binding helper to register.

Functions

`bind_global_shortcuts`(registry)	Install a NiceGUI keyboard listener for the registry.
`combo_for_current_os`(shortcut)	Resolve the `KeyCombo` for the current OS.
`get_binding`(shortcut)	Return the `ShortcutBinding` for the given shortcut id.
`is_macos`()	Return `True` when running on macOS (used for combo selection).
`list_bindings`()	Return the canonical bindings table (Frontend §3.7).
`resolve`(*, key[, cmd, ctrl, shift, alt])	Find the shortcut id matching the given key event, if any.

Classes

`KeyCombo`(key[, cmd, ctrl, shift, alt])	A modifier-and-key combination.
`Shortcut`(*values)	Identifiers for the app-level shortcut set (Frontend §3.7).
`ShortcutBinding`(shortcut, macos, other, ...)	One row in the §3.7 shortcut table.
`ShortcutRegistry`([handlers])	A populated registry of shortcut handlers.

class exlab_wizard.ui.keyboard.KeyCombo(key, cmd=False, ctrl=False, shift=False, alt=False)[source]#

Bases: object

A modifier-and-key combination.

Parameters:

key (str)
cmd (bool)
ctrl (bool)
shift (bool)
alt (bool)

alt: bool = False#

cmd: bool = False#

ctrl: bool = False#

key: str#

matches(*, key, cmd, ctrl, shift, alt)[source]#

Return True if a NiceGUI KeyEventArguments matches this combo.

Parameters:

key (str)
cmd (bool)
ctrl (bool)
shift (bool)
alt (bool)

Return type:

bool

shift: bool = False#

class exlab_wizard.ui.keyboard.Shortcut(*values)[source]#

Bases: StrEnum

Identifiers for the app-level shortcut set (Frontend §3.7).

FOCUS_TREE_SEARCH = 'focus_tree_search'#

NEW_PROJECT = 'new_project'#

NEW_RUN = 'new_run'#

NEW_TEST_RUN = 'new_test_run'#

OPEN_PROBLEMS = 'open_problems'#

OPEN_SETTINGS = 'open_settings'#

REFRESH_TREE = 'refresh_tree'#

WIZARD_CANCEL = 'wizard_cancel'#

WIZARD_NEXT = 'wizard_next'#

class exlab_wizard.ui.keyboard.ShortcutBinding(shortcut, macos, other, description)[source]#

Bases: object

One row in the §3.7 shortcut table.

Parameters:

shortcut (Shortcut)
macos (KeyCombo)
other (KeyCombo)
description (str)

description: str#

macos: KeyCombo#

other: KeyCombo#

shortcut: Shortcut#

class exlab_wizard.ui.keyboard.ShortcutRegistry(handlers=<factory>)[source]#

Bases: object

A populated registry of shortcut handlers.

Pages instantiate one registry, register handlers for the actions they care about, and pass the registry to bind_global_shortcuts() to install a single keyboard listener.

Parameters:: handlers (dict[Shortcut, Callable[[], None]])

dispatch(shortcut)[source]#

Invoke the handler for shortcut if registered.

Returns True if a handler ran, False if the shortcut had no registered handler.

Parameters:: shortcut (Shortcut)
Return type:: bool

handlers: dict[Shortcut, Callable[[], None]]#

register(shortcut, handler)[source]#

Attach a handler. Only one handler per shortcut.

Raises:

ValueError – if a handler is already registered for shortcut.

Parameters:

shortcut (Shortcut)
handler (Callable[[], None])

Return type:

None

exlab_wizard.ui.keyboard.bind_global_shortcuts(registry)[source]#

Install a NiceGUI keyboard listener for the registry.

NiceGUI is imported lazily so unit tests can exercise the registry surface without spinning up an app.

Parameters:: registry (ShortcutRegistry)
Return type:: None

exlab_wizard.ui.keyboard.combo_for_current_os(shortcut)[source]#

Resolve the KeyCombo for the current OS.

Parameters:: shortcut (Shortcut)
Return type:: KeyCombo

exlab_wizard.ui.keyboard.get_binding(shortcut)[source]#

Return the ShortcutBinding for the given shortcut id.

Raises:: KeyError – if the shortcut is not in the canonical table.
Parameters:: shortcut (Shortcut)
Return type:: ShortcutBinding

exlab_wizard.ui.keyboard.is_macos()[source]#

Return True when running on macOS (used for combo selection).

Return type:: bool

exlab_wizard.ui.keyboard.list_bindings()[source]#

Return the canonical bindings table (Frontend §3.7).

Return type:: tuple[ShortcutBinding, ...]

exlab_wizard.ui.keyboard.resolve(*, key, cmd=False, ctrl=False, shift=False, alt=False)[source]#

Find the shortcut id matching the given key event, if any.

Parameters:

key (str)
cmd (bool)
ctrl (bool)
shift (bool)
alt (bool)

Return type:

Shortcut | None