Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorEngine::PerScreenStates< StateT > Class Template Reference

Exported because this is a header-only template used from every engine library, so the category has to resolve outside phosphor-engine. More...

#include <PhosphorEngine/PerScreenStates.h>

Public Types

using ContextKeyResolver = std::function<PlacementStateKey(const QString& screenId)>
 Resolves the key a screen is CURRENTLY showing.

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.
void setContextKeyResolver (ContextKeyResolver resolver)
bool hasWindow (const QString &windowId) const
PlacementStateKey keyForWindow (const QString &windowId) const
 The PRIMARY key for windowId, or a default-constructed key when untracked (an empty screenId marks "not tracked", as before).
std::optional< PlacementStateKey > windowKey (const QString &windowId) const
 The PRIMARY key for windowId, or nullopt when untracked.
QList< PlacementStateKey > membershipsForWindow (const QString &windowId) const
 Every state this window belongs to, in the order they were added.
bool hasMembership (const QString &windowId, const PlacementStateKey &key) const
 Whether windowId belongs to the state at key specifically.
void setKeyForWindow (const QString &windowId, const PlacementStateKey &key)
 Make key the window's ONLY membership.
void addMembership (const QString &windowId, const PlacementStateKey &key)
 Add key to the window's memberships, keeping the ones it has.
void removeMembership (const QString &windowId, const PlacementStateKey &key)
 Drop one membership.
void removeWindow (const QString &windowId)
 Drop EVERY membership for windowId (does not touch state objects).
PlacementStateKey takeWindow (const QString &windowId)
 Remove every membership and return the primary (default key when absent), mirroring QHash::take.
QStringList trackedWindowIds () const
 Every tracked window id, once each however many states hold it.
void forEachMembership (const std::function< void(const QString &, const PlacementStateKey &)> &fn) const
 Visit every (windowId, key) membership pair.
StateT * forWindow (const QString &windowId, PlacementStateKey *outKey=nullptr) const
 Resolve the state holding windowId's PRIMARY membership (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 membership equal to 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 MEMBERSHIPS matching pred (e.g.

Detailed Description

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

Exported because this is a header-only template used from every engine library, so the category has to resolve outside phosphor-engine.

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 the keys of every state holding it (its memberships, with a context resolver picking the primary). The snap, autotile and scroll engines manage exactly this pair; this template holds it once so the lockstep bookkeeping (lazy create, membership 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 Typedef Documentation

◆ ContextKeyResolver

template<typename StateT>
using PhosphorEngine::PerScreenStates< StateT >::ContextKeyResolver = std::function<PlacementStateKey(const QString& screenId)>

Resolves the key a screen is CURRENTLY showing.

The container cannot know this (the engine owns the context tracker), so the engine installs its currentKeyForScreen here and multi-membership lookups use it to pick the membership in view. Optional: without it the first membership wins, which is the right answer for every single-membership window.

Member Function Documentation

◆ addMembership()

template<typename StateT>
void PhosphorEngine::PerScreenStates< StateT >::addMembership ( const QString & windowId,
const PlacementStateKey & key )
inline

Add key to the window's memberships, keeping the ones it has.

No-op when it is already a member.

◆ containsKey()

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

◆ forEachMembership()

template<typename StateT>
void PhosphorEngine::PerScreenStates< StateT >::forEachMembership ( const std::function< void(const QString &, const PlacementStateKey &)> & fn) const
inline

Visit every (windowId, key) membership pair.

For sweeps that have to see a multi-membership window once per state rather than once.

◆ 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 holding windowId's PRIMARY membership (no create).

When outKey is non-null it receives that key iff the window is tracked. A multi-membership window has other states too; see membershipsForWindow.

◆ hasMembership()

template<typename StateT>
bool PhosphorEngine::PerScreenStates< StateT >::hasMembership ( const QString & windowId,
const PlacementStateKey & key ) const
inline

Whether windowId belongs to the state at key specifically.

The question to ask instead of comparing keyForWindow() against a key: once a window can be in two states at once, "its key is not that one" stops meaning "it is not in that one".

◆ 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 PRIMARY key for windowId, or a default-constructed key when untracked (an empty screenId marks "not tracked", as before).

◆ membershipsForWindow()

template<typename StateT>
QList< PlacementStateKey > PhosphorEngine::PerScreenStates< StateT >::membershipsForWindow ( const QString & windowId) const
inline

Every state this window belongs to, in the order they were added.

◆ 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 reports a stale-caller bug rather than driving the move.

◆ rekeyWindows()

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

Rewrite every membership equal to oldKey to newKey.

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

◆ removeMembership()

template<typename StateT>
void PhosphorEngine::PerScreenStates< StateT >::removeMembership ( const QString & windowId,
const PlacementStateKey & key )
inline

Drop one membership.

The window stops being tracked entirely when its last one goes, so hasWindow cannot answer true for a window no state holds.

◆ 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 EVERY membership 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 MEMBERSHIPS matching pred (e.g.

a vanished desktop/activity). Per membership, not per window: a window present on several desktops loses only the ones that went away, and drops out of tracking entirely when the last of them does.

◆ setContextKeyResolver()

template<typename StateT>
void PhosphorEngine::PerScreenStates< StateT >::setContextKeyResolver ( ContextKeyResolver resolver)
inline

◆ setKeyForWindow()

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

Make key the window's ONLY membership.

This is ordinary placement: the state named by key owns the window outright, and any membership it held elsewhere is gone. Adopting a window into an ADDITIONAL context is addMembership.

◆ 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 every membership and return the primary (default key when absent), mirroring QHash::take.

◆ trackedWindowIds()

template<typename StateT>
QStringList PhosphorEngine::PerScreenStates< StateT >::trackedWindowIds ( ) const
inline

Every tracked window id, once each however many states hold it.

◆ windowKey()

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

The PRIMARY key for windowId, or nullopt when untracked.


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