Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
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  GeometryUtils
namespace  GeometryDefaults
namespace  JsonKeys
namespace  PerScreenKeys

Classes

class  DesktopRemap
 How KWin's desktop positions moved in one change of its desktop list: for each 1-based position in the OLD list, the position the same desktop holds in the NEW list, or 0 when it was removed. 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
struct  SnapResult
struct  UnfloatResult
struct  ZoneAssignmentEntry
struct  DesktopSpan
 The contexts a window occupies, as the per-desktop membership pass reads them: which desktops (x11 numbering, the numbering the state keys use) and which activity. More...
struct  MembershipReconcileResult
 What a membership pass did, so the caller can drive the bookkeeping the engines cannot reach: the placement re-capture and the effect's per-window zone mirror for a snap release, and the adaptor-level untrack for a window that holds no context at all any more. More...
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, implemented by all three engines (snap zone layouts, autotile algorithms, the scrolling strip) so the daemon dispatches every lifecycle event and navigation intent through one polymorphic call with no mode branches. More...
class  IPlacementState
 Per-screen placement state contract. More...
class  IVirtualDesktopManager
struct  WindowDesktopContext
 The contexts the compositor last reported a window on, as far as the registry knows them, in KWin's current desktop numbering: a renumber moves the numbers of records not reported since (WindowRegistry::remapDesktops). More...
class  IWindowRegistry
class  IWindowTrackingService
struct  LayerSwitchSide
 One side (tiled or floating) of a layer focus switch, as the owning engine sees it. More...
struct  LayerSwitchResult
 Outcome of resolving a layer focus switch. More...
struct  NavigationContext
 Target window + screen for a navigation or lifecycle operation. More...
class  PerScreenStates
 Exported because this is a header-only template used from every engine library, so the category has to resolve outside phosphor-engine. More...
class  PlacementEngineBase
 Abstract base class for placement engines. More...
struct  ContextChange
 Outcome of a context mutation on ScreenContextTracker. More...
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  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...
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
class  IScrollSettings
 Settings surface the scrolling engine reads, injected by the daemon via PlacementEngineBase::setEngineSettings (qobject_cast at point of use, mirroring IAutotileSettings). More...
class  ISnapSettings
class  IAutotileSettings

Typedefs

using TilingStateKey = PlacementStateKey
 Backwards-compatible spelling for autotile's existing sources.
using StickyPredicate = std::function<bool(const QString&)>
 Answers whether a window is on all desktops.
using DesktopSpanQuery = std::function<DesktopSpan(const QString&)>
 Answers a window's DesktopSpan.

Enumerations

enum class  SnapIntent { UserInitiated , AutoRestored , AutoReplaced }
enum class  WindowKind : int { Unknown = 0 , Normal = 1 , Transient = 2 }
 Coarse structural classification of a window, carried on the open and close wire calls and on the placement record. More...
enum class  RestoreReason : int {
  Open = 0 , Unminimize = 1 , PendingSweep = 2 , DesktopArrival = 3 ,
  DaemonRestartSweep = 4 , DesktopReapply = 5
}
 Why a snap restore is being resolved. More...
enum class  StickyWindowHandling { TreatAsNormal = 0 , RestoreOnly = 1 , IgnoreAll = 2 }
enum class  StickyPinPhase { Acquire , Release }
 Which half of the sticky-screen pin pass to run. More...

Functions

size_t qHash (const PlacementStateKey &key, size_t seed=0)
WindowKind clampWindowKindFromWire (int wire)
 Clamp an integer wire value to a valid WindowKind.
RestoreReason clampRestoreReasonFromWire (int wire)
 Clamp an integer wire value to a valid RestoreReason.
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)
 The REOPEN CONTRACT, which the predicates below implement: a window is restored only on the KWin output it opens on.
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 claim 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 the 5-argument form.
template<typename IsEngineMode>
bool pendingCrossScreenManagedRestore (const WindowPlacement &p, QLatin1String engineId, QLatin1String managedState, const QString &openingWindowId, const QString &openingScreenId, IsEngineMode &&isEngineMode)
 The reopen contract over pendingCrossScreenManagedRestore.
template<typename IsSnappingMode>
bool pendingCrossScreenSnapRestore (const WindowPlacement &p, const QString &openingWindowId, const QString &openingScreenId, IsSnappingMode &&isSnappingMode)
 The snap specialization of the reopen contract above.
bool ownRecordLeftScreen (const WindowPlacement &own, const QString &openingScreenId)
 Whether a window's OWN record names a different screen than the one it is opening on while some engine still holds a live slot for it: the "left its screen" test of the reopen contract.

Variables

constexpr int MAX_PLAUSIBLE_VIRTUAL_DESKTOP = 1024
 Upper sanity bound for a virtual desktop number read back from disk.

Typedef Documentation

◆ DesktopSpanQuery

using PhosphorEngine::DesktopSpanQuery = std::function<DesktopSpan(const QString&)>

Answers a window's DesktopSpan.

The same query drives per-desktop membership for spans and for sticky windows without either being a special case.

◆ StickyPredicate

using PhosphorEngine::StickyPredicate = std::function<bool(const QString&)>

Answers whether a window is on all desktops.

The sticky-pin pass takes it from the caller rather than reading a tracker, so an engine needs no window-tracking dependency to maintain its pins.

◆ TilingStateKey

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

◆ RestoreReason

enum class PhosphorEngine::RestoreReason : int
strong

Why a snap restore is being resolved.

Replaces the isOpenPath bool the Snap.resolveWindowRestore wire used to carry.

The bool conflated FIVE drivers into "open / not open". The daemon gates on it: the open claim and the appId FIFO serve a genuine Open (the two sweeps get the FIFO only for a window no engine ever captured), and every other reason is a re-entry of the window's own record. What the bool could NOT express is the DesktopArrival re-drive: the continuation of an open whose window a RouteToDesktop rule sent to another desktop, so the effect parked it and re-drives once the desktop is shown. It is not a user action and not an open of its own, so it never borrows a sibling's record, but it does run the screen routing a parked open still owes.

A third gate reads it on the EFFECT side: the open-path setFrameGeometry shadow seed, which is what lets the daemon translate a bare RouteToScreen for a never-moved window. That one is == Open too, which is why the two deferred-routing flush call sites must stay Open — give them any other reason and RouteToScreen silently stops working for freshly flushed windows.

Enumerator
Open 

a window OPEN: session restore, deferred-routing flush

Unminimize 

unminimize of a window orphaned by a daemon restart

PendingSweep 

the pending-restores sweep, once the daemon is ready

DesktopArrival 

re-drive after the daemon moved the window to another desktop

DaemonRestartSweep 

the bring-up stacking-restore sweep

DesktopReapply 

re-apply the zone a window already holds in the context it arrived in; places nothing new

◆ SnapIntent

enum class PhosphorEngine::SnapIntent
strong
Enumerator
UserInitiated 
AutoRestored 

An automatic placement of a window that genuinely opened: may take focus under "Focus new windows".

AutoReplaced 

The same automatic placement for a window that did NOT just open (a restart or pending sweep, an unminimize, a desktop arrival).

Identical bookkeeping to AutoRestored, never takes focus. Appended for ABI.

◆ StickyPinPhase

enum class PhosphorEngine::StickyPinPhase
strong

Which half of the sticky-screen pin pass to run.

The halves resolve a screen's context key against OPPOSITE sides of a context change, so they cannot share a call site.

Acquire runs BEFORE the context moves: it decides whether to pin from the state under the key the screen resolves to now. Release runs AFTER: it migrates the pinned state onto the key the screen resolves to with the pin gone. Run Release early and that key still names the OUTGOING desktop, so the migration lands on the strip the user is leaving and force-releases every window it held. The pin is what keeps the split safe — while it is held the key resolves to the pinned desktop from either side.

Enumerator
Acquire 
Release 

◆ StickyWindowHandling

Enumerator
TreatAsNormal 
RestoreOnly 
IgnoreAll 

◆ WindowKind

enum class PhosphorEngine::WindowKind : int
strong

Coarse structural classification of a window, carried on the open and close wire calls and on the placement record.

Nothing branches on it any more: the pending-restore consume gate it fed was removed with that queue. Wire/JSON encoding is int; Unknown is the permissive default.

Enumerator
Unknown 
Normal 
Transient 

Function Documentation

◆ clampRestoreReasonFromWire()

RestoreReason PhosphorEngine::clampRestoreReasonFromWire ( int wire)
inline

Clamp an integer wire value to a valid RestoreReason.

Mirrors clampWindowKindFromWire: an out-of-range value collapses to Open.

