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

One window's single, authoritative placement record — the unit of the unified, engine-agnostic restore model. More...

#include <PhosphorEngine/WindowPlacement.h>

Public Member Functions

bool isValid () const
EngineSlot slotFor (const QString &engineId) const
 The slot for engineId, or a default (empty) slot if this engine has no recorded state for the window.
QRect freeGeometryFor (const QString &screenId) const
 The shared free/float geometry for screenId, or an invalid rect if none has been captured on that screen yet.
QString anyFreeGeometryScreenId () const
 The screenId of the deterministic cross-screen fallback pick: the lexicographically-smallest screenId holding a valid rect.
QRect anyFreeGeometry () const
 Any captured free/float geometry (the deterministic pick of anyFreeGeometryScreenId()), used as a cross-screen fallback when the exact screen has none.
bool hasRestorableContent () const
 Whether this record carries anything worth restoring.
bool sameContentAs (const WindowPlacement &o) const
 Content equality IGNORING sequence (the store stamps a fresh sequence on every record(), so it must not count as a change).
QJsonObject toJson () const

Static Public Member Functions

static QLatin1String snapEngineId ()
 Built-in engine-slot ids.
static QLatin1String autotileEngineId ()
static QLatin1String scrollingEngineId ()
static QLatin1String stateFree ()
 Common state-token vocabulary.
static QLatin1String stateFloating ()
static QLatin1String stateSnapped ()
static QLatin1String stateTiled ()
static QLatin1String stateReleased ()
 An engine that KNOWINGLY GAVE THE WINDOW UP (a cross-mode handoff) leaves this instead of its managed slot.
static WindowPlacement fromJson (const QString &appId, const QJsonObject &obj)

Public Attributes

QString windowId
 full appId|uuid; exact key for daemon-restart (uuid stable)
QString appId
 window class; FIFO key for close/reopen (uuid changes)
QString screenId
 last managed-context screen
int virtualDesktop = 0
 0 = all-desktops / sticky / unknown.
QString activity
 empty = all-activities / unknown
WindowKind kind = WindowKind::Unknown
QHash< QString, EngineSlot > engines
QHash< QString, QRect > freeGeometryByScreen
quint64 sequence = 0
bool reclaimEligible = true
 The cross-screen reclaim's credit, retired with the reclaim: a window is now restored only on the output it opens on, so nothing rations cross-monitor pulls any more.
qint64 closedAtMsecs = 0
 INERT, kept for ABI layout. Never stamped or read.

Detailed Description

One window's single, authoritative placement record — the unit of the unified, engine-agnostic restore model.

The WindowPlacementStore holds at most ONE record per window (NOT one per engine). The record carries:

  • per-engine STATE in engines (keyed by IPlacementEngine::engineId()): each engine's own slot + state, independent of the others (per-mode float independence — floating in snap does not float in autotile);
  • ONE SHARED free/float GEOMETRY in freeGeometryByScreen: the position the window occupies when it is NOT engine-managed, shared across snap/autotile but keyed PER SCREEN so a window remembers a distinct free spot per monitor. Written ONLY from a genuine free/floating frame; FROZEN while the window is snapped or tiled. A zone/tile rect never enters this map.

Extensibility: a new engine needs no change here — it keys its own slot under its engineId() and reads/writes the shared geometry. Core code never interprets an EngineSlot::state beyond equality.

Member Function Documentation

◆ anyFreeGeometry()

QRect PhosphorEngine::WindowPlacement::anyFreeGeometry ( ) const
inline

Any captured free/float geometry (the deterministic pick of anyFreeGeometryScreenId()), used as a cross-screen fallback when the exact screen has none.

Returns an invalid rect when the window has no free geometry on record at all.

◆ anyFreeGeometryScreenId()

QString PhosphorEngine::WindowPlacement::anyFreeGeometryScreenId ( ) const
inline

The screenId of the deterministic cross-screen fallback pick: the lexicographically-smallest screenId holding a valid rect.

There is no per-screen recency to pick a "newest", and QHash iteration order is unspecified — without a total order the fallback float-back screen would differ run to run. Empty when no screen has a valid rect.

◆ autotileEngineId()

QLatin1String PhosphorEngine::WindowPlacement::autotileEngineId ( )
inlinestatic

◆ freeGeometryFor()

QRect PhosphorEngine::WindowPlacement::freeGeometryFor ( const QString & screenId) const
inline

The shared free/float geometry for screenId, or an invalid rect if none has been captured on that screen yet.

The exact key wins, so a genuinely per-virtual-screen capture keeps its own remembered spot. On a miss the search widens to keys on the SAME PHYSICAL OUTPUT — and no further. That is not a cross-screen fallback (which was removed on purpose, because answering from another monitor teleports the window); virtual screens subdivide one output and share its coordinate space, so a rect filed under a sibling subdivision is already in the right coordinates.

The widening is load-bearing, not defensive. VirtualScreenMigration rewrites these keys to the new virtual screen by the window's zones, or for a record with no zones (a floating window has none by definition) by the virtual screen the rect's centre falls in. A rect that no virtual screen holds, one left partly off the output for instance, keeps its PHYSICAL key while every reader asks with a virtual id, and an exact-only lookup would miss it.

◆ fromJson()

WindowPlacement PhosphorEngine::WindowPlacement::fromJson ( const QString & appId,
const QJsonObject & obj )
inlinestatic

◆ hasRestorableContent()

bool PhosphorEngine::WindowPlacement::hasRestorableContent ( ) const
inline

Whether this record carries anything worth restoring.

