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

Hook point for consumer-controlled QQmlEngine ownership policy. More...

#include <PhosphorLayer/IQmlEngineProvider.h>

Public Member Functions

 IQmlEngineProvider ()=default
virtual ~IQmlEngineProvider ()=default
virtual QQmlEngine * engineForSurface (const SurfaceConfig &cfg)=0
 Return the engine for a surface being constructed.
virtual void releaseEngine (QQmlEngine *engine)=0
 Called when a Surface that previously received an engine is destroyed.

Detailed Description

Hook point for consumer-controlled QQmlEngine ownership policy.

Default (when SurfaceFactory::Deps::engineProvider is nullptr): every Surface that loads contentUrl content without a shared engine constructs its own QQmlEngine at warmUp() and destroys it in its own dtor. Full isolation — no cross-surface QML state leakage.

Opt-in sharing: implement this interface, return the same QQmlEngine pointer from every engineForSurface() call, and release it (or not) as you see fit. Singletons and type registrations become visible to all surfaces sharing the engine; that is the trade-off you make when you opt in.

Lifetime contract. A Surface asks for an engine only when it loads QML from SurfaceConfig::contentUrl. When it is destroyed it calls releaseEngine() later, from the event loop, once its window is gone. The provider must therefore outlive every Surface it served AND those deferred calls, or delete the engines it issued in its own destructor: the release is tied to the engine, so deleting the engine cancels it.

Constructor & Destructor Documentation

◆ IQmlEngineProvider()

PhosphorLayer::IQmlEngineProvider::IQmlEngineProvider ( )
default

◆ ~IQmlEngineProvider()

virtual PhosphorLayer::IQmlEngineProvider::~IQmlEngineProvider ( )
virtualdefault

Member Function Documentation

◆ engineForSurface()

virtual QQmlEngine * PhosphorLayer::IQmlEngineProvider::engineForSurface ( const SurfaceConfig & cfg)
pure virtual

Return the engine for a surface being constructed.

The provider may return:

  • a per-surface engine (construct a fresh one each call — mirrors the default behaviour but lets the consumer customise engine setup);
  • a shared engine (return the same pointer every time);
  • a pool-selected engine (e.g. one per Role, one per content URL, …).

The returned engine must outlive the Surface that receives it, up to the Surface's deferred releaseEngine() call.

◆ releaseEngine()

virtual void PhosphorLayer::IQmlEngineProvider::releaseEngine ( QQmlEngine * engine)
pure virtual

Called when a Surface that previously received an engine is destroyed.

Per-surface-engine providers typically delete engine. Shared-engine providers no-op. Pool providers may decrement a refcount.


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