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

Window-zone tracking service (business logic layer). More...

#include <PhosphorPlacement/WindowTrackingService.h>

Inheritance diagram for PhosphorPlacement::WindowTrackingService:
[legend]

Classes

struct  PendingRestoreTarget
 A pre-computed snap restore target for the effect's instant-restore cache: zone geometry, the saved screen (so the effect only applies it on that screen's output) and the record's window id (an entry for a window the effect can still see is dropped). More...
struct  ZonePruneResult
 unsnapped: windows left in no zone in view (windowId, targetScreenId). More...

Public Types

enum  DirtyField : uint32_t {
  DirtyNone = 0 , DirtyActiveLayoutId = 1u << 0 , DirtyZoneAssignments = 1u << 1 , DirtyKnownDesktops = 1u << 2 ,
  DirtyPreTileGeometries = 1u << 3 , DirtyLastUsedZone = 1u << 4 , DirtyPreFloatZones = 1u << 5 , DirtyPreFloatScreens = 1u << 6 ,
  DirtyUserSnapped = 1u << 7 , DirtyAutotileOrders = 1u << 8 , DirtyAutotilePending = 1u << 9 , DirtyWindowPlacements = 1u << 11 ,
  DirtyScrollStrips = 1u << 12 , DirtyScreenPixelSizes = 1u << 13 , DirtyAll = 0x3FFFu
}
using SnapStateResolver = PhosphorPlacement::SnapStateResolver
 The injectable SnapState-resolver seam.
using AutotileModePredicate = std::function<bool(const QString& windowId)>
 Predicate: is the window's CURRENT screen in Autotile mode?
using EngineTiledPredicate = std::function<bool(const QString& windowId)>
 Predicate: is the window ACTIVELY TILED by a tiling-family engine (autotile / scrolling) in the context in view?
using ModeEngineIdResolver = std::function<QString(const QString& windowId, const QString& screenId)>
 Resolver: which engine id owns windowId's mode on screenId?
using ManagedFramePredicate = std::function<bool(const QString& windowId, const QRect& frame)>
 (M): frame equals a rect a snap membership of the window resolves to (its zones and pre-float zones, each on its store's screen) or one the injected predicate names (the adaptor's settled frame, the tiling engines' last managed rect).
using EngineFloatResolver = std::function<bool(const QString& windowId)>
 Per-engine float resolver/writer.
using EngineFloatWriter = std::function<void(const QString& windowId, bool floating)>
using EngineFloatLister = std::function<QStringList()>
using ResnapEntry = PhosphorEngine::ResnapEntry
using DirtyMask = uint32_t

Signals

void windowZoneChanged (const QString &windowId, const QString &zoneId)
 The window's primary zone changed (empty: it left every zone).
void stateChanged ()
 Emitted when state needs to be saved.

Public Member Functions

 WindowTrackingService (PhosphorZones::LayoutRegistry *layoutManager, PhosphorScreens::ScreenManager *screenManager, PhosphorWorkspaces::VirtualDesktopManager *vdm, IGeometryResolver *geometryResolver=nullptr, PlacementConfig config={}, QObject *parent=nullptr)
const PlacementConfig & config () const
 The placement config.
void setPlacementConfig (const PlacementConfig &config)
QObject * asQObject () override
 ~WindowTrackingService () override
void setWindowRegistry (PhosphorEngine::WindowRegistry *registry)
 Wire the shared WindowRegistry.
void setSnapStateResolver (SnapStateResolver resolver)
void setSnapState (PhosphorSnapEngine::SnapState *state)
 Convenience wiring for a SINGLE snap store (unit tests).
PhosphorEngine::WindowPlacementStore & placementStore () override
 The unified, engine-agnostic placement store (one WindowPlacement record per window).
const PhosphorEngine::WindowPlacementStore & placementStore () const
void setSnapEngine (PhosphorEngine::PlacementEngineBase *engine)
 Wire the snap-mode placement engine.
PhosphorEngine::PlacementEngineBase * snapEngine () const
void setAutotileModePredicate (AutotileModePredicate predicate)
bool isWindowInAutotileMode (const QString &windowId) const
 The AutotileModePredicate's answer for windowId; false when unwired (snap-only tests / early init).
void setEngineTiledPredicate (EngineTiledPredicate predicate)
bool isWindowEngineTiled (const QString &windowId) const
 True if a tiling-family engine (autotile / scrolling) reports the window actively tiled.
void setModeEngineIdResolver (ModeEngineIdResolver resolver)
QString owningModeEngineId (const QString &windowId, const QString &screenId) const
 The owning engine id for windowId on screenId per the resolver; snap's engine id when the resolver is unwired (snap-only tests) or answers empty.
std::optional< PhosphorEngine::WindowPlacement > claimPlacementForOpen (const QString &windowId, const QString &openingScreenId, const QString &openingEngineId)
 The reopen contract's claim (the store's screen-aware claimForOpen) for windowId opening on openingScreenId under openingEngineId: its own record, else the newest sibling record that engine can restore on this output (managed and in its mode, or floating with a free geometry on this very screen).
PhosphorEngine::WindowRegistry * windowRegistry () const
 The wired registry, or null.
PhosphorScreens::ScreenManager * screenManager () const override
QRect screenAvailableGeometry (const QString &screenId) const override
 The area of screenId a window may occupy (the output minus panels and struts), or an invalid rect when the screen cannot be resolved.
void assignWindowToZone (const QString &windowId, const QString &zoneId, const QString &screenId, int virtualDesktop) override
 Assign a window to a zone.
void assignWindowToZones (const QString &windowId, const QStringList &zoneIds, const QString &screenId, int virtualDesktop) override
 Assign a window to multiple zones (multi-zone snap).
void unassignWindow (const QString &windowId) override
 Remove window from its assigned zone.
QString zoneForWindow (const QString &windowId) const override
 Get the primary zone ID for a window.
QStringList zonesForWindow (const QString &windowId) const override
 Get all zone IDs for a window (multi-zone support).
QString screenForWindow (const QString &windowId) const override
 The screen a window is assigned to, or empty when it has none.
QString screenForWindow (const QString &windowId, const QString &defaultScreen) const override
 Same, but returns defaultScreen when the window has no screen assignment — the canonicalizing with-default variant.
QStringList windowsInZone (const QString &zoneId) const override
 Every window holding a zone in any context, each once.
QStringList snappedWindows () const
 Get all snapped windows.
int pruneStaleAssignments (const QSet< QString > &aliveWindowIds)
 Drop per-window state for windows not in the alive set: every snap store's assignments, the sticky map, the legacy float set, the suspension floats and SnapEngine's state-index memberships (SnapEngine::pruneStaleWindows).
bool isWindowSnapped (const QString &windowId) const override
 Whether the window holds a zone in its primary store (the context in view when it is a member there).
std::optional< QRect > validateGeometryForScreen (const QRect &geo, const QString &savedScreen, const QString &currentScreenId) const
 Validate and adjust a saved geometry for screen-aware restore.
std::optional< QRect > validatedUnmanagedGeometry (const QString &windowId, const QString &screenId) const override
 Look up a window's free (unmanaged) geometry from the unified WindowPlacementStore and validate it.
bool geometryBelongsToScreen (const QRect &geometry, const QString &screenId) const override
 Does geometry plausibly belong to the coordinate space screenId names?
std::optional< QPoint > outputOrigin (const QString &screenId) const
 The top-left of screenId's output (its monitor, for a virtual screen) that float-back rects are measured from on disk (WindowPlacementStore::OutputOrigin); nullopt for an output this session has not seen (F814).
void recordFreeGeometry (const QString &windowId, const QString &screenId, const QRect &geometry, bool overwrite) override
 Float-back writes.
void recordFloatingClose (const QString &windowId, const QString &screenId, const QRect &geometry)
 The close-time capture of an engine-orphaned window: the float geometry (P, M, S as above) and screenId as the record's managed screen.
void setManagedFramePredicate (ManagedFramePredicate predicate)
bool isManagedFrame (const QString &windowId, const QRect &frame) const
bool occupiesZoneInView (const QString &windowId) const
 (O): the window is snapped, not floating, in the store its screen shows, on a screen snap runs.
void clearFreeGeometry (const QString &windowId) override
 Clear a window's shared free/float geometry from the record.
void clearFreeGeometry (const QString &windowId, const QString &screenId) override
 Screen-scoped consume-once variant: clears only screenId's remembered float-back, preserving other monitors' entries.
