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

The pure scrolling-strip model: an ordered list of columns on an unbounded strip, viewed through a viewport of the work area's extent. More...

#include <PhosphorScrollEngine/ScrollStrip.h>

Classes

struct  ViewOverhang
 How far the view hangs past each end of the strip, in main-axis px: leading before the first column (a negative view offset) and trailing past the last offset that still ends on the strip. More...

Public Member Functions

 ScrollStrip ()=default
const QVector< Column > & columns () const
int columnCount () const
bool isEmpty () const
int activeColumnIndex () const
const Column * activeColumn () const
QString activeWindowId () const
 The focused window: the active tile of the active column, or empty.
int columnOfWindow (const QString &windowId) const
 Column index owning windowId, or -1.
bool containsWindow (const QString &windowId) const
QStringList windowsInOrder () const
 All windows in strip order (column order along the strip, then each column's stack order across it), including minimized tiles (their slot is part of the order contract).
int windowCount () const
bool insertWindow (const QString &windowId, const ColumnWidth &width, ColumnDisplay display, const ScrollLayoutParams &params, int minWidth=0, int minHeight=0, ScrollInsertPosition pos=ScrollInsertPosition::RightOfActive)
 Insert a new single-tile column for windowId at pos (default: immediately AFTER the active column along the strip, or at index 0 on an empty strip), focus it, and leave every other column untouched.
bool insertWindowIntoActiveColumn (const QString &windowId, const ColumnWidth &width, std::optional< ColumnDisplay > displayOverride, const ScrollLayoutParams &params, int minWidth=0, int minHeight=0)
 Insert windowId as a new tile at the END of the active column's stack (rule-driven "open consumed into the focused column").
bool insertWindowAt (int columnIndex, const QString &windowId, const ColumnWidth &width, ColumnDisplay display, const ScrollLayoutParams &params)
 Insert a restored single-tile column at columnIndex (clamped) — the persistence/restore path.
bool insertWindowIntoColumnAt (int columnIndex, int tileIndex, const QString &windowId, const ScrollLayoutParams &params, int minWidth=0, int minHeight=0, std::optional< ColumnDisplay > displayOverride=std::nullopt)
 Re-insert windowId as a TILE of the existing column at columnIndex (float/minimize round-trip of a stacked tile), at tileIndex clamped into the stack.
bool removeWindow (const QString &windowId, const ScrollLayoutParams &params)
 Remove windowId; a column left empty closes up.
bool setWindowMinimized (const QString &windowId, bool minimized, const ScrollLayoutParams &params)
 Mark a tile minimized (kept in order, excluded from layout) or restore it.
bool isWindowMinimized (const QString &windowId) const
bool setWindowMinimumSize (const QString &windowId, int minWidth, int minHeight)
 Update a tile's stored minimum size. Returns true when it changed.
QSize windowMinimumSize (const QString &windowId) const
 The tile's minimum frame size (Tile::minWidth), or 0x0 when untracked.
bool focusColumn (int columnIndex, const ScrollLayoutParams &params)
 Focus a column by index (clamped; active tile within it unchanged).
bool focusAdjacentColumn (int delta, const ScrollLayoutParams &params)
 Focus the adjacent non-fully-minimized column. delta is -1/+1.
bool focusFirstColumn (const ScrollLayoutParams &params)
bool focusLastColumn (const ScrollLayoutParams &params)
bool focusAdjacentTile (int delta)
 Focus the previous/next non-minimized tile within the active column, stopping at either end (ScrollEngine::cycleTab wraps instead, by falling back to focusTileAtEnd when this refuses).
bool focusTileAtEnd (bool last)
 Focus the first (last false) or last non-minimized tile of the active column (niri focus-window-top/bottom).
bool focusTileByOrdinal (int ordinal)
 Focus the ordinal'th (1-based) non-minimized tile of the active column, which is that ordinal's tab when the column is tabbed.
bool focusWindow (const QString &windowId, const ScrollLayoutParams &params)
 Make windowId the active tile of its (newly active) column.
bool moveActiveColumn (int delta, const ScrollLayoutParams &params)
 Swap the active column with its neighbour. delta is -1/+1.
bool moveActiveColumnTo (int target, const ScrollLayoutParams &params)
 Move the active column directly to target (one list move + one reanchor — a positional move must not pay per-step swap costs).
bool moveColumnTo (int from, int to, const ScrollLayoutParams &params)
 Move the column at strip index from to strip index to and make it the active column (a placement map dragging one column past the others).
bool moveActiveColumnToFirst (const ScrollLayoutParams &params)
bool moveActiveColumnToLast (const ScrollLayoutParams &params)
bool moveActiveTile (int delta)
 Reorder the active tile within its column by delta positions.
bool consumeWindowIntoColumn (const ScrollLayoutParams &params)
 Pull the next column's active tile onto the END of the active column's stack (niri consume-window-into-column).
bool expelWindowFromColumn (const ScrollLayoutParams &params)
 Push the active tile out into its own new column immediately AFTER the current one along the strip (niri expel-window-from-column).
bool consumeOrExpel (int delta, const ScrollLayoutParams &params)
 niri consume-or-expel: when the active tile is alone in its column it is consumed into the neighbour column in delta's direction (appended); otherwise it is expelled into its own new column on that side.
bool takeWindow (const QString &windowId, const ScrollLayoutParams &params)
 Remove windowId with no focus policy beyond index fixups — the cross-context transfer / float path (the caller re-homes the window).
bool setActiveColumnWidth (const ColumnWidth &width)
 Set the active column's width intent, verbatim, dropping a maximize-to-edges override (the drop alone is a change).
bool cycleActiveColumnPresetWidth (int delta, const ScrollLayoutParams &params)
 Cycle the active column through the preset width list.
bool adjustActiveColumnWidth (qreal deltaPercent, const ScrollLayoutParams &params)
 Adjust the active column's width by deltaPercent of the work area's MAIN extent (niri set-column-width "+10%"/"-10%").
bool toggleMaximizeActiveColumn (const ScrollLayoutParams &params)
 Full work-area MAIN extent, still tiled (niri maximize-column).
bool toggleMaximizeColumnForWindow (const QString &windowId, const ScrollLayoutParams &params)
 The same verb aimed at the column OWNING windowId rather than at the active one.
bool toggleMaximizeToEdgesActiveColumn (const ScrollLayoutParams &params)
 Toggle the active column's maximize-to-edges state (niri maximize-window-to-edges, generalized to the column): full raw work area on both axes, gap-free (Column::maximizedToEdges carries the contract).
bool toggleMaximizeToEdgesForWindow (const QString &windowId, const ScrollLayoutParams &params)
 The same verb aimed at the column OWNING windowId, for the compositor's maximize interception — toggleMaximizeColumnForWindow's doc carries why the named form is load-bearing.
bool setMaximizedToEdgesForWindow (const QString &windowId, bool maximized)
 Restore-path setter for the column owning windowId: a stash claim re-asserting the state it captured, not a user verb, so none of the toggle's addressing or feedback applies.
bool expandActiveColumnToAvailableWidth (const ScrollLayoutParams &params)
 Grow the active column into the on-screen MAIN-axis space not taken by the FULLY visible columns at the current view (niri expand-column-to-available-width).
bool equalizeVisibleColumnWidths (const ScrollLayoutParams &params)
 Give every visible column an equal share of the work area's MAIN extent (Karousel equalize; niri has no equivalent).
bool minimizeActiveColumnWidth (const ScrollLayoutParams &params)
 The active column at its narrowest: the smallest preset, or MinColumnWidthFraction when the preset list is empty (Karousel minimize-width; the empty-list arm is reachable only from a test or an embedder, since the engine never hands down an empty vocabulary).
bool resetToDefaults (const std::optional< ColumnWidth > &defaultWidth, const std::optional< WindowHeight > &defaultHeight, ColumnDisplay defaultDisplay, const ScrollLayoutParams &params)
 Every column back to defaultWidth and defaultDisplay, and every tile back to defaultHeight: the scrolling half of the Retile shortcut, whose other modes re-apply their layout the same way.
bool setActiveWindowHeight (const WindowHeight &height)
 Set the active tile's height intent, verbatim.
bool cycleActiveWindowPresetHeight (int delta, const ScrollLayoutParams &params)
 Cycle the active tile through the preset height list.
bool adjustActiveWindowHeight (qreal deltaPercent, const ScrollLayoutParams &params)
 Adjust the active tile's height by deltaPercent of the work area's CROSS extent.
bool toggleMaximizeActiveWindowHeight (const ScrollLayoutParams &params)
 Toggle the active tile between filling its column's cross budget and the height it had before, falling back to the even auto-split when it had none of its own.
bool minimizeActiveWindowHeight (const ScrollLayoutParams &params)
 The active tile at its shortest: the smallest preset height, or MinWindowHeightFraction of the work area's cross extent when the preset list is empty.
bool expandActiveWindowToAvailableHeight (const ScrollLayoutParams &params)
 Grow the active tile into the empty cross space left in its column.
bool equalizeActiveColumnHeights ()
 Back to the even auto-split for EVERY tile in the active column: the height twin of equalizeVisibleColumnWidths.
bool reconcileWindowSize (const QString &windowId, const QSize &ackedSize, bool mainChanged, bool crossChanged, const ScrollLayoutParams &params)
 Record the size a client/user resize actually settled on.
int windowColumnMainExtentPx (const QString &windowId, const ScrollLayoutParams &params) const
 The extent ALONG the strip of the column holding windowId under params, exactly as the relayout resolves it (columnExtentPx: the intent raised to the column's floors, capped at the work area, or the raw extent of a maximized-to-edges column), or -1 when this strip does not hold the window.
int windowTileCrossExtentPx (const QString &windowId, const ScrollLayoutParams &params) const
 The extent ACROSS the strip of windowId's tile under params, exactly as the relayout resolves it (the stack's split with its floors, or a tabbed column's content rect), or -1 when this strip lays no tile out for the window (it does not hold it, or the tile is minimized).
int tileCrossCapacityPx (const QString &windowId, const ScrollLayoutParams &params) const
 The most windowId's column can ever give its tile ACROSS the strip under params while its siblings keep their own floors: for a stack, the column's cross budget (the work area less the gaps between its visible tiles) less every other visible tile's floor across (tileMinCrossPx, a pixel at least); for a tabbed column, its cross extent less the indicator's cross reservation, since every tab shares one rect.
bool toggleActiveColumnTabbed ()
 Toggle the active column between Normal and Tabbed presentation.
bool toggleActiveWindowedFullscreen ()
 Toggle windowed fullscreen on the active tile of the active column.
bool setWindowedFullscreen (const QString &windowId, bool on)
 Direct flag write for windowId (any tile, not just the active one) — compositor-driven reconciliation clears through this, and the mode-round-trip restore path re-applies stashed flags through it.
bool isWindowedFullscreen (const QString &windowId) const
bool setWindowHeightIntent (const QString &windowId, const WindowHeight &height)
 Direct height-intent write for windowId (any tile, not just the active one).
bool restateWindowHeightIntent (const QString &windowId, const WindowHeight &height)
 setWindowHeightIntent for a REMEMBERED intent re-stated on the way back into a column (an unfloat, a cancelled or dropped drag, a migration): the intent is written the same way, but a tabbed column's extent owner is left as the column held it before the write, so a non-Auto height does not take the column from the tab that sizes it.
WindowHeight windowHeightIntent (const QString &windowId) const
 The height intent windowId's tile carries, or a default-constructed (Auto) one for an unknown window.
bool setTabbedHeightOwner (const QString &windowId)
 Make windowId's tab the one whose height decides its TABBED column's cross extent.
QVector< int > visibleColumnIndices (const ScrollLayoutParams &params) const
 Strip indices of the columns currently intersecting the viewport, in strip order — a viewport-intersection helper, NOT the zone-number space.
QVector< int > fullyVisibleColumnIndices (const ScrollLayoutParams &params) const
 Strip indices of the columns lying ENTIRELY inside the viewport, in strip order — the stricter twin of visibleColumnIndices, and the one expandActiveColumnToAvailableWidth and centerVisibleColumns walk.
bool isCenteringActiveColumn (const ScrollLayoutParams &params) const
 Whether the layout policy pins the ACTIVE column to the middle of the viewport, so its on-screen position is not the strip's to choose.
int rotateVisibleColumns (bool clockwise, const ScrollLayoutParams &params)
 Rotate the window contents of the VISIBLE columns through their slots (clockwise = every stack shifts one slot ALONG the strip, towards its end, and the last visible wraps to the first).
int viewAnchor () const
 The stored active-relative view anchor (see class doc).
bool viewDetached () const
 Whether an explicit pan owns the view instead of the centering policy (see the class doc).
void setViewDetached (bool detached)
 The other half of restoreViewAnchor: re-assert a captured detachment.
void restoreViewAnchor (int anchor, const ScrollLayoutParams &params)
 Restore a previously captured view anchor, RAW: a centered anchor implies an out-of-range derived viewOffset by design (the same shape centerActiveColumn stores), so no clamp is applied here — later structural inserts re-clamp when the strip cannot honour the view.
void reanchorForDropCommit (int oldViewOffset, const ScrollLayoutParams &params)
 Drag-drop re-anchor (ScrollEngine::commitDragInsertPreview): land the just-dropped ACTIVE column at the on-screen position the drop indicator promised — its strip position minus oldViewOffset, the view offset captured BEFORE the commit's insert — then move the view the MINIMUM that makes the column fully visible (the Never fit).
void clampViewIntoStrip (const ScrollLayoutParams &params)
 Drag-begin settle (ScrollEngine::beginDragInsertPreview): after the detach take shortens the strip, pull a view that now hangs past the TRAILING strip edge back over real columns.
ViewOverhang viewOverhang (const ScrollLayoutParams &params) const
void clampViewOverhang (const ScrollLayoutParams &params, int keepLeading, int keepTrailing)
 Pull the view back toward the strip until it hangs past the leading end by at most keepLeading px and past the trailing end by at most keepTrailing px (each 0 for none): a both-edge clamp that keeps a measured overhang the caller wants to survive.
void updateViewForFocus (const ScrollLayoutParams &params)
 Re-apply the centering policy to the current active column (settings change / work-area change) using the current anchor as the "no scroll" baseline.
bool centerActiveColumn (const ScrollLayoutParams &params)
 Center the active column in the view (niri center-column).
bool centerVisibleColumns (const ScrollLayoutParams &params)
 Center the span of FULLY visible columns in the view (niri center-visible-columns).
bool scrollViewBy (int delta, const ScrollLayoutParams &params)
 Scroll the view delta pixels forward ALONG THE STRIP (negative scrolls back towards its start) WITHOUT changing focus, clamped to the strip's ends.
int predictedFocusScrollPx (int columnIndex, const ScrollLayoutParams &params) const
 How far the view WOULD move, in pixels along the strip, if column columnIndex became the active one right now.
ResolvedStrip relayout (const ScrollLayoutParams &params) const
 Resolve every non-minimized tile's absolute pixel rect against params.
ScrollStripModel stripModel (const ScrollLayoutParams &params) const
 The whole strip as a renderer of a strip MAP reads it: every column's strip position and main extent, every tile's cross extent, the viewport's offset and extent on the same axis, and the active column (ScrollStripModel documents each field).
bool stripFitsViewport (const ScrollLayoutParams &params) const
 True when the whole strip already fits the viewport, i.e.
bool stripSettledInViewport (const ScrollLayoutParams &params) const
 stripFitsViewport AND the derived view offset is settled inside [0, stripExtent - viewport] — i.e.

Static Public Member Functions

static int tabbedMainReservationPx (const Column &c, const ScrollLayoutParams &params)
 Pixels the tab indicator takes out of column c ALONG the strip: the difference between the column's main extent and the one its tiles are offered.
static int tabbedCrossReservationPx (const Column &c, const ScrollLayoutParams &params)
 Pixels the tab indicator takes out of column c ACROSS the strip, the cross-axis twin of tabbedMainReservationPx.
static int resolveColumnWidthPx (const ColumnWidth &width, const ScrollLayoutParams &params)
 The pixel MAIN extent width resolves to under params (gap-aware proportions, preset lookup; no min-extent clamp).

Detailed Description

The pure scrolling-strip model: an ordered list of columns on an unbounded strip, viewed through a viewport of the work area's extent.

This class is deliberately free of engine/compositor dependencies (Qt Core value types only) so the full behavioural matrix is unit-testable in isolation. The one invariant everything here serves: INSERTING OR REMOVING A COLUMN NEVER RESIZES ANOTHER COLUMN. Only the viewport moves.

Coordinates

Strip coordinates run ALONG THE MAIN AXIS from the first column's leading edge at 0. The viewport is the work area; its leading edge sits at viewOffset in strip coordinates. The view anchor is stored RELATIVE TO THE ACTIVE COLUMN (viewAnchor = active column's leading edge position within the viewport), so structural changes before the focus along the strip never make the focused window drift — viewOffset is derived, never stored.

View detachment

Because the anchor is active-relative, the centering policy owns the view: updateViewForFocus re-derives it at the top of every applyLayout, so a view the POLICY did not choose cannot survive a layout pass. That is right for every mutator except the ones that place the view on purpose. scrollViewBy moves the view because the user pointed somewhere, not because focus, structure or policy changed, and a pan the next layout pass undoes is not a pan at all.

So a successful scrollViewBy DETACHES the view, and updateViewForFocus then leaves the anchor entirely alone — not even a re-clamp, for the reason that function documents. equalizeVisibleColumnWidths detaches too: it positions the group edge to edge on purpose, and a policy that re-centered the active column afterwards would clip the group again on the next pass. reanchorForDropCommit detaches outside the centering policies, because a drop owns the view the way a pan does. Any focus-driven or structural re-anchor (every reanchorAfterFocusChange caller: the COLUMN-focus and move verbs, insertWindow, insertWindowIntoColumnAt, the expel verbs, a removal that has to scroll focus back into view), an active column that vanished, the first column of an empty strip, the Always policy's own re-centering, or either centering verb re-attaches it and the policy takes the view back. So does a successful width verb on the ACTIVE column (setActiveColumnWidth, the preset cycle, adjust, both maximize toggles, expand, minimize), because a column resized under a fixed view can be left mostly off screen. That includes the maximize-to-edges toggle the compositor's maximize interception dispatches when it lands on the active column, in either direction and whether the user or the client asked, since the column's width changes either way. A successful resetToDefaults re-attaches too, whatever it reset, because it puts the whole layout back. A bystander's removal that leaves focus where it was does not, and neither does reconcileWindowSize, whose resize the user released exactly where they wanted it.

The TILE-focus ops here never re-anchor, so ScrollEngine clears the latch through setViewDetached on their behalf: the tile-focus verb macro behind cycleTab, focusTab, focusWindowTop and focusWindowBottom; the cross-axis leg of a directional focus press; and ScrollEngine::windowFocused, when a compositor report names the window the strip already calls active (it is refused here, or moves a tile inside the active column, so it reaches no re-anchor). The next layout pass then lets the policy answer. Detachment travels with the anchor through the mode-round-trip stash and the persisted blob for the same reason the anchor does: restoring the position while dropping the detachment hands the view straight back to the policy that would move it.

Naming exemption

The public verbs below keep their physical width/height spellings (setActiveColumnWidth, adjustActiveWindowHeight, WindowHeight, and their siblings) because they are shipped API carrying niri's own vocabulary. Throughout this header width reads as the column's MAIN extent (along the strip) and height as the tile's CROSS extent (across it), whichever way the strip actually runs. StripAxis's role-naming rule governs NEW internals; it does not ask for these names to be rewritten.

Mutators that can change which column is focused (or shift pixel positions under the anchor) take the current ScrollLayoutParams so they can keep the view anchored / apply the center-focused-column policy at the mutation site. Structural mutators return true when they changed anything; the owning engine relayouts and applies geometry afterwards.

Constructor & Destructor Documentation

◆ ScrollStrip()

PhosphorScrollEngine::ScrollStrip::ScrollStrip ( )
default

Member Function Documentation

◆ activeColumn()

const Column * PhosphorScrollEngine::ScrollStrip::activeColumn ( ) const

◆ activeColumnIndex()

int PhosphorScrollEngine::ScrollStrip::activeColumnIndex ( ) const
inline

◆ activeWindowId()

QString PhosphorScrollEngine::ScrollStrip::activeWindowId ( ) const

The focused window: the active tile of the active column, or empty.

If that tile is MINIMIZED it falls back to the column's first non-minimized tile, so this can name a different window than activeColumn()->activeTileIdx points at. The mutating verbs (moveActiveTile, expelWindowFromColumn, setActiveWindowHeight, consumeOrExpel) all act on activeTileIdx, so a caller pairing this accessor with one of them could report a window the operation did not touch. Not reachable in production today, where the daemon models minimize as float and a minimized window is not a strip tile at all.

The height SIZING verbs (the preset cycle, adjust, maximize, minimize and expand) are not on that list: each measures through activeTileCrossPx, which resolves activeTileIdx's tile from a relayout and answers -1 when it is minimized, so they refuse rather than act on a window this accessor did not name.

◆ adjustActiveColumnWidth()

bool PhosphorScrollEngine::ScrollStrip::adjustActiveColumnWidth ( qreal deltaPercent,
const ScrollLayoutParams & params )

Adjust the active column's width by deltaPercent of the work area's MAIN extent (niri set-column-width "+10%"/"-10%").

Measured from the RENDERED extent rather than the bare intent, and floored at the greater of MinColumnWidthFraction and the column's own floor (columnMinExtentPx: its frame minimum and any committed floor, which drop out while respectMinimumSize is off, the same way the client half does for the height verb), so a repeated shrink stops at the floor instead of burying an ever smaller intent under it. Refuses when the target lands on the current extent, so a column already rendering below the floor refuses a shrink rather than growing. A non-finite deltaPercent refuses, and a finite one is bounded to ±100 (a larger step clamps to the same extent).

◆ adjustActiveWindowHeight()

bool PhosphorScrollEngine::ScrollStrip::adjustActiveWindowHeight ( qreal deltaPercent,
const ScrollLayoutParams & params )

Adjust the active tile's height by deltaPercent of the work area's CROSS extent.

The current height is read off a fresh relayout, since an Auto tile only gets a pixel value from the whole column distribution, and the result is floored the way adjustActiveColumnWidth floors its width (MinWindowHeightFraction, raised to the tile's floor across while respectMinimumSize is on: its frame minimum and any committed cross floor, activeWindowHeightFloorPx). A TABBED column adjusts too, in the same column-extent space the cycle measures in. deltaPercent is refused and bounded the way adjustActiveColumnWidth's is.

◆ centerActiveColumn()

bool PhosphorScrollEngine::ScrollStrip::centerActiveColumn ( const ScrollLayoutParams & params)

Center the active column in the view (niri center-column).

Returns true when the anchor actually moved.

◆ centerVisibleColumns()

bool PhosphorScrollEngine::ScrollStrip::centerVisibleColumns ( const ScrollLayoutParams & params)

Center the span of FULLY visible columns in the view (niri center-visible-columns).

Falls back to centerActiveColumn when no column is fully visible. Returns true when the anchor actually moved.

◆ clampViewIntoStrip()

void PhosphorScrollEngine::ScrollStrip::clampViewIntoStrip ( const ScrollLayoutParams & params)

Drag-begin settle (ScrollEngine::beginDragInsertPreview): after the detach take shortens the strip, pull a view that now hangs past the TRAILING strip edge back over real columns.

removeWindowInternal deliberately leaves that dead space on an ordinary close; during a drag hold it is what the user must aim a drop at, so the begin settle reclaims it. Trailing edge ONLY: a leading overhang is how the centering mutators deliberately express a centered short strip, and a view already in range is untouched. The detach latch is left alone — a pan still owns a clamped view.

◆ clampViewOverhang()

void PhosphorScrollEngine::ScrollStrip::clampViewOverhang ( const ScrollLayoutParams & params,
int keepLeading,
int keepTrailing )

Pull the view back toward the strip until it hangs past the leading end by at most keepLeading px and past the trailing end by at most keepTrailing px (each 0 for none): a both-edge clamp that keeps a measured overhang the caller wants to survive.

The detach latch is left alone, as clampViewIntoStrip leaves it.

◆ columnCount()

int PhosphorScrollEngine::ScrollStrip::columnCount ( ) const
inline

◆ columnOfWindow()

int PhosphorScrollEngine::ScrollStrip::columnOfWindow ( const QString & windowId) const

Column index owning windowId, or -1.

◆ columns()

const QVector< Column > & PhosphorScrollEngine::ScrollStrip::columns ( ) const
inline

◆ consumeOrExpel()

bool PhosphorScrollEngine::ScrollStrip::consumeOrExpel ( int delta,
const ScrollLayoutParams & params )

niri consume-or-expel: when the active tile is alone in its column it is consumed into the neighbour column in delta's direction (appended); otherwise it is expelled into its own new column on that side.

delta is -1 (towards the strip's start) / +1 (towards its end).

◆ consumeWindowIntoColumn()

bool PhosphorScrollEngine::ScrollStrip::consumeWindowIntoColumn ( const ScrollLayoutParams & params)

Pull the next column's active tile onto the END of the active column's stack (niri consume-window-into-column).

◆ containsWindow()

bool PhosphorScrollEngine::ScrollStrip::containsWindow ( const QString & windowId) const
inline

◆ cycleActiveColumnPresetWidth()

bool PhosphorScrollEngine::ScrollStrip::cycleActiveColumnPresetWidth ( int delta,
const ScrollLayoutParams & params )

Cycle the active column through the preset width list.

delta -1/+1. Entry follows niri's rule (cyclePresetIndexByExtent): a forward press takes the narrowest preset WIDER than what the column renders at and wraps to the narrowest of all when nothing is wider; a backward press takes the widest preset narrower and wraps to the widest of all, so every entry is reachable in both directions even when the vocabulary was typed out of size order. Measured from the RENDERED extent, so a column held at its floor (a frame minimum or a committed floor, columnMinExtentPx) enters where it looks like it should, and a press whose entry would still render at that same extent refuses rather than writing an intent the floor hides.

◆ cycleActiveWindowPresetHeight()

bool PhosphorScrollEngine::ScrollStrip::cycleActiveWindowPresetHeight ( int delta,
const ScrollLayoutParams & params )

Cycle the active tile through the preset height list.

delta -1/+1. Entry follows the same niri rule the width cycle uses (nearest entry TALLER going forward, nearest shorter going back, wrapping at each end), measured off a fresh relayout so an AUTO tile enters the cycle at what it currently renders rather than always at the first entry. A TABBED column cycles too, in two steps: the press first CLAIMS extent ownership for the shown tab, and the OWNER's intent then sizes the whole column (tabbedColumnCrossPx), so the press moves the column's cross extent. The measurement then reads the column rather than the tile, since the indicator's reservation sits between the two.

◆ equalizeActiveColumnHeights()

bool PhosphorScrollEngine::ScrollStrip::equalizeActiveColumnHeights ( )

Back to the even auto-split for EVERY tile in the active column: the height twin of equalizeVisibleColumnWidths.

Auto IS the even share, so unlike the width verb this one names the split rather than computing it, and it needs no params.

◆ equalizeVisibleColumnWidths()

bool PhosphorScrollEngine::ScrollStrip::equalizeVisibleColumnWidths ( const ScrollLayoutParams & params)

Give every visible column an equal share of the work area's MAIN extent (Karousel equalize; niri has no equivalent).

Visible on visibleColumnIndices' terms: every column whose strip span intersects the viewport joins the split, a column clipped by either edge included. That is the strip model's answer, so a straddler the engine's edge clamp parks for showing too thin a sliver joins as well and comes back as a full share. Written as Fixed pixels like adjustActiveColumnWidth, and the remainder of the division goes to the last column not held at its floor, so the group still tiles the viewport edge to edge. A column whose floor (columnMinExtentPx: its minimum size or a committed floor) exceeds its share keeps that floor and the rest share what is left. The group's lead column lands AT the viewport's lead edge: the anchor is re-derived after the rewrite so a column ahead of the active one growing does not slide the group under the active column, and a column clipped at either edge comes fully into view. A group whose shares already match but which is not flush at the lead edge (a small pan, or a centering policy re-centering it) is brought flush, and that alone is a change. The view is then DETACHED like a pan's (see the class doc), so the centering policy does not undo the edge-to-edge position on the next pass and a second press finds nothing to change. Refuses when fewer than two columns are visible, when the active column is not one of them, when the gaps between the group leave less than a pixel per column, when the floors alone fill the viewport, when a share would fall below MinColumnWidthFraction of the work area, or when every extent is already what it would become and the group is already flush.

◆ expandActiveColumnToAvailableWidth()

bool PhosphorScrollEngine::ScrollStrip::expandActiveColumnToAvailableWidth ( const ScrollLayoutParams & params)

Grow the active column into the on-screen MAIN-axis space not taken by the FULLY visible columns at the current view (niri expand-column-to-available-width).

Fully visible on fullyVisibleColumnIndices' terms, which is niri's accounting: a column clipped by either viewport edge is not counted, so the expansion reclaims its on-screen pixels and pushes it out of view. Refuses when the active column is not itself fully visible (there is no meaningful answer for a straddler), and when the column already fills the viewport. After a width write the anchor is re-derived so the group's lead column sits at the viewport's lead edge (the equalizeVisibleColumnWidths rule): the grown group then fills the viewport edge to edge and a lead-edge straddler leaves the view.

Two cases route through toggleMaximizeActiveColumn instead of writing Fixed pixels, both niri's: a centering policy that pins the active column to the middle (the column's position is not ours to choose, so "fill what is left" has no stable answer), and an active column that is the ONLY fully visible one (the result is full width, and going through the toggle leaves the user a way back out of it).

The centering branch is taken BEFORE the straddling-active refusal, so under a centering policy a straddling active column maximizes rather than refusing: the policy already owns that column's position, which is the whole reason the branch exists.

◆ expandActiveWindowToAvailableHeight()

bool PhosphorScrollEngine::ScrollStrip::expandActiveWindowToAvailableHeight ( const ScrollLayoutParams & params)

Grow the active tile into the empty cross space left in its column.

The height twin of expandActiveColumnToAvailableWidth. Empty space inside a column exists only when no tile is Auto: an Auto tile absorbs the leftover by weight in the relayout, so with one present the measurement below finds nothing to claim and the verb refuses.

One case routes through toggleMaximizeActiveWindowHeight rather than writing Fixed pixels, the expand-column verb's rule: the active tile is the only visible one in its column (or the column is tabbed, where every tab is committed at the column's own rect and there is no leftover WITHIN it), so the result is the whole budget and going through the toggle leaves a way back out.

◆ expelWindowFromColumn()

bool PhosphorScrollEngine::ScrollStrip::expelWindowFromColumn ( const ScrollLayoutParams & params)

Push the active tile out into its own new column immediately AFTER the current one along the strip (niri expel-window-from-column).

◆ focusAdjacentColumn()

bool PhosphorScrollEngine::ScrollStrip::focusAdjacentColumn ( int delta,
const ScrollLayoutParams & params )

Focus the adjacent non-fully-minimized column. delta is -1/+1.

◆ focusAdjacentTile()

bool PhosphorScrollEngine::ScrollStrip::focusAdjacentTile ( int delta)

Focus the previous/next non-minimized tile within the active column, stopping at either end (ScrollEngine::cycleTab wraps instead, by falling back to focusTileAtEnd when this refuses).

delta -1/+1.

◆ focusColumn()

bool PhosphorScrollEngine::ScrollStrip::focusColumn ( int columnIndex,
const ScrollLayoutParams & params )

Focus a column by index (clamped; active tile within it unchanged).

◆ focusFirstColumn()

bool PhosphorScrollEngine::ScrollStrip::focusFirstColumn ( const ScrollLayoutParams & params)

◆ focusLastColumn()

bool PhosphorScrollEngine::ScrollStrip::focusLastColumn ( const ScrollLayoutParams & params)

◆ focusTileAtEnd()

bool PhosphorScrollEngine::ScrollStrip::focusTileAtEnd ( bool last)

Focus the first (last false) or last non-minimized tile of the active column (niri focus-window-top/bottom).

False when already there.

◆ focusTileByOrdinal()

bool PhosphorScrollEngine::ScrollStrip::focusTileByOrdinal ( int ordinal)

Focus the ordinal'th (1-based) non-minimized tile of the active column, which is that ordinal's tab when the column is tabbed.

Like the sibling tile-focus verbs it is NOT gated on the display mode, so it addresses the stack the same way. False when the column has no such tile or it is already the active one.

◆ focusWindow()

bool PhosphorScrollEngine::ScrollStrip::focusWindow ( const QString & windowId,
const ScrollLayoutParams & params )

Make windowId the active tile of its (newly active) column.

Externally-driven focus (compositor activation). Returns false when untracked or already the focused window.

◆ fullyVisibleColumnIndices()

QVector< int > PhosphorScrollEngine::ScrollStrip::fullyVisibleColumnIndices ( const ScrollLayoutParams & params) const

Strip indices of the columns lying ENTIRELY inside the viewport, in strip order — the stricter twin of visibleColumnIndices, and the one expandActiveColumnToAvailableWidth and centerVisibleColumns walk.

A column clipped by either edge is excluded, which is what lets centerVisibleColumns leave it out of the span, and lets expandActiveColumnToAvailableWidth reclaim a straddler's pixels the way niri does. Zero-extent (fully minimized) columns carry no strip position and are skipped, matching stripExtentPx.

◆ insertWindow()

bool PhosphorScrollEngine::ScrollStrip::insertWindow ( const QString & windowId,
const ColumnWidth & width,
ColumnDisplay display,
const ScrollLayoutParams & params,
int minWidth = 0,
int minHeight = 0,
ScrollInsertPosition pos = ScrollInsertPosition::RightOfActive )

Insert a new single-tile column for windowId at pos (default: immediately AFTER the active column along the strip, or at index 0 on an empty strip), focus it, and leave every other column untouched.

The view scrolls only as the centering policy requires. Returns false when already present. IntoActiveColumn is NOT handled here — the engine routes it through insertWindowIntoActiveColumn so the strip's two insert verbs stay distinct; passed anyway, it degrades to RightOfActive.

◆ insertWindowAt()

bool PhosphorScrollEngine::ScrollStrip::insertWindowAt ( int columnIndex,
const QString & windowId,
const ColumnWidth & width,
ColumnDisplay display,
const ScrollLayoutParams & params )

Insert a restored single-tile column at columnIndex (clamped) — the persistence/restore path.

Does not change focus, WITH ONE EXCEPTION: on an EMPTY strip the new column becomes the active one, because a strip with columns and no focus has no valid state to be in. The asymmetry is load-bearing for the restore paths, which lean on the first arrival taking the focus and on every later one leaving it alone until the stashed focus is re-asserted. NOTE: carries no min-size parameters; callers that know the window's minimum must follow up with setWindowMinimumSize (the open/restore/crossing sites all do). params re-clamps the view anchor after the positional insert (an insert BEFORE the active column along the strip grows it without moving the active column, and an unclamped anchor can strand the view past the strip end — the mode-transition seed bug).

◆ insertWindowIntoActiveColumn()

bool PhosphorScrollEngine::ScrollStrip::insertWindowIntoActiveColumn ( const QString & windowId,
const ColumnWidth & width,
std::optional< ColumnDisplay > displayOverride,
const ScrollLayoutParams & params,
int minWidth = 0,
int minHeight = 0 )

Insert windowId as a new tile at the END of the active column's stack (rule-driven "open consumed into the focused column").

Falls back to insertWindow when the strip is empty. width is honoured ONLY on the empty-strip fallback (which routes through insertWindow); joining an existing column keeps the host column's width intent — an override would resize every sibling. displayOverride applies only when ENGAGED (an explicit openTabbed rule): a plain consume-open must not overwrite the host column's user-toggled display with the config default. The empty-strip fallback opens with the override when engaged, else Normal.

◆ insertWindowIntoColumnAt()

bool PhosphorScrollEngine::ScrollStrip::insertWindowIntoColumnAt ( int columnIndex,
int tileIndex,
const QString & windowId,
const ScrollLayoutParams & params,
int minWidth = 0,
int minHeight = 0,
std::optional< ColumnDisplay > displayOverride = std::nullopt )

Re-insert windowId as a TILE of the existing column at columnIndex (float/minimize round-trip of a stacked tile), at tileIndex clamped into the stack.

Fails when the column index is out of range — callers fall back to a fresh column.

TAKES FOCUS, unlike insertWindowAt: the new tile becomes its column's active one, the column becomes the strip's active column, and the view re-anchors. That is what the unfloat path wants (the window the user just restored is the one to look at), but it means a restore path driving several arrivals must re-assert its own focus afterwards — the last arrival would otherwise keep it. The tile is seeded with params.defaultWindowHeight; callers with a remembered intent overwrite it via setWindowHeightIntent. displayOverride, when ENGAGED, is applied to the host column BEFORE the tile joins (through applyColumnDisplay, so the extent ownership transition holds), the same contract insertWindowIntoActiveColumn carries. Disengaged leaves the host's display alone, which is what a float/minimize round trip wants.

◆ isCenteringActiveColumn()

bool PhosphorScrollEngine::ScrollStrip::isCenteringActiveColumn ( const ScrollLayoutParams & params) const

Whether the layout policy pins the ACTIVE column to the middle of the viewport, so its on-screen position is not the strip's to choose.

The one spelling of the test the anchor math (keepOrRecenterAnchor, reanchorAfterFocusChange, updateViewForFocus), the removal re-focus, and the expand verb all ask.

◆ isEmpty()

bool PhosphorScrollEngine::ScrollStrip::isEmpty ( ) const
inline

◆ isWindowedFullscreen()

bool PhosphorScrollEngine::ScrollStrip::isWindowedFullscreen ( const QString & windowId) const

◆ isWindowMinimized()

bool PhosphorScrollEngine::ScrollStrip::isWindowMinimized ( const QString & windowId) const

◆ minimizeActiveColumnWidth()

bool PhosphorScrollEngine::ScrollStrip::minimizeActiveColumnWidth ( const ScrollLayoutParams & params)

The active column at its narrowest: the smallest preset, or MinColumnWidthFraction when the preset list is empty (Karousel minimize-width; the empty-list arm is reachable only from a test or an embedder, since the engine never hands down an empty vocabulary).

Refuses when already there, measured in RENDERED pixels so a column whose floor (a minimum size or a committed floor) already pins it at or above the target refuses too.

◆ minimizeActiveWindowHeight()

bool PhosphorScrollEngine::ScrollStrip::minimizeActiveWindowHeight ( const ScrollLayoutParams & params)

The active tile at its shortest: the smallest preset height, or MinWindowHeightFraction of the work area's cross extent when the preset list is empty.

The height twin of minimizeActiveColumnWidth, and the empty-list arm is reachable only from a test or an embedder for the same reason. Height has no Proportion spelling, so that fallback is written as Fixed pixels rather than as a fraction. Refuses when the tile already renders there.

◆ moveActiveColumn()

bool PhosphorScrollEngine::ScrollStrip::moveActiveColumn ( int delta,
const ScrollLayoutParams & params )

Swap the active column with its neighbour. delta is -1/+1.

◆ moveActiveColumnTo()

bool PhosphorScrollEngine::ScrollStrip::moveActiveColumnTo ( int target,
const ScrollLayoutParams & params )

Move the active column directly to target (one list move + one reanchor — a positional move must not pay per-step swap costs).

◆ moveActiveColumnToFirst()

bool PhosphorScrollEngine::ScrollStrip::moveActiveColumnToFirst ( const ScrollLayoutParams & params)

◆ moveActiveColumnToLast()

bool PhosphorScrollEngine::ScrollStrip::moveActiveColumnToLast ( const ScrollLayoutParams & params)

◆ moveActiveTile()

bool PhosphorScrollEngine::ScrollStrip::moveActiveTile ( int delta)

Reorder the active tile within its column by delta positions.

Any magnitude is accepted, not just -1/+1: the walk steps over minimized tiles, so a single-step request can cross several slots. The move is a REMOVE-AND-INSERT (QList::move), not a swap, so for |delta| > 1 the intervening tiles shift by one rather than the two endpoints exchanging places. A delta of 0 is a no-op.

◆ moveColumnTo()

bool PhosphorScrollEngine::ScrollStrip::moveColumnTo ( int from,
int to,
const ScrollLayoutParams & params )

Move the column at strip index from to strip index to and make it the active column (a placement map dragging one column past the others).

Unlike focusColumn, from is NOT clamped: an index past the end names no column, and moving the last column in its place would be a drag nobody made. False for either index out of range or equal.

◆ predictedFocusScrollPx()

int PhosphorScrollEngine::ScrollStrip::predictedFocusScrollPx ( int columnIndex,
const ScrollLayoutParams & params ) const

How far the view WOULD move, in pixels along the strip, if column columnIndex became the active one right now.

A pure query: it runs the same centering policy reanchorAfterFocusChange runs and compares the resulting view offset with the current one, mutating nothing.

This is niri's focus-follows-mouse max-scroll-amount predicate: focus-follows-mouse asks it before activating a window so a pointer grazing a column that is mostly off screen does not yank the whole strip. Answers 0 for the active column, for an out-of-range index and for a degenerate work area, all of which mean "focusing this costs no scroll" and so can never be refused by a cap.

◆ reanchorForDropCommit()

void PhosphorScrollEngine::ScrollStrip::reanchorForDropCommit ( int oldViewOffset,
const ScrollLayoutParams & params )

Drag-drop re-anchor (ScrollEngine::commitDragInsertPreview): land the just-dropped ACTIVE column at the on-screen position the drop indicator promised — its strip position minus oldViewOffset, the view offset captured BEFORE the commit's insert — then move the view the MINIMUM that makes the column fully visible (the Never fit).

The policy's OnOverflow arm centers a column too wide to share the viewport with either neighbour, which after a drop hides every other window and reads as the drop having flown away, and the minimal fit keeps whatever neighbour still fits on screen beside it. A maximized-to-edges column keeps its one correct position (focusAnchorFor's reason). This arm SETS the detach latch, so the drop owns the view the way a pan does and the centering policy cannot take it back until something re-attaches it (the class doc's View detachment section lists them).

The EXCEPTION is a policy that pins the focused column to the middle whatever put it there — CenterFocusedColumn::Always, and the lone-column rule (isCenteringActiveColumn). There the drop centers through centerActiveColumn and leaves the view ATTACHED, which is the same verdict an open, a move-to-last or a plain focus step reaches.

◆ reconcileWindowSize()

bool PhosphorScrollEngine::ScrollStrip::reconcileWindowSize ( const QString & windowId,
const QSize & ackedSize,
bool mainChanged,
bool crossChanged,
const ScrollLayoutParams & params )

Record the size a client/user resize actually settled on.

The acked MAIN extent becomes the column's Fixed width intent only when mainChanged (the engine compares the gesture's start frame with the frame it ended on) — a resize purely ACROSS the strip must not pin a Proportion/Preset column to pixels. ackedSize is the size the engine settled on, which is the frame the resize ended at except on an axis where the relayout will centre the window: there a drag of one edge is doubled (ScrollEngine::onWindowResized) so the dragged edge lands where it was released once the column is centred again. The acked CROSS extent becomes the tile's Fixed height intent symmetrically, only when crossChanged; a lone tile is included, because relayout honours a solo tile's Fixed height (niri parity). On a TABBED column both intents size the COLUMN rather than the window, so each ack is lifted on the way in by the reservation the indicator takes on its axis (tabbedMainReservationPx along the strip, tabbedCrossReservationPx across it), the conversion the height sizing verbs make. Other columns are untouched.

