PhosphorEngine Namespace Reference

Namespaces
namespace	GapResolution
	Shared resolution of gap-override layers expressed as PerScreenKeys-shaped QVariantMaps (context-rule gap overrides, per-screen config overrides).
namespace	GeometryDefaults
namespace	GeometryUtils
namespace	JsonKeys
namespace	PerScreenKeys

Classes
struct	ContextChange
	Outcome of a context mutation on ScreenContextTracker. More...
struct	EngineSlot
	One engine's view of a window: which managed slot it occupies (or that it is floating / unmanaged) in THAT engine's mode. More...
class	IAutotileSettings
class	ICrossSurfaceResolver
	Resolves the neighbouring surface — output or virtual desktop — in a direction, for cross-surface window navigation. More...
class	IGeometrySettings
class	IPlacementEngine
	Unified placement engine interface. More...
class	IPlacementState
	Per-screen placement state contract. More...
class	ISnapSettings
class	IVirtualDesktopManager
class	IWindowRegistry
class	IWindowTrackingService
struct	LayerSwitchResult
	Outcome of resolving a layer focus switch. More...
struct	LayerSwitchSide
	One side (tiled or floating) of a layer focus switch, as the owning engine sees it. More...
struct	NavigationContext
	Target window + screen for a navigation or lifecycle operation. More...
struct	PendingRestore
class	PerScreenStates
	The two cooperating maps a per-monitor placement engine keeps: a forward map from PlacementStateKey to the owning per-screen state object (Qt-parent-owned by the engine, constructed via a caller-supplied factory), and a reverse map from windowId to its owning key. More...
class	PlacementEngineBase
	Abstract base class for placement engines. More...
struct	PlacementStateKey
	Identity of a per-screen placement state: a window's placement is scoped to the (screen, virtual desktop, activity) triple it was created in. More...
struct	ResnapEntry
class	ScreenContextTracker
	Tracks the "current context" of each screen for a placement engine: the global current virtual desktop, per-output desktop overrides (Plasma 6.7 "switch desktops independently per screen", #648), the sticky-desktop pin (KWin "virtualdesktopsonlyonprimary" model), and the current activity. More...
struct	SnapResult
struct	UnfloatResult
struct	WindowMetadata
struct	WindowPlacement
	One window's single, authoritative placement record — the unit of the unified, engine-agnostic restore model. More...
class	WindowPlacementStore
	The single source of truth for window restore state in the unified model. More...
class	WindowRegistry
struct	ZoneAssignmentEntry

Typedefs
using	TilingStateKey = PlacementStateKey
	Backwards-compatible spelling for autotile's existing sources.

Enumerations
enum class	SnapIntent { UserInitiated , AutoRestored }
enum class	WindowKind : int { Unknown = 0 , Normal = 1 , Transient = 2 }
	Coarse structural classification for the snap-restore consume gate. More...
enum class	StickyWindowHandling { TreatAsNormal = 0 , RestoreOnly = 1 , IgnoreAll = 2 }

Functions
size_t	qHash (const PlacementStateKey &key, size_t seed=0)
WindowKind	clampWindowKindFromWire (int wire)
	Clamp an integer wire value to a valid WindowKind.
constexpr QLatin1StringView	RestoreSentinel ("__restore__")
PHOSPHORENGINE_EXPORT LayerSwitchResult	resolveLayerFocusSwitch (bool floatingHasFocus, const LayerSwitchSide &tiledSide, const LayerSwitchSide &floatingSide)
	Resolve niri's switch-focus-between-floating-and-tiling for any engine: pick the leg from floatingHasFocus, then the target on the far side — its candidate if eligible, else the first eligible fallback.
bool	hasStableAppIdFor (const QString &appId, const QString &windowId)
	Shared cross-engine ownership predicate over a placement record: does this record carry engineId's slot in its MANAGED state (managedState — snap "snapped", autotile/scrolling "tiled") with a RECORDED screen that is a DIFFERENT screen than the opening one, itself currently in that engine's mode, resolved in the RECORD'S OWN (desktop, activity) context? A same-screen record (or one with no screen of its own) is never "cross-screen": the window is already where its managed slot lives, so the engine owning the OPENING context claims it and the slot merely lies dormant.
bool	recordContextMatchesLive (const WindowPlacement &p, int liveDesktop, const QString &liveActivity)
	Whether a record's own (desktop, activity) context is compatible with the live context an engine would INSERT it into — the guard a cross-screen claim needs because the reclaim VERDICT is granted on the record's context while the adoption keys the window by the home screen's CURRENT context.
template<typename IsEngineMode >
bool	pendingCrossScreenManagedRestore (const WindowPlacement &p, QLatin1String engineId, QLatin1String managedState, const QString &openingScreenId, IsEngineMode &&isEngineMode)
template<typename IsSnappingMode >
bool	pendingCrossScreenSnapRestore (const WindowPlacement &p, const QString &openingScreenId, IsSnappingMode &&isSnappingMode)
	The snap-engine specialization of pendingCrossScreenManagedRestore — the original three-way gate (SnapEngine claims, AutotileEngine and ScrollEngine defer).

Typedef Documentation

TilingStateKey

using PhosphorEngine::TilingStateKey = typedef PlacementStateKey

Backwards-compatible spelling for autotile's existing sources.

The autotile engine predates the shared base primitives and refers to this triple as TilingStateKey; keep the alias so that source keeps compiling unchanged.

Enumeration Type Documentation

SnapIntent

enum class PhosphorEngine::SnapIntent

strong

Enumerator
UserInitiated
AutoRestored

StickyWindowHandling

enum class PhosphorEngine::StickyWindowHandling

strong

Enumerator
TreatAsNormal
RestoreOnly
IgnoreAll

WindowKind

enum class PhosphorEngine::WindowKind : int

strong

Coarse structural classification for the snap-restore consume gate.

Wire/JSON encoding is int; Unknown is the permissive default.

Enumerator
Unknown
Normal
Transient

Function Documentation

clampWindowKindFromWire()

WindowKind PhosphorEngine::clampWindowKindFromWire ( int  wire )

inline

Clamp an integer wire value to a valid WindowKind.

Unknown wire values (out-of-range, future enum values from an older daemon) collapse to Unknown rather than producing an undefined enum. The close-capture consume gate (CloseCaptureContext::windowKind) refuses only when both sides are concrete and disagree, so Unknown is permissive — the safe-by-default policy. On the restore side the value is carried in the record for that gate; SnapEngine::resolveWindowRestore itself no longer branches on it. Centralised here so the persistence-layer call sites (WindowTrackingAdaptor::windowClosed, SnapAdaptor::resolveWindowRestore, WindowPlacement::fromJson) stay in lockstep when a new kind is added.

hasStableAppIdFor()

bool PhosphorEngine::hasStableAppIdFor ( const QString &  appId, const QString &  windowId  )

inline

Shared cross-engine ownership predicate over a placement record: does this record carry engineId's slot in its MANAGED state (managedState — snap "snapped", autotile/scrolling "tiled") with a RECORDED screen that is a DIFFERENT screen than the opening one, itself currently in that engine's mode, resolved in the RECORD'S OWN (desktop, activity) context? A same-screen record (or one with no screen of its own) is never "cross-screen": the window is already where its managed slot lives, so the engine owning the OPENING context claims it and the slot merely lies dormant.

Without the same-screen bail, a record whose (desktop, activity) context differs from the opening one — a sticky window, or a per-desktop mode split on one monitor — would defer here while the owner's reciprocal gate also stands down, stranding the window unmanaged.

Every engine is BOTH a claimer and a deferrer through this one predicate: the engine whose (engineId, managedState) matches the record — with the recorded screen still in that engine's mode — claims the window cross-screen (snap via resolveWindowRestore's recorded-screen restore, the tiling engines via claimCrossScreenReopen), and every OTHER engine's open path stands down. KWin's session restore opens windows on a nondeterministic output, so a window whose record homes it on monitor A routinely arrives on monitor B; without the reclaim it strands there, unmanaged, on whatever engine owns B (the login-restore windows-on-the-wrong-monitor bug). Every engine must reach its verdict from the same record or the window ends up both-claimed or both-skipped. Keying on the record's context (not each engine's live current desktop, which can differ under per-screen virtual-desktop overrides) plus running this ONE predicate on every side makes the N-way agreement hold by construction: mode is exclusive per (screen, desktop, activity), so at most one engine's mode check passes for the recorded home. A new tiling engine must add both the defer gate and the claim.

Callers must pass a MANAGED token as managedState (stateSnapped / stateTiled) — the function itself matches whatever token it is handed. Float restore is screen-local by doctrine (it restores a position WITHIN the monitor KWin chose, never moves the window across monitors), so a FLOATING state must never be used to earn a cross-screen pull.

