feat(kwin): workspaces are KWin's own desktops

komorebi's workspaces exist on Windows and macOS because neither has a virtual
desktop API: switching hides every window of the workspace being left. KWin has
virtual desktops, per output since 6.8, so here workspace i is KWin's desktop i
on every monitor, and each monitor shows one. KWin shows, hides and focuses the
windows of a desktop; komorebi asks for a switch, puts a window on a desktop,
and follows what anything else does.

The Backend gets the workspace methods (ensure_workspaces, switch_workspace,
set_window_workspace, window_workspace, current_workspaces), and the fake its
desktops. The bridge reports the desktops, the desktop each output shows and a
window's desktops, and carries out output_desktop and desktop commands, typed
and tested with the fixtures like the rest. The table turns a switch or a move
komorebi did not make into a WorkspaceChange or a WorkspaceMove, and records its
own when it sends them, so that KWin's report of those raises nothing. The
window manager follows a switch with no command in reply
(adopt_workspace_change), puts windows on their desktops before a desktop is
shown (focusing a window first would take the monitor back), and loads the
windows open at startup onto the workspace of their desktop.

Per-output desktops are a kwinrc setting that is off by default, and
kwriteconfig6 was not on the PATH of the user service in a live session, so
komorebi edits kwinrc itself (kwin::kwinrc) and puts the user's value back when
it stops, also after a crash.

focus-workspace, move-to-workspace and send-to-workspace come with this commit,
since the tests of switching and moving, and vm-workspace-switch, need them; the
named and cycling workspace commands follow. vm-workspace-switch runs the daemon
against a real KWin; vm-kwin-contract checks what komorebi relies on from KWin's
per-output desktops, on a headless KWin with two outputs and no komorebi.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:37 -07:00
1 parent 1b10611022
commit 62e37e44cf
38 files changed
+3522 -77

No files matched your search

