mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-21 16:11:37 +01:00
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:
1 parent
1b10611022
commit
62e37e44cf
38 files changed
+3522
-77
No files matched your search
+96
-14
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user