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

#include <PhosphorEngine/WindowRegistry.h>

Inheritance diagram for PhosphorEngine::WindowRegistry:
[legend]

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.
std::optional< bool > fillsOutputState (const QString &windowId) const override
 IWindowRegistry::fillsOutputState over the reported maximize (either axis) and fullscreen fields.
std::optional< WindowDesktopContext > desktopContext (const QString &windowId) const override
 The desktop set and activity last reported for windowId (bare instance id or composite appId|instanceId), or nullopt when the window is unknown.
QStringList instancesWithAppId (const QString &appId) const
 Every instance currently recorded under appId, most recently indexed first (QMultiHash::values(key)).
QStringList instanceIds () const
 Every instance holding a METADATA RECORD, unordered.
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.
void beginDesktopRenumber ()
 Snapshot the recorded instances as the ones a coming desktop renumber applies to.
int remapDesktops (const DesktopRemap &remap)
 Move the desktop fields of every instance still in the snapshot through remap the way KWin moves the windows: a window on several desktops keeps the surviving ones (renumbered) and drops the removed ones, and a window left on no desktop goes to the removed desktop's successor (DesktopRemap::successor).
void endDesktopRenumber ()
 End the snapshot without moving anything.
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.

◆ beginDesktopRenumber()

void PhosphorEngine::WindowRegistry::beginDesktopRenumber ( )

Snapshot the recorded instances as the ones a coming desktop renumber applies to.

Called when KWin's desktop list starts changing (the desktop manager's desktopListChanging): any upsert or remove after this drops its instance from the snapshot, since its push already carries the new numbering. The snapshot lasts until remapDesktops or endDesktopRenumber ends it; calling this while one is held replaces it.

◆ canonicalizeForLookup()

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

◆ 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. An empty id, or one with no instance part ("appId|"), names no window and comes back unchanged without being frozen.

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

◆ desktopContext()

std::optional< WindowDesktopContext > PhosphorEngine::WindowRegistry::desktopContext ( const QString & windowId) const
overridevirtual

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 from PhosphorEngine::IWindowRegistry.

◆ endDesktopRenumber()

void PhosphorEngine::WindowRegistry::endDesktopRenumber ( )

End the snapshot without moving anything.

For the end of a desktop-list change that renumbered nothing (an append, a rename) or was given up on, which brings no remapDesktops call (the desktop manager's desktopListChangeSettled): a snapshot left held would hand a later, unrelated renumber records that were pushed in the live numbering.

◆ fillsOutputState()

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

IWindowRegistry::fillsOutputState over the reported maximize (either axis) and fullscreen fields.

Accepts a bare instance id or a composite id.

Reimplemented from PhosphorEngine::IWindowRegistry.

◆ instanceIds()

QStringList PhosphorEngine::WindowRegistry::instanceIds ( ) const

Every instance holding a METADATA RECORD, unordered.

Canonical-only instances (a canonical id frozen before any metadata push arrived) are NOT listed: they carry no context to seed from, which is what every consumer of this wants (the dynamic-workspaces population census seeds derived per-window state at attach time rather than replaying history). Use contains() for the same record-backed question about one id.

◆ instancesWithAppId()

QStringList PhosphorEngine::WindowRegistry::instancesWithAppId ( const QString & appId) const

Every instance currently recorded under appId, most recently indexed first (QMultiHash::values(key)).

An appId change re-indexes the instance at the head, so this is not arrival order: callers that need a FIFO sequence must 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. An EMPTY aliveInstanceIds is refused (returns 0 with a warning) while any record or mapping exists: the effect's first alive report can come before restored apps map.

◆ remapDesktops()

int PhosphorEngine::WindowRegistry::remapDesktops ( const DesktopRemap & remap)

Move the desktop fields of every instance still in the snapshot through remap the way KWin moves the windows: a window on several desktops keeps the surviving ones (renumbered) and drops the removed ones, and a window left on no desktop goes to the removed desktop's successor (DesktopRemap::successor).

Emit metadataChanged for each record that changed, and end the snapshot. Without a beginDesktopRenumber first it changes nothing, and an identity remap changes nothing but still ends the snapshot. Returns the count changed (F763).

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

An upsert a subscriber makes during the emit is replayed after it and keeps the instance's canonical mapping; inside clear() that replay is dropped.

◆ 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: