Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
ScrollStrip.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
8#include "phosphorscrollengine_export.h"
9
10#include <QSize>
11#include <QString>
12#include <QStringList>
13#include <QVector>
14
15#include <optional>
16
17namespace PhosphorScrollEngine {
18
99class PHOSPHORSCROLLENGINE_EXPORT ScrollStrip
100{
101public:
102 ScrollStrip() = default;
103
104 // ── Introspection ────────────────────────────────────────────────────────
105 const QVector<Column>& columns() const
106 {
107 return m_columns;
108 }
109 int columnCount() const
110 {
111 return m_columns.size();
112 }
113 bool isEmpty() const
114 {
115 return m_columns.isEmpty();
116 }
118 {
119 return m_activeColumnIdx;
120 }
121 const Column* activeColumn() const;
138 QString activeWindowId() const;
140 int columnOfWindow(const QString& windowId) const;
141 bool containsWindow(const QString& windowId) const
142 {
143 return columnOfWindow(windowId) != -1;
144 }
145
148 QStringList windowsInOrder() const;
149 int windowCount() const;
150 // ── Structure: open / close / minimize ──────────────────────────────────
159 bool insertWindow(const QString& windowId, const ColumnWidth& width, ColumnDisplay display,
160 const ScrollLayoutParams& params, int minWidth = 0, int minHeight = 0,
172 bool insertWindowIntoActiveColumn(const QString& windowId, const ColumnWidth& width,
173 std::optional<ColumnDisplay> displayOverride, const ScrollLayoutParams& params,
174 int minWidth = 0, int minHeight = 0);
189 bool insertWindowAt(int columnIndex, const QString& windowId, const ColumnWidth& width, ColumnDisplay display,
190 const ScrollLayoutParams& params);
209 bool insertWindowIntoColumnAt(int columnIndex, int tileIndex, const QString& windowId,
210 const ScrollLayoutParams& params, int minWidth = 0, int minHeight = 0,
211 std::optional<ColumnDisplay> displayOverride = std::nullopt);
216 bool removeWindow(const QString& windowId, const ScrollLayoutParams& params);
229 bool setWindowMinimized(const QString& windowId, bool minimized, const ScrollLayoutParams& params);
230 bool isWindowMinimized(const QString& windowId) const;
232 bool setWindowMinimumSize(const QString& windowId, int minWidth, int minHeight);
234 QSize windowMinimumSize(const QString& windowId) const;
235
236 // ── Focus ────────────────────────────────────────────────────────────────
238 bool focusColumn(int columnIndex, const ScrollLayoutParams& params);
240 bool focusAdjacentColumn(int delta, const ScrollLayoutParams& params);
246 bool focusAdjacentTile(int delta);
249 bool focusTileAtEnd(bool last);
255 bool focusTileByOrdinal(int ordinal);
259 bool focusWindow(const QString& windowId, const ScrollLayoutParams& params);
260
261 // ── Structure: move / consume / expel ───────────────────────────────────
263 bool moveActiveColumn(int delta, const ScrollLayoutParams& params);
266 bool moveActiveColumnTo(int target, const ScrollLayoutParams& params);
272 bool moveColumnTo(int from, int to, const ScrollLayoutParams& params);
282 bool moveActiveTile(int delta);
293 bool consumeOrExpel(int delta, const ScrollLayoutParams& params);
301 bool takeWindow(const QString& windowId, const ScrollLayoutParams& params);
302
303 // ── Sizing ───────────────────────────────────────────────────────────────
322 bool cycleActiveColumnPresetWidth(int delta, const ScrollLayoutParams& params);
335 bool adjustActiveColumnWidth(qreal deltaPercent, const ScrollLayoutParams& params);
368 bool toggleMaximizeColumnForWindow(const QString& windowId, const ScrollLayoutParams& params);
380 bool toggleMaximizeToEdgesForWindow(const QString& windowId, const ScrollLayoutParams& params);
385 bool setMaximizedToEdgesForWindow(const QString& windowId, bool maximized);
473 bool resetToDefaults(const std::optional<ColumnWidth>& defaultWidth,
474 const std::optional<WindowHeight>& defaultHeight, ColumnDisplay defaultDisplay,
475 const ScrollLayoutParams& params);
494 bool cycleActiveWindowPresetHeight(int delta, const ScrollLayoutParams& params);
504 bool adjustActiveWindowHeight(qreal deltaPercent, const ScrollLayoutParams& params);
627 bool reconcileWindowSize(const QString& windowId, const QSize& ackedSize, bool mainChanged, bool crossChanged,
628 const ScrollLayoutParams& params);
638 int windowColumnMainExtentPx(const QString& windowId, const ScrollLayoutParams& params) const;
648 int windowTileCrossExtentPx(const QString& windowId, const ScrollLayoutParams& params) const;
660 int tileCrossCapacityPx(const QString& windowId, const ScrollLayoutParams& params) const;
668 static int tabbedMainReservationPx(const Column& c, const ScrollLayoutParams& params);
676 static int tabbedCrossReservationPx(const Column& c, const ScrollLayoutParams& params);
677
678 // ── Display ──────────────────────────────────────────────────────────────
681
691 bool setWindowedFullscreen(const QString& windowId, bool on);
692 bool isWindowedFullscreen(const QString& windowId) const;
693
704 bool setWindowHeightIntent(const QString& windowId, const WindowHeight& height);
712 bool restateWindowHeightIntent(const QString& windowId, const WindowHeight& height);
713
720 WindowHeight windowHeightIntent(const QString& windowId) const;
721
728 bool setTabbedHeightOwner(const QString& windowId);
729
735 QVector<int> visibleColumnIndices(const ScrollLayoutParams& params) const;
736
745 QVector<int> fullyVisibleColumnIndices(const ScrollLayoutParams& params) const;
746
753
773 int rotateVisibleColumns(bool clockwise, const ScrollLayoutParams& params);
774
775 // ── View ─────────────────────────────────────────────────────────────────
778 int viewAnchor() const
779 {
780 return m_viewAnchor;
781 }
782
785 bool viewDetached() const
786 {
787 return m_viewDetached;
788 }
789
799 void setViewDetached(bool detached)
800 {
801 m_viewDetached = detached;
802 }
803
816 void restoreViewAnchor(int anchor, const ScrollLayoutParams& params);
836 void reanchorForDropCommit(int oldViewOffset, const ScrollLayoutParams& params);
854 {
855 int leading = 0;
856 int trailing = 0;
857 };
864 void clampViewOverhang(const ScrollLayoutParams& params, int keepLeading, int keepTrailing);
890 bool scrollViewBy(int delta, const ScrollLayoutParams& params);
891
903 int predictedFocusScrollPx(int columnIndex, const ScrollLayoutParams& params) const;
904
905 // ── Relayout ─────────────────────────────────────────────────────────────
909
923
933 bool stripFitsViewport(const ScrollLayoutParams& params) const;
934
945
946 // ── Pixel resolution helpers (shared with the engine/tests) ─────────────
949 static int resolveColumnWidthPx(const ColumnWidth& width, const ScrollLayoutParams& params);
950
951private:
952 // scrollstrip_sizing.cpp
962 int activeTileCrossPx(const ScrollLayoutParams& params) const;
982 int activeColumnCrossBudgetPx(const ScrollLayoutParams& params) const;
993 int activeWindowHeightFloorPx(const ScrollLayoutParams& params) const;
1011 static bool claimTabbedHeightOwnership(Column& c, int tileIdx, const WindowHeight& incoming);
1016 static bool applyColumnDisplay(Column& c, ColumnDisplay display);
1019 bool toggleMaximizeColumnAt(int columnIndex, const ScrollLayoutParams& params);
1023 bool toggleMaximizeToEdgesAt(int columnIndex, const ScrollLayoutParams& params);
1024
1025 // scrollstrip_structure.cpp
1026 Column* activeColumnMutable();
1027 Tile* activeTileMutable();
1028 void clampActiveIndices();
1029 void removeColumnAt(int columnIndex);
1033 bool removeWindowInternal(const QString& windowId, const ScrollLayoutParams& params, bool refocus);
1034 // scrollstrip_relayout.cpp
1037 int columnExtentPx(const Column& c, const ScrollLayoutParams& params) const;
1046 int columnMinExtentPx(const Column& c, const ScrollLayoutParams& params) const;
1051 static int committedMainFloorPx(const QString& windowId, const ScrollLayoutParams& params);
1059 static int tileMinCrossPx(const Tile& t, const Column& c, const ScrollLayoutParams& params);
1070 static int tabbedColumnCrossPx(const Column& c, const ScrollLayoutParams& params);
1072 int columnStripPos(int columnIndex, const ScrollLayoutParams& params) const;
1074 int stripExtentPx(const ScrollLayoutParams& params) const;
1076 int viewOffsetFor(const ScrollLayoutParams& params) const;
1078 int centeredAnchorFor(int columnIndex, const ScrollLayoutParams& params) const;
1082 int clampedAnchor(int anchor, const ScrollLayoutParams& params) const;
1086 int clampedAnchorFor(int columnIndex, int anchor, const ScrollLayoutParams& params) const;
1092 int focusAnchorFor(int targetIdx, int prevIdx, int oldViewOffset, const ScrollLayoutParams& params) const;
1101 int keepOrRecenterAnchor(int oldViewOffset, const ScrollLayoutParams& params);
1108 void reanchorAfterFocusChange(int prevIdx, int oldViewOffset, const ScrollLayoutParams& params);
1114 void noteActiveColumnChanged()
1115 {
1116 m_viewDetached = false;
1117 }
1125 bool reattachViewIf(bool changed)
1126 {
1127 if (changed) {
1128 m_viewDetached = false;
1129 }
1130 return changed;
1131 }
1132
1133 QVector<Column> m_columns;
1134 int m_activeColumnIdx = -1;
1136 int m_viewAnchor = 0;
1139 bool m_viewDetached = false;
1159 ColumnWidth m_preMaximizeWidth;
1160 int m_preMaximizeColumnIdx = -1;
1161};
1162
1163} // namespace PhosphorScrollEngine
bool adjustActiveWindowHeight(qreal deltaPercent, const ScrollLayoutParams &params)
Adjust the active tile's height by deltaPercent of the work area's CROSS extent.
QVector< int > fullyVisibleColumnIndices(const ScrollLayoutParams &params) const
Strip indices of the columns lying ENTIRELY inside the viewport, in strip order — the stricter twin o...
bool setMaximizedToEdgesForWindow(const QString &windowId, bool maximized)
Restore-path setter for the column owning windowId: a stash claim re-asserting the state it captured,...
int activeColumnIndex() const
Definition ScrollStrip.h:117
bool expandActiveWindowToAvailableHeight(const ScrollLayoutParams &params)
Grow the active tile into the empty cross space left in its column.
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 int...
bool toggleMaximizeColumnForWindow(const QString &windowId, const ScrollLayoutParams &params)
The same verb aimed at the column OWNING windowId rather than at the active one.
ResolvedStrip relayout(const ScrollLayoutParams &params) const
Resolve every non-minimized tile's absolute pixel rect against params.
bool removeWindow(const QString &windowId, const ScrollLayoutParams &params)
Remove windowId; a column left empty closes up.
ViewOverhang viewOverhang(const ScrollLayoutParams &params) const
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 ...
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 scrol...
bool focusWindow(const QString &windowId, const ScrollLayoutParams &params)
Make windowId the active tile of its (newly active) column.
int columnOfWindow(const QString &windowId) const
Column index owning windowId, or -1.
bool setWindowedFullscreen(const QString &windowId, bool on)
Direct flag write for windowId (any tile, not just the active one) — compositor-driven reconciliation...
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-ex...
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 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 alo...
bool containsWindow(const QString &windowId) const
Definition ScrollStrip.h:141
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 resol...
bool focusFirstColumn(const ScrollLayoutParams &params)
bool cycleActiveColumnPresetWidth(int delta, const ScrollLayoutParams &params)
Cycle the active column through the preset width list.
int rotateVisibleColumns(bool clockwise, const ScrollLayoutParams &params)
Rotate the window contents of the VISIBLE columns through their slots (clockwise = every stack shifts...
bool toggleActiveWindowedFullscreen()
Toggle windowed fullscreen on the active tile of the active column.
bool setWindowMinimized(const QString &windowId, bool minimized, const ScrollLayoutParams &params)
Mark a tile minimized (kept in order, excluded from layout) or restore it.
void restoreViewAnchor(int anchor, const ScrollLayoutParams &params)
Restore a previously captured view anchor, RAW: a centered anchor implies an out-of-range derived vie...
bool viewDetached() const
Whether an explicit pan owns the view instead of the centering policy (see the class doc).
Definition ScrollStrip.h:785
bool stripSettledInViewport(const ScrollLayoutParams &params) const
stripFitsViewport AND the derived view offset is settled inside [0, stripExtent - viewport] — i....
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 m...
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...
bool centerActiveColumn(const ScrollLayoutParams &params)
Center the active column in the view (niri center-column).
bool moveActiveColumnTo(int target, const ScrollLayoutParams &params)
Move the active column directly to target (one list move + one reanchor — a positional move must not ...
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.
const Column * activeColumn() const
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...
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-widt...
bool isWindowMinimized(const QString &windowId) const
bool focusTileByOrdinal(int ordinal)
Focus the ordinal'th (1-based) non-minimized tile of the active column, which is that ordinal's tab w...
bool scrollViewBy(int delta, const ScrollLayoutParams &params)
Scroll the view delta pixels forward ALONG THE STRIP (negative scrolls back towards its start) WITHOU...
bool setWindowHeightIntent(const QString &windowId, const WindowHeight &height)
Direct height-intent write for windowId (any tile, not just the active one).
bool consumeWindowIntoColumn(const ScrollLayoutParams &params)
Pull the next column's active tile onto the END of the active column's stack (niri consume-window-int...
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 st...
bool expelWindowFromColumn(const ScrollLayoutParams &params)
Push the active tile out into its own new column immediately AFTER the current one along the strip (n...
bool isCenteringActiveColumn(const ScrollLayoutParams &params) const
Whether the layout policy pins the ACTIVE column to the middle of the viewport, so its on-screen posi...
bool stripFitsViewport(const ScrollLayoutParams &params) const
True when the whole strip already fits the viewport, i.e.
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 ...
bool cycleActiveWindowPresetHeight(int delta, const ScrollLayoutParams &params)
Cycle the active tile through the preset height list.
bool moveActiveColumn(int delta, const ScrollLayoutParams &params)
Swap the active column with its neighbour. delta is -1/+1.
bool setWindowMinimumSize(const QString &windowId, int minWidth, int minHeight)
Update a tile's stored minimum size. Returns true when it changed.
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 tabbedMainRes...
bool minimizeActiveColumnWidth(const ScrollLayoutParams &params)
The active column at its narrowest: the smallest preset, or MinColumnWidthFraction when the preset li...
bool minimizeActiveWindowHeight(const ScrollLayoutParams &params)
The active tile at its shortest: the smallest preset height, or MinWindowHeightFraction of the work a...
void setViewDetached(bool detached)
The other half of restoreViewAnchor: re-assert a captured detachment.
Definition ScrollStrip.h:799
bool setActiveWindowHeight(const WindowHeight &height)
Set the active tile's height intent, verbatim.
bool setActiveColumnWidth(const ColumnWidth &width)
Set the active column's width intent, verbatim, dropping a maximize-to-edges override (the drop alone...
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 ke...
QSize windowMinimumSize(const QString &windowId) const
The tile's minimum frame size (Tile::minWidth), or 0x0 when untracked.
QStringList windowsInOrder() const
All windows in strip order (column order along the strip, then each column's stack order across it),...
bool toggleMaximizeToEdgesActiveColumn(const ScrollLayoutParams &params)
Toggle the active column's maximize-to-edges state (niri maximize-window-to-edges,...
bool toggleMaximizeActiveWindowHeight(const ScrollLayoutParams &params)
Toggle the active tile between filling its column's cross budget and the height it had before,...
bool focusAdjacentColumn(int delta, const ScrollLayoutParams &params)
Focus the adjacent non-fully-minimized column. delta is -1/+1.
int columnCount() const
Definition ScrollStrip.h:109
bool moveActiveTile(int delta)
Reorder the active tile within its column by delta positions.
bool setTabbedHeightOwner(const QString &windowId)
Make windowId's tab the one whose height decides its TABBED column's cross extent.
bool isWindowedFullscreen(const QString &windowId) const
bool toggleActiveColumnTabbed()
Toggle the active column between Normal and Tabbed presentation.
void reanchorForDropCommit(int oldViewOffset, const ScrollLayoutParams &params)
Drag-drop re-anchor (ScrollEngine::commitDragInsertPreview): land the just-dropped ACTIVE column at t...
bool focusAdjacentTile(int delta)
Focus the previous/next non-minimized tile within the active column, stopping at either end (ScrollEn...
bool toggleMaximizeActiveColumn(const ScrollLayoutParams &params)
Full work-area MAIN extent, still tiled (niri maximize-column).
bool takeWindow(const QString &windowId, const ScrollLayoutParams &params)
Remove windowId with no focus policy beyond index fixups — the cross-context transfer / float path (t...
bool centerVisibleColumns(const ScrollLayoutParams &params)
Center the span of FULLY visible columns in the view (niri center-visible-columns).
WindowHeight windowHeightIntent(const QString &windowId) const
The height intent windowId's tile carries, or a default-constructed (Auto) one for an unknown window.
bool expandActiveColumnToAvailableWidth(const ScrollLayoutParams &params)
Grow the active column into the on-screen MAIN-axis space not taken by the FULLY visible columns at t...
bool focusColumn(int columnIndex, const ScrollLayoutParams &params)
Focus a column by index (clamped; active tile within it unchanged).
bool focusLastColumn(const ScrollLayoutParams &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,...
bool focusTileAtEnd(bool last)
Focus the first (last false) or last non-minimized tile of the active column (niri focus-window-top/b...
bool moveActiveColumnToLast(const ScrollLayoutParams &params)
void clampViewIntoStrip(const ScrollLayoutParams &params)
Drag-begin settle (ScrollEngine::beginDragInsertPreview): after the detach take shortens the strip,...
bool moveActiveColumnToFirst(const ScrollLayoutParams &params)
QString activeWindowId() const
The focused window: the active tile of the active column, or empty.
bool equalizeActiveColumnHeights()
Back to the even auto-split for EVERY tile in the active column: the height twin of equalizeVisibleCo...
bool restateWindowHeightIntent(const QString &windowId, const WindowHeight &height)
setWindowHeightIntent for a REMEMBERED intent re-stated on the way back into a column (an unfloat,...
const QVector< Column > & columns() const
Definition ScrollStrip.h:105
bool equalizeVisibleColumnWidths(const ScrollLayoutParams &params)
Give every visible column an equal share of the work area's MAIN extent (Karousel equalize; niri has ...
QVector< int > visibleColumnIndices(const ScrollLayoutParams &params) const
Strip indices of the columns currently intersecting the viewport, in strip order — a viewport-interse...
bool isEmpty() const
Definition ScrollStrip.h:113
bool toggleMaximizeToEdgesForWindow(const QString &windowId, const ScrollLayoutParams &params)
The same verb aimed at the column OWNING windowId, for the compositor's maximize interception — toggl...
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 r...
int viewAnchor() const
The stored active-relative view anchor (see class doc).
Definition ScrollStrip.h:778
void updateViewForFocus(const ScrollLayoutParams &params)
Re-apply the centering policy to the current active column (settings change / work-area change) using...
Definition ScrollEngine.h:46
ScrollInsertPosition
Where a fresh-opened window's new column enters the strip (config default; the openColumnPlacement wi...
Definition ScrollTypes.h:513
@ RightOfActive
Definition ScrollTypes.h:514
ColumnDisplay
How a column presents its tiles (niri's column display).
Definition ScrollTypes.h:246
Column width INTENT — the source of truth the strip stores.
Definition ScrollTypes.h:528
One column: a stack of tiles ACROSS the strip (vertical on a horizontal strip, horizontal on a vertic...
Definition ScrollTypes.h:850
A full relayout pass over one strip.
Definition ScrollTypes.h:1151
Inputs a relayout resolves pixel rects against.
Definition ScrollTypes.h:977
The whole strip of one screen as a renderer of a strip MAP needs it: every column with its strip posi...
Definition ScrollEngineTypes.h:272
How far the view hangs past each end of the strip, in main-axis px: leading before the first column (...
Definition ScrollStrip.h:854
int trailing
Definition ScrollStrip.h:856
int leading
Definition ScrollStrip.h:855
One window in a column.
Definition ScrollTypes.h:766
Tile height INTENT within a column (its extent ACROSS the strip).
Definition ScrollTypes.h:596