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

#include <PhosphorEngine/IWindowTrackingService.h>

Inheritance diagram for PhosphorEngine::IWindowTrackingService:
[legend]

Public Member Functions

virtual ~IWindowTrackingService ()=default
virtual QObject * asQObject ()=0
virtual PhosphorScreens::ScreenManager * screenManager () const =0
virtual QRect screenAvailableGeometry (const QString &screenId) const =0
 The area of screenId a window may occupy (the output minus panels and struts), or an invalid rect when the screen cannot be resolved.
virtual void assignWindowToZone (const QString &windowId, const QString &zoneId, const QString &screenId, int virtualDesktop)=0
virtual void assignWindowToZones (const QString &windowId, const QStringList &zoneIds, const QString &screenId, int virtualDesktop)=0
virtual void unassignWindow (const QString &windowId)=0
virtual QStringList recordedSnapZones (const QString &windowId) const =0
 A window's recorded snap zone(s), preferring the LIVE assignment but falling back to the DURABLE placement-record snap slot when the live cache is cold.
virtual QString zoneForWindow (const QString &windowId) const =0
virtual QStringList zonesForWindow (const QString &windowId) const =0
virtual QString screenForWindow (const QString &windowId) const =0
 The screen a window is assigned to (empty when none), canonicalizing the id so a window resolves across the effect-restart re-identification skew (#628).
virtual QString screenForWindow (const QString &windowId, const QString &defaultScreen) const =0
 Same, returning defaultScreen when the window has no assignment.
virtual QStringList windowsInZone (const QString &zoneId) const =0
virtual bool isWindowSnapped (const QString &windowId) const =0
virtual QString findEmptyZone (const QString &screenId=QString()) const =0
virtual void recordSnapIntent (const QString &windowId, bool wasUserInitiated)=0
virtual bool isWindowFloating (const QString &windowId) const =0
virtual bool isSuspensionFloat (const QString &windowId) const
 Whether the window's float is a MINIMIZE SUSPENSION rather than placement intent.
virtual void clearSuspensionFloat (const QString &windowId)
 Drop the suspension classification.
virtual void setWindowFloating (const QString &windowId, bool floating)=0
virtual void unsnapForFloat (const QString &windowId)=0
virtual bool clearFloatingForSnap (const QString &windowId)=0
virtual bool isWindowSticky (const QString &windowId) const =0
virtual QStringList preFloatZones (const QString &windowId) const =0
virtual QString preFloatScreen (const QString &windowId) const =0
virtual void clearPreFloatZone (const QString &windowId)=0
 Clear the saved pre-float zone/screen for windowId (both the windowId key and its appId alias).
virtual bool clearAutoSnapped (const QString &windowId)=0
virtual void updateLastUsedZone (const QString &zoneId, const QString &screenId, const QString &windowClass, int virtualDesktop)=0
virtual QString currentAppIdFor (const QString &anyWindowId) const =0
virtual std::optional< QRect > validatedUnmanagedGeometry (const QString &windowId, const QString &screenId) const =0
 The window's remembered UNMANAGED (free/float-back) geometry, resolved FOR screenId, or nullopt when no record can answer.
virtual bool geometryBelongsToScreen (const QRect &geometry, const QString &screenId) const =0
 Does geometry plausibly belong to the coordinate space screenId names?
virtual void recordFreeGeometry (const QString &windowId, const QString &screenId, const QRect &geometry, bool overwrite)=0
 Record a window's SHARED free/float geometry (the placement record's freeGeometryByScreen), so snap and autotile read the same value.
virtual void clearFreeGeometry (const QString &windowId)=0
 Clear a window's shared free/float geometry (all screens) from the record, leaving its engine slots intact.
virtual void releaseEngineSlot (const QString &windowId, const QString &engineId)
 Downgrade engineId's slot on windowId's record to WindowPlacement::stateReleased() and mark the placements dirty.
virtual void forgetDesktopZones (const QString &windowId, const QString &engineId, int desktop)
 Drop desktop's entry from engineId's per-desktop zone map on windowId's record and mark the placements dirty.
virtual void renumberDesktopZones (int removedDesktop)
 Apply a desktop removal to every persisted per-desktop zone map (drop removedDesktop, shift the entries above it down) and mark the placements dirty.
virtual void clearFreeGeometry (const QString &windowId, const QString &screenId)
 Screen-scoped consume-once variant: clears only screenId's remembered float-back, preserving other monitors' entries.
virtual QRect zoneGeometry (const QString &zoneId, const QString &screenId) const =0
 Frame for zoneId measured against screenId.