mainChanged / crossChanged say which axis the interactive resize actually moved, in ROLE terms. ackedSize is the compositor's physical QSize and is decoded through params.axis, so the caller must derive the two flags against that same axis, or each guard ends up protecting the intent it was not written for. The bools were spelled widthChanged / heightChanged before the strip gained a second axis, and the signature kept its shape, so an out-of-tree caller still passing physical width/height flags compiles and is silently wrong on a vertical strip.

◆ relayout()

ResolvedStrip PhosphorScrollEngine::ScrollStrip::relayout ( const ScrollLayoutParams & params) const

Resolve every non-minimized tile's absolute pixel rect against params.

Pure function of the current model state; does not mutate.

◆ removeWindow()

bool PhosphorScrollEngine::ScrollStrip::removeWindow ( const QString & windowId,
const ScrollLayoutParams & params )

Remove windowId; a column left empty closes up.

Keeps the view anchored so surviving neighbours don't jump, and selects a sensible new focus when the active tile/column vanished. Returns false when untracked.

◆ resetToDefaults()

bool PhosphorScrollEngine::ScrollStrip::resetToDefaults ( const std::optional< ColumnWidth > & defaultWidth,
const std::optional< WindowHeight > & defaultHeight,
ColumnDisplay defaultDisplay,
const ScrollLayoutParams & params )

