#include <PhosphorOverlay/ShellHost.h>
Classes | |
| struct | SurfaceStateWants |
| What the consumer's live content wants from the shell surface on one screen. More... | |
Public Types | |
| using | SurfaceFactory = std::function<PhosphorLayer::Surface*(const QString& screenId, QScreen* physScreen)> |
| Consumer-provided factory for the per-screen layer-shell surface. | |
| using | PostCreateCallback = std::function<void(const QString& screenId, ShellState& state)> |
| Hook fired after a fresh shell surface + window are recorded in the ShellState. | |
| using | PreDestroyCallback = std::function<void(const QString& screenId)> |
| Hook fired before the library deletes the shell surface. | |
Public Member Functions | |
| ShellHost (QObject *parent=nullptr) | |
| ~ShellHost () override | |
| void | setSurfaceFactory (SurfaceFactory factory) |
| Inject the per-screen surface factory. | |
| void | setPostCreateCallback (PostCreateCallback callback) |
| Inject the post-create hook (optional but typically used). | |
| void | setPreDestroyCallback (PreDestroyCallback callback) |
| Inject the pre-destroy hook (optional). | |
| void | setSurfaceAnimator (PhosphorAnimationLayer::SurfaceAnimator *animator) |
| Inject the SurfaceAnimator that drives every slot's show/hide leg. | |
| ShellState * | ensureShell (const QString &screenId, QScreen *physScreen) |
| All methods on this class must be called on the GUI thread. | |
| void | destroyShell (const QString &screenId) |
Tear down the shell for screenId. | |
| void | syncSurfaceState (const QString &screenId, const SurfaceStateWants &wants) |
| Reconcile the shell's mapped state + pointer-input region with the consumer's view of what's live on this screen. | |
| bool | rekey (const QString &oldKey, const QString &newKey) |
Move the ShellState entry from oldKey to newKey, preserving the underlying heap-allocated state object (the borrowed pointer stored on the consumer's parallel per-screen state stays valid). | |
| void | registerConfigForRole (const PhosphorLayer::Role &role, PhosphorAnimationLayer::SurfaceAnimator::Config config) |
Register an animator config under role. | |
| void | hideSlot (const QString &screenId, const QString &slotKey, std::function< void()> completion={}) |
Animator-driven slot hide for the slot keyed by slotKey on the shell for screenId. | |
| ShellState & | getOrCreateStateFor (const QString &screenId) |
| Read-write accessor. | |
| const ShellState * | stateFor (const QString &screenId) const |
| Read-only accessor. | |
| bool | hasState (const QString &screenId) const |
True if a ShellState exists (live or zeroed) for screenId. | |
| void | removeState (const QString &screenId) |
Remove the ShellState for screenId entirely. | |
| QStringList | screenIds () const |
| Enumerate every screen id with a ShellState entry (in arbitrary QHash iteration order). | |
| void | markFailure (const QString &screenId) |
| Sticky per-screen creation-failure flag. | |
| void | clearFailure (const QString &screenId) |
| bool | hasFailure (const QString &screenId) const |
| QStringList | failureScreenIds () const |
| Snapshot of every screen id currently flagged as failed. | |
| using PhosphorOverlay::ShellHost::PostCreateCallback = std::function<void(const QString& screenId, ShellState& state)> |
Hook fired after a fresh shell surface + window are recorded in the ShellState.
Consumers use this to look up content slot Items by QML object name, wire up QML signal handlers, prime the rendering pipeline, and run any per-shell warm-up. Receives a mutable reference to the ShellState the library just populated.
| using PhosphorOverlay::ShellHost::PreDestroyCallback = std::function<void(const QString& screenId)> |
Hook fired before the library deletes the shell surface.
Consumers use this to drop their parallel per-screen state (e.g. content-mode sentinels, content geometry caches, signal-disconnection bookkeeping) so a stale signal handler firing during teardown doesn't dereference a dangling pointer.
Only fires when a live shell surface is being torn down - re-calls of destroyShell on an already-drained entry (shellSurface already nullptr) skip the callback. ~ShellHost's cleanup loop therefore won't re-enter consumer state that may have already started destruction.
| using PhosphorOverlay::ShellHost::SurfaceFactory = std::function<PhosphorLayer::Surface*(const QString& screenId, QScreen* physScreen)> |
Consumer-provided factory for the per-screen layer-shell surface.
The library does not know which Role / qmlSource / SurfaceManager the consumer wires through - the factory encapsulates all of that, returns the resulting Surface*, or nullptr on failure.
|
explicit |
|
override |
| void PhosphorOverlay::ShellHost::clearFailure | ( | const QString & | screenId | ) |
| void PhosphorOverlay::ShellHost::destroyShell | ( | const QString & | screenId | ) |
Tear down the shell for screenId.
Fires the pre-destroy callback before scheduling shellSurface for deletion via deleteLater. After return, the ShellState entry survives with every shell-mechanism field nulled - callers that want the entry removed entirely should follow up with removeState.
| ShellState * PhosphorOverlay::ShellHost::ensureShell | ( | const QString & | screenId, |
| QScreen * | physScreen ) |
All methods on this class must be called on the GUI thread.
It writes QQuickWindow flags and masks and issues Wayland protocol requests through the surface's transport, none of which is safe off-thread. The constraint is an obligation on the consumer, not something the class enforces or detects.
Idempotent: bring up (or return) the per-screen shell for screenId on physScreen. Returns a pointer to the ShellState on success. Returns nullptr when:
When the sticky-failure flag is set and a state object already exists (e.g. from a prior getOrCreateStateFor or a previously-live shell that was torn down), returns that existing state with shellSurface() == nullptr. Callers that need to retry must call clearFailure first.
On the cached-live path (state exists and shellSurface() is non-null), the state's physScreen() is refreshed to the argument so callers that read it always see the most recent ensureShell call's value, and shellWindow() is re-read from Surface::window() alongside it.
The PostCreateCallback runs with the state's mechanism fields already populated, and its return value is the pointer this function hands back. It may call destroyShell for the same screen — the daemon does exactly that to tear down a half-wired shell — in which case the returned state is non-null with shellSurface() == nullptr. It must NOT call removeState or rekey for that screen, since both delete the object the caller is about to receive.
| QStringList PhosphorOverlay::ShellHost::failureScreenIds | ( | ) | const |
Snapshot of every screen id currently flagged as failed.
Used by hot-plug cleanup paths that need to clear sentinels by consumer- specific id schemes (e.g. clear every virtual-screen id rooted on a now-removed physical monitor) without burdening the library with the consumer's id grammar.
| ShellState & PhosphorOverlay::ShellHost::getOrCreateStateFor | ( | const QString & | screenId | ) |
Read-write accessor.
Returns the existing ShellState for screenId, default-constructing one in place if absent so callers can populate fields without an explicit insert. Named getOrCreateStateFor (not stateFor) to make the materialisation contract explicit — a stateFor(...) call that silently inserted a fresh entry on miss could surprise readers expecting a pure accessor. Pair with hasState if "peek without materialising" is the intent.
| bool PhosphorOverlay::ShellHost::hasFailure | ( | const QString & | screenId | ) | const |
| bool PhosphorOverlay::ShellHost::hasState | ( | const QString & | screenId | ) | const |
True if a ShellState exists (live or zeroed) for screenId.
| void PhosphorOverlay::ShellHost::hideSlot | ( | const QString & | screenId, |
| const QString & | slotKey, | ||
| std::function< void()> | completion = {} ) |
Animator-driven slot hide for the slot keyed by slotKey on the shell for screenId.
completion fires:
Completion is dropped when the call is a programmer-setup error: animator not injected, empty screenId, or empty slotKey - none have a recovery path the consumer could take.
It is ALSO dropped when the hide leg is cancelled before it settles, which the animator does per its own cancellation contract. Hiding the shell surface cancels every leg on that surface, and so does destroying it, so a syncSurfaceState that unmaps the surface or a destroyShell landing while a slot hide is in flight will strand whatever that completion was going to clean up. Consumers must not rely on this completion as the only path that clears parallel per-screen state across a teardown.
| void PhosphorOverlay::ShellHost::markFailure | ( | const QString & | screenId | ) |
Sticky per-screen creation-failure flag.
Once set, subsequent create attempts on screenId short-circuit until cleared (typically on screen hot-plug). Mirrors the legacy OverlayService::m_notificationCreationFailed semantics.
| void PhosphorOverlay::ShellHost::registerConfigForRole | ( | const PhosphorLayer::Role & | role, |
| PhosphorAnimationLayer::SurfaceAnimator::Config | config ) |
Register an animator config under role.
Pass-through to PhosphorAnimationLayer::SurfaceAnimator::registerConfigForRole so consumers route every animator-config write through the same host that owns the slot vocabulary. No-op when the SurfaceAnimator has not been injected.
| bool PhosphorOverlay::ShellHost::rekey | ( | const QString & | oldKey, |
| const QString & | newKey ) |
Move the ShellState entry from oldKey to newKey, preserving the underlying heap-allocated state object (the borrowed pointer stored on the consumer's parallel per-screen state stays valid).
Returns true on success; returns false when:
That drop DELETES the stale state object, so this is a third delete site alongside the destructor and removeState, and any borrowed pointer to the newKey entry dies with it. No PreDestroyCallback fires for it — the dropped entry is non-live by construction, and the callback is gated on a live shell surface, so removeState would not fire one for the same entry either.
On success the sticky creation-failure flag at newKey is cleared, since a live shell now backs that key. oldKey's flag is deliberately left alone.
Same-key (oldKey == newKey) is idempotent success: returns true iff a live entry exists under that key. The entry is at newKey after the call - the bool reports "the postcondition holds", not "a move happened".
Surface re-anchoring is the consumer's responsibility: the layer surface's anchors / margins were baked in at attach time for oldKey, so a flavor-changing rekey (e.g. physical → virtual screen) requires the consumer to push corrected placement through the surface transport after a successful rekey. Consumers that don't need re-anchoring (same-screen identifier drift) can ignore the post-rekey step.
| void PhosphorOverlay::ShellHost::removeState | ( | const QString & | screenId | ) |
Remove the ShellState for screenId entirely.
The library does NOT delete the shellSurface pointer - the caller's destroy pathway is expected to schedule that via deleteLater first.
| QStringList PhosphorOverlay::ShellHost::screenIds | ( | ) | const |
Enumerate every screen id with a ShellState entry (in arbitrary QHash iteration order).
| void PhosphorOverlay::ShellHost::setPostCreateCallback | ( | PostCreateCallback | callback | ) |
Inject the post-create hook (optional but typically used).
| void PhosphorOverlay::ShellHost::setPreDestroyCallback | ( | PreDestroyCallback | callback | ) |
Inject the pre-destroy hook (optional).
| void PhosphorOverlay::ShellHost::setSurfaceAnimator | ( | PhosphorAnimationLayer::SurfaceAnimator * | animator | ) |
Inject the SurfaceAnimator that drives every slot's show/hide leg.
Required before any hideSlot call. Borrowed pointer - the lib does not own the animator; composition roots typically own a single instance and thread it through every consumer.
| void PhosphorOverlay::ShellHost::setSurfaceFactory | ( | SurfaceFactory | factory | ) |
Inject the per-screen surface factory.
Required before any ensureShell call; the library has no built-in surface creation pipeline.
| const ShellState * PhosphorOverlay::ShellHost::stateFor | ( | const QString & | screenId | ) | const |
Read-only accessor.
Returns nullptr if no state exists for screenId - callers that need to peek without materializing an empty entry should use this overload.
| void PhosphorOverlay::ShellHost::syncSurfaceState | ( | const QString & | screenId, |
| const SurfaceStateWants & | wants ) |
Reconcile the shell's mapped state + pointer-input region with the consumer's view of what's live on this screen.
wants.visible - true when at least one slot wants the surface mapped (driven by the consumer's slot-visibility check). Drives the Surface state machine in both directions: show() on false→true, hide() on true→false. The behavior of hide() is governed by the SurfaceConfig the consumer registered: keepMappedOnHide=false (the default) unmaps the wl_surface synchronously so the shell stops being composited when idle; keepMappedOnHide=true keeps it mapped and click-through. A shell whose slots carry their own transitions should set SurfaceConfig::animateRoot=false. Either way Surface's show and hide edges cancel EVERY animator track keyed on the shell surface, slot tracks included, without running their completions. So the consumer must call Surface::show() itself before dispatching a slot's beginShow, and must only report wants.visible false once every slot's hide leg has completed.
wants.inputGrabbing - true when at least one modal slot (consumer-defined; Phosphor today: snap-assist, layout picker and the cheatsheet) wants pointer input. When false, OR when wants.visible is false, the shell's QQuickWindow is flagged Qt::WindowTransparentForInput so background windows stay interactable beneath non-modal slots (OSDs, main overlay, zone selector during drag). The wants.visible term means this does not rest on the caller guaranteeing that a grabbing slot is a visible one: a grab with nothing visible would otherwise hand an unseen surface every click on the screen.
Input is all-or-nothing for the whole shell surface: a visible modal grab takes every click the surface covers, and anything else leaves it click-through. Every passive slot shares one screen-sized surface, so a slot wanting clicks only where it draws would need a sub-surface input region, which nothing asks for today.
wants.keyboardGrabbing - true when at least one slot needs to TYPE (consumer-defined; Phosphor today: the cheatsheet's search field). Drives the layer surface's keyboard interactivity between Exclusive and None at runtime, which wlr-layer-shell permits after the initial configure. Separate from wants.inputGrabbing because the two are genuinely different asks: snap-assist and the layout picker are modal for the pointer but must NOT take the keyboard away from the focused toplevel, since they are driven entirely by global shortcuts the compositor routes before any surface sees them.
Exclusive rather than OnDemand: a slot that wants the keyboard was opened by an explicit user gesture and expects to receive the next keystroke, not to be clicked into first. The cost is that the focused window stops receiving keys for the slot's lifetime, so consumers must drop the flag on the FIRST edge of dismissal rather than waiting for a hide animation to finish.
Gated on wants.visible for the same reason the input flag is: an invisible surface must never hold the session's keyboard.
While the surface has not yet presented a frame since it last mapped (whether this call or the consumer's own Surface::show() mapped it), the Exclusive request is held until that frame, then sent as a runtime change. Arriving with the first buffer, KWin would decide activation under its focus-stealing prevention and could leave the keyboard with the window the user came from. Every call re-decides, and a hide drops a request still waiting. Releasing to None is cosmetic under KWin, which moves focus on only when the surface unmaps.
Per-screen, with no cross-screen arbitration: this call reads and writes one screen's state and nothing else. When the keyboard-grabbing slot MOVES between screens, the consumer must call this for the screen being LEFT as well as the one being entered. Syncing the new screen does not release the old one, and two surfaces asking for an exclusive keyboard at once is resolved by the compositor, not here.
No-op when the shell surface or window is not yet up, and the keyboard write is additionally skipped when the surface has not attached yet (null transport handle) — harmless, since the role attaches kbd-None.
Taken as a struct rather than three bools in a row: the three are independent, same-typed, and a transposition would compile silently while producing exactly the failure this doc block warns about (a pointer-modal slot taking the keyboard from the focused window). Designated initialisers at the call site name each one.