docs(scrolling): the scrolling layout, and what changed in the design docs

docs/usage/scrolling-layout.md says how the columns work. The design docs
say what the strip is, where a window out of view rests, and that the
generated tables of COMPARE.md are to be made again.
This commit is contained in:
LGUG2Z committed 2026-10-30 14:44:54 -07:00
1 parent e42a86454c
commit 76c97fb4e1
9 files changed
+265 -38

No files matched your search

+21 -10
View File
@@ -536,17 +536,28 @@ still takes the windows that open into containers, and they are tiled when it is
`LayoutRatios` and `ScrollingLayoutColumns` set the focused workspace's [`LayoutOptions`]
([`Workspace::layout_options`]): the share of the work area its first columns and rows take, and
the number of columns of the scrolling layout in view. The layout calculates the tiles from
them, and from the tiles it calculated last ([`Workspace::latest_layout`]), which the scrolling
layout scrolls from.
them, and from the tiles it calculated last ([`Workspace::latest_layout`]).
The scrolling layout is a strip of columns that runs past the edges of the work area. Its tiles
are the only ones [`Workspace::update`] does not clamp to the work area, so the windows of the
columns out of view are off the screen; a window whose tile is out of view while part of it is
in view is centered in the work area first. A `FocusChange` tiles a scrolling workspace after the
focused container has changed, which scrolls the strip to it. KWin keeps part of a window it
resizes on an output, so the bridge asks again for the position of a window KWin pulled back
within a second of the command, three times at most ([`bridge.js`]'s `settle`), unless the window
is maximized meanwhile.
The scrolling layout is a strip of columns that runs past the edges of the work area, and a column
can hold several windows ([the scrolling layout](../usage/scrolling-layout.md), and
[scrolling-next.md](scrolling-next.md) for where it comes from). Each workspace keeps a
`ScrollingSpace` of `komorebi-scrolling` ([`Workspace::scrolling`]), made on the first layout
and keyed by the id of each container; [`Workspace::update`] makes it match the containers and the
focus, and asks it where every container goes ([`Workspace::layout_scrolling`]). Its tiles are the
only ones [`Workspace::update`] does not clamp to the work area. `consume`, `expel`,
`toggle-column-stack`, `scrolling-layout-full-width`, `center-focus`, `expand` and `pan` act on
the strip, and `focus`, `move`, `resize-*` and `retile` go through it in this layout; a container
that leaves a workspace leaves what its column was given for the next one to find
(`note_scrolling_departure`). A window that is out of view rests at the edge it left by with five
pixels of it on the screen and keeps its size (`parked`), or is hidden ([`Window::hide`]) where
that edge has another monitor next to it (`rest`), because KWin shows a window on every monitor it
overlaps. A `FocusChange` tiles a scrolling workspace after the focused container has changed,
which scrolls the strip to it. A window that did not get as narrow as its column is widens the
column, at the first layout 400 ms after the windows were sent (`adopt_actual_widths`: the frame
comes back from KWin a moment after the command). A drag of an edge keeps the strip with the rest
of what it started from ([`LiveResize`]). KWin keeps part of a window it resizes on an output, so
the bridge asks again for the position of a window KWin pulled back within a second of the
command, three times at most ([`bridge.js`]'s `settle`), unless the window is maximized meanwhile.
`Promote` moves the focused container to index 0, the largest tile of every layout but the grid,
through `LockableSequence`, so the containers before it move one index on
+13 -10
View File
@@ -53,8 +53,9 @@ Terms used below:
- **A workspace** is komorebi's name for one of the desktops of a monitor, in all three programs.
- **A parking desktop** is a KWin virtual desktop that nobody looks at, which kfde moves windows to
in order to hide them.
- **The strip** is the scrolling layout of kfm, in the crate `komorebi-scrolling`. It is not the
`Scrolling` layout of `komorebi-layouts`.
- **The strip** is the scrolling layout of kfm, in the crate `komorebi-scrolling`. Since upstream's
`next` branch it is also what the `Scrolling` layout of `komorebi-layouts` is laid out with, in
kfde too ([scrolling-next.md](scrolling-next.md)).
## What is the same
@@ -84,8 +85,9 @@ Compared file by file with the crate of kfw, kfm: 0 of 13 source files differ fr
The layouts of `komorebi-layouts` are calculated by the same code in the three programs, so the same
windows in the same order get the same rectangles, apart from what the window manager takes off for
the work area, the padding and the borders. The exception is the `Scrolling` layout of kfm, which kfm
lays out with the strip (see the section on configuration). What differs between the programs is
the work area, the padding and the borders. The exception is the `Scrolling` layout, which is laid
out with the strip of `komorebi-scrolling` in kfm and in kfde, and not in kfw before its `next`
branch (see the section on configuration). What differs between the programs is
what the system does with the rectangles: the next sections.
### One configuration file, largely portable
@@ -410,11 +412,13 @@ The nested structs have the same keys, except for these:
| `AnimationsConfig` | 5 | 4 | 4 | `ghost_movement` | - |
<!-- /gen:keys-nested -->
There is one more difference that is not a key. kfm has a scrolling strip, with columns that
hold several windows, a `scrolling` key and the commands in the "kfm scrolling strip" group above.
kfde has the `Scrolling` layout of `komorebi-layouts`, tuned with `layout_options` and the command
`scrolling-layout-columns`, which kfw and kfm have too. A `scrolling` key in a file written for kfm
is skipped by kfde.
There is one more difference that is not a key. kfm has a `scrolling` key. kfde has the `Scrolling`
layout of `komorebi-layouts`, which is laid out with the same strip as kfm's, with columns that hold
several windows and the commands `consume`, `expel`, `toggle-column-stack`,
`scrolling-layout-full-width`, `center-focus`, `expand` and `pan`, and is tuned with
`layout_options` and the command `scrolling-layout-columns`, which kfw and kfm have too. A
`scrolling` key in a file written for kfm is skipped by kfde. The generated tables above were made
before kfde took these commands: `scripts/compare-gen.py --update` makes them again.
## Events, and what drives them
@@ -793,7 +797,6 @@ From the tables above, and from what has no row in them:
- The Win32 workarounds of the "Win32 quirks" group, the AutoHotkey and PowerShell configurations,
the named-pipe subscribers, and whkd as a separate program.
- The license check and the splash screen of the macOS and Windows builds.
- kfm's scrolling strip: columns that hold several windows, and its commands.
- The tab and title bar commands (`remove-title-bar`, `toggle-title-bars`).
## What kfde has that kfw and kfm do not
+4 -3
View File
@@ -219,9 +219,10 @@ to the module that breaks how komorebi is installed or started fails the VM suit
KWin moves a window anywhere it is asked to, but when it resizes a window it keeps 100 pixels of
it on an output, and it does so once the client has drawn at the new size, which is after the
bridge has set the frame. The scrolling layout moves the windows of the columns out of view off
the screen and resizes them in the same command, and a terminal that rounds its size to its
cells is resized again by its client, so KWin pulls both back onto the screen. By then, setting
bridge has set the frame. The scrolling layout moves the windows of the columns out of view to the
edge of the work area, where a few pixels of them are on the screen, and resizes the ones that
change width in the same command, and a terminal that rounds its size to its cells is resized
again by its client, so KWin pulls both back onto the screen. By then, setting
the position alone is a plain move, which KWin honors. The bridge remembers where it was asked
to put a window for a second, and sets the position again when the window's frame changes to
another one in that time ([PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame)). Three tries
+4 -2
View File
@@ -571,7 +571,7 @@ covers part of its neighbor's.
KWin moves a window anywhere it is asked to, off the screen too, but when it *resizes* a window
it keeps 100 pixels of it on an output, and it does that once the client has drawn at the new
size. A window that is moved off the screen and resized at once, as the scrolling layout does
with the columns out of view, is pulled back onto the screen a moment later; so is one whose
with the columns out of view that change width, is pulled back onto the screen a moment later; so is one whose
client rounds the size, as `foot` does. The bridge therefore remembers the position it was asked
for, for a second, and when the window's frame changes to another position in that time, asks
for the position again, which is a plain move. It tries three times at most, so a window that
@@ -938,4 +938,6 @@ they work or that they do not.
- The scrolling layout on a monitor that has another beside it. A strip spills onto the
neighbor when that monitor shows the same workspace number, and a window whose middle is on a
monitor that shows another desktop is not drawn. This is read from KWin's sources, not
checked with pixels.
checked with pixels. The layout no longer leaves a window there: one that would rest or
overhang past an edge with another monitor next to it is hidden, or cut down to its own work
area ([scrolling-next.md](scrolling-next.md)), which only the fake desktop has run.
+17
View File
@@ -44,3 +44,20 @@ is, whether it is hidden, how wide it really is) is a call to the backend in kfd
enough to follow a scroll without a flash. It is what stacks do.
- The 16 px tolerance of `2dff53095` against the clients of `client-geometry` (`foot` rounds to
cells, which is below it).
## What is tested, and where
- `komorebi/src/scrolling.rs`: the glue against a workspace with no desktop (widths, consume, expel,
moving a column, stacking and spreading out with the windows that are hidden, expanding, panning,
where a window rests, which monitors are the others, what a window that will not get narrow
says). The model itself has its tests in upstream's `komorebi-scrolling`.
- `komorebi/tests/scrolling.rs` and `layout_options.rs`: the commands through
`WindowManager::process_command` against the fake desktop, a strip next to another monitor, and a
drag of the left edge of a column.
- `komorebic/tests/cli.rs`: each new subcommand sends its message.
- `nix/tests/vm/lib/komorebi_vm/platforms/kde/extras/scrolling.py`, run by `vm-scrolling`: where KWin
keeps a window at the edge and the commands of the columns, in a real session. **Not run**: the VM
suites are verified later. What to look at first is that KWin leaves a window with a right edge
5 pixels inside the work area where it was put (the bridge's `settle` is what is meant to see to it),
and that `toggle-column-stack` parks and restores the right windows.
+8 -3
View File
@@ -182,9 +182,14 @@ per-output desktops.
## scrolling
The shared `scrolling` scenario (run by `core-e2e`) puts each window in view in turn. This suite is
about the windows that are not in view: where KWin keeps the columns that scroll off the screen,
and that the strip follows the focus. All of it is KWin's; it is the extra `scrolling.run`, with
no check dropped.
about the windows that are not in view: where KWin keeps the columns that scroll off the screen
(at an edge, with a few pixels of them on it), and that the strip follows the focus. It also runs
the commands of the columns of several windows (`pan`, `consume`, `toggle-column-stack`, `expel`,
`scrolling-layout-full-width`), which are kfde's and not in the shared scenario because komorebi
for Windows has them only on its `next` branch. All of it is KWin's; it is the extra
`scrolling.run`. The check that a window keeps the distance of a column from the one in view,
which the layout does not keep any more (a window rests at the edge), was replaced by two that it
rests there and keeps its width.
## stacks