Every column back to defaultWidth and defaultDisplay, and every tile back to defaultHeight: the scrolling half of the Retile shortcut, whose other modes re-apply their layout the same way.

All three defaults are arguments because the engine resolves them per screen: the display is not carried in params at all, and the width is std::nullopt when the context's default is "the client decides" (the engine's ClientDecides kind with no rule pinning a width), in which case every column keeps the width it has and only display and heights are reset. The height is std::nullopt on the same terms (the ClientDecides height kind with no rule pinning one), and then every tile keeps the height it has. A column the display write turns Tabbed still resolves to one extent, because the transition names an owner rather than flattening the tabs that do not own it. Returns true when any intent changed. Clears the single pre-maximize slot whenever a default width was supplied, since nothing is maximized once every column is back at that default — including when no column needed rewriting. Under a std::nullopt width a maximized column stays maximized and keeps its restore slot.

Intents only: a column's floors are not intents and stay where they are. A column floored by its frame minimum or by its client's own commits (ScrollLayoutParams::committedFloor) is back at the default INTENT and still renders at its floor, so this can answer true with that column unmoved, and a tile held across the strip by a committed cross floor (committedCrossFloor) keeps its share the same way.

◆ resolveColumnWidthPx()

int PhosphorScrollEngine::ScrollStrip::resolveColumnWidthPx ( const ColumnWidth & width,
const ScrollLayoutParams & params )
static

