One layer-shell surface with a managed lifecycle. More...
#include <PhosphorLayer/Surface.h>
Classes | |
| class | CtorToken |
| Opaque construction token — only SurfaceFactory can create instances of it. More... | |
Public Types | |
| enum class | State { Constructed , Warming , Shown , Hidden , Failed } |
Public Slots | |
Lifecycle | |
Safe to call in any state; invalid transitions warn and no-op. hide() and warmUp() are no-ops when the surface is already in the state they ask for. show() on a Shown surface is not: it replays the root show animation (the root snaps transparent and fades back in) unless SurfaceConfig::animateRoot is false. Declared as Q_SLOTS so consumers can wire QML-side signals (e.g. a dismissTimer's dismissRequested()) directly via the string-based QObject::connect(window, SIGNAL(foo()), surface, SLOT(hide())) syntax. QML-defined signals can't be addressed via Qt5 &Class::signal pointers, so the string form is the only path — without Q_SLOT registration the connect would silently fail at runtime. | |
| void | show () |
| void | hide () |
| void | warmUp () |
| Create window + content (and, for contentUrl content, the engine that loads it), leave hidden. | |
Signals | |
| void | stateChanged (State newState) |
| NOTIFY signal for the state Q_PROPERTY. | |
| void | failed (const QString &reason) |
| Emitted once when transitioning to State::Failed. | |
| void | screenLost () |
| Emitted when the QScreen the Surface is bound to is removed from the IScreenProvider's list or destroyed, in any state but Failed. | |
Public Member Functions | |
| ~Surface () override | |
| Q_ENUM so QMetaEnum can stringify State values in log messages (State::Failed → "Failed") and so Q_PROPERTY / QSignalSpy introspection works. | |
| State | state () const noexcept |
| const SurfaceConfig & | config () const noexcept |
| void | setKeyboardInteractivity (KeyboardInteractivity keyboard) |
| Change the surface's keyboard interactivity. | |
| bool | isLogicallyShown () const noexcept |
| Convenience: is the Surface in the logical "shown" state? | |
Escape hatches | |
Prefer the declarative API. These are for consumers that need to reach into Qt machinery (installing event filters, connecting to window-specific signals, etc.). | |
| QQuickWindow * | window () const noexcept |
| ITransportHandle * | transport () const noexcept |
Protected Member Functions | |
| Surface (CtorToken, SurfaceConfig cfg, SurfaceDeps deps, QObject *parent) | |
| Protected so subclasses can forward a CtorToken through their own constructor. | |
One layer-shell surface with a managed lifecycle.
Owns its QQuickWindow and, for contentUrl content loaded without a shared or provider engine, its QQmlEngine. Constructed only via SurfaceFactory so injected dependencies can travel with it.
| From | Event | To |
|---|---|---|
| Constructed | warmUp() | Warming |
| Constructed | show() | Warming |
| Warming | (content ready) | Hidden |
| Hidden | (intent=show pending) | Shown |
| Warming | (content error) | Failed |
| Hidden | show() | Shown |
| Shown | hide() | Hidden |
| any | (transport rejected) | Failed |
A first show() therefore emits stateChanged three times, Warming, then Hidden, then Shown: the surface attaches hidden and only then maps.
Invalid transitions (e.g. show() from Failed) log qCWarning with the debugName and no-op. They never throw.
Topology-driven respawn (screen removal / compositor restart) is the consumer's responsibility, not the library's: subscribe to TopologyCoordinator callbacks or use ScreenSurfaceRegistry::syncToScreens to decide when to destroy and rebuild surfaces. Surface observes the removal of its own screen and reports it through screenLost, but it never destroys or rebuilds itself, so consumers retain full control over the save-state-before-destroy sequencing.
hide() is synchronous from the caller's perspective. Under the default policy the window is unmapped immediately; under SurfaceConfig::keepMappedOnHide it stays mapped and is made transparent to input instead. We do not expose a transient "Hiding" state because the compositor's acknowledgement is invisible to application code and the surface is unusable until it's either Shown again or recreated.
|
strong |
|
override |
Q_ENUM so QMetaEnum can stringify State values in log messages (State::Failed → "Failed") and so Q_PROPERTY / QSignalSpy introspection works.
Not currently registered with QML — consumers that want to bind surface state from QML should register the type themselves via qmlRegisterUncreatableType<Surface>.
|
protected |
|
noexcept |
|
signal |
Emitted once when transitioning to State::Failed.
reason is a human-readable diagnostic (QML compile error, transport rejection, etc.). Surface remains in Failed thereafter.
The library defers this signal via Qt::QueuedConnection so consumer slots that call delete surface do not re-enter library code on a dead this. The stateChanged(Failed) that precedes it is delivered from the same deferred call and is delete-safe too (failed() is then not emitted). For non-failure stateChanged emissions the consumer must prefer deleteLater() over delete.
|
slot |
|
nodiscardnoexcept |
Convenience: is the Surface in the logical "shown" state?
Equivalent to state() == State::Shown and exists to give consumers a single canonical answer to "is this overlay currently the user's view of itself" regardless of the underlying lifecycle.
Under SurfaceConfig::keepMappedOnHide=true, the QQuickWindow stays Qt-visible across logical hide/show cycles — window()->isVisible() is therefore NOT a reliable signal for "currently shown" because it stays true while the surface is logically Hidden under Qt::WindowTransparentForInput. This helper is the right answer for every lifecycle: keep-mapped surfaces consult Surface state (false during the transparent-for-input span); unmap-on-hide surfaces that stay alive across hides agree with window()->isVisible(); destroy-on-hide surfaces are simply gone from the consumer's tracking when hidden, so the call site never reaches isLogicallyShown() on a destroyed Surface.
|
signal |
Emitted when the QScreen the Surface is bound to is removed from the IScreenProvider's list or destroyed, in any state but Failed.
The Surface stays in its current state and config().screen reads nullptr. An ATTACHED surface (Shown or Hidden) stays bound to the removed output until the consumer destroys and recreates it; a surface not yet attached (Constructed or Warming) attaches to the provider's primary unless the consumer destroys it first. Consumers decide whether to destroy+rebuild or wait for the screen to come back.
The library defers this signal via Qt::QueuedConnection so consumer slots that call delete surface do not re-enter library code on a dead this. Deleting the Surface from a stateChanged slot for non-Failed transitions remains UB — prefer deleteLater() there.
| void PhosphorLayer::Surface::setKeyboardInteractivity | ( | KeyboardInteractivity | keyboard | ) |
Change the surface's keyboard interactivity.
On an attached surface it takes effect live, through the transport handle, which commits it. Called before the first attach, it sets the policy the surface attaches with. config().effectiveKeyboard() reports the last value set either way. An out-of-range value, or a call on a Failed surface, warns and is ignored.
Two compositor behaviours to design around, both seen under KWin:
|
slot |
|
noexcept |
|
signal |
NOTIFY signal for the state Q_PROPERTY.
Carries the new state so slots don't need a round-trip getter call. The previous state is not exposed — track it in your slot if you need it.
|
noexcept |
|
slot |
Create window + content (and, for contentUrl content, the engine that loads it), leave hidden.
Pre-compiles QML so the first show() is latency-free.
|
noexcept |