spacr.qt.widgets.loading_screen

Full-window loading cover and startup photomosaic animation.

The application shows this cover while constructing its window. With eager preloading, spacr.qt.app._PipelinePreloader imports pipeline modules on a worker thread and reports progress through a GUI-thread timer. The default on-demand policy ends the loading phase without importing those modules. The host then closes the cover or starts its photomosaic animation, according to the startup preferences.

Reported progress lights the three phases of STRAP_LINE and fills the thin rule below them. LoadingScreen.show_mosaic() replaces the plain logo with the photomosaic; LoadingScreen.blow_away() animates its removal. replay_startup_animation() runs the sequence again over an existing window.

Classes

BlowAway	The motion of the photomosaic's tiles as a wind front blows them away.
LoadingScreen	Full-window loading cover with optional photomosaic animation.
MosaicMap	The startup photomosaic's picture and which of its tiles hold the logo.

Functions

blow_away_running(→ bool)	Whether a blow-away is drawing its frames.
mosaic_splash_wanted(→ bool)	Whether the loading cover shows the photomosaic.
replay_startup_animation(→ Optional[LoadingScreen])	Play the startup sequence again inside window.
startup_animation_allowed(→ bool)	Whether the photomosaic may blow away when the window is ready.
strap_line(→ str)	The whole strap line as one translated string.
strap_phrases(→ Sequence[str])	The strap line's phases, translated, for the home screen to reuse.
will_blow_away(→ bool)	Whether screen will end with the blow-away rather than vanish.

Module Contents

class spacr.qt.widgets.loading_screen.BlowAway(occupied, origin, side: float, *, seed: int = _MOSAIC_SEED, wind=(1.0, 0.3), start: float = 0.05, sweep: float = 1.1, pace: float = 1.0, end: float | None = None)

The motion of the photomosaic’s tiles as a wind front blows them away.

Pure arithmetic on arrays, with no Qt: every tile’s launch time and flight are drawn once from a seeded generator, and frame() evaluates the whole flock at one moment, so the motion depends on elapsed time only and never on how many frames were drawn.

The front sweeps across the mosaic along wind. As it reaches a tile, the tile lifts towards the viewer, turns over like a card (one axis scaled through the cosine of its flip angle, with a skew and a little foreshortening for perspective), spins, and flies downwind with random turbulence and slight gravity while it fades. Background tiles do not fly; they leave with the front.

Parameters:

• occupied – grid x grid booleans; True tiles fly.

• origin – the mosaic’s top-left corner, in widget coordinates.

• side – the mosaic’s side, in the same units.

• seed – seed of the randomness.

• wind – direction the wind blows, (x, y); down-screen is +y.

• start – seconds before the front reaches the first tile.

• sweep – seconds the front takes to cross the mosaic.

• pace – how many times slower than the 694 flight each tile flies (lift, flip, spin, travel and fade are stretched alike).

• end – when given, the last tile has gone by then: lives are cut to end there and duration is end.

Draw every tile’s launch and flight; see the class docstring.

backdrop(t: float)

How opaque the cover’s ground is behind and ahead of the front.

Parameters:

t – seconds since the blow-away began.

Returns:

(front, behind, ahead): the front’s position along the wind as a share of the mosaic (0 at its upwind edge, 1 at the downwind one), and the ground’s opacity, 0..1, on either side.

frame(t: float, bounds=None, floor: float = 0.02)

Where every flying tile is at t.

Parameters:

• t – seconds since the blow-away began.

• bounds – (x0, y0, x1, y1); tiles whose centre has left it by more than two pitches are dropped. None keeps them all.

• floor – tiles fainter than this are dropped.

Returns:

(index, m11, m12, m21, m22, dx, dy, opacity): indices into the flying tiles and, for each, the affine matrix that places a tile drawn centred on the origin, and its opacity.

launched(t: float) → numpy.ndarray

Indices of every tile, flying or not, the front has reached.

Parameters:

t – seconds since the blow-away began.

Returns:

row-major tile indices.

class spacr.qt.widgets.loading_screen.LoadingScreen(total: int = 0, parent: PySide6.QtWidgets.QWidget | None = None)

Bases: PySide6.QtWidgets.QWidget

Full-window loading cover with optional photomosaic animation.

By default it shows the white mark beside the strap line. Once show_mosaic() is called it shows the spaCR photomosaic above the strap line instead, and blow_away() ends it by blowing the mosaic’s tiles off the window to reveal the window underneath.

Parameters:

• total – how many steps will be reported. Zero or negative means “unknown”, and the phases stay dim rather than dividing by it.

• parent – the window this fills. It is sized to the parent and resizes with it, rather than being a separate top-level – a second window would earn its own taskbar entry and could be dragged off the thing it is supposed to be covering.

Build the splash that covers the window while it is being assembled.

Opaque by construction: it covers a partly-built window, and any transparency would show the thing it exists to hide.

Parameters:

• total – how many steps the progress bar counts to; 0 shows no proportion.

• parent – the window to cover; its geometry is adopted.

advance(done: int | None = None) → None

Report progress. Without an argument, counts one more step.

blow_away(on_finished: Callable[[], None] | None = None, *, force: bool = False, plain: bool = False) → bool

End the cover by blowing the mosaic’s tiles off the window.

The logo holds until two seconds after the cover first painted (at once when called later than that), then blows away over four seconds: the black container fades from one to three seconds in and the last tile has gone at four. The cover deletes itself then.

Parameters:

• on_finished – called once, when the cover has gone.

• force – play even where startup_animation_allowed() says no; for the Help replay, tests and previews.