The pixel MAIN extent width resolves to under params (gap-aware proportions, preset lookup; no min-extent clamp).

◆ restateWindowHeightIntent()

bool PhosphorScrollEngine::ScrollStrip::restateWindowHeightIntent ( const QString & windowId,
const WindowHeight & height )

setWindowHeightIntent for a REMEMBERED intent re-stated on the way back into a column (an unfloat, a cancelled or dropped drag, a migration): the intent is written the same way, but a tabbed column's extent owner is left as the column held it before the write, so a non-Auto height does not take the column from the tab that sizes it.

A caller whose window owned the column when it left hands that back through setTabbedHeightOwner. Returns whether the intent changed.

◆ restoreViewAnchor()

void PhosphorScrollEngine::ScrollStrip::restoreViewAnchor ( int anchor,
const ScrollLayoutParams & params )

Restore a previously captured view anchor, RAW: a centered anchor implies an out-of-range derived viewOffset by design (the same shape centerActiveColumn stores), so no clamp is applied here — later structural inserts re-clamp when the strip cannot honour the view.

The stash-restore path re-applies the anchor AFTER re-focusing the stashed active window, overriding the focus change's own centering-policy reanchor with the user's actual view. It does NOT touch the detachment latch: that focus call has just cleared it, and re-asserting it is the caller's job through setViewDetached, so both halves of a captured view are restored by the same code. params is currently UNUSED (the raw restore needs no layout maths) but stays in the exported signature: every sibling anchor mutator takes it, and dropping it is an ABI break for no gain.

