From 9a58e5117afa2df6bfbe544a1c40f2534935f094 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Thu, 29 Oct 2026 14:10:39 -0700 Subject: [PATCH] docs(pan): document panning the scrolling layout --- docs/cli/center-focus.md | 5 ++- docs/cli/pan.md | 45 +++++++++++++++++++++++++++ docs/usage/scrolling-layout.md | 56 +++++++++++++++++++++++++++++++++- komorebic/src/main.rs | 5 ++- mkdocs.yml | 1 + 5 files changed, 105 insertions(+), 7 deletions(-) create mode 100644 docs/cli/pan.md diff --git a/docs/cli/center-focus.md b/docs/cli/center-focus.md index 5d256376..37450a12 100644 --- a/docs/cli/center-focus.md +++ b/docs/cli/center-focus.md @@ -1,10 +1,9 @@ # center-focus ``` -Centre the user focus on the screen, once +Scroll the Scrolling layout so that the focused column is in the middle of the screen, once -In the Scrolling layout the screen scrolls so that the focused column is in the middle of it. Only -the Scrolling layout scrolls, so this does nothing in the other layouts. +Only the Scrolling layout scrolls, so this does nothing in the other layouts. Usage: komorebic center-focus diff --git a/docs/cli/pan.md b/docs/cli/pan.md new file mode 100644 index 00000000..40ad7c22 --- /dev/null +++ b/docs/cli/pan.md @@ -0,0 +1,45 @@ +# pan + +``` +Move the view of the Scrolling layout a column to the left or the right, or with the fingers on a +touchpad + +The strip of columns moves by the width of a new column and comes to rest with a column against an +edge of the screen. Focus stays on the column that has it if that is still fully in view, and +otherwise goes to the nearest column that is. Only the Scrolling layout has a strip to move, so this +does nothing in the other layouts. + +With --stream the strip follows the fingers as they go, 10 centimetres of travel being the width of +the screen, until they lift, and then comes to rest in the column that the speed that they lifted at +takes it to. Standard input is the gesture stream that whkd writes on Windows, one message to a +line: `begin`, `move dx= t=`, `end` and `cancel`. A gesture that is not finished when +standard input closes is given up, and the strip goes back to where it was. + +Usage: komorebic pan [OPTIONS] [DIRECTION] + +Arguments: + [DIRECTION] + The way that the view goes + + [possible values: left, right] + +Options: + --stream + Read the gestures of fingers on a touchpad from standard input, in the gesture stream that + whkd writes for a swipe of three or four fingers, and pan with them + + --sensitivity + What the distances of a gesture are multiplied by, which is 1 if it is left out, with + --stream + + --reversed + Go the other way to the fingers, with --stream + + --paging + Take a step for every two centimetres that the fingers go, and not move the view with + them, with --stream + + -h, --help + Print help (see a summary with '-h') + +``` \ No newline at end of file diff --git a/docs/usage/scrolling-layout.md b/docs/usage/scrolling-layout.md index c3e99883..c672c9ff 100644 --- a/docs/usage/scrolling-layout.md +++ b/docs/usage/scrolling-layout.md @@ -2,7 +2,9 @@ In the Scrolling layout every window is a column in a row that is as long as it needs to be, and the screen is a viewport onto a part of it. A new window is added to the right of the focused one. Nothing is squeezed to make it fit: -the row gets longer, and the screen scrolls to follow your focus. +the row gets longer, and the screen scrolls to follow your focus. Every workspace that uses the layout has a row of +its own, and the screen of the monitor that shows it is the viewport onto it, so each monitor has a strip of its own, +and focus and move commands carry on to the next monitor when they reach the end of one. ```json { @@ -132,6 +134,58 @@ and the screen scrolls back to where it was. If you have, focus goes to the wind on the right, or to the one before it if there is none. A window that is closed without having focus does not take focus with it. +## Panning + +[`komorebic pan`](../cli/pan.md) moves the view along the row without moving focus first. `pan left` brings what is to +the left of the screen into view, and `pan right` what is to the right, by the width of a new column. The row comes to +rest with a column against an edge of the screen, and focus goes to the nearest column that is fully on the screen if the +focused one has gone off it. With [animations](animations.md) on, the windows glide to where the row rests. + +``` +alt + shift - 0x2B : komorebic pan left # 0x2B is , +alt + shift - 0x2F : komorebic pan right # 0x2F is . +``` + +It does nothing in the other layouts. + +### With the fingers on a touchpad + +`komorebic pan --stream` reads the gestures of fingers on a touchpad from standard input and moves the view with them: +the row follows the fingers while they are down, and when they lift it comes to rest with a column against an edge of the +screen, the one that the speed that the fingers lifted at takes it to. + +Nothing in komorebi for Mac writes that stream yet, and skhd has no bindings for swipes, so it takes a program that reads +the touchpad and writes it, with its output piped in: + +``` +touchpad-gestures | komorebic pan --stream +``` + +The stream is the gesture stream that [whkd](https://github.com/LGUG2Z/whkd) writes on Windows, so a program that +writes it works on either: a line for each `begin`, `move`, `end` and `cancel`, a name and then `key=value` fields in any +order, with the distances in centimetres and the times in milliseconds on a clock of the program's own, since only the +differences between them mean anything. `move` needs `dx` and `t`, and `dy` is not used. Fields and messages that are not +known are ignored. + +``` +begin fingers=3 x=4.000 y=2.000 t=118337 +move dx=0.420 dy=-0.030 x=4.420 y=1.970 t=118345 +move dx=0.510 dy=-0.020 x=4.930 y=1.950 t=118353 +end x=5.400 y=1.950 t=118369 +``` + +- A swipe of 10 centimetres across the touchpad moves the row the width of the screen, and the row can be pulled up to + a screen's width past either end, from where it comes back when the fingers lift. `--sensitivity` multiplies the + distances, and `--reversed` makes the row go the other way to the fingers. +- With `--paging` the row does not follow the fingers: it takes a step, as `komorebic pan` does, for every two + centimetres that they go. +- A gesture that is given up, or whose stream stops, puts the row back to where it was, and so does one that moves again + after you changed workspace. One that ends after you changed workspace lets the row of the workspace that it began on + come to rest instead. Vertical movement is not used. +- The windows are moved as the fingers go, a few at a time, so one that belongs to an app that is slow to resize lags + behind them. +- It does nothing in the other layouts. + ## Resizing [`komorebic resize-edge`](../cli/resize-edge.md) and [`komorebic resize-axis`](../cli/resize-axis.md) change the width of diff --git a/komorebic/src/main.rs b/komorebic/src/main.rs index c5882ff6..88f62916 100644 --- a/komorebic/src/main.rs +++ b/komorebic/src/main.rs @@ -1020,10 +1020,9 @@ enum SubCommand { ScrollingLayoutColumns(ScrollingLayoutColumns), /// Make the focused column of the Scrolling layout as wide as the screen, or put it back ScrollingLayoutFullWidth, - /// Centre the user focus on the screen, once + /// Scroll the Scrolling layout so that the focused column is in the middle of the screen, once /// - /// In the Scrolling layout the screen scrolls so that the focused column is in the middle of - /// it. Only the Scrolling layout scrolls, so this does nothing in the other layouts. + /// Only the Scrolling layout scrolls, so this does nothing in the other layouts. CenterFocus, /// Make the focused column of the Scrolling layout fill the room that the columns in view /// leave on the screen, which does nothing in any other layout diff --git a/mkdocs.yml b/mkdocs.yml index 0190e554..320234fe 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -155,6 +155,7 @@ nav: - cli/promote-focus.md - cli/center-focus.md - cli/expand.md + - cli/pan.md - cli/promote-window.md - cli/retile.md - cli/display-index-preference.md