void releaseEngineSlot (const QString &windowId, const QString &engineId) override
 Downgrade engineId's slot to released on windowId's record(s) and mark the placements dirty — the dirty-marking wrapper the tiling engines' handoffRelease calls instead of reaching into the store, so the release survives to disk.
void forgetDesktopZones (const QString &windowId, const QString &engineId, int desktop) override
 Dirty-marking wrapper for WindowPlacementStore::forgetDesktopZones.
void renumberDesktopZones (int removedDesktop) override
 Dirty-marking wrapper for WindowPlacementStore::renumberDesktopZones that also shifts the buffered resnap rows the same way: a row on the removed desktop maps to 0, the all-desktops sentinel, and a row past it moves down one.
void remapDesktopZones (const PhosphorEngine::DesktopRemap &remap) override
 renumberDesktopZones for any change of KWin's desktop list (F763): move every persisted per-desktop zone map and record-level desktop through remap and mark the placements dirty.
void setEngineFloatResolver (EngineFloatResolver resolver)
void setEngineFloatWriter (EngineFloatWriter writer)
void setEngineFloatLister (EngineFloatLister lister)
 Aggregates every engine's floating windows for the engine-agnostic floatingWindows() enumeration.
bool isWindowFloating (const QString &windowId) const override
 Whether the engine running the window's current screen mode floats it.
bool isSuspensionFloat (const QString &windowId) const override
 Suspension-float classification (minimize-floats).
void markSuspensionFloat (const QString &windowId)
void clearSuspensionFloat (const QString &windowId) override
 Drop the suspension classification.
void setWindowFloating (const QString &windowId, bool floating) override
 Set window floating state.
QStringList floatingWindows () const
 Get all floating window IDs.
void unsnapForFloat (const QString &windowId) override
 Unsnap window for floating (saves zone for later restore).
QString preFloatZone (const QString &windowId) const
 Get primary zone to restore to when unfloating, from the window's own entry in its primary snap store.
QStringList preFloatZones (const QString &windowId) const override
 Get all zones to restore to when unfloating (multi-zone support), from the window's primary snap store.
QString preFloatScreen (const QString &windowId) const override
 Get the screen id where the window was snapped before floating, from the window's primary snap store.
void clearPreFloatZone (const QString &windowId) override
 Clear the window's pre-float zone in every snap store.
void clearPreFloatZoneExceptHiddenContexts (const QString &windowId, const QString &screenId)
 Clear the window's pre-float zone in every snap store except the hidden contexts of screenId: a store filed under that same screen for a desktop or activity it does not show now keeps its entry.
bool hasSnapState () const
 True while the resolver's globals store resolves: wired, and (for the engine resolver, whose arms hold a QPointer) while the snap engine is alive.
bool clearFloatingForSnap (const QString &windowId) override
 Clear the float when a floating window is snapped.
void setWindowSticky (const QString &windowId, bool sticky)
 Record whether a window is sticky (on all desktops).
bool isWindowSticky (const QString &windowId) const override
 Whether the window is on all desktops: the compositor's setWindowSticky report when one arrived, else the registry's last metadata push, else false.
void recordSnapIntent (const QString &windowId, bool wasUserInitiated) override
 Record that a window class was user-snapped.
QString lastUsedZoneId () const
 Get last used zone ID.
QString lastUsedZoneClass () const
 App class string stamped on the last-used-zone tracking.
QString lastUsedScreenName () const
 Screen name companion of the last-used-zone tracking.
int lastUsedDesktop () const
 Virtual-desktop companion of the last-used-zone tracking.
void retagLastUsedZoneClass (const QString &newClass)
 Update the last-used-zone class tag without touching zone/screen.
void updateLastUsedZone (const QString &zoneId, const QString &screenId, const QString &windowClass, int virtualDesktop) override
 Update last used zone tracking.
void markAsAutoSnapped (const QString &windowId)
 Mark a window as auto-snapped.
bool isAutoSnapped (const QString &windowId) const
 Check if a window was auto-snapped.
bool clearAutoSnapped (const QString &windowId) override
 Clear auto-snapped flag for a window.
QString findEmptyZone (const QString &screenId=QString()) const override
 Find the first empty zone in the layout for a screen.
PhosphorProtocol::EmptyZoneList getEmptyZones (const QString &screenId) const
 Get typed list of all empty zones for Snap Assist continuation.
QRect zoneGeometry (const QString &zoneId, const QString &screenId) const override
 Get geometry for a zone on a specific screen.
QRect multiZoneGeometry (const QStringList &zoneIds, const QString &screenId) const
 Get combined geometry for multiple zones on a specific screen.
void populateResnapBufferForAllScreens (const QSet< QString > &excludeScreens={}, const QSet< QString > &includeScreens={}, int desktopFilter=0)
 Populate the resnap buffer: each window's primary zone position, read from a map over every loaded layout.
void clearResnapBuffer ()
 Clear the resnap buffer.
QStringList buildZoneOrderedWindowList (const QString &screenId) const
 The windows snapped (not floating) on screenId in the context in view, sorted by their primary zone's number in the layout that holds it, ties by window id.
void bufferWindowsOfRemovedLayout (PhosphorZones::Layout *layout)
 Replace the resnap buffer with the windows in view on a snapping screen whose primary zone layout (being removed, still alive) holds, by zone position and tagged fromRemovedLayout, so a resnap moves them to the layout their context runs, or to their float-back when the delete leaves it on none.
void migrateScreenAssignmentsToVirtual (const QString &physicalScreenId, const QStringList &virtualScreenIds, PhosphorScreens::ScreenManager *mgr)
 Migrate window screen assignments from physical to virtual screen IDs.
void migrateScreenAssignmentsFromVirtual (const QString &physicalScreenId)
 Reverse migration: virtual screen IDs → physical screen ID.
QSet< QString > physicalScreensWithStaleVirtualAssignments (const QSet< QString > &subdividedPhysicalIds) const
 Find physical screens whose state still references virtual ids, excluding screens the caller knows are still subdivided.
