spacr.qt.walkthrough¶

Per-module walkthroughs — the coach-marks, once per module, on demand.

spacr.qt.first_run shows one tour, once, about the home screen. That answered “where am I?” and nothing else: a user who has seen it still opens Mask for the first time and meets 190 settings under thirteen headings with no idea which two of them matter, and there is no way to ask again.

This module makes the tour per module and repeatable:

the first time a module is opened, its own short walkthrough runs;
every walkthrough is available afterwards from Help → Walkthroughs, and from the command palette, for any module — not only the one on screen;
“seen” is tracked per module, so a new module added to the shell next release introduces itself to an existing user rather than staying silent because the one global flag was set in 2026.

A walkthrough is built from the module’s own settings layout rather than hand-written per module. That is what stops it rotting: the steps name the module’s first curated group and its essential settings, both of which come from spacr.qt.screens.settings_model, so a layout change updates the walkthrough with it. Modules that want more can register extra steps:

from spacr.qt.walkthrough import register_steps
register_steps("mask", [WalkStep("Test mode first", "...")])

Reuses spacr.qt.first_run._TourOverlay for the rendering, because a second dimmed-overlay-with-a-card would be a second thing to keep looking like the first one.

Classes¶

WalkStep

One narrated coach-mark in a module walkthrough.

Functions¶

`build_steps`(→ List[WalkStep])	The walkthrough for one module, derived from its settings layout.
`install_help_menu`(→ Optional[PySide6.QtWidgets.QMenu])	Add a Walkthroughs submenu listing every module.
`install_window_hooks`(→ Optional[_WalkthroughHandler])	Wire the walkthroughs into a live main window.
`mark_seen`(→ None)	Remember that `app_key`'s walkthrough has been shown.
`maybe_show`(→ Optional[spacr.qt.first_run._TourOverlay])	Show `app_key`'s walkthrough if this user has not seen it.
`register_steps`(→ None)	Add module-specific steps to `app_key`'s walkthrough.
`reset`(→ None)	Forget one module's walkthrough, or every module's.
`show_walkthrough`(...)	Run `app_key`'s walkthrough over `window`.
`unregister_steps`(→ bool)	Drop a module's registered steps. `True` if there were any.
`was_seen`(→ bool)	True once `app_key`'s walkthrough has been finished or dismissed.

Module Contents¶

class spacr.qt.walkthrough.WalkStep[source]¶

One narrated coach-mark in a module walkthrough.

Variables:

title – short headline.
body – one or two sentences under it.
highlight – callable taking the live screen and returning the widget to ring, or None to centre the card.

spacr.qt.walkthrough.build_steps(app_key: str) → List[WalkStep][source]¶

The walkthrough for one module, derived from its settings layout.

Four beats, in the order somebody actually works: what the module is, where its inputs go, which settings matter out of how many, and how to run it. Every fact in them is read from the registry or the layout, so none of them can go stale the way a hand-written paragraph does.

Parameters:: app_key – the module’s app key.

spacr.qt.walkthrough.install_help_menu(window: PySide6.QtWidgets.QMainWindow) → PySide6.QtWidgets.QMenu | None[source]¶

Add a Walkthroughs submenu listing every module.

Every module, not only the one on screen: the question “how does Measure work?” is usually asked from somewhere that is not Measure.

Parameters:: window – the main window; the submenu is inserted into its menu-bar Help menu, before the first separator, and the window keeps the submenu and the handler it creates.
Returns:: the submenu, or None when there is no Help menu or one is already installed.

spacr.qt.walkthrough.install_window_hooks(window: PySide6.QtWidgets.QMainWindow) → _WalkthroughHandler | None[source]¶

Wire the walkthroughs into a live main window.

Called once from spacr.qt.shortcuts.install().

Parameters:: window – the main window; gets the Help-menu submenu, and its _stack screen stack (when present) is followed so each module’s walkthrough is offered on the first visit. Wiring twice is a no-op.

spacr.qt.walkthrough.mark_seen(app_key: str) → None[source]¶

Remember that app_key’s walkthrough has been shown.

Parameters:: app_key – the module’s registry key; its seen flag is set in spaCR’s QSettings.

spacr.qt.walkthrough.maybe_show(window: PySide6.QtWidgets.QMainWindow, app_key: str) → spacr.qt.first_run._TourOverlay | None[source]¶

Show app_key’s walkthrough if this user has not seen it.

Called when a module is opened. Per module, so a module added next release introduces itself instead of being silenced by a flag set the first time the app ever ran.

Parameters:

window – the main window the walkthrough is shown over.
app_key – the module’s registry key; nothing is shown when was_seen() is already true for it.

spacr.qt.walkthrough.register_steps(app_key: str, steps: List[WalkStep], *, replace: bool = False) → None[source]¶

Add module-specific steps to app_key’s walkthrough.

The seam a module uses to say something the layout cannot — “run test mode on three fields before committing a plate” is advice, not structure, and no amount of reading the settings map produces it.

Parameters:

app_key – the module’s app key.
steps – steps appended after the derived ones.
replace – overwrite an existing registration instead of raising.

Raises:

ValueError – on a second registration without replace.

spacr.qt.walkthrough.reset(app_key: str | None = None) → None[source]¶

Forget one module’s walkthrough, or every module’s.

Parameters:: app_key – the module to reset, or None for all of them.

spacr.qt.walkthrough.show_walkthrough(window: PySide6.QtWidgets.QMainWindow, app_key: str, *, force: bool = True) → spacr.qt.first_run._TourOverlay | None[source]¶

Run app_key’s walkthrough over window.

Navigates to the module first — a walkthrough that highlights a settings group on a screen the user is not looking at highlights nothing.

Parameters:

window – the live main window.
app_key – the module to walk through.
force – show even when it has been seen before. The default, since every route to this function except the automatic one is somebody asking for it.

Returns:

the overlay, or None when it was skipped.

spacr.qt.walkthrough.unregister_steps(app_key: str) → bool[source]¶

Drop a module’s registered steps. True if there were any.

Parameters:: app_key – the module’s registry key, as passed to register_steps().

spacr.qt.walkthrough.was_seen(app_key: str) → bool[source]¶

True once app_key’s walkthrough has been finished or dismissed.

Parameters:: app_key – the module’s registry key; its seen flag is read from spaCR’s QSettings.