The two cooperating maps a per-monitor placement engine keeps: a forward map from PlacementStateKey to the owning per-screen state object (Qt-parent-owned by the engine, constructed via a caller-supplied factory), and a reverse map from windowId to its owning key. More...

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

Public Member Functions
StateT *	forKey (const PlacementStateKey &key, const std::function< StateT *()> &factory)
	Lazily creates the state for `key` if absent.

StateT *	stateForKey (const PlacementStateKey &key) const
	The state for `key`, or nullptr if none exists (never creates).

bool	containsKey (const PlacementStateKey &key) const

void	insertState (const PlacementStateKey &key, StateT *state)
	Insert/replace the state at `key` (caller retains ownership semantics).

StateT *	takeState (const PlacementStateKey &key)
	Remove and return the state at `key` (nullptr if absent). Does not delete.

int	stateCount () const

const QHash< PlacementStateKey, StateT * > &	states () const
	Read-only view of the forward map for iteration.

bool	hasWindow (const QString &windowId) const

PlacementStateKey	keyForWindow (const QString &windowId) const
	The owning key for `windowId`, or a default-constructed key when untracked (mirrors QHash::value — an empty screenId marks "not tracked").

std::optional< PlacementStateKey >	windowKey (const QString &windowId) const
	The owning key for `windowId`, or nullopt when untracked.

void	setKeyForWindow (const QString &windowId, const PlacementStateKey &key)

void	removeWindow (const QString &windowId)
	Drop the reverse-map entry for `windowId` (does not touch state objects).

PlacementStateKey	takeWindow (const QString &windowId)
	Remove and return the reverse-map entry for `windowId` (default key when absent), mirroring QHash::take.

const QHash< QString, PlacementStateKey > &	windowKeys () const
	Read-only view of the reverse map for iteration.

StateT *	forWindow (const QString &windowId, PlacementStateKey *outKey=nullptr) const
	Resolve the state that owns `windowId` (no create).

void	migrate (const QString &windowId, const PlacementStateKey &oldKey, const PlacementStateKey &newKey)
	Move a window's reverse-map entry from `oldKey` to `newKey`.

void	rekeyWindows (const PlacementStateKey &oldKey, const PlacementStateKey &newKey)
	Rewrite every reverse-map entry pointing at `oldKey` to `newKey`.

void	removeStatesIf (const std::function< bool(const PlacementStateKey &, StateT )> &pred, const std::function< void(const PlacementStateKey &, StateT )> &onRemove)
	Lockstep prune of the forward map: for every state matching `pred`, invoke `onRemove` (engine-specific teardown) BEFORE dropping the entry.

void	removeWindowsIf (const std::function< bool(const QString &, const PlacementStateKey &)> &pred)
	Drop reverse-map entries matching `pred` (e.g. a vanished desktop/activity).

Detailed Description

template<typename StateT>
class PhosphorEngine::PerScreenStates< StateT >

The two cooperating maps a per-monitor placement engine keeps: a forward map from PlacementStateKey to the owning per-screen state object (Qt-parent-owned by the engine, constructed via a caller-supplied factory), and a reverse map from windowId to its owning key.

Both the snap engine (SnapState) and the autotile engine (TilingState) manage exactly this pair; this template holds it once so the lockstep bookkeeping (lazy create, reverse-map maintenance, migration, prune) is written once.

StateT must implement PhosphorEngine::IPlacementState.

Engine-specific lifecycle (algorithm hooks, retile scheduling, overflow bookkeeping, state teardown) is deliberately OUT of this container: the mutation and prune helpers take the engine's callbacks so the engine wraps its own hooks around the pure map moves.

Member Function Documentation

◆ containsKey()

template<typename StateT >

bool PhosphorEngine::PerScreenStates< StateT >::containsKey ( const PlacementStateKey & key ) const

inline

◆ forKey()

template<typename StateT >

StateT * PhosphorEngine::PerScreenStates< StateT >::forKey	(	const PlacementStateKey &	key,
		const std::function< StateT *()> &	factory
	)

inline

Lazily creates the state for key if absent.

factory is invoked only on a miss; if it returns nullptr (e.g. the engine rejected an unknown screen) nothing is inserted and nullptr is returned.

◆ forWindow()

template<typename StateT >

StateT * PhosphorEngine::PerScreenStates< StateT >::forWindow	(	const QString &	windowId,
		PlacementStateKey *	outKey = `nullptr`
	)		const

inline

Resolve the state that owns windowId (no create).

When outKey is non-null it receives the window's owning key iff the window is tracked.

◆ hasWindow()

template<typename StateT >

bool PhosphorEngine::PerScreenStates< StateT >::hasWindow ( const QString & windowId ) const

inline

◆ insertState()

template<typename StateT >

void PhosphorEngine::PerScreenStates< StateT >::insertState	(	const PlacementStateKey &	key,
		StateT *	state
	)

