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... | |
| struct | WindowMetadata |
| 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. | |
| 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.
| 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.
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.
|
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.
|
strong |
|
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 | |
|
strong |
|
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 | |
|
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.
|
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.
|
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.
|
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.
| bool PhosphorEngine::pendingCrossScreenManagedRestore | ( | const WindowPlacement & | p, |
| QLatin1String | engineId, | ||
| QLatin1String | managedState, | ||
| const QString & | openingScreenId, | ||
| IsEngineMode && | 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.
| 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.
| bool PhosphorEngine::pendingCrossScreenSnapRestore | ( | const WindowPlacement & | p, |
| const QString & | openingWindowId, | ||
| const QString & | openingScreenId, | ||
| IsSnappingMode && | isSnappingMode ) |
The snap specialization of the reopen contract above.
|
inline |
|
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.
| 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).
|
inlineconstexpr |
|
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.