Note that Open is the most PERMISSIVE value, not the safest one — it is the only reason that grants both gates. It is chosen anyway because it is the default the effect's own signature carries, so an unrecognised value behaves like a caller that named nothing, which is what every pre-existing call site meant. Treating a garbled value as a non-open driver would instead silently suppress a genuine restore, and a silently skipped restore is far harder to notice than one that ran.

◆ 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. 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

The REOPEN CONTRACT, which the predicates below implement: a window is restored only on the KWin output it opens on.

Each engine restores from the window's record only when the record's screen is the opening screen, or another virtual screen of the same output in that engine's mode, and never pulls a window onto another output. A window whose OWN record names another screen has left it: it is not restored there, and its engine slots are released (WindowPlacementStore::releaseEngineSlot) so they cannot read as a home later. A placement rule fires on that window only for a genuine open.

pendingCrossScreenManagedRestore, the 5-argument form, answers the bare question underneath: does this record carry engineId's slot in its MANAGED state (managedState, snap "snapped", autotile/scrolling "tiled") with a RECORDED screen other than the opening one, itself in that engine's mode in the RECORD'S OWN (desktop, activity) context? A same-screen record (or one with no screen) is never "cross-screen". It predates the contract and no longer gates anything on its own; the 6-argument form adds the contract's output and instance rules, and every caller uses that one. Callers must pass a MANAGED token: float restore is screen-local, so a FLOATING state never earns a 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, which is what login restore reads), and the record-level screenId is only as fresh as the last owning engine's capture. Claimants 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. (The function this whole block documents is pendingCrossScreenManagedRestore, declared below the two helpers that follow — it needs their definitions first.) 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.

◆ ownRecordLeftScreen()

bool PhosphorEngine::ownRecordLeftScreen ( const WindowPlacement & own,
const QString & openingScreenId )
inline

Whether a window's OWN record names a different screen than the one it is opening on while some engine still holds a live slot for it: the "left its screen" test of the reopen contract.

Exact (virtual-screen level) compare. Such a window is not restored, and every engine slot of the record is released rather than left to read as a home later. Released slots do not count: they are already a verdict.

◆ pendingCrossScreenManagedRestore() [1/2]

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

◆ pendingCrossScreenManagedRestore() [2/2]

template<typename IsEngineMode>
bool PhosphorEngine::pendingCrossScreenManagedRestore ( const WindowPlacement & p,
QLatin1String engineId,
QLatin1String managedState,
const QString & openingWindowId,
const QString & openingScreenId,
IsEngineMode && isEngineMode )

The reopen contract over pendingCrossScreenManagedRestore.

Restores happen only on the opening output: a record on ANOTHER KWin output is a leave, whoever it belongs to. The window's OWN record (same instance) is compared at the virtual-screen level, so its own record on another virtual screen, even of the same output, is a leave too. Only a FIFO record (another instance of the app) on another virtual screen of the SAME output, in the same mode, is pending. Callers reach this only when the opening screen is in engineId's mode, so "the recorded screen is in that mode" is the same-mode test.

◆ pendingCrossScreenSnapRestore() [1/2]

template<typename IsSnappingMode>
bool PhosphorEngine::pendingCrossScreenSnapRestore ( const WindowPlacement & p,
const QString & openingScreenId,
IsSnappingMode && isSnappingMode )

The snap-engine specialization of the 5-argument form.

Superseded by the 4-argument reopen-contract overload below and kept for source compatibility.

◆ pendingCrossScreenSnapRestore() [2/2]

template<typename IsSnappingMode>
bool PhosphorEngine::pendingCrossScreenSnapRestore ( const WindowPlacement & p,
const QString & openingWindowId,
const QString & openingScreenId,
IsSnappingMode && isSnappingMode )

The snap specialization of the reopen contract above.

◆ 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 claim 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 claimed 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()

QLatin1StringView PhosphorEngine::RestoreSentinel ( "__restore__" )
inlineconstexpr

Variable Documentation

◆ MAX_PLAUSIBLE_VIRTUAL_DESKTOP

int PhosphorEngine::MAX_PLAUSIBLE_VIRTUAL_DESKTOP = 1024
inlineconstexpr

Upper sanity bound for a virtual desktop number read back from disk.

Not a compositor limit — KWin's real desktop count is only knowable at runtime, and the effect re-checks the target against the live list before moving anything. This exists so a corrupt or foreign session.json cannot put an arbitrary integer into a placement record.