virtual QRect resolveZoneGeometry (const QStringList &zoneIds, const QString &screenId) const =0
virtual QString resolveEffectiveScreenId (const QString &screenId) const =0
virtual WindowPlacementStore & placementStore ()=0
 The unified, engine-agnostic placement store.
virtual QString findEmptyZoneInLayout (PhosphorZones::Layout *layout, const QString &screenId, int desktopFilter=0) const =0
virtual QSet< QUuid > buildOccupiedZoneSet (const QString &screenFilter=QString(), int desktopFilter=0) const =0
virtual QVector< ResnapEntry > takeResnapBuffer ()=0
virtual void markLastUsedZoneDirty ()
 An engine cleared a last-used zone in one of its stores: persist it.
virtual void remapDesktopZones (const DesktopRemap &remap)
 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.

Constructor & Destructor Documentation

◆ ~IWindowTrackingService()

virtual PhosphorEngine::IWindowTrackingService::~IWindowTrackingService ( )
virtualdefault

Member Function Documentation

◆ asQObject()

virtual QObject * PhosphorEngine::IWindowTrackingService::asQObject ( )
pure virtual

◆ assignWindowToZone()

virtual void PhosphorEngine::IWindowTrackingService::assignWindowToZone ( const QString & windowId,
const QString & zoneId,
const QString & screenId,
int virtualDesktop )
pure virtual

◆ assignWindowToZones()

virtual void PhosphorEngine::IWindowTrackingService::assignWindowToZones ( const QString & windowId,
const QStringList & zoneIds,
const QString & screenId,
int virtualDesktop )
pure virtual

◆ buildOccupiedZoneSet()

virtual QSet< QUuid > PhosphorEngine::IWindowTrackingService::buildOccupiedZoneSet ( const QString & screenFilter = QString(),
int desktopFilter = 0 ) const
pure virtual

◆ clearAutoSnapped()

virtual bool PhosphorEngine::IWindowTrackingService::clearAutoSnapped ( const QString & windowId)
pure virtual

◆ clearFloatingForSnap()

virtual bool PhosphorEngine::IWindowTrackingService::clearFloatingForSnap ( const QString & windowId)
pure virtual

◆ clearFreeGeometry() [1/2]

virtual void PhosphorEngine::IWindowTrackingService::clearFreeGeometry ( const QString & windowId)
pure virtual

Clear a window's shared free/float geometry (all screens) from the record, leaving its engine slots intact.

For the drag-out / layout-change consume paths that restore the float-back once and must not re-apply it.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ clearFreeGeometry() [2/2]

virtual void PhosphorEngine::IWindowTrackingService::clearFreeGeometry ( const QString & windowId,
const QString & screenId )
inlinevirtual

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 in PhosphorPlacement::WindowTrackingService.

◆ clearPreFloatZone()

virtual void PhosphorEngine::IWindowTrackingService::clearPreFloatZone ( const QString & windowId)
pure virtual

Clear the saved pre-float zone/screen for windowId (both the windowId key and its appId alias).

Used to drop stale pre-float state when a floating window crosses monitors, so a later unfloat does not restore it to a zone on the monitor it left.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ clearSuspensionFloat()

virtual void PhosphorEngine::IWindowTrackingService::clearSuspensionFloat ( const QString & windowId)
inlinevirtual

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 in PhosphorPlacement::WindowTrackingService.

◆ currentAppIdFor()

virtual QString PhosphorEngine::IWindowTrackingService::currentAppIdFor ( const QString & anyWindowId) const
pure virtual

◆ findEmptyZone()

virtual QString PhosphorEngine::IWindowTrackingService::findEmptyZone ( const QString & screenId = QString()) const
pure virtual

◆ findEmptyZoneInLayout()

virtual QString PhosphorEngine::IWindowTrackingService::findEmptyZoneInLayout ( PhosphorZones::Layout * layout,
const QString & screenId,
int desktopFilter = 0 ) const
pure virtual

◆ forgetDesktopZones()

virtual void PhosphorEngine::IWindowTrackingService::forgetDesktopZones ( const QString & windowId,
const QString & engineId,
int desktop )
inlinevirtual

Drop desktop's entry from engineId's per-desktop zone map on windowId's record and mark the placements dirty.

The store MERGES that map, so a capture that stops naming a desktop does not forget it: an engine that releases a window from a desktop its span no longer covers says so here, or the stale zone survives every later save and a restart puts the window back on a desktop it left. Default no-op for the same reason releaseEngineSlot's is.

Reimplemented in PhosphorPlacement::WindowTrackingService.

◆ geometryBelongsToScreen()

virtual bool PhosphorEngine::IWindowTrackingService::geometryBelongsToScreen ( const QRect & geometry,
const QString & screenId ) const
pure virtual

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.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ isSuspensionFloat()