True when the window has a captured free/float geometry, OR a MANAGED slot (snapped/tiled, which restore by zone/tile reference), OR a slot that still references a zone (zoneIds — a floated-from-snap window's pre-float zones, or a zone on another desktop in zonesByDesktop) or a tile order.

A bare slot with no geometry, no zone reference, and no tile order — whether floating (a never-snapped floated window captured frame-less) or the retired free token — has NOTHING to restore. Snapping now defaults every unmanaged window to floating, so this geometry-less floated residue is exactly the case that must be rejected: it must NOT be persisted, and the snap restore's accept predicate must never CONSUME it from the per-app FIFO. At MaxPerApp entries per app, such residue would otherwise starve and even evict the window's real placement (evictForCapacity prefers a contentless victim but falls back to the FIFO head), silently breaking geometry restore.

◆ isValid()

bool PhosphorEngine::WindowPlacement::isValid ( ) const
inline

◆ sameContentAs()

bool PhosphorEngine::WindowPlacement::sameContentAs ( const WindowPlacement & o) const
inline

Content equality IGNORING sequence (the store stamps a fresh sequence on every record(), so it must not count as a change).

Lets the merge in record() short-circuit a re-capture that produced an identical placement — the save-time refreshOpenWindowPlacements() re-captures every open window each tick, and without this an unchanged window would re-mark dirty and reschedule the save timer forever (a self-perpetuating save/capture loop).

◆ scrollingEngineId()

QLatin1String PhosphorEngine::WindowPlacement::scrollingEngineId ( )
inlinestatic

◆ slotFor()

EngineSlot PhosphorEngine::WindowPlacement::slotFor ( const QString & engineId) const
inline

The slot for engineId, or a default (empty) slot if this engine has no recorded state for the window.

◆ snapEngineId()

QLatin1String PhosphorEngine::WindowPlacement::snapEngineId ( )
inlinestatic

Built-in engine-slot ids.

Cross-engine readers (such as the resnap and the teardown capture) key slotFor() on these instead of spelling the id inline — same drift-prevention rationale as the state-token accessors below. Each engine's own engineId() override returns the same spelling.

◆ stateFloating()

QLatin1String PhosphorEngine::WindowPlacement::stateFloating ( )
inlinestatic

◆ stateFree()

QLatin1String PhosphorEngine::WindowPlacement::stateFree ( )
inlinestatic

Common state-token vocabulary.

Engines may define more; these cover the built-in snap/autotile states. Retired snap state — snapping is now two-state (snapped/floating). No engine produces it any more; a legacy free record persisted by an older build deserializes to this token and is restored as floating (see SnapEngine::resolveWindowRestore). Retained only for that legacy-record mapping and the tests that exercise it.

◆ stateReleased()

QLatin1String PhosphorEngine::WindowPlacement::stateReleased ( )
inlinestatic

An engine that KNOWINGLY GAVE THE WINDOW UP (a cross-mode handoff) leaves this instead of its managed slot.

It is deliberately not an absent slot: takeForReopen's exact-final gate treats "a record for this instance carrying a slot for the ASKING engine that the reopen predicate rejects" as a FINAL verdict with no FIFO fallback, and a released window must keep that verdict — dropping the slot outright made it indistinguishable from a fresh open, which then consumed a SIBLING instance's floating record and restored at the sibling's position. It is equally not a managed state: the reopen claim keys on snapped/tiled, so a released slot can no longer advertise a home the engine has given up.

◆ stateSnapped()

QLatin1String PhosphorEngine::WindowPlacement::stateSnapped ( )
inlinestatic

◆ stateTiled()

QLatin1String PhosphorEngine::WindowPlacement::stateTiled ( )
inlinestatic

◆ toJson()

QJsonObject PhosphorEngine::WindowPlacement::toJson ( ) const
inline

Member Data Documentation

◆ activity

QString PhosphorEngine::WindowPlacement::activity

empty = all-activities / unknown

◆ appId

QString PhosphorEngine::WindowPlacement::appId

window class; FIFO key for close/reopen (uuid changes)

◆ closedAtMsecs

qint64 PhosphorEngine::WindowPlacement::closedAtMsecs = 0

INERT, kept for ABI layout. Never stamped or read.

◆ engines

QHash<QString, EngineSlot> PhosphorEngine::WindowPlacement::engines

◆ freeGeometryByScreen

QHash<QString, QRect> PhosphorEngine::WindowPlacement::freeGeometryByScreen

◆ kind

WindowKind PhosphorEngine::WindowPlacement::kind = WindowKind::Unknown

◆ reclaimEligible

bool PhosphorEngine::WindowPlacement::reclaimEligible = true

The cross-screen reclaim's credit, retired with the reclaim: a window is now restored only on the output it opens on, so nothing rations cross-monitor pulls any more.

Nothing reads it. It still round-trips as "liveAtSave" so an older daemon reading a newer file sees the default it always wrote for a live window, and stays OUTSIDE sameContentAs like sequence.

◆ screenId

QString PhosphorEngine::WindowPlacement::screenId

last managed-context screen

◆ sequence

quint64 PhosphorEngine::WindowPlacement::sequence = 0

◆ virtualDesktop

int PhosphorEngine::WindowPlacement::virtualDesktop = 0

0 = all-desktops / sticky / unknown.

The three meanings are deliberately conflated in one sentinel: LayoutRegistry::modeForScreen treats 0 as its supported desktop-agnostic input, which is the right answer for a genuinely sticky window and an approximation for a window whose desktop was simply never captured (a plain setFloating records none). Under per-desktop mode splits the approximation can resolve a mode the window's real desktop does not have; splitting the sentinel into sticky-vs-unknown is a persisted-data-model change and has not been taken.

◆ windowId

QString PhosphorEngine::WindowPlacement::windowId

full appId|uuid; exact key for daemon-restart (uuid stable)


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