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

#include <PhosphorEngine/IWindowRegistry.h>

Inheritance diagram for PhosphorEngine::IWindowRegistry:
[legend]

Public Member Functions

virtual ~IWindowRegistry ()=default
virtual QString canonicalizeWindowId (const QString &rawWindowId)=0
 Freeze (on first contact) and return the canonical id for rawWindowId's instance.
virtual QString canonicalizeForLookup (const QString &rawWindowId) const =0
virtual QString appIdFor (const QString &instanceId) const =0
 The app identity recorded for instanceId, or empty when the instance is unknown.
virtual std::optional< bool > minimizedState (const QString &windowId) const
 Tri-state compositor minimize state for windowId.
virtual std::optional< WindowDesktopContext > desktopContext (const QString &windowId) const
 The desktop set and activity last reported for windowId (bare instance id or composite appId|instanceId), or nullopt when the window is unknown.
virtual std::optional< bool > fillsOutputState (const QString &windowId) const
 Whether windowId is maximized on either axis or fullscreen as last reported: engaged true when any of those is on, engaged false when the full maximize and fullscreen are both known off, nullopt when either was never delivered or the window is unknown.

Constructor & Destructor Documentation

◆ ~IWindowRegistry()

virtual PhosphorEngine::IWindowRegistry::~IWindowRegistry ( )
virtualdefault

Member Function Documentation

◆ appIdFor()

virtual QString PhosphorEngine::IWindowRegistry::appIdFor ( const QString & instanceId) const
pure virtual

The app identity recorded for instanceId, or empty when the instance is unknown.

Takes a BARE instance id: unlike minimizedState, which accepts either form, this does not split a composite appId|instanceId and answers empty for one. Callers holding a window id should extract the instance part first (or use a service-level currentAppIdFor, which does it for them).

Implemented in PhosphorEngine::WindowRegistry.

◆ canonicalizeForLookup()

virtual QString PhosphorEngine::IWindowRegistry::canonicalizeForLookup ( const QString & rawWindowId) const
pure virtual

◆ canonicalizeWindowId()

virtual QString PhosphorEngine::IWindowRegistry::canonicalizeWindowId ( const QString & rawWindowId)
pure virtual

Freeze (on first contact) and return the canonical id for rawWindowId's instance.

The mapping is seeded once and never re-seeded, so a mid-session class mutation keeps resolving to the identity the stores were keyed with. That single stable key per window, for the window's whole life, is the invariant every keyed store depends on: engines key their membership maps at adopt time and have no re-key path, so an implementation that let the canonical CHANGE mid-life would strand live state rather than correct it.

The freeze is deliberately unconditional, including for an id whose appId part is empty (KWin reports a blank class for a surface it has not finished mapping). Callers needing a window's app identity must ask appIdFor / currentAppIdFor, which read the metadata record and self-correct when the class arrives, rather than parsing it back out of the frozen id. An empty id, or one with no instance part ("appId|"), names no window and comes back unchanged without being frozen.

Implemented in PhosphorEngine::WindowRegistry.

◆ desktopContext()

virtual std::optional< WindowDesktopContext > PhosphorEngine::IWindowRegistry::desktopContext ( const QString & windowId) const
inlinevirtual

The desktop set and activity last reported for windowId (bare instance id or composite appId|instanceId), or nullopt when the window is unknown.

Default reports unknown, like minimizedState. Consumers then treat the window's desktops as unknown instead of inventing them: the snap restore, for one, takes the record's own desktop when it names a zone there, else the screen's, and the persisted-zone seed drops none of the desktops the record names.

Reimplemented in PhosphorEngine::WindowRegistry.

◆ fillsOutputState()

virtual std::optional< bool > PhosphorEngine::IWindowRegistry::fillsOutputState ( const QString & windowId) const
inlinevirtual

Whether windowId is maximized on either axis or fullscreen as last reported: engaged true when any of those is on, engaged false when the full maximize and fullscreen are both known off, nullopt when either was never delivered or the window is unknown.

Such a window's frame is the output (on one axis at least), not a free position, and only the compositor knows its restore rect. Default reports unknown, like minimizedState.

Reimplemented in PhosphorEngine::WindowRegistry.

◆ minimizedState()

virtual std::optional< bool > PhosphorEngine::IWindowRegistry::minimizedState ( const QString & windowId) const
inlinevirtual

Tri-state compositor minimize state for windowId.

Engaged true/false when the compositor has reported the window's minimize state; std::nullopt when it is UNKNOWN (no record for the window, or the metadata push never carried the field). SEEDING and TILING consumers — anything that would place, move, or count a window in a layout — must treat nullopt conservatively rather than as false: collapsing unknown into "not minimized" is the fail-open that seeds hidden windows into tiling layouts and persists minimize-suspension floats. CAPTURE-side consumers may deliberately require engaged-true (.value_or(false)) when their traffic is causally ordered after the minimize edge's metadata push (the snap pre-snap capture / recordFloatingClose document this per site) — refusing a capture on unknown would lose genuine free positions, the opposite failure.

Default implementation reports unknown so registry-less engines and test fakes stay honest instead of claiming visibility.

Reimplemented in PhosphorEngine::WindowRegistry.


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