◆ rotateVisibleColumns()

int PhosphorScrollEngine::ScrollStrip::rotateVisibleColumns ( bool clockwise,
const ScrollLayoutParams & params )

Rotate the window contents of the VISIBLE columns through their slots (clockwise = every stack shifts one slot ALONG the strip, towards its end, and the last visible wraps to the first).

Width and display INTENTS stay with the SLOT, like autotile's rotate through fixed zones, so the strip's geometry holds still for the ordinary case. The maximize-to-edges flag travels with the WINDOWS, since the compositor mirrors it onto each window's own maximize bit, and so does the tabbed height owner, which is then reconciled against the slot's display (a Tabbed slot receiving a Normal stack names the tab on show, a Normal slot holds none). The geometry is not an absolute either: a column's resolved width also honours its tiles' floors along the strip (columnMinExtentPx: the min-MAIN clamp and any committed floor, both of which travel with the window) and that flag, so rotating a window with a large floor into a small slot grows that slot and shrinks the one it left. The anchor is re-clamped afterwards when the strip as a whole shrank, so the view cannot be stranded past its end. The active column index stays put (focus follows the slot; callers activate its new window). Returns the number of windows rotated, 0 when fewer than two columns are visible.

◆ scrollViewBy()

bool PhosphorScrollEngine::ScrollStrip::scrollViewBy ( int delta,
const ScrollLayoutParams & params )