• plain – hold the logo, then cross-fade it and the container away in one second instead of blowing it away (Reduce motion).

Returns:

True when the blow-away will play and the cover will take itself down; False when it will not – no mosaic, the animation is off, or a click already asked to skip – and the caller takes the cover down as before.

container_opacity() → float

How opaque the black container behind the logo is now.

Returns:

1.0 until a second into the blow-away, then falling monotonically to 0.0 three seconds in (over the one second of the plain cross-fade under Reduce motion); 0.0 once the cover is done.

elapsed() → float

Seconds since the blow-away began; 0.0 before it has.

eventFilter(watched, event) → bool

Keep covering the window as it resizes.

A window that opens maximised is resized after the cover is put over it, and by then the window may have handed the cover to the blow-away and stopped sizing it.

Parameters:

• watched – the window this covers.

• event – the event; only a resize is acted on.

Returns:

False, so the window still sees every event.

fraction() → float

Completed share, 0.0 to 1.0. Zero when the total is unknown.

frame_stats() → dict

What drawing the blow-away cost, for measuring it.

Returns:

frames, the mean and the slowest frame’s paint time in milliseconds, and the most tiles drawn in one frame.

keyPressEvent(event) → None

A key while the blow-away runs skips it.

Parameters:

event – the Qt key event; accepted, so the key goes no further.

lit_phases() → int

How many of the three phases are lit at the current fraction.

The last phase lights only at completion, so a user never sees the sentence finished while work is still running.

mosaic_shown() → bool

Whether the cover shows the photomosaic.

mousePressEvent(event) → None

A click on the cover asks to skip the blow-away.

Parameters:

event – the Qt mouse event; accepted, so the click goes no further than the cover.

paintEvent(event) → None

Draw the loading state, or one frame of the blow-away.

Parameters:

event – the Qt paint event.

playing() → bool

Whether the blow-away is waiting to start or under way.

resizeEvent(event) → None

Re-centre the message for the new size.

Parameters:

event – the Qt resize event.

set_total(total: int) → None

Set the denominator; repaints if it changed.

Parameters:

total – number of steps the progress counts towards; converted to int and floored at 0, which means unknown and makes fraction() report 0.0.

show_mosaic(mosaic: MosaicMap | None = None) → bool

Show the photomosaic instead of the mark.

Parameters:

mosaic – the map to show; the packaged one by default.

Returns:

whether the mosaic is now shown. False when its files are missing, and the cover keeps the mark.

skip() → None

Skip to the end: take the cover down now, or as soon as allowed.

Before blow_away() it is remembered, and the cover then comes down without the animation when loading ends.

class spacr.qt.widgets.loading_screen.MosaicMap(image_path: str, grid: int, tile_px: int, occupied: numpy.ndarray)

The startup photomosaic’s picture and which of its tiles hold the logo.

Parameters:

• image_path – the picture, grid * tile_px pixels square.

• grid – tiles per side.

• tile_px – pixels per tile in the picture.

• occupied – grid x grid booleans, row-major; True where the tile holds the picture and flies, False for the dim background.

Hold the map; see the class docstring for the parameters.

classmethod load(directory: str | None = None) → MosaicMap | None

Read the tile map and check its picture is there.

Parameters:

directory – where the map and picture are; the packaged spacr/resources/splash by default.

Returns:

the map, or None when either file is missing or the map cannot be read – the loading cover then keeps its plain look.

spacr.qt.widgets.loading_screen.blow_away_running() → bool

Whether a blow-away is drawing its frames.

Idle-time warming asks this and waits, so its slices do not take frames from the animation in the four seconds it runs. While the logo only holds, the window keeps loading underneath it.

Returns:

True while any cover that still exists is past its hold and drawing; a cover deleted mid-way, with its window, no longer counts.

spacr.qt.widgets.loading_screen.mosaic_splash_wanted() → bool

Whether the loading cover shows the photomosaic.

Returns:

False when NO_SPLASH_ENV is set, otherwise True.

spacr.qt.widgets.loading_screen.replay_startup_animation(window: PySide6.QtWidgets.QWidget) → LoadingScreen | None

Play the startup sequence again inside window.

Help > Show startup animation. The black container with the logo comes back over the window, holds for two seconds and blows away as it does at startup. It plays even when Preferences > Appearance > Animation > Startup animation is off; under Preferences > Appearance > Accessibility > Reduce motion the logo holds and then cross-fades away in one second. A click or a key skips it. The window’s size, state and keyboard focus are left as they were.

Parameters:

window – the window to play it in.

Returns:

the cover now playing, or None when the logo cannot be read or a cover is already over the window.

spacr.qt.widgets.loading_screen.startup_animation_allowed() → bool

Whether the photomosaic may blow away when the window is ready.

No when NO_SPLASH_ENV is set, on the offscreen platform, while Preferences > Appearance > Accessibility > Reduce motion is on, or when Preferences > Appearance > Animation > Startup animation is off. An unreadable preference disables the animation.

Returns:

True when the blow-away should play.

spacr.qt.widgets.loading_screen.strap_line() → str

The whole strap line as one translated string.

spacr.qt.widgets.loading_screen.strap_phrases() → Sequence[str]

The strap line’s phases, translated, for the home screen to reuse.

The home screen shows the same sentence beside the same logo, so it takes the words from here rather than repeating them – one string, one place, one set of translation rows.

spacr.qt.widgets.loading_screen.will_blow_away(screen) → bool

Whether screen will end with the blow-away rather than vanish.

Parameters:

screen – the window’s loading cover, or anything standing in for it.

Returns:

True for a LoadingScreen showing the mosaic, not yet asked to skip, where startup_animation_allowed() says yes.