Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorShell::ShellEngine Class Reference

#include <PhosphorShell/ShellEngine.h>

Inheritance diagram for PhosphorShell::ShellEngine:
[legend]

Classes

struct  Deps

Public Types

using EngineHook = std::function<void(QQmlEngine*)>
 Register a callback that fires whenever a fresh QQmlEngine is created — at startup AND on hot-reload (file watcher triggers rebuild).

Public Slots

void requestReload ()
 Coalesced rebuild for configuration changes affecting surface geometry.

Signals

void aboutToReload ()
 Emitted at the very top of a hot reload, BEFORE any teardown.
void loaded ()
 A successful load() call.
void reloaded ()
 A successful rebuild after a file or screen change, including the first successful build following a failed load().
void failed (const QString &reason)
 Something went wrong, with a human-readable reason.

Public Member Functions

 ShellEngine (Deps deps, QObject *parent=nullptr)
 ~ShellEngine () override
bool load (const QUrl &shellUrl)
 Build the shell from shellUrl.
QQmlEngine * engine () const
 The current QML engine, or null before a successful load and after a failed one.
void addEngineHook (EngineHook hook)
QMargins reservedMarginsFor (QScreen *screen) const
 The space this shell's own panels reserve on screen, per edge: the largest exclusive zone advertised to the compositor on each edge by a materialized panel there.

Member Typedef Documentation

◆ EngineHook

using PhosphorShell::ShellEngine::EngineHook = std::function<void(QQmlEngine*)>

Register a callback that fires whenever a fresh QQmlEngine is created — at startup AND on hot-reload (file watcher triggers rebuild).

Use this to install image providers, register engine-scoped singletons, or set additional context properties without forcing ShellEngine to depend on the modules that supply them. The callback is invoked synchronously, in registration order, after the engine's own context properties are set but before any QML is loaded.

A hook must tolerate being called for an engine that is destroyed moments later: hooks run before the QML is parsed, and a load that then fails tears that engine down immediately.

Hooks cannot be removed, and the list is replayed on every reload, so EVERYTHING A HOOK CAPTURES MUST OUTLIVE THIS ShellEngine. For a hook capturing stack objects that means declaring them before the engine, so reverse destruction takes the engine first.

Registering a hook from inside a hook is permitted but does not join the pass already running: addEngineHook invokes a late arrival itself when an engine already exists, and the in-flight loop deliberately does not pick it up, so it runs exactly once for that engine.

Constructor & Destructor Documentation

◆ ShellEngine()

PhosphorShell::ShellEngine::ShellEngine ( Deps deps,
QObject * parent = nullptr )
explicit

◆ ~ShellEngine()

PhosphorShell::ShellEngine::~ShellEngine ( )
override

Member Function Documentation

◆ aboutToReload

void PhosphorShell::ShellEngine::aboutToReload ( )
signal

Emitted at the very top of a hot reload, BEFORE any teardown.

loaded, reloaded and failed all report after the fact, which is useless to anything holding objects built from the outgoing QQmlEngine: by the time they fire, that engine and every object it created are gone. A consumer that owns engine-scoped state (a popout transport holding live surfaces, say) needs a chance to drain while the graph is still valid.

Covers RELOAD only, not destruction: ~ShellEngine tears down without emitting anything, so a consumer must also drain from its own shutdown path (QGuiApplication::aboutToQuit, or before the engine goes out of scope). Nor is it paired one-to-one with reloaded: a reload whose rebuild fails emits this and then failed, never reloaded, and the next file change emits it again, so the drain must be idempotent.

◆ addEngineHook()

void PhosphorShell::ShellEngine::addEngineHook ( EngineHook hook)

◆ engine()

QQmlEngine * PhosphorShell::ShellEngine::engine ( ) const
nodiscard

The current QML engine, or null before a successful load and after a failed one.

NON-OWNING, and NOT STABLE: every hot reload destroys this engine and builds a fresh one, so a cached pointer dangles after the first file save. Anything that must survive a reload belongs in an engine hook, which is re-run against each new engine.

◆ failed

void PhosphorShell::ShellEngine::failed ( const QString & reason)
signal

Something went wrong, with a human-readable reason.

Two POSTCONDITIONS share this signal. A rejected call (empty URL, null dependency, a second load()) leaves any running shell untouched and engine() non-null. A failed build has already torn everything down and leaves engine() null. Check engine() to tell them apart before deciding whether to retry, fall back or exit.

◆ load()

bool PhosphorShell::ShellEngine::load ( const QUrl & shellUrl)

Build the shell from shellUrl.

Returns true once the QML root and every panel surface exist.

SINGLE-SHOT for anything past the argument checks. The early guards (empty URL, null dependency) leave the object untouched and CAN be retried; a failure inside the build cannot, and a second call is refused with failed. Recovery from that is a fresh ShellEngine, not a retry on this one.

On failure failed carries the reason. Note the two shapes it comes in: a rejected call leaves a previously loaded shell running and engine() non-null, while a failed build tears everything down and leaves engine() null. engine() is the discriminator.

After a failed FIRST load the file watcher stays armed, so editing the file recovers. That recovery reports reloaded, never loaded: loaded is emitted only by a successful load() call. A consumer that mounts its UI on loaded alone stays dark after one bad shell.qml.

◆ loaded

void PhosphorShell::ShellEngine::loaded ( )
signal

A successful load() call.

Emitted at most once per instance, and NOT emitted when a shell that failed its first load later recovers through the watcher; that reports reloaded. A consumer that mounts on loaded alone stays dark after one bad shell.qml.

◆ reloaded

void PhosphorShell::ShellEngine::reloaded ( )
signal

A successful rebuild after a file or screen change, including the first successful build following a failed load().

◆ requestReload

void PhosphorShell::ShellEngine::requestReload ( )
slot

Coalesced rebuild for configuration changes affecting surface geometry.

◆ reservedMarginsFor()

QMargins PhosphorShell::ShellEngine::reservedMarginsFor ( QScreen * screen) const
nodiscard

The space this shell's own panels reserve on screen, per edge: the largest exclusive zone advertised to the compositor on each edge by a materialized panel there.

Zero on every edge for a screen with no reserving panel, and for a null screen.

For a popout that wants to hang from the bar rather than float mid- screen: its surface is full-bleed and cannot ask the compositor where the bar ends, but this engine placed the bar and knows. Read live, so a reload that changes a panel's thickness is reflected on the next open.


The documentation for this class was generated from the following file: