Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorScrollEngine::ScrollEngine Class Reference

niri-style scrolling placement engine. More...

#include <PhosphorScrollEngine/ScrollEngine.h>

Inheritance diagram for PhosphorScrollEngine::ScrollEngine:
[legend]

Public Types

enum class  FocusedColumnRefusal : quint8 { None , NotScrolling , NoColumn , FloatFocused }
 Why focusedColumnWindows answered empty, so the caller can tell the user which of the distinct situations it hit. More...
using VisibleTile = ScrollVisibleTile
 The zone-number unit.
using VisibleTileWithRect = ScrollVisibleTileWithRect
 A tile paired with its screen-normalized rect, from ONE strip walk.
using FloatPredicate = std::function<bool(const QString& windowId, const QString& screenId)>
 Predicate deciding whether an opening window should start FLOATING because a "Float this app" rule matched it.
using RestorePositionPredicate = std::function<bool(const QString& windowId)>
 Predicate gating the float-POSITION restore on the floating-reopen branch: the window is marked floating unconditionally, only the geometry move onto the recorded free spot is gated.
using OpenParamsResolver = std::function<ScrollOpenParams(const QString& windowId, const QString& screenId)>
 Resolver for the per-window open-behaviour rule overrides.
using ModeResolver = std::function<bool(const QString& screenId, int desktop, const QString& activity)>
 Context-mode resolver shape shared by the three injected closures below: invoked as (screenId, virtualDesktop, activity) → bool.
using ContextGapProvider
 Per-context (window-rule) gap overrides, resolved daemon-side so this library stays settings-agnostic.
Public Types inherited from PhosphorEngine::IPlacementEngine
enum class  LayoutSupport { None , Placement , Templates }
 How this engine relates to user-selectable layouts — the entries the layout picker, drag layout popup, quick-layout slots and layout cycle operate on. More...

Signals

void windowsTiled (const QString &tileRequestsJson)
 Batch of absolute pixel rects for the KWin effect, same JSON contract as AutotileEngine::windowsTiled.
void scrollingScreensChanged (const QStringList &screenIds, bool isDesktopSwitch)
 Scrolling twin of autotileScreensChanged, with the same identical-set re-emit contract on desktop/activity switches.
void stripContextChanged (const QString &screenId, const QString &epoch, const QString &debugLabel)
 The identity of the strip screenId is now showing has changed.
void enabledChanged (bool enabled)
void tabStripsChanged (const QString &screenId, const QString &stripsJson)
 Tab-indicator model for screenId, emitted when the resolved model changes (a relayout that produces an identical payload stays silent): a JSON array with one entry per tabbed column that actually resolves an indicator and is in view, or was in view before this batch's view slide (a DEPARTING column keeps its pills for the length of the outgoing leg) — {x, y, width, height (the INDICATOR's absolute px rect, not the column's), position (TabIndicatorPosition), activeIndex, tabs: [windowId, ...]}.
Signals inherited from PhosphorEngine::PlacementEngineBase
void geometryRestoreRequested (const QString &windowId, const QRect &geometry, const QString &screenId)
void sizeRestoreRequested (const QString &windowId, const QSize &size, const QString &screenId)
 Resize windowId to size where it stands, leaving the position to the compositor.
void navigationFeedback (bool success, const QString &action, const QString &reason, const QString &sourceId, const QString &targetId, const QString &screenId)
void windowFloatingChanged (const QString &windowId, bool floating, const QString &screenId)
void activateWindowRequested (const QString &windowId)
void windowDesktopMoveRequested (const QString &windowId, int desktop)
 Emitted when directional navigation moves a window across virtual desktops: the engine has already re-keyed its own tiling state, and the compositor must move the real window to desktop (1-based).
void windowOutputMoveExpected (const QString &windowId, const QString &targetScreenId)
 Emitted when daemon-initiated directional navigation moves a window across physical outputs: the engine has already migrated its own tiling state (removed from the source key, re-added on targetScreenId) and scheduled both reflows.
void crossModeMoveRequested (const QString &windowId, const QString &targetScreenId, int targetDesktop, const QString &direction)
 Emitted when a directional MOVE reaches a context boundary whose target is a DIFFERENT tiling mode than the source — the source engine cannot place the window itself (it has no state for the other mode), so it defers to the daemon.
void crossModeSwapRequested (const QString &windowId, const QString &targetScreenId, int targetDesktop, const QString &direction)
 Emitted when a directional SWAP reaches a context boundary whose target is a DIFFERENT tiling mode than the source — the two-way cross-mode exchange.
void crossModeFocusRequested (const QString &targetScreenId, const QString &direction, bool *handled)
 Emitted when a directional FOCUS reaches a monitor boundary whose neighbour context runs a DIFFERENT tiling mode — the source engine cannot name that surface's entry-edge window (it holds no state for the other mode), so it defers to the daemon, which asks the target engine for the window facing the source in direction and activates it.
void windowFloatingStateSynced (const QString &windowId, bool floating, const QString &screenId)
 Emitted to sync floating state without restoring geometry: engine-internal divergence correction, an engine-initiated float (rules, oversize, the compositor's own-fullscreen hold), and a release-time clear, which carries an EMPTY screenId.
void windowsBatchFloated (const QStringList &windowIds, const QString &screenId)
 Emitted when overflow windows are batch-floated during applyTiling.
void algorithmChanged (const QString &algorithmId)
 Emitted when the active tiling algorithm changes.
void placementChanged (const QString &screenId)
 Emitted when the placement layout changes for a screen.
void windowsReleased (const QStringList &windowIds, const QSet< QString > &releasedScreenIds)
 Emitted when windows are released from engine management.
void settingsPersistRequested ()
 Emitted when the engine writes tuning values back to the settings object and wants the daemon to persist them to disk.

Public Member Functions

 ScrollEngine (PhosphorEngine::IWindowTrackingService *windowTracker, PhosphorScreens::ScreenManager *screenManager, QObject *parent=nullptr)
 ~ScrollEngine () override
void setWindowRegistry (QObject *registry) override
 Attach a window-class registry (QObject carrying WindowRegistry).
bool isActiveOnScreen (const QString &screenId) const override
 Whether this engine is active on the given screen.
bool isEnabled () const noexcept override
QSet< QString > activeScreens () const override
void setActiveScreens (const QSet< QString > &screens) override
 Set which screens use scrolling.
void setActiveScreenHint (const QString &screenId) override
 NOTE: activeScreen() is deliberately NOT overridden.
void windowOpened (const QString &windowId, const QString &screenId, int minWidth, int minHeight) override
 A new window appeared on this engine's screen.
bool claimCrossScreenReopen (const QString &windowId, const QString &openingScreenId, int minWidth, int minHeight) override
 The reopen claim (see IPlacementEngine for the contract): only a FIFO record on another virtual screen of the opening output, in scrolling mode, for a window opening on a scrolling screen; never a record on another monitor and never the window's own.
QString heldScreenForWindow (const QString &windowId) const override
 OPTIONAL: the screen this engine genuinely HOLDS the window on IN THE SCREEN'S CURRENT CONTEXT — a MEMBERSHIP answer (tiled or engine-floating both count; a phantom reverse-map key does not), empty when the engine does not hold it or holds it only in a background context.
std::optional< PhosphorEngine::PlacementStateKey > heldKeyForWindow (const QString &windowId) const override
 The (screen, desktop, activity) key of the state that genuinely holds windowId, tiled or floating, in ANY context, or nullopt when none does.
QStringList parkOutput (const QString &physicalScreenId) override
 Copy every context of physicalScreenId (each of its virtual screens) into the park, before the prune drops them.
bool readoptParked (const QString &windowId, const QString &parkedPhysicalId, const QString &returnedPhysicalId) override
 Re-seat windowId's contexts parked under parkedPhysicalId on returnedPhysicalId as a re-statement (no focus, no last-used), each in its own (screen, desktop, activity): its virtual screen on the returned output (or the bare output), never the context in view.
void dropParked (const QString &windowId, const QString &physicalScreenId, int desktop, const QString &activity) override
 Forget windowId's parked contexts; an empty physicalScreenId, a desktop of 0 or an empty activity matches every one.
bool hasParked (const QString &windowId, const QString &physicalScreenId) const override
 Whether windowId has a context parked under physicalScreenId (any output when it is empty).
void forceReemit (const QString &screenId)
 Retile screenId with its next layout forced to emit: the daemon re-asserting a strip KWin moved.
void beginArrivalBurst () override
 Bracket a BURST of windowOpened calls delivered together (the adaptor's three dispatch loops: windowsOpenedBatch, the deferred-open flush, and the parked-open replay — daemon bring-up re-announce and mode flips; a reopen claim's re-entry inherits the loop's bracket, while the snap facade's is deliberately UNBRACKETED since each resolveWindowRestore is its own D-Bus message).
void endArrivalBurst () override
void noteCrossScreenClaimsExhausted (const QString &windowId, bool exhausted) override
 INERT, kept for ABI: fed the removed cross-screen defer gates.
void windowClosed (const QString &windowId) override
 A window was closed.
void windowFocused (const QString &windowId, const QString &screenId) override
 A window gained focus (called when the compositor reports activation).
void windowMinSizeUpdated (const QString &windowId, int minWidth, int minHeight) override
 Update a window's minimum size after the initial windowOpened.
QSize windowMinimumSize (const QString &windowId) const override
 The window's declared minimum as a FRAME size (Tile::minWidth), from its strip tile, falling back to the FloatRestore entry while it is floated (or minimized — the effect reports minimize as a float).
void onWindowResized (const QString &rawWindowId, const QRect &oldFrame, const QRect &newFrame, const QString &screenId) override
 Notify the engine that a tracked window finished an interactive resize.
void toggleWindowFloat (const QString &windowId, const QString &screenId) override
 Toggle between managed and floating.
void setWindowFloat (const QString &windowId, bool shouldFloat, const QString &screenId=QString()) override
 Announces Passive (windowFloatingStateSynced, F557); the user float verbs announce Active (F578).
bool isWindowFloatingInScroll (const QString &windowId) const
 Authoritative scroll float state (the scroll half of the per-engine float contract the WTS resolver reads).
QStringList allFloatingWindows () const
bool isModeSpecificFloated (const QString &windowId) const override
void markModeSpecificFloated (const QString &windowId) override
void clearModeSpecificFloatMarker (const QString &windowId) override
void focusInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
 Move keyboard focus to the adjacent window.
void moveFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
 Move the focused window to the adjacent slot.
void swapFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
 Swap the focused window with the adjacent window.
void moveFocusedToPosition (int position, const PhosphorEngine::NavigationContext &ctx) override
 Move the focused window to the Nth position.
void spanFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
 Zone spanning has no strip analogue; reports a "not_supported" span OSD like AutotileEngine so the shortcut is not a silent press.
void rotateWindows (bool clockwise, const PhosphorEngine::NavigationContext &ctx) override
 Rotate all managed windows on the screen.
void reapplyLayout (const PhosphorEngine::NavigationContext &ctx) override
 Re-apply the current layout to all managed windows.
void snapAllWindows (const PhosphorEngine::NavigationContext &ctx) override
 Bring every unmanaged window on the screen back under this engine's placement (zones for snap, the strip for scrolling).
void cycleFocus (bool forward, const PhosphorEngine::NavigationContext &ctx) override
 Cycle keyboard focus through managed windows.
void pushToEmptyZone (const PhosphorEngine::NavigationContext &ctx) override
 Move the focused window to the first empty slot.
void restoreFocusedWindow (const PhosphorEngine::NavigationContext &ctx) override
 Restore the focused window out of its managed state.
void toggleFocusedFloat (const PhosphorEngine::NavigationContext &ctx) override
 Toggle the focused window between managed and floating.
void switchFocusBetweenFloatingAndTiling (const QString &screenId) override
 niri switch-focus-between-floating-and-tiling (IPlacementEngine override).
void focusColumnFirst (const QString &screenId)
void focusColumnLast (const QString &screenId)
void moveColumnToFirst (const QString &screenId)
void moveColumnToLast (const QString &screenId)
void consumeWindowIntoColumn (const QString &screenId)
void expelWindowFromColumn (const QString &screenId)
void consumeOrExpelWindow (int delta, const QString &screenId)
 delta -1 = towards the strip's start, +1 = towards its end (niri consume-or-expel-window-left/right).
void centerColumn (const QString &screenId)
void toggleColumnTabbed (const QString &screenId)
void toggleWindowedFullscreen (const QString &screenId)
 Windowed fullscreen (niri toggle-windowed-fullscreen) on the active window: layout-neutral per-tile flag, see Tile::windowedFullscreen.
bool setWindowFullscreenFloat (const QString &windowId, bool floating, const QString &screenId)
 Compositor-driven: hold a strip tile out for its OWN fullscreen or return it, with a user float's slot memory but a PASSIVE announcement (no OSD, no free-geometry restore).
bool isFullscreenFloated (const QString &windowId) const
 True while the slot carries the compositor's hold, and for a window that CLOSED mid-hold until WindowTracking.windowClosed has taken its capture (forgetClosedFullscreenHold).
void forgetClosedFullscreenHold (const QString &windowId)
 Drop the closed-mid-hold memory once the daemon's close capture has read it, or a live release left no capture to read it.
void clearWindowedFullscreen (const QString &windowId)
 Compositor-driven reconciliation: the client left fullscreen on its own.
void reapplyWindowGeometry (const QString &windowId)
 Compositor-driven repair: the compositor moved this window behind the engine's back (KWin's fullscreen-exit restore), so evict its emit-gate memory and relayout its screen to re-emit the true rect.
void reportCommittedSize (const QString &windowId, const QSize &offered, const QSize &committed)
 Compositor-driven: the size a client settled on when offered its tile rect, reported when it is not the offer (engine_committed.cpp).
void cycleColumnPresetWidth (int delta, const QString &screenId)
 delta -1/+1 through the preset width list.
void adjustColumnWidth (qreal deltaPercent, const QString &screenId)
 deltaPercent of the work area's MAIN extent (e.g. +10 / -10).
bool toggleMaximizeColumn (const QString &screenId, const QString &windowId=QString())
 Toggle the maximized state of a column on screenId.
bool toggleMaximizeToEdges (const QString &screenId, const QString &windowId=QString())
 Toggle a column's maximize-to-edges state (full raw work area on both axes, gap-free; niri maximize-window-to-edges generalized to the column).
void expandColumnToAvailableWidth (const QString &screenId)
void equalizeVisibleColumnWidths (const QString &screenId)
 Equal shares of the viewport for every column intersecting it, clipped ones included (Karousel equalize; ScrollStrip carries the contract).
void minimizeColumnWidth (const QString &screenId)
 The focused column at the smallest preset (Karousel minimize-width).
void resetStripToDefaults (const QString &screenId)
 Every column on the screen back to the context's default width and display, every window back to the even split: the scrolling half of the mode-neutral Retile shortcut.