Scroll the view delta pixels forward ALONG THE STRIP (negative scrolls back towards its start) WITHOUT changing focus, clamped to the strip's ends.

Forward is rightward on a horizontal strip and downward on a vertical one. The anchor is stored relative to the active column, so a forward view move shrinks it by the same amount. Returns true when the anchor actually moved — a caller sitting at either end gets false and can stop. A move DETACHES the view from the centering policy (see the class doc); a refusal leaves the latch as it found it. This is the only mutator that moves the view without a focus, structure or policy change behind it; the drag-insert edge auto-scroll, the engine's view-scroll verb (behind the wheel and the keyboard page pair) and its pixel pan (behind the placement map's lens drag) are its callers. delta may be any int: the clamp is computed wide.

◆ setActiveColumnWidth()

bool PhosphorScrollEngine::ScrollStrip::setActiveColumnWidth ( const ColumnWidth & width)

Set the active column's width intent, verbatim, dropping a maximize-to-edges override (the drop alone is a change).

The absolute set-column-width verb's (and the tests') way to reach an exact intent; the cycle, adjust and maximize verbs below write the column directly. Callers own validation — nothing here clamps. The width is the column's extent ALONG the strip.

◆ setActiveWindowHeight()

bool PhosphorScrollEngine::ScrollStrip::setActiveWindowHeight ( const WindowHeight & height)

Set the active tile's height intent, verbatim.

The height twin of setActiveColumnWidth and the absolute set-window-height verb's write: it drops a maximize-to-edges override and the tile's restore slot, and a non-Auto height claims a tabbed column's extent for the tile. The cycle and adjust verbs write the tile directly, and the restore and open paths go through setWindowHeightIntent instead. Callers own validation. The height is the tile's extent ACROSS the strip.

◆ setMaximizedToEdgesForWindow()

bool PhosphorScrollEngine::ScrollStrip::setMaximizedToEdgesForWindow ( const QString & windowId,
bool maximized )

Restore-path setter for the column owning windowId: a stash claim re-asserting the state it captured, not a user verb, so none of the toggle's addressing or feedback applies.

No-op (false) when the strip does not hold the window or the state already matches.

◆ setTabbedHeightOwner()

bool PhosphorScrollEngine::ScrollStrip::setTabbedHeightOwner ( const QString & windowId)

Make windowId's tab the one whose height decides its TABBED column's cross extent.

The restore seam for that ownership: the mode-round-trip stash and the persisted blob both carry it, because the tabs that do not own it keep their own heights and a fallback scan would hand the column to a different tab than held it. No-op for an unknown window or a Normal column. Returns whether the owner moved.

◆ setViewDetached()

void PhosphorScrollEngine::ScrollStrip::setViewDetached ( bool detached)
inline