QHash< QString, QRect > updatedWindowGeometries () const
 windowId -> its zone rect in the context in view (else its primary's), for the work-area re-apply.
QHash< QString, QList< PendingRestoreTarget > > pendingRestoreGeometries () const
 appId -> list of {geometry, screenId, windowId}, newest first: the snapped records of closed windows the resolve would restore where they open now (a snapping context, a zone its layout holds, the shown desktop's zone for a multi-desktop record), cut on each output at the first newer record the open claim would take instead.
void windowClosed (const QString &windowId, PhosphorEngine::WindowKind kind=PhosphorEngine::WindowKind::Unknown)
 Clean up all tracking data for a closed window.
ZonePruneResult pruneStaleZoneAssignments ()
 Drop stale zones in the store holding each: an id no layout holds, in every context, and for a context in view that runs snapping, a zone its layout lacks (None keeps them).
void onLayoutChanged ()
 The prune alone; the adaptor calls pruneStaleZoneAssignments to relay.
QStringList recordedSnapZones (const QString &windowId) const override
 Live snap zones if present, else the durable placement-record snap slot.
QStringList snapZonesOnDesktopInView (const PhosphorEngine::EngineSlot &slot, const QString &screenId) const
 slot's zones for the desktop screenId shows: the per-desktop map's entry when the slot carries one (empty when it names no zone there), else the flat zoneIds.
QVector< ResnapEntry > takeResnapBuffer () override
void markLastUsedZoneDirty () override
 An engine cleared a last-used zone in one of its stores: persist it.
const QSet< QString > & userSnappedClasses () const
 The user-snapped classes.
void setUserSnappedClasses (const QSet< QString > &classes)
 Set user-snapped classes (loaded from the persisted state by the adaptor).
void setLastUsedZone (const QString &zoneId, const QString &screenId, const QString &zoneClass, int desktop)
 Set last used zone info (the adaptor's session load; held until a store is wired).
void setFloatingWindows (const QSet< QString > &windows)
 Set floating windows (test / bulk-seed entry point).
void markDirty (DirtyMask fields)
 OR the given fields into the dirty mask AND emit stateChanged.
DirtyMask takeDirty ()
 Return the current dirty mask, clearing it atomically.
DirtyMask peekDirty () const
 Return the current dirty mask without clearing.
void clearDirty ()
 Clear every dirty bit.
QString resolveEffectiveScreenId (const QString &screenId) const override
 A live or non-virtual id comes back as is; a virtual screen that no longer exists resolves to the nearest-index live one on its monitor, or the monitor itself when it is no longer split or connected.
QRect resolveZoneGeometry (const QStringList &zoneIds, const QString &screenId) const override
 Resolve zone geometry: combined geometry for multi-zone, single for single zone.
QString findEmptyZoneInLayout (PhosphorZones::Layout *layout, const QString &screenId, int desktopFilter=0) const override
QSet< QUuid > buildOccupiedZoneSet (const QString &screenFilter=QString(), int desktopFilter=0) const override
 Build set of occupied zone UUIDs, optionally filtered by screen and virtual desktop.
QString currentAppIdFor (const QString &anyWindowId) const override
 Current app class for a windowId, preferring the live registry.
QString canonicalizeForLookup (const QString &rawWindowId) const
 Canonicalize for read-only callers (no map mutation).
Public Member Functions inherited from PhosphorEngine::IWindowTrackingService
virtual ~IWindowTrackingService ()=default

Static Public Member Functions

static void downgradeMismatchedManagedSlots (PhosphorEngine::WindowPlacement &placement, const QString &recordedScreenId, const QString &closeScreenId)
 Downgrade managed slots recorded against a different screen: when recordedScreenId does not match closeScreenId, every snapped/tiled slot in placement becomes plain floating with its zone ids, order and per-desktop zones cleared, since they name THAT screen's zones and tile order.
static QList< QPair< QString, int > > mismatchedDesktopZones (const PhosphorEngine::WindowPlacement &placement, const QString &recordedScreenId, const QString &closeScreenId)
 The (engine id, desktop) entries that downgrade clears from the per-desktop maps, read before it runs: record() merges the stored map back in, so a caller forgets these after recording (F282).

Detailed Description

Window-zone tracking service (business logic layer).

The engine-agnostic facade over the snap stores and the unified WindowPlacementStore:

  • zone assignments (which window is in which zone), read through SnapState
  • free (float-back) geometry per screen, held in the placement records
  • float routing to the owning engine, and the suspension-float and sticky bits
  • the resnap buffer, the dirty mask and the last-used zone companions

The WindowTrackingAdaptor persists it through the dirty mask. The auto-snap and rotation decisions are SnapEngine's (calculateSnapToLastZone, calculateRotation).

Member Typedef Documentation

◆ AutotileModePredicate

using PhosphorPlacement::WindowTrackingService::AutotileModePredicate = std::function<bool(const QString& windowId)>

Predicate: is the window's CURRENT screen in Autotile mode?

Injected by the daemon (engine-/settings-agnostic LGPL boundary). Its one reader is the adaptor's capture funnel, which tries the autotile capture first when it answers true. When unset, every window reads as not autotile.

◆ DirtyMask

◆ EngineFloatLister

◆ EngineFloatResolver

using PhosphorPlacement::WindowTrackingService::EngineFloatResolver = std::function<bool(const QString& windowId)>

Per-engine float resolver/writer.

Float state is genuinely per-engine: a window floated in autotile mode is NOT floating in snapping mode and vice versa. The authoritative store lives in each engine (SnapState, TilingState, the scroll engine's float set), keyed by the screen's current mode. The placement library is intentionally engine- and settings-agnostic (LGPL boundary), so the daemon injects a resolver (reader) and writer that route to the engine owning the window's CURRENT screen mode.

When unset (unit tests / early init before the engines are wired), the service falls back to the legacy shared m_floatingWindows set so existing single-engine tests keep their historical behaviour.

◆ EngineFloatWriter

using PhosphorPlacement::WindowTrackingService::EngineFloatWriter = std::function<void(const QString& windowId, bool floating)>

◆ EngineTiledPredicate

using PhosphorPlacement::WindowTrackingService::EngineTiledPredicate = std::function<bool(const QString& windowId)>

Predicate: is the window ACTIVELY TILED by a tiling-family engine (autotile / scrolling) in the context in view?

Injected by the daemon; the wiring ORs both engines' isWindowTiled where each holds the window in view. Distinct from the MODE predicate: a fresh spawn on a tiling screen is in that mode but not tiled, and its frame is a genuine free geometry.

◆ ManagedFramePredicate

using PhosphorPlacement::WindowTrackingService::ManagedFramePredicate = std::function<bool(const QString& windowId, const QRect& frame)>

(M): frame equals a rect a snap membership of the window resolves to (its zones and pre-float zones, each on its store's screen) or one the injected predicate names (the adaptor's settled frame, the tiling engines' last managed rect).

Exact compare, never size-only.

◆ ModeEngineIdResolver

using PhosphorPlacement::WindowTrackingService::ModeEngineIdResolver = std::function<QString(const QString& windowId, const QString& screenId)>

Resolver: which engine id owns windowId's mode on screenId?

Injected by the daemon (engine-/settings-agnostic LGPL boundary), same pattern as AutotileModePredicate but answering with the OWNING engine's WindowPlacement engine id ("snap" / "autotile" / "scrolling") for an explicit screen. Used wherever a slot must be synthesized for a window no engine captured (recordFloatingClose, the minimize preserve): the reopen accepts are keyed strictly per engine slot, so a synthesized float slot filed under the wrong engine is invisible to the engine that will actually field the reopen — the float-is-per-mode invariant read from the store side.

◆ ResnapEntry

◆ SnapStateResolver

The injectable SnapState-resolver seam.

Defined in its own header so consumers can name the type without pulling in the whole service. The alias keeps the historical WindowTrackingService::SnapStateResolver spelling valid for existing call sites.

Member Enumeration Documentation

◆ DirtyField

Enumerator
DirtyNone 
DirtyActiveLayoutId 
DirtyZoneAssignments 
DirtyKnownDesktops 

the virtual desktop ids the session last saw (was DirtyPendingRestores)

DirtyPreTileGeometries 
DirtyLastUsedZone 
DirtyPreFloatZones 
DirtyPreFloatScreens 
DirtyUserSnapped 
DirtyAutotileOrders 
DirtyAutotilePending 
DirtyWindowPlacements 

unified WindowPlacementStore (sole per-window restore state)

DirtyScrollStrips 

scrolling strip-structure snapshots (WTA-provided blob)

DirtyScreenPixelSizes 

each monitor's last compositor-reported pixel size (WTA-provided)

DirtyAll 

Constructor & Destructor Documentation

◆ WindowTrackingService()

PhosphorPlacement::WindowTrackingService::WindowTrackingService ( PhosphorZones::LayoutRegistry * layoutManager,
PhosphorScreens::ScreenManager * screenManager,
PhosphorWorkspaces::VirtualDesktopManager * vdm,
IGeometryResolver * geometryResolver = nullptr,
PlacementConfig config = {},
QObject * parent = nullptr )
explicit

◆ ~WindowTrackingService()

PhosphorPlacement::WindowTrackingService::~WindowTrackingService ( )
override

Member Function Documentation

◆ asQObject()

QObject * PhosphorPlacement::WindowTrackingService::asQObject ( )
overridevirtual

◆ assignWindowToZone()

void PhosphorPlacement::WindowTrackingService::assignWindowToZone ( const QString & windowId,
const QString & zoneId,
const QString & screenId,
int virtualDesktop )
overridevirtual

Assign a window to a zone.

Parameters
windowIdFull window ID
zoneIdPhosphorZones::Zone UUID string
screenIdScreen of the zone; with a pinned desktop, naming another than the window's moves it there
virtualDesktopVirtual desktop number (1-based, 0 = all)

Implements PhosphorEngine::IWindowTrackingService.

◆ assignWindowToZones()

void PhosphorPlacement::WindowTrackingService::assignWindowToZones ( const QString & windowId,
const QStringList & zoneIds,
const QString & screenId,
int virtualDesktop )
overridevirtual

Assign a window to multiple zones (multi-zone snap).

Parameters
windowIdFull window ID
zoneIdsList of zone UUID strings (first is primary)
screenIdScreen of the zones; with a pinned desktop, naming another than the window's moves it there
virtualDesktopVirtual desktop number (1-based, 0 = all)

Implements PhosphorEngine::IWindowTrackingService.

◆ bufferWindowsOfRemovedLayout()

void PhosphorPlacement::WindowTrackingService::bufferWindowsOfRemovedLayout ( PhosphorZones::Layout * layout)

Replace the resnap buffer with the windows in view on a snapping screen whose primary zone layout (being removed, still alive) holds, by zone position and tagged fromRemovedLayout, so a resnap moves them to the layout their context runs, or to their float-back when the delete leaves it on none.

◆ buildOccupiedZoneSet()

QSet< QUuid > PhosphorPlacement::WindowTrackingService::buildOccupiedZoneSet ( const QString & screenFilter = QString(),
int desktopFilter = 0 ) const
overridevirtual

Build set of occupied zone UUIDs, optionally filtered by screen and virtual desktop.

Uses PhosphorScreens::ScreenIdentity::screensMatch() for format-agnostic screen comparison.

Parameters
desktopFilterWhen > 0, only counts assignments whose window desktop matches (or is 0 = pinned/all-desktops), so windows parked on other desktops do not make zones appear occupied. A store of another activity never counts.

Implements PhosphorEngine::IWindowTrackingService.

◆ buildZoneOrderedWindowList()

QStringList PhosphorPlacement::WindowTrackingService::buildZoneOrderedWindowList ( const QString & screenId) const

The windows snapped (not floating) on screenId in the context in view, sorted by their primary zone's number in the layout that holds it, ties by window id.

Seeds the autotile order on a switch to tiling.

◆ canonicalizeForLookup()

QString PhosphorPlacement::WindowTrackingService::canonicalizeForLookup ( const QString & rawWindowId) const

Canonicalize for read-only callers (no map mutation).

Delegates to the registry's canonicalizeForLookup when available. Unit tests that don't attach a registry get a passthrough.

◆ claimPlacementForOpen()

std::optional< PhosphorEngine::WindowPlacement > PhosphorPlacement::WindowTrackingService::claimPlacementForOpen ( const QString & windowId,
const QString & openingScreenId,
const QString & openingEngineId )

The reopen contract's claim (the store's screen-aware claimForOpen) for windowId opening on openingScreenId under openingEngineId: its own record, else the newest sibling record that engine can restore on this output (managed and in its mode, or floating with a free geometry on this very screen).

An empty engine id applies no engine predicate.

◆ clearAutoSnapped()

bool PhosphorPlacement::WindowTrackingService::clearAutoSnapped ( const QString & windowId)
overridevirtual

Clear auto-snapped flag for a window.

Parameters
windowIdFull window ID
Returns
true if the window had the auto-snapped flag

Implements PhosphorEngine::IWindowTrackingService.

◆ clearDirty()

void PhosphorPlacement::WindowTrackingService::clearDirty ( )

Clear every dirty bit.

Called from loadState's end after in-memory state mirrors the disk file — nothing is dirty until the next mutation lands.

◆ clearFloatingForSnap()

bool PhosphorPlacement::WindowTrackingService::clearFloatingForSnap ( const QString & windowId)
overridevirtual

Clear the float when a floating window is snapped.

Unfloats through the routed writer and drops the pre-float zone in the window's primary store. Called by SnapEngine's commit, which emits windowFloatingClearedForSnap when this or snap's own float bit cleared.

Parameters
windowIdWindow identifier
Returns
true if the routed float read answered floating

Implements PhosphorEngine::IWindowTrackingService.

◆ clearFreeGeometry() [1/2]

void PhosphorPlacement::WindowTrackingService::clearFreeGeometry ( const QString & windowId)
overridevirtual

Clear a window's shared free/float geometry from the record.

See IWindowTrackingService::clearFreeGeometry.

Implements PhosphorEngine::IWindowTrackingService.

◆ clearFreeGeometry() [2/2]

void PhosphorPlacement::WindowTrackingService::clearFreeGeometry ( const QString & windowId,
const QString & screenId )
overridevirtual

Screen-scoped consume-once variant: clears only screenId's remembered float-back, preserving other monitors' entries.

Default falls back to the all-screens form for implementations without per-screen granularity.

Reimplemented from PhosphorEngine::IWindowTrackingService.

◆ clearPreFloatZone()

void PhosphorPlacement::WindowTrackingService::clearPreFloatZone ( const QString & windowId)
overridevirtual

Clear the window's pre-float zone in every snap store.

Implements PhosphorEngine::IWindowTrackingService.

◆ clearPreFloatZoneExceptHiddenContexts()

void PhosphorPlacement::WindowTrackingService::clearPreFloatZoneExceptHiddenContexts ( const QString & windowId,
const QString & screenId )

Clear the window's pre-float zone in every snap store except the hidden contexts of screenId: a store filed under that same screen for a desktop or activity it does not show now keeps its entry.

That entry is the window's snap home on that desktop (a window on several desktops, or a sticky one, holds one per desktop), so a float on the desktop in view must not take it. The store screenId shows now clears, and so does every store on another screen, because a window that moves forgets the zone it floated from there. Screens compare by id (ScreenIdentity::screensMatch), so another virtual screen of the same monitor counts as another screen: virtual screens are not per desktop, and a window present on several desktops sits on the same one on each. An empty screenId, or a resolver that cannot name a store's key (the single-store convenience), hides nothing and clears like clearPreFloatZone.

◆ clearResnapBuffer()

void PhosphorPlacement::WindowTrackingService::clearResnapBuffer ( )

Clear the resnap buffer.

Called when virtual screen configuration changes to prevent stale resnap data from referencing old screen IDs.

◆ clearSuspensionFloat()

void PhosphorPlacement::WindowTrackingService::clearSuspensionFloat ( const QString & windowId)
overridevirtual

Drop the suspension classification.

The adaptor owns it on the minimize/unminimize edges, but an engine-side USER unfloat (the float shortcut) also ends the suspension and never crosses that boundary — without this the bit strands and every later capture takes the minimize-preserve path. No-op for implementations that do not track the classification.

Reimplemented from PhosphorEngine::IWindowTrackingService.

◆ config()

const PlacementConfig & PhosphorPlacement::WindowTrackingService::config ( ) const
inline

The placement config.

The adaptor keeps it current with the settings (F327); every reader reads it at the time of use, none caches it.

◆ currentAppIdFor()

QString PhosphorPlacement::WindowTrackingService::currentAppIdFor ( const QString & anyWindowId) const
overridevirtual

Current app class for a windowId, preferring the live registry.

Equivalent to PhosphorIdentity::WindowId::extractAppId() when no registry is attached. With a registry, returns the latest appId for the instance id — so snap rule matching against a freshly-renamed window (Electron/CEF) sees the current class.

Implements PhosphorEngine::IWindowTrackingService.

◆ downgradeMismatchedManagedSlots()

void PhosphorPlacement::WindowTrackingService::downgradeMismatchedManagedSlots ( PhosphorEngine::WindowPlacement & placement,
const QString & recordedScreenId,
const QString & closeScreenId )
static

Downgrade managed slots recorded against a different screen: when recordedScreenId does not match closeScreenId, every snapped/tiled slot in placement becomes plain floating with its zone ids, order and per-desktop zones cleared, since they name THAT screen's zones and tile order.

Same-screen (or unscreened) records pass through. Shared by recordFloatingClose and the adaptor's minimize preserve so the two close-shaped writers cannot drift.

◆ findEmptyZone()

QString PhosphorPlacement::WindowTrackingService::findEmptyZone ( const QString & screenId = QString()) const
overridevirtual

Find the first empty zone in the layout for a screen.

Parameters
screenIdScreen to find layout for (empty = active layout)
Returns
PhosphorZones::Zone ID or empty string if all occupied

Implements PhosphorEngine::IWindowTrackingService.

◆ findEmptyZoneInLayout()

QString PhosphorPlacement::WindowTrackingService::findEmptyZoneInLayout ( PhosphorZones::Layout * layout,
const QString & screenId,
int desktopFilter = 0 ) const
overridevirtual

◆ floatingWindows()

QStringList PhosphorPlacement::WindowTrackingService::floatingWindows ( ) const

Get all floating window IDs.

◆ forgetDesktopZones()

void PhosphorPlacement::WindowTrackingService::forgetDesktopZones ( const QString & windowId,
const QString & engineId,
int desktop )
overridevirtual

Dirty-marking wrapper for WindowPlacementStore::forgetDesktopZones.

Reimplemented from PhosphorEngine::IWindowTrackingService.

◆ geometryBelongsToScreen()

bool PhosphorPlacement::WindowTrackingService::geometryBelongsToScreen ( const QRect & geometry,
const QString & screenId ) const
inlineoverridevirtual

Does geometry plausibly belong to the coordinate space screenId names?

The same predicate validatedUnmanagedGeometry applies to its own answer, exposed because it is NOT the only reader of the shared free-geometry map. A caller that reaches a rect through the placement store directly — the engines' reopen and release paths do, via takeForReopen — gets no validation from that route and hands the rect straight to a geometry apply. A mis-keyed record then teleports the window to whatever monitor the coordinates describe, which is the failure the read guard exists to stop; those callers need the same check rather than their own copy of it.

Not a substitute for an is-this-on-any-screen rescue test: this asks whether the rect belongs to THIS key, so a rect sitting squarely on a different monitor answers false. Fails OPEN when the screen cannot be resolved, so an embedder with no screen manager keeps its behaviour.

Forwards to the private geometryOverlapsScreen, which is where the semantics (physical-output resolution, size-clamped thresholds, fail-open) are documented.

Implements PhosphorEngine::IWindowTrackingService.

◆ getEmptyZones()

PhosphorProtocol::EmptyZoneList PhosphorPlacement::WindowTrackingService::getEmptyZones ( const QString & screenId) const

Get typed list of all empty zones for Snap Assist continuation.

Parameters
screenIdScreen id (EDID-based, or a virtual-screen id)
Returns
PhosphorProtocol::EmptyZoneList of empty zone entries with overlay-local geometry

◆ hasSnapState()

bool PhosphorPlacement::WindowTrackingService::hasSnapState ( ) const

True while the resolver's globals store resolves: wired, and (for the engine resolver, whose arms hold a QPointer) while the snap engine is alive.

The read-only queries (zoneForWindow, zonesForWindow, isWindowSnapped, windowsInZone, snappedWindows, isAutoSnapped, userSnappedClasses), the walk behind the empty-zone queries, the stale prune and recordSnapIntent need no check first: with no store they answer empty or false, or do nothing. The other writers still assert it, because each is reached only after a commit or a zone answer that already needs a store.

◆ isAutoSnapped()

bool PhosphorPlacement::WindowTrackingService::isAutoSnapped ( const QString & windowId) const

Check if a window was auto-snapped.

Parameters
windowIdFull window ID
Returns
true if the window was auto-snapped (not user-initiated)

◆ isManagedFrame()

bool PhosphorPlacement::WindowTrackingService::isManagedFrame ( const QString & windowId,
const QRect & frame ) const

◆ isSuspensionFloat()

bool PhosphorPlacement::WindowTrackingService::isSuspensionFloat ( const QString & windowId) const
overridevirtual

Suspension-float classification (minimize-floats).

A float applied while the compositor reported the window MINIMIZED is a suspension, not placement intent, and the classification must OUTLIVE the live minimize bit: on the unminimize edge the effect's metadata push flips isMinimized to false immediately, while the unfloat only commits after the animation grace — a placement capture landing inside that window would otherwise persist the suspension float as a genuine user float. Marked by the adaptor at the float WRITE (where minimize state is still fresh). Cleared by the adaptor on unfloat and on windowClosed, and by SnapEngine's Meta+F unfloat, which never crosses the adaptor (WindowTrackingService::windowClosed itself does not touch the set). The prune backstop sweeps it for windows that die without a close signal.

Reimplemented from PhosphorEngine::IWindowTrackingService.

◆ isWindowEngineTiled()

bool PhosphorPlacement::WindowTrackingService::isWindowEngineTiled ( const QString & windowId) const

True if a tiling-family engine (autotile / scrolling) reports the window actively tiled.

Returns false when the predicate is unwired (snap-only tests).

◆ isWindowFloating()

bool PhosphorPlacement::WindowTrackingService::isWindowFloating ( const QString & windowId) const
overridevirtual

Whether the engine running the window's current screen mode floats it.

Delegates to the per-engine resolver when wired; otherwise falls back to the legacy shared floating set.

Implements PhosphorEngine::IWindowTrackingService.

◆ isWindowInAutotileMode()

bool PhosphorPlacement::WindowTrackingService::isWindowInAutotileMode ( const QString & windowId) const

The AutotileModePredicate's answer for windowId; false when unwired (snap-only tests / early init).

◆ isWindowSnapped()

bool PhosphorPlacement::WindowTrackingService::isWindowSnapped ( const QString & windowId) const
overridevirtual

Whether the window holds a zone in its primary store (the context in view when it is a member there).

Implements PhosphorEngine::IWindowTrackingService.

◆ isWindowSticky()

bool PhosphorPlacement::WindowTrackingService::isWindowSticky ( const QString & windowId) const
overridevirtual

Whether the window is on all desktops: the compositor's setWindowSticky report when one arrived, else the registry's last metadata push, else false.

Implements PhosphorEngine::IWindowTrackingService.

◆ lastUsedDesktop()

int PhosphorPlacement::WindowTrackingService::lastUsedDesktop ( ) const

Virtual-desktop companion of the last-used-zone tracking.

◆ lastUsedScreenName()

QString PhosphorPlacement::WindowTrackingService::lastUsedScreenName ( ) const

Screen name companion of the last-used-zone tracking.

Returned alongside lastUsedZoneId so persistence-layer reloads can round-trip the companion fields without blanking them.

◆ lastUsedZoneClass()

QString PhosphorPlacement::WindowTrackingService::lastUsedZoneClass ( ) const

App class string stamped on the last-used-zone tracking.

Used by the reactive metadata handler to detect stale class tags after a mid-session rename.

◆ lastUsedZoneId()

QString PhosphorPlacement::WindowTrackingService::lastUsedZoneId ( ) const

Get last used zone ID.

◆ markAsAutoSnapped()

void PhosphorPlacement::WindowTrackingService::markAsAutoSnapped ( const QString & windowId)

Mark a window as auto-snapped.

Auto-snapped windows should not update the last-used zone tracking when snapped. This prevents unwanted zone changes when windows are automatically restored on open.

Parameters
windowIdFull window ID

◆ markDirty()

void PhosphorPlacement::WindowTrackingService::markDirty ( DirtyMask fields)

OR the given fields into the dirty mask AND emit stateChanged.

The mutators' entry point (scheduleSaveState is its DirtyAll wrapper). Public because the adaptor also marks from outside: an active-layout change it observes, and a failed write's bits re-marked for retry. Idempotent (OR) and cheap.

◆ markLastUsedZoneDirty()

void PhosphorPlacement::WindowTrackingService::markLastUsedZoneDirty ( )
overridevirtual

An engine cleared a last-used zone in one of its stores: persist it.

Reimplemented from PhosphorEngine::IWindowTrackingService.

◆ markSuspensionFloat()

void PhosphorPlacement::WindowTrackingService::markSuspensionFloat ( const QString & windowId)

◆ migrateScreenAssignmentsFromVirtual()

void PhosphorPlacement::WindowTrackingService::migrateScreenAssignmentsFromVirtual ( const QString & physicalScreenId)

Reverse migration: virtual screen IDs → physical screen ID.

Called when virtual screen configuration is removed for a physical screen. Strips the "/vs:N" suffix from all tracked window screen assignments that belong to the given physical screen, reverting them to the physical ID, and re-files the snap stores likewise.

Parameters
physicalScreenIdThe physical screen ID to migrate back to

◆ migrateScreenAssignmentsToVirtual()

void PhosphorPlacement::WindowTrackingService::migrateScreenAssignmentsToVirtual ( const QString & physicalScreenId,
const QStringList & virtualScreenIds,
PhosphorScreens::ScreenManager * mgr )

Migrate window screen assignments from physical to virtual screen IDs.

Windows snapped before virtual screens were configured have physical screen IDs in the snap stores' screen assignments. When virtual screens are active, all per-screen lookups use virtual IDs, so these windows become invisible to zone occupancy checks, snap assist, float/unfloat, etc.

This method iterates all screen assignments and, for any window whose screen matches the given physical screen, determines which virtual screen the window's zone falls within and updates the assignment accordingly.

Also migrates pre-float screen assignments in SnapState, and the placement records: a closed window's by the zones its record's snapped slot names. The snap engine then re-files each membership under the store for its new screen (SnapStateResolver::rekeyToRecordedScreens, F105) before the zones are pruned.

Parameters
physicalScreenIdThe physical screen being subdivided
virtualScreenIdsVirtual screen IDs for the physical screen
mgrPhosphorScreens::ScreenManager for geometry lookups

◆ mismatchedDesktopZones()

QList< QPair< QString, int > > PhosphorPlacement::WindowTrackingService::mismatchedDesktopZones ( const PhosphorEngine::WindowPlacement & placement,
const QString & recordedScreenId,
const QString & closeScreenId )
static

The (engine id, desktop) entries that downgrade clears from the per-desktop maps, read before it runs: record() merges the stored map back in, so a caller forgets these after recording (F282).

◆ multiZoneGeometry()

QRect PhosphorPlacement::WindowTrackingService::multiZoneGeometry ( const QStringList & zoneIds,
const QString & screenId ) const

Get combined geometry for multiple zones on a specific screen.

Parameters
zoneIdsList of zone UUID strings
screenIdScreen identifier, resolved exactly as zoneGeometry() does.
Returns
Union of all zone geometries, or invalid QRect if none found

◆ occupiesZoneInView()

bool PhosphorPlacement::WindowTrackingService::occupiesZoneInView ( const QString & windowId) const

(O): the window is snapped, not floating, in the store its screen shows, on a screen snap runs.

◆ onLayoutChanged()

void PhosphorPlacement::WindowTrackingService::onLayoutChanged ( )

The prune alone; the adaptor calls pruneStaleZoneAssignments to relay.

◆ outputOrigin()

std::optional< QPoint > PhosphorPlacement::WindowTrackingService::outputOrigin ( const QString & screenId) const

The top-left of screenId's output (its monitor, for a virtual screen) that float-back rects are measured from on disk (WindowPlacementStore::OutputOrigin); nullopt for an output this session has not seen (F814).

◆ owningModeEngineId()

QString PhosphorPlacement::WindowTrackingService::owningModeEngineId ( const QString & windowId,
const QString & screenId ) const

The owning engine id for windowId on screenId per the resolver; snap's engine id when the resolver is unwired (snap-only tests) or answers empty.

The production resolver's mode switch is total and never answers empty, so the empty arm is pure defence — but it is a REAL branch: a future resolver answering empty on a tiling-mode screen would file the synthesized close slot under snap, invisibly to that engine's reopen accept.

◆ peekDirty()

DirtyMask PhosphorPlacement::WindowTrackingService::peekDirty ( ) const

Return the current dirty mask without clearing.

Read-only accessor for tests and instrumentation.

◆ pendingRestoreGeometries()

QHash< QString, QList< PendingRestoreTarget > > PhosphorPlacement::WindowTrackingService::pendingRestoreGeometries ( ) const

appId -> list of {geometry, screenId, windowId}, newest first: the snapped records of closed windows the resolve would restore where they open now (a snapping context, a zone its layout holds, the shown desktop's zone for a multi-desktop record), cut on each output at the first newer record the open claim would take instead.

The effect fetches it again when the daemon emits WindowTracking.pendingRestoresChanged on a layout, desktop, activity or monitor change (F625).

◆ physicalScreensWithStaleVirtualAssignments()

QSet< QString > PhosphorPlacement::WindowTrackingService::physicalScreensWithStaleVirtualAssignments ( const QSet< QString > & subdividedPhysicalIds) const

Find physical screens whose state still references virtual ids, excluding screens the caller knows are still subdivided.

Sweeps every state that holds a screen id (each snap store's screen and pre-float screen assignments, every placement record's managed screen and free-geometry keys) and returns the set of physical screen ids for which any stored value is still a "physId/vs:N" form whose physId is NOT in subdividedPhysicalIds.

Pair with migrateScreenAssignmentsFromVirtual on each returned id to clean up state left over from a config change applied while the daemon was offline.

Owning the scan here (rather than the daemon enumerating each store) keeps state-shape knowledge inside WTS — adding a new screen-id-bearing store updates this method, not every caller.

Parameters
subdividedPhysicalIdsPhysical ids that legitimately have virtual subdivisions in the current config (these are kept).
Returns
Physical ids that should have migrateScreenAssignmentsFromVirtual applied. Empty when state is consistent with the policy.

◆ placementStore() [1/2]

const PhosphorEngine::WindowPlacementStore & PhosphorPlacement::WindowTrackingService::placementStore ( ) const

◆ placementStore() [2/2]

PhosphorEngine::WindowPlacementStore & PhosphorPlacement::WindowTrackingService::placementStore ( )
overridevirtual

The unified, engine-agnostic placement store (one WindowPlacement record per window).

Every engine reaches it via this service; the WTA persists it.

Implements PhosphorEngine::IWindowTrackingService.

◆ populateResnapBufferForAllScreens()

void PhosphorPlacement::WindowTrackingService::populateResnapBufferForAllScreens ( const QSet< QString > & excludeScreens = {},
const QSet< QString > & includeScreens = {},
int desktopFilter = 0 )

Populate the resnap buffer: each window's primary zone position, read from a map over every loaded layout.

Every layout switch builds its buffer here, and the result replaces the buffer even when it is empty. A minimized window's pre-float zones move to the same-numbered zone (F963), in every store: the filters below choose buffer rows only.

Parameters
excludeScreensScreens to skip (the screens a tiling engine runs, autotile or scrolling)
includeScreensWhen non-empty, only windows on these screens. Only the activity in view is taken.
desktopFilterWhen > 0, only windows on their screen's current desktop (this value when no desktop manager answers); sticky windows (virtualDesktop==0) always pass.

◆ preFloatScreen()

QString PhosphorPlacement::WindowTrackingService::preFloatScreen ( const QString & windowId) const
overridevirtual

Get the screen id where the window was snapped before floating, from the window's primary snap store.

Parameters
windowIdFull window ID
Returns
Screen id, or empty if unknown

Implements PhosphorEngine::IWindowTrackingService.

◆ preFloatZone()

QString PhosphorPlacement::WindowTrackingService::preFloatZone ( const QString & windowId) const

Get primary zone to restore to when unfloating, from the window's own entry in its primary snap store.

Parameters
windowIdFull window ID
Returns
PhosphorZones::Zone ID or empty string if none

◆ preFloatZones()

QStringList PhosphorPlacement::WindowTrackingService::preFloatZones ( const QString & windowId) const
overridevirtual

Get all zones to restore to when unfloating (multi-zone support), from the window's primary snap store.

Parameters
windowIdFull window ID
Returns
List of zone IDs (empty if none)

Implements PhosphorEngine::IWindowTrackingService.

◆ pruneStaleAssignments()

int PhosphorPlacement::WindowTrackingService::pruneStaleAssignments ( const QSet< QString > & aliveWindowIds)

Drop per-window state for windows not in the alive set: every snap store's assignments, the sticky map, the legacy float set, the suspension floats and SnapEngine's state-index memberships (SnapEngine::pruneStaleWindows).

Refuses an empty set. Returns the number of pruned entries.

◆ pruneStaleZoneAssignments()

ZonePruneResult PhosphorPlacement::WindowTrackingService::pruneStaleZoneAssignments ( )

Drop stale zones in the store holding each: an id no layout holds, in every context, and for a context in view that runs snapping, a zone its layout lacks (None keeps them).

A window left in no zone and not floating gives up its snap record slot. First re-slots a removed layout's minimized windows (bufferWindowsOfRemovedLayout, F1035). The adaptor relays the result.

◆ recordedSnapZones()

QStringList PhosphorPlacement::WindowTrackingService::recordedSnapZones ( const QString & windowId) const
overridevirtual

Live snap zones if present, else the durable placement-record snap slot.

See IWindowTrackingService::recordedSnapZones. A multi-desktop or sticky window answers for the desktop its screen shows: its live store there, else its record's zone for that desktop, else nothing. A single-desktop window answers its own store.

Implements PhosphorEngine::IWindowTrackingService.

◆ recordFloatingClose()

void PhosphorPlacement::WindowTrackingService::recordFloatingClose ( const QString & windowId,
const QString & screenId,
const QRect & geometry )

The close-time capture of an engine-orphaned window: the float geometry (P, M, S as above) and screenId as the record's managed screen.

A managed slot recorded on another screen is downgraded to a float and forgets its per-desktop zones, the owning engine gets a floating slot if it lacks one, and the app's pure-float siblings on the screen collapse into this record.

◆ recordFreeGeometry()

void PhosphorPlacement::WindowTrackingService::recordFreeGeometry ( const QString & windowId,
const QString & screenId,
const QRect & geometry,
bool overwrite )
overridevirtual

Float-back writes.

Three writers fill WindowPlacement::freeGeometryByScreen: recordFreeGeometry, recordFloatingClose and the adaptor's captureWindowPlacement. Each refuses (P) a rect off its screen key and (M) a managed frame (isManagedFrame); recordFreeGeometry and the capture also refuse (O) a window in a zone in view or tiled in view. (S) A minimized or output-filling window's frame is refused where a frame is SAMPLED (the capture, the close, the snap pre-snap capture), never for an explicit rect.

Implements PhosphorEngine::IWindowTrackingService.

◆ recordSnapIntent()

void PhosphorPlacement::WindowTrackingService::recordSnapIntent ( const QString & windowId,
bool wasUserInitiated )
overridevirtual

Record that a window class was user-snapped.

Parameters
windowIdFull window ID to extract class from
wasUserInitiatedtrue if user-initiated snap

Implements PhosphorEngine::IWindowTrackingService.

◆ releaseEngineSlot()

void PhosphorPlacement::WindowTrackingService::releaseEngineSlot ( const QString & windowId,
const QString & engineId )
overridevirtual

Downgrade engineId's slot to released on windowId's record(s) and mark the placements dirty — the dirty-marking wrapper the tiling engines' handoffRelease calls instead of reaching into the store, so the release survives to disk.

See WindowPlacementStore::releaseEngineSlot for what the downgrade means and why it is not a removal.

Reimplemented from PhosphorEngine::IWindowTrackingService.

◆ remapDesktopZones()

void PhosphorPlacement::WindowTrackingService::remapDesktopZones ( const PhosphorEngine::DesktopRemap & remap)
overridevirtual

renumberDesktopZones for any change of KWin's desktop list (F763): move every persisted per-desktop zone map and record-level desktop through remap and mark the placements dirty.

The default handles a single removal through renumberDesktopZones and nothing else. Appended last for ABI.

Reimplemented from PhosphorEngine::IWindowTrackingService.

◆ renumberDesktopZones()

void PhosphorPlacement::WindowTrackingService::renumberDesktopZones ( int removedDesktop)
overridevirtual

Dirty-marking wrapper for WindowPlacementStore::renumberDesktopZones that also shifts the buffered resnap rows the same way: a row on the removed desktop maps to 0, the all-desktops sentinel, and a row past it moves down one.

remapDesktopZones is the same for any desktop list change (F763).

Reimplemented from PhosphorEngine::IWindowTrackingService.

◆ resolveEffectiveScreenId()

QString PhosphorPlacement::WindowTrackingService::resolveEffectiveScreenId ( const QString & screenId) const
overridevirtual

A live or non-virtual id comes back as is; a virtual screen that no longer exists resolves to the nearest-index live one on its monitor, or the monitor itself when it is no longer split or connected.

Implements PhosphorEngine::IWindowTrackingService.

◆ resolveZoneGeometry()

QRect PhosphorPlacement::WindowTrackingService::resolveZoneGeometry ( const QStringList & zoneIds,
const QString & screenId ) const
overridevirtual

Resolve zone geometry: combined geometry for multi-zone, single for single zone.

Avoids repeating the (size>1) ? multiZoneGeometry : zoneGeometry ternary.

Implements PhosphorEngine::IWindowTrackingService.

◆ retagLastUsedZoneClass()

void PhosphorPlacement::WindowTrackingService::retagLastUsedZoneClass ( const QString & newClass)

Update the last-used-zone class tag without touching zone/screen.

Called by the reactive metadata handler when the renamed window was the tracked class's only instance. The tag is informational and rides with the last-used companions: auto-snap by class reads userSnappedClasses instead.

◆ screenAvailableGeometry()

QRect PhosphorPlacement::WindowTrackingService::screenAvailableGeometry ( const QString & screenId) const
overridevirtual

The area of screenId a window may occupy (the output minus panels and struts), or an invalid rect when the screen cannot be resolved.

Exposed here so an engine that must not link the screens library (the LGPL engine base) can still clamp a restored size to the output.

Implements PhosphorEngine::IWindowTrackingService.

◆ screenForWindow() [1/2]

QString PhosphorPlacement::WindowTrackingService::screenForWindow ( const QString & windowId) const
overridevirtual

The screen a window is assigned to, or empty when it has none.

Point accessor over the screen-assignment map that canonicalizes windowId to the first-seen composite (via SnapState), so external callers resolve a window even after the effect-restart-after-class-mutation skew rather than reading the raw whole-map getter with a stale composite (issue #628).

Implements PhosphorEngine::IWindowTrackingService.

◆ screenForWindow() [2/2]

QString PhosphorPlacement::WindowTrackingService::screenForWindow ( const QString & windowId,
const QString & defaultScreen ) const
overridevirtual

Same, but returns defaultScreen when the window has no screen assignment — the canonicalizing with-default variant.

Implements PhosphorEngine::IWindowTrackingService.

◆ screenManager()

PhosphorScreens::ScreenManager * PhosphorPlacement::WindowTrackingService::screenManager ( ) const
overridevirtual

◆ setAutotileModePredicate()

void PhosphorPlacement::WindowTrackingService::setAutotileModePredicate ( AutotileModePredicate predicate)

◆ setEngineFloatLister()

void PhosphorPlacement::WindowTrackingService::setEngineFloatLister ( EngineFloatLister lister)

Aggregates every engine's floating windows for the engine-agnostic floatingWindows() enumeration.

See setEngineFloatResolver rationale.

◆ setEngineFloatResolver()

void PhosphorPlacement::WindowTrackingService::setEngineFloatResolver ( EngineFloatResolver resolver)

◆ setEngineFloatWriter()

void PhosphorPlacement::WindowTrackingService::setEngineFloatWriter ( EngineFloatWriter writer)

◆ setEngineTiledPredicate()

void PhosphorPlacement::WindowTrackingService::setEngineTiledPredicate ( EngineTiledPredicate predicate)

◆ setFloatingWindows()

void PhosphorPlacement::WindowTrackingService::setFloatingWindows ( const QSet< QString > & windows)

Set floating windows (test / bulk-seed entry point).

Seeds only the legacy fallback set, which nothing persists and which is unread once the engine float resolver is wired. A snap float itself does persist, as the record's floating snap slot. Kept for the unit suites.

◆ setLastUsedZone()

void PhosphorPlacement::WindowTrackingService::setLastUsedZone ( const QString & zoneId,
const QString & screenId,
const QString & zoneClass,
int desktop )

Set last used zone info (the adaptor's session load; held until a store is wired).

◆ setManagedFramePredicate()

void PhosphorPlacement::WindowTrackingService::setManagedFramePredicate ( ManagedFramePredicate predicate)

◆ setModeEngineIdResolver()

void PhosphorPlacement::WindowTrackingService::setModeEngineIdResolver ( ModeEngineIdResolver resolver)

◆ setPlacementConfig()

void PhosphorPlacement::WindowTrackingService::setPlacementConfig ( const PlacementConfig & config)
inline

◆ setSnapEngine()

void PhosphorPlacement::WindowTrackingService::setSnapEngine ( PhosphorEngine::PlacementEngineBase * engine)

Wire the snap-mode placement engine.

Not owned.

Not the float-back store (that is the shared WindowPlacementStore). Read for the stale-window prune and for isActiveOnScreen, the "snapping runs here live" test of the resnap, prune and occupancy paths; unset (unit tests), those read the configured mode or pass.

◆ setSnapState()

void PhosphorPlacement::WindowTrackingService::setSnapState ( PhosphorSnapEngine::SnapState * state)

Convenience wiring for a SINGLE snap store (unit tests).

Every store arm routes to state; forgetWindow is a no-op (windowClosed already cleared the one store) and holdsWindow / keyFor stay unset, so the store is the window's only membership and its recorded desktop stands for its context. nullptr clears the resolver.

◆ setSnapStateResolver()

void PhosphorPlacement::WindowTrackingService::setSnapStateResolver ( SnapStateResolver resolver)

◆ setUserSnappedClasses()

void PhosphorPlacement::WindowTrackingService::setUserSnappedClasses ( const QSet< QString > & classes)

Set user-snapped classes (loaded from the persisted state by the adaptor).

FAILS SAFE, not lossy: called before a SnapState is wired (the adaptor's constructor loads state before the daemon installs the resolver), the classes are HELD and flushed by setSnapStateResolver / setSnapState. Dropping them made recovery depend on an incidental second load, and a save in between would have written the emptied set back over the user's auto-snap-by-class list.

◆ setWindowFloating()

void PhosphorPlacement::WindowTrackingService::setWindowFloating ( const QString & windowId,
bool floating )
overridevirtual

Set window floating state.

Routes to the engine owning the window's current screen mode via the injected writer when wired; otherwise updates the legacy shared set and the snap state directly.

Parameters
windowIdFull window ID
floatingtrue to float, false to unfloat

Implements PhosphorEngine::IWindowTrackingService.

◆ setWindowRegistry()

void PhosphorPlacement::WindowTrackingService::setWindowRegistry ( PhosphorEngine::WindowRegistry * registry)

Wire the shared WindowRegistry.

Not owned; the adaptor forwards its own setter, so it can be swapped or cleared at any time.

Feeds currentAppIdFor, canonicalizeForLookup, the placement store's live-instance probe, the durable resnap arm's desktop context, isWindowSticky's fallback (F610), recordedSnapZones' desktop arm (F964) and recordFloatingClose's minimized and output-filling refusals. Without one (unit tests) each is permissive.

◆ setWindowSticky()

void PhosphorPlacement::WindowTrackingService::setWindowSticky ( const QString & windowId,
bool sticky )

Record whether a window is sticky (on all desktops).

◆ snapEngine()

PhosphorEngine::PlacementEngineBase * PhosphorPlacement::WindowTrackingService::snapEngine ( ) const

◆ snappedWindows()

QStringList PhosphorPlacement::WindowTrackingService::snappedWindows ( ) const

Get all snapped windows.

Returns
List of window IDs that are currently snapped

◆ snapZonesOnDesktopInView()

QStringList PhosphorPlacement::WindowTrackingService::snapZonesOnDesktopInView ( const PhosphorEngine::EngineSlot & slot,
const QString & screenId ) const

slot's zones for the desktop screenId shows: the per-desktop map's entry when the slot carries one (empty when it names no zone there), else the flat zoneIds.

◆ stateChanged

void PhosphorPlacement::WindowTrackingService::stateChanged ( )
signal

Emitted when state needs to be saved.

◆ takeDirty()

DirtyMask PhosphorPlacement::WindowTrackingService::takeDirty ( )

Return the current dirty mask, clearing it atomically.

Used by the adaptor's saveState() to snapshot "what needs writing" in one step.

◆ takeResnapBuffer()

QVector< ResnapEntry > PhosphorPlacement::WindowTrackingService::takeResnapBuffer ( )
overridevirtual

◆ unassignWindow()

void PhosphorPlacement::WindowTrackingService::unassignWindow ( const QString & windowId)
overridevirtual

Remove window from its assigned zone.

Parameters
windowIdFull window ID

Implements PhosphorEngine::IWindowTrackingService.

◆ unsnapForFloat()

void PhosphorPlacement::WindowTrackingService::unsnapForFloat ( const QString & windowId)
overridevirtual

Unsnap window for floating (saves zone for later restore).

Parameters
windowIdFull window ID

Implements PhosphorEngine::IWindowTrackingService.

◆ updatedWindowGeometries()

QHash< QString, QRect > PhosphorPlacement::WindowTrackingService::updatedWindowGeometries ( ) const

windowId -> its zone rect in the context in view (else its primary's), for the work-area re-apply.

Empty while keepWindowsInZonesOnResolutionChange is off.

◆ updateLastUsedZone()

void PhosphorPlacement::WindowTrackingService::updateLastUsedZone ( const QString & zoneId,
const QString & screenId,
const QString & windowClass,
int virtualDesktop )
overridevirtual

Update last used zone tracking.

Implements PhosphorEngine::IWindowTrackingService.

◆ userSnappedClasses()

const QSet< QString > & PhosphorPlacement::WindowTrackingService::userSnappedClasses ( ) const

The user-snapped classes.

◆ validatedUnmanagedGeometry()

std::optional< QRect > PhosphorPlacement::WindowTrackingService::validatedUnmanagedGeometry ( const QString & windowId,
const QString & screenId ) const
overridevirtual

Look up a window's free (unmanaged) geometry from the unified WindowPlacementStore and validate it.

PER-WINDOW. It does not fall back to a same-app sibling's record: that was removed in discussion #1028, where a live window with no record of its own inherited a dead instance's absolute coordinates and was moved to whatever monitor that instance last occupied. A window with nothing on record gets nullopt and should be left where it is.

SCREEN-LOCAL when the caller names a screen: it will not search other screens for one. When the caller passes an EMPTY screenId it resolves to the record's OWN screen instead, which can therefore answer a rect for a monitor the window has since left. That is deliberate — the alternative is answering nothing at all for every window snap does not track — but a caller that knows the window's live screen should pass it rather than relying on the record.

The rect is also checked against the screen it is filed under, because the key alone cannot be trusted — see geometryBelongsToScreen, which the other readers of this store share.

Parameters
windowIdFull window ID
screenIdScreen to resolve against; empty resolves to the record's own screen

Implements PhosphorEngine::IWindowTrackingService.

◆ validateGeometryForScreen()

std::optional< QRect > PhosphorPlacement::WindowTrackingService::validateGeometryForScreen ( const QRect & geo,
const QString & savedScreen,
const QString & currentScreenId ) const

Validate and adjust a saved geometry for screen-aware restore.

When savedScreen and currentScreenId name different screens the rect keeps its size (clamped) and is centred on the current screen's available area; otherwise an on-screen rect comes back as is and an off-screen one is clamped onto the nearest screen. Reads the screen manager. Its one caller, validatedUnmanagedGeometry, reaches it only when no screen manager can measure the output, passing the same screen twice.

Parameters
geoSaved geometry (e.g. a window's recorded free geometry)
savedScreenScreen id at capture time (may be empty)
currentScreenIdScreen id the window is on now
Returns
Adjusted geometry, or nullopt if geo is invalid

◆ windowClosed()

void PhosphorPlacement::WindowTrackingService::windowClosed ( const QString & windowId,
PhosphorEngine::WindowKind kind = PhosphorEngine::WindowKind::Unknown )

Clean up all tracking data for a closed window.

Parameters
windowIdFull window ID
kindStructural kind of the closing window. Unused: it gated the pending-restore queue this close used to write, which was removed. Kept so the D-Bus close path keeps its signature.

◆ windowRegistry()

PhosphorEngine::WindowRegistry * PhosphorPlacement::WindowTrackingService::windowRegistry ( ) const

The wired registry, or null.

Read by the daemon's engine seed, release and minimize filters and by the drag adaptor.

◆ windowsInZone()

QStringList PhosphorPlacement::WindowTrackingService::windowsInZone ( const QString & zoneId) const
overridevirtual

Every window holding a zone in any context, each once.

Parameters
zoneIdPhosphorZones::Zone UUID string
Returns
List of window IDs

Implements PhosphorEngine::IWindowTrackingService.

◆ windowZoneChanged

void PhosphorPlacement::WindowTrackingService::windowZoneChanged ( const QString & windowId,
const QString & zoneId )
signal

The window's primary zone changed (empty: it left every zone).

Relayed by WindowTrackingAdaptor::windowZoneChanged; the daemon dismisses Snap Assist on it.

◆ zoneForWindow()

QString PhosphorPlacement::WindowTrackingService::zoneForWindow ( const QString & windowId) const
overridevirtual

Get the primary zone ID for a window.

Parameters
windowIdFull window ID
Returns
PhosphorZones::Zone ID or empty string if not assigned

Implements PhosphorEngine::IWindowTrackingService.

◆ zoneGeometry()

QRect PhosphorPlacement::WindowTrackingService::zoneGeometry ( const QString & zoneId,
const QString & screenId ) const
overridevirtual

Get geometry for a zone on a specific screen.

Parameters
zoneIdPhosphorZones::Zone UUID string
screenIdScreen identifier. With a screen manager wired this must name a resolvable output: an empty or unknown id answers an invalid rect rather than measuring the zone against the primary monitor (see frameScreenIdResolves in navigation.cpp). Without a screen manager there is nothing to resolve against and the primary screen is used.
Returns
PhosphorZones::Zone geometry in pixels, or invalid QRect if not found

Implements PhosphorEngine::IWindowTrackingService.

◆ zonesForWindow()

QStringList PhosphorPlacement::WindowTrackingService::zonesForWindow ( const QString & windowId) const
overridevirtual

Get all zone IDs for a window (multi-zone support).

Parameters
windowIdFull window ID
Returns
List of zone IDs (empty if not assigned)

Implements PhosphorEngine::IWindowTrackingService.


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