spacr.qt.shortcuts

Window-wide and screen-specific shortcuts for the spaCR Qt GUI.

The default window-wide actions include:

Ctrl+0 Go home (Cmd+H is Hide on macOS) Ctrl+1..9 Open the corresponding app-registry entry if visible Ctrl+K Open the command palette Ctrl+Shift+H Search spaCR from the field beside the Help menu F1 Show the shortcuts cheat sheet ? Use the active screen’s help action, or show the cheat sheet Ctrl+P Open Preferences Ctrl+Alt+0 Put GUI scale, font scale and preview scales back to 100 % Ctrl+/ Toggle the active module’s AI Console Ctrl+End Jump to the newest console line F11 Toggle full screen

install() creates the bindings returned by installed(). Other actions in SHORTCUTS are bound by the main window’s menus; the scroll gesture uses an event filter. Screen-owned bindings are included by mapped(), with their scope and saved overrides. Escape handling belongs to the active screen, overlay or dialog rather than a binding installed here.

Declared window-wide key sequences can be rebound. The cheat sheet carries a “Change shortcuts…” button that opens a table of the window-wide actions; a key typed there replaces the default, a key already taken by another action is named as a conflict and cannot be saved, and the overrides are kept in the Preferences store under _KEYMAP_KEY in Qt’s portable spelling, so a keymap saved on one platform reads the same on the others. Keys that belong to a single screen (Annotate, Make Masks, the field browser, Gate Editor) have separate editable rows and saved overrides, applied to both existing and new screens.

Classes

ShortcutOverlay	Show the declared shortcut map and additional child bindings over a window.
ShortcutSpec	One shortcut declaration.

Functions

discover(→ List[ShortcutSpec])	Find additional child shortcut and action sequences for the map.
install(→ None)	Bind the shortcuts returned by installed() on window.
installed(→ List[ShortcutSpec])	The window-wide keys that install() is responsible for binding.
mapped(→ List[ShortcutSpec])	Every shortcut the map describes: window-wide, then per-screen.
native(→ str)	keys in the spelling the user's own keyboard has.
show_cheat_sheet(→ None)	Show shortcut help as an overlay or a fallback dialog.

Module Contents

class spacr.qt.shortcuts.ShortcutOverlay(window: PySide6.QtWidgets.QWidget)

Bases: PySide6.QtWidgets.QWidget

Show the declared shortcut map and additional child bindings over a window.

The translucent card groups actions by category and displays saved overrides and screen scopes. Its scroll area exposes content that does not fit. Key presses and mouse presses handled by the overlay dismiss it; the Change shortcuts button closes it and opens the keymap editor.

Parameters:

window – the parent widget to cover and inspect for bindings. The overlay resizes with this widget and does not create a separate top-level window.

Build the shortcut cheat sheet as a card over the window.

Parameters:

window – the window it covers; the card is centred in it and scrolls when the map does not fit.

dismiss() → None

Close the overlay and let go of the window.

eventFilter(obj, event)

Track the window’s size so the overlay stays full-bleed.

Parameters:

• obj – the watched object: the covered window or the card’s scroll viewport.

• event – the event delivered to it. A resize of the window resizes the overlay to match; a mouse press on the scroll viewport dismisses the overlay and is consumed.

keyPressEvent(event) → None

Dismiss the overlay when a key press reaches this handler.

Parameters:

event – the key event; which key was pressed is not read.

mousePressEvent(event) → None

Dismiss the overlay when a mouse press reaches this handler.

Parameters:

event – the mouse press event; its button and position are not read.

paintEvent(event) → None

Leave the main window visible around the translucent shortcut card.

Parameters:

event – the paint event; ignored, so nothing is painted behind the card.

resizeEvent(event) → None

Keep the card centred when the window resizes.

Parameters:

event – the resize event; not read, the card is re-centred for the overlay’s current size.

class spacr.qt.shortcuts.ShortcutSpec

One shortcut declaration.

Parameters:

• keys – the binding, in Qt’s portable spelling. It is PRINTED through QKeySequence.toString(NativeText), so Ctrl reads as the Command symbol on macOS – writing “Ctrl+H” into a label would hard-code one platform into the help.

• label – what the key does.

• category – the group it is shown under.

• scope – where it works. The default is the whole window; a per-screen binding names its screen.

spacr.qt.shortcuts.discover(window) → List[ShortcutSpec]

Find additional child shortcut and action sequences for the map.

Sequences already described by mapped(), including saved window-wide overrides, are excluded. Other nonempty sequences are deduplicated by their native spelling. The scan includes existing holders regardless of whether they are enabled or currently visible; it does not determine which action would receive a key event.

The declared map supplies labels and scopes for known bindings even before their owning screens have been constructed.

Parameters:

window – the widget whose child QShortcut and QAction objects are searched; a widget that cannot be searched yields an empty list.

spacr.qt.shortcuts.install(window: PySide6.QtWidgets.QMainWindow) → None

Bind the shortcuts returned by installed() on window.

Existing shortcut holders are reused. Menu-owned keys and the scroll gesture are installed elsewhere; this function also installs the optional window hooks and applies saved keymap overrides.

Parameters:

window – the main window the application shortcuts are bound to.

spacr.qt.shortcuts.installed() → List[ShortcutSpec]

The window-wide keys that install() is responsible for binding.

Gestures are not among them. A gesture is a modifier held while the mouse wheel turns, and it is caught by an event filter rather than by a key sequence, so no shortcut object can express it and none is created for it. Listing one here would promise a binding that cannot be made.

Every gesture is still listed on the shortcut map. mapped() returns what the hands can do, and this returns what the shortcut objects own.

spacr.qt.shortcuts.mapped() → List[ShortcutSpec]

Every shortcut the map describes: window-wide, then per-screen.

spacr.qt.shortcuts.native(keys: str) → str

keys in the spelling the user’s own keyboard has.

Ctrl is the Command symbol on macOS and Qt already knows; writing “Ctrl+H” into a label hard-codes one platform into the help.

Parameters:

keys – a key sequence in Qt’s portable spelling, such as 'Ctrl+H'. Returned unchanged when Qt cannot convert it.

spacr.qt.shortcuts.show_cheat_sheet(parent) → None

Show shortcut help as an overlay or a fallback dialog.

A nonzero-sized widget gets ShortcutOverlay, which includes declared screen scopes, saved bindings and additional child sequences. A parentless or zero-sized caller gets a modal dialog containing the default window-wide SHORTCUTS table instead.

Parameters:

parent – the window to cover. A QWidget with a non-zero size gets the overlay, replacing any overlay it already has. Otherwise, None or a zero-sized widget parents the fallback dialog.

Returns:

the overlay when one is shown, or None after the fallback dialog closes.