spacr.qt.preview_registry

Which modules get a Live Preview, and how one is attached from outside.

Four modules have a preview: Mask, Measure, Timelapse and Motility. Each one costs a thirteen-line arm in AppScreen._build_runtime_panel, two attribute names in a null-out block, and a row in a toggle table two hundred lines further down.

Adding a preview to another module that way, for example Cellpose Masks or Plaque Assay, needs the same edits to the shared screen.

This module removes those edits. A module declares a preview here; the strip above the settings form grows a toggle for it; the card is inserted above the Run row through the same _runtime_wrap / _actions_row anchors spacr.qt.prerun uses. Nothing inside AppScreen changes, and the four previews it already builds are left alone — a module the shared screen has already served is skipped here rather than given a second card.

A module that has been FOLDED into a host reaches the same machinery from the other end. Its own screen is not built any more, so install – which answers for the screen’s own key – can never attach its panel; attach_folded() lets the host ask for it by name and keeps it hidden behind whatever the host uses to reveal the rest of that module. Mask Generation’s tracking switch is the case it was written for.

Sampling is done by the panels. The panels reached through this registry are the shipped ones, which group a plate into image sets from file names alone and open a bounded, reproducible random sample of it. Nothing here enumerates, opens or lists a directory. A new panel registered here must sample the same way — see spacr.qt.widgets.preview_controls.

Classes

PreviewSpec

One module's preview declaration.

Functions

attach_folded(→ Optional[_PreviewHost])	Attach ANOTHER module's declared preview to screen.
install(→ Optional[_PreviewHost])	Attach screen's declared preview, if it has one to attach.
install_window_hooks(→ Optional[_StackWatcher])	Follow window's screen stack, attaching declared previews.
preview_app_keys(→ Tuple[str, ...])	Every module with a preview, however it is attached.
register_preview(→ PreviewSpec)	Declare a preview for app_key.
unregister_preview(→ bool)	Drop a declaration. True if there was one.

Module Contents

class spacr.qt.preview_registry.PreviewSpec

One module’s preview declaration.

Variables:

• builder – "module:function" returning (panel, card), the shape every existing build_*_preview_card already has. Named rather than imported so declaring a preview imports nothing at launch; a preview panel imports the imaging stack.

• title – the toggle’s label.

• tooltip – the toggle’s tooltip text.

• propagation – rename map applied to whatever the panel hands back through set_propagate_callback, so a panel written for one module’s setting names can serve another’s.

• owned_by_screen – True for the ones AppScreen already builds. They are declared here so this registry is the single answer to “which modules have a preview”, and skipped at install time so they do not get a second card.

• fill – "module:function" taking (host, card) and building the panel into the card, returning it. Given, a preview ATTACHED through this registry builds only its card at install – builder is called with panel_later=True – and the panel the first time the card is shown or the panel is asked for, so a hidden preview adds no work when the module opens.

spacr.qt.preview_registry.attach_folded(screen: PySide6.QtWidgets.QWidget, app_key: str) → _PreviewHost | None

Attach ANOTHER module’s declared preview to screen.

A module folded into a host as settings categories brings its panel with it. Mask Generation has the Cellpose live preview and no track preview; Timelapse’s whole preview is the tracking one, built by the screen the fold means nobody opens any more. Without this the switch would show the tracking settings but no preview of their effect, which the separate Timelapse screen had.

owned_by_screen is deliberately ignored: it means “AppScreen builds this one for its own key”, and here the key belongs to another module. The card and its toggle both start hidden; the host reveals them when the fold is switched on.

Parameters:

• screen – the HOST screen.

• app_key – the folded module’s key.

Returns:

the host, or None when there is nothing to attach.

spacr.qt.preview_registry.install(screen: PySide6.QtWidgets.QWidget) → _PreviewHost | None

Attach screen’s declared preview, if it has one to attach.

Returns None when the module declares no preview, when AppScreen already built one for it, when the screen has no runtime panel to insert into, or when one is already installed. Never raises, so a missing preview does not stop the module opening.

Parameters:

screen – app screen widget; its app_key attribute selects the declared preview, and the installed host is remembered on it so a second call returns the same one.

spacr.qt.preview_registry.install_window_hooks(window: PySide6.QtWidgets.QMainWindow) → _StackWatcher | None

Follow window’s screen stack, attaching declared previews.

Called once from spacr.qt.shortcuts.install(), after the settings strip’s own hook so the toggle has somewhere to go.

Parameters:

window – main window whose _stack screen stack is followed; without one nothing is installed, and a watcher already stored on it is returned instead of a new one.

spacr.qt.preview_registry.preview_app_keys() → Tuple[str, ...]

Every module with a preview, however it is attached.

spacr.qt.preview_registry.register_preview(app_key: str, spec: PreviewSpec, *, replace: bool = False) → PreviewSpec

Declare a preview for app_key.

Parameters:

• app_key – the module’s app key.

• spec – its declaration.

• replace – overwrite an existing declaration instead of raising.

Raises:

ValueError – on a second declaration without replace, so two modules cannot claim one key unnoticed.

spacr.qt.preview_registry.unregister_preview(app_key: str) → bool

Drop a declaration. True if there was one.

Parameters:

app_key – app key whose preview declaration is removed; converted with str() first.