+96 -14
View File
@@ -7,10 +7,10 @@ tested, without one.
This page describes that trait, who implements and calls it, where each of its rules is
enforced, the model of the desktop the window manager tiles, the backend that reaches KWin,
how an event about a window becomes a tile, how a message on the daemon's socket is
answered, how subscribers are notified of both, what the orders a message gives do, and how the
NixOS module runs the daemon. It grows with the code: each part of the daemon that is added has
its place here.
how an event about a window becomes a tile, how workspaces are the compositor's desktops, how
a message on the daemon's socket is answered, how subscribers are notified of both, what the
orders a message gives do, and how the NixOS module runs the daemon. It grows with the code:
each part of the daemon that is added has its place here.
## Vocabulary
@@ -19,16 +19,22 @@ its place here.
- **Monitor**: a connected output, with its bounds and its work area (its bounds minus
the panels).
- **Workspace**: the containers a monitor shows, in order, and the layout that tiles
them. A monitor has a ring of workspaces and shows one of them.
them. A monitor has a ring of workspaces and shows one of them. Workspace `i` is the
compositor's desktop `i` on that monitor.
- **Desktop**: one of KWin's virtual desktops. KWin shows the windows of one desktop on each
output and hides the others; with its per-output virtual desktops on, each output shows a
desktop of its own.
- **Container**: what a layout places. It gets one tile, and every window in it is put on
that tile.
- **Layout**: the arrangement (BSP, columns, rows, ...) that turns a work area and a
number of containers into one rectangle, a **tile**, for each container.
- **Event**: what the compositor reports about a window: it was shown, destroyed, given
the focus, minimized or restored ([`WindowManagerEvent`]). Two events come from komorebi
itself: a command asks it to manage the focused window, or to stop managing it.
the focus, minimized or restored, or put on another workspace's desktop; and that a monitor
shows another workspace ([`WindowManagerEvent`]). Two events come from komorebi itself: a
command asks it to manage the focused window, or to stop managing it.
- **Message**: what a client sends the daemon on its socket, a [`SocketMessage`]: an order
(focus a window, move it, change the layout, resize it, retile, stop) or a question (the state, the monitors, one [`StateQuery`]).
(focus a window, move it, change the layout, resize it, show a workspace, retile, stop) or a
question (the state, the monitors, one [`StateQuery`]).
- **Rule**: a condition on a window's title, executable, class or path ([`MatchingRule`]), in
one of the process-wide lists that decide whether a window is managed (the ignore and the
manage rules) and whether it floats when it opens (the float rules).
@@ -81,7 +87,9 @@ The desktop, as the window manager sees it, is two lists and a pointer:
of the window that has it.
A command is one of: move and resize a window, focus it, raise it, minimize it or bring it
back, close it, and put the pointer in the middle of a rectangle.
back, close it, put the pointer in the middle of a rectangle, make desktops for the
workspaces, show a workspace on a monitor, and put a window on a workspace. The workspace a
window is on, and the one each monitor shows, are queries.
The window manager tiles a tree of four levels, each level a [`Ring`]: a list with one
element focused, so that "the focused workspace" or "the focused container" means
@@ -111,9 +119,10 @@ tile is clamped to the work area, so it cannot reach onto a neighboring monitor.
The [`WindowManager`] keeps the monitors, the windows the user minimized (they are in no
workspace until they are restored), and an index from each window it manages to the
monitor and workspace that have it. It is loaded from the backend at startup: every
monitor, and every open window that is normal, alive, not minimized and not ignored by a
rule, on the focused workspace of the monitor its middle is on. After that it changes only
when an event comes in, and each event ends with the workspace in front tiled again.
monitor, focused on the workspace the compositor shows on it, and every open window that is
normal, alive, not minimized and not ignored by a rule, on the workspace whose desktop it is
on, of the monitor its middle is on. After that it changes only when an event comes in, and
each event ends with the workspace in front tiled again.
## The KWin backend
@@ -179,6 +188,41 @@ and returns once the snapshot has arrived, so that the window manager reads a fu
it starts. [PLATFORM.md](PLATFORM.md) has the D-Bus names, the files and the environment
variables; [DESIGN.md](DESIGN.md#why-does-komorebi-run-a-script-inside-kwin) has the reasons.
## Workspaces
komorebi's workspaces are the compositor's virtual desktops: workspace `i` is desktop `i` on
every monitor, and each monitor shows one at a time. The compositor shows the windows of the
desktop in front, hides the others, and keeps which window of each desktop had the focus; the
window manager hides no window to leave a workspace. The reasons are in
[DESIGN.md](DESIGN.md#why-are-komorebis-workspaces-kwins-virtual-desktops).
Showing a workspace ([`Monitor::load_focused_workspace`]) is three steps. Every window of every
workspace of the monitor is put on the desktop of its workspace, unless it is already there.
The compositor is asked to show the workspace on the monitor ([`Backend::switch_workspace`]),
which leaves the other monitors as they are. The workspace's focused window is given the focus.
The order matters: a window that is focused while it is on another desktop takes the monitor
back to that desktop.
Desktops are global in KWin: every monitor has as many as the monitor with the most
workspaces, and each has one name. At startup, and when a workspace is asked for that has no
desktop, the backend creates the missing ones over KWin's `org.kde.KWin.VirtualDesktopManager`
interface, named "Workspace 1", "Workspace 2" and so on ([`WindowManager::sync_workspace_desktops`]).
Without KWin's per-output virtual desktops every output would show the same desktop, so
[`connect`] turns them on in the user's `kwinrc`, and [`Kwinrc`] keeps the user's value and
puts it back when komorebi stops, also after a crash.
Something else can switch a monitor to another desktop: a pager, a KWin shortcut, an
application that raises a window of another desktop, which KWin answers by showing that
desktop. KWin has one signal for it, which does not say which output, so the bridge sends the
desktop of every output after it, and once a second. The table compares it with what it had,
and a monitor that shows another desktop is a `WorkspaceChange` event: the window manager
focuses that workspace and tiles it ([`WindowManager::adopt_workspace_change`]), and asks the
compositor for nothing, since KWin has already shown the windows and chosen which to focus. A
window put on another desktop by something else (the window menu's "Move to Desktop") is a
`WorkspaceMove`: the window manager moves the window to that workspace. komorebi's own switch
and move come back from KWin as the same reports; the table records them when the command is
sent ([`Table::switch_commands`], [`Table::window_workspace_commands`]), so they raise nothing.
## The command socket
The daemon takes messages on a Unix socket, `komorebi.sock` in [`DATA_DIR`]
@@ -370,6 +414,13 @@ would be smaller than a tenth of the work area, or than it is already. The adjus
until a `Retile`, which drops them; `RetileWithResizeDimensions` tiles with them, and `Save`,
`Load`, `QuickSave` and `QuickLoad` write them to a file as JSON and read them back.
`FocusWorkspaceNumber` shows another workspace of the focused monitor
([`WindowManager::focus_workspace`]). `MoveContainerToWorkspaceNumber` takes the focused
container (or the focused window, when it is a floating one) to the back of another workspace
of the monitor and shows that workspace, and `SendContainerToWorkspaceNumber` does the same
and leaves the workspace in front showing ([`WindowManager::move_container_to_workspace`]). A
workspace that does not exist yet is created, with the ones before it, and gets a desktop.
`PreselectDirection` reserves the index on one side of the focused container for the next
window ([`WindowManager::preselect_container_in_direction`]). The workspace inserts an empty
container there ([`Container::preselect`]), which [`Workspace::update`] keeps and the layout
@@ -429,7 +480,8 @@ module's unit.
operations on it (tile the workspace in front, tile every monitor, take a minimized
window out, move the focus, move the focused container, change the layout, resize or
promote the focused container, float a window, lock a container, set the padding of a
workspace, manage and unmanage a window).
workspace, manage and unmanage a window, show a workspace, move a container to another
workspace, follow a workspace switch made by something else).
- [`desktop`](../../komorebi/src/desktop.rs): loads the monitors and the open windows from
the backend.
- [`window_manager_event`](../../komorebi/src/window_manager_event.rs) and
@@ -439,7 +491,9 @@ module's unit.
channel that carries events from the backend to the window manager, and
[`listen_for_events`], the thread that takes them off it.
- [`kwin`](../../komorebi/src/kwin/mod.rs): the KWin backend, its D-Bus service and the held
call; [`kwin::state`](../../komorebi/src/kwin/state.rs), the table; and
call; [`kwin::state`](../../komorebi/src/kwin/state.rs), the table;
[`kwin::kwinrc`](../../komorebi/src/kwin/kwinrc.rs), the editor of the user's `kwinrc`, which
keeps the values it changes and puts them back; and
[`bridge.js`](../../komorebi/src/kwin/bridge.js), the bridge.
- [`process_command`](../../komorebi/src/process_command.rs): the thread that listens on the
socket, and what the window manager does with each message.
@@ -480,6 +534,11 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
- A command about a window that does not exist, or is no longer alive, is an error. It
never panics. The KWin backend knows a closed window for a minute after it closed, and
sends its commands to the bridge, which reports that it could not carry them out.
- Workspace `i` is the compositor's desktop `i`, and each monitor shows one
(`switch_workspace`, `set_window_workspace`, `window_workspace`, `current_workspaces`). A
backend asked for a workspace that has no desktop makes the desktops up to it
(`ensure_workspaces`). The compositor shows and hides the windows of the desktops, and a
backend reports a switch or a move it did not make as an event.
- `shutdown`, `is_window`, `window_rect` and `monitor_from_point` have defaults, written in
terms of the queries. An implementor should not need to override them, except `shutdown`
when it created something in the compositor that has to be given up.
@@ -518,6 +577,12 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
| A resize leaves no tile smaller than a tenth of the work area, or than it was | framework path: [`WindowManager::resize_window`] calculates the tiles for the adjustment, and cuts the adjustment down until they all fit | `a_resize_leaves_every_tile_about_a_tenth_of_the_work_area_wide_at_least` | the paddings are taken off afterwards, so a tile can end up a little smaller |
| The offset of a workspace wins over its monitor's, which wins over the window manager's | framework path: [`Monitor::update_workspace_globals`] gives the workspace the monitor's offset or else the window manager's, and [`Workspace::update`] takes its own before that | `the_workspaces_offset_wins_over_the_monitors_which_wins_over_the_global_one` | none |
| A workspace whose tiling is off moves no window | framework path: [`Workspace::update`] returns before the layout when [`Workspace::tile`] is false | `with_tiling_off_no_window_is_moved_until_it_is_back_on` | none |
| komorebi hides no window to leave a workspace | framework path: showing a workspace is one request to the compositor ([`Backend::switch_workspace`]), which shows and hides the windows of its desktops | `switching_workspace_asks_the_compositor_to_show_the_other_desktop`, `vm-workspace-switch` ("KWin shows the desktop, komorebi hides nothing") | none |
| Showing a workspace on one monitor leaves the other monitors as they are | KWin's per-output virtual desktops, which [`connect`] turns on | `showing_a_workspace_switches_that_output_only`, `vm-kwin-contract` ("the other keeps its own") | a `kwinrc` komorebi cannot write: every monitor switches |
| A window is on its new workspace's desktop before the desktop is shown or the window focused | framework path: [`Monitor::load_focused_workspace`] puts every window on its desktop first | `moving_a_window_to_another_workspace_puts_it_on_the_desktop_before_showing_it` | none |
| A workspace switch or a window move made by something else is followed, and answered with no command | framework path: the table reports what it did not send as a `WorkspaceChange` or a `WorkspaceMove`, and [`WindowManager::adopt_workspace_change`] asks the compositor for nothing | `a_workspace_switch_by_someone_else_is_followed_not_undone`, `a_window_moved_to_another_desktop_by_someone_else_changes_workspace`, `another_party_switching_a_monitor_is_a_workspace_change`, `vm-workspace-switch` ("nothing is flip-flopping") | none |
| komorebi's own switch or move, reported back by KWin, changes nothing | framework path: the table records a switch and a move when it makes their commands | `the_compositor_reporting_komorebis_own_switch_changes_nothing`, `komorebis_own_move_coming_back_as_an_event_moves_nothing`, `komorebi_switching_a_monitor_comes_back_as_a_change_to_what_it_already_knows` | none |
| The user's `kwinrc` gets back the value komorebi changed, also after a crash | framework path: [`Kwinrc`] records the first value of a key in a backup file, and the backend's `shutdown` puts it back | `what_komorebi_changed_is_put_back_exactly_and_what_it_added_is_removed`, `a_backup_left_by_a_crash_keeps_the_values_from_before_the_first_run`, `vm-workspace-switch` ("back as they were") | `SIGKILL`: the next run puts it back when it stops |
| Moving the focus moves no window | test | `focus_gives_the_focus_to_the_window_on_that_side_and_moves_nothing`, `vm-core-e2e` ("moving the focus moved no window") | none |
| A subscriber that is gone is dropped, not retried | test | `a_subscriber_that_is_gone_is_dropped_and_not_tried_again` | none |
| The bridge holds no window manager logic | convention, with every decision about an event in the table, which the `kwin::state` unit tests pin | the unit tests in `komorebi/src/kwin/state.rs` | none |
@@ -648,6 +713,14 @@ A window is shown, and ends up on a tile:
strip in a real KWin, with its columns out of view off the screen.
- [`nix/tests/vm/suites/commands`](../../nix/tests/vm/suites/commands/test.py): every layout,
and every `komorebic` command, against a real KWin with two outputs.
- [`komorebi/tests/workspaces.rs`](../../komorebi/tests/workspaces.rs): workspaces as the
fake's desktops; [`komorebi/src/kwin/kwinrc.rs`](../../komorebi/src/kwin/kwinrc.rs), the
`kwinrc` editor and its tests.
- [`nix/tests/vm/suites/workspace-switch`](../../nix/tests/vm/suites/workspace-switch/test.py):
workspaces as a real KWin's desktops, switched by `komorebic` and by KWin;
[`nix/tests/vm/suites/kwin-contract`](../../nix/tests/vm/suites/kwin-contract/test.py), the
behavior of KWin's per-output virtual desktops komorebi relies on, with two outputs and no
komorebi.
- [`nix/nixos-module.nix`](../../nix/nixos-module.nix): the NixOS module;
[`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix), its scenarios, evaluated in
real NixOS systems; and [`nix/tests/vm/suites/module`](../../nix/tests/vm/suites/module/test.py),
@@ -727,6 +800,15 @@ A window is shown, and ends up on a tile:
[`Table`]: ../../komorebi/src/kwin/state.rs
[`Table::handle`]: ../../komorebi/src/kwin/state.rs
[`Table::compositor_lost`]: ../../komorebi/src/kwin/state.rs
[`Table::switch_commands`]: ../../komorebi/src/kwin/state.rs
[`Table::window_workspace_commands`]: ../../komorebi/src/kwin/state.rs
[`Kwinrc`]: ../../komorebi/src/kwin/kwinrc.rs
[`Backend::switch_workspace`]: ../../komorebi/src/backend/mod.rs
[`Monitor::load_focused_workspace`]: ../../komorebi/src/monitor.rs
[`WindowManager::sync_workspace_desktops`]: ../../komorebi/src/window_manager.rs
[`WindowManager::adopt_workspace_change`]: ../../komorebi/src/window_manager.rs
[`WindowManager::focus_workspace`]: ../../komorebi/src/window_manager.rs
[`WindowManager::move_container_to_workspace`]: ../../komorebi/src/window_manager.rs
[`bridge.js`]: ../../komorebi/src/kwin/bridge.js
[`kwin-api.d.ts`]: ../../komorebi/src/kwin/kwin-api.d.ts
[`bridge.test.js`]: ../../komorebi/src/kwin/bridge.test.js
+36
View File
@@ -223,3 +223,39 @@ to put a window for a second, and sets the position again when the window's fram
another one in that time ([PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame)). Three tries
at most keep it from chasing a window that cannot go where it was asked, such as a fullscreen
one.
## Why are komorebi's workspaces KWin's virtual desktops?
Because KWin has virtual desktops, per output since KWin 6.8, and Windows and macOS have no API
for them. komorebi's own workspaces exist there for that reason: switching workspace hides
every window of the workspace being left and restores the windows of the one being entered. On
KDE that is what KWin does with its desktops, and native behavior is preferred over a
workaround (see [What is komorebi for KDE the port of?](#what-is-komorebi-for-kde-the-port-of)):
workspace `i` is desktop `i` on every monitor, and each monitor shows one at a time.
The spikes measured what KWin does with per-output desktops on a headless KWin with two
outputs: showing a desktop on one output left the other output's alone; KWin gave the focus to
a window of the desktop it switched to, by itself; and activating a window on another desktop
of its output (an application raising itself) made KWin switch that output to the window's
desktop and focus the window, by itself. So komorebi asks for a switch and follows the ones it
did not ask for, with no command in reply. A first attempt in which komorebi hid the windows
itself switched between two workspaces about 280 times a second after an application raised a
window of another workspace: KWin delivered focus events it had generated before it carried
out komorebi's commands, and komorebi took each for a new request. With KWin's desktops there
is nothing to debounce, since komorebi answers a switch with nothing.
The costs: desktops are global, so every monitor has as many as the monitor with the most
workspaces, with one name each, and they show in the pager and the overview. A window komorebi
does not manage (a dialog, say) belongs to the desktop it opened on and goes out of view with
it. The desktops komorebi created stay when it stops: by then they are the user's desktops.
## Why does komorebi edit `kwinrc` itself?
Because per-output virtual desktops are off by default, they are a setting in the user's
`kwinrc`, and the program that would set it cannot be counted on. KDE's `kwriteconfig6` was not
on the PATH of komorebi's user service in the first live run in a Plasma session, and
per-output desktops stayed off; `kreadconfig6` is not always installed either. The file is
plain ini, which komorebi changes line by line, and asks KWin to reload its configuration.
It is the user's setting, so the value komorebi found is kept in a backup file and put back
when komorebi stops; a backup a crash left behind keeps the value from before the first run,
and the next run puts it back.
+70 -11
View File
@@ -19,6 +19,8 @@ was measured with KWin 6.8.1, Plasma 6.8.1 and Qt 6.12.0 from nixpkgs `d3b13ad`
- **Script**: a JavaScript program that KWin runs inside itself, through its scripting API.
komorebi's is the **bridge**, [`bridge.js`](../../komorebi/src/kwin/bridge.js).
- **Output**: KWin's name for a monitor.
- **Desktop**: one of KWin's virtual desktops. Each output shows one; komorebi's workspace `i`
is desktop `i`.
- **Headless KWin**: `kwin_wayland --virtual`, a KWin with virtual outputs and no display,
which the VM tests run ([vm-tests.md](vm-tests.md)).
@@ -26,10 +28,35 @@ was measured with KWin 6.8.1, Plasma 6.8.1 and Qt 6.12.0 from nixpkgs `d3b13ad`
### KWin 6.8 or newer
KWin 6.8 is the oldest KWin komorebi supports. The bridge reads the work area of each output
for the virtual desktop that output shows (`workspace.currentDesktopForScreen`), which is part
of the per-output virtual desktops KWin 6.8 introduced. At time of writing (2026-10-27) KWin
6.8.1 is the only version komorebi has been run against; 6.7 and older have not been tried.
KWin 6.8 is the oldest KWin komorebi supports. komorebi's workspaces are KWin's virtual
desktops, one shown on each output, which needs the per-output virtual desktops KWin 6.8
introduced (`workspace.currentDesktopForScreen`, `workspace.setCurrentDesktopForScreen`, and
the setting `[Windows] PerOutputVirtualDesktops` in `kwinrc`). At time of writing (2026-10-27)
KWin 6.8.1 is the only version komorebi has been run against; 6.7 and older have not been
tried.
### Per-output virtual desktops
What komorebi relies on KWin to do with them, on KWin 6.8.1 at time of writing (2026-10-27),
measured in the spikes and checked by the VM test `vm-kwin-contract` on a headless KWin with two
outputs:
- With `PerOutputVirtualDesktops=true` in the `[Windows]` group of `kwinrc`, a script that
shows a desktop on one output (`workspace.setCurrentDesktopForScreen`) leaves the other
output's desktop as it was. komorebi turns the setting on when it starts, has KWin reload its
configuration (`org.kde.KWin.reconfigure`), and puts the user's value back when it stops.
- KWin raises `workspace.currentDesktopChanged` when an output shows another desktop. The signal
does not say which output, so the bridge reads the desktop of every output after it.
- KWin gives the focus to a window of the desktop it switched an output to, by itself.
- Activating a window that is on another desktop of its output switches that output to the
window's desktop and gives the window the focus.
- A window that a script moves so that its middle is on another output keeps its desktops;
`window.output` follows the middle. KWin puts a window on the new output's desktop only during
an interactive move.
- Putting a window on another desktop from outside the script raises the window's
`desktopsChanged`.
- Desktops are global: every output has the same desktops, with the same names, and each output
shows one of them. The ids of the desktops are UUIDs; the bridge names them by id.
### Wayland
@@ -74,9 +101,16 @@ the windows and outputs it finds, and from then on every window that opens, clos
focus, is minimized or brought back, moves or changes size. The daemon waits up to 10 seconds
for the first report and does not start without it.
Before it loads the script, it turns on KWin's per-output virtual desktops in the user's
`kwinrc` (`[Windows] PerOutputVirtualDesktops=true`), unless they are on, and asks KWin to
reload its configuration. If a workspace has no desktop, it creates the missing desktops over
`org.kde.KWin.VirtualDesktopManager`, named "Workspace 1", "Workspace 2" and so on. A desktop
that is already there keeps its name.
Every command of the window manager (move and resize, focus, raise, minimize, bring back or
close a window) is queued for the bridge, which gets the queue as the answer to its held call
and carries the commands out in KWin, in order. The script API cannot move the pointer, so
close a window, show a workspace on an output, put a window on a workspace) is queued for the
bridge, which gets the queue as the answer to its held call and carries the commands out in
KWin, in order. The script API cannot move the pointer, so
when the pointer follows the focus komorebi invokes KWin's own "Move Mouse to Focus" shortcut,
which puts the pointer in the middle of the window KWin has focused.
@@ -94,11 +128,15 @@ an owner again; the VM test `vm-kwin-restart` restarts KWin twice under a runnin
#### What komorebi leaves behind
When it is stopped with `SIGINT`, `SIGTERM` or a `Stop` message on its socket, it asks KWin
to unload the script, closes an empty connection to each subscriber, and removes the socket.
The file `bridge.js` stays in the runtime directory, which is removed at logout. A daemon
that is killed leaves the script running in KWin, reporting to nobody, and the socket file in
the runtime directory, until the next start replaces both or the session ends.
When it is stopped with `SIGINT`, `SIGTERM` or a `Stop` message on its socket, it puts back
the value `PerOutputVirtualDesktops` had in `kwinrc` (or removes the key, when the user had
none) and asks KWin to reload its configuration, asks KWin to unload the script, closes an
empty connection to each subscriber, and removes the socket. The desktops it created stay:
they are the user's desktops from then on. The file `bridge.js` stays in the runtime
directory, which is removed at logout. A daemon that is killed leaves the script running in
KWin, reporting to nobody, the socket file in the runtime directory, and per-output desktops
on, until the next start replaces the script and the socket, and its stop puts the setting
back (the backup in the runtime directory keeps the user's value), or the session ends.
### A headless KWin
@@ -143,11 +181,19 @@ What komorebi calls:
| `org.kde.KWin` | `/Scripting/Script<id>` | `org.kde.kwin.Script` | `run()` | after `loadScript` |
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `AddMatch(s)`, for the signal `NameOwnerChanged` | at start, to see KWin leave the bus and come back |
| `org.kde.kglobalaccel` | `/component/kwin` | `org.kde.kglobalaccel.Component` | `invokeShortcut(s)`, with `MoveMouseToFocus` | when the pointer follows the focus |
| `org.kde.KWin` | `/KWin` | `org.kde.KWin` | `reconfigure()` | after komorebi changed `kwinrc`, at start and at exit |
| `org.kde.KWin` | `/VirtualDesktopManager` | `org.kde.KWin.VirtualDesktopManager` | the property `desktops`, `createDesktop(us)`, `setDesktopName(ss)` | when a workspace has no desktop, and at start |
The property `desktops` is introspected as `a(iss)`, a position, an id and a name for each
desktop, and the value on the wire is `a(uss)`: komorebi reads it as that. It is read uncached,
since a read right after `createDesktop` has to see the new desktop.
## Files and directories
| Path | What | Lifetime |
|---|---|---|
| `$XDG_CONFIG_HOME/kwinrc` (`~/.config/kwinrc`) | KWin's configuration: komorebi sets `PerOutputVirtualDesktops=true` in `[Windows]`, changing that line or adding it and nothing else, and writes the file beside it first and renames it over it | put back as it was when the daemon stops |
| `$XDG_RUNTIME_DIR/komorebi/kwinrc-backup.json` | the value each key of `kwinrc` had before komorebi first changed it | removed when the values are put back; one a crash left behind is used by the next run |
| `$XDG_RUNTIME_DIR/komorebi/bridge.js` | the script KWin loads, with its configuration (the D-Bus names and the hold time of `Poll`) on its first line | written at every start; the directory is removed at logout |
| `$XDG_RUNTIME_DIR/komorebi/komorebi.sock` | the command socket | bound once the daemon is connected to KWin, after a file left there is removed; removed when the daemon stops |
| `$XDG_RUNTIME_DIR/komorebi/NAME` | the socket of a subscriber, which the subscriber binds and names in its subscription | removed by the daemon, with the subscriber, when it cannot connect to it |
@@ -170,6 +216,19 @@ either. An address with no bus behind it is the first error under [No KWin](#no-
The runtime directory of the user, normally `/run/user/<uid>`: komorebi writes the bridge to
the `komorebi` directory in it, and binds its command socket there.
### `XDG_CONFIG_HOME`
Where the user's `kwinrc` is: `$XDG_CONFIG_HOME/kwinrc`, or `~/.config/kwinrc` when it is not
set. Without either, komorebi leaves per-output virtual desktops as they are and logs that it
found no configuration directory.
### `XDG_CONFIG_DIRS`
Where KConfig looks for the system's `kwinrc` when the user's has no value: komorebi reads
`PerOutputVirtualDesktops` the same way, from the user's file and then from the first of these
directories that has it (`/etc/xdg` when the variable is not set), and changes nothing when the
setting is on already.
### `XDG_DATA_HOME`
The logs are written to `$XDG_DATA_HOME/komorebi` (`~/.local/share/komorebi` if
+8
View File
@@ -134,6 +134,14 @@ the run.
in order, `daemon.window_ids(log)` maps a window's title to the daemon's id
for it, and `daemon.requests(log)` returns the frame the daemon last asked KWin
for, for each window.
- `desk(wid)` is the number of the desktop a window is on and `shown()` the one
KWin shows, both counted from 1 as `kdotool` counts, `desktops()` how many
desktops KWin has, and `kwinrc(group, key)` a value of the user's `kwinrc`.
- `kwin_script(name, source, keep=)` runs a KWin script and returns the lines it
reported: the script calls `report(...)`, which `print`s a line marked with
`name` to KWin's log, and ends with `report("done")`. A script that is kept
goes on reporting what its signal handlers see, and `kwin_reports(name)`
reads every line it has reported so far from the journal.
- `monitor_bridge(path)` records the bridge's traffic on the session bus with
`dbus-monitor`, and `latency.rounds` times each batch of commands in it, from
the daemon's answer to the last frame KWin reports for the windows it moved.