PhosphorEngine::WindowRegistry Class Reference

#include <phosphor-engine/include/PhosphorEngine/WindowRegistry.h>

Inheritance diagram for PhosphorEngine::WindowRegistry:

Classes
struct	WindowContext
	The window's own context for per-window mode resolution: its virtual desktop (0 = all/unknown), the full desktop list when it spans several (empty otherwise), and activity (empty = all/unknown), read without copying the full ~30-field metadata record — this sits on the per-query float-resolver path. More...

Signals
void	windowAppeared (const QString &instanceId)
void	metadataChanged (const QString &instanceId, const WindowMetadata &oldMetadata, const WindowMetadata &newMetadata)
void	windowDisappeared (const QString &instanceId)

Public Member Functions
	WindowRegistry (QObject *parent=nullptr)
	~WindowRegistry () override
void	upsert (const QString &instanceId, const WindowMetadata &metadata)
void	remove (const QString &instanceId)
	Remove metadata and canonical state, emitting windowDisappeared exactly once while the canonical mapping remains available to subscribers.
std::optional< WindowMetadata >	metadata (const QString &instanceId) const
std::optional< WindowContext >	windowContext (const QString &instanceId) const
QString	appIdFor (const QString &instanceId) const override
	The app identity recorded for instanceId, or empty when the instance is unknown.
bool	isMinimized (const QString &windowId) const
	Live compositor minimize state, collapsed to a bool: unknown reads as false.
std::optional< bool >	minimizedState (const QString &windowId) const override
	Tri-state minimize state (IWindowRegistry contract): engaged when a record exists AND the compositor reported the field; nullopt when the window is unknown or the field was never delivered.
QStringList	instancesWithAppId (const QString &appId) const
	Every instance currently recorded under appId, in UNSPECIFIED order (QMultiHash bucket order, not insertion or arrival order).
bool	contains (const QString &instanceId) const
int	size () const
void	clear ()
	Remove every record and canonical mapping, firing windowDisappeared for each.
QString	canonicalizeWindowId (const QString &rawWindowId) override
	Freeze (on first contact) and return the canonical id for rawWindowId's instance.
QString	canonicalizeForLookup (const QString &rawWindowId) const override
int	pruneStaleInstances (const QSet< QString > &aliveInstanceIds)
	Defensive cleanup for windows that died WITHOUT a close signal reaching the registry (compositor crash, lost D-Bus call): drop every metadata record AND canonical-id translation whose instance id is absent from aliveInstanceIds, firing windowDisappeared for each so subscribers (e.g.
Public Member Functions inherited from PhosphorEngine::IWindowRegistry
virtual	~IWindowRegistry ()=default

Constructor & Destructor Documentation

WindowRegistry()

PhosphorEngine::WindowRegistry::WindowRegistry ( QObject *  parent = nullptr )

explicit

~WindowRegistry()

PhosphorEngine::WindowRegistry::~WindowRegistry ( )

override

Member Function Documentation

appIdFor()

QString PhosphorEngine::WindowRegistry::appIdFor ( const QString &  instanceId ) const

overridevirtual

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).

Implements PhosphorEngine::IWindowRegistry.

canonicalizeForLookup()

QString PhosphorEngine::WindowRegistry::canonicalizeForLookup ( const QString &  rawWindowId ) const

overridevirtual

Implements PhosphorEngine::IWindowRegistry.

canonicalizeWindowId()

QString PhosphorEngine::WindowRegistry::canonicalizeWindowId ( const QString &  rawWindowId )

overridevirtual

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.

Implements PhosphorEngine::IWindowRegistry.

clear()

void PhosphorEngine::WindowRegistry::clear

(

)

Remove every record and canonical mapping, firing windowDisappeared for each.

TEST SEAM: production tears windows down per-window (remove() on windowClosed, pruneStaleInstances for missed closes); only tests bulk-reset the registry.

contains()

bool PhosphorEngine::WindowRegistry::contains

(

const QString &

instanceId

)

const

instancesWithAppId()

QStringList PhosphorEngine::WindowRegistry::instancesWithAppId

(

const QString &

appId

)

const

Every instance currently recorded under appId, in UNSPECIFIED order (QMultiHash bucket order, not insertion or arrival order).

Callers that need a deterministic sequence — anything FIFO-shaped — must sort or otherwise order the result themselves.

isMinimized()

bool PhosphorEngine::WindowRegistry::isMinimized

(

const QString &

windowId

)

const

Live compositor minimize state, collapsed to a bool: unknown reads as false.

Prefer minimizedState() wherever "unknown" must not be treated as "not minimized" (seeding, capture guards). Accepts either a bare instance id or a composite appId|instanceId window id.

metadata()

std::optional< WindowMetadata > PhosphorEngine::WindowRegistry::metadata

(

const QString &

instanceId

)

const

metadataChanged

void PhosphorEngine::WindowRegistry::metadataChanged ( const QString &  instanceId, const WindowMetadata &  oldMetadata, const WindowMetadata &  newMetadata  )

signal

minimizedState()

std::optional< bool > PhosphorEngine::WindowRegistry::minimizedState ( const QString &  windowId ) const

overridevirtual

Tri-state minimize state (IWindowRegistry contract): engaged when a record exists AND the compositor reported the field; nullopt when the window is unknown or the field was never delivered.

Accepts either a bare instance id or a composite appId|instanceId window id.

Reimplemented from PhosphorEngine::IWindowRegistry.

pruneStaleInstances()

int PhosphorEngine::WindowRegistry::pruneStaleInstances

(

const QSet< QString > &

aliveInstanceIds

)

Defensive cleanup for windows that died WITHOUT a close signal reaching the registry (compositor crash, lost D-Bus call): drop every metadata record AND canonical-id translation whose instance id is absent from aliveInstanceIds, firing windowDisappeared for each so subscribers (e.g.

saved-autotile-order cleanup) drop their ghost state too. Returns the count removed. aliveInstanceIds are the uuid components (WindowId::extractInstanceId), matching this registry's keying. The normal per-window path is remove() on windowClosed; this is the batch backstop the WTA alive-ids report drives.

remove()

void PhosphorEngine::WindowRegistry::remove

(

const QString &

instanceId

)

Remove metadata and canonical state, emitting windowDisappeared exactly once while the canonical mapping remains available to subscribers.

size()

int PhosphorEngine::WindowRegistry::size

(

)

const

upsert()

void PhosphorEngine::WindowRegistry::upsert	(	const QString &	instanceId,
		const WindowMetadata &	metadata
	)

windowAppeared

void PhosphorEngine::WindowRegistry::windowAppeared ( const QString &  instanceId )

signal

windowContext()

std::optional< WindowContext > PhosphorEngine::WindowRegistry::windowContext

(

const QString &

instanceId

)

const

windowDisappeared

void PhosphorEngine::WindowRegistry::windowDisappeared ( const QString &  instanceId )

signal

---

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

• phosphor-engine/include/PhosphorEngine/WindowRegistry.h