PhosphorOverlay::ShellHost Class Reference

#include <phosphor-overlay/include/PhosphorOverlay/ShellHost.h>

Inheritance diagram for PhosphorOverlay::ShellHost:

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)
	Idempotent: bring up (or return) the per-screen shell for screenId on physScreen.
void	destroyShell (const QString &screenId)
	Tear down the shell for screenId.
void	syncSurfaceState (const QString &screenId, bool anyVisible, bool anyInputGrabbing)
	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 &	stateFor (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.

Member Typedef Documentation

PostCreateCallback

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.

PreDestroyCallback

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.

SurfaceFactory

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.

Constructor & Destructor Documentation

ShellHost()

PhosphorOverlay::ShellHost::ShellHost ( QObject *  parent = nullptr )

explicit

~ShellHost()

PhosphorOverlay::ShellHost::~ShellHost ( )

override

Member Function Documentation

clearFailure()

void PhosphorOverlay::ShellHost::clearFailure

(

const QString &

screenId

)

destroyShell()

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.

ensureShell()

ShellState * PhosphorOverlay::ShellHost::ensureShell	(	const QString &	screenId,
		QScreen *	physScreen
	)

Idempotent: bring up (or return) the per-screen shell for screenId on physScreen.

Returns a pointer to the ShellState on success. Returns nullptr when:

• the factory is unset, or
• the factory was called and returned nullptr (sticky-failure flag set automatically), AND no state object had been materialized for that screen before.

When the sticky-failure flag is set and a state object already exists (e.g. from a prior stateFor 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.

failureScreenIds()

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.

hasFailure()

bool PhosphorOverlay::ShellHost::hasFailure

(

const QString &

screenId

)

const

hasState()

bool PhosphorOverlay::ShellHost::hasState

(

const QString &

screenId

)

const

True if a ShellState exists (live or zeroed) for screenId.

hideSlot()

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:

• asynchronously, on the hide-leg's settle, when the slot was visible and the animator ran the transition;
• synchronously, before this call returns, when nothing needed to animate (no shell, no slot under that key, slot Item gone, slot Item not currently visible) - consumer post-hide cleanup (clear loader mode, release content state, restore siblings) runs in either case.

Completion is dropped only 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.

markFailure()

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.

registerConfigForRole()

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.

rekey()

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:

• oldKey has no live shell (no entry or shellSurface is nullptr)
• newKey already has a LIVE entry (refuses to clobber); a stale zeroed entry under newKey is dropped to make room.

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.

removeState()

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.

screenIds()

QStringList PhosphorOverlay::ShellHost::screenIds

(

)

const

Enumerate every screen id with a ShellState entry (in arbitrary QHash iteration order).

setPostCreateCallback()

void PhosphorOverlay::ShellHost::setPostCreateCallback

(

PostCreateCallback

callback

)

Inject the post-create hook (optional but typically used).

setPreDestroyCallback()

void PhosphorOverlay::ShellHost::setPreDestroyCallback

(

PreDestroyCallback

callback

)

Inject the pre-destroy hook (optional).

setSurfaceAnimator()

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.

setSurfaceFactory()

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.

stateFor() [1/2]

ShellState & PhosphorOverlay::ShellHost::stateFor

(

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.

stateFor() [2/2]

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.

syncSurfaceState()

void PhosphorOverlay::ShellHost::syncSurfaceState	(	const QString &	screenId,
		bool	anyVisible,
		bool	anyInputGrabbing
	)

Reconcile the shell's mapped state + pointer-input region with the consumer's view of what's live on this screen.

anyVisible - 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=true keeps the wl_surface mapped (animator drives root opacity to 0); keepMappedOnHide=false unmaps the wl_surface synchronously so the shell stops being composited when idle. The shell surface's role typically has no animator Config registered, so per-surface cancel/beginHide collapse to no-ops and do not interfere with per-slot animator state (which lives on different keys).

anyInputGrabbing - true when at least one modal slot (consumer-defined; PZ today: snap-assist + layout picker) wants pointer input. When 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).

No-op when the shell surface or window is not yet up.

---

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

• phosphor-overlay/include/PhosphorOverlay/ShellHost.h