The other half of restoreViewAnchor: re-assert a captured detachment.

Only meaningful alongside the anchor it was captured with, so a caller that drops that anchor (the stash's axis-mismatch arm) must drop this too, or the view stays pinned wherever the focus restore left it.

Clearing it standalone is how the engine re-attaches on behalf of the tile-focus ops (the class doc lists the sites): it hands the view to the policy while leaving the anchor for the next updateViewForFocus to derive, which is the one thing a re-anchor here could not do without a focus change to derive from.

◆ setWindowedFullscreen()

bool PhosphorScrollEngine::ScrollStrip::setWindowedFullscreen ( const QString & windowId,
bool on )

Direct flag write for windowId (any tile, not just the active one) — compositor-driven reconciliation clears through this, and the mode-round-trip restore path re-applies stashed flags through it.

Returns false for an unknown window or an unchanged flag.

◆ setWindowHeightIntent()

bool PhosphorScrollEngine::ScrollStrip::setWindowHeightIntent ( const QString & windowId,
const WindowHeight & height )

Direct height-intent write for windowId (any tile, not just the active one).

The mode-round-trip restore path re-applies stashed heights through this, the open path commits a client-decided height and a migration re-states the height the window carried over, and the per-window open-height rule resolves through it too. A non-Auto height claims a TABBED column's extent for the tile (claimTabbedHeightOwnership), and a claim that moves the owner is a change even when the intent was already the one asked for. Returns false for an unknown window, and for an unchanged intent that moved no ownership. Unlike setActiveWindowHeight it leaves a maximize-to-edges override standing.

◆ setWindowMinimized()

bool PhosphorScrollEngine::ScrollStrip::setWindowMinimized ( const QString & windowId,
bool minimized,
const ScrollLayoutParams & params )

Mark a tile minimized (kept in order, excluded from layout) or restore it.

Returns true when the flag actually changed.

TEST SEAM, and the entry point to a whole test-driven domain: the daemon models minimize as a FLOAT (the effect reports it that way), so in production a minimized window leaves the strip entirely and nothing here ever sets the flag. The minimized branches in relayout, focus, move and the height budget are nonetheless real behaviour the model owes its callers — kept, exercised by test_scrollstrip_core / _ops, and documented as unreached rather than deleted, because the alternative is a model that silently mislays a tile the day the daemon does drive minimize directly.

◆ setWindowMinimumSize()

bool PhosphorScrollEngine::ScrollStrip::setWindowMinimumSize ( const QString & windowId,
int minWidth,
int minHeight )

Update a tile's stored minimum size. Returns true when it changed.

◆ stripFitsViewport()

bool PhosphorScrollEngine::ScrollStrip::stripFitsViewport ( const ScrollLayoutParams & params) const

True when the whole strip already fits the viewport, i.e.

there is nothing off screen to scroll to. A degenerate work area counts as fitting, so a caller cannot scroll a screen that is going away.

Exists so a per-frame caller can ask the question without paying for a full relayout: relayout() allocates a ResolvedColumn (with a nested tile vector) per column, and a predicate needs none of that. The edge auto-scroll's disarm gate asks stripSettledInViewport, which is built on this one.

◆ stripModel()

ScrollStripModel PhosphorScrollEngine::ScrollStrip::stripModel ( const ScrollLayoutParams & params) const

The whole strip as a renderer of a strip MAP reads it: every column's strip position and main extent, every tile's cross extent, the viewport's offset and extent on the same axis, and the active column (ScrollStripModel documents each field).

ONE relayout pass plus one cumulative walk over the columns, so the cost is the same as a relayout rather than a columnStripPos per column. Pure function of the current model state; does not mutate. On a degenerate work area (no extent along the strip) the columns resolve no extent, so none takes a strip position, and every tile's cross extent is 0 because the relayout lays nothing out there. The exception is a maximized-to-edges column, which resolves against the raw work area while that still has an extent.

◆ stripSettledInViewport()

bool PhosphorScrollEngine::ScrollStrip::stripSettledInViewport ( const ScrollLayoutParams & params) const

stripFitsViewport AND the derived view offset is settled inside [0, stripExtent - viewport] — i.e.

genuinely nothing to reveal. The distinction matters because the centering mutators deliberately store an anchor whose derived viewOffset is out of range (their comments say so), which can leave a column hanging off one edge even though the strip FITS; the edge auto-scroll's clamped-delta walk is the one motion that brings it back, so its disarm gate must ask this, not the fits-only question. Degenerate work areas and empty strips answer true, same fail-closed reading as stripFitsViewport.

◆ tabbedCrossReservationPx()

int PhosphorScrollEngine::ScrollStrip::tabbedCrossReservationPx ( const Column & c,
const ScrollLayoutParams & params )
static

Pixels the tab indicator takes out of column c ACROSS the strip, the cross-axis twin of tabbedMainReservationPx.

0 for a column that is not tabbed, and whenever the indicator's thickness eats the MAIN axis instead (which of the two it eats depends on the strip's axis, see TabIndicatorParams::reservedThickness). Public beside its twin for the engine's client-decided height, which lifts an intent into column space the way reconcileWindowSize does.

◆ tabbedMainReservationPx()

int PhosphorScrollEngine::ScrollStrip::tabbedMainReservationPx ( const Column & c,
const ScrollLayoutParams & params )
static

Pixels the tab indicator takes out of column c ALONG the strip: the difference between the column's main extent and the one its tiles are offered.

0 for a column that is not tabbed, and whenever the indicator's thickness eats the CROSS axis instead (which of the two it eats depends on the strip's axis, see TabIndicatorParams::reservedThickness). The main-axis twin of tabbedCrossReservationPx, and the reservation columnMinExtentPx adds to each tile's floor.

◆ takeWindow()

bool PhosphorScrollEngine::ScrollStrip::takeWindow ( const QString & windowId,
const ScrollLayoutParams & params )

Remove windowId with no focus policy beyond index fixups — the cross-context transfer / float path (the caller re-homes the window).

Everything the tile carried goes with it, so a caller that re-homes the window reads its intents first. A committed floor, along the strip or across it, is not tile state: the engine holds both per window (ScrollLayoutParams::committedFloor and committedCrossFloor), and neither this nor removeWindow touches them.

◆ tileCrossCapacityPx()

int PhosphorScrollEngine::ScrollStrip::tileCrossCapacityPx ( const QString & windowId,
const ScrollLayoutParams & params ) const

The most windowId's column can ever give its tile ACROSS the strip under params while its siblings keep their own floors: for a stack, the column's cross budget (the work area less the gaps between its visible tiles) less every other visible tile's floor across (tileMinCrossPx, a pixel at least); for a tabbed column, its cross extent less the indicator's cross reservation, since every tab shares one rect.