inline

Insert/replace the state at key (caller retains ownership semantics).

◆ keyForWindow()

template<typename StateT >

PlacementStateKey PhosphorEngine::PerScreenStates< StateT >::keyForWindow ( const QString & windowId ) const

inline

The owning key for windowId, or a default-constructed key when untracked (mirrors QHash::value — an empty screenId marks "not tracked").

◆ migrate()

template<typename StateT >

void PhosphorEngine::PerScreenStates< StateT >::migrate	(	const QString &	windowId,
		const PlacementStateKey &	oldKey,
		const PlacementStateKey &	newKey
	)

inline

Move a window's reverse-map entry from oldKey to newKey.

Only the reverse map moves; the engine wraps its own remove-from-old / add-to-new state lifecycle hooks around this call. oldKey is the caller's asserted current key: the reverse map is authoritative, so oldKey only guards against a stale-caller bug (in debug builds) rather than driving the move.

◆ rekeyWindows()

template<typename StateT >

void PhosphorEngine::PerScreenStates< StateT >::rekeyWindows	(	const PlacementStateKey &	oldKey,
		const PlacementStateKey &	newKey
	)

inline

Rewrite every reverse-map entry pointing at oldKey to newKey.

Used when a whole state is re-keyed (sticky-pin desktop migration).

◆ removeStatesIf()

template<typename StateT >

void PhosphorEngine::PerScreenStates< StateT >::removeStatesIf	(	const std::function< bool(const PlacementStateKey &, StateT *)> &	pred,
		const std::function< void(const PlacementStateKey &, StateT *)> &	onRemove
	)

inline

Lockstep prune of the forward map: for every state matching pred, invoke onRemove (engine-specific teardown) BEFORE dropping the entry.

The reverse map is left to the caller (release paths collect released windows and clean the reverse map separately; desktop/activity prunes use removeWindowsIf()).

◆ removeWindow()

template<typename StateT >

void PhosphorEngine::PerScreenStates< StateT >::removeWindow ( const QString & windowId )

inline

Drop the reverse-map entry for windowId (does not touch state objects).

◆ removeWindowsIf()

template<typename StateT >

void PhosphorEngine::PerScreenStates< StateT >::removeWindowsIf ( const std::function< bool(const QString &, const PlacementStateKey &)> & pred )

inline

Drop reverse-map entries matching pred (e.g. a vanished desktop/activity).

◆ setKeyForWindow()

template<typename StateT >

void PhosphorEngine::PerScreenStates< StateT >::setKeyForWindow	(	const QString &	windowId,
		const PlacementStateKey &	key
	)

inline

◆ stateCount()

template<typename StateT >

int PhosphorEngine::PerScreenStates< StateT >::stateCount ( ) const

inline

◆ stateForKey()

template<typename StateT >

StateT * PhosphorEngine::PerScreenStates< StateT >::stateForKey ( const PlacementStateKey & key ) const

inline

The state for key, or nullptr if none exists (never creates).

◆ states()

template<typename StateT >

const QHash< PlacementStateKey, StateT * > & PhosphorEngine::PerScreenStates< StateT >::states ( ) const

inline

Read-only view of the forward map for iteration.

◆ takeState()

template<typename StateT >

StateT * PhosphorEngine::PerScreenStates< StateT >::takeState ( const PlacementStateKey & key )

inline

Remove and return the state at key (nullptr if absent). Does not delete.

◆ takeWindow()

template<typename StateT >

PlacementStateKey PhosphorEngine::PerScreenStates< StateT >::takeWindow ( const QString & windowId )

inline

Remove and return the reverse-map entry for windowId (default key when absent), mirroring QHash::take.

◆ windowKey()

template<typename StateT >

std::optional< PlacementStateKey > PhosphorEngine::PerScreenStates< StateT >::windowKey ( const QString & windowId ) const

inline

The owning key for windowId, or nullopt when untracked.

◆ windowKeys()

template<typename StateT >

const QHash< QString, PlacementStateKey > & PhosphorEngine::PerScreenStates< StateT >::windowKeys ( ) const

inline

Read-only view of the reverse map for iteration.

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

phosphor-engine/include/PhosphorEngine/PerScreenStates.h

Phosphor Qt6 / Wayland library suite for window-management tools

Public Member Functions

Detailed Description

Member Function Documentation

◆ containsKey()

◆ forKey()

◆ forWindow()

◆ hasWindow()

◆ insertState()

◆ keyForWindow()

◆ migrate()

◆ rekeyWindows()

◆ removeStatesIf()

◆ removeWindow()

◆ removeWindowsIf()

◆ setKeyForWindow()

◆ stateCount()

◆ stateForKey()

◆ states()

◆ takeState()

◆ takeWindow()

◆ windowKey()

◆ windowKeys()