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

One layer-shell surface with a managed lifecycle. More...

#include <PhosphorLayer/Surface.h>

Inheritance diagram for PhosphorLayer::Surface:
[legend]

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.

Detailed Description

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.

Lifecycle (state machine)

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.

Member Enumeration Documentation

◆ State

enum class PhosphorLayer::Surface::State
strong
Enumerator
Constructed 

Config accepted; no window yet.

Warming 

Engine / window / content initialising.

Shown 

Layer surface attached; window visible.

Hidden 

Attached but window hidden — show() is cheap.

Failed 

Unrecoverable (content error, transport rejected, …).

Constructor & Destructor Documentation

◆ ~Surface()

PhosphorLayer::Surface::~Surface ( )
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>.

◆ Surface()

PhosphorLayer::Surface::Surface ( CtorToken ,
SurfaceConfig cfg,
SurfaceDeps deps,
QObject * parent )
protected

Protected so subclasses can forward a CtorToken through their own constructor.

Still unreachable to consumers — CtorToken is SurfaceFactory-only-constructible.

Member Function Documentation

◆ config()

const SurfaceConfig & PhosphorLayer::Surface::config ( ) const
noexcept

◆ failed

void PhosphorLayer::Surface::failed ( const QString & reason)
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.

Safe to delete the Surface from this slot

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.

◆ hide

void PhosphorLayer::Surface::hide ( )
slot

◆ isLogicallyShown()

bool PhosphorLayer::Surface::isLogicallyShown ( ) const
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.

◆ screenLost

void PhosphorLayer::Surface::screenLost ( )
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.

Safe to delete the Surface from this slot

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.

◆ setKeyboardInteractivity()

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:

  • Exclusive requested before the first presented frame reaches the compositor with the first buffer, where focus-stealing prevention may refuse a new surface the focus. A consumer that needs the grab sets it after the first frame (ShellHost defers its grab the same way).
  • Dropping to None does not hand focus back: KWin keeps a surface active until it is destroyed or another window is activated, so a consumer that needs focus back hides or destroys the surface.

◆ show

void PhosphorLayer::Surface::show ( )
slot

◆ state()

State PhosphorLayer::Surface::state ( ) const
noexcept

◆ stateChanged

void PhosphorLayer::Surface::stateChanged ( State newState)
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.

◆ transport()

ITransportHandle * PhosphorLayer::Surface::transport ( ) const
noexcept

◆ warmUp

void PhosphorLayer::Surface::warmUp ( )
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.

◆ window()

QQuickWindow * PhosphorLayer::Surface::window ( ) const
noexcept

The documentation for this class was generated from the following file:
  • phosphor-layer/include/PhosphorLayer/Surface.h