-1 when this strip does not hold the window as a visible tile or the work area is degenerate, and never below 0 otherwise (0 when the siblings' floors alone fill the column). A committed cross floor past this is one the column can never hold (ScrollEngine::outgrowsWorkArea).

◆ toggleActiveColumnTabbed()

bool PhosphorScrollEngine::ScrollStrip::toggleActiveColumnTabbed ( )

Toggle the active column between Normal and Tabbed presentation.

◆ toggleActiveWindowedFullscreen()

bool PhosphorScrollEngine::ScrollStrip::toggleActiveWindowedFullscreen ( )

Toggle windowed fullscreen on the active tile of the active column.

Layout-neutral: the tile keeps its column slot; the flag only rides the apply payload so the compositor flips the client's fullscreen state. Returns false when there is no active tile.

◆ toggleMaximizeActiveColumn()

bool PhosphorScrollEngine::ScrollStrip::toggleMaximizeActiveColumn ( const ScrollLayoutParams & params)

Full work-area MAIN extent, still tiled (niri maximize-column).

Toggles back to the pre-maximize intent when already maximized.

"Already maximized" is decided on RESOLVED PIXELS, not on the stored intent value, so every route to a full-width column un-maximizes — preset cycling, expand, a restore from disk. Three arms sit behind the simple description:

  • The stored pre-maximize width is re-validated against the current work area and axis. One captured on a wider output resolves clamped back to full width, and restoring it would spend the slot and move nothing, so that case falls through instead.
  • With no usable stored width (maximized in an earlier session, or another column's maximize took the single slot) it un-maximizes to the context default width rather than dead-ending.
  • If the default is ITSELF full width, it takes half the work area, because otherwise that user could never un-maximize.

Refuses (false) when there is no active column, on a degenerate work area, and for a column whose floor (columnMinExtentPx: a frame minimum or a committed floor) pins it at or past the work area, a dead end the verb cannot resolve; the definition documents why.

◆ toggleMaximizeActiveWindowHeight()

bool PhosphorScrollEngine::ScrollStrip::toggleMaximizeActiveWindowHeight ( const ScrollLayoutParams & params)

Toggle the active tile between filling its column's cross budget and the height it had before, falling back to the even auto-split when it had none of its own.

The height twin of toggleMaximizeActiveColumn, restore included: the displaced height is kept in the tile's preMaximizeHeight rather than in a strip-level index, so unlike m_preMaximizeColumnIdx it needs no re-clamping from the structural ops. Auto is what un-maximizing means for a tile that never had a height of its own, since the height family reads Auto as "the column decides". For a tile that is alone in its column Auto and the full budget render identically, so that press changes the stored intent without moving anything — the toggle still answers true, because the intent decides how the tile shares the column the moment a sibling arrives.

The maximized test reads the stored intent as well as the rendered extent: siblings held up by their frame minimums can stop the tile reaching the budget on screen, and a pixel-only test would then maximize forever and never come back. Both non-Auto spellings count — a Preset whose fraction RESOLVES to the budget is maximized just as a Fixed at the budget is, or the top preset would be silently rewritten to a Fixed of the same extent and lose its anchor. A TABBED column toggles in the column's own space, the cycle and adjust verbs' rule.

reconcileWindowSize overwrites the stored height with whatever size a resize settles on, and clears the restore slot with it. That is safe, and the reason is worth writing down because it is not obvious: reconcile is reached from exactly one place, ScrollEngine::onWindowResized, which the daemon calls only from WindowTrackingAdaptor::notifyWindowResized, which the effect fires only from windowFinishUserMovedResized gated on KWin's isUserResize(). So the ONLY thing that can overwrite the intent is a user's finished interactive resize, and a user who has just dragged this window to a size of their own SHOULD stop reading as maximized. A client resizing itself — a terminal quantising to its character cell — never reaches reconcile and cannot erase the maximize. Its answer to an offered tile does reach the engine, through ScrollEngine::reportCommittedSize, which learns only floors from it (along the strip for the column, across it for the tile) and never writes an intent.

Do not "fix" this by refusing the ack in reconcile. That makes onWindowResized's refused-ack branch schedule a retile which re-applies the same rect, and a client that will not take it quantises again: a self-driving loop, which is what that branch's own comment describes.

The height the maximize displaced is remembered in the tile's preMaximizeHeight, so un-maximizing puts it back; Auto is the answer only when nothing was remembered, which is the case for a tile that reached the budget by another route.

That slot is BOTH the restore value and the first half of the maximized test, and this is where the height axis deliberately DIVERGES from the width axis rather than mirroring it. The width toggle keeps its restore in m_preMaximizeColumnIdx + m_preMaximizeWidth and re-infers maximized state from resolved pixels, which it can afford because a column's main budget is the whole viewport: it does not move when the STRIP changes shape, only when the work area does, and the width restore arm re-validates its stored width against the current one before using it. A column's CROSS budget moves on both counts — it is the cross extent less one gap per inter-tile seam, so closing a sibling or tabbing the column grows it without the work area moving at all — and a tile holding Fixed(the old budget) then re-infers as NOT maximized. Consulting the slot first is what stops that press re-entering the maximize arm and overwriting the user's remembered height with a near-full one. The pixel and intent tests stay behind it for the tile that reached full height by another route and so has no slot.

It lives on the tile rather than in a strip-level index precisely so the structural ops do not have to re-clamp it; Tile's own note carries the rest, including why it is neither serialized nor carried across a re-insert.

◆ toggleMaximizeColumnForWindow()

bool PhosphorScrollEngine::ScrollStrip::toggleMaximizeColumnForWindow ( const QString & windowId,
const ScrollLayoutParams & params )

The same verb aimed at the column OWNING windowId rather than at the active one.

Refuses (false) when this strip does not hold the window.

The distinction is load-bearing for a request that names ONE window (the D-Bus toggleMaximizeColumn with a window id, which the shell's placement map sends): the active column is frequently a different one, so aiming at the active column would resize somebody else's column. The compositor's maximize interception goes to the maximize-to-edges twin below, not here.

◆ toggleMaximizeToEdgesActiveColumn()

bool PhosphorScrollEngine::ScrollStrip::toggleMaximizeToEdgesActiveColumn ( const ScrollLayoutParams & params)

Toggle the active column's maximize-to-edges state (niri maximize-window-to-edges, generalized to the column): full raw work area on both axes, gap-free (Column::maximizedToEdges carries the contract).

Pure declared state — the stored width intent is untouched, so the un-maximize arm is just "stop overriding". Refuses only on a degenerate work area (the sibling verbs' bail) and on a missing column.

◆ toggleMaximizeToEdgesForWindow()

bool PhosphorScrollEngine::ScrollStrip::toggleMaximizeToEdgesForWindow ( const QString & windowId,
const ScrollLayoutParams & params )

The same verb aimed at the column OWNING windowId, for the compositor's maximize interception — toggleMaximizeColumnForWindow's doc carries why the named form is load-bearing.

◆ updateViewForFocus()

void PhosphorScrollEngine::ScrollStrip::updateViewForFocus ( const ScrollLayoutParams & params)

Re-apply the centering policy to the current active column (settings change / work-area change) using the current anchor as the "no scroll" baseline.

A DETACHED view is left entirely alone, not even re-clamped (see the class doc and the body's comment for why).

◆ viewAnchor()

int PhosphorScrollEngine::ScrollStrip::viewAnchor ( ) const
inline

The stored active-relative view anchor (see class doc).

Exposed for the engine's mode-round-trip stash — pixels derived from it are not.

◆ viewDetached()

bool PhosphorScrollEngine::ScrollStrip::viewDetached ( ) const
inline

Whether an explicit pan owns the view instead of the centering policy (see the class doc).

Exposed for the stash and the persisted blob, which must carry it beside the anchor.

◆ viewOverhang()

ViewOverhang PhosphorScrollEngine::ScrollStrip::viewOverhang ( const ScrollLayoutParams & params) const

◆ visibleColumnIndices()

QVector< int > PhosphorScrollEngine::ScrollStrip::visibleColumnIndices ( const ScrollLayoutParams & params) const

Strip indices of the columns currently intersecting the viewport, in strip order — a viewport-intersection helper, NOT the zone-number space.

Zone numbers are per-TILE and live one layer up, in ScrollEngine::visibleTiles. The group equalizeVisibleColumnWidths splits and rotateVisibleColumns rotates.

◆ windowColumnMainExtentPx()

int PhosphorScrollEngine::ScrollStrip::windowColumnMainExtentPx ( const QString & windowId,
const ScrollLayoutParams & params ) const

The extent ALONG the strip of the column holding windowId under params, exactly as the relayout resolves it (columnExtentPx: the intent raised to the column's floors, capped at the work area, or the raw extent of a maximized-to-edges column), or -1 when this strip does not hold the window.

The tile itself is offered this less tabbedMainReservationPx. The engine's committed-floor bookkeeping (ScrollEngine::reportCommittedSize) measures with it, passing params whose ScrollLayoutParams::committedFloor it has masked when it needs the extent a column resolves to without one window's floor.

◆ windowCount()

int PhosphorScrollEngine::ScrollStrip::windowCount ( ) const

◆ windowHeightIntent()

WindowHeight PhosphorScrollEngine::ScrollStrip::windowHeightIntent ( const QString & windowId) const

The height intent windowId's tile carries, or a default-constructed (Auto) one for an unknown window.

The reader half of setWindowHeightIntent: every caller that hands a window's height across a structural boundary — the cross-output move, the context migration — has to read it before the take destroys the tile, and each had grown its own column-then-tile walk to do so.

◆ windowMinimumSize()

QSize PhosphorScrollEngine::ScrollStrip::windowMinimumSize ( const QString & windowId) const

The tile's minimum frame size (Tile::minWidth), or 0x0 when untracked.

◆ windowsInOrder()

QStringList PhosphorScrollEngine::ScrollStrip::windowsInOrder ( ) const

All windows in strip order (column order along the strip, then each column's stack order across it), including minimized tiles (their slot is part of the order contract).

◆ windowTileCrossExtentPx()

int PhosphorScrollEngine::ScrollStrip::windowTileCrossExtentPx ( const QString & windowId,
const ScrollLayoutParams & params ) const

The extent ACROSS the strip of windowId's tile under params, exactly as the relayout resolves it (the stack's split with its floors, or a tabbed column's content rect), or -1 when this strip lays no tile out for the window (it does not hold it, or the tile is minimized).

The cross twin of windowColumnMainExtentPx: the engine's cross-floor bookkeeping measures a tile's share with it the same way, passing params whose ScrollLayoutParams::committedCrossFloor it has masked when it needs the share a tile resolves to without one window's floor. A full relayout per call.


The documentation for this class was generated from the following file:
  • phosphor-scroll-engine/include/PhosphorScrollEngine/ScrollStrip.h