void cycleWindowPresetHeight (int delta, const QString &screenId)
void adjustWindowHeight (qreal deltaPercent, const QString &screenId)
void maximizeWindowHeight (const QString &screenId)
 Toggle the focused window between filling its column and the even split (the height twin of toggleMaximizeColumn).
void minimizeWindowHeight (const QString &screenId)
 The focused window at the shortest preset height (the height twin of minimizeColumnWidth).
void expandWindowToAvailableHeight (const QString &screenId)
 Grow the focused window into the empty space left in its column (the height twin of expandColumnToAvailableWidth).
void equalizeWindowHeights (const QString &screenId)
 An equal share of the focused column for each of its windows (the height twin of equalizeVisibleColumnWidths).
void centerVisibleColumns (const QString &screenId)
 Center the span of fully visible columns (niri center-visible-columns).
void scrollViewByPercent (qreal percent, const QString &screenId)
 Scroll the view along the strip by percent of the work area's MAIN extent WITHOUT changing focus (Karousel scroll-left/right and its page variants; niri has no equivalent).
void scrollViewByPx (int px, const QString &screenId)
 The pixel twin of scrollViewByPercent, for a caller that already holds a distance along the strip (the placement map's drag pan, over org.phosphor_works.Placement.Scrolling.scrollViewByPx).
void focusColumnAtIndex (int index, const QString &screenId)
 Focus the column at strip index index (ScrollStrip::focusColumn), re-anchoring the view under the same centering policy every other focus verb applies, then activating the column's active window.
void moveColumnToIndex (int from, int to, const QString &screenId)
 Move the column at strip index from to strip index to (ScrollStrip::moveColumnTo), leaving the moved column active and re-anchoring the view the way the other move verbs do, then activating its active window.
void focusWindowTop (const QString &screenId)
 First/last non-minimized tile of the active column (niri focus-window-top/bottom).
void focusWindowBottom (const QString &screenId)
void focusColumnPlain (int delta, const QString &screenId)
 Plain adjacent-column focus that stops at the strip edge (niri focus-column-left/right).
void focusColumnWrap (int delta, const QString &screenId)
 Adjacent-column focus that wraps to the far end at the strip edge (niri focus-column-left-or-last / right-or-first).
void cycleTab (int delta, const QString &screenId)
 Cycle the active column's tabs, wrapping at either end.
void focusTab (int ordinal, const QString &screenId)
 Focus the active column's ordinal'th tab, 1-based, counting the column's non-minimized tiles — which are the tabs its indicator draws when the column is tabbed.
void moveFocusedToFloating (const QString &screenId)
 Explicit float / re-tile of the focused window (niri move-window-to-floating / move-window-to-tiling); already-there presses answer with no_target feedback.
void moveFocusedToTiling (const QString &screenId)
void setColumnWidth (const ColumnWidth &width, const QString &screenId)
 Absolute width/height intents (niri set-column-width/set-window-height with an absolute value).
void setWindowHeight (const WindowHeight &height, const QString &screenId)
StripAxis stripAxisForScreen (const QString &screenId) const
 Which way screenId's strip runs, resolved live.
void focusColumnByDelta (int delta, const QString &screenId)
 Focus the previous/next column ALONG THE STRIP, for callers holding a strip-relative intent rather than a physical direction.
PhosphorEngine::IPlacementState * stateForScreen (const QString &screenId) override
 Per-screen state object for the given screen.
const PhosphorEngine::IPlacementState * stateForScreen (const QString &screenId) const override
QStringList focusedColumnWindows (const QString &screenId, FocusedColumnRefusal *reason=nullptr) const
 The focused column of screenId's current strip, in tile order, for a verb that relocates the column as a whole (the dynamic-workspaces move-column-to-workspace verb).
bool stashColumnForDesktopMove (const QString &screenId, const QStringList &windowIds, int targetDesktop)
 The column-preserving half of the move-column-to-workspace verb.
bool stashStripForOutputMove (const QString &sourceStripScreenId, const QString &targetStripScreenId, int desktop, const QStringList &windowIds)
 The column-preserving half of the move-workspace-to-monitor verb.
TabIndicatorParams tabIndicatorParamsForScreen (const QString &screenId) const
 The tab-indicator geometry screenId resolves to: the configured values with any per-screen rule override layered on per property.
bool isWindowTracked (const QString &windowId) const override
bool isWindowTiled (const QString &windowId) const override
 Whether the window is actively tiled (engine-owned, non-floating).
bool isWindowManaged (const QString &windowId) const override
 Whether the engine considers the window "managed" (eligible for layout operations).
QString screenForTrackedWindow (const QString &windowId) const override
 Return the screen this engine considers the window to be on (any context), or empty if the window isn't tracked by this engine.
QRect lastManagedRect (const QString &rawWindowId) const override
 The exact rect this engine last APPLIED to windowId while managing it (its tile rect), remembered PAST the window's transition out of the managed state.
QStringList managedWindowOrder (const QString &screenId) const override
QVector< VisibleTile > visibleTiles (const QString &screenId) const
 The visible tiles of screenId's current-context strip in zone- number order.
QVector< QRect > visibleTileRects (const QString &screenId) const
 The rects of visibleTiles — the plain absolute-pixel projection, in the same order.
int visibleTileNumberForWindow (const QString &screenId, const QString &windowId) const
 windowId's zone number on screenId's current strip, or -1 when it is off-screen, a hidden tab, or untracked.
QVector< QRectF > visibleTileRectsRelative (const QString &screenId) const
 visibleTileRects normalized to the FULL screen geometry (0.0–1.0 per axis) — the shape zone previews consume.
ScrollStripSnapshot stripSnapshot (const QString &screenId, const QString &excludeWindowId=QString()) const
 Column-aware strip snapshot for the daemon's strip-mode drag popup.
QVector< VisibleTileWithRect > visibleTilesWithRects (const QString &screenId) const
 visibleTiles and visibleTileRectsRelative in a single resolve.
ScrollStripModel stripModelForScreen (const QString &screenId) const
 The whole strip of screenId's current context as a strip MAP reads it (ScrollStripModel): every column, on and off screen, with its strip position and extent, the viewport's offset and extent on the same axis, and the active column.
void setInitialWindowOrder (const QString &screenId, const QStringList &windowIds) override
QString managedFocusedWindow (const QString &screenId) const override
 The window this engine considers focused on screenId, or empty.
int stickyPinnedDesktopForScreen (const QString &screenId) const override
 The desktop this engine has pinned this screen to, or 0.
void setInitialFocusedWindow (const QString &screenId, const QString &windowId) override
 Hand the incoming engine the focus captured from the outgoing one.
int pruneStaleWindows (const QSet< QString > &aliveWindowIds) override
 Drop any per-engine bookkeeping for windows not in aliveWindowIds.
LayoutSupport layoutSupport () const override
 The strip consumes layouts as sizing TEMPLATES, never as window placement: the screen's assigned ScrollingTemplate is the sizing vocabulary.
bool providesDragInsertSelector () const override
 The strip renders in the daemon's drag popup as column cards speaking the drag-insert vocabulary (new column in a gap, join on a card, tab dock on a tabbed card).
QList< qreal > effectivePresetColumnWidths (const QString &screenId) const
 Effective preset vocabulary for a screen: the per-screen TEMPLATE override when the daemon pushed a usable one (every entry validated against the same floor as the settings parser), else the cached settings list.
QList< qreal > effectivePresetWindowHeights (const QString &screenId) const
ScrollBlueprintProgress blueprintProgressForScreen (const QString &screenId) const
 How far this screen's CURRENT context has worked through its template blueprint.
QString engineId () const override
 Stable engine identity for HandoffContext.fromEngineId.
void handoffReceive (const HandoffContext &ctx) override
 Receive ownership of a window from another engine.
void handoffRelease (const QString &windowId) override
 Release ownership of a window WITHOUT modifying its geometry.
QString entryWindowForCrossing (const QString &screenId, const QString &direction) const
 Cross-mode swap support (queried by the daemon when THIS engine is the swap target): the strip window at the entry edge facing the source for a crossing arriving in direction — a "right" crossing enters the viewport's left edge.
int columnIndexForWindow (const QString &screenId, const QString &windowId) const
 The column index windowId's column holds on screenId (current context), or -1 — the landing-slot reference a swap counterpart uses via HandoffContext.insertIndex.
QStringList windowsBeyondFocusScrollLimit (const QString &screenId, int maxScrollPercent) const
 The windows on screenId that focus-follows-mouse must REFUSE to focus under a cap of maxScrollPercent percent of the viewport's extent along the strip — niri's focus-follows-mouse max-scroll-amount.
bool hasDragInsertPreview () const override
QString dragInsertPreviewScreenId () const override
QString dragInsertPreviewPriorScreenId () const override
 See the base declaration.
QString dragInsertPreviewWindowId () const
 The window id of the active drag-insert preview, or empty (test seam, mirroring AutotileEngine's accessor).
bool beginDragInsertPreview (const QString &rawWindowId, const QString &screenId) override
void commitDragInsertPreview () override
void setDragInsertClientSize (const QSize &size) override
 Stores size on the live preview for commit's "the client decides" sizing of a window dragged in off a float.
void cancelDragInsertPreview (bool dragStillActive=false) override
 dragStillActive carries the base-interface contract and is deliberately unused here (see the definition): the DETACH-ONCE model plus the interactive-drag mark already keep the dragged window's rect from being emitted mid-drag.
DragInsertTarget computeDragInsertTargetAtPoint (const QString &screenId, const QPoint &cursorPos) const override
 primary = column index; newSlot true opens a NEW column at primary; otherwise the window joins column primary as tile secondary (a MODEL-column tile index — minimized tiles count).
void updateDragInsertPreview (const DragInsertTarget &target) override
 Update the drop target for an active drag-insert preview.
bool dragAutoScrollTick (const QString &screenId, const QPoint &cursorPos, qreal dtSeconds) override
 Edge auto-scroll (drag_autoscroll.cpp).
bool dragAutoScrollActive () const override
 Whether edge auto-scroll currently owns the drop target.
void cancelDragAutoScroll () override
 The ONE disarm: hands the drop target back to the ordinary hit-test and restarts the start delay.
QRect dragInsertIndicatorRect (const QString &screenId) const override
 The rect the dragged window would occupy if it were dropped at the currently remembered target — the drop indicator the daemon paints.
void setInteractiveDragWindow (const QString &windowId) override
 While set, applyLayout never emits this window's rect, onWindowResized never reconciles its acks, reportCommittedSize learns nothing from its commits, and a grouped open never joins its column as a tab: during a drag the effect floats the window VISUALLY ONLY.
void setCrossSurfaceResolver (PhosphorEngine::ICrossSurfaceResolver *resolver) override
 Inject the cross-surface resolver used to find a neighbouring output / desktop when directional navigation reaches a surface boundary.
void setCurrentDesktop (int desktop) override
void setCurrentDesktopForScreen (const QString &screenId, int desktop) override
 Set a single screen's current virtual desktop (Plasma 6.7 "switch desktops independently for each screen").
void clearCurrentDesktopForScreen (const QString &screenId) override
 Drop a screen's per-output desktop, reverting it to the global current.
void setCurrentActivity (const QString &activity) override
void updateStickyScreenPins (const PhosphorEngine::StickyPredicate &, PhosphorEngine::StickyPinPhase) override
 Pin screens whose managed windows are ALL sticky to their current desktop, unpinning (and migrating the state to the new desktop key) once a non-sticky window appears — the "virtualdesktopsonlyonprimary" contract AutotileEngine also implements: without the pin a desktop switch resolves a fresh key and the strip comes up empty while the sticky windows are still visible.
PhosphorEngine::MembershipReconcileResult reconcileDesktopMemberships (const QString &screenId, const PhosphorEngine::DesktopSpanQuery &spanOf) override
 Give a window present on several desktops a column in each of their strips, so it can be placed and sized independently per desktop rather than existing only in the context it opened in.
PhosphorEngine::MembershipReconcileResult reconcileWindowMemberships (const QString &windowId, const PhosphorEngine::DesktopSpanQuery &spanOf) override
 The same pass for ONE window, on the screen it is held on.
QSet< int > desktopsWithActiveState () const override
void pruneStatesForDesktop (int removedDesktop) override
void renumberDesktopsAfterRemoval (int removedDesktop) override
 Shift every per-(screen, desktop, activity) state ABOVE removedDesktop down by one, because Plasma renumbers x11 desktop numbers when a desktop in the middle is deleted (removing 2 of 4 makes 3 become 2 and 4 become 3).
void remapDesktops (const PhosphorEngine::DesktopRemap &remap) override
 OPTIONAL: KWin's desktop list changed (a removal, an insert or a reorder).
void pruneStatesForActivities (const QStringList &validActivities) override
void pruneStatesForRemovedScreen (const QString &physicalScreenId) override
 Prune per-(screen, desktop, activity) state for a PHYSICALLY REMOVED output (monitor hot-unplug), matching every virtual sub-screen of the removed physical id.
void releaseWindowOffScreen (const QString &windowId, const QString &keepScreenId) override
 The base release, plus the stashed columns the window holds on any other screen (engine_stashleave.cpp).
void saveState () override
void loadState () override
void setPersistenceDelegate (std::function< void()> saveFn, std::function< void()> loadFn)
QJsonObject serializeStripState () const
 Durable strip-structure snapshot: every LIVE strip (current states) plus the un-consumed mode-round-trip stash entries, keyed "screenId|desktop|activity".
void restoreStripState (const QJsonObject &state)
 Load a serializeStripState blob into the stash so the EXISTING arrival-restore path (restoreFromStripStash) rebuilds each strip as its windows are announced.
void remapRestoredStripStash (const PhosphorEngine::DesktopRemap &remap)
 The start-up renumber when KWin's first desktop list lands after windows did (F1045): only the entries restoreStripState staged that no live window has touched since move through remap, onto a key it would have staged them on.
void setFuzzyClaimGraceMsForTesting (qint64 graceMs)
 TEST SEAM: shorten (or lengthen) the cross-session fuzzy-claim grace window — the period after a stash is staged, or its screen re-enters scrolling, during which an appId-only claim may take a dead sibling's slot.
std::optional< PhosphorEngine::WindowPlacement > capturePlacement (const QString &windowId) const override
 Report windowId's CURRENT placement for persistence, or nullopt if this engine does not manage it.
void refreshConfigFromSettings () override
 Re-read all tuning values from the engine's settings interface.
void retile (const QString &screenId=QString()) override
void scheduleRetileForScreen (const QString &screenId) override
void setFloatPredicate (FloatPredicate predicate)
void setRestorePositionPredicate (RestorePositionPredicate predicate)
void setOpenParamsResolver (OpenParamsResolver resolver)
void setSnappingModeResolver (ModeResolver resolver)
 INERT, kept for ABI: a snapping-mode resolver that fed windowOpened's cross-screen restore defer gate, which the reopen contract removed (a window opening on a scrolling screen is scroll's).
void setScrollingModeResolver (ModeResolver resolver)
 Scrolling-mode resolver: whether a context runs Scrolling as the daemon resolves it (feature switch and disabled cascade included, F1137).
void setAutotileModeResolver (ModeResolver resolver)
 INERT, kept for ABI: an autotile-mode resolver that fed the same removed defer gate.
void setScreenGeometryProviders (std::function< QRect(const QString &)> availableGeometry, std::function< QRect(const QString &)> screenGeometry)
 Embedder/test seam: inject screen geometry when NO ScreenManager is wired (headless hosts).
void setAllScreenGeometriesProvider (std::function< QList< QRect >()> allScreenGeometries)
 The union half of the provider seam: every output's full rect, used only for the parking union's bottom edge.
void setContextGapProvider (ContextGapProvider provider)
void applyPerScreenConfig (const QString &screenId, const QVariantMap &overrides) override
void clearPerScreenConfig (const QString &screenId) override
QVariantMap perScreenOverrides (const QString &screenId) const override
Public Member Functions inherited from PhosphorEngine::PlacementEngineBase
void setEngineSettings (QObject *settings)
QObject * engineSettings () const
 ~PlacementEngineBase () override
void setOpenFocusEligible (bool eligible) override
 OPTIONAL: whether the opens dispatched next may take focus ("Focus new windows"): true for a genuine open, false for a re-placement.
Public Member Functions inherited from PhosphorEngine::IPlacementEngine
virtual ~IPlacementEngine ()=default
 IPlacementEngine (const IPlacementEngine &)=delete
IPlacementEngine & operator= (const IPlacementEngine &)=delete
void windowOpened (const QString &windowId, const QString &screenId)
 Convenience overload — equivalent to windowOpened(id, screen, 0, 0).
virtual void reapplyManagedWindowAppearance ()
 Re-drive the compositor's per-window appearance (border, hidden title bar) for every window this engine currently manages, WITHOUT recomputing the layout — windows keep their current zones/positions.
virtual bool restorePlacement (const WindowPlacement &placement, const QString &screenId)
 Apply placement to a (re)opening window on screenId.
virtual QString algorithmId () const
virtual void setAlgorithm (const QString &algorithmId)
virtual QString activeScreen () const
virtual qreal effectiveSplitRatioStep (const QString &screenId) const
virtual int runtimeMaxWindows () const
 Runtime max-windows limit.
virtual std::optional< int > savedMaxWindowsForAlgorithm (const QString &algorithmId) const
 The user's saved per-algorithm max-windows tuning for algorithmId, or std::nullopt when the engine keeps no such slot.
virtual void increaseMasterRatio (qreal delta=kDefaultSplitRatioStep)
virtual void decreaseMasterRatio (qreal delta=kDefaultSplitRatioStep)
virtual void increaseMasterCount ()
virtual void decreaseMasterCount ()
virtual void focusMaster ()
virtual void swapFocusedWithMaster ()

Additional Inherited Members

Static Public Attributes inherited from PhosphorEngine::IPlacementEngine
static constexpr qreal kDefaultSplitRatioStep = 0.05
 One home for the master/split ratio step so the default return below and the two default arguments cannot drift apart.
Protected Member Functions inherited from PhosphorEngine::PlacementEngineBase
 PlacementEngineBase (QObject *parent=nullptr)
bool openFocusEligible () const
 Whether the open being handled may take focus (see IPlacementEngine::setOpenFocusEligible).
void announceLayerSwitch (const LayerSwitchResult &result, const QString &action, const QString &screenId)
 Emit the activation + navigationFeedback pair for a resolved layer focus switch (resolveLayerFocusSwitch).
void restoreFreeSizeWhereItStands (IWindowTrackingService *tracker, const QString &windowId, const QString &screenId, RestoreReason reason, bool placedBefore, const QList< QSize > &managedSizes)
 The size-only half of a float verdict, shared by every engine (#1106).
Protected Member Functions inherited from PhosphorEngine::IPlacementEngine
 IPlacementEngine ()=default
Static Protected Member Functions inherited from PhosphorEngine::PlacementEngineBase
static bool isManagedSize (const QList< QSize > &managedSizes, const QSize &size)
 Whether size is within two pixels of any entry of managedSizes on both axes.
static bool placedByPreviousLineage (const WindowPlacementStore &store, const QString &windowId)
 The placedBefore snapshot for restoreFreeSizeWhereItStands: store holds a record WITH AN ENGINE SLOT under this exact uuid, so a previous daemon lineage placed the window (a daemon-only restart or mode-swap re-announce).

Detailed Description

niri-style scrolling placement engine.

Implements IPlacementEngine for screens assigned to Scrolling mode. Each (screen, virtual desktop, activity) context owns one ScrollState wrapping a ScrollStrip — an ordered list of columns on an unbounded strip, running whichever way that screen's axis resolves, viewed through the screen's work area. The defining invariant: OPENING A WINDOW INSERTS A NEW COLUMN AND RESIZES NOTHING; only the viewport scrolls.

Geometry leaves the engine as the same windowsTiled JSON contract the autotile engine emits, relayed by the shared tiling adaptor to the KWin effect's tile-request path (staggered apply, supersession epochs, maximize reset). Columns scrolled out of the viewport are parked with real geometry just below the union of all outputs — the one place no monitor topology can occupy, and never at extreme coordinates — so input hit-testing stays sane; the enter/leave animation origin comes from the tile request's scrollEdge field, not from where the park happens to sit. A column STRADDLING a screen edge is committed CLAMPED at that edge (both MAIN edges, plus the cross-axis overflow edge; a cross-axis UNDERFLOW cannot occur, since a column starts at the work area's cross origin by construction) unless the crop-straddlers setting keeps the true rect for the effect to crop; a remainder below the peek floor parks instead. Hidden tiles of a tabbed column park the same way (a hidden tab must not sit under the active tile stealing clicks).

Floating reuses the shared PlasmaZones float model: a floated window leaves the strip (its column closes up) and the engine remembers the column index so unfloat / unminimize restores the slot. The effect's minimize machinery reports minimize as a float toggle, so slot memory covers minimize for free. The compositor's own-fullscreen hold (setWindowFullscreenFloat) is a third producer, announced passively.

See also
PhosphorEngine::IPlacementEngine, ScrollStrip, ScrollState

Member Typedef Documentation

◆ ContextGapProvider

Initial value:
std::function<QVariantMap(const QString& screenId, int desktop, const QString& activity)>

Per-context (window-rule) gap overrides, resolved daemon-side so this library stays settings-agnostic.

Returns a PerScreenKeys-shaped map (InnerGap / OuterGap* / UsePerSideOuterGap); values present in the map win over the IScrollSettings gaps. Same lifetime contract as the other injected closures.

Takes the CONTEXT explicitly rather than resolving it daemon-side from the screen's current desktop. A mutation on a BACKGROUND state — a close on a desktop that is not in view, say — has to resolve gaps for the desktop the state belongs to, and a screen-only provider would hand it the desktop in view's rules instead. A desktop of 0 with an empty activity means "whatever the screen is showing now", which is what every current-context caller passes.

◆ FloatPredicate

using PhosphorScrollEngine::ScrollEngine::FloatPredicate = std::function<bool(const QString& windowId, const QString& screenId)>

Predicate deciding whether an opening window should start FLOATING because a "Float this app" rule matched it.

Daemon-injected, keyed by the live windowId. Clear with {} before destroying captured state.

Takes the OPENING SCREEN as well, for the same reason OpenParamsResolver does: the resolver needs it to stamp ScreenId and to derive Mode, without which a rule pairing either with Float is silently inert even though the rules editor offers that pairing.

◆ ModeResolver

using PhosphorScrollEngine::ScrollEngine::ModeResolver = std::function<bool(const QString& screenId, int desktop, const QString& activity)>

Context-mode resolver shape shared by the three injected closures below: invoked as (screenId, virtualDesktop, activity) → bool.

The daemon bakes the mode lookup (and, where relevant, engine liveness and global toggles) into each closure so this library stays free of the zones-layer mode type. Same clear-before-destroy contract as the other injected closures.

◆ OpenParamsResolver

using PhosphorScrollEngine::ScrollEngine::OpenParamsResolver = std::function<ScrollOpenParams(const QString& windowId, const QString& screenId)>

Resolver for the per-window open-behaviour rule overrides.

Same injection contract as the float predicate. Takes the OPENING screen as well as the window: the open-behaviour rules a user authors are commonly pinned to a screen or to Scrolling mode, and the daemon-side window metadata carries neither, so this path is the one that can supply them.

◆ RestorePositionPredicate

using PhosphorScrollEngine::ScrollEngine::RestorePositionPredicate = std::function<bool(const QString& windowId)>

Predicate gating the float-POSITION restore on the floating-reopen branch: the window is marked floating unconditionally, only the geometry move onto the recorded free spot is gated.

Mirrors AutotileEngine::RestorePositionPredicate (daemon-wired scrollingRestoreFloatedWindowsOnLogin setting + the per-window RestorePosition rule); unset (tests / no daemon) means the move always fires, preserving historical behaviour.

◆ VisibleTile

The zone-number unit.

Declared in ScrollEngineTypes.h and aliased here, so ScrollEngine::VisibleTile keeps naming it for every consumer — the daemon's strip zones alias it by that spelling. Its full contract, including why a digit's ACTION is coarser than the address it resolves, lives on ScrollVisibleTile.

◆ VisibleTileWithRect

A tile paired with its screen-normalized rect, from ONE strip walk.

Aliased out of ScrollEngineTypes.h like VisibleTile above.

Member Enumeration Documentation

◆ FocusedColumnRefusal

Why focusedColumnWindows answered empty, so the caller can tell the user which of the distinct situations it hit.

Enumerator
None 

Not refused: the answer names the column.

NotScrolling 

screenId is not a screen this engine scrolls (exact id, see below).

NoColumn 

The screen scrolls but its current strip has no active column.

FloatFocused 

A floating window holds focus, so no column is the one in front of the user.

Constructor & Destructor Documentation

◆ ScrollEngine()

PhosphorScrollEngine::ScrollEngine::ScrollEngine ( PhosphorEngine::IWindowTrackingService * windowTracker,
PhosphorScreens::ScreenManager * screenManager,
QObject * parent = nullptr )
explicit

◆ ~ScrollEngine()

PhosphorScrollEngine::ScrollEngine::~ScrollEngine ( )
override

Member Function Documentation

◆ activeScreens()

QSet< QString > PhosphorScrollEngine::ScrollEngine::activeScreens ( ) const
inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ adjustColumnWidth()

void PhosphorScrollEngine::ScrollEngine::adjustColumnWidth ( qreal deltaPercent,
const QString & screenId )

deltaPercent of the work area's MAIN extent (e.g. +10 / -10).

◆ adjustWindowHeight()

void PhosphorScrollEngine::ScrollEngine::adjustWindowHeight ( qreal deltaPercent,
const QString & screenId )

◆ allFloatingWindows()

QStringList PhosphorScrollEngine::ScrollEngine::allFloatingWindows ( ) const

◆ applyPerScreenConfig()

void PhosphorScrollEngine::ScrollEngine::applyPerScreenConfig ( const QString & screenId,
const QVariantMap & overrides )
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ beginArrivalBurst()

void PhosphorScrollEngine::ScrollEngine::beginArrivalBurst ( )
overridevirtual

Bracket a BURST of windowOpened calls delivered together (the adaptor's three dispatch loops: windowsOpenedBatch, the deferred-open flush, and the parked-open replay — daemon bring-up re-announce and mode flips; a reopen claim's re-entry inherits the loop's bracket, while the snap facade's is deliberately UNBRACKETED since each resolveWindowRestore is its own D-Bus message).

An engine that applies geometry per arrival may defer those applies until endArrivalBurst so a restore of an unchanged session resolves one final layout instead of N visible intermediates. Defaults are no-ops (autotile's retile already coalesces). Brackets may nest, only the outermost end flushes, and model state is fully updated during the burst; only the apply defers.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ beginDragInsertPreview()

bool PhosphorScrollEngine::ScrollEngine::beginDragInsertPreview ( const QString & rawWindowId,
const QString & screenId )
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ blueprintProgressForScreen()

ScrollBlueprintProgress PhosphorScrollEngine::ScrollEngine::blueprintProgressForScreen ( const QString & screenId) const

How far this screen's CURRENT context has worked through its template blueprint.

Public for the same reason as the preset readers above: it is a read-only introspection surface, here for ScrollingAdaptor::blueprintProgressJson and the Monitors page that renders it.

Reports the current (desktop, activity) context, matching visibleStripJson — a sibling desktop's strip has its own progress and is not what a screen readout means. A screen with no blueprint, no state yet, or one this engine does not own reports {0, 0}.

◆ cancelDragAutoScroll()

void PhosphorScrollEngine::ScrollEngine::cancelDragAutoScroll ( )
overridevirtual

The ONE disarm: hands the drop target back to the ordinary hit-test and restarts the start delay.

Every caller must either re-aim (repairDragAutoScrollTarget), clear lastTarget itself, or accept the stale target deliberately the way the tick's no-geometry exits do (foreign screen, dead state, dead work area — where a hit-test is impossible and the daemon's own screen-mismatch teardown follows). A thoughtless bare cancel leaves the auto-scroll's last edge slot standing for a release to commit.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ cancelDragInsertPreview()

void PhosphorScrollEngine::ScrollEngine::cancelDragInsertPreview ( bool dragStillActive = false)
overridevirtual

dragStillActive carries the base-interface contract and is deliberately unused here (see the definition): the DETACH-ONCE model plus the interactive-drag mark already keep the dragged window's rect from being emitted mid-drag.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ capturePlacement()

std::optional< PhosphorEngine::WindowPlacement > PhosphorScrollEngine::ScrollEngine::capturePlacement ( const QString & windowId) const
overridevirtual

Report windowId's CURRENT placement for persistence, or nullopt if this engine does not manage it.

Fill the engine's EngineSlot — state from its token vocabulary (free/floating/snapped/tiled/...) plus its slot reference (zone IDs / tile order) — under engines[engineId()], and the screen/desktop/ activity context. Do NOT set freeGeometryByScreen: the capture orchestrator fills the shared free/float geometry from the live frame, and only when the state is free/floating, so a managed rect never becomes the float-back.

This is the polymorphic capture seam the common layer drives — the WTA close hook and the save-time snapshot call it for every window.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ centerColumn()

void PhosphorScrollEngine::ScrollEngine::centerColumn ( const QString & screenId)

◆ centerVisibleColumns()

void PhosphorScrollEngine::ScrollEngine::centerVisibleColumns ( const QString & screenId)

Center the span of fully visible columns (niri center-visible-columns).

◆ claimCrossScreenReopen()

bool PhosphorScrollEngine::ScrollEngine::claimCrossScreenReopen ( const QString & windowId,
const QString & openingScreenId,
int minWidth,
int minHeight )
overridevirtual

The reopen claim (see IPlacementEngine for the contract): only a FIFO record on another virtual screen of the opening output, in scrolling mode, for a window opening on a scrolling screen; never a record on another monitor and never the window's own.

This implementation: first-observation gate by ScrollState MEMBERSHIP; the store's claim-honouring, live-excluding peekForReclaim over the registry-aware appId; the home in the LIVE scrolling set with the record's (desktop, activity) matching its current key (sentinel records stay eligible); returns the REAL adoption outcome verified by membership after the windowOpened re-entry. Peek-not-take: consumption stays with the open path's own restore machinery (strip stash claim, takeForReopen).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearCurrentDesktopForScreen()

void PhosphorScrollEngine::ScrollEngine::clearCurrentDesktopForScreen ( const QString & screenId)
overridevirtual

Drop a screen's per-output desktop, reverting it to the global current.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearModeSpecificFloatMarker()

void PhosphorScrollEngine::ScrollEngine::clearModeSpecificFloatMarker ( const QString & windowId)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearPerScreenConfig()

void PhosphorScrollEngine::ScrollEngine::clearPerScreenConfig ( const QString & screenId)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearWindowedFullscreen()

void PhosphorScrollEngine::ScrollEngine::clearWindowedFullscreen ( const QString & windowId)

Compositor-driven reconciliation: the client left fullscreen on its own.

◆ columnIndexForWindow()

int PhosphorScrollEngine::ScrollEngine::columnIndexForWindow ( const QString & screenId,
const QString & windowId ) const

The column index windowId's column holds on screenId (current context), or -1 — the landing-slot reference a swap counterpart uses via HandoffContext.insertIndex.

◆ commitDragInsertPreview()

void PhosphorScrollEngine::ScrollEngine::commitDragInsertPreview ( )
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ computeDragInsertTargetAtPoint()

DragInsertTarget PhosphorScrollEngine::ScrollEngine::computeDragInsertTargetAtPoint ( const QString & screenId,
const QPoint & cursorPos ) const
overridevirtual

primary = column index; newSlot true opens a NEW column at primary; otherwise the window joins column primary as tile secondary (a MODEL-column tile index — minimized tiles count).

Zone map, symmetric by construction: a visible column's two END bands along the strip open a new column at that column's own spot (it steps aside and the indicator covers it), its middle joins it, and each inter-column boundary belongs to exactly one band — the following neighbour's LEADING band. Only the view's two extremes differ: the first visible column's LEADING band (plus everything before it along the strip) aims the leading slot as a past-the-edge hint (leadingEdge), and the last visible column's TRAILING band (plus everything after it) appends after the strip. The dragged window is DETACHED while a preview is live, so the strip hit-tested here is stable across ticks and no own-slot special case exists (nothing the cursor hovers can be the dragged window). While a preview is live for screenId the hit-test resolves against the preview's captured context key, not the screen's current one.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ consumeOrExpelWindow()

void PhosphorScrollEngine::ScrollEngine::consumeOrExpelWindow ( int delta,
const QString & screenId )

delta -1 = towards the strip's start, +1 = towards its end (niri consume-or-expel-window-left/right).

◆ consumeWindowIntoColumn()

void PhosphorScrollEngine::ScrollEngine::consumeWindowIntoColumn ( const QString & screenId)

◆ cycleColumnPresetWidth()

void PhosphorScrollEngine::ScrollEngine::cycleColumnPresetWidth ( int delta,
const QString & screenId )

delta -1/+1 through the preset width list.

◆ cycleFocus()

void PhosphorScrollEngine::ScrollEngine::cycleFocus ( bool forward,
const PhosphorEngine::NavigationContext & ctx )
overridevirtual

Cycle keyboard focus through managed windows.

Implements PhosphorEngine::IPlacementEngine.

◆ cycleTab()

void PhosphorScrollEngine::ScrollEngine::cycleTab ( int delta,
const QString & screenId )

Cycle the active column's tabs, wrapping at either end.

delta -1/+1. The stack twin of focusColumnWrap: the generic directional focus crosses onto the neighbouring output at the stack edge, and this is the opt-in variant that stays inside the column. Acts on the tiles of a stacked column too — they are the same tiles the column shows as tabs once it is flipped.

◆ cycleWindowPresetHeight()

void PhosphorScrollEngine::ScrollEngine::cycleWindowPresetHeight ( int delta,
const QString & screenId )

◆ desktopsWithActiveState()

QSet< int > PhosphorScrollEngine::ScrollEngine::desktopsWithActiveState ( ) const
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dragAutoScrollActive()

bool PhosphorScrollEngine::ScrollEngine::dragAutoScrollActive ( ) const
overridevirtual

Whether edge auto-scroll currently owns the drop target.

True from the moment the band's delay elapses until the cursor leaves the band, the preview ends, the strip shrinks to fit the viewport, the feature is switched off, or any other condition that makes the scroll incoherent (the implementation's disarm paths are the full list — a vanished state, a dead work area, no visible column, a foreign screen). Not an exhaustive contract, so do not read it as one. Reaching a strip end does NOT end ownership: the view is pinned but the cursor is still asking to insert past that edge, and that edge slot stays the promise. Handing the target back there would resume per-column hit-testing the instant the strip pins, which is the churn this whole mechanism exists to prevent.

While true the caller keeps pushing the indicator but must leave computeDragInsertTargetAtPoint alone.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dragAutoScrollTick()

bool PhosphorScrollEngine::ScrollEngine::dragAutoScrollTick ( const QString & screenId,
const QPoint & cursorPos,
qreal dtSeconds )
overridevirtual

Edge auto-scroll (drag_autoscroll.cpp).

Moves the VIEW only, which is compatible with DETACH-ONCE: the invariant is that structure and the hit-tested answer hold still under a stationary cursor, not that pixels do. It keeps that answer still by owning the target while it scrolls — see dragAutoScrollActive.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dragInsertIndicatorRect()

QRect PhosphorScrollEngine::ScrollEngine::dragInsertIndicatorRect ( const QString & screenId) const
overridevirtual

The rect the dragged window would occupy if it were dropped at the currently remembered target — the drop indicator the daemon paints.

Absolute screen pixels, the same basis as visibleTiles.

Detach-once means the strip NEVER opens a gap to show where the drop lands (autotile's live restructure slid this layout out from under a stationary cursor), so this rect is the only feedback there is. Null when no preview is live for screenId or before the first hit-test resolves a target. Not clamped into the viewport: a target on a parked column reports where it truly lands, and the overlay clips.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dragInsertPreviewPriorScreenId()

QString PhosphorScrollEngine::ScrollEngine::dragInsertPreviewPriorScreenId ( ) const
inlineoverridevirtual

See the base declaration.

Empty without a preview, and empty when begin took the window from untracked, which for this engine also covers a window that was floating outside any strip.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dragInsertPreviewScreenId()

QString PhosphorScrollEngine::ScrollEngine::dragInsertPreviewScreenId ( ) const
inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dragInsertPreviewWindowId()

QString PhosphorScrollEngine::ScrollEngine::dragInsertPreviewWindowId ( ) const
inline

The window id of the active drag-insert preview, or empty (test seam, mirroring AutotileEngine's accessor).

◆ dropParked()

void PhosphorScrollEngine::ScrollEngine::dropParked ( const QString & windowId,
const QString & physicalScreenId,
int desktop,
const QString & activity )
overridevirtual

Forget windowId's parked contexts; an empty physicalScreenId, a desktop of 0 or an empty activity matches every one.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ effectivePresetColumnWidths()

QList< qreal > PhosphorScrollEngine::ScrollEngine::effectivePresetColumnWidths ( const QString & screenId) const

Effective preset vocabulary for a screen: the per-screen TEMPLATE override when the daemon pushed a usable one (every entry validated against the same floor as the settings parser), else the cached settings list.

Wholesale replacement, never a merge — see ScrollPerScreenKeys. Public for D-Bus/introspection consumers (ScrollingAdaptor::presetVocabularyJson).

◆ effectivePresetWindowHeights()

QList< qreal > PhosphorScrollEngine::ScrollEngine::effectivePresetWindowHeights ( const QString & screenId) const

◆ enabledChanged

void PhosphorScrollEngine::ScrollEngine::enabledChanged ( bool enabled)
signal

◆ endArrivalBurst()

void PhosphorScrollEngine::ScrollEngine::endArrivalBurst ( )
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ engineId()

QString PhosphorScrollEngine::ScrollEngine::engineId ( ) const
inlineoverridevirtual

Stable engine identity for HandoffContext.fromEngineId.

Conventional values: "snap" / "autotile" / "scrolling". Empty string means "unidentified" and disables receive-side reasoning that depends on the source mode.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ entryWindowForCrossing()

QString PhosphorScrollEngine::ScrollEngine::entryWindowForCrossing ( const QString & screenId,
const QString & direction ) const

Cross-mode swap support (queried by the daemon when THIS engine is the swap target): the strip window at the entry edge facing the source for a crossing arriving in direction — a "right" crossing enters the viewport's left edge.

Ranked over visibleTiles, so the answer is always a tile that carries a zone number. Empty when the strip is empty, and equally when nothing on it is currently visible (every column parked, or no valid work area) — the caller degrades a swap to a plain move on both.

◆ equalizeVisibleColumnWidths()

void PhosphorScrollEngine::ScrollEngine::equalizeVisibleColumnWidths ( const QString & screenId)

Equal shares of the viewport for every column intersecting it, clipped ones included (Karousel equalize; ScrollStrip carries the contract).

Refuses with fewer than two.

◆ equalizeWindowHeights()

void PhosphorScrollEngine::ScrollEngine::equalizeWindowHeights ( const QString & screenId)

An equal share of the focused column for each of its windows (the height twin of equalizeVisibleColumnWidths).

◆ expandColumnToAvailableWidth()

void PhosphorScrollEngine::ScrollEngine::expandColumnToAvailableWidth ( const QString & screenId)

◆ expandWindowToAvailableHeight()

void PhosphorScrollEngine::ScrollEngine::expandWindowToAvailableHeight ( const QString & screenId)

Grow the focused window into the empty space left in its column (the height twin of expandColumnToAvailableWidth).

A column holding an Auto window has no empty space to claim, since that window already absorbs it.

◆ expelWindowFromColumn()

void PhosphorScrollEngine::ScrollEngine::expelWindowFromColumn ( const QString & screenId)

◆ focusColumnAtIndex()

void PhosphorScrollEngine::ScrollEngine::focusColumnAtIndex ( int index,
const QString & screenId )

Focus the column at strip index index (ScrollStrip::focusColumn), re-anchoring the view under the same centering policy every other focus verb applies, then activating the column's active window.

An index past the last column clamps to it, the strip's own rule; a negative index is out of contract and is refused silently, the way focusColumnPlain refuses a bad delta. The already-active column answers no_target like the other focus verbs.

◆ focusColumnByDelta()

void PhosphorScrollEngine::ScrollEngine::focusColumnByDelta ( int delta,
const QString & screenId )

Focus the previous/next column ALONG THE STRIP, for callers holding a strip-relative intent rather than a physical direction.

The wheel is the one that matters: the effect collapses both physical wheel axes onto a single +/-1 before it ever reaches D-Bus.

The physical token is synthesized HERE from the screen's own axis, which is the whole point — a caller that spelled "left"/"right" itself would walk the STACK on a vertical strip. Deliberately not routed through focusColumnPlain: that verb stops at the strip edge, and the wheel's documented contract is that a notch at the edge crosses onto the adjacent output.

◆ focusColumnFirst()

void PhosphorScrollEngine::ScrollEngine::focusColumnFirst ( const QString & screenId)

◆ focusColumnLast()

void PhosphorScrollEngine::ScrollEngine::focusColumnLast ( const QString & screenId)

◆ focusColumnPlain()

void PhosphorScrollEngine::ScrollEngine::focusColumnPlain ( int delta,
const QString & screenId )

Plain adjacent-column focus that stops at the strip edge (niri focus-column-left/right).

delta -1/+1. The generic focusInDirection crosses monitors instead; this is the opt-in edge-stop variant.

◆ focusColumnWrap()

void PhosphorScrollEngine::ScrollEngine::focusColumnWrap ( int delta,
const QString & screenId )

Adjacent-column focus that wraps to the far end at the strip edge (niri focus-column-left-or-last / right-or-first).

delta -1/+1.

◆ focusedColumnWindows()

QStringList PhosphorScrollEngine::ScrollEngine::focusedColumnWindows ( const QString & screenId,
FocusedColumnRefusal * reason = nullptr ) const

The focused column of screenId's current strip, in tile order, for a verb that relocates the column as a whole (the dynamic-workspaces move-column-to-workspace verb).

screenId must be the EXACT screen this engine keys the strip by, the virtual "<phys>/vs:N" id on a subdivided monitor. There is no physical-to-virtual resolution and no active-screen fallback: a monitor split into several scrolling sub-screens has no single answer for its physical id, and any guess would relocate a column the user never addressed.

Refuses under float focus, the same refusal the column verbs give (refuseUnderFloatFocus): the strip's active column is then the one behind the float, not the one the user is looking at.

The answer includes the column's HIDDEN members: a window of a shared column that is out of the strip because it is minimized or held for its own fullscreen, placed at the slot it will return to. Those are part of the column and travel with it. A window the user floated is not, and is left out. Minimized is read from the window registry's tri-state answer, and an unknown state is treated as not minimized.

reason, when given, says why the answer is empty (None otherwise).

◆ focusInDirection()

void PhosphorScrollEngine::ScrollEngine::focusInDirection ( const QString & direction,
const PhosphorEngine::NavigationContext & ctx )
overridevirtual

Move keyboard focus to the adjacent window.

Implements PhosphorEngine::IPlacementEngine.

◆ focusTab()

void PhosphorScrollEngine::ScrollEngine::focusTab ( int ordinal,
const QString & screenId )

Focus the active column's ordinal'th tab, 1-based, counting the column's non-minimized tiles — which are the tabs its indicator draws when the column is tabbed.

Like cycleTab it is NOT gated on the display mode, so it addresses a stacked column's windows the same way and resolves even when no indicator is drawn at all. An ordinal past the column's tab count answers no_target feedback.

◆ focusWindowBottom()

void PhosphorScrollEngine::ScrollEngine::focusWindowBottom ( const QString & screenId)

◆ focusWindowTop()

void PhosphorScrollEngine::ScrollEngine::focusWindowTop ( const QString & screenId)

First/last non-minimized tile of the active column (niri focus-window-top/bottom).

◆ forceReemit()

void PhosphorScrollEngine::ScrollEngine::forceReemit ( const QString & screenId)

Retile screenId with its next layout forced to emit: the daemon re-asserting a strip KWin moved.

◆ forgetClosedFullscreenHold()

void PhosphorScrollEngine::ScrollEngine::forgetClosedFullscreenHold ( const QString & windowId)

Drop the closed-mid-hold memory once the daemon's close capture has read it, or a live release left no capture to read it.

The same moment ends the last-applied rect a close retained (lastManagedRect), when the window no longer holds a place in any strip here, since nothing else reclaims it while the daemon runs. After a live release that also takes it from the float-back refusal, which then rests on the daemon's record of the frame the window settled at under management.

◆ handoffReceive()

void PhosphorScrollEngine::ScrollEngine::handoffReceive ( const HandoffContext & ctx)
overridevirtual

Receive ownership of a window from another engine.

Implementations should:

  • Add the window to their own tracking (per-screen/per-state).
  • Decide placement (snap to zone / tile / float) using the context and engine-local policy. Drag drops typically place at dropPos; non-drag handoffs (cross-engine focus changes, programmatic moves) typically respect wasFloating (the window keeps its live frame, so no geometry is carried in the context).
  • Emit any windowFloatingChanged / placement signals their normal placement paths emit, so downstream state stays consistent.

Default is a no-op so engines that don't yet implement the handoff don't reject the call — the orchestrator falls back to its legacy path.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ handoffRelease()

void PhosphorScrollEngine::ScrollEngine::handoffRelease ( const QString & windowId)
overridevirtual

Release ownership of a window WITHOUT modifying its geometry.

Implementations should:

  • Remove the window from per-screen/per-state tracking.
  • Clear zone assignments (if any) WITHOUT triggering a resnap of neighbours — that's the receiving engine's job once it places the window in its layout.
  • Preserve any pre-tile / pre-float captured geometry that should survive the cross-engine move (the receiving engine may consult it via the HandoffContext for size preservation).

Default is a no-op for the same reason as handoffReceive.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ hasDragInsertPreview()

bool PhosphorScrollEngine::ScrollEngine::hasDragInsertPreview ( ) const
inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ hasParked()

bool PhosphorScrollEngine::ScrollEngine::hasParked ( const QString & windowId,
const QString & physicalScreenId ) const
overridevirtual

Whether windowId has a context parked under physicalScreenId (any output when it is empty).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ heldKeyForWindow()

std::optional< PhosphorEngine::PlacementStateKey > PhosphorScrollEngine::ScrollEngine::heldKeyForWindow ( const QString & windowId) const
overridevirtual

The (screen, desktop, activity) key of the state that genuinely holds windowId, tiled or floating, in ANY context, or nullopt when none does.

Membership-grade like heldScreenForWindow but NOT scoped to the screen's current context: for a lifecycle engine the desktop reconcile asks "which desktop's stack still lists this window" after the compositor reports a desktop-set change, when the holding state is usually a BACKGROUND one the current-context predicates answer empty for.

At most ONE key comes back: the PRIMARY membership (the one in the context its screen shows, else the first) when its state genuinely holds the window, otherwise the first membership whose state does. The membership pass answers for a window's other desktops. nullopt is not "no state mentions this window": a phantom membership left by a refused adoption answers nullopt too, the safe direction here. ScrollEngine answers nullopt during a drag-insert preview (the window is detached from the strip until the drop or cancel).

All three engines override it. The reconcile asks only a lifecycle engine; snapping, a membership engine, answers for its Meta+F test, the bus swap's held context and the window-state rows.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ heldScreenForWindow()

QString PhosphorScrollEngine::ScrollEngine::heldScreenForWindow ( const QString & windowId) const
overridevirtual

OPTIONAL: the screen this engine genuinely HOLDS the window on IN THE SCREEN'S CURRENT CONTEXT — a MEMBERSHIP answer (tiled or engine-floating both count; a phantom reverse-map key does not), empty when the engine does not hold it or holds it only in a background context.

Read where the engine's own hold matters more than the window's position: the daemon's seed filter, engine routing and tiled-in-view predicate, the tracking adaptor's capture, focus, resize and screen-leave paths, and the tiling adaptor's arrival dispatch, where after a claim onto another virtual screen the effect's queued announce still carries the ARRIVAL screen. isWindowTracked cannot serve: its contract is PER-ENGINE (ScrollEngine answers from a raw reverse-map key a refused adoption can leave dangling; SnapEngine and AutotileEngine verify membership). isWindowManaged/isWindowTiled cannot either: both exclude engine-floating windows, which a claim can produce.

CURRENT-context only, so the check never suppresses repair: a claim's adoption keys by the home screen's current context, while a stale hold in a BACKGROUND context is healed by the very announce this check would otherwise refuse.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isActiveOnScreen()

bool PhosphorScrollEngine::ScrollEngine::isActiveOnScreen ( const QString & screenId) const
overridevirtual

Whether this engine is active on the given screen.

Implements PhosphorEngine::IPlacementEngine.

◆ isEnabled()

bool PhosphorScrollEngine::ScrollEngine::isEnabled ( ) const
overridevirtualnoexcept

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isFullscreenFloated()

bool PhosphorScrollEngine::ScrollEngine::isFullscreenFloated ( const QString & windowId) const

True while the slot carries the compositor's hold, and for a window that CLOSED mid-hold until WindowTracking.windowClosed has taken its capture (forgetClosedFullscreenHold).

◆ isModeSpecificFloated()

bool PhosphorScrollEngine::ScrollEngine::isModeSpecificFloated ( const QString & windowId) const
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isWindowFloatingInScroll()

bool PhosphorScrollEngine::ScrollEngine::isWindowFloatingInScroll ( const QString & windowId) const

Authoritative scroll float state (the scroll half of the per-engine float contract the WTS resolver reads).

◆ isWindowManaged()

bool PhosphorScrollEngine::ScrollEngine::isWindowManaged ( const QString & windowId) const
overridevirtual

Whether the engine considers the window "managed" (eligible for layout operations).

Semantics are engine-specific:

  • Autotile: equivalent to isWindowTiled (floating windows excluded).
  • Scrolling: the window occupies a strip column (floating windows excluded), same shape as autotile.
  • Snap: NOT implemented — SnapEngine keeps the inherited false. Callers that need a consistent cross-engine check for "engine owns this window at all" should use isWindowTracked instead; that is also the only correct check on a snap screen.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isWindowTiled()

bool PhosphorScrollEngine::ScrollEngine::isWindowTiled ( const QString & windowId) const
overridevirtual

Whether the window is actively tiled (engine-owned, non-floating).

Distinct from isWindowTracked (which includes floating windows).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isWindowTracked()

bool PhosphorScrollEngine::ScrollEngine::isWindowTracked ( const QString & windowId) const
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ lastManagedRect()

QRect PhosphorScrollEngine::ScrollEngine::lastManagedRect ( const QString & windowId) const
overridevirtual

The exact rect this engine last APPLIED to windowId while managing it (its tile rect), remembered PAST the window's transition out of the managed state.

On a float toggle the engine flips its managed bit before the compositor repositions the window, so state predicates (isWindowTiled et al.) already answer "not managed" while the live frame still IS the managed rect — the capture orchestrator compares against this to refuse adopting such a frame as free/float geometry. Invalid when the engine never applied a rect (the base default: engines whose managed rects are resolvable from persisted state, like snap's zone geometry, don't need it).

Reimplemented from PhosphorEngine::PlacementEngineBase.

◆ layoutSupport()

LayoutSupport PhosphorScrollEngine::ScrollEngine::layoutSupport ( ) const
inlineoverridevirtual

The strip consumes layouts as sizing TEMPLATES, never as window placement: the screen's assigned ScrollingTemplate is the sizing vocabulary.

Its STORED preset lists (presetColumnWidths / presetWindowHeights) become the screen's preset column-width and window-height vocabularies, pushed straight through by the daemon, and its seed blueprint prescribes the columns the strip opens with. No geometry is derived from a layout's zones. Explicit override — the capability is load-bearing for the daemon's layout-selection gates, not an inherited absence.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ loadState()

void PhosphorScrollEngine::ScrollEngine::loadState ( )
overridevirtual

◆ managedFocusedWindow()

QString PhosphorScrollEngine::ScrollEngine::managedFocusedWindow ( const QString & screenId) const
overridevirtual

The window this engine considers focused on screenId, or empty.

The focus half of the mode-transition capture that managedWindowOrder supplies the position half of. Order alone is not enough to hand a flip back to the user unchanged: an engine with a VIEW (the strip) has to know which window to anchor on, and re-deriving that from position picks whichever column the seed happened to adopt first.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ managedWindowOrder()

QStringList PhosphorScrollEngine::ScrollEngine::managedWindowOrder ( const QString & screenId) const
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ markModeSpecificFloated()

void PhosphorScrollEngine::ScrollEngine::markModeSpecificFloated ( const QString & windowId)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ maximizeWindowHeight()

void PhosphorScrollEngine::ScrollEngine::maximizeWindowHeight ( const QString & screenId)

Toggle the focused window between filling its column and the even split (the height twin of toggleMaximizeColumn).

Unlike that one this keeps no pre-maximize slot; ScrollStrip::toggleMaximizeActiveWindowHeight documents why.

◆ minimizeColumnWidth()

void PhosphorScrollEngine::ScrollEngine::minimizeColumnWidth ( const QString & screenId)

The focused column at the smallest preset (Karousel minimize-width).

The strip falls back to the engine floor when the vocabulary is empty, an arm only a test or an embedder handing the strip bare params can reach: every in-tree producer of the preset list substitutes a non-empty fallback for an empty one.

◆ minimizeWindowHeight()

void PhosphorScrollEngine::ScrollEngine::minimizeWindowHeight ( const QString & screenId)

The focused window at the shortest preset height (the height twin of minimizeColumnWidth).

◆ moveColumnToFirst()

void PhosphorScrollEngine::ScrollEngine::moveColumnToFirst ( const QString & screenId)

◆ moveColumnToIndex()

void PhosphorScrollEngine::ScrollEngine::moveColumnToIndex ( int from,
int to,
const QString & screenId )

Move the column at strip index from to strip index to (ScrollStrip::moveColumnTo), leaving the moved column active and re-anchoring the view the way the other move verbs do, then activating its active window.

A negative index is refused silently like focusColumnAtIndex's; an index past the end, or from == to, answers no_target since there is no such column to move (from is not clamped, unlike a focus index).

◆ moveColumnToLast()

void PhosphorScrollEngine::ScrollEngine::moveColumnToLast ( const QString & screenId)

◆ moveFocusedInDirection()

void PhosphorScrollEngine::ScrollEngine::moveFocusedInDirection ( const QString & direction,
const PhosphorEngine::NavigationContext & ctx )
overridevirtual

Move the focused window to the adjacent slot.

Implements PhosphorEngine::IPlacementEngine.

◆ moveFocusedToFloating()

void PhosphorScrollEngine::ScrollEngine::moveFocusedToFloating ( const QString & screenId)

Explicit float / re-tile of the focused window (niri move-window-to-floating / move-window-to-tiling); already-there presses answer with no_target feedback.

◆ moveFocusedToPosition()

void PhosphorScrollEngine::ScrollEngine::moveFocusedToPosition ( int position,
const PhosphorEngine::NavigationContext & ctx )
overridevirtual

Move the focused window to the Nth position.

Implements PhosphorEngine::IPlacementEngine.

◆ moveFocusedToTiling()

void PhosphorScrollEngine::ScrollEngine::moveFocusedToTiling ( const QString & screenId)

◆ noteCrossScreenClaimsExhausted()

void PhosphorScrollEngine::ScrollEngine::noteCrossScreenClaimsExhausted ( const QString & windowId,
bool exhausted )
overridevirtual

INERT, kept for ABI: fed the removed cross-screen defer gates.

Nothing calls it and the in-tree overrides ignore it.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ onWindowResized()

void PhosphorScrollEngine::ScrollEngine::onWindowResized ( const QString & windowId,
const QRect & oldFrame,
const QRect & newFrame,
const QString & screenId )
overridevirtual

Notify the engine that a tracked window finished an interactive resize.

The daemon's WindowTracking adaptor forwards the compositor's interactive-resize-finished event here so an engine can reflow the rest of its layout to absorb the change (autotile fills the freed gap; GitHub #652). oldFrame / newFrame are the window's frame geometry before and after the resize; screenId is the screen the daemon resolved the window to. Default is a no-op for engines (e.g. snap) that have no neighbour-reflow model.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ parkOutput()

QStringList PhosphorScrollEngine::ScrollEngine::parkOutput ( const QString & physicalScreenId)
overridevirtual

Copy every context of physicalScreenId (each of its virtual screens) into the park, before the prune drops them.

Returns the parked windows.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ perScreenOverrides()

QVariantMap PhosphorScrollEngine::ScrollEngine::perScreenOverrides ( const QString & screenId) const
inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ providesDragInsertSelector()

bool PhosphorScrollEngine::ScrollEngine::providesDragInsertSelector ( ) const
inlineoverridevirtual

The strip renders in the daemon's drag popup as column cards speaking the drag-insert vocabulary (new column in a gap, join on a card, tab dock on a tabbed card).

Explicit override — load-bearing for the drag adaptor's selector gate, not an inherited absence.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pruneStaleWindows()

int PhosphorScrollEngine::ScrollEngine::pruneStaleWindows ( const QSet< QString > & aliveWindowIds)
overridevirtual

Drop any per-engine bookkeeping for windows not in aliveWindowIds.

The base keeps no per-window state of its own now, so it returns 0; engines override and add their own pruning (then call the base).

Reimplemented from PhosphorEngine::PlacementEngineBase.

◆ pruneStatesForActivities()

void PhosphorScrollEngine::ScrollEngine::pruneStatesForActivities ( const QStringList & validActivities)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pruneStatesForDesktop()

void PhosphorScrollEngine::ScrollEngine::pruneStatesForDesktop ( int removedDesktop)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pruneStatesForRemovedScreen()

void PhosphorScrollEngine::ScrollEngine::pruneStatesForRemovedScreen ( const QString & physicalScreenId)
overridevirtual

Prune per-(screen, desktop, activity) state for a PHYSICALLY REMOVED output (monitor hot-unplug), matching every virtual sub-screen of the removed physical id.

All three engines override this and the daemon drives each from its screenRemoved handling: snap's stores are created lazily on placement with no screens set to reap them, and the two tiling engines' screens-set sweeps only reap CURRENT-context states, so sibling-context states (other desktops/activities) of the removed output would leak without the explicit whole-output prune. A tiling-family engine must emit windowsReleased for the windows it drops here, AFTER its reverse-map cleanup, so the daemon's restore consumers can re-home them; snap does not, because it is the engine those releases are restored INTO.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pushToEmptyZone()

void PhosphorScrollEngine::ScrollEngine::pushToEmptyZone ( const PhosphorEngine::NavigationContext & ctx)
overridevirtual

Move the focused window to the first empty slot.

Engines whose placement has no empty-slot concept answer with a "push"/"not_supported" feedback emit rather than silence — the shortcut must not read as broken (same policy the span default documents above).

Implements PhosphorEngine::IPlacementEngine.

◆ readoptParked()

bool PhosphorScrollEngine::ScrollEngine::readoptParked ( const QString & windowId,
const QString & parkedPhysicalId,
const QString & returnedPhysicalId )
overridevirtual

Re-seat windowId's contexts parked under parkedPhysicalId on returnedPhysicalId as a re-statement (no focus, no last-used), each in its own (screen, desktop, activity): its virtual screen on the returned output (or the bare output), never the context in view.

One that no longer runs the engine's mode as the daemon resolves it gets nothing (snap also refuses one switched off, disabled or excluding the window); one out of view is seated at once, or granted to the arrival path on a screen not running the mode yet. True if any was.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ reapplyLayout()

void PhosphorScrollEngine::ScrollEngine::reapplyLayout ( const PhosphorEngine::NavigationContext & ctx)
overridevirtual

Re-apply the current layout to all managed windows.

Implements PhosphorEngine::IPlacementEngine.

◆ reapplyWindowGeometry()

void PhosphorScrollEngine::ScrollEngine::reapplyWindowGeometry ( const QString & windowId)

Compositor-driven repair: the compositor moved this window behind the engine's back (KWin's fullscreen-exit restore), so evict its emit-gate memory and relayout its screen to re-emit the true rect.

◆ reconcileDesktopMemberships()

PhosphorEngine::MembershipReconcileResult PhosphorScrollEngine::ScrollEngine::reconcileDesktopMemberships ( const QString & screenId,
const PhosphorEngine::DesktopSpanQuery & spanOf )
overridevirtual

Give a window present on several desktops a column in each of their strips, so it can be placed and sized independently per desktop rather than existing only in the context it opened in.

Driven off the desktop SPAN, so {1,2} is handled on the same terms as sticky.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ reconcileWindowMemberships()

PhosphorEngine::MembershipReconcileResult PhosphorScrollEngine::ScrollEngine::reconcileWindowMemberships ( const QString & windowId,
const PhosphorEngine::DesktopSpanQuery & spanOf )
overridevirtual

The same pass for ONE window, on the screen it is held on.

The daemon calls it when the compositor reports that window's desktop set or activity changed, so a span shrink releases only the contexts the window left and a sticky transition adopts the context in view without waiting for a desktop switch.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ refreshConfigFromSettings()

void PhosphorScrollEngine::ScrollEngine::refreshConfigFromSettings ( )
overridevirtual

Re-read all tuning values from the engine's settings interface.

Called by the daemon after any settings change. Engines that cache config values (e.g. AutotileEngine) override this to repopulate their config struct. Engines that read on demand (e.g. SnapEngine) leave this as a no-op.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ releaseWindowOffScreen()

void PhosphorScrollEngine::ScrollEngine::releaseWindowOffScreen ( const QString & windowId,
const QString & keepScreenId )
overridevirtual

The base release, plus the stashed columns the window holds on any other screen (engine_stashleave.cpp).

Reimplemented from PhosphorEngine::PlacementEngineBase.

◆ remapDesktops()

void PhosphorScrollEngine::ScrollEngine::remapDesktops ( const PhosphorEngine::DesktopRemap & remap)
overridevirtual

OPTIONAL: KWin's desktop list changed (a removal, an insert or a reorder).

Move every structure keyed by a desktop number through remap and prune the removed desktops' (F763, F787). The default runs a change that only removes desktops as pruneStatesForDesktop then renumberDesktopsAfterRemoval per removal, highest first, and only logs an insert or a reorder, which it cannot apply. Defined in PlacementEngineBase.cpp. Appended last for ABI.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ remapRestoredStripStash()

void PhosphorScrollEngine::ScrollEngine::remapRestoredStripStash ( const PhosphorEngine::DesktopRemap & remap)

The start-up renumber when KWin's first desktop list lands after windows did (F1045): only the entries restoreStripState staged that no live window has touched since move through remap, onto a key it would have staged them on.

Strips, in-session stashes and every other context map keep the live numbering. (engine_desktopremap.cpp)

◆ renumberDesktopsAfterRemoval()

void PhosphorScrollEngine::ScrollEngine::renumberDesktopsAfterRemoval ( int removedDesktop)
overridevirtual

Shift every per-(screen, desktop, activity) state ABOVE removedDesktop down by one, because Plasma renumbers x11 desktop numbers when a desktop in the middle is deleted (removing 2 of 4 makes 3 become 2 and 4 become 3).

The companion to pruneStatesForDesktop, which only drops the removed desktop's own state: without the shift every surviving higher state keeps its old number, and a consumer comparing a stored key against the compositor's numbers (the daemon's desktop-membership reconcile above all) reads a window that never moved as having left its desktop. The caller drives prune first, then this, knowing which desktop was removed (desktopCountChanged alone cannot tell). An implementation must move EVERY structure keyed by a PlacementStateKey or by a bare desktop number, walking the affected desktops in ASCENDING order so each target key is vacant when written. The single-removal form of remapDesktops.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ reportCommittedSize()

void PhosphorScrollEngine::ScrollEngine::reportCommittedSize ( const QString & windowId,
const QSize & offered,
const QSize & committed )

Compositor-driven: the size a client settled on when offered its tile rect, reported when it is not the offer (engine_committed.cpp).

Only an answer to the tile's WHOLE resolved rect counts, and only while minimum sizes are respected; a peek clamped at the screen edge or a stack tile clamped across the strip was never offered its column. What the engine learns, per window and per strip orientation (CommittedExtent):

  • an extent ALONG the strip past the offer becomes a floor the column is held to like a declared minimum, and the screen-edge peek floor rises with it. That peek memory outlives a dropped floor while a column still offers at least as much. It ends once this column offers less on a pass that offers the tile its whole rect and every other column the window holds offers less too (a float or a maximized-to-edges membership elsewhere keeps it), and ending it ends that orientation's whole extent, give-back history included;
  • a narrower answer gives a floor back: down to the answer while that still overshoots what the column resolves to without the floor, entirely once it does not. A narrower answer never creates a floor. A floor re-taught after a give-back is pinned against further give-backs, so a client that does not answer one offer the same way twice settles instead of resizing its column on every round trip;
  • an answer within kCommittedExtentSlackPx of the offer along the strip counts as the offer, and one that is the offer from a tile holding a peek memory longer than it and no floor ends that memory (and the extent with it) once every other column the window holds offers less too: the client took a whole offer narrower than the memory, a park included, and the compositor reports a parked tile's matched answer for exactly this;
  • an extent ACROSS the strip past the offer, inside the work area, becomes a floor on the tile's share of its column (CommittedCrossExtent), held like a declared minimum across the strip, so the stack's split gives the tile at least that and shrinks its siblings. Its premise is the tile's offer along the strip when it was learned, re-stamped when the same answer leaves a changed, nonzero floor along the strip (one taught, or one partly given back). An answer that gives the floor along the strip back entirely moves the offer without re-stamping, so the premise sweep reads it. A shorter answer gives a cross floor back the way a narrower one gives back a floor along the strip, pinning included. Every comparison against an offer, a work area or a capacity allows kCommittedExtentSlackPx, so a rounding pixel is never read as an answer, an overflow or a floor kept a pixel past what a column offers. A floor its column can never offer (the floor plus the tab reservation past the work area's main extent), a cross floor its stack can never hold beside its siblings' own floors (ScrollStrip::tileCrossCapacityPx), or an answer longer than the work area across the strip floats the window, the policy a declared minimum past the work area already gets, announced PASSIVELY like the open-time oversized float (the engine decided it, so no float OSD and no free-geometry restore). Of two tiles whose cross floors cannot fit together, the one whose client teaches its floor second floats. A floor drops when its column satisfies it in every desktop the window holds a column on, on the user's own interactive resize along the strip (onWindowResized, for every tile of the column), when the client lowers its declared minimum on that axis, when a work-area shrink leaves it past the work area, and when the window leaves the engine, leaves its output, moves to another desktop or drops into a strip as an arrival sized by its client; it survives float round trips (a user float, minimize, the fullscreen hold, a cancelled drag), drag reorders, Retile, and the evacuee park. A cross floor follows the same rules across the strip (satisfied in every desktop, a user resize across the strip, a lowered minimum across it, the same leaves and survivals), and also drops when its stack can no longer hold it and when the tile's offer along the strip moves off its premise, since a client that picks its cross extent from its width may answer the new width differently and would otherwise be held to an answer it gave another width.

◆ resetStripToDefaults()

void PhosphorScrollEngine::ScrollEngine::resetStripToDefaults ( const QString & screenId)

Every column on the screen back to the context's default width and display, every window back to the even split: the scrolling half of the mode-neutral Retile shortcut.

Either extent is left as it is when the context's default for it is "the client decides" and no rule pins one (see resetDefaultColumnWidthFor and resetDefaultWindowHeightFor); the display always resets. Re-applies the layout the way the autotile and snapping halves re-apply theirs. Intents only: a column held to a floor (its client's declared minimum, or a floor its client's own commits taught, see reportCommittedSize) stays at that floor, since neither is an intent the reset could write.

◆ restoreFocusedWindow()

void PhosphorScrollEngine::ScrollEngine::restoreFocusedWindow ( const PhosphorEngine::NavigationContext & ctx)
overridevirtual

Restore the focused window out of its managed state.

Implements PhosphorEngine::IPlacementEngine.

◆ restoreStripState()

void PhosphorScrollEngine::ScrollEngine::restoreStripState ( const QJsonObject & state)

Load a serializeStripState blob into the stash so the EXISTING arrival-restore path (restoreFromStripStash) rebuilds each strip as its windows are announced.

Additive and conservative: keys that already have a stash entry or a live populated state are skipped, so a second load cannot re-stage stale structure over adopted windows.

◆ retile()

void PhosphorScrollEngine::ScrollEngine::retile ( const QString & screenId = QString())
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ rotateWindows()

void PhosphorScrollEngine::ScrollEngine::rotateWindows ( bool clockwise,
const PhosphorEngine::NavigationContext & ctx )
overridevirtual

Rotate all managed windows on the screen.

Implements PhosphorEngine::IPlacementEngine.

◆ saveState()

void PhosphorScrollEngine::ScrollEngine::saveState ( )
overridevirtual

◆ scheduleRetileForScreen()

void PhosphorScrollEngine::ScrollEngine::scheduleRetileForScreen ( const QString & screenId)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ screenForTrackedWindow()

QString PhosphorScrollEngine::ScrollEngine::screenForTrackedWindow ( const QString & windowId) const
overridevirtual

Return the screen this engine considers the window to be on (any context), or empty if the window isn't tracked by this engine.

The daemon's shortcut router consults it across engines, so a cross-engine handoff that emptied the source's tracking still routes the next shortcut to the engine that now owns the window.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ scrollingScreensChanged

void PhosphorScrollEngine::ScrollEngine::scrollingScreensChanged ( const QStringList & screenIds,
bool isDesktopSwitch )
signal

Scrolling twin of autotileScreensChanged, with the same identical-set re-emit contract on desktop/activity switches.

◆ scrollViewByPercent()

void PhosphorScrollEngine::ScrollEngine::scrollViewByPercent ( qreal percent,
const QString & screenId )

Scroll the view along the strip by percent of the work area's MAIN extent WITHOUT changing focus (Karousel scroll-left/right and its page variants; niri has no equivalent).

Positive is forward along the strip, negative is back, clamped at both ends, and the view stays where it lands: the strip's centering policy hands the view over to the pan until something re-attaches it (ScrollStrip's View detachment section lists what does). A percent that rounds to fewer than one pixel reports no_movement; a pan already pinned at the end it is asked to move toward reports no_target. The OSD names the two refusals differently. Takes a percent rather than pixels because the work area is resolved here and nowhere the shortcut layer can see.

◆ scrollViewByPx()

void PhosphorScrollEngine::ScrollEngine::scrollViewByPx ( int px,
const QString & screenId )

The pixel twin of scrollViewByPercent, for a caller that already holds a distance along the strip (the placement map's drag pan, over org.phosphor_works.Placement.Scrolling.scrollViewByPx).

Same detachment and clamping, but the only answer it reports is no_windows, for an empty strip. A successful pan, a zero px and a pan pinned at the end it is asked to move toward all report nothing, because the map pans once per frame of a drag and the navigation OSD would keep returning for the whole of it, a drag held against the strip's end or held still included. px is bounded to a million pixels either way, the band the percent verb and the D-Bus adaptor use; that only trims a pan the strip would clamp at its end anyway.

◆ serializeStripState()

QJsonObject PhosphorScrollEngine::ScrollEngine::serializeStripState ( ) const

Durable strip-structure snapshot: every LIVE strip (current states) plus the un-consumed mode-round-trip stash entries, keyed "screenId|desktop|activity".

On a key collision the live strip's focus, view and axis win and the stash's not-yet-returned columns are appended after the live ones (a merge, not a replacement). The daemon persists this blob through the WTA's session store so a login restore rebuilds stacked columns (with each column's active tile, i.e. a tabbed column's shown tab), the strip focus, and the view anchor together with whether that anchor was an explicit pan (the detach latch) instead of one default column per window. Per-tile height intents ride along; per-window minimum sizes do not — the client re-reports those. (engine_serialize.cpp)

◆ setActiveScreenHint()

void PhosphorScrollEngine::ScrollEngine::setActiveScreenHint ( const QString & screenId)
overridevirtual

NOTE: activeScreen() is deliberately NOT overridden.

m_activeScreen is this engine's private, focus-tracked memory of the last scrolling screen it acted on, and it can be stale while focus sits on a screen this engine does not scroll. Exposing an unguarded reader invited a caller to treat that memory, or a screen this engine may have stopped managing, as the current one.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setActiveScreens()

void PhosphorScrollEngine::ScrollEngine::setActiveScreens ( const QSet< QString > & screens)
overridevirtual

Set which screens use scrolling.

Retiles newly-added screens; tears down (and releases the windows of) removed ones. Mirrors AutotileEngine::setAutotileScreens, including the identical-set re-emit contract on desktop switches (the context-switch flag is consumed on both branches and PROPAGATED on both: the identical-set re-emit fires only on a real switch, and the changed-set emit carries the flag through). One deliberate divergence: the identical-set branch RETILES every screen even without a switch — the daemon's per-pass override push depends on it (scrolling.cpp, LOAD-BEARING).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setAllScreenGeometriesProvider()

void PhosphorScrollEngine::ScrollEngine::setAllScreenGeometriesProvider ( std::function< QList< QRect >()> allScreenGeometries)
inline

The union half of the provider seam: every output's full rect, used only for the parking union's bottom edge.

Ignored while a ScreenManager is present (it answers authoritatively).

◆ setAutotileModeResolver()

void PhosphorScrollEngine::ScrollEngine::setAutotileModeResolver ( ModeResolver resolver)
inline

INERT, kept for ABI: an autotile-mode resolver that fed the same removed defer gate.

Nothing reads it and the daemon no longer wires it.

◆ setColumnWidth()

void PhosphorScrollEngine::ScrollEngine::setColumnWidth ( const ColumnWidth & width,
const QString & screenId )

Absolute width/height intents (niri set-column-width/set-window-height with an absolute value).

D-Bus surface; no shortcut carries a value.

◆ setContextGapProvider()

void PhosphorScrollEngine::ScrollEngine::setContextGapProvider ( ContextGapProvider provider)
inline

◆ setCrossSurfaceResolver()

void PhosphorScrollEngine::ScrollEngine::setCrossSurfaceResolver ( PhosphorEngine::ICrossSurfaceResolver * resolver)
inlineoverridevirtual

Inject the cross-surface resolver used to find a neighbouring output / desktop when directional navigation reaches a surface boundary.

The resolver is borrowed, not owned; the caller must keep it alive for the engine's lifetime (in the daemon it outlives both engines by member order). Engines that don't support cross-surface navigation ignore it.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setCurrentActivity()

void PhosphorScrollEngine::ScrollEngine::setCurrentActivity ( const QString & activity)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setCurrentDesktop()

void PhosphorScrollEngine::ScrollEngine::setCurrentDesktop ( int desktop)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setCurrentDesktopForScreen()

void PhosphorScrollEngine::ScrollEngine::setCurrentDesktopForScreen ( const QString & screenId,
int desktop )
overridevirtual

Set a single screen's current virtual desktop (Plasma 6.7 "switch desktops independently for each screen").

A PURE context swap — it selects which per-(screen, desktop) tiling state is current for this screen; it does NOT migrate windows between desktop states (the other desktop's state must stay put so it reappears when that screen returns). Default no-op for engines that are not per-screen-desktop-aware.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setDragInsertClientSize()

void PhosphorScrollEngine::ScrollEngine::setDragInsertClientSize ( const QSize & size)
overridevirtual

Stores size on the live preview for commit's "the client decides" sizing of a window dragged in off a float.

No-op with no preview live.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setFloatPredicate()

void PhosphorScrollEngine::ScrollEngine::setFloatPredicate ( FloatPredicate predicate)
inline

◆ setFuzzyClaimGraceMsForTesting()

void PhosphorScrollEngine::ScrollEngine::setFuzzyClaimGraceMsForTesting ( qint64 graceMs)
inline

TEST SEAM: shorten (or lengthen) the cross-session fuzzy-claim grace window — the period after a stash is staged, or its screen re-enters scrolling, during which an appId-only claim may take a dead sibling's slot.

See StashedStrip::fuzzyClaimWindow.

It exists because the grace is measured by a QElapsedTimer against a 60 s constant, which leaves the REFUSAL half of the contract — the half that stops a stash hijacking every same-app window the user opens for the rest of the session — reachable in a test only by sleeping a minute. Passing 0 expires the window immediately, so a test can assert a late arrival opens fresh instead of adopting a stashed slot.

Production never calls this; the constructor's seed is the shipped value.

◆ setInitialFocusedWindow()

void PhosphorScrollEngine::ScrollEngine::setInitialFocusedWindow ( const QString & screenId,
const QString & windowId )
overridevirtual

Hand the incoming engine the focus captured from the outgoing one.

Advisory. WHEN to apply it is the implementor's choice, not part of this contract: the seeded window is usually not the LAST to re-announce, so an implementor that re-derives focus from arrivals has to defer the seed past them or have it overwritten. The scroll engine consumes it at the end of its arrival burst for exactly that reason; an implementor with no burst concept is free to apply it however it likes.

An empty windowId is not a no-op: it means the capturing transition found no focus to report, and it must CLEAR any seed an earlier one left, or a stale seed outlives the transition that owned it.

An engine with no view of its own has nothing to do with this and the default no-op is the right implementation for it — the focused window is wherever the compositor already has it.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setInitialWindowOrder()

void PhosphorScrollEngine::ScrollEngine::setInitialWindowOrder ( const QString & screenId,
const QStringList & windowIds )
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setInteractiveDragWindow()

void PhosphorScrollEngine::ScrollEngine::setInteractiveDragWindow ( const QString & windowId)
overridevirtual

While set, applyLayout never emits this window's rect, onWindowResized never reconciles its acks, reportCommittedSize learns nothing from its commits, and a grouped open never joins its column as a tab: during a drag the effect floats the window VISUALLY ONLY.

The engine keeps its strip tile for a drag with no drag-insert preview armed; under DETACH-ONCE the tile is gone for the duration of a preview, and the mark still has to hold because the acks keep arriving either way. So without it every mid-drag ack re-emitted the slot rect (yanking the window from the cursor) and pinned the column's width/height intents to transient drag frames. Clearing does NOT retile — every drop path finalizes on its own (see the definition).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setOpenParamsResolver()

void PhosphorScrollEngine::ScrollEngine::setOpenParamsResolver ( OpenParamsResolver resolver)
inline

◆ setPersistenceDelegate()

void PhosphorScrollEngine::ScrollEngine::setPersistenceDelegate ( std::function< void()> saveFn,
std::function< void()> loadFn )
inline

◆ setRestorePositionPredicate()

void PhosphorScrollEngine::ScrollEngine::setRestorePositionPredicate ( RestorePositionPredicate predicate)
inline

◆ setScreenGeometryProviders()

void PhosphorScrollEngine::ScrollEngine::setScreenGeometryProviders ( std::function< QRect(const QString &)> availableGeometry,
std::function< QRect(const QString &)> screenGeometry )
inline

Embedder/test seam: inject screen geometry when NO ScreenManager is wired (headless hosts).

availableGeometry supplies the work area, screenGeometry the full rect used for off-canvas parking bounds. Ignored while a ScreenManager is present. Without a ScreenManager the parking union degrades to the single screen's own bottom unless setAllScreenGeometriesProvider is also wired — a multi-output embedder must supply one or the other, or a park below one monitor may land on the one beneath it.

◆ setScrollingModeResolver()

void PhosphorScrollEngine::ScrollEngine::setScrollingModeResolver ( ModeResolver resolver)
inline

Scrolling-mode resolver: whether a context runs Scrolling as the daemon resolves it (feature switch and disabled cascade included, F1137).

claimCrossScreenReopen asks it of the RECORDED context (unset: it never claims), readoptParked of a context not in view, which gets nothing back once it stopped scrolling (unset: every context still scrolls), and handoffReceive of a background desktop it receives into, on the same terms as readoptParked.

◆ setSnappingModeResolver()

void PhosphorScrollEngine::ScrollEngine::setSnappingModeResolver ( ModeResolver resolver)
inline

INERT, kept for ABI: a snapping-mode resolver that fed windowOpened's cross-screen restore defer gate, which the reopen contract removed (a window opening on a scrolling screen is scroll's).

Nothing reads it and the daemon no longer wires it; a setter call is harmless.

◆ setWindowFloat()

void PhosphorScrollEngine::ScrollEngine::setWindowFloat ( const QString & windowId,
bool shouldFloat,
const QString & screenId = QString() )
overridevirtual

Announces Passive (windowFloatingStateSynced, F557); the user float verbs announce Active (F578).

Implements PhosphorEngine::IPlacementEngine.

◆ setWindowFullscreenFloat()

bool PhosphorScrollEngine::ScrollEngine::setWindowFullscreenFloat ( const QString & windowId,
bool floating,
const QString & screenId )

Compositor-driven: hold a strip tile out for its OWN fullscreen or return it, with a user float's slot memory but a PASSIVE announcement (no OSD, no free-geometry restore).

True when the engine holds, or has returned, this call's own float: a first hold of a strip tile, a repeat hold of a tile this call already holds, or a return of a tile this call held. False for an empty or untracked window, a window that floats under another owner, and a return of a window this call did not hold. The return puts the window back in its slot at its width, held to any committed floor it had (the hold does not end one), and re-runs the oversized verdict before the strip is laid out: a window whose minimum or committed floor no longer fits the work area floats again, as it would at open, and no batch configures its column first.

◆ setWindowHeight()

void PhosphorScrollEngine::ScrollEngine::setWindowHeight ( const WindowHeight & height,
const QString & screenId )

◆ setWindowRegistry()

void PhosphorScrollEngine::ScrollEngine::setWindowRegistry ( QObject * registry)
overridevirtual

Attach a window-class registry (QObject carrying WindowRegistry).

Engines qobject_cast to their concrete type internally.

Parameters
registryNot owned; must outlive this engine.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ snapAllWindows()

void PhosphorScrollEngine::ScrollEngine::snapAllWindows ( const PhosphorEngine::NavigationContext & ctx)
overridevirtual

Bring every unmanaged window on the screen back under this engine's placement (zones for snap, the strip for scrolling).

Stated layout-neutrally on purpose: an engine without a layout concept (layoutSupport() == LayoutSupport::None) still implements this intent.

Implements PhosphorEngine::IPlacementEngine.

◆ spanFocusedInDirection()

void PhosphorScrollEngine::ScrollEngine::spanFocusedInDirection ( const QString & direction,
const PhosphorEngine::NavigationContext & ctx )
overridevirtual

Zone spanning has no strip analogue; reports a "not_supported" span OSD like AutotileEngine so the shortcut is not a silent press.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ stashColumnForDesktopMove()

bool PhosphorScrollEngine::ScrollEngine::stashColumnForDesktopMove ( const QString & screenId,
const QStringList & windowIds,
int targetDesktop )

The column-preserving half of the move-column-to-workspace verb.

The verb moves each window to targetDesktop one by one, and each arrives there on its own, so without this record they would land as one column per window. This records the column holding windowIds on screenId's current strip as a strip-stash column under the context the windows will be adopted into, (screenId, targetDesktop, current activity), so the arrivals rejoin one column with its width, display, tab, height owner and per-tile heights. The column opens where a fresh arrival would (the screen's insert position, never into the active column), not at an index of a strip it never stood in.

Call it after focusedColumnWindows answered windowIds and BEFORE the first window is released, and only when targetDesktop runs scrolling on screenId: the record waits for arrivals this engine adopts. screenId is the exact strip key, as for focusedColumnWindows. windowIds keeps the caller's order and membership (the column as the user addressed it); windows no longer tracked on the strip are skipped.

The record carries no focus, view anchor or blueprint cursor: those belong to the strip the column leaves. An entry already stashed for the destination keeps its own, and the column is appended to it.

Returns false, recording nothing, when the screen does not scroll, none of windowIds is on its current strip, or the destination context is the current one (a sticky-pinned screen keys every desktop by its pin, so the windows would arrive back in the strip they left).

◆ stashStripForOutputMove()

bool PhosphorScrollEngine::ScrollEngine::stashStripForOutputMove ( const QString & sourceStripScreenId,
const QString & targetStripScreenId,
int desktop,
const QStringList & windowIds )

The column-preserving half of the move-workspace-to-monitor verb.

That verb keeps the workspace's desktop and moves its windows to another monitor, each arriving there on its own, so without this record the strip would be rebuilt as one column per window. This records every column of the strip on sourceStripScreenId for desktop, in strip order and with each column's hidden members (as stashColumnForDesktopMove carries them), cut down to windowIds, under (targetStripScreenId, desktop, current activity). The arrivals on the target strip rejoin their columns in the stashed order, with width, display, tab, height owner and per-tile heights. A fresh record also carries the strip's focus and blueprint spent-ness, since the whole strip moves; an entry already stashed for the destination keeps its own and gains the columns after its own. The view (anchor and pan) goes with the focus only when the destination context's work area has the source's main-axis length on the same axis, since the anchor is pixels into a strip whose column extents follow the work area. Otherwise the record carries no view (StashedStrip::viewCarried) and the centering policy places one around the restored focus.

Both ids are exact strip keys (a "<phys>/vs:N" id on a split monitor). A sticky pin on either screen keys that side by the pin. Call it after the sticky filter and BEFORE the first window is released, with only the ids that will actually move, and only when desktop runs scrolling on targetStripScreenId.

Returns false, recording nothing, for an empty or identical pair of ids, a desktop below 1, no strip state for the source, or no listed window on it.

◆ stateForScreen() [1/2]

const PhosphorEngine::IPlacementState * PhosphorScrollEngine::ScrollEngine::stateForScreen ( const QString & screenId) const
overridevirtual

◆ stateForScreen() [2/2]

PhosphorEngine::IPlacementState * PhosphorScrollEngine::ScrollEngine::stateForScreen ( const QString & screenId)
overridevirtual

Per-screen state object for the given screen.

May return nullptr if the engine does not manage the screen OR if per-screen state ownership has not yet been wired for that engine. Callers must not use a non-null return as a proxy for "engine manages this screen" — use isActiveOnScreen() for that check.

Implements PhosphorEngine::IPlacementEngine.

◆ stickyPinnedDesktopForScreen()

int PhosphorScrollEngine::ScrollEngine::stickyPinnedDesktopForScreen ( const QString & screenId) const
inlineoverridevirtual

The desktop this engine has pinned this screen to, or 0.

See the interface doc for why the gate compares the PIN and not the resolved key.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ stripAxisForScreen()

StripAxis PhosphorScrollEngine::ScrollEngine::stripAxisForScreen ( const QString & screenId) const

Which way screenId's strip runs, resolved live.

THE single source of the resolved axis for everything outside the layout path — the daemon publishes it to the effect, and the strip selector draws its miniature with it. Neither may derive an aspect ratio of its own: two independent derivations can disagree on a near-square monitor, and that disagreement is invisible in tests and intermittent in the field.

Resolves the work area LIVE. The engine subscribes to no ScreenManager signal, so answering from a snapshot taken at the last relayout would hand out the PRE-rotation axis at exactly the moment a rotation makes someone ask.

◆ stripContextChanged

void PhosphorScrollEngine::ScrollEngine::stripContextChanged ( const QString & screenId,
const QString & epoch,
const QString & debugLabel )
signal

The identity of the strip screenId is now showing has changed.

epoch is OPAQUE. It is derived from the same context key that keys strip storage, and a consumer may only compare it for equality with the last one it saw. It must never be parsed, ordered, or reconciled against the compositor's own notion of the current desktop or activity: a screen under a sticky pin resolves to the PINNED desktop, deliberately not the live one, so anything derived from KWin's current desktop disagrees with this engine forever on exactly those screens.

debugLabel is for logging and nothing else. Branching on it is the same mistake as parsing the epoch, wearing a different hat.

Announced INDEPENDENTLY of any geometry batch, which is the whole point: applyLayout emits on change only, so a switch onto a strip nobody touched produces no batch, and identity carried as a batch field would be silent in precisely the case a consumer most needs it.

Announced from setActiveScreens, for every screen in the resulting set; from the sticky-pin RELEASE path, which moves a screen's key without going through that push; and from applyDesktopRemap, for a screen whose strip a desktop-list change re-keyed. A pin ACQUIRE announces nothing because it pins to the desktop the key already resolves to. Desktop and activity switches therefore reach a consumer by way of the daemon's screen push rather than by the setters themselves: a key change with no such push behind it is not announced.

There is no bring-up seed. The epoch is announce-only, with nothing to read it from, so a consumer that attaches after a screen was announced holds no epoch for it and must treat its first announcement as a record rather than a comparison.

The value is deterministic across processes — the one-argument qHash seeds at 0 and never consults Qt's per-process hash seed — so a restarted daemon announces the same epoch for the same context. A consumer must not read a change out of a restart, nor assume one.

◆ stripModelForScreen()

ScrollStripModel PhosphorScrollEngine::ScrollEngine::stripModelForScreen ( const QString & screenId) const

The whole strip of screenId's current context as a strip MAP reads it (ScrollStripModel): every column, on and off screen, with its strip position and extent, the viewport's offset and extent on the same axis, and the active column.

Same precondition as visibleTiles: answers for the screen NAMED, with no operation-screen fallback. The params are resolved ONCE here and handed to ScrollStrip::stripModel, which runs one relayout, the cost discipline visibleTilesWithRects follows. A screen with no state yet (owned but never populated) answers an empty model carrying the screen's resolved axis and viewport, so a consumer can draw an empty strip; an unknown screen with no resolvable work area answers the default-constructed model.

◆ stripSnapshot()

ScrollStripSnapshot PhosphorScrollEngine::ScrollEngine::stripSnapshot ( const QString & screenId,
const QString & excludeWindowId = QString() ) const

Column-aware strip snapshot for the daemon's strip-mode drag popup.

One relayout pass, same cost discipline as visibleTilesWithRects. Resolves against the drag-insert preview's CAPTURED context key when a preview is live for screenId (same rule as computeDragInsertTargetAtPoint), else the current context — so the detached drag window is absent either way. excludeWindowId filters a drag window that has NOT been detached yet; it is consulted ONLY on the no-preview path (callers must pass only the window a live preview detached — any other id is silently ignored while a preview owns the screen). See the snapshot type's index contract in ScrollEngineTypes.h. Implemented in engine_snapshot.cpp.

◆ swapFocusedInDirection()

void PhosphorScrollEngine::ScrollEngine::swapFocusedInDirection ( const QString & direction,
const PhosphorEngine::NavigationContext & ctx )
overridevirtual

Swap the focused window with the adjacent window.

Implements PhosphorEngine::IPlacementEngine.

◆ switchFocusBetweenFloatingAndTiling()

void PhosphorScrollEngine::ScrollEngine::switchFocusBetweenFloatingAndTiling ( const QString & screenId)
overridevirtual

niri switch-focus-between-floating-and-tiling (IPlacementEngine override).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ tabIndicatorParamsForScreen()

TabIndicatorParams PhosphorScrollEngine::ScrollEngine::tabIndicatorParamsForScreen ( const QString & screenId) const

The tab-indicator geometry screenId resolves to: the configured values with any per-screen rule override layered on per property.

Public because the resolution has seven independent fall-back paths and is otherwise only observable through a relayout's resolved rects, which conflates it with the layout maths. Const and side-effect free.

◆ tabStripsChanged

void PhosphorScrollEngine::ScrollEngine::tabStripsChanged ( const QString & screenId,
const QString & stripsJson )
signal

Tab-indicator model for screenId, emitted when the resolved model changes (a relayout that produces an identical payload stays silent): a JSON array with one entry per tabbed column that actually resolves an indicator and is in view, or was in view before this batch's view slide (a DEPARTING column keeps its pills for the length of the outgoing leg) — {x, y, width, height (the INDICATOR's absolute px rect, not the column's), position (TabIndicatorPosition), activeIndex, tabs: [windowId, ...]}.

A column still in view whose every emitted tile parked is left out, since nothing it labels is on screen. Columns whose indicator is suppressed (the master switch off, or a single-tab column under hideWhenSingleTab) are simply absent, so a consumer never re-tests those conditions and cannot disagree with the relayout that sized the column around them. An empty array clears the screen's indicators. The daemon only relays this payload; the compositor enriches the window ids with titles and urgency and paints the pills itself.

◆ toggleColumnTabbed()

void PhosphorScrollEngine::ScrollEngine::toggleColumnTabbed ( const QString & screenId)

◆ toggleFocusedFloat()

void PhosphorScrollEngine::ScrollEngine::toggleFocusedFloat ( const PhosphorEngine::NavigationContext & ctx)
overridevirtual

Toggle the focused window between managed and floating.

Implements PhosphorEngine::IPlacementEngine.

◆ toggleMaximizeColumn()

bool PhosphorScrollEngine::ScrollEngine::toggleMaximizeColumn ( const QString & screenId,
const QString & windowId = QString() )

Toggle the maximized state of a column on screenId.

An empty windowId targets the ACTIVE column; a named window targets the column owning it and refuses when the strip does not hold it. Answers whether the strip CHANGED, like its twin below. A pure width verb: it moves no maximize bit (only the twin's declared state is mirrored onto KWin's).

◆ toggleMaximizeToEdges()

bool PhosphorScrollEngine::ScrollEngine::toggleMaximizeToEdges ( const QString & screenId,
const QString & windowId = QString() )

Toggle a column's maximize-to-edges state (full raw work area on both axes, gap-free; niri maximize-window-to-edges generalized to the column).

Addressing and return as toggleMaximizeColumn. A named window that is the active tile of a SHARED column is first expelled into its own column. This is the verb the compositor's maximize interception dispatches, and the KWin maximize bit mirrors THIS state alone: false means no batch is coming, so the effect puts KWin's bit back.

◆ toggleWindowedFullscreen()

void PhosphorScrollEngine::ScrollEngine::toggleWindowedFullscreen ( const QString & screenId)

Windowed fullscreen (niri toggle-windowed-fullscreen) on the active window: layout-neutral per-tile flag, see Tile::windowedFullscreen.

◆ toggleWindowFloat()

void PhosphorScrollEngine::ScrollEngine::toggleWindowFloat ( const QString & windowId,
const QString & screenId )
overridevirtual

Toggle between managed and floating.

Implements PhosphorEngine::IPlacementEngine.

◆ updateDragInsertPreview()

void PhosphorScrollEngine::ScrollEngine::updateDragInsertPreview ( const DragInsertTarget & target)
overridevirtual

Update the drop target for an active drag-insert preview.

An invalid target is IGNORED, never clamped — implementations keep the previous stored target (autotile's engine-local int form clamps instead; that contract does not cross this seam).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ updateStickyScreenPins()

void PhosphorScrollEngine::ScrollEngine::updateStickyScreenPins ( const PhosphorEngine::StickyPredicate & ,
PhosphorEngine::StickyPinPhase  )
overridevirtual

Pin screens whose managed windows are ALL sticky to their current desktop, unpinning (and migrating the state to the new desktop key) once a non-sticky window appears — the "virtualdesktopsonlyonprimary" contract AutotileEngine also implements: without the pin a desktop switch resolves a fresh key and the strip comes up empty while the sticky windows are still visible.

A screen that already holds a strip on another desktop is never pinned: that is a screen the user merely happens to be viewing with sticky windows on it, and once the membership pass has given a sticky window a column on two desktops the pin is redundant for it. See PhosphorEngine::StickyPinPhase.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ visibleTileNumberForWindow()

int PhosphorScrollEngine::ScrollEngine::visibleTileNumberForWindow ( const QString & screenId,
const QString & windowId ) const

windowId's zone number on screenId's current strip, or -1 when it is off-screen, a hidden tab, or untracked.

Convenience/test seam with no production caller today (like visibleTileRects above): every production number consumer walks visibleTiles and reads VisibleTile::zoneNumber directly, so this exists for callers that hold only a window id.

◆ visibleTileRects()

QVector< QRect > PhosphorScrollEngine::ScrollEngine::visibleTileRects ( const QString & screenId) const

The rects of visibleTiles — the plain absolute-pixel projection, in the same order.

Convenience only, and with no production caller today: every consumer wants the zone number alongside the rect, so they walk visibleTiles and read VisibleTile::zoneNumber rather than re-deriving an ordinal from this list's index. Kept for callers that want bare screen coordinates; the normalized twin is below.

◆ visibleTileRectsRelative()

QVector< QRectF > PhosphorScrollEngine::ScrollEngine::visibleTileRectsRelative ( const QString & screenId) const

visibleTileRects normalized to the FULL screen geometry (0.0–1.0 per axis) — the shape zone previews consume.

The tiles are clipped to the gap-inset work area, so the fractions show the panel gap; that is the same basis the daemon's own OSD card uses (its twin renorm of the absolute rects in stripzones.h) WHENEVER the screen rect resolves, so the settings thumbnail and the OSD draw the same shape. The D-Bus strip payload (scrollingadaptor.cpp) carries these rects, each paired with its zone number, through visibleTilesWithRects: where a layout switch shows the layout's zones, a scrolling screen shows what the strip actually looks like right now. Falls back to the work area as the basis only when no screen rect is resolvable — a KNOWN divergence from the OSD twin in that window (it falls back to QScreen::geometry() via the daemon's shared resolver, which this LGPL library cannot link), so during early startup the two surfaces can briefly disagree by the panel's share of the output. Self-heals on the next poll once the screen resolves. Same emptiness contract. Production reads the PAIRED form (visibleTilesWithRects, via the D-Bus strip payload in scrollingadaptor.cpp); this projection serves the test suites.

The pairing is index-wise and both walks run in the same synchronous call, so a caller reading this beside visibleTiles gets rects and numbers for the same tiles in the same order.

◆ visibleTiles()

QVector< VisibleTile > PhosphorScrollEngine::ScrollEngine::visibleTiles ( const QString & screenId) const

The visible tiles of screenId's current-context strip in zone- number order.

Not every on-screen window is here: hidden tabs of a tabbed column, minimized tiles, parked columns, and tiles whose intersection with the work area is EMPTY (a stack whose min heights overflow the work area resolves its tail beyond the work area's far cross edge) all carry no number and cannot be reached by a digit. Partially-visible columns are CLIPPED, not dropped: an arbitrarily thin sliver still carries its own number, because the cut-off edge is what tells the viewer the strip continues off-screen. Note the walk numbers by the STRIP rect clipped to the work area, while the APPLIED geometry may differ: the apply path clamps straddlers to the SCREEN edge and parks a remainder below its peek floor, so a barely-visible column can carry a number here while sitting parked — a digit press still works, because focusing re-anchors the view and scrolls it back in. Empty when the screen has no state, no visible tile, or no valid work area (unknown/removed screen, or outer gaps that swallowed it).

PRECONDITION, unlike the navigation verbs: this and its siblings do NO resolveOperationScreen fallback. They answer for the screen NAMED, so a caller passing a screen the engine does not manage gets an empty result rather than the active screen's strip — pass the same screen the verb will act on or the two halves of the address/action pair can describe different outputs.

Transient staleness: the walk relayouts WITHOUT updateViewForFocus, so between a work-area change (resolution, panels, outer gaps) and the next applyLayout it resolves against the pre-change view anchor. The window is the daemon's ~400ms geometry debounce plus the queued hop; it is self-healing (the next apply re-anchors) and reaches the settings poll, the OSD preview and a digit press landing inside it.

◆ visibleTilesWithRects()

QVector< VisibleTileWithRect > PhosphorScrollEngine::ScrollEngine::visibleTilesWithRects ( const QString & screenId) const

visibleTiles and visibleTileRectsRelative in a single resolve.

Reading the two separately costs TWO layoutParamsForScreen calls and two relayouts for one answer, and layoutParamsForScreen is not cheap — it resolves the per-screen override map and parses both preset vocabularies. The D-Bus strip payload is polled on a live timer while the Monitors state view is open, so that doubling is a recurring cost rather than a one-off. It also removes the count-mismatch guard the paired reads needed: one walk cannot disagree with itself.

◆ windowClosed()

void PhosphorScrollEngine::ScrollEngine::windowClosed ( const QString & windowId)
overridevirtual

A window was closed.

An implementation must drop the window from whichever state actually holds it, BACKGROUND contexts included, resolving through the stored key rather than the screen's current one. heldKeyForWindow answers across every context, so a close that only cleaned the current context would leave it answering a key for a window that is gone.

Implements PhosphorEngine::IPlacementEngine.

◆ windowFocused()

void PhosphorScrollEngine::ScrollEngine::windowFocused ( const QString & windowId,
const QString & screenId )
overridevirtual

A window gained focus (called when the compositor reports activation).

Named "focused" here because it's the engine's perspective; the D-Bus protocol and DaemonClient use "windowActivated" — same event.

Implements PhosphorEngine::IPlacementEngine.

◆ windowMinimumSize()

QSize PhosphorScrollEngine::ScrollEngine::windowMinimumSize ( const QString & windowId) const
overridevirtual

The window's declared minimum as a FRAME size (Tile::minWidth), from its strip tile, falling back to the FloatRestore entry while it is floated (or minimized — the effect reports minimize as a float).

The fallback matters at the cross-engine handoff, which queries this whatever state the window is in: answering 0x0 hands the receiving engine an unclamped window.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ windowMinSizeUpdated()

void PhosphorScrollEngine::ScrollEngine::windowMinSizeUpdated ( const QString & windowId,
int minWidth,
int minHeight )
overridevirtual

Update a window's minimum size after the initial windowOpened.

The compositor discovers a min size late for some clients (or the client raises it at runtime); engines that fit windows to slots re-validate their layout on a change. Default is a no-op for engines without a min-size model.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ windowOpened()

void PhosphorScrollEngine::ScrollEngine::windowOpened ( const QString & windowId,
const QString & screenId,
int minWidth,
int minHeight )
overridevirtual

A new window appeared on this engine's screen.

Implements PhosphorEngine::IPlacementEngine.

◆ windowsBeyondFocusScrollLimit()

QStringList PhosphorScrollEngine::ScrollEngine::windowsBeyondFocusScrollLimit ( const QString & screenId,
int maxScrollPercent ) const

The windows on screenId that focus-follows-mouse must REFUSE to focus under a cap of maxScrollPercent percent of the viewport's extent along the strip — niri's focus-follows-mouse max-scroll-amount.

A window is named when activating it would move the view further than the cap allows.

The daemon publishes the answer to the KWin effect, which owns focus-follows-mouse and cannot ask this question per pointer event.

100 or more is the "no cap" SENTINEL and answers empty without walking the strip, which is the shipped default and so the case worth short-circuiting. Read it as the sentinel it is rather than as a geometric claim: under CenterFocusedColumn::Always a step from a viewport-wide column to a narrow one costs more than one viewport (the recentring pays half of each column plus the gap), so a cap of exactly 100 is NOT equivalent to measuring against the viewport. Nothing depends on the two agreeing, but a future reader should not infer that they do.

Callers refuse on the answer, so every question this cannot answer — an unknown screen, an empty strip, a degenerate work area — comes back empty. Fully minimized columns are skipped rather than measured: they hold no strip extent, so the centering arms would answer about nothing, and their tiles are not focus targets under a pointer.

◆ windowsTiled

void PhosphorScrollEngine::ScrollEngine::windowsTiled ( const QString & tileRequestsJson)
signal

Batch of absolute pixel rects for the KWin effect, same JSON contract as AutotileEngine::windowsTiled.

The field list and semantics live in dbus/org.phosphor_works.Placement.Tiling.xml's TileRequestEntry annotation, which is the single source: an inline copy here named a handful of the fields actually emitted and drifted every time one was added, which is why no count is repeated here. Float transitions go out on the two float signals; this batch never carries release entries.


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