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

Namespaces

namespace  ScrollPerScreenKeys
 Per-screen override-map keys for ScrollEngine::applyPerScreenConfig.

Classes

class  ScrollEngine
 niri-style scrolling placement engine. More...
struct  ScrollOpenParams
 Per-window open-behaviour overrides resolved from window rules (openColumnWidth / openTabbed / openColumnPlacement). More...
struct  ScrollVisibleTile
 One visible tile of a strip: the unit of the scroll "zone number" space. More...
struct  ScrollVisibleTileWithRect
 A tile paired with its screen-normalized rect, from ONE strip walk (see ScrollEngine::visibleTilesWithRects). More...
struct  ScrollStripSnapshotTile
 One tile of a strip snapshot (see ScrollEngine::stripSnapshot). More...
struct  ScrollStripSnapshotColumn
 One column of a strip snapshot, in strip order. More...
struct  ScrollStripSnapshot
 A column-aware strip snapshot for drag-popup renderers. More...
struct  ScrollStripModelTile
 One tile of a strip MODEL (see ScrollStripModel). More...
struct  ScrollStripModelColumn
 One column of a strip model, in strip order. More...
struct  ScrollStripModel
 The whole strip of one screen as a renderer of a strip MAP needs it: every column with its strip position and extent, the viewport's offset and size on the same axis, and the active column. More...
struct  StashedTile
 The mode-round-trip strip stash value types (ScrollEngine::m_stripStash). More...
struct  StashedColumn
struct  StashedStrip
 One stashed strip: the structural columns plus the focus/view pair whose loss made every mode round trip re-anchor on an arbitrary window (first arrival won the focus). More...
struct  FloatRestore
 What a floated/minimized window's column held, so unfloat restores the slot AND the user's width/display intent (a Proportion/Preset column must not come back as the default width). More...
struct  DragInsertPreview
 Live drag-insert preview state (drag_preview.cpp). More...
struct  CommittedMainExtent
 What a client's own commits have taught the engine about one window's extent ALONG a strip that runs one way (ScrollEngine::reportCommittedSize). More...
struct  CommittedCrossExtent
 What a client's own commits have taught the engine about one window's extent ACROSS a strip that runs one way (ScrollEngine::reportCommittedSize): a tile the client answers longer than its share of its column across the strip, inside the work area. More...
struct  CommittedExtent
 One window's CommittedMainExtent per strip orientation, the value type of ScrollEngine::m_committedExtents. More...
class  ScrollState
 Per-(screen, desktop, activity) scrolling state: one ScrollStrip plus the windows floated out of it. More...
class  ScrollStrip
 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...
struct  ScrollBlueprintProgress
 How far a screen has worked through its context template's seed blueprint. More...
struct  TabIndicatorParams
 The tab indicator's GEOMETRY inputs — the subset of the Scrolling.TabIndicator family that changes resolved rects, so it has to live in the layout params rather than staying with the paint half. More...
struct  ColumnWidth
 Column width INTENT — the source of truth the strip stores. More...
struct  WindowHeight
 Tile height INTENT within a column (its extent ACROSS the strip). More...
struct  Tile
 One window in a column. More...
struct  Column
 One column: a stack of tiles ACROSS the strip (vertical on a horizontal strip, horizontal on a vertical one). More...
struct  ScrollLayoutParams
 Inputs a relayout resolves pixel rects against. More...
struct  ResolvedTile
 One tile's resolved output for a relayout pass. More...
struct  ResolvedColumn
 One column's resolved output. More...
struct  ResolvedStrip
 A full relayout pass over one strip. More...
class  StripAxis
 Coordinate mapping for one strip orientation: a pure value type, trivially copyable, no allocation, cheap enough to read once per column and once per tile inside the relayout loop. More...

Enumerations