A matched slot is NOT proof of current ownership. Engine slots are only ever merged, never cleared on ordinary close (a window that closed tiled keeps its slot — that persistence IS what login restore reads), and an engine that knowingly gives a window up mid-session must clear its slot via WindowPlacementStore::clearEngineSlot, or the stale slot plus the record-level screenId will read as a home to pull the window back to. The record-level screenId is likewise only as fresh as the last owning engine's successful capture; engine-miss captures leave it stale. Both halves are why claimants must validate the verdict against LIVE state (live screen set, membership after adoption) rather than trusting the record alone.

isEngineMode is invoked as (screenId, virtualDesktop, activity) → bool and must answer whether that context resolves to engineId's mode; callers wrap their layout-manager mode lookup (and any null-manager permissiveness) in it, keeping this library free of the zones-layer mode type. Whether windowId carries a stable, FIFO-matchable appId — the guard every cross-engine gate and claim runs before consulting the placement store. A bare id (no appId|uuid composite, so extractAppId returns the id itself) or an empty appId has no bucket: no record can match it, and treating it as matchable would let a degenerate id slip past the same-screen bail (empty compares unequal to every screen). Spelled once here because five call sites across three engines each carried the same two-term test inline, and a sixth engine would get it wrong by omission.

pendingCrossScreenManagedRestore()

template<typename IsEngineMode >

bool PhosphorEngine::pendingCrossScreenManagedRestore	(	const WindowPlacement &	p,
		QLatin1String	engineId,
		QLatin1String	managedState,
		const QString &	openingScreenId,
		IsEngineMode &&	isEngineMode
	)

pendingCrossScreenSnapRestore()

template<typename IsSnappingMode >

bool PhosphorEngine::pendingCrossScreenSnapRestore	(	const WindowPlacement &	p,
		const QString &	openingScreenId,
		IsSnappingMode &&	isSnappingMode
	)

The snap-engine specialization of pendingCrossScreenManagedRestore — the original three-way gate (SnapEngine claims, AutotileEngine and ScrollEngine defer).

Kept as a named form because "snapped snap-slot on a snapping-mode home" is the verdict three call sites spell.

qHash()

size_t PhosphorEngine::qHash ( const PlacementStateKey &  key, size_t  seed = 0  )

inline

recordContextMatchesLive()

bool PhosphorEngine::recordContextMatchesLive ( const WindowPlacement &  p, int  liveDesktop, const QString &  liveActivity  )

inline

Whether a record's own (desktop, activity) context is compatible with the live context an engine would INSERT it into — the guard a cross-screen claim needs because the reclaim VERDICT is granted on the record's context while the adoption keys the window by the home screen's CURRENT context.

Without it, a window recorded on desktop 3 is reclaimed onto the strip or layout of whatever desktop that screen happens to show, displacing that desktop's windows while KWin still has the window on its own.

The sentinels are honoured rather than compared: virtualDesktop == 0 means all-desktops / sticky / unknown and an empty activity means all-activities / unknown (see WindowPlacement::virtualDesktop), so those records are compatible with any live context — the same desktop-agnostic reading LayoutRegistry::modeForScreen gives them, which is what granted the verdict in the first place. Only a CONCRETE recorded context that disagrees with a concrete live one refuses.

resolveLayerFocusSwitch()

PHOSPHORENGINE_EXPORT LayerSwitchResult PhosphorEngine::resolveLayerFocusSwitch	(	bool	floatingHasFocus,
		const LayerSwitchSide &	tiledSide,
		const LayerSwitchSide &	floatingSide
	)

Resolve niri's switch-focus-between-floating-and-tiling for any engine: pick the leg from floatingHasFocus, then the target on the far side — its candidate if eligible, else the first eligible fallback.

Encodes the verb contract once so all three engines refuse and report identically; what stays per-engine is HOW "floating has focus" is known and what bookkeeping the activation needs (see the scroll engine's echo asymmetry: the float-to-tiling activation is the engine's own doing and is echo-filtered, so that engine must clear its flag eagerly, while the tiling-to-float leg deliberately lets the genuine focus report arm the float-side memory).

RestoreSentinel()

constexpr QLatin1StringView PhosphorEngine::RestoreSentinel ( "__restore__"  )

inlineconstexpr