virtual bool PhosphorEngine::IWindowTrackingService::isSuspensionFloat ( const QString & windowId) const
inlinevirtual

Whether the window's float is a MINIMIZE SUSPENSION rather than placement intent.

Outlives the live minimize bit through the unminimize animation grace so capture paths can keep preserving the pre-minimize record. Default false for implementations that do not track the classification.

Reimplemented in PhosphorPlacement::WindowTrackingService.

◆ isWindowFloating()

virtual bool PhosphorEngine::IWindowTrackingService::isWindowFloating ( const QString & windowId) const
pure virtual

◆ isWindowSnapped()

virtual bool PhosphorEngine::IWindowTrackingService::isWindowSnapped ( const QString & windowId) const
pure virtual

◆ isWindowSticky()

virtual bool PhosphorEngine::IWindowTrackingService::isWindowSticky ( const QString & windowId) const
pure virtual

◆ markLastUsedZoneDirty()

virtual void PhosphorEngine::IWindowTrackingService::markLastUsedZoneDirty ( )
inlinevirtual

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

Reimplemented in PhosphorPlacement::WindowTrackingService.

◆ placementStore()

virtual WindowPlacementStore & PhosphorEngine::IWindowTrackingService::placementStore ( )
pure virtual

The unified, engine-agnostic placement store.

Engines reach it through the tracking service to capture/restore the one WindowPlacement per window.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ preFloatScreen()

virtual QString PhosphorEngine::IWindowTrackingService::preFloatScreen ( const QString & windowId) const
pure virtual

◆ preFloatZones()

virtual QStringList PhosphorEngine::IWindowTrackingService::preFloatZones ( const QString & windowId) const
pure virtual

◆ recordedSnapZones()

virtual QStringList PhosphorEngine::IWindowTrackingService::recordedSnapZones ( const QString & windowId) const
pure virtual

A window's recorded snap zone(s), preferring the LIVE assignment but falling back to the DURABLE placement-record snap slot when the live cache is cold.

The live per-store zone maps are runtime-only — a daemon restart (and handoffRelease on autotile entry) clears them — so consumers that must survive a restart (the autotile→snap resnap) read this instead. Only the window's OWN record counts, never a sibling instance's: a window that was never snapped in either source answers an empty list.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ recordFreeGeometry()

virtual void PhosphorEngine::IWindowTrackingService::recordFreeGeometry ( const QString & windowId,
const QString & screenId,
const QRect & geometry,
bool overwrite )
pure virtual

Record a window's SHARED free/float geometry (the placement record's freeGeometryByScreen), so snap and autotile read the same value.

Refuses a rect off screenId, a managed frame and the frame of a window in a zone or tile in view; a caller that SAMPLES a frame refuses a minimized or output-filling window's itself. overwrite=false leaves an existing entry for screenId untouched (first-capture-wins). No-op on an invalid geometry.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ recordSnapIntent()

virtual void PhosphorEngine::IWindowTrackingService::recordSnapIntent ( const QString & windowId,
bool wasUserInitiated )
pure virtual

◆ releaseEngineSlot()

virtual void PhosphorEngine::IWindowTrackingService::releaseEngineSlot ( const QString & windowId,
const QString & engineId )
inlinevirtual

Downgrade engineId's slot on windowId's record to WindowPlacement::stateReleased() and mark the placements dirty.

Called by an engine that KNOWINGLY gives a window up (cross-mode handoff), and for a window that left its screen, because a stale managed slot would read as a restorable home. Default no-op: an embedder without persistence has nothing to downgrade. NOT for ordinary close — a window that closed tiled keeps its slot, which is what login restore reads.

Reimplemented in PhosphorPlacement::WindowTrackingService.

◆ remapDesktopZones()

virtual void PhosphorEngine::IWindowTrackingService::remapDesktopZones ( const DesktopRemap & remap)
inlinevirtual

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 in PhosphorPlacement::WindowTrackingService.

◆ renumberDesktopZones()

virtual void PhosphorEngine::IWindowTrackingService::renumberDesktopZones ( int removedDesktop)
inlinevirtual

Apply a desktop removal to every persisted per-desktop zone map (drop removedDesktop, shift the entries above it down) and mark the placements dirty.

The engines renumber their live stores on the same event; the record has to follow or a restart seeds a zone under a number that now names a different desktop. Default no-op.

Reimplemented in PhosphorPlacement::WindowTrackingService.

◆ resolveEffectiveScreenId()

virtual QString PhosphorEngine::IWindowTrackingService::resolveEffectiveScreenId ( const QString & screenId) const
pure virtual