enum class  CenterFocusedColumn : int { Never = 0 , Always = 1 , OnOverflow = 2 }
 Persistent view-centering policy for the focused column (niri's center-focused-column). More...
enum class  ColumnDisplay : int { Normal = 0 , Tabbed = 1 }
 How a column presents its tiles (niri's column display). More...
enum class  TabIndicatorPosition : int { Left = 0 , Right = 1 , Top = 2 , Bottom = 3 }
 Which side of the column the tab indicator runs along (niri's TabIndicatorPosition, same declaration order). More...
enum class  DefaultWidthKind : int { Proportion = 0 , Fixed = 1 , ClientDecides = 2 , Preset = 3 }
 Wire vocabulary of the DEFAULT-column-width KIND setting (IScrollSettings::scrollingDefaultColumnWidthKind). More...
enum class  DefaultHeightKind : int { Auto = 0 , Fixed = 1 , Preset = 2 , ClientDecides = 3 }
 Wire vocabulary of the DEFAULT-window-height KIND setting. More...
enum class  ScrollInsertPosition : int {
  RightOfActive = 0 , LeftOfActive = 1 , First = 2 , Last = 3 ,
  IntoActiveColumn = 4
}
 Where a fresh-opened window's new column enters the strip (config default; the openColumnPlacement window rule outranks it). More...

Functions

bool isVerticalTabIndicator (TabIndicatorPosition position)
 True when position puts the indicator on a vertical edge, so its long axis is the column's HEIGHT and its thickness eats the column's WIDTH.
int nearestPresetIndex (const QList< qreal > &presets, qreal fraction)
 Shared nearest-entry resolution for the fraction anchors above — the ONE implementation behind preset resolution, cycling, and height-fraction probes (it replaced three per-site variants).
qreal nearestPresetValue (const QList< qreal > &presets, qreal fraction, qreal fallback=0.5)
 The nearest entry's VALUE.
int proportionalPx (qreal proportion, int workExtent, int gap)
 A proportion resolves against the work extent PLUS one gap so that proportions summing to 1 tile edge-to-edge with the gaps between them (0.5 + 0.5 across a 1000px area with a 10px gap → 495 + 10 + 495).
template<typename Resolver>
int cyclePresetIndexByExtent (int count, int currentPx, int delta, Resolver resolve)
 The vocabulary index a preset CYCLE press lands on, given what the target currently measures on screen.
QVector< const ResolvedColumn * > visibleColumnsOf (const ResolvedStrip &resolved, const QRect &workArea)
 The columns of resolved that intersect workArea, in strip order.

Variables

constexpr qreal MinColumnWidthFraction = 0.05
 The narrowest column width this engine will accept as a proportion of the work area.
constexpr qreal MinWindowHeightFraction = 0.05
 The shortest tile height this engine will accept as a proportion of the work area.

Enumeration Type Documentation

◆ CenterFocusedColumn

Persistent view-centering policy for the focused column (niri's center-focused-column).

Wire/config encoding is the int value; append only.

Enumerator
Never 

Focusing an off-screen column scrolls the minimum amount to pin it to the edge it entered from; never centers.

Always 

The focused column is always centered in the view.

OnOverflow 

Center only when the focused column plus the previously focused one cannot both fit on screen at once.

◆ ColumnDisplay

enum class PhosphorScrollEngine::ColumnDisplay : int
strong

How a column presents its tiles (niri's column display).

Enumerator
Normal 

Tiles split the column's CROSS extent between them; all are visible.

Tabbed 

Only the active tile is laid out, at the column's content rect (its CROSS extent less whatever an in-column indicator reserved); the other tiles are hidden and represented by a tab-indicator strip.

That cross extent is the height intent of the tab that OWNS it (Column::heightOwnerId), NOT the tab on show: reading the shown tab would resize the column on every tab switch and break the compositor's tab cross-fade, which is built on the arriving tab occupying the rect the outgoing one just vacated. So a tabbed column need not span the work area (ScrollStrip::tabbedColumnCrossPx).

◆ DefaultHeightKind

enum class PhosphorScrollEngine::DefaultHeightKind : int
strong

Wire vocabulary of the DEFAULT-window-height KIND setting.

The first three members happen to share WindowHeight::Kind's values (Auto/Fixed/ Preset), but this space is NOT that enum and must never be cast to it: ClientDecides has no WindowHeight::Kind counterpart at all, exactly like its width twin. The engine translates with explicit ifs.

Enumerator
Auto 
Fixed 
Preset 
ClientDecides 

New windows join their column at the client's own cross extent, the height twin of DefaultWidthKind::ClientDecides.

Appended as 3 because the other three are load-bearing wire values in stored configs.

◆ DefaultWidthKind

enum class PhosphorScrollEngine::DefaultWidthKind : int
strong

Wire vocabulary of the DEFAULT-column-width KIND setting (IScrollSettings::scrollingDefaultColumnWidthKind).

Deliberately distinct from ColumnWidth::Kind — this enum's 2 means "client decides" (a settings-level policy with no per-column representation), while ColumnWidth::Kind's 2 is Preset. Never static_cast between the two.

Enumerator
Proportion 
Fixed 
ClientDecides 
Preset 

New columns open on a preset VALUE anchor (ColumnWidth::makePreset takes a fraction), so they reflow with preset-list changes by snapping to the nearest entry.

The config spin stays index-based; the engine resolves it to the anchor at read time. Appended as 3 — 2 is taken by ClientDecides and stored configs rely on it.

◆ ScrollInsertPosition

Where a fresh-opened window's new column enters the strip (config default; the openColumnPlacement window rule outranks it).

Wire/config encoding is the int value; append only. RightOfActive must stay 0 so an absent key preserves the historical behavior.

Enumerator
RightOfActive 
LeftOfActive 
First 

The strip's FIRST column.

Last 

The strip's LAST column (niri's append).

IntoActiveColumn 

Stack into the focused column instead of opening a new one.

◆ TabIndicatorPosition

Which side of the column the tab indicator runs along (niri's TabIndicatorPosition, same declaration order).

Left/Right put the indicator on a vertical edge and it runs down the column; Top/Bottom put it on a horizontal edge and it runs across. The settings layer spells the same wire values in ConfigDefaults and settingsschema_scrolling.cpp static_asserts the two agree.

Enumerator
Left 
Right 
Top 
Bottom 

Function Documentation

◆ cyclePresetIndexByExtent()

template<typename Resolver>
int PhosphorScrollEngine::cyclePresetIndexByExtent ( int count,
int currentPx,
int delta,
Resolver resolve )

The vocabulary index a preset CYCLE press lands on, given what the target currently measures on screen.

niri's rule (Column::toggle_width / toggle_window_height), ported: a press moves the size the way the key says, so a forward press takes an entry strictly WIDER/TALLER than the current extent and a backward press one strictly smaller, wrapping at each end. The one-pixel allowance is niri's too, for fractional-scale rounding. Which entry, and which end, are resolved by EXTENT here (nearest on the pressed side; the vocabulary's own smallest and largest for the wraps) rather than by position in the list, which is the divergence the next two paragraphs are about.

Anchored on the resolved EXTENT rather than on a stored vocabulary index, which is this engine's one deliberate divergence: a stored index lets a short template vocabulary rewrite an anchor's original intent, so the index was removed. For an ascending list (every shipped default, and every list a user would plausibly type) the two rules agree entry for entry — a list typed out of size order cycles in SIZE order here and in TYPED order under niri.

Both the pick and the WRAP are by extent, not by position, and that is what makes the SIZE-order claim above true. Order is NOT guaranteed: the settings schema's canonicalProportionList deduplicates what a user types but preserves their order, refreshConfigFromSettings' parser and the per-screen override path neither sort nor deduplicate, and only the template channel arrives sorted (phosphor-zones normalizePresetList). So a list typed as e.g. 1/2, 1/3, 2/3 keeps its narrowest entry in the middle. Wrapping to position 0 there would hand a forward press the MIDDLE entry and leave the narrowest reachable only backwards.

resolve maps a vocabulary index to the pixel extent that entry would render at. Returns -1 for an empty vocabulary.

◆ isVerticalTabIndicator()

bool PhosphorScrollEngine::isVerticalTabIndicator ( TabIndicatorPosition position)
inline

True when position puts the indicator on a vertical edge, so its long axis is the column's HEIGHT and its thickness eats the column's WIDTH.

Free function rather than a member so the enum stays a plain wire type.

◆ nearestPresetIndex()

int PhosphorScrollEngine::nearestPresetIndex ( const QList< qreal > & presets,
qreal fraction )
inline

Shared nearest-entry resolution for the fraction anchors above — the ONE implementation behind preset resolution, cycling, and height-fraction probes (it replaced three per-site variants).

An EMPTY list answers -1, not 0: every other answer is a valid index into presets, and handing back an out-of-range 0 made the empty case look like a hit that a caller would then use to subscript. Every in-tree caller bails on an empty list before reaching here, so the guard is the belt for the one that does not.

◆ nearestPresetValue()

qreal PhosphorScrollEngine::nearestPresetValue ( const QList< qreal > & presets,
qreal fraction,
qreal fallback = 0.5 )
inline

The nearest entry's VALUE.

An empty list returns fallback, matching the old presetAt clamp's 0.5 answer.

◆ proportionalPx()

int PhosphorScrollEngine::proportionalPx ( qreal proportion,
int workExtent,
int gap )
inline

A proportion resolves against the work extent PLUS one gap so that proportions summing to 1 tile edge-to-edge with the gaps between them (0.5 + 0.5 across a 1000px area with a 10px gap → 495 + 10 + 495).

Lives here rather than in relayout's anonymous namespace because the preset CYCLES have to resolve a vocabulary entry to the very pixels relayout will lay it out at — a second copy of this rounding is exactly the drift that makes a cycle press land one entry off.

◆ visibleColumnsOf()

QVector< const ResolvedColumn * > PhosphorScrollEngine::visibleColumnsOf ( const ResolvedStrip & resolved,
const QRect & workArea )
inline

The columns of resolved that intersect workArea, in strip order.

Single definition of "visible" on purpose. The drag-insert hit-test and the edge auto-scroll's target writer both need it, and the auto-scroll's owned target is only coherent with the hit-test while the two agree: if one drifted, the owned target would name a column the hit-test does not consider visible and the painted indicator would disagree with the drop. The returned pointers alias resolved and are valid only as long as it is.

Variable Documentation

◆ MinColumnWidthFraction

qreal PhosphorScrollEngine::MinColumnWidthFraction = 0.05
inlineconstexpr

The narrowest column width this engine will accept as a proportion of the work area.

Every producer of a proportion clamps or validates against it: the config read, the per-screen rule override, the per-window open rule, the preset list, and the persisted-blob boundary.

KEEP IN SYNC with ConfigDefaults::scrollingDefaultColumnWidthProportionMin and the rules-side PhosphorRules::MinColumnWidthRatio. Neither is reachable from here — ConfigDefaults is app-side, and PhosphorRules is a library this one does not link (the dependency runs the other way) — so the bound is hand-mirrored, but at least it is hand-mirrored once.

◆ MinWindowHeightFraction

qreal PhosphorScrollEngine::MinWindowHeightFraction = 0.05
inlineconstexpr

The shortest tile height this engine will accept as a proportion of the work area.

The height twin of MinColumnWidthFraction, deliberately its own name: the two bounds happen to share a value today, and a caller that clamps a HEIGHT against the width constant would silently follow a later width-only change. KEEP IN SYNC with PhosphorRules::MinColumnWidthRatio (ActionParams.h), which the rules-side height validation currently uses for BOTH fractions; like the width constant above, the bound is hand-mirrored because the dependency runs the other way.