mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-18 14:48:34 +01:00
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:
1 parent
348cb7ae96
commit
d781028a2a
390 files changed
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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`.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user