◆ resolveZoneGeometry()

virtual QRect PhosphorEngine::IWindowTrackingService::resolveZoneGeometry ( const QStringList & zoneIds,
const QString & screenId ) const
pure virtual

◆ screenAvailableGeometry()

virtual QRect PhosphorEngine::IWindowTrackingService::screenAvailableGeometry ( const QString & screenId) const
pure virtual

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.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ screenForWindow() [1/2]

virtual QString PhosphorEngine::IWindowTrackingService::screenForWindow ( const QString & windowId) const
pure virtual

The screen a window is assigned to (empty when none), canonicalizing the id so a window resolves across the effect-restart re-identification skew (#628).

There is deliberately no flat whole-map accessor on this interface: window placement is stored per (screen, desktop, activity) context, and a cross-store union erases the context that per-desktop consumers need.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ screenForWindow() [2/2]

virtual QString PhosphorEngine::IWindowTrackingService::screenForWindow ( const QString & windowId,
const QString & defaultScreen ) const
pure virtual

Same, returning defaultScreen when the window has no assignment.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ screenManager()

virtual PhosphorScreens::ScreenManager * PhosphorEngine::IWindowTrackingService::screenManager ( ) const
pure virtual

◆ setWindowFloating()

virtual void PhosphorEngine::IWindowTrackingService::setWindowFloating ( const QString & windowId,
bool floating )
pure virtual

◆ takeResnapBuffer()

virtual QVector< ResnapEntry > PhosphorEngine::IWindowTrackingService::takeResnapBuffer ( )
pure virtual

◆ unassignWindow()

virtual void PhosphorEngine::IWindowTrackingService::unassignWindow ( const QString & windowId)
pure virtual

◆ unsnapForFloat()

virtual void PhosphorEngine::IWindowTrackingService::unsnapForFloat ( const QString & windowId)
pure virtual

◆ updateLastUsedZone()

virtual void PhosphorEngine::IWindowTrackingService::updateLastUsedZone ( const QString & zoneId,
const QString & screenId,
const QString & windowClass,
int virtualDesktop )
pure virtual

◆ validatedUnmanagedGeometry()

virtual std::optional< QRect > PhosphorEngine::IWindowTrackingService::validatedUnmanagedGeometry ( const QString & windowId,
const QString & screenId ) const
pure virtual

The window's remembered UNMANAGED (free/float-back) geometry, resolved FOR screenId, or nullopt when no record can answer.

"Validated" describes the POSITION, not the size: the answer is the spot remembered for screenId, sanity-checked against the live screen layout so a rect left off-canvas by a resolution change is pulled back.

SCREEN-LOCAL. A spot remembered on another monitor is not a float-back for this one, so there is no cross-screen fallback — a non-null answer IS evidence the window was free on this screen. Callers that find nothing leave the window where it is.

The lookup is restricted to the window's OWN record. It used to take an exactOnly flag defaulting to FALSE, which admitted a same-app SIBLING's free geometry as cross-instance float-back sharing. Every caller of this function asks a per-window question — "put THIS window back where IT was" — and for that the share is not a convenience but a teleport: an app's bucket fills with dead instances (MaxPerApp), a live window with no record of its own borrows a ghost's, and it lands wherever that ghost last was, on whatever monitor. Discussion #1028 is that bug. Two of the three engines had already opted out and written down why; the flag is gone so the remaining paths cannot drift back.

The SIZE is whatever the compositor last reported and is never bounded here. A caller minting a SIZING INTENT out of it (a Fixed column width, a fixed tile height) owes it a bound of its own — the extents are untrusted input from a compositor and, through the injected service, from an embedder. Callers that only re-place a window at a remembered spot need no such bound.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ windowsInZone()

virtual QStringList PhosphorEngine::IWindowTrackingService::windowsInZone ( const QString & zoneId) const
pure virtual

◆ zoneForWindow()

virtual QString PhosphorEngine::IWindowTrackingService::zoneForWindow ( const QString & windowId) const
pure virtual

◆ zoneGeometry()

virtual QRect PhosphorEngine::IWindowTrackingService::zoneGeometry ( const QString & zoneId,
const QString & screenId ) const
pure virtual

Frame for zoneId measured against screenId.

The id is REQUIRED: an implementation backed by a screen manager answers an invalid rect for an empty or unresolvable id rather than standing the primary output in, because callers only check isValid() and a wrong monitor moves the window.

Implemented in PhosphorPlacement::WindowTrackingService.

◆ zonesForWindow()

virtual QStringList PhosphorEngine::IWindowTrackingService::zonesForWindow ( const QString & windowId) const
pure virtual

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