refactor(repo): move the KDE and macOS docs under docs/ (pure move)

komorebi-for-kde/docs/ -> docs/linux/
komorebi-for-mac/docs/ -> docs/macos/

The Windows docs stay where they are (docs/). Renames only, so links and include paths
that named the old directories are broken at this revision; they are fixed in the revision
that fixes the paths of the whole layout move.
This commit is contained in:
LGUG2Z committed 2026-11-05 15:03:27 -08:00
1 parent 348cb7ae96
commit d781028a2a
390 files changed

No files matched your search

+95
View File
@@ -0,0 +1,95 @@
# Animation
komorebi can have a window slide to its new place when the layout changes, instead of jumping
there. It does not animate anything itself: a KWin effect, Geometry Change, animates a window
that a program or a script moves or resizes, and komorebi tells it how long the animation lasts
and how it eases.
Animation is off by default.
## Installing the effect
The effect is not part of KWin, and KWin finds effects when it starts: log out and in again after
installing it. On NixOS the flake's module installs it with komorebi, which is what
`services.komorebi.effects.animation.enable` does (it is on by default); the effect is built so
that KWin does not load it until komorebi asks.
[`installation.md`](../installation.md) has the module's options.
komorebi loads the effect when animation is turned on, and unloads it when it is turned off or
komorebi exits. A machine that does not have the effect has no animation: komorebi says so once
in its log, and windows jump to their places.
## Turning it on, and how long it lasts
[`komorebic animation`](../cli/animation.md) turns animation on or off, and
[`komorebic animation-duration`](../cli/animation-duration.md) sets how long it lasts, in
milliseconds: 250 by default.
```sh
komorebic animation enable
komorebic animation-duration 400
komorebic animation disable
```
Both take `--animation-type movement` to set the animation of windows going to their places apart
from the global setting, which is how the settings of one kind of animation win over the global
ones. Movement is the only kind there is. A global setting takes the settings of the kinds away.
```sh
komorebic animation enable --animation-type movement
komorebic animation-duration 600 --animation-type movement
```
[`komorebic animation-fps`](../cli/animation-fps.md) is accepted and does nothing: KWin animates
at the refresh rate of the screen.
## Easing
[`komorebic animation-style`](../cli/animation-style.md) sets the curve a window follows to its
place: `linear` by default, or one of the easings by name (`ease-out-expo`, `ease-in-out-sine`,
`ease-out-bounce`, ...; `komorebic animation-style --help` lists them). They are Qt's easing
curves, and a style is Qt's name for the curve with the "Ease" taken off (`EaseInOutSine` is
`InOutSine`). Like the others, it takes `--animation-type movement`.
```sh
komorebic animation-style --style ease-out-expo
komorebic animation-style --style ease-in-out-sine --animation-type movement
```
The stock Geometry Change always eases out exponentially. The build the flake installs also reads
the curve, which is what lets a style other than that one take effect; with the stock effect every
style looks like an ease out. A cubic Bézier, which only a configuration can name, is not one of
Qt's curves and is drawn as an ease out too.
## In komorebi.json
The `animation` key of [`komorebi.json`](configuration.md#animation) has the same settings:
`enabled`, `duration` and `style`, each either one value for every kind of animation or a value
for each kind (`{ "movement": true }`), and `fps`.
```json
{
"animation": {
"enabled": true,
"duration": 400,
"style": "EaseOutExpo"
}
}
```
The file sets them when the daemon starts and when the file changes. A file without the key leaves
the settings as they are, and one with it that leaves out `duration` or `style` leaves that one as
it is.
## What is animated
What is painted moves; the window does not. The frame KWin reports for a window, and so the frame
komorebi reads back, is the final one from the start of the animation, so komorebi never waits for
an animation to end. The window is not cross-faded as it changes size: it is a move and a resize,
not a change of what the window shows. An interactive move or resize by the user is not animated.
While the effect is loaded, windows that other programs move are animated too.
## What is put back
The effect keeps its settings in the user's `kwinrc`, in the group
`[Effect-kwin4_effect_geometry_change]`. komorebi writes them when it asks for the animation, and
when it exits or animation is turned off it puts back what the user had there.
@@ -0,0 +1,73 @@
# Application specific configuration
Some applications need to be told how to behave under a tiling window manager: a calculator that
should float instead of taking a tile, a launcher that should never be tiled. The
[rules](rules.md) that say so can be put in `komorebi.json`, or in a file of their own,
`applications.json`, that the configuration names. The file can be shared, or kept apart from
the settings, and a list of files can be put together from several sources.
## The file
`applications.json` is an object with one entry for each application. The name of the entry is
only for the reader. Each entry has lists of [rules](rules.md), as `komorebi.json` has them:
```json
{
"KDE Plasma": {
"floating": [
{ "kind": "Class", "id": "org.kde.kcalc", "matching_strategy": "Equals" },
{ "kind": "Class", "id": "org.kde.spectacle", "matching_strategy": "Equals" }
]
},
"Steam": {
"ignore": [{ "kind": "Exe", "id": "steam", "matching_strategy": "Equals" }]
}
}
```
| List | What it does | In `komorebi.json` |
|---|---|---|
| `ignore` | komorebi leaves the windows alone | `ignore_rules` |
| `manage` | komorebi tiles the windows, whatever the ignore rules say | `manage_rules` |
| `floating` | the windows open floating | `floating_applications` |
| `titleless`, `tabbed` | nothing: they work around how another platform exposes windows, and a KWin window is always a window | `titleless_applications`, `tabbed_applications` |
An entry named `$schema` has the address of a schema as its value, as an editor wants it, and
is ignored.
## Naming the file
`app_specific_configuration_path` in `komorebi.json` is the path of one file, or a list of paths:
```json
{
"app_specific_configuration_path": "$HOME/.config/komorebi/applications.json"
}
```
```json
{
"app_specific_configuration_path": [
"$HOME/.config/komorebi/applications.json",
"$HOME/.config/komorebi/mine.json"
]
}
```
Environment variables in a path, such as `$HOME`, are replaced. The files are read when
`komorebi.json` is: when the daemon starts, and again when the configuration changes. Their rules
are added to the ones the daemon has, after the rules of `komorebi.json` itself, which
[Configuration](configuration.md#rules) explains.
A path with no file behind it is skipped, and the daemon logs a warning: one `komorebi.json` can
serve every platform, even if it names a file that only another platform has. A file that is
there and is not an `applications.json`, or has a rule that is not valid, is an error: the daemon
does not start with it, and a reload with it fails and logs the error. Only a file with the
extension `.json` is read.
## The file komorebi ships
[`komorebic/applications.json`](../../komorebic/applications.json) in the repository has an
entry for KDE Plasma, which floats the calculators of KDE and GNOME, the screenshot tool, the
authentication dialog of Plasma and System Settings. A test loads it, and opens the windows it
names.
+110
View File
@@ -0,0 +1,110 @@
# Borders
komorebi puts a colored border around every window. It does not draw it: a KWin effect, KDE
Rounded Corners, draws the border outside each window, in the gap between the tiles, and komorebi
tells the effect how wide it is, how round the corners are and which color each window's border
has. The border around the window that has the focus is blue, and the border around every other
window is gray.
## Installing the effect
The effect is not part of KWin, and KWin finds effects when it starts: log out and in again after
installing it. On NixOS the flake's module installs it with komorebi, which is what
`services.komorebi.effects.borders.enable` does (it is on by default); the effect is built so that
KWin does not load it until komorebi asks.
[`installation.md`](../installation.md) has the module's options.
komorebi loads the effect when it starts and borders are on, and unloads it when it exits or the
borders are turned off. A machine that does not have the effect has no borders: komorebi says so
once in its log, and leaves no room for them.
## Turning borders on and off
[`komorebic border`](../cli/border.md) turns borders on or off. They are on by default.
```sh
komorebic border disable
komorebic border enable
```
## Colors
A window's border has the color of what the window is to the layout:
| Kind | Window | Default |
|---|---|---|
| `single` | the focused window | blue, `66 165 245` |
| `unfocused` | every other window | gray, `128 128 128` |
| `unfocused-locked` | a locked container that does not have the focus | red, `158 8 8` |
| `stack` | a stack that has the focus | green, `0 165 66` |
| `monocle` | a monocled window | pink, `255 51 153` |
| `floating` | a floating window that has the focus | yellow, `245 245 165` |
[`komorebic border-colour`](../cli/border-colour.md) sets the color of a kind, from its red,
green and blue, each from 0 to 255; without `--window-kind` it sets `single`.
```sh
komorebic border-colour 255 128 0
komorebic border-colour --window-kind unfocused 64 64 64
komorebic border-colour --window-kind floating 200 200 0
```
The stock KDE Rounded Corners has one color for the active window and one for the others. The
build the flake installs also takes a color for each window, which is what lets a locked, a
floating, a stack and a monocled window have colors of their own. With the stock effect every
kind is drawn as `single` or `unfocused`, whichever is closer, and komorebi says so once in its
log.
## Width and room
[`komorebic border-width`](../cli/border-width.md) sets how thick the border is, in pixels: 10 by
default. The effect draws at most 20 pixels, and draws the border only where a window has a shadow,
so a window with no shadow has no border.
While the borders are drawn, the layout leaves room for them: every tile gives up the width of the
border on each side, so that the border is drawn in the gap between two windows and does not fall
on the window next to it. [`komorebic border-offset`](../cli/border-offset.md) leaves more room
than the width, in pixels, which the effect draws nothing in. With borders off, or without the
effect, the layout leaves no room at all. A change of the width or the offset reaches the layout
the next time the workspace is tiled again, which [`komorebic retile`](../cli/retile.md) does.
```sh
komorebic border-width 6
komorebic border-offset 2
komorebic retile
```
## In komorebi.json
The same settings can be in [`komorebi.json`](configuration.md#borders): `border`, `border_width`
and `border_offset` are what the three commands above set, and `border_radius` is how round the
corners are, in pixels (10 by default), which has no command. The file sets them when the daemon
starts and when the file changes; a key it leaves out leaves the setting as it is.
```json
{
"border": true,
"border_width": 6,
"border_offset": 2,
"border_radius": 12
}
```
`border_colours` sets the colors of the kinds of window above, each as red, green and blue or as
a hex color, and leaves out the kinds it does not name. A [theme](themes.md), which the
`theme` key of the file gives too, replaces them.
```json
{
"border_colours": {
"single": { "r": 255, "g": 128, "b": 0 },
"unfocused": "#404040"
}
}
```
## What is put back
The effect keeps its settings in the user's `kwinrc`, in the group `[Round-Corners]`. komorebi
writes them when it asks for the border, and when it exits or the borders are turned off it puts
back what the user had there, also after a crash: the next run puts them back when it stops.
+81
View File
@@ -0,0 +1,81 @@
# Monitors that change
komorebi follows the outputs KWin has, and a change of them needs no command: this page says
what komorebi does when a monitor changes. The one thing to set is where a monitor goes in
komorebi's order, [`display_index_preferences`](#a-monitor-is-plugged-in).
## A monitor changes size
A monitor changes size when its resolution or its scale changes (in System Settings, under
Display & Monitor, or with `kscreen-doctor output.<name>.scale.1.5`), and when a panel changes
the room the windows have on it: a panel that starts, grows, moves or is hidden. komorebi reads
the size and the work area of every monitor again, and tiles the workspace in front on the
focused monitor in the area it now has.
The windows of the other monitors keep their tiles until something tiles them again.
[`komorebic retile`](../cli/retile.md) does it for every monitor.
KWin has no signal for the room a panel leaves, so komorebi looks at it when a panel opens,
closes or moves, and once a second. A panel that is laid out a moment after komorebi starts is
found within a second.
## A window is moved to another monitor
A window moves to another monitor when something other than komorebi moves it: a KWin shortcut
that sends the window to the next screen, the window menu, a drag with the pointer, or an
application. KWin tells komorebi, which finds every container and floating window that is on
another monitor than the one it has it on, and moves it to the workspace with the same number on
the monitor it is on. The monitors that windows moved between are tiled again.
A window is on the monitor whose area has the middle of its frame. A container is on the monitor
of the window that has the focus in it. A move komorebi made itself, with
[`komorebic move-to-monitor`](../cli/move-to-monitor.md) for one, is in komorebi's state already,
and finds nothing to do.
While the user drags a window with the pointer, komorebi moves nothing: where the window goes is
decided when they let go of it ([moving windows by dragging](moving-windows.md#by-dragging)).
## A monitor is unplugged
KWin takes the windows of an output that goes (it is unplugged, or disabled with
`kscreen-doctor output.<name>.disable`) to the outputs that are left, and puts them where it
likes. komorebi takes the monitor's workspaces over there: every container, and every floating
window, goes to the workspace with the same number on the monitor KWin put its window on, and
the workspaces that changed are tiled again. A [stack](stacking-windows.md) goes as a stack. A
monocle window comes as a tile of its own, and the windows the monocle hid are shown again. A
[maximized window](maximizing-windows.md) stays maximized, on the workspace it goes to; if that
workspace has a maximized window already, it goes back to its tile.
A moment after an output goes or comes back (1.5 seconds), komorebi looks at where every window
is once more, because KWin moves windows about for a while after the outputs change: the windows
it took to the monitor that is left may go back to the output that is plugged in again, and a
change of resolution or scale changes where the middle of a window is.
komorebi keeps the monitor that went, with its workspaces, layouts, paddings and offsets, for
when it comes back, and forgets the [workspace rules](workspace-rules.md) of its workspaces until
then. When no output is left at all, komorebi does nothing.
## A monitor is plugged in
komorebi knows a monitor by the manufacturer, the model and the serial number KWin reports for
the output, or by the output's name when it has no serial number. A monitor komorebi has kept
comes back with what was kept: its workspaces and their settings, and the wallpaper of the
monitor, less the windows that have closed or that are somewhere else now. Its windows were tiled
on other monitors when it went, so it comes back with none of them. The monitor that had the focus
keeps it, and every monitor shows its workspace in front.
A monitor that komorebi has not seen gets workspaces of its own, and the windows that open on it
are tiled there. When `komorebi.json` has an entry for the monitor in
[`display_index_preferences`](configuration.md#monitors-and-workspaces) and the monitor was not
connected when the file was read, it takes the entry when it is plugged in. The monitors are put
at the index the user gave them with
[`komorebic display-index-preference`](../cli/display-index-preference.md), and after the other
monitors otherwise.
## Following it from a program
A [subscriber](subscribing-to-notifications.md) is sent a notification each time komorebi has
dealt with a change of the monitors, whether or not anything changed in the state. Its `event` is
`{"Resize":0}` for a change of size, where the number is the id of the monitor that changed, or 0
when KWin does not say which, and `{"DisplayConnectionChange":0}` for a monitor that was
unplugged or plugged in.
+161
View File
@@ -0,0 +1,161 @@
# Checking the setup
[`komorebic check`](../cli/check.md) reads your configuration the way the daemon does, reads your
key binding file, looks at the desktop komorebi has to run on, and says in words what is wrong. It
does not need the daemon to be running, and it changes nothing.
```sh
komorebic check
komorebic check --komorebi-config ~/mine.json
komorebic check --configuration-only
```
It reads `komorebi.json` in the [config home](configuration.md#where-the-file-is), or the file
`--komorebi-config` names (`-k`; environment variables in the path are replaced). It prints a
section of findings for the configuration, one for the key bindings and one for the desktop, then
the number of errors and warnings, and exits with status 1 if and only if a finding is an error, so
a script can run it before it starts the daemon. `--configuration-only` leaves the desktop out, for
a machine that is not the one komorebi will run on: a build that checks a file, say.
## What a finding says
Each finding is on a line of its own, after its level, with advice under it when there is some:
| Level | Meaning |
|---|---|
| `ok` | Right as it is |
| `note` | Something to know |
| `warning` | Something that will not do what was meant: komorebi starts and carries on |
| `error` | Something that stops komorebi, or a part of it, from working |
## The configuration
The first section says where komorebi looks, and then what it finds in the file:
- **No file.** A `note`: komorebi starts with its defaults, and
[`komorebic quickstart`](quickstart-and-autostart.md#quickstart) has an example to begin from.
- **JSON that does not parse.** An `error` that shows the line, and the two before it, with a caret
under the place serde stopped:
```text
error bad.json is not valid JSON: expected ident at line 3 column 29
1 | {
2 | "resize_delta": 100,
3 | "mouse_follows_focus": tru,
| ^
```
- **A value komorebi does not read.** An `error` that shows the line the same way, for a value of
the wrong kind or a name that is not one of the choices (`"cross_boundary_behaviour":
"Sideways"`). The hint says that [`komorebic static-config-schema`](../cli/static-config-schema.md)
prints the schema, for an editor to check the file against.
- **A key that is not a setting.** A `warning`, with the nearest setting when one is near enough to
be what you meant, at the root of the file, in a monitor and in a workspace. komorebi reads the
file without it, so a typo is ignored, which is why the check says so:
```text
warning `resize_dlta` is not a setting komorebi has
did you mean `resize_delta`?
```
- **A key for another platform.** Not a mistake, since one `komorebi.json` can serve
[every platform](configuration.md#one-file-for-every-platform). The keys that only komorebi for
Windows or for macOS reads, and the keys komorebi for KDE reads and does nothing with, are listed
once, in a `note`. A workspace's `custom_layout` and `custom_layout_rules`, which Windows has, are
a `warning`: they are not supported yet.
- **An application specific configuration that is not there.** A `warning` for each file that
`app_specific_configuration_path` names and that does not exist: komorebi starts without it,
and the windows it names are managed like any other.
- **A wallpaper that is not a file.** An `error` for each wallpaper, of a monitor or of a
workspace, whose `path` is not a file: the shell has nothing to show.
- **A wallpaper no theme can be made from.** A `warning` for a picture of which the
[borders cannot take their colors](wallpapers.md#the-colors-of-the-borders), when
`generate_theme` is not `false`: the wallpaper is set and the borders keep the colors they have.
- **A workspace that is only a name.** A `warning` for a workspace with no `layout`, no `tile` and
no `layout_rules`, which komorebi does not tile.
- **Placement rules that are not used.** A `note` for a workspace that has
[`initial_window_placement_rules`](../initial-window-placement-rules.md) and
[appends windows to a container](stacking-windows.md) (`"window_container_behaviour":
"Append"`, on the workspace, or in the file when the workspace does not say): a window that is
appended has no place of its own to be given.
The check takes the keys it knows from the schema of the types the daemon reads the file with, at
every level, so it knows every setting komorebi reads.
## The key bindings
The second section is about the key binding file `komorebic hotkeys compile` would read: the first
of `skhdrc`, `whkdrc` and `sxhkdrc` in the config home. It reads the file as
[`hotkeys compile`](../cli/hotkeys-compile.md) does, plans it in the mode `hotkeys compile` uses
when it is not given one, and looks at:
- **No file.** A `note`, with where key bindings come from: a key binding file made into shortcuts
by `komorebic hotkeys compile`, or shortcuts set up in System Settings.
- **The bindings.** `ok` with the file, how many bindings it has, and how many of them become
shortcut files and how many are for komorebi's engine.
- **Lines that cannot be read.** A `warning` that says how many are left out, and shows the first
five with their line numbers. The rest of the file is read all the same.
- **Bindings that are not realized as the file's own hotkey daemon would.** A `note` with how many,
and the first five: a left Alt that is the same as the right one, say, since KDE does not tell
them apart.
- **Shortcut files that are not the plan's.** A `warning` when the generated files in
`$XDG_DATA_HOME/kglobalaccel` are not the ones `komorebic hotkeys compile` would write for the
file now: how many to add, to change and to remove. The hint is the command that makes them
match. Otherwise `ok`.
`--configuration-only` leaves this section in: it looks at files, not at the desktop.
## The desktop
The third section is about the desktop `komorebic check` runs in, which has to be the session
komorebi runs in: it asks the session bus of the environment it is run from, so run it in a
terminal of the Plasma session, not over ssh. It looks, in this order, at:
- **The session.** A `warning` when `XDG_CURRENT_DESKTOP` does not name KDE, and one when the
session is not Wayland (`XDG_SESSION_TYPE` is not `wayland` and there is no `WAYLAND_DISPLAY`):
komorebi is made for KWin on Wayland and tried on nothing else.
- **The session bus, and KWin on it.** An `error` when it cannot connect to the session bus (the
hint says that `DBUS_SESSION_BUS_ADDRESS` has to be that of the desktop session, which it is not
over ssh), when the bus does not answer, and when KWin is not on it, since komorebi works through
KWin and nothing else. The check goes no further after one of them, because nothing after it can
be answered.
- **KWin's version.** `ok` for KWin 6 or newer, an `error` for an older one, and a `note` when
KWin does not say what version it is.
- **komorebi and its script.** komorebi is running when its socket takes a connection, and its
script is in KWin when KWin says it has loaded `komorebi-bridge`:
| komorebi | script | Finding |
|---|---|---|
| running | in KWin | `ok` |
| running | not in KWin | `error`: it cannot see a window; `komorebic log` says why, and restarting komorebi loads the script again |
| not running | in KWin | `warning`: a script of a daemon that is gone is still in KWin, and starting komorebi replaces it |
| not running | not in KWin | `note`: `komorebic start` |
- **The border effect.** The borders are drawn by an effect of KWin, KDE Rounded Corners, and
only komorebi's build of it has a color for each kind of window (the stock one has a color for the
active window and one for the others). `ok` when the effect is komorebi's build; a `warning` when
`border` is on and the effect is not installed, or is the stock one, and a `note` when `border` is
off. The build is told by what it contains (the name of its D-Bus interface in the plugin file,
or its object on the bus), not by its name.
- **The animation effect.** Windows are animated by Geometry Change, a script effect, and only
komorebi's build reads its curve from a setting (the stock one eases out exponentially and
nothing else). `ok` when the copy KWin uses is komorebi's build. A `warning` when `animation` is
on and the effect is not installed, and when it is the stock one and `animation.style` is any
other than `EaseOutExpo` (the style is ignored, and the default is `Linear`); a `note` when
animation is off. A `warning` too when a copy in your own data directory, which KWin takes before
the system's, is not the same build as the system's and hides it.
- **The Plasma shell.** Only when a monitor or a workspace has a
[wallpaper](wallpapers.md): `ok` when the shell is on the bus, a `warning` when it is not
(wallpapers will not be set; komorebi asks again for half a minute after it starts, for a shell
that is late).
- **What starts komorebi at login.** `ok` with the file that does it: the autostart entry
[`enable-autostart`](quickstart-and-autostart.md#starting-komorebi-with-plasma) writes, or a
systemd user unit (`~/.config/systemd/user`, `/etc/systemd/user`, or the one of the NixOS module).
A `note` when there is none. It is looked for after the rest, whatever the rest found.
Effects are looked for where KWin looks: the check reads the environment of the process that owns
`org.kde.KWin` (`/proc/PID/environ`) for the plugin and data directories, so the answer is KWin's
and not that of the shell the command is typed in.
Every question to the bus has two seconds to be answered, so a bus that never answers is an `error`
like one that is not there.
+273
View File
@@ -0,0 +1,273 @@
# Configuration
komorebi is configured by one file, `komorebi.json`. Many of its settings can also be changed
while the daemon runs, with a `komorebic` command, but the file is where the settings that should
be there every time komorebi starts belong: the workspaces of each monitor and their layouts, the
padding around the tiles, the rules that decide which windows are tiled.
[Example configurations](../example-configurations.md) has a file to start from.
## Where the file is
The daemon reads, in this order:
1. the file `--config` names: `komorebi --config ~/mine.json`, or `komorebic start --config
~/mine.json`. Environment variables in the path, such as `$HOME`, are replaced;
2. `komorebi.json` in the config home, which is `$KOMOREBI_CONFIG_HOME` when that is set (it has
to be a directory) and `~/.config/komorebi` when it is not.
With neither, komorebi runs on its defaults, which are what every setting below says it is when
the file leaves it out. [`komorebic configuration`](../cli/configuration.md) (or `komorebic
config`) prints the path of the file in the config home, when there is one.
On NixOS, [the module's `configFile`](../installation.md#options) gives the daemon a file the
same way `--config` does.
## Changing the file
The daemon watches the file it read. When the file changes, about two seconds later it reads it
again and applies it to the windows it has: it sets the settings, gives each monitor the
workspaces the file lists for it, and tiles every monitor again. The windows stay in the
workspaces they are in. An editor that writes the file in place and one that writes a new file
and renames it over the old one are both followed.
A file that cannot be read, or that has a value of the wrong kind, changes nothing: the daemon
logs the error and keeps what it has. The file is written as JSON that may have comments and
trailing commas.
Reading the file again sets every setting of the daemon from it, and a key the file leaves out is
the default of the setting: a `resize-delta` given with a command is gone when the file changes.
These stay as they were when the file leaves them out: `default_workspace_padding`,
`default_container_padding`, `display_index_preferences`, the four settings of the borders, each
color of `border_colours` the file does not name, the theme and the animation, when the file has no
`animation`. The rules add up, as
[Rules](#rules) says. A workspace the file lists gets its name, padding, offsets, rules and
wallpaper from its entry, and its layout when the entry names one; a workspace the file does not list is left as
it is.
[`komorebic generate-static-config`](../cli/generate-static-config.md) prints the settings the
daemon has now as a `komorebi.json`: a way to start a file from a setup arrived at with commands.
The rules (`ignore_rules`, `manage_rules` and `floating_applications`) are not in what it prints;
the `workspace_rules` and `initial_workspace_rules` of the workspaces that were loaded from a file
are.
## One file for every platform
komorebi for Windows and komorebi for Mac have their own keys, and one `komorebi.json` can serve
all of them. A key that komorebi for KDE does not read is ignored, and so is a key it does not
know: loading never fails because of one. Keys that mean nothing on Plasma, because they are about
how another platform draws or hides windows, are accepted: `titleless_applications`,
`tabbed_applications`, `window_hiding_position` of a monitor, and the keys that only Windows has
(`window_hiding_behaviour`, `border_style`, `stackbar`, and the others of the Windows file).
## The keys
### Settings of the daemon
| Key | Default | What it does |
|---|---|---|
| `resize_delta` | `50` | How many pixels `resize-edge` and `resize-axis` resize by |
| `focus_follows_mouse` | none | `Windows` or `Komorebi` to have KWin give the focus to the window under the pointer ([Focus follows mouse](focus-follows-mouse.md)); the two are the same on KDE. Left out, KWin's focus policy is the user's own |
| `mouse_follows_focus` | `true` | Whether the pointer goes to the window that is given the focus |
| `cross_monitor_move_behaviour` | `Swap` | What `move` does at the edge of a monitor: `Swap`, `Insert` or `NoOp` |
| `cross_boundary_behaviour` | `Monitor` | Where `focus` and `move` go at the edge of a monitor: to the next `Monitor` or the next `Workspace` |
| `unmanaged_window_operation_behaviour` | `Op` | Whether a command is carried out while the focused window is not tiled: `Op` or `NoOp` |
| `window_container_behaviour` | `Create` | What a window that opens gets: a tile of its own (`Create`) or a place in the focused stack (`Append`) |
| `float_override` | `false` | Whether every window that opens floats |
| `float_override_placement` | `None` | What is done to a window the override floats: `None`, `Center` or `CenterAndResize` |
| `floating_layer_behaviour` | `Tile` | What a window that opens while a workspace is on its floating layer gets: `Tile` or `Float` |
| `floating_layer_placement` | `Center` | What is done to a window that `floating_layer_behaviour` floats |
| `monocle_focus_behaviour` | `NoOp` | What `focus` does while a container is in monocle: `NoOp` or `Cycle` |
| `toggle_float_placement` | `CenterAndResize` | What `toggle-float` does to the window it floats: `None`, `Center` or `CenterAndResize` |
| `float_rule_placement` | `None` | The same, for a window that opens and matches `floating_applications` |
| `floating_window_aspect_ratio` | `Standard` | The aspect ratio `CenterAndResize` gives the window: `Standard` (4:3), `Widescreen` (16:9), `Ultrawide` (21:9) or `[width, height]` |
### Padding and offsets
| Key | Default | What it does |
|---|---|---|
| `default_workspace_padding` | `5` | The gap, in pixels, between the edge of the work area and the tiles |
| `default_container_padding` | `5` | The gap around each tile |
| `global_work_area_offset` | none | The part of every monitor's work area that tiles stay out of: `left`, `top`, `right` and `bottom`. `left` and `top` move the edge in; `right` and `bottom` make the area narrower and shorter by that much |
[Padding and work area offsets](padding-and-offsets.md) explains how the three nest. A monitor
(`container_padding`, `workspace_padding`, `work_area_offset`) and a workspace (the same three)
can have values of their own, which come before the default.
### Borders
| Key | Default | What it does |
|---|---|---|
| `border` | `true` | Whether the compositor draws a border around each window (`active_window_border` is the same key under its old name) |
| `border_width` | `10` | How thick the border is, in pixels (`active_window_border_width`) |
| `border_offset` | `0` | How much more room than the width the layout leaves around each window (`active_window_border_offset`) |
| `border_radius` | `10` | How round the corners of the border are, in pixels |
| `border_colours` | see [Borders](borders.md#colors) | The color of the border of each kind of window: `single`, `stack`, `monocle`, `floating`, `unfocused` and `unfocused_locked`, each as `{ "r": 66, "g": 165, "b": 245 }` or `"#42A5F5"` (`active_window_border_colours`). A theme replaces them |
| `theme` | none | A theme that gives every kind of border its color: a Catppuccin theme, a Base16 scheme or a palette of your own ([Themes](themes.md)). It wins over `border_colours` |
[Borders](borders.md) explains what the compositor draws and what the layout leaves room for.
`komorebic border`, `border-width` and `border-offset` change the first three while the daemon
runs.
### Animation
`animation` is an object with these keys:
| Key | Default | What it does |
|---|---|---|
| `enabled` | `false`, required | Whether windows are animated going to their places: `true` or `false` for every kind of animation, or `{ "movement": true }` for the kinds it names |
| `duration` | `250` | How long the animation lasts, in milliseconds, in the same two forms |
| `style` | `Linear` | The easing curve, in the same two forms: a name such as `EaseOutExpo`, or a cubic Bézier as four numbers ([Animation](animation.md#easing)) |
| `fps` | `60` | Accepted and not used: KWin animates at the refresh rate of the screen |
[Animation](animation.md) explains what is animated. A file that has no `animation` leaves the
settings as they are, and one that has it and leaves out `duration` or `style` leaves that one as it
is; a value given for every kind of animation takes the settings of single kinds away.
### Transparency
| Key | Default | What it does |
|---|---|---|
| `transparency` | `false` | Whether the windows that do not have the focus are see-through |
| `transparency_alpha` | `200` | How opaque they are, from 0 to 255 |
| `transparency_ignore_rules` | none | Rules for the windows that are never see-through |
[Transparency](transparency.md) explains which windows are see-through. `transparency_ignore_rules`
is a list of rules, which [Rules](#rules) describes, and has no command.
### Rules
| Key | What it does |
|---|---|
| `ignore_rules` | Windows komorebi leaves alone (`float_rules` is the same key under its old name) |
| `manage_rules` | Windows komorebi tiles whatever the ignore rules say |
| `floating_applications` | Windows that open floating |
| `app_specific_configuration_path` | One `applications.json`, or a list of them, whose rules are added to these ([Application specific configuration](application-specific-configuration.md)) |
Each is a list of rules, which [Rules](rules.md) explains. A rule is an object with `kind` (`Exe`,
`Class`, `Title` or `Path`), `id` and `matching_strategy` (`Equals`, `StartsWith`, `EndsWith`,
`Contains`, `Regex`, or one of the four that negate them: `DoesNotEqual`, `DoesNotStartWith`,
`DoesNotEndWith` and `DoesNotContain`), or a list of such objects, all of which have to match.
Rules in the file add to the ones the daemon has: a rule that is taken out of the file stays
until the daemon restarts. The exception is a workspace's `workspace_rules` and
`initial_workspace_rules`, which the file gives again each time it is read.
### Monitors and workspaces
`monitors` is a list with one entry for each monitor, each with its `workspaces`. The first entry
is for the first monitor, the second for the second, and so on. A monitor that has no entry keeps
what it has.
`display_index_preferences` puts an entry on a monitor by what the monitor is called instead
of by its place: `{ "0": "DP-1", "1": "HDMI-A-1" }` says that the entry at index 0 is for the
monitor `DP-1`. `komorebic monitor-information` shows the names.
A monitor that has no preference takes the first entry nobody's preference names and that no
other monitor has taken.
A monitor entry can also have a `floating_layer_behaviour`, which is the one its workspaces take
unless they have their own, and which comes before the one for every monitor, and a `wallpaper`,
the picture the monitor shows while one of its workspaces is in front, unless that workspace has
one of its own ([Wallpapers](wallpapers.md)).
A monitor takes as many workspaces as its entry lists, and KWin gets a virtual desktop for each,
named for it. A workspace has these keys:
| Key | Default | What it does |
|---|---|---|
| `name` | required | The name `focus-named-workspace` and the other named commands find it by |
| `layout` | none | The layout: `BSP`, `Columns`, `Rows`, `VerticalStack`, `RightMainVerticalStack`, `HorizontalStack`, `UltrawideVerticalStack`, `Grid` or `Scrolling` |
| `tile` | see below | Whether the workspace tiles its windows |
| `layout_flip` | none | The axis the layout is mirrored on: `Horizontal`, `Vertical` or `HorizontalAndVertical` |
| `layout_options` | none | Options of the layout, such as `column_ratios` and `scrolling` |
| `workspace_rules` | none | Rules for the windows that always go to this workspace ([Workspace rules](workspace-rules.md)) |
| `initial_workspace_rules` | none | Rules for the windows that go to this workspace when komorebi first sees them |
| `layout_rules` | none | `{ "3": "Columns" }`: the layout the workspace has once it has 3 containers or more |
| `layout_options_rules` | none | The same, for the layout options |
| `container_padding`, `workspace_padding` | the default | The padding of this workspace |
| `work_area_offset` | none | The offset of this workspace |
| `work_area_offset_rules` | none | `{ "2": { "left": 100, "top": 0, "right": 200, "bottom": 0 } }`: the offset the workspace has once it has 2 containers or more |
| `apply_window_based_work_area_offset` | `true` | Whether the workspace takes its monitor's window-based offset |
| `window_container_behaviour` | the default | What a window that opens on this workspace gets: `Create` or `Append` |
| `window_container_behaviour_rules` | none | `{ "2": "Append" }`: the behavior the workspace has once it has 2 containers or more |
| `float_override` | the default | Whether every window that opens on this workspace floats |
| `floating_layer_behaviour` | the default | What a window that opens while this workspace is on its floating layer gets: `Tile` or `Float` |
| `wallpaper` | none | The picture the monitor shows while this workspace is in front, instead of its monitor's: `{ "path": "~/Pictures/sea.png" }`, and `generate_theme` and `theme_options` for the borders' colors ([Wallpapers](wallpapers.md)) |
| `initial_window_placement_rules` | none | Where in the list of containers a window that opens on this workspace goes: a place, or a place for each kind of window ([Initial window placement rules](../initial-window-placement-rules.md)) |
A workspace that names no `layout` and does not say `"tile": true` does not tile: its windows
stay where they open. A workspace with `layout_rules` tiles. Otherwise a workspace tiles.
The highest of the rules that the number of containers reaches wins. A layout rule changes the
layout of the workspace and leaves it there when the number falls below the threshold again, so a
rule at 1 is how to say what the layout is when there is one window; the offset and the layout
options of a rule are the ones the workspace has while it has that many containers.
The window container behavior rules are the exception: while the workspace has fewer containers
than the lowest threshold it has no behavior of its own and takes the one for every workspace,
and a workspace that has rules takes its behavior from them alone, so
`toggle-workspace-window-container-behaviour` does not outlast the next time it is tiled.
### Layout options for every workspace
`layout_defaults` gives the layout options and the layout options rules of a layout to every
workspace that has that layout and sets neither `layout_options` nor `layout_options_rules`:
```json
{
"layout_defaults": {
"Columns": { "layout_options": { "column_ratios": [0.6] } },
"Scrolling": { "layout_options": { "scrolling": { "columns": 2 } } }
}
}
```
A workspace that sets either of its own has none of the defaults of its layout, not even for the
setting it leaves out.
## Layout rules from the command line
The layout rules of a workspace can be added and taken away while the daemon runs:
```sh
komorebic workspace-layout-rule 0 1 3 columns
komorebic named-workspace-layout-rule mail 2 rows
komorebic clear-workspace-layout-rules 0 1
komorebic clear-named-workspace-layout-rules mail
```
[`workspace-layout-rule`](../cli/workspace-layout-rule.md) takes the index of the monitor, the
index of the workspace, the number of containers and the layout;
[`named-workspace-layout-rule`](../cli/named-workspace-layout-rule.md) takes the name of the
workspace instead. A rule for a count that has one replaces it. The clear commands take every
rule of the workspace away and leave it with the layout it has.
## The schema
The Rust types that read `komorebi.json` also describe it as a JSON Schema, which an editor can
check the file against, and which the NixOS module is typed from. [`schema.json`](../../schema.json)
in the repository is the schema of `komorebi.json`, [`schema.asc.json`](../../schema.asc.json) the
schema of an [`applications.json`](application-specific-configuration.md), and the commands print
them (and two more), without a daemon:
```sh
komorebic static-config-schema
komorebic application-specific-configuration-schema
komorebic notification-schema
komorebic socket-schema
```
[`notification-schema`](../cli/notification-schema.md) is the schema of what a
[subscriber](subscribing-to-notifications.md) is sent, and
[`socket-schema`](../cli/socket-schema.md) the schema of a message. To check a file by hand:
```sh
komorebic static-config-schema > schema.json
check-jsonschema --schemafile schema.json ~/.config/komorebi/komorebi.json
```
`check-jsonschema` reads plain JSON, so comments in the file have to come out first. The schema
does not stop komorebi from reading a file that does not follow it: a key it does not have is
dropped, as [above](#one-file-for-every-platform). [`komorebic check`](checking-the-setup.md)
reads the file the way the daemon does, and names a key that is not a setting, with the nearest
one that is.
+83
View File
@@ -0,0 +1,83 @@
# Floating windows
A floating window is one of a workspace's windows that is not in its layout: komorebi gives it no
tile and does not move it, and it stays where it is put by hand.
[`komorebic toggle-float`](../cli/toggle-float.md) takes the window that has the focus out of the
layout, and the other windows of the workspace share the work area. The same command on a
floating window puts it back in the layout, at the place of the focused window.
```sh
komorebic toggle-float
```
A floated window keeps its size and position by default. The floating windows of a workspace are
in the daemon's state as `floating_windows`, next to its containers.
## Windows that open floating
With the float override on, every window that opens floats instead of getting a tile.
[`komorebic toggle-float-override`](../cli/toggle-float-override.md) turns it on and off for every
workspace, and
[`komorebic toggle-workspace-float-override`](../cli/toggle-workspace-float-override.md) for the
focused workspace only: the first time it takes the opposite of what every workspace has, and from
then on it follows its own setting.
```sh
komorebic toggle-float-override
komorebic toggle-workspace-float-override
```
The override is in the daemon's state, as `float_override` for every workspace and in each
workspace that has one of its own.
In `komorebi.json` it is `float_override`, for every workspace and in the entry of a workspace.
`float_override_placement` says what is done to the window the override floats: `None` leaves it
where KWin put it, `Center` centers it in the work area and `CenterAndResize` also makes it half
as tall as the work area, with the aspect ratio `floating_window_aspect_ratio` names. A window is
centered only on a workspace that tiles.
## The two layers
A workspace is on one of two layers: its tiles, or its floating windows. Which one decides what
[`komorebic focus`](../cli/focus.md), [`cycle-focus`](../cli/cycle-focus.md),
[`move`](../cli/move.md) and [`resize-edge`](../cli/resize-edge.md) act on. Floating a window puts
the workspace on its floating layer, and giving the focus to a tiled window, with the pointer or a
command, puts it back on its tiling layer. A window that opens and is tiled does the same, and so
does putting a floating window back in the layout.
[`komorebic toggle-workspace-layer`](../cli/toggle-workspace-layer.md) switches the layer by hand.
The windows of the layer it goes to are raised in front of the others, and one of them is given the
focus: the focused floating window, or the focused container's window. Going to the tiles hides the
floating windows, and going back to the floating layer shows them.
```sh
komorebic toggle-workspace-layer
```
On the floating layer:
- `focus left`, `right`, `up` and `down` give the focus to the nearest floating window on that
side, by where KWin has them. When no floating window is on that side the focus goes to the
monitor on that side, as it does for tiles, and the command fails where there is none: the
daemon logs "there is no container or monitor in this direction".
- `cycle-focus next` and `previous` go round the floating windows in the order they were floated,
and wrap around.
- `move` moves the focused floating window by the [resize delta](resizing-windows.md), 50 pixels
unless it was set, and not out of the work area.
- `resize-edge` and `resize-axis` change the frame of the focused floating window: `increase` on
the left or the upper side moves it that way, and on the right or the lower side makes it wider
or taller by twice the delta; `decrease` does the opposite.
- `preselect-direction` does nothing.
[`komorebic toggle-maximize`](../cli/toggle-maximize.md) maximizes the focused floating window
there, and when it is restored it is a tile, not a floating window.
The layer is `layer` in the state of each workspace, `Tiling` or `Floating`.
What a window that opens while a workspace is on its floating layer gets is
`floating_layer_behaviour` in `komorebi.json`: `Tile`, the default, gives it a tile, and `Float`
floats it, centered in the work area as `floating_layer_placement` says (`Center` by default; the
values are those of `float_override_placement`). The entry of a monitor and the entry of a
workspace can have a `floating_layer_behaviour` of their own: the workspace's comes before the
monitor's, which comes before the one for every monitor.
+51
View File
@@ -0,0 +1,51 @@
# Focus follows mouse
With focus follows mouse, the window under the pointer is the window that has the focus: moving the
pointer into another window gives that window the focus, with no click. komorebi does not do this
itself. It asks KWin to, by changing KWin's own focus policy, and follows where the focus goes like
it follows any other change of focus.
## Turning it on and off
`komorebic focus-follows-mouse` turns it on or off, and `komorebic toggle-focus-follows-mouse`
switches it. It is off by default: KWin's focus policy is the user's own until komorebi changes
it.
```sh
komorebic focus-follows-mouse enable
komorebic focus-follows-mouse disable
komorebic toggle-focus-follows-mouse
```
Both take `--implementation`, `windows` (the default) or `komorebi`, the two that komorebi for
Windows has. On KDE they are the same: both ask KWin for its own focus policy, and which one was
asked for is only remembered, in the `focus_follows_mouse` of the daemon's state.
## In komorebi.json
The `focus_follows_mouse` key of [`komorebi.json`](configuration.md#settings-of-the-daemon) is
`"Windows"` or `"Komorebi"` to turn it on, which is what `--implementation` names, and has no value
or is left out to leave it off:
```json
{
"focus_follows_mouse": "Windows"
}
```
The file sets it when the daemon starts and when the file changes, and a file that leaves it out
turns it off and gives the user's focus policy back, also when it was turned on with a command.
## What it does to KWin
Turning it on sets two keys in the group `[Windows]` of the user's `kwinrc`, `FocusPolicy=1`
("focus follows mouse") and `DelayFocusInterval=0`, and asks KWin to read its configuration
again. Turning it off, and exiting komorebi, put back what the user had: the value each key
had before komorebi changed it, or no value if the key was not there. A daemon that was killed
leaves the keys changed until the next run, whose exit puts them back.
## The pointer follows the focus too
[`komorebic mouse-follows-focus`](../cli/mouse-follows-focus.md) is the other direction: the pointer
goes to the middle of the window that is given the focus. With both on, the pointer and the focus
stay in the same window.
+75
View File
@@ -0,0 +1,75 @@
# Focusing windows
komorebi gives the focus to another window of the focused workspace when it is told to. It
moves no window to do it: the windows stay on their tiles, and KWin makes the chosen one the
active window.
## In a direction
[`komorebic focus`](../cli/focus.md) focuses the window whose tile is on one side of the
focused one: `left`, `right`, `up` or `down`. Which tile is on which side is the layout's
business. In the BSP layout with three windows, for example, the first window has the left
half, and `focus right` from it goes to the window at the top right.
```sh
komorebic focus left
komorebic focus down
komorebic focus up
komorebic focus right
```
When there is no tile on that side, the focus goes to the monitor on that side, if there is one,
to the tile nearest the monitor the focus came from: `focus right` lands on the leftmost tile of
the monitor on the right. With no monitor there either, nothing happens, and the daemon logs
"there is no container or monitor in this direction".
[`komorebic focus-monitor`](../cli/focus-monitor.md) focuses a monitor by its index,
[`komorebic cycle-monitor`](../cli/cycle-monitor.md) the next or the previous one, and
[`komorebic focus-monitor-at-cursor`](../cli/focus-monitor-at-cursor.md) the one the pointer is
on. [`komorebic eager-focus`](../cli/eager-focus.md) focuses the first window komorebi manages of
an executable, on any workspace of any monitor, and shows its workspace.
```sh
komorebic focus-monitor 1
komorebic eager-focus firefox
```
## In order
[`komorebic cycle-focus`](../cli/cycle-focus.md) focuses the next or the previous window in the
order of the workspace, which is the order in which the windows were opened, each new one
after the window that had the focus. It wraps around: `next` from the last window is the
first.
```sh
komorebic cycle-focus next
komorebic cycle-focus previous
```
## The largest tile
[`komorebic promote-focus`](../cli/promote-focus.md) focuses the window on the first tile of the
layout, which is its largest ([Moving windows](moving-windows.md#to-the-largest-tile)).
## The pointer
By default the pointer moves to the middle of the window that is given the focus. komorebi asks
KWin to do it with its "Move Mouse to Focus" shortcut, so the pointer follows only in a session
that has KWin's global shortcuts (a headless KWin has none).
[`komorebic mouse-follows-focus`](../cli/mouse-follows-focus.md) turns this on or off, and
[`komorebic toggle-mouse-follows-focus`](../cli/toggle-mouse-follows-focus.md) switches between
the two:
```sh
komorebic mouse-follows-focus disable
komorebic toggle-mouse-follows-focus
```
The setting is in the daemon's state as `mouse_follows_focus`, and it lasts until the daemon
stops.
## Binding them to keys
komorebi reads no keys. Bind the commands to keys in Plasma's System Settings, under Keyboard,
Shortcuts, as custom shortcuts that run a command: for example `Meta+H` for
`komorebic focus left` and `Meta+L` for `komorebic focus right`.
+17
View File
@@ -0,0 +1,17 @@
# Fullscreen windows
A window that goes fullscreen, with its program's own key (F11 in many programs), the window
menu or a shortcut, covers its whole monitor, the panels included. komorebi leaves it there. It
never moves or resizes a fullscreen window, whatever happens to the others: a retile, a window
that opens or closes, a [layout](layouts.md) that changes.
The window stays in its container, so the layout keeps a tile for it, and the other windows are
tiled as if it were not fullscreen. The fullscreen window covers them, and they are in their tiles
when it leaves.
When the window leaves fullscreen, KWin gives it the frame it had before. That frame may not be
its tile any more, because windows can have opened or closed meanwhile, so komorebi tiles the
workspace again and the window goes to the tile the layout has for it.
There is no `komorebic` command for fullscreen: it is KWin's, and the program's. A window that is
fullscreen when komorebi starts is left alone the same way.
+120
View File
@@ -0,0 +1,120 @@
# Key bindings
komorebi reads key bindings from a file in the format of skhd (`skhdrc`), whkd (`whkdrc`) or
sxhkd (`sxhkdrc`), the hotkey daemons of komorebi on macOS and on Windows and of X11 window
managers, so an existing file can be used as it is. On Plasma under Wayland no program sees
the keys of another, so the keys are KDE's global shortcuts, in one of two ways:
- **Static shortcuts**: KDE runs the command of the key by itself, from a `.desktop` file. A
static shortcut works when komorebi is not running and shows in System Settings, where it
can be changed, but it is one combo, pressed, the same in every application, and KDE takes
about 0.2 seconds to start its command.
- **The engine**: the komorebi daemon registers the keys with KDE and runs the command of each
press itself, a few milliseconds after the key. It realizes what a static shortcut cannot:
modes, chord chains, bindings that fire on release, bindings that do something else in each
application, a blacklist and a pause binding. It works only while the daemon runs.
The mode decides which bindings go where:
| Mode | Static shortcuts | The engine |
|---|---|---|
| `engine` (the default) | none | every binding |
| `auto` | every binding that can be one, in a file with no modes, blacklist or pause binding | the others |
| `static` | every binding that can be one | none: the others are left out, with a warning |
[`skhdrc.sample`](../skhdrc.sample), [`whkdrc.sample`](../whkdrc.sample) and
[`sxhkdrc.sample`](../sxhkdrc.sample) are the same bindings in the three formats.
## On NixOS
The module's `keybindings` options take the file or its text, and do the rest: the static
shortcuts are installed in the system profile, where KDE finds them when you log in, and the
daemon is started with the file and the same mode.
```nix
services.komorebi = {
enable = true;
keybindings = {
format = "skhd";
file = ./skhdrc;
mode = "auto";
};
};
```
| Option | Default | What it does |
|---|---|---|
| `keybindings.format` | none | `"skhd"`, `"whkd"` or `"sxhkd"`; required with `text` or `file`. |
| `keybindings.text`, `keybindings.file` | none | The bindings, or the file they are in: exactly one of the two. skhd's `.load` is refused, since the file it reads would not be in the store. |
| `keybindings.mode` | `"engine"` | The mode, as in the table above. |
| `keybindings.chordTimeout` | `3000` | How long, in milliseconds, the engine waits for the next key of a chord chain. |
| `keybindings.layout` | `"us"` | The keyboard layout positional key names are read with; `"us"` is the only one. |
| `keybindings.strict` | `false` | Fail the build when something in the file is not realized as its own daemon realizes it. |
| `keybindings.appAliases` | `{ }` | Other names of an application, for the bindings that are for one application: `{ firefox = [ "firefox-esr" ]; }`. |
What `komorebic hotkeys compile` had to say about the file (its diagnostics, below) is in the
build log, and in `diagnostics.txt` of the `komorebi-keybindings` package.
## Without NixOS
[`komorebic hotkeys compile`](../cli/hotkeys-compile.md) writes the static shortcuts of a
file to `~/.local/share/kglobalaccel`, where KDE reads them at the next login (`--reload`
hands new ones over at once), and the daemon runs the engine for the rest when it is given
the same mode. Without a file name both read the first of `skhdrc`, `whkdrc` and `sxhkdrc` in
`~/.config/komorebi`, where [`komorebic quickstart`](quickstart-and-autostart.md#quickstart)
writes the sample `skhdrc`.
```sh
komorebic hotkeys compile --mode auto --reload
komorebic start -- --keybindings-mode auto
```
The daemon's options are `--keybindings FILE`, `--keybindings-format skhd|whkd|sxhkd` (when
the name does not end with one of those), `--keybindings-mode`, `--chord-timeout MS` and
`--app-alias NAME=ALIAS[,ALIAS]...`.
[`komorebic export-kde-shortcuts`](../cli/export-kde-shortcuts.md) writes the static
shortcuts of an skhdrc and leaves the rest out, for a setup without the engine.
## What is realized, and what is not
Everything the three formats bind keys with is realized, by a static shortcut or by the
engine, except what follows. `komorebic hotkeys compile --dry-run` prints a diagnostic for
each case the file has, with its line, and `--strict` (`keybindings.strict`) turns a warning
into a failure.
- **Approximated**: side-specific modifiers (`lalt`, `rwin`) are either side, since KDE does
not tell them apart. A capturing mode (skhd's `@`) lets the keys it has no binding for reach
the application. skhd's `->` and sxhkd's `~` do not pass the key on to the application. A
key that is not the next of an sxhkd chain does not end the chain: only Escape and the chord
timeout do. A release binding (sxhkd's `@`) fires when any key of its combo is released
first. `.shell` is not followed: commands run through `sh -c`.
- **Not supported**: skhd's `fn` modifier, `.load`, `.alias`, key forwarding and key
sequences; mouse buttons; keypad keys; the X modifiers KDE has no equivalent for (`hyper`,
`meta`, `mode_switch`, `lock`, `mod2`, `mod3`, `mod5`, `any`).
- **Applications**: a binding for an application matches the executable, the Wayland app id
(`org.kde.konsole`) or the desktop entry of the focused window, whatever the case. skhd
and whkd name applications as macOS and Windows do, so a name that differs on KDE needs an
alias.
- **Positional keys**: skhd's keycodes (`0x21`) and whkd's `oem_*` keys are read as on a US
keyboard, and a shifted symbol is the one a US keyboard types (`alt + shift - 1` is
`Alt+!`).
## When something goes wrong
- [`komorebic check`](../cli/check.md) reads the file as `hotkeys compile` does, and says how
many bindings it has, which lines it cannot read, and whether the shortcut files KDE reads are
the ones `hotkeys compile` would write now ([Checking the setup](checking-the-setup.md#the-key-bindings)).
- [`komorebic hotkeys state`](../cli/hotkeys-state.md) shows the keys komorebi has
registered with KDE and what the engine is doing: its mode, the keys it holds, and whether
a chord chain is being typed.
- The daemon's log says which file it read and how many bindings went where, and, at the
debug level, every diagnostic, every mode it enters and every application that takes the
focus.
- A key that another shortcut already has is not given to komorebi, and the daemon logs a
warning that names it. The same binding as a static shortcut and in the engine is one such
case: give `hotkeys compile` and the daemon the same mode.
- A daemon that was killed leaves its keys registered with KDE, doing nothing.
[`komorebic hotkeys release`](../cli/hotkeys-release.md) gives them back (the NixOS
module's unit runs it whenever the daemon stops), and so does the next start of the daemon.
- [`komorebic hotkeys reload`](../cli/hotkeys-reload.md) has the daemon read its file again
after a change.
+112
View File
@@ -0,0 +1,112 @@
# Layouts
The layout of a workspace turns its work area and the number of its containers into one tile
for each container. Every workspace starts with the BSP layout. A command that changes the
layout tiles the focused workspace again at once.
## The layouts
These are the layouts of `komorebi-layouts`, in the order `cycle-layout next` goes through them:
| Layout | `komorebic` name | The tiles |
|---|---|---|
| BSP | `bsp` | each new tile splits the last one in two, alternately side by side and one above the other |
| Columns | `columns` | side by side, as wide as each other |
| Rows | `rows` | one above the other, as high as each other |
| Vertical stack | `vertical-stack` | the first on the left half, the others stacked on the right |
| Horizontal stack | `horizontal-stack` | the first on the top half, the others side by side below it |
| Ultrawide vertical stack | `ultrawide-vertical-stack` | the first in the middle, the second on the left, the others stacked on the right |
| Grid | `grid` | columns of tiles, as even as the number of containers allows |
| Right main vertical stack | `right-main-vertical-stack` | the first on the right half, the others stacked on the left |
| Scrolling | `scrolling` | columns side by side |
## Changing the layout
[`komorebic change-layout`](../cli/change-layout.md) gives the focused workspace the layout it
names, and [`komorebic cycle-layout`](../cli/cycle-layout.md) the next or the previous one in
the table above:
```sh
komorebic change-layout vertical-stack
komorebic cycle-layout next
komorebic cycle-layout previous
```
`cycle-layout next` goes from the scrolling layout back to BSP. Going backwards,
`komorebi-layouts` leaves the scrolling layout out: `cycle-layout previous` goes from BSP to the
right main vertical stack.
[`komorebic query focused-workspace-layout`](../cli/query.md) prints the layout of the focused
workspace.
## Ratios
[`komorebic layout-ratios`](../cli/layout-ratios.md) sets the share of the work area the first
columns (`--columns`) and the first rows (`--rows`) of the focused workspace's layout take, as
fractions: `--columns 0.6` gives the first column 60% of the width, and the columns after it
share the rest.
```sh
komorebic layout-ratios --columns 0.6
komorebic layout-ratios --columns 0.5 0.3 --rows 0.7
```
Each takes five ratios at most, each kept between 0.1 and 0.9, and the ratios after the one that
would make them add up to 1 are dropped, so that there is always room for another column or row.
The ratios stay with the workspace when its layout changes. Without `--columns` or `--rows`,
`layout-ratios` changes nothing.
## The scrolling layout
The scrolling layout is a row of columns that runs past the edges of the monitor, and the screen
is a view onto a part of it. A column can hold several windows, and the strip scrolls to follow the
focus. [`komorebic scrolling-layout-columns`](../cli/scrolling-layout-columns.md) sets how many
columns are in view at once on the focused workspace:
```sh
komorebic change-layout scrolling
komorebic scrolling-layout-columns 2
```
[The scrolling layout](scrolling-layout.md) says how to centre the focused column, put windows in
the same column, resize columns and windows, and move the view along the strip.
## Flipping the layout
[`komorebic flip-layout`](../cli/flip-layout.md) mirrors the tiles of the focused workspace:
`horizontal` swaps left and right, `vertical` top and bottom, and `horizontal-and-vertical`
both. A flip is added to the one the workspace has, so the same flip twice puts the layout
back.
```sh
komorebic flip-layout horizontal
komorebic flip-layout horizontal
```
The containers keep their order, and the directions of [`focus`](focusing-windows.md) and
[`move`](moving-windows.md) are the ones on the screen: after `flip-layout horizontal`,
`focus left` goes to the tile on the left.
## Turning tiling off
[`komorebic toggle-tiling`](../cli/toggle-tiling.md) turns the tiling of the focused workspace
off, and on again. While it is off, komorebi moves none of its windows: they stay where they
are, and can be moved by hand. Windows that open on the workspace are still taken into it, and
when tiling is turned back on, every window is tiled again. `query focused-workspace-layout`
prints `None` while tiling is off.
## Preselecting a tile
[`komorebic preselect-direction`](../cli/preselect-direction.md) reserves the place on one side
of the focused window for the next window that opens on the workspace. The layout gives the
reserved place a tile at once, empty until the window opens.
[`komorebic cancel-preselect`](../cli/cancel-preselect.md) gives the place up.
```sh
komorebic preselect-direction left
komorebic cancel-preselect
```
The place is a position in the order of the workspace, so where its tile is depends on the
layout. A workspace reserves one place at a time: a second `preselect-direction` is ignored
until the window opens or the place is given up. The grid layout has no preselection.
+71
View File
@@ -0,0 +1,71 @@
# Managing windows
komorebi tiles every normal application window that KWin reports, and leaves dialogs, splash
screens and other windows that are not for tiling alone, and the windows that [rules](rules.md)
say to ignore. The commands here act on the window
that has the focus in KWin, take a window out of the layout or back into it, and pause the
daemon.
## Minimizing and closing
[`komorebic minimize`](../cli/minimize.md) asks KWin to minimize the window that has the focus,
and [`komorebic close`](../cli/close.md) asks it to close the window, as the buttons of its title
bar do.
```sh
komorebic minimize
komorebic close
```
The window leaves the layout when KWin reports that it was minimized or closed, and the other
windows of the workspace share the work area. A minimized window comes back into the layout, in a
container of its own, when it is restored.
## Taking a window out of the layout
[`komorebic unmanage`](../cli/unmanage.md) takes the window that has the focus out of the layout.
It stays open, in the middle of the work area with the size it had, and komorebi leaves it alone
from then on: it does not tile it again, and it does not move it.
[`komorebic manage`](../cli/manage.md), with that window focused, puts it back in the layout,
after the focused window, or where the workspace's
[placement rules](../initial-window-placement-rules.md) say.
```sh
komorebic unmanage
komorebic manage
```
`komorebic manage` also takes in a window komorebi missed, such as one that opened while the
daemon was paused, but not a window an ignore rule covers. The daemon forgets an unmanaged window when it closes, and when the daemon
stops.
## Commands while the focused window is not tiled
By default, a command acts on the workspace whatever window has the focus. With
[`komorebic unmanaged-window-operation-behaviour no-op`](../cli/unmanaged-window-operation-behaviour.md),
the daemon ignores every command while the window that has the focus is not one of the windows it
tiles: a floating window, a window it does not manage, or one taken out with
`komorebic unmanage`. The daemon logs "ignoring commands while active window is not managed by
komorebi" for each.
```sh
komorebic unmanaged-window-operation-behaviour no-op
komorebic unmanaged-window-operation-behaviour op
```
The commands that are ignored include `komorebic state`, `komorebic stop` and the command that
sets the behavior back to `op`: give the focus to a tiled window first.
## Pausing
[`komorebic toggle-pause`](../cli/toggle-pause.md) pauses the daemon, and the same command
resumes it. While it is paused, komorebi does not act on what KWin reports, so it moves no
window, and of its commands it carries out only `toggle-pause`, `state`, `global-state` and
`stop`. The daemon's state says whether it is paused, as `is_paused`.
```sh
komorebic toggle-pause
```
What KWin reported while the daemon was paused is not acted on afterwards: a window that opened
in the meantime is not tiled until it is managed with `komorebic manage`.
+60
View File
@@ -0,0 +1,60 @@
# Maximizing windows
[`komorebic toggle-maximize`](../cli/toggle-maximize.md) has KWin maximize the window that has the
focus: it takes the work area of its monitor, the panels left alone, and has no padding around it.
The window leaves the layout while it is maximized, and the same command restores it and puts it
back in a container of its own, at the place in the order of the workspace it was taken from.
A window you maximize yourself, with its title bar, a double click or a shortcut, is treated the
same way: see [A window you maximize](#a-window-you-maximize).
```sh
komorebic toggle-maximize
```
A window that is the only one of its container takes the container with it, and the container is
made again when the window comes back. The tiles that were left are not moved while the window is
maximized: it covers them. A window that opens meanwhile is added to the layout, where a new
window goes (after the focused container, unless the workspace has
[placement rules](../initial-window-placement-rules.md)), and has its tile when the maximized
window is restored. A window that closes while it is maximized takes the maximize with it, and the
other windows are tiled again.
A window in [monocle](monocle.md) that is maximized leaves the monocle. When the monitor of a
maximized window is unplugged, the window goes to a monitor that is left and stays maximized: see
[Changing monitors](changing-monitors.md#a-monitor-is-unplugged).
## A window you maximize
KWin tells komorebi when a window is maximized or restored, whoever did it. A window you maximize
leaves the layout as it does for `toggle-maximize`, and the tiles that were left are not moved
while it is maximized. A window that was floating or in [monocle](monocle.md) leaves that as well.
If another window is maximized already, it goes back to its tile. A window that is already
maximized when komorebi starts, or that opens maximized, is the maximized window from the start.
When you restore the window, with its title bar, a double click or a shortcut, it goes back in a
container of its own at the place it came from, as if `toggle-maximize` had restored it; a window
that was floating comes back as a tile. `toggle-maximize` restores a window you maximized, too.
Only a window that KWin has maximized both ways counts: a window maximized in one direction only,
which a shortcut can do, is a restored window to komorebi.
## What is left alone
While a window is maximized, by `toggle-maximize` or by you, the commands that are about the tiles
of the layout do nothing, and the daemon logs that it ignores them: [`move`](../cli/move.md),
[`cycle-move`](../cli/cycle-move.md), the [stack](stacking-windows.md) commands,
[`promote`](../cli/promote.md) and the other promote commands,
[`resize-edge`](../cli/resize-edge.md) and [`resize-axis`](../cli/resize-axis.md),
[`preselect-direction`](../cli/preselect-direction.md), [`toggle-lock`](../cli/toggle-lock.md),
[`toggle-float`](../cli/toggle-float.md), [`toggle-monocle`](../cli/toggle-monocle.md), and the
commands that move or send a container to another monitor or workspace, such as
[`move-to-monitor`](../cli/move-to-monitor.md) and
[`send-to-workspace`](../cli/send-to-workspace.md). Restore the window first.
[`komorebic focus`](../cli/focus.md) finds no container on any side of the maximized window, so
the focus goes to the monitor on that side, and the command fails where there is none. A
maximized window, or a window in monocle, on the workspace it reaches is given the focus whole.
## In the daemon's state
A workspace with a maximized window has it as `maximized_window`, which is not in its
`containers`, and the index it goes back to as `maximized_window_restore_idx`.
+56
View File
@@ -0,0 +1,56 @@
# Monocle
A workspace in monocle shows one window: the container that has the focus takes the whole work
area, and the layout gives the other containers no tile, and their windows are out of sight,
until the monocle is turned off.
[`komorebic toggle-monocle`](../cli/toggle-monocle.md) turns the monocle of the focused workspace
on, for the container that has the focus, and off. The window is put where a window alone in the
workspace would be: the work area less the panels, the workspace padding and the container
padding. Turned off, the container goes back to the place in the order of the workspace it was
taken from, and the layout tiles every container again.
```sh
komorebic toggle-monocle
```
The windows of the other containers are hidden while the monocle is on, the way the windows behind
the front one of a [stack](stacking-windows.md) are, and the front window of each is shown again
when the monocle is turned off. A window that opens meanwhile is added to the layout after the
focused container, and has its tile when the monocle is turned off. When the window in monocle
closes, the monocle is gone and the other windows are shown and tiled again.
## Focusing
Giving the focus to another window does not take the monocle with it: komorebi gives the focus
back to the window in monocle, so that it is the one in front. What focusing in a direction
does meanwhile is set with
[`komorebic monocle-focus-behaviour`](../cli/monocle-focus-behaviour.md):
- `no-op`, the default: no container is on any side of the window in monocle, so
[`komorebic focus`](../cli/focus.md) goes to the monitor on that side, as it does at the edge of
a layout, and gives the focus to the window in monocle there if its workspace has one. Where
there is no monitor on that side it fails, and the daemon logs "there is no container or
monitor in this direction".
- `cycle`: `komorebic focus left` or `down` makes the previous container the monocle, and
`right` or `up` the next one.
[`komorebic toggle-monocle-focus-behaviour`](../cli/toggle-monocle-focus-behaviour.md) switches
between the two, and `monocle_focus_behaviour` in `komorebi.json` (`NoOp` or `Cycle`) sets it from
the file. [`komorebic cycle-focus`](../cli/cycle-focus.md) always carries the monocle to the next or
the previous container, whatever the behavior is.
```sh
komorebic monocle-focus-behaviour cycle
komorebic toggle-monocle-focus-behaviour
```
## What is left alone
While a window is in monocle, [`komorebic move`](../cli/move.md) and
[`komorebic cycle-move`](../cli/cycle-move.md) are refused, and
[`komorebic toggle-float`](../cli/toggle-float.md) does nothing: the daemon logs that it ignores
them. Turn the monocle off first.
In the daemon's state, a workspace in monocle has the container as `monocle_container`, which
is not one of its `containers`, and the index it goes back to as `monocle_container_restore_idx`.
+132
View File
@@ -0,0 +1,132 @@
# Moving windows
komorebi moves the focused window to another tile of its workspace when it is told to, or when
the window is dragged there. The window swaps places with the window on that tile, the workspace
is tiled again, and the window that moved keeps the focus.
## In a direction
[`komorebic move`](../cli/move.md) swaps the focused window with the window whose tile is on one
side of it: `left`, `right`, `up` or `down`. As with
[`komorebic focus`](focusing-windows.md#in-a-direction), the layout decides which tile is on
which side.
```sh
komorebic move left
komorebic move down
komorebic move up
komorebic move right
```
When there is no tile on that side, the window goes to the monitor on that side, if there is one,
and takes the place nearest the monitor it came from. What it does there is
[`komorebic cross-monitor-move-behaviour`](../cli/cross-monitor-move-behaviour.md): `swap`, the
default, sends the window it takes the place of back to where it came from; `insert` puts it in
among the windows there; `no-op` keeps it where it is.
[`komorebic toggle-cross-monitor-move-behaviour`](../cli/toggle-cross-monitor-move-behaviour.md)
switches between `insert` and `swap`. With no monitor on that side, nothing moves, and the daemon
logs "there is no container or monitor in this direction".
## To another monitor
[`komorebic move-to-monitor`](../cli/move-to-monitor.md) takes the focused window to a monitor, by
its index, and focuses it there; [`komorebic send-to-monitor`](../cli/send-to-monitor.md) does the
same and leaves the focus on the monitor it came from. Their `cycle-` forms take the next or the
previous monitor. [`komorebic move-to-monitor-workspace`](../cli/move-to-monitor-workspace.md) and
[`komorebic send-to-monitor-workspace`](../cli/send-to-monitor-workspace.md) name a workspace of
that monitor too, and [`komorebic move-to-named-workspace`](../cli/move-to-named-workspace.md) and
[`komorebic send-to-named-workspace`](../cli/send-to-named-workspace.md) find it by its name.
```sh
komorebic move-to-monitor 1
komorebic send-to-monitor-workspace 1 2
```
[`komorebic move-workspace-to-monitor`](../cli/move-workspace-to-monitor.md) takes the whole
workspace in front to another monitor, and
[`komorebic swap-workspaces-with-monitor`](../cli/swap-workspaces-with-monitor.md) exchanges the
workspaces of the focused monitor with those of another.
## In order
[`komorebic cycle-move`](../cli/cycle-move.md) swaps the focused window with the next or the
previous window in the order of the workspace, and wraps around: `next` from the last window
swaps it with the first.
```sh
komorebic cycle-move next
komorebic cycle-move previous
```
## To the largest tile
The first tile of a layout is the largest one: the left half in BSP and the vertical stack, the
top half in the horizontal stack, the middle of the ultrawide vertical stack and the right half
in the right main vertical stack. In the columns, rows and scrolling layouts it is the first
column or row. The grid layout is left alone: these commands do nothing there.
[`komorebic promote`](../cli/promote.md) moves the focused window to the first tile, and the
windows that were before it each move one tile on.
[`komorebic promote-swap`](../cli/promote-swap.md) swaps the focused window with the window on
the first tile instead, and from the first tile swaps it back with the window it was last
swapped with. [`komorebic promote-window`](../cli/promote-window.md) promotes the window on one
side of the focused one.
```sh
komorebic promote
komorebic promote-swap
komorebic promote-window left
```
[`komorebic promote-focus`](../cli/promote-focus.md) gives the focus to the window on the first
tile and moves nothing.
## Locking a window in its place
[`komorebic toggle-lock`](../cli/toggle-lock.md) locks the focused window's container at its
place in the order of the workspace, and unlocks it again. Windows that open, close or move
around a locked container leave it where it is: a new window that would go in its place goes
after it. A window moved onto the place of a locked one with `move`, `cycle-move` or
`promote-swap` is locked there instead, since the lock belongs to the place.
```sh
komorebic toggle-lock
```
The `LockMonitorWorkspaceContainer` and `UnlockMonitorWorkspaceContainer` messages lock and
unlock a container by the index of its monitor, its workspace and itself, for a program such as
a status bar. They have no subcommand.
## By dragging
A window can be moved with the pointer too: drag it by its title bar and let go. Where it goes
depends on where the pointer is:
- On the tile of another window of the same monitor, the two windows swap places, and the
workspace is tiled again. With the
[window container behavior](stacking-windows.md#windows-that-open-into-a-stack) set to `append`,
the window joins the stack on that tile instead, in front.
- On another monitor, the window goes there, with the stack it is in, and takes the place of the
container whose tile it was let go on, which moves one place on. On a monitor with no window it
is the first container. Both monitors are tiled again.
- Where there is no tile, on a panel for example, the window goes back to its own.
With the [float override](floating-windows.md#windows-that-open-floating) on, a window let go on a
tile of its own monitor floats where it was let go instead. A floating window can be dragged
anywhere and takes no tile. Let go on another monitor, it is one of the floating windows there,
but only when the workspace it came from has a tile: with nothing else on it, komorebi does not
notice that the window changed monitors.
komorebi takes a drag for a move when the window's frame is as wide and as tall as its tile at
the end of it, or when it ends on another monitor. A client that sizes itself in steps, such as
a terminal that keeps to whole cells of its font, can be a few pixels short of its tile: dragging
it on its own monitor swaps nothing, and it stays where it was let go until the workspace is
tiled again, which the next change of focus does.
## The pointer
The pointer follows the window that moved, unless
[mouse follows focus](focusing-windows.md#the-pointer) is off. A drag is the exception: the
pointer is where it was let go, whether the windows swapped, the window joined another or went
back to its tile. Only a window let go on another monitor takes the pointer with it, to the
middle of its tile, unless mouse follows focus is off.
+83
View File
@@ -0,0 +1,83 @@
# Padding and work area offsets
komorebi tiles the windows of a workspace in the work area of its monitor, which is the part of
the monitor that KWin reports free of Plasma's panels. Padding puts gaps around the tiles, and an
offset keeps a part of the work area free of tiles.
## Padding
A workspace has two paddings, in pixels:
- the **workspace padding**, between the edges of the work area and the tiles;
- the **container padding**, around each tile, so that two tiles side by side are twice that far
apart.
A workspace that has no padding of its own takes 5 pixels for each.
[`komorebic focused-workspace-padding`](../cli/focused-workspace-padding.md) and
[`komorebic focused-workspace-container-padding`](../cli/focused-workspace-container-padding.md)
set the paddings of the focused workspace, and
[`komorebic workspace-padding`](../cli/workspace-padding.md) and
[`komorebic container-padding`](../cli/container-padding.md) those of a workspace given by the
index of its monitor and its own, counted from 0.
[`komorebic named-workspace-padding`](../cli/named-workspace-padding.md) and
[`komorebic named-workspace-container-padding`](../cli/named-workspace-container-padding.md) find
the workspace by the [name](workspaces.md#names) it was given instead, on whichever monitor has
it. A name no workspace has changes nothing.
```sh
komorebic focused-workspace-padding 20
komorebic focused-workspace-container-padding 10
komorebic workspace-padding 0 1 0
komorebic container-padding 0 1 0
komorebic named-workspace-padding mail 0
komorebic named-workspace-container-padding mail 0
```
[`komorebic adjust-workspace-padding`](../cli/adjust-workspace-padding.md) and
[`komorebic adjust-container-padding`](../cli/adjust-container-padding.md) make a padding of the
focused workspace larger or smaller by a number of pixels. They change a padding the workspace
has of its own, set by one of the commands above: on a workspace that has none, the daemon logs
"there is no workspace padding" or "there is no container padding". A padding is not made
smaller than 0.
```sh
komorebic adjust-workspace-padding increase 5
komorebic adjust-container-padding decrease 5
```
## Work area offsets
An offset is four numbers. The first two move the top left corner of the work area right and
down; the last two make the work area narrower and shorter. So `0 40 0 40` keeps a strip of 40
pixels at the top free, `0 0 0 40` a strip at the bottom, and `40 0 40 0` a strip on the left.
[`komorebic global-work-area-offset`](../cli/global-work-area-offset.md) sets the offset of every
monitor, [`komorebic monitor-work-area-offset`](../cli/monitor-work-area-offset.md) the offset of
one monitor, which it takes instead of the global one, and
[`komorebic workspace-work-area-offset`](../cli/workspace-work-area-offset.md) the offset of one
workspace, which it takes instead of both. Each tiles every monitor again, as
[`komorebic retile`](../cli/retile.md) does.
```sh
komorebic global-work-area-offset 0 40 0 40
komorebic monitor-work-area-offset 1 0 0 0 40
komorebic workspace-work-area-offset 0 2 40 0 40 0
```
A monitor can also have a window-based offset, which applies on top of the other one while the
workspace in front has no more windows than the monitor's limit, 1 unless it is given another.
With a window-based offset, a window that is alone on a wide monitor does not have to take its
whole width. No command sets a monitor's window-based offset: it is part of the configuration of
a monitor.
[`komorebic toggle-window-based-work-area-offset`](../cli/toggle-window-based-work-area-offset.md)
turns it off for the focused workspace, and on again.
```sh
komorebic toggle-window-based-work-area-offset
```
The daemon's state has the offsets as `work_area_offset` (of the window manager, of each monitor
and of each workspace), and a monitor's window-based offset and limit as
`window_based_work_area_offset` and `window_based_work_area_offset_limit`.
@@ -0,0 +1,60 @@
# Quickstart and autostart
## Quickstart
[`komorebic quickstart`](../cli/quickstart.md) writes three example files into the config home
(`~/.config/komorebi`, or `$KOMOREBI_CONFIG_HOME`), which it makes if it has to:
- `komorebi.json`, which is [`docs/komorebi.example.json`](../example-configurations.md):
eight workspaces on the first monitor, each with another layout, and some padding;
- `applications.json`, which is
[`komorebic/applications.json`](application-specific-configuration.md#the-file-komorebi-ships),
the rules `komorebi.json` names for the applications that need them;
- `skhdrc`, which is [`docs/skhdrc.sample`](../skhdrc.sample): the [key bindings](keybindings.md)
of the sample, in the format of skhd, which the daemon and `komorebic hotkeys compile` read from
there.
When a file is there already, `quickstart` asks before it writes over it, and leaves the file
alone unless the answer is `y` or `yes`. It prints the files it wrote, and then tells you to run
`komorebic start`.
```sh
komorebic quickstart
komorebic start
```
## Starting komorebi with Plasma
On NixOS, [the module](../installation.md#nixos) starts komorebi with every Plasma session.
Elsewhere, [`komorebic enable-autostart`](../cli/enable-autostart.md) writes an XDG autostart
entry, `~/.config/autostart/komorebi.desktop` (`$XDG_CONFIG_HOME/autostart`), which Plasma runs at
login, after its workspace has started:
```sh
komorebic enable-autostart
komorebic enable-autostart --config ~/mine.json
```
The entry runs `komorebi`, or `komorebi --config` with the file `--config` names, as the session
finds `komorebi` on its `PATH`. [`komorebic disable-autostart`](../cli/disable-autostart.md) takes
the entry away again, and says so when there is none.
Do not use both the module and the entry: the session bus gives its name to one komorebi, and the
second exits.
## Starting over with another file
[`komorebic replace-configuration`](../cli/replace-configuration.md) makes the running daemon start
over from another `komorebi.json`:
```sh
komorebic replace-configuration ~/work.json
```
The daemon makes its window manager again from the file, as it does at start: it brings back
the windows it had hidden, the back of a stack, so that none is out of sight, loads the monitors
and the windows that are open from KWin, gives the monitors the entries of the file and tiles
them, and from then on watches the new file and not the one it had. It is not the same as
changing the file the daemon watches, which [Configuration](configuration.md#changing-the-file)
describes: the windows that were in a workspace go where the new file puts them, not where they
were. A file that is not a `komorebi.json` is logged, and the daemon carries on as it was.
+77
View File
@@ -0,0 +1,77 @@
# Resizing windows
komorebi resizes the focused window by moving the edges of its tile, and its neighbors give up
the room. A window can also be resized by dragging one of its edges. The size a tile has been
given is kept until the workspace is retiled with `komorebic retile`, so it lasts while windows
open and close around it.
## An edge
[`komorebic resize-edge`](../cli/resize-edge.md) (or `resize`) moves one edge of the focused
window: `left`, `right`, `up` or `down`, and `increase` moves it outwards, `decrease` inwards.
```sh
komorebic resize-edge left increase
komorebic resize-edge right decrease
```
An edge with no tile on the other side of it, such as the left edge of the first window in the
BSP layout, does not move. Neither does an edge the layout keeps where it is: the grid layout
has no resizing at all, and in the columns layout a window can only be made wider or narrower.
## An axis
[`komorebic resize-axis`](../cli/resize-axis.md) moves both edges of the focused window along an
axis: `horizontal` the left and the right edge, `vertical` the top and the bottom edge, and
`horizontal-and-vertical` all four.
```sh
komorebic resize-axis horizontal increase
```
## How far
[`komorebic resize-delta`](../cli/resize-delta.md) sets how far a resize goes, in pixels: an
edge moves by half of it. The delta starts at 50, so an edge moves by 25 pixels.
```sh
komorebic resize-delta 100
```
A resize never makes a tile narrower or shorter than a tenth of the monitor's work area, unless
the tile is smaller than that already: a resize that would is carried out as far as it can go.
## By dragging an edge
Take hold of an edge or a corner of a tiled window with the pointer, drag it, and let go: the
edges of the window's tile move by as much as the pointer moved them, the neighbors give up or
take the room, and the window is put on its tile. The neighbors follow the edge while it is
dragged, and go back if it is dragged back to where it began, without the animation of
[`animation`](animation.md): the effect leaves a user's resize alone. A corner moves two edges. The rules
are those of `resize-edge`: an edge with no tile on the other side of it does not move, and the
window goes back to its tile; no tile is made smaller than a tenth of the work area, so a long
drag goes as far as it can. The window of a stack has the tile of the stack. A floating window and
the window of a monocle have no tile: they are left as the user made them. [Resizing a tile by
dragging its edge](../drag-resize.md) says how a drag is measured.
## Back to the layout
[`komorebic retile`](../cli/retile.md) tiles every monitor again in its layout, without the
sizes the tiles were given. To tile again and keep them, send the `RetileWithResizeDimensions`
message, which has no subcommand of its own.
## Saving and loading the sizes
The sizes the tiles of the focused workspace were given can be saved to a file and loaded back,
on the same workspace or another one with as many windows:
```sh
komorebic save-resize ~/sizes.json
komorebic load-resize ~/sizes.json
```
[`komorebic quick-save-resize`](../cli/quick-save-resize.md) and
[`komorebic quick-load-resize`](../cli/quick-load-resize.md) do the same with one file the daemon
keeps in its temporary directory, `komorebi.quicksave.json` in `$TMPDIR` (or `/tmp`). A path
given to `save-resize` and `load-resize` can name environment variables, which `komorebic`
expands.
+71
View File
@@ -0,0 +1,71 @@
# Rules
A rule names an application by one of four things about its windows, and says what komorebi does
with them:
- `exe`: the name of the program's executable, such as `kate`;
- `class`: the app id of a Wayland window, such as `org.kde.kate`, or the class of an X11 window;
- `title`: the title of the window;
- `path`: the full path of the executable, such as `/usr/bin/kate`.
[`komorebic state`](../cli/state.md) shows them for every window komorebi has, as the `title`,
`exe`, `class` and `path` of its `details`.
## Ignoring an application
[`komorebic ignore-rule`](../cli/ignore-rule.md) makes komorebi leave the windows of an
application alone. A rule given this way matches a title or a class that starts or ends with what
it names, and an executable or a path that is exactly what it names. The windows it matches are
not tiled when they open, and the tiled windows of the workspaces in front whose executable,
class, title or path is exactly what it names leave the layout.
```sh
komorebic ignore-rule exe steam
komorebic ignore-rule class org.kde.kcalc
komorebic ignore-rule title "Picture-in-Picture"
```
`komorebic float-rule` is the same command. Plasma's desktop and panels (`plasmashell`) and
KRunner are ignored from the start.
[`komorebic manage-rule`](../cli/manage-rule.md) makes komorebi tile the windows of an
application that an ignore rule covers, from the next one that opens.
```sh
komorebic manage-rule class org.kde.plasmashell
```
[`komorebic manage`](managing-windows.md#taking-a-window-out-of-the-layout) does not take in a
window an ignore rule covers: a manage rule does.
## When a rule decides
A rule decides when a window opens. Applications often open a window before they give it its
title, so the title a rule sees then can be a placeholder. When the title of a window komorebi
does not have changes, komorebi asks the rules again, so a window that a title rule ignored while
it had its first title is tiled once its title no longer matches. A window komorebi tiles stays
tiled whatever its title becomes.
## Floating the windows of an application
[`komorebic session-float-rule`](../cli/session-float-rule.md) takes the focused window out of
the layout into the floating windows of its workspace, and adds a rule that floats every window
that opens with the same executable, class and title.
[`komorebic session-float-rules`](../cli/session-float-rules.md) shows those rules, and
[`komorebic clear-session-float-rules`](../cli/clear-session-float-rules.md) removes them: the
windows that float already stay floating.
```sh
komorebic session-float-rule
komorebic session-float-rules
komorebic clear-session-float-rules
```
A window that a float rule matches floats when it opens, and
[`komorebic toggle-float`](floating-windows.md) puts one in the layout.
## How long rules last
The rules given with these commands last until the daemon stops.
[`komorebic global-state`](../cli/global-state.md) shows the ignore and the manage rules the daemon
has, and its data directory.
+169
View File
@@ -0,0 +1,169 @@
# Running komorebi
`komorebi` is the daemon that tiles your windows, and `komorebic` is the command line you
control it with. This page covers starting and stopping the daemon, asking it what it is
doing, and reading its log.
## Getting the two programs
[Installing komorebi](../installation.md) covers NixOS, where the flake's module installs both
and starts the daemon with every Plasma session, and building them from source. In a checkout of
the repository, on Linux, `nix build` leaves them in `result/bin`, and `nix profile install .`
puts them on your `PATH`. Without nix, build them with the Rust toolchain that
`rust-toolchain.toml` selects:
```sh
cargo build --release --locked
export PATH="$PWD/target/release:$PATH"
```
With the NixOS module, the daemon is the user unit `komorebi.service`, which starts when you log
in to Plasma. `systemctl --user start komorebi` starts it again after a `komorebic stop`, and
`journalctl --user -u komorebi` shows what it wrote. Everything else on this page applies to it
as it is.
## Starting and stopping
[`komorebic start`](../cli/start.md) runs the `komorebi` on your `PATH` in the background,
and checks three seconds later that it is running. It tries three times. If `komorebi` has
not started by then, `komorebic start` runs it once more in the foreground and prints what
it wrote on its standard error, which explains why it did not start. When a `komorebi` is
running already, `komorebic start` does nothing.
`komorebi` manages the windows of the Plasma Wayland session it is started in: it connects
to KWin on the session bus and loads a script into it, so start it from a terminal in that
session. Outside a Plasma session it exits with an error that says what is missing, which
`komorebic start` prints. [`komorebic check`](checking-the-setup.md) says what is missing from the
session, and what is wrong with the configuration, without starting anything.
`--config` gives the daemon the `komorebi.json` to read
([Configuration](configuration.md) says where it looks otherwise), and
[`komorebic quickstart`](quickstart-and-autostart.md) writes one to start from:
```sh
komorebic start --config ~/mine.json
```
Everything after a `--` is passed to `komorebi`. `--fake-backend` runs it against an
in-memory desktop with one monitor and no windows instead of KWin, which is a way to try the
daemon and `komorebic` without a compositor:
```sh
komorebic start
komorebic start -- --log-level debug
komorebic start -- --fake-backend
```
[`komorebic stop`](../cli/stop.md) tells the daemon to stop. It brings back the windows it hid (the
back of a stack, [stacking windows](stacking-windows.md), and the windows behind a
[monocle](monocle.md)), removes the desktop they were hidden on, asks KWin to unload its script,
removes its socket and exits. Stopping the process with `SIGINT` or `SIGTERM` does the same.
## Key bindings
[Key bindings](keybindings.md) is the guide to key bindings, and to the NixOS module's
options for them; this section is a summary for a daemon started by hand.
komorebi reads key bindings from a file in the format of skhd, whkd or sxhkd. The daemon
looks for `skhdrc`, `whkdrc` or `sxhkdrc` in `~/.config/komorebi` (or in
`$KOMOREBI_CONFIG_HOME`) and takes the first it finds; `--keybindings FILE` names another,
with `--keybindings-format skhd|whkd|sxhkd` when its name does not end with one of those.
The daemon registers the keys with KDE itself and runs the command of each press:
```sh
komorebic start -- --keybindings ~/dotfiles/skhdrc
```
KDE can also run a binding with no komorebi process, as a static shortcut that shows in System
Settings: [`komorebic hotkeys compile`](../cli/hotkeys-compile.md) writes those, and
`--mode auto` writes every binding that can be one. Give the daemon the same mode, so that it
leaves those bindings to KDE:
```sh
komorebic hotkeys compile --mode auto
komorebic start -- --keybindings-mode auto
```
The daemon realizes the modes of an skhdrc (and the chains of an sxhkdrc that stay open)
itself: while a mode is active, only its keys are taken, and every other key reaches the
window as usual. The log says which mode the daemon is in after each change. A chord chain
of an sxhkdrc (`alt + w ; h`) works the same way: after `alt + w`, only the keys that can
come next and Escape are taken, until one of them is pressed or 3 seconds pass
(`--chord-timeout 1500` waits 1.5 seconds instead).
A binding that does something else in each application (skhd's `[ ... ]` list, whkd's
per-application list) takes its key only while an application it names has the focus, or
any application for a `*` or `Default` entry; everywhere else the key reaches the application.
A name matches the executable, the Wayland app id (`org.kde.konsole`) or the desktop entry of
the focused window, whatever the case. skhd and whkd name applications as macOS and Windows
do, so give the daemon the names they have on KDE:
```sh
komorebic start -- --app-alias firefox=firefox-esr,librewolf --app-alias Terminal=konsole
```
[`komorebic hotkeys state`](../cli/hotkeys-state.md) shows the keys komorebi has registered
with KDE and what the daemon's engine is doing (its mode, and the keys it holds), and
[`komorebic hotkeys reload`](../cli/hotkeys-reload.md) has the daemon read its key binding
file again. A daemon that is killed leaves its keys swallowed until it is started again;
`komorebic stop` gives them back, and so does
[`komorebic hotkeys release`](../cli/hotkeys-release.md), with or without a daemon, which the
NixOS module's unit runs after the daemon stops. When KWin restarts, the daemon registers the
keys again with the new KWin.
## Asking komorebi what it is doing
The daemon answers questions on its socket, and these commands print the answers:
- [`komorebic state`](../cli/state.md): every monitor, with its workspaces, their
containers and the windows in them, as JSON.
- [`komorebic monitor-information`](../cli/monitor-information.md): the id, the name and
the bounds of every monitor, as JSON.
- [`komorebic query`](../cli/query.md): one value, the answer to one question: the index of
the focused monitor, workspace, container or window, the layout of the focused workspace,
whether the focused container is a single window or a stack, or the version of the
daemon.
```sh
komorebic query focused-workspace-index
komorebic state | jq '.monitors.elements[0].workspaces.elements[0].containers.elements | length'
```
[`komorebic retile`](../cli/retile.md) tiles the windows of every monitor again, which puts
a window that was moved by hand back on its tile.
When the daemon is not running, these commands fail: there is no socket to write to.
A program that wants to know what komorebi does without asking can subscribe to its
notifications instead ([Subscribing to notifications](subscribing-to-notifications.md)).
## The socket and the data directory
The daemon listens on `komorebi.sock` in its data directory, `$XDG_RUNTIME_DIR/komorebi`
(the local data directory, `~/.local/share/komorebi`, when there is no runtime directory).
[`komorebic data-directory`](../cli/data-directory.md) prints the directory, if it exists.
## The log
The daemon logs to its standard output and to a file a day in `~/.local/share/komorebi`
(`$XDG_DATA_HOME/komorebi` when that is set): `komorebi.log.YYYY-MM-DD`, with colors, and
`komorebi_plaintext.log.YYYY-MM-DD`, without. The day is the UTC date.
[`komorebic log`](../cli/log.md) follows the file of the current day, with colors, until
you press Ctrl-C. The `--log-level` of `komorebi` sets how much is logged: `error`, `warn`,
`info` (the default), `debug` or `trace`.
## Shell completions
[`komorebic completions`](../cli/completions.md) prints a completion script for bash,
elvish, fish, PowerShell or zsh:
```sh
komorebic completions fish > ~/.config/fish/completions/komorebic.fish
komorebic completions bash > ~/.local/share/bash-completion/completions/komorebic
```
## Every command
[`docs/cli`](../cli/start.md) has a page for every `komorebic` command, generated from its
help with `just docgen`.
+191
View File
@@ -0,0 +1,191 @@
# The Scrolling Layout
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.
```json
{
"monitors": [
{
"workspaces": [
{
"name": "I",
"layout": "Scrolling",
"layout_options": {
"scrolling": {
"columns": 3,
"center_focused_column": "Never"
}
}
}
]
}
]
}
```
## Column widths
`columns` says how many columns fit across the screen, which is to say that a new column is a `columns`th of the screen
wide. It is `3` unless you say otherwise. It does not say how many windows there are: a lone window is a third of the
screen wide, and is not stretched to fill it.
- Opening or closing a window never changes the width of another window.
- A column that you have resized keeps its width as windows come and go.
- Columns that you have not resized follow `columns`. Changing it with
[`komorebic scrolling-layout-columns`](../cli/scrolling-layout-columns.md), or crossing the threshold of a
`layout_options_rules` entry, lays them out again.
## Centring the focused column
`center_focused_column` says when the focused column is put in the middle of the screen. It is one of:
- `"Never"`, the default, which scrolls only as far as it has to.
- `"Always"`, which keeps the focused column in the middle of the screen.
- `"OnOverflow"`, which centres it when it does not fit on the screen together with the column that focus came from.
`true` and `false` are also accepted, as they were before there were three choices: `true` is `"Always"` and `false` is
`"Never"`. Like `columns`, it is set for a workspace, or for a `layout_options_rules` entry.
A lone window is a third of the screen wide, at the left edge. To have it fill the screen, or to take it out of the
layout for a while, use [`komorebic toggle-monocle`](../cli/toggle-monocle.md).
The layout options of a workspace can also be given for a number of windows, as `layout_options_rules`, which is
where `columns` and `center_focused_column` change when the workspace has that many windows.
## Columns of several windows
A column can hold more than one window, one above the other, sharing the height of the screen. A new window is always a
column of its own, to the right of the column that has focus. To put windows in the same column:
- [`komorebic consume right`](../cli/consume.md) takes the first window of the column on the right and puts it at the
bottom of the focused column.
- [`komorebic consume left`](../cli/consume.md) takes the last window of the column on the left and puts it at the top of
the focused column.
- [`komorebic expel`](../cli/expel.md) takes the focused window out of its column and puts it in a column of its own on
the right.
- [`komorebic toggle-column-stack`](../cli/toggle-column-stack.md) stacks the windows of the focused column, or spreads
the focused stack out into a column with a window in each slot. A [stack](../cli/stack.md) is one slot that shows one
window at a time, and it takes the height of the column. The window that has focus keeps it. The column keeps its width,
but the heights that its windows were given are not remembered for when you toggle back.
A stack is the stack that you have in every layout, so [`cycle-stack`](../cli/cycle-stack.md),
[`focus-stack-window`](../cli/focus-stack-window.md) and [`stack`](../cli/stack.md) work on it as they always do.
[`unstack`](../cli/unstack.md) takes the window that has focus off the stack and puts it in a column of its own to the
right of the one that it was in.
These only do anything in the Scrolling layout, which is the only one with columns of several windows for now.
The focused window keeps focus, and stays where it is on screen, when you do any of these.
Focus and move commands know about columns:
- [`focus left` and `focus right`](../cli/focus.md) go to the neighbouring column, and to the window in it that had focus
last. `focus up` and `focus down` go to the windows of the focused column, and stop at the ends, where they carry on
to another monitor as they always did.
- [`move left` and `move right`](../cli/move.md) move the whole focused column. `move up` and `move down` move the
window up or down in its column.
- A column keeps its width, and a [stack](../cli/stack.md) is still one tile showing one of its windows, as in any layout.
A column that you resized, or made the full width of the screen, keeps that as windows are added to it or taken out.
A window that you move to another workspace or monitor is a column of its own there, and keeps the width of the column
that it was in.
## Heights
The windows of a column share its height equally. To change that:
- [`komorebic resize-edge up`, `down`](../cli/resize-edge.md) and the [axis](../cli/resize-axis.md) commands make the
focused window taller or shorter, by half of the [resize delta](../cli/resize-delta.md) for each edge. The other windows
in the column share what it leaves.
Giving a window a height gives the others in its column an equal share of what it leaves, so there is always something
to take up the difference. No window is made shorter than 100 pixels, and what one window is given cannot
leave the others with less. A window that is alone in its column is as tall as the screen, and a window that is taken
out of its column, or put in another, starts with an equal share.
## Full width and centring
- [`komorebic scrolling-layout-full-width`](../cli/scrolling-layout-full-width.md) makes the focused column as wide as the
screen, or puts it back to the width that it had.
- [`komorebic center-focus`](../cli/center-focus.md) scrolls the screen so that the focused column is in the middle of
it, once. `center_focused_column` does it every time that focus moves instead.
- [`komorebic expand`](../cli/expand.md) makes the focused column as wide as it can be without moving another column out
of view: it takes up the room that the columns on the screen leave. It does nothing when there is none, and in the
other layouts. With `center_focused_column` set to `"Always"` it makes the column the full width of the screen, or
puts it back, as `scrolling-layout-full-width` does.
A column that you make the full width of the screen takes the gaps into account, so that it fills the screen exactly.
Nothing else moves to make room for a column that gets wider: the focused column keeps its left edge, and the screen
scrolls only if the column no longer fits.
## Scrolling
The row scrolls only when it has to.
- Focusing a window that is already on screen does not move anything.
- Focusing one that is not scrolls just far enough to bring it in, and no further.
- A window that is wider than the screen starts at the left edge.
- The focused window does not move when windows to its left open, close or change width.
When you close a window, focus goes back to the window that it was opened next to if you have not moved focus since,
and the screen scrolls back to where it was. If you have, focus goes to the window that takes the closed window's place
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 a column. The row comes to rest with a
column against an edge of the screen, and focus goes to the nearest column on the screen if the focused one has gone off
it.
```
alt + wheelup : komorebic pan left
alt + wheeldown : komorebic pan right
```
It does nothing in the other layouts. Panning with the fingers on a touchpad (`pan --stream`) is for Windows only.
## Resizing
[`komorebic resize-edge`](../cli/resize-edge.md) and [`komorebic resize-axis`](../cli/resize-axis.md) change the width of
the focused column, by half of the [resize delta](../cli/resize-delta.md) for each edge, so resizing the horizontal axis
changes the width by the whole delta. Dragging an edge with the mouse does the same. Resizing the top or bottom edge
changes the [height](#heights) of a window that shares its column with others. A window that is alone in its column is
as tall as the screen, so resizing its height does nothing.
[`komorebic retile`](../cli/retile.md) puts every column back to the width that
[`scrolling-layout-columns`](../cli/scrolling-layout-columns.md) gives, and every window in a column of several back to
an equal share of its height, on the focused workspace of each monitor. The focused column stays where it is on screen,
unless it has to scroll to stay in view.
## Windows with a minimum width
Many apps will not make a window narrower than some width, whatever they are asked. KWin reports the size that a window
has drawn at a moment after komorebi asks for it, so komorebi asks a window how wide it is at the first layout after
the windows have had 400 milliseconds to settle, and if it did not get as narrow as its column (by more than 16
pixels, which is what a terminal's grid of cells and the rounding of a scale are), the column becomes as wide as the
window needs. The columns after it move along to make room, and nothing overlaps. A column never gets narrower again
because of this, and never gets wider than the screen. [`retile`](../cli/retile.md) forgets what was learned.
## Windows that are out of view
A window that scrolls out of view comes to rest at the edge of the work area that it left by, with 5 pixels of it still
on screen. It keeps its size, so nothing has to be resized to bring it back, which is what KWin pulls a window back
onto the screen for. A window that is partly in view keeps its size too, and overhangs the edge of the work area.
KWin shows a window on whichever monitor it overlaps, so with more than one monitor this needs care. If another monitor
is next to the edge that a window would rest at or overhang, a window that has scrolled out of view is hidden instead
of parked (it goes where the back windows of a [stack](stacking-windows.md) go, and comes back when the strip scrolls
to it), and a window that is partly in view is made narrower to fit its own work area. Each workspace on 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.
## Limits
- Switching to another layout and back keeps the widths, but a column whose windows were moved past each other in the
other layout is made again from the order that they are in.
- Windows resting at the edges have borders too, so you may see a thin line of one at the edge of the screen.
- There are no animations of the strip: the windows are put where they go at once, or by KWin's own effects.
+45
View File
@@ -0,0 +1,45 @@
# Sleeping and locking
komorebi looks at the desktop again when the machine wakes up and when the screen is unlocked.
There is nothing to configure and no command to run.
## Why
While the screen is locked or the machine is asleep, KWin sends its clients no frame callbacks,
so the windows do not draw and nothing komorebi asked for in that time is done: a window moved
by something else stays where it was moved, and a window that was asked to move does not. The
monitors can come back in another order, or at another size, or not all of them. A window that
is where komorebi did not put it is not in its tile.
## What komorebi does
- **The screen is unlocked.** The lock screen is a window of KWin's, on every desktop and in no
task list, and komorebi does not manage windows like that: it has no tile, and nothing is
moved about while the screen is locked. Locking the screen does nothing. A moment after it is
unlocked (0.6 seconds: the lock screen goes before the windows can be seen), komorebi looks
at the desktop.
- **The machine wakes up.** komorebi hears it from logind (`PrepareForSleep`, which is false when
the machine is awake). Going to sleep does nothing. A moment after it wakes (2.5 seconds: the
outputs are found again one after another, and the compositor moves windows about as they
are), komorebi looks at the desktop.
Looking at the desktop is the same for both. komorebi reads the monitors again, as when one is
unplugged or plugged in ([Changing monitors](changing-monitors.md)), reads the size and work
area of every monitor, finds every window that is on another monitor than the one it has it on,
and tiles every monitor. Nothing is done while komorebi is paused
([`komorebic toggle-pause`](../cli/toggle-pause.md)).
The bridge compares the window KWin has active with the one it last told komorebi about once a
second, because the window that is active again after an unlock is not always announced, and
komorebi's idea of the focus follows KWin's.
## What is not tested
A real suspend and a real resume are not tested: the virtual machines the tests run in have no
way to wake from one. The signals komorebi waits for are tested on private buses, and the lock
screen against a real KWin.
## Following it from a program
A [subscriber](subscribing-to-notifications.md) is sent a notification, whose `event` is `"Wake"`,
when komorebi has looked at the desktop after a wake or an unlock.
+128
View File
@@ -0,0 +1,128 @@
# Stacking windows
A stack is a container with more than one window. The windows share one tile of the layout, and
one of them, the window in front, is in sight: the others are out of the way. Stacking puts two
windows on one tile, so the layout has one tile fewer to give out.
## Putting windows in a stack
[`komorebic stack`](../cli/stack.md) puts the focused window and the window on one side of it in
one stack: `left`, `right`, `up` or `down`. As with
[`komorebic focus`](focusing-windows.md#in-a-direction), the layout decides which tile is on which
side. The focused window ends up in front, and it keeps the focus. Where the layout has no tile on
that side, nothing happens.
```sh
komorebic stack left
komorebic stack down
```
[`komorebic unstack`](../cli/unstack.md) takes the window in front out of its stack and puts it
in a tile of its own, and the next window of the stack is in front again. The tile is after the
stack, unless the workspace has [placement rules](../initial-window-placement-rules.md), which
say where a window goes that gets a tile of its own. A window that is alone on its tile cannot be
unstacked, and the daemon logs "a container must have at least one window".
```sh
komorebic unstack
```
[`komorebic stack-all`](../cli/stack-all.md) puts every window of the focused workspace in one
stack, in the order they had, with the focused window in front.
[`komorebic unstack-all`](../cli/unstack-all.md) takes every window out of the focused stack,
each onto a tile of its own, and the window that had the focus keeps it.
```sh
komorebic stack-all
komorebic unstack-all
```
A stack moves as one: moving it with [`komorebic move`](moving-windows.md#in-a-direction) or to
another workspace takes every window in it. When the window in front closes, the next window of
the stack comes to the front and has the focus.
## Choosing the window in front
[`komorebic cycle-stack`](../cli/cycle-stack.md) brings the next or the previous window of the
focused stack to the front and gives it the focus; the window that was in front is hidden. It
wraps around: `next` from the last window of the stack brings the first.
```sh
komorebic cycle-stack next
komorebic cycle-stack previous
```
[`komorebic focus-stack-window`](../cli/focus-stack-window.md) brings the window at an index of
the stack to the front, counting from 0 in the order the stack has, which is the order of its
`windows` in [`komorebic state`](../cli/state.md). It works on the monitor the pointer is on,
which it focuses first, so that a program such as a status bar that runs it when one of its tabs
is clicked acts on the stack of its own monitor.
```sh
komorebic focus-stack-window 0
```
[`komorebic cycle-stack-index`](../cli/cycle-stack-index.md) moves the window in front one place
along the stack, swapping it with the window there, and wraps around the same way. It stays in
front and keeps the focus: only the order of the stack changes, which is what `cycle-stack` and
`focus-stack-window` count by.
```sh
komorebic cycle-stack-index next
```
A stack of one window cannot be cycled, and an index the stack does not have cannot be focused:
the daemon logs "there is only one window in this container" or "there is no window in this
container at index 5".
## Windows that open into a stack
By default a window that opens gets a tile of its own. With the window container behavior set to
`append`, a window that opens joins the focused stack instead, in front, and a workspace with no
window still gives it a tile of its own, since there is nothing to join.
[`komorebic toggle-window-container-behaviour`](../cli/toggle-window-container-behaviour.md)
switches every workspace between the two.
[`komorebic toggle-workspace-window-container-behaviour`](../cli/toggle-workspace-window-container-behaviour.md)
does it for the focused workspace only: the first time, it takes the opposite of what every
workspace has, and from then on it follows its own setting.
```sh
komorebic toggle-window-container-behaviour
komorebic toggle-workspace-window-container-behaviour
```
The setting is in the daemon's state, as `new_window_behaviour` for every workspace and as
`window_container_behaviour` in each workspace that has one of its own.
In `komorebi.json`, `window_container_behaviour` is the setting for every workspace, `Create` or
`Append`, and the entry of a workspace can have its own. The entry of a workspace can also have
`window_container_behaviour_rules`, which give the behavior by the number of containers:
```json
{ "name": "chat", "layout": "Columns", "window_container_behaviour_rules": { "2": "Append" } }
```
A window opens in a tile of its own until the workspace has two containers, and joins the focused
stack from then on. The [configuration](configuration.md) page says how the rules and the toggle
for one workspace go together.
## Where the windows behind go
komorebi does not minimize the windows behind the front one: it moves them to a virtual desktop
that nobody looks at, which it makes when it first needs it and calls `komorebi-park`. A window
there is still open, still on its workspace as far as komorebi is concerned, and still in the
stack, and it comes back to the desktop of its workspace when it is brought to the front, when it
is unstacked, and when komorebi stops. The parking desktop is the last desktop, after the ones
that are workspaces, and is not one of them.
KWin keeps its virtual desktops in its configuration as soon as one is made, so the parking
desktop would be there in the next session if komorebi did not remove it. It does when it stops.
If komorebi did not get to stop (it was killed, or the session ended under it), the next komorebi
finds the parking desktop in KWin's list, sends the windows on it back to the first workspace's
desktop, and removes it. If the parking desktop is removed while komorebi runs, the next hide
makes a new one.
A window on the parking desktop can still be reached by something else. Raising one, with a
click in the task manager, makes KWin show the parking desktop on that monitor, and komorebi
sends the monitor straight back to the workspace it was showing. The window that was raised
becomes the front of its stack when komorebi handles its focus change.
@@ -0,0 +1,90 @@
# Subscribing to notifications
A program such as a status bar, a widget or a script can follow what komorebi does by
subscribing to its notifications. After each event the window manager handles (a window
was shown, closed, focused, minimized, restored or moved to another output), each message it
takes on its socket and each change of the monitors, the daemon sends every subscriber a
notification: the event, the message or the change, and the state of the window manager after it.
## Subscribing
A subscriber listens on a Unix socket of its own in the daemon's data directory,
`$XDG_RUNTIME_DIR/komorebi` (on NixOS and most systemd distributions,
`/run/user/<uid>/komorebi`), and tells the daemon the name of the socket with
[`komorebic subscribe-socket`](../cli/subscribe-socket.md). The socket has to exist before
it subscribes: the daemon sends the notification of the subscription at once, and removes a
subscriber it cannot connect to.
With [socat](http://www.dest-unreach.org/socat/), a shell can subscribe and print every
notification:
```sh
socat -u UNIX-LISTEN:"$XDG_RUNTIME_DIR/komorebi/bar.sock",fork STDOUT &
komorebic subscribe-socket bar.sock
```
[`komorebic unsubscribe-socket bar.sock`](../cli/unsubscribe-socket.md) stops the
notifications.
## Notifications
The daemon sends each notification on a new connection to the subscriber's socket: it
connects, writes one JSON object, and closes the connection. There is no newline after the
object. The first notification a subscriber receives is the one of its subscription.
A notification has two fields:
- `event`: the event, the message or the change of the monitors. An event is a window event,
with the signal it came from and the window, such as
`{"type":"Show","content":[{"type":"KWin","content":"WindowAdded"},{"id":...}]}`. A
message is written the way a client writes it on the daemon's socket, such as
`{"type":"Retile"}`. A change of the monitors is the name of the change with its content:
`{"Resize":0}` for a monitor that changed size, with the id of the monitor, or 0 when KWin
does not say which, and `{"DisplayConnectionChange":0}` for a monitor that was unplugged or
plugged in, and `"Wake"` for the machine waking up or the screen being unlocked.
[Changing monitors](changing-monitors.md) and [Sleeping and locking](sleeping-and-locking.md)
say when each is sent.
- `state`: the state of the window manager after it, with the same fields as what
[`komorebic state`](../cli/state.md) prints, on one line.
An event about a window that komorebi does not manage, and a message that fails, are not
sent.
## Only when something changed
A subscriber can ask to be sent a notification only when the event or the message changed
the state, with the `filter_state_changes` option. It is still sent the notification of a
window that is shown, of every change of the monitors, of every new subscription, so it
receives the state as soon as it subscribes, of a theme, which changes the colors of the
borders and nothing in the state, and of every reload of `komorebi.json`.
`komorebic subscribe-socket` has no option for it; a program writes the message
on the daemon's socket itself:
```sh
printf '%s' '{"type":"AddSubscriberSocketWithOptions","content":["bar.sock",{"filter_state_changes":true}]}' |
socat - UNIX-CONNECT:"$XDG_RUNTIME_DIR/komorebi/komorebi.sock"
```
## When a subscriber goes away
A subscriber that the daemon cannot connect to, because its program has exited or its
socket was removed, is removed at the next notification, and its socket file with it. The
daemon does not try it again: a program that wants notifications again subscribes again.
The daemon keeps its subscribers only while it runs, so after a restart every program has
to subscribe again.
When the daemon stops, it connects to each subscriber and closes the connection without
writing anything.
A subscriber should accept and read every connection as it comes. The daemon writes each
notification while the window manager is locked, and waits when the socket's buffer is
full, so a subscriber that stops reading can hold up the window manager. While it is held
up, the window events KWin reports wait for it, and once 20 are waiting the daemon drops
the ones that come after them.
## In Rust
The `komorebi-client` crate has `subscribe` and `subscribe_with_options`, which listen on
the socket, subscribe, and return the listener: each connection on it is one
`Notification`. `cargo doc --package komorebi-client --open` shows their documentation,
with an example.
+68
View File
@@ -0,0 +1,68 @@
# Themes
A theme gives the borders their colors. Instead of choosing the color of each kind of window with
[`komorebic border-colour`](../cli/border-colour.md), a program tells the daemon to take a theme,
and the six kinds of border (`single`, `stack`, `monocle`, `floating`, `unfocused` and
`unfocused-locked`) take the colors the theme gives them: a Catppuccin theme, a Base16 theme, or a
Base16 palette of your own.
There is no `komorebic` command for it: the daemon takes it from the `theme` key of
[`komorebi.json`](configuration.md#borders), or as a message on its socket, the `Theme` message,
which a program sends with [`komorebi-client`](../../komorebi-client/src/lib.rs) or a script writes
as a line of JSON.
```rust
use komorebi_client::SocketMessage;
use komorebi_client::send_message;
let theme: SocketMessage = r#"{
"type": "Theme",
"content": { "palette": "Catppuccin", "name": "Mocha" }
}"#
.parse()?;
send_message(&theme)?;
```
The key has the same fields as the message, and wins over `border_colours` of the file, which has
no effect while a theme is set:
```json
{
"theme": { "palette": "Catppuccin", "name": "Mocha" }
}
```
The file sets the theme when the daemon starts and when the file changes. A file without `theme`
leaves the one the daemon has.
## What a theme gives
`palette` is the kind of theme (`Catppuccin`, `Base16` or `Custom`), and `name` the theme: one of
Catppuccin's four, `Latte`, `Frappe`, `Macchiato` and `Mocha`, or one of the Base16 schemes
(`Custom` has a `colours` of the sixteen Base16 colors instead). A kind of border that the message
does not name takes the theme's default for it:
| Border | Catppuccin | Base16 |
|---|---|---|
| `single_border` | Blue | Base0D |
| `stack_border` | Green | Base0B |
| `monocle_border` | Pink | Base0F |
| `floating_border` | Yellow | Base09 |
| `unfocused_border` | Base | Base01 |
| `unfocused_locked_border` | Red | Base08 |
The message can name another color of the theme for any of them, as `"single_border": "Mauve"`
for Catppuccin or `"single_border": "Base0E"` for Base16.
A theme sets the colors that `border-colour` sets, and replaces them, and the colors set after it
replace the theme's. The theme is kept as the current one. The border has to be on and drawn by
the effect for any of it to show ([Borders](borders.md)).
## Palettes from a picture
The Base16 palette of a picture can be made from the picture itself: the same palette generator as
komorebi for Windows takes the picture's colors and gives a light or a dark variant. A palette
takes seconds to make for a large picture, so each one is kept in `$XDG_CACHE_HOME/komorebi`
(`~/.cache/komorebi`), in a file named for the picture, a hash of its path, size and time of last
change, and the variant. It is made again when the path, the size or the time of change differ. A
picture with fewer than eight colors has no palette.
+63
View File
@@ -0,0 +1,63 @@
# Transparency
komorebi can make the windows that do not have the focus see-through, so that the one you are
working in stands out. It does not draw anything itself: the opacity of a window is a property
KWin has, which komorebi sets. Transparency is off by default.
## Turning it on
[`komorebic transparency`](../cli/transparency.md) turns transparency on or off,
[`komorebic toggle-transparency`](../cli/toggle-transparency.md) switches it, and
[`komorebic transparency-alpha`](../cli/transparency-alpha.md) sets how opaque a see-through window
is, from 0 (not there at all) to 255 (not see-through): 200 by default.
```sh
komorebic transparency enable
komorebic transparency-alpha 150
komorebic toggle-transparency
```
## In komorebi.json
The same settings are keys of [`komorebi.json`](configuration.md#transparency): `transparency`,
`transparency_alpha` and `transparency_ignore_rules`, a list of rules, as [Rules](rules.md)
explains them, for the windows that are never see-through.
```json
{
"transparency": true,
"transparency_alpha": 150,
"transparency_ignore_rules": [
{ "kind": "Exe", "id": "mpv", "matching_strategy": "Equals" }
]
}
```
The file sets them when the daemon starts and when the file changes. A file that leaves out
`transparency` or `transparency_alpha` has the defaults, off and 200, so a change made with a
command does not survive the file changing. The ignore rules add up, as the other rules do.
## Which windows are see-through
On the workspace each monitor shows, the window in front in every container is see-through unless
its container has the focus on the focused monitor. A window on a monitor that is not the focused
one is see-through, whatever its container. On a workspace with a monocle the monocled window is
the only one that counts: it is opaque on the focused monitor and see-through on another. A
workspace that does not tile has no see-through windows, and neither does a window that a rule
keeps out of it: the rules are the `transparency_ignore_rules` of
[`komorebi.json`](configuration.md#transparency), which no command sets.
Windows that are not in front, such as the other windows of a stack, are not on the screen and
are left as they are. With transparency off, every window is opaque.
## What is put back
When komorebi exits, every window it made see-through is opaque again. A window that closes needs
nothing.
## The border
The border effect draws a window from a texture that has the window's opacity in it. The build
of the effect that the flake installs draws a window again when its opacity changes, so the border
and the window change together. With the stock effect a change of opacity alone does not show
until the window changes.
+70
View File
@@ -0,0 +1,70 @@
# Wallpapers
A monitor, or a workspace of it, can have a wallpaper: the picture the monitor shows while that
workspace is in front. A workspace's own wallpaper is shown instead of its monitor's, and a
workspace that has none shows its monitor's. komorebi sets the wallpaper when a workspace comes
into view, however it comes: a [`komorebic`](../cli/focus-workspace.md) command, or a pager, a
shortcut, or an application raising a window of another workspace. It sets it when it starts too,
for the workspace that is in front. A monitor and a workspace with no wallpaper are left alone.
Plasma keeps one wallpaper for each screen, not for each virtual desktop, so komorebi changes the
screen's wallpaper as its workspace changes, as komorebi does on Windows and macOS.
## Setting wallpapers
The wallpapers are in `komorebi.json` ([Configuration](configuration.md)): a `wallpaper` in the
entry of a monitor and one in the entry of a workspace. The first entry of `monitors` is the first
monitor, and so on; the entries of `workspaces` are the workspaces of that monitor, in order. A
file that is read again, because it changed, shows the new wallpaper of the workspace in front at
once.
```json
{
"monitors": [
{
"wallpaper": { "path": "~/Pictures/dunes.png" },
"workspaces": [
{ "name": "code" },
{ "name": "chat",
"wallpaper": { "path": "~/Pictures/sea.png",
"theme_options": { "theme_variant": "Light", "single_border": "Base09" } } }
]
}
]
}
```
A `path` may start with `~` or have environment variables in it (`$HOME`), and may have spaces in
it. The picture fills the screen and is cropped where it does not fit. The monitor has the
`dunes.png` of the example, and the second workspace has `sea.png`.
A request for a wallpaper never holds up komorebi: switching workspaces does not wait for the
Plasma shell. The shell is asked what the screen shows before it is told anything, so a wallpaper
you changed by hand is put back when its workspace is shown again, and a wallpaper that is already
right is not touched.
## The colors of the borders
A wallpaper also gives the borders their colors, unless it says `"generate_theme": false`. The
palette of the picture, made by the generator komorebi for Windows uses, is a Base16 theme, so the
borders of a workspace with a warm picture are warm and those of a workspace with a cool picture
are cool ([Themes](themes.md) has what the six kinds of border take by default). They change with
the workspace, so the colors are right when the workspace comes into view.
`theme_options` choose the variant of the palette, `"theme_variant": "Dark"` (the default) or
`"Light"`, and which color of the palette each kind of border takes, `single_border`,
`stack_border`, `monocle_border`, `floating_border`, `unfocused_border` and
`unfocused_locked_border`, each one of `Base00` to `Base0F`. `bar_accent` is read and not used:
there is no komorebi bar here.
A palette takes seconds to make for a large picture, so each one is kept in
`$XDG_CACHE_HOME/komorebi` (`~/.cache/komorebi`), in a file named for the picture, a hash of its
path, size and time of last change, and the variant. A picture with fewer than eight colors has no
palette: its wallpaper is set, and the borders keep the colors they had.
## When the Plasma shell is not there
The shell is another process, and komorebi may start before it does. komorebi asks again for about
half a minute, with longer waits between the tries, and then says once, in its log, that it is
leaving wallpapers alone until the shell answers. A session with no Plasma shell has no wallpapers
to set, and nothing else in komorebi is affected.
+83
View File
@@ -0,0 +1,83 @@
# Workspace rules
A workspace rule sends the windows of an application to a workspace. It is a [rule](rules.md)
(`exe`, `class`, `title` or `path`) with a place: the index of a monitor and of a workspace, or
the name of a workspace. There are two kinds:
- an **initial** rule sends a window once, when komorebi first sees it: after that the window
stays wherever you put it;
- a **permanent** rule sends the windows of the application there every time, so that a window
you take away from that workspace goes back.
The windows are sent when a window opens or is focused, when the configuration is loaded, and when
you ask for it: komorebi looks at the rules at each event about a window it manages, before it
handles it. A window that
opens is in a workspace only after its own event has been handled, so it is sent by the next
event, which is the activation KWin reports a moment later.
Only the windows in view are looked at: the one on top of each container, and the floating
windows. A window that is on its workspace already is left alone. A workspace that does not
exist yet is made, with the ones before it. When the window is on the workspace in front, it
leaves it and is hidden (it is put on the parking desktop, as the back of a stack is), and the
workspace is tiled again without it; either way, it goes to the virtual desktop of its new
workspace, so it is out of view until that workspace is shown, which brings it back and tiles it.
A floating window that goes to another monitor is moved onto that monitor.
## In komorebi.json
A workspace has `workspace_rules` and `initial_workspace_rules`, each a list of
[rules](configuration.md#rules) like the ones in `ignore_rules`:
```json
{
"monitors": [
{
"workspaces": [
{ "name": "web", "layout": "BSP" },
{
"name": "code",
"layout": "BSP",
"initial_workspace_rules": [
{ "kind": "Exe", "id": "kate", "matching_strategy": "Equals" }
],
"workspace_rules": [
{ "kind": "Class", "id": "org.kde.konsole", "matching_strategy": "Equals" }
]
}
]
}
]
}
```
The rules are made again from the file each time it is read, so a rule taken out of the file is
gone, and so are the ones `komorebic` added. The windows that are open are sent where the file
says when it has been read.
## With komorebic
[`initial-workspace-rule`](../cli/initial-workspace-rule.md) and
[`workspace-rule`](../cli/workspace-rule.md) take what the rule names (`exe`, `class`, `title` or
`path`), its text, and the index of the monitor and of the workspace;
[`initial-named-workspace-rule`](../cli/initial-named-workspace-rule.md) and
[`named-workspace-rule`](../cli/named-workspace-rule.md) take the name of the workspace instead,
and add no rule when no workspace has the name. A rule given this way matches a title or a class
that starts or ends with what it names, and an executable or a path that is exactly what it names.
A rule that is there already is not added again.
```sh
komorebic initial-workspace-rule exe kate 0 1
komorebic workspace-rule class org.kde.konsole 0 1
komorebic named-workspace-rule exe thunderbird mail
```
[`enforce-workspace-rules`](../cli/enforce-workspace-rules.md) forgets which windows the initial
rules have sent and looks at the rules again, so that every window of an application goes to the
workspace its initial rule gives. The three clear commands take rules away:
[`clear-workspace-rules`](../cli/clear-workspace-rules.md) by monitor and workspace index,
[`clear-named-workspace-rules`](../cli/clear-named-workspace-rules.md) by name, and
[`clear-all-workspace-rules`](../cli/clear-all-workspace-rules.md) all of them. The first two
also take away the rules of every other workspace of the monitor they are given, and of every
other monitor's workspace with the same index, because of how they pick the rules to keep. Which
rules the daemon has is in the `workspace_rules` of
[`komorebic global-state`](../cli/global-state.md).
+119
View File
@@ -0,0 +1,119 @@
# Workspaces
Each monitor has workspaces, and shows one of them at a time. A workspace has its own windows
and its own layout. komorebi's workspaces are KWin's virtual desktops: workspace 0 is the first
desktop, workspace 1 the second, and so on, which is why the pager, the overview and KWin's
shortcuts show and switch them too.
komorebi turns on KWin's per-output virtual desktops when it starts, so that each monitor shows
a desktop of its own: switching the workspace of one monitor leaves the others as they are. It
puts the setting back as it was when it stops.
## Showing another workspace
[`komorebic focus-workspace`](../cli/focus-workspace.md) shows a workspace of the focused
monitor, by its number, counted from 0. KWin shows the windows of that workspace and hides the
others, and the window of that workspace that had the focus has it again.
```sh
komorebic focus-workspace 1
komorebic focus-workspace 0
```
A workspace that does not exist yet is created, with the ones before it, and KWin gets a
desktop for each, named "Workspace 2" and so on. A desktop that is there already keeps its
name. The desktops komorebi creates stay when it stops.
## Moving a window to another workspace
[`komorebic move-to-workspace`](../cli/move-to-workspace.md) takes the focused window to another
workspace, puts it after the windows there, and shows that workspace.
[`komorebic send-to-workspace`](../cli/send-to-workspace.md) does the same and stays on the
workspace in front, which is tiled again without the window.
```sh
komorebic move-to-workspace 1
komorebic send-to-workspace 2
```
## Going round the workspaces
[`komorebic cycle-workspace`](../cli/cycle-workspace.md) shows the next or the previous workspace
of the focused monitor, and wraps around at both ends;
[`komorebic cycle-empty-workspace`](../cli/cycle-empty-workspace.md) shows the next or the previous
one that has no window, if there is one.
[`komorebic cycle-move-to-workspace`](../cli/cycle-move-to-workspace.md) and
[`komorebic cycle-send-to-workspace`](../cli/cycle-send-to-workspace.md) take the focused window to
the next or the previous workspace, with and without showing it.
```sh
komorebic cycle-workspace next
komorebic cycle-empty-workspace previous
komorebic cycle-move-to-workspace next
```
## The last workspace
Each monitor remembers which workspace was in front before the one in front now.
[`komorebic focus-last-workspace`](../cli/focus-last-workspace.md) shows it again, so two in a row
go back and forth between the two.
[`komorebic move-to-last-workspace`](../cli/move-to-last-workspace.md) and
[`komorebic send-to-last-workspace`](../cli/send-to-last-workspace.md) take the focused window
there, with and without showing it.
## Names
[`komorebic workspace-name`](../cli/workspace-name.md) names a workspace, given by the index of its
monitor and its own index, and
[`komorebic ensure-named-workspaces`](../cli/ensure-named-workspaces.md) gives a monitor a workspace
for each name it is given, in order. The name is komorebi's, for the commands that find a
workspace by its name: KWin's desktop keeps the name it has.
[`komorebic focus-named-workspace`](../cli/focus-named-workspace.md) shows the workspace with that
name, on the monitor that has it, and focuses that monitor. A name no workspace has changes
nothing. `komorebic query focused-workspace-name` prints the name of the workspace in front, or its
index when it has none.
```sh
komorebic ensure-named-workspaces 0 web code mail
komorebic focus-named-workspace mail
```
## Adding and removing workspaces
[`komorebic new-workspace`](../cli/new-workspace.md) adds a workspace after the last one of the
focused monitor and shows it, and [`komorebic ensure-workspaces`](../cli/ensure-workspaces.md)
gives a monitor at least as many workspaces as it is told.
[`komorebic close-workspace`](../cli/close-workspace.md) removes the workspace in front and shows
the one before it, when the workspace has no window and no name and is not the monitor's last.
[`komorebic focus-workspaces`](../cli/focus-workspaces.md) shows the workspace with the same index
on every monitor.
## The layout of another workspace
[`komorebic workspace-layout`](../cli/workspace-layout.md) and
[`komorebic workspace-tiling`](../cli/workspace-tiling.md) set the layout of a workspace, and turn
its tiling off or on, by the index of its monitor and its own index;
[`komorebic named-workspace-layout`](../cli/named-workspace-layout.md) and
[`komorebic named-workspace-tiling`](../cli/named-workspace-tiling.md) find it by its name. The
focused workspace is tiled again at once, and another workspace the next time it is tiled, when it
is shown at the latest.
```sh
komorebic workspace-layout 0 1 columns
komorebic named-workspace-tiling mail disable
```
## Switching with KWin
Anything that switches KWin's desktop switches komorebi's workspace: the pager, KWin's own
shortcuts, the overview, or an application that raises a window of another desktop (KWin then
shows that desktop and focuses the window). komorebi follows, tiles the workspace that came
into view, and asks KWin for nothing in reply. A window moved to another desktop with the
window menu's "Move to Desktop" moves to that workspace.
## The windows that were open before
When komorebi starts, each window that is open goes to the workspace whose desktop it is on,
and each monitor starts on the workspace KWin shows there. A window that is on every desktop
goes to the workspace in front.