mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-20 07:31:39 +01:00
feat(kwin): borders drawn by the compositor
komorebi draws no border. KWin's KDE Rounded Corners effect does, outside each window in the gap the layout leaves, and komorebi says how it looks. The window manager describes a Look (a border with a width, a radius and two colors) and asks the backend for it with Backend::apply_look after every event, message and retile. The backend answers whether borders are being drawn, and the layout leaves room around the windows only while they are: a border with no effect to draw it takes none. The KWin backend writes the effect's settings into the user's kwinrc, with every inner outline off (the effect's default draws one over the title bar), loads the effect when borders are on and has it read them again. It unloads the effect and puts the user's settings back when the borders go or komorebi exits. The module installs the effect (effects.borders), which is built to stay unloaded until komorebi asks, and vm-look reads the pixels around two windows in a real session. The session library of the VM tests also waits for the panel of the Plasma shell now: a window komorebi tiles before the panel is made is tiled under it, which hides the bottom of its border from a screenshot. Kde.wait_for_panel_room waits until the daemon's work area is not the whole of its monitor, which is the daemon having learned that the panel takes room, and vm-look calls it where the daemon starts, before the windows open. The shell makes its panel and KWin takes room for it a while later, which the daemon learns of up to a second after, so a daemon that tiles in between puts the windows under the panel and tiles them again, and a screenshot taken between the two shows frames as high as the screen. It is a wait and not a check, since a session that is too slow, as TCG often is, may never take the room. komorebic gets border, border-width and border-offset, and visible-windows. komorebi.json takes the same settings as border, border_width and border_offset, and border_radius, which has no command. The module warns when config asks for borders and the effect is not installed.
This commit is contained in:
1 parent
efcc90d279
commit
2c35e4bb6f
53 files changed
+2546
-64
No files matched your search
+88
-15
@@ -9,9 +9,9 @@ This page describes that trait, who implements and calls it, where each of its r
|
||||
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 workspaces are the compositor's desktops, how
|
||||
a stack hides its windows, how a message on the daemon's socket is answered, how subscribers
|
||||
are notified of both, what the orders a message gives do, how `komorebi.json` configures the
|
||||
daemon, 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.
|
||||
are notified of both, what the orders a message gives do, how the compositor is asked to draw the
|
||||
borders, how `komorebi.json` configures the daemon, 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
|
||||
|
||||
@@ -67,6 +67,10 @@ daemon that is added has its place here.
|
||||
asked the daemon, by the name of that socket, to send it notifications.
|
||||
- **Notification**: what a subscriber is sent after each event and each message the window
|
||||
manager handles: the event or the message, and the state after it ([`Notification`]).
|
||||
- **Look**: how the compositor is asked to dress the windows, which it draws ([`Look`]):
|
||||
a border, with its width, its corner radius and two colors.
|
||||
- **Effect**: a plugin of the compositor that changes how windows are drawn. KDE Rounded Corners
|
||||
is the effect that draws the border.
|
||||
- **Compositor**: the program that owns the screen and the windows. On KDE Plasma it is
|
||||
KWin.
|
||||
- **Backend**: the implementation of the [`Backend`](../../komorebi/src/backend/mod.rs)
|
||||
@@ -650,9 +654,10 @@ file `--config` names, or else `komorebi.json` in [`HOME_DIR`] (`$KOMOREBI_CONFI
|
||||
has three steps, because the monitors are known only after the backend is asked:
|
||||
|
||||
1. [`StaticConfig::preload`] reads the file, applies the settings that are process-wide (the
|
||||
default paddings, [`LAYOUT_DEFAULTS`], the indices of the monitors, and the rules in
|
||||
[`IGNORE_IDENTIFIERS`], [`MANAGE_IDENTIFIERS`] and [`FLOATING_APPLICATIONS`]) and makes the
|
||||
[`WindowManager`], with the settings that are its own. It starts a watcher on the file.
|
||||
default paddings, [`LAYOUT_DEFAULTS`], the indices of the monitors, the settings of the borders
|
||||
in [`border_manager`], and the rules in [`IGNORE_IDENTIFIERS`], [`MANAGE_IDENTIFIERS`] and
|
||||
[`FLOATING_APPLICATIONS`]) and makes the [`WindowManager`], with the settings that are its own.
|
||||
It starts a watcher on the file.
|
||||
2. [`WindowManager::init`] loads the monitors and the windows from the backend, in the order the
|
||||
indices of the monitors give.
|
||||
3. [`StaticConfig::postload`] gives each monitor the entry of the file that is its own, and each
|
||||
@@ -679,9 +684,11 @@ there and is not an applications.json is an error.
|
||||
Three kinds of key reach the model. A **setting** of the window manager is a field of it
|
||||
([`WindowManager::resize_delta`] and the others). A **default** is a process-wide static that a
|
||||
monitor or a workspace falls back to when it has no value of its own: the paddings, the layout
|
||||
defaults. A **rule** is an entry of one of the process-wide lists. A workspace's own
|
||||
`layout_rules`, `work_area_offset_rules` and `window_container_behaviour_rules` are fields of the
|
||||
[`Workspace`], which [`Workspace::update`] reads each time it tiles.
|
||||
defaults. The settings of the borders are statics too, which the file sets and
|
||||
[`border_manager::current_look`] and the layout read. A **rule** is an entry of one of the
|
||||
process-wide lists. A workspace's own `layout_rules`, `work_area_offset_rules` and
|
||||
`window_container_behaviour_rules` are fields of the [`Workspace`], which [`Workspace::update`]
|
||||
reads each time it tiles.
|
||||
|
||||
A workspace's `workspace_rules` and `initial_workspace_rules` are not fields of the window manager
|
||||
but entries of [`WORKSPACE_MATCHING_RULES`], which [`StaticConfig::postload`] and
|
||||
@@ -754,15 +761,50 @@ goes the other way, for `GenerateStaticConfig`.
|
||||
| The configuration the daemon generates loads and says the same | test | `a_configuration_comes_out_again_as_the_settings_of_the_window_manager` | none |
|
||||
| The daemon reads the file it is given or the one in the config home, not both | startup order: `main.rs` takes `--config` before the config home | `the_daemon_follows_the_file_it_is_given_when_the_file_changes`, `the_daemon_reads_komorebi_json_from_the_config_home` | none |
|
||||
|
||||
## The look
|
||||
|
||||
komorebi decides what the windows look like and the compositor draws it, since only the
|
||||
compositor has the frames, the corners and the shadows. A border is the outer outline of a window,
|
||||
drawn outside it, in the gap the layout leaves between tiles. The window manager describes a
|
||||
[`Look`] and asks the backend for it ([`Backend::apply_look`]); the backend sees that it is drawn
|
||||
and answers whether borders are being drawn. The reasons are in
|
||||
[DESIGN.md](DESIGN.md#why-does-the-compositor-draw-the-borders-and-not-komorebi).
|
||||
|
||||
[`border_manager`] holds the settings, as statics that the messages `Border`, `BorderWidth` and
|
||||
`BorderOffset` set: whether borders are on, their width, the offset, the radius of the corners and
|
||||
the two colors. [`border_manager::current_look`] makes the [`Look`] of them, and
|
||||
[`border_manager::send_notification`] asks the backend for it and keeps the answer in
|
||||
[`BORDER_DRAWN`]. It is called before the first layout, after every event and every message, and
|
||||
after every retile. A backend remembers the look it applied last and does nothing when it is asked
|
||||
for the same again, so nothing reaches KWin unless a setting changed.
|
||||
|
||||
A drawn border takes room. While [`BORDER_DRAWN`] is set, [`Monitor::update_workspace_globals`]
|
||||
gives the workspace the width and the offset of the border, and [`Workspace::update`] takes both
|
||||
off every side of every tile, so the border falls in the gap and not on the window next to it.
|
||||
Without a border, because they are off or the compositor has no effect to draw one, the room is
|
||||
given back the next time the workspace is tiled.
|
||||
|
||||
The KWin backend draws the border with the effect KDE Rounded Corners
|
||||
([`kwin::effects`](../../komorebi/src/kwin/effects.rs)). `apply_look` writes the effect's settings
|
||||
into the user's `kwinrc`, group `[Round-Corners]`, through [`Kwinrc`]; loads the effect with
|
||||
`loadEffect` unless it is loaded; and always asks it to read its settings again
|
||||
(`reconfigureEffect`), since KWin hands an effect the copy of `kwinrc` it read when it started. A
|
||||
look without a border unloads the effect, if komorebi loaded it, and puts the user's settings
|
||||
back. `shutdown` does the same. An effect KWin did not find when it started is reported once and
|
||||
komorebi goes on without it, with `apply_look` answering false.
|
||||
[PLATFORM.md](PLATFORM.md#kwin-effects) has the effect, its settings and what was measured.
|
||||
|
||||
## The NixOS module
|
||||
|
||||
The flake exports one module under two names, `nixosModules.default` and
|
||||
`nixosModules.komorebi`: [`nixos-module.nix`] and the flake's overlay, which builds
|
||||
`komorebi-full` (both programs) with the flake's nixpkgs and Rust toolchain. Its options are
|
||||
`enable`, `package` (by default `pkgs.komorebi-full`, from the overlay), `logLevel`,
|
||||
`configFile`, `config`, `applicationSpecificConfiguration`, and `execStart`, which is read-only: the
|
||||
module sets it to `bin/komorebi` of the package with `--log-level`, and `--config` with a
|
||||
`komorebi.json` when `configFile` or `config` is set. `config` is typed from
|
||||
`configFile`, `config`, `applicationSpecificConfiguration`, `effects.borders.enable` and
|
||||
`effects.borders.package` (by default `pkgs.kde-rounded-corners-komorebi`, from the overlay), and
|
||||
`execStart`, which is read-only: the module sets it to `bin/komorebi` of the package with
|
||||
`--log-level`, and `--config` with a `komorebi.json` when `configFile` or `config` is set. `config`
|
||||
is typed from
|
||||
`nix/komorebi-options.nix`, the options `schemars-nixgen` makes from the schema of `komorebi.json`;
|
||||
the module writes it as JSON, with no null in it, and `configFile` and the written file both go
|
||||
through `check-jsonschema` against `schema.json` when the system is built (comment lines taken out
|
||||
@@ -771,7 +813,8 @@ fetched from GitHub that become `app_specific_configuration_path`; the module ha
|
||||
`internal.configAttrs` is the configuration as the attribute set the options make, for the tests.
|
||||
With `services.komorebi.enable`, the module:
|
||||
|
||||
- installs the package in the system profile;
|
||||
- installs the package in the system profile, and the effect that draws the borders unless
|
||||
`effects.borders.enable` is off;
|
||||
- defines the user unit `komorebi.service`, which every user of the machine has. Plasma's
|
||||
`plasma-workspace.target` wants it, so a Plasma session starts it at login, and it is ordered
|
||||
after `plasma-core.target`, which Plasma orders after KWin's service, `plasma-kwin_wayland`;
|
||||
@@ -794,6 +837,8 @@ module's unit.
|
||||
| A configuration with a layout or a value komorebi does not have does not build | evaluation error: `config` is typed from the schema; and `check-jsonschema` fails the build for a file that does not follow it | `nixos-module-eval` ("a layout komorebi does not have does not evaluate"), `nix-options-validation` | `configFile` with a file the schema accepts |
|
||||
| The sources of application specific configuration reach the daemon only while `applicationSpecificConfiguration.enable` is set | framework path: the module adds `app_specific_configuration_path` to the file it writes only when `enable` is set and there are sources | `nixos-module-eval` ("with applicationSpecificConfiguration.enable = false, the sources are left out of config", "with the sources turned off and no config, there is nothing to write") | none |
|
||||
| `komorebi` and `komorebic` are on every user's `PATH` | the module installs the package in the system profile | `nixos-module-eval`; every VM suite runs `komorebic` | none |
|
||||
| The border effect is installed with komorebi, and only by the module | the module installs `effects.borders.package` in the system profile when `effects.borders.enable` is set | `nixos-module-eval` ("the border effect is installed in the system profile", "with the border effect off, komorebi is installed and the effect is not"), `vm-look` | `effects.borders.enable = false` |
|
||||
| The border effect the module installs is built for the KWin of the system and is not loaded until komorebi asks | the package: `kde-rounded-corners-komorebi` links the `libkwin` of the nixpkgs' KWin and says `EnabledByDefault` false in its metadata | the `kde-rounded-corners-komorebi-install` check | `effects.borders.package` |
|
||||
| Every Plasma session starts komorebi, once KWin's service has started | systemd: the user unit is wanted by `plasma-workspace.target`, after `plasma-core.target` | `nixos-module-eval`, `vm-module` | `systemctl --user mask komorebi` |
|
||||
| A daemon that fails or is killed is started again | systemd: `Restart=on-failure` | `vm-module` (`SIGKILL`) | none |
|
||||
| A daemon that is told to stop stays stopped, and the unit is not failed | systemd: the exit statuses of `Stop` (0) and of `SIGTERM` (130) are successes | `vm-module` | none |
|
||||
@@ -839,6 +884,10 @@ module's unit.
|
||||
[`bridge.js`](../../komorebi/src/kwin/bridge.js), the bridge.
|
||||
- [`static_config`](../../komorebi/src/static_config.rs): `komorebi.json`, [`StaticConfig`], and
|
||||
how it is loaded, reloaded and generated.
|
||||
- [`border_manager`](../../komorebi/src/border_manager/mod.rs): the border settings, and the
|
||||
[`Look`] they make, which it asks the backend for.
|
||||
- [`kwin::effects`](../../komorebi/src/kwin/effects.rs): the KWin effect that draws the border,
|
||||
its settings and the state komorebi keeps of it.
|
||||
- [`process_command`](../../komorebi/src/process_command.rs): the thread that listens on the
|
||||
socket, and what the window manager does with each message.
|
||||
- [`state`](../../komorebi/src/state.rs): the [`State`] a `State` message is answered with,
|
||||
@@ -854,8 +903,9 @@ module's unit.
|
||||
`docs/cli`.
|
||||
- [`main.rs`](../../komorebi/src/main.rs): the daemon. It connects to KWin, or installs the
|
||||
fake with `--fake-backend`, makes the window manager from `komorebi.json` when there is one,
|
||||
which binds the socket, loads the desktop, gives the monitors their configuration and tiles, starts the threads that listen on the socket and handle events, and
|
||||
waits to be stopped.
|
||||
which binds the socket, loads the desktop, gives the monitors their configuration, asks for the
|
||||
borders and tiles, starts the threads that listen on the socket and handle events, and waits to
|
||||
be stopped.
|
||||
- [`nixos-module.nix`]: the NixOS module, which installs komorebi and runs the daemon as a
|
||||
systemd user unit of every Plasma session.
|
||||
|
||||
@@ -888,6 +938,9 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
|
||||
`set_window_workspace` changes where it comes back to, not where it is hidden. Only the back of
|
||||
a stack and the containers behind a monocle are hidden: nothing is hidden to leave a
|
||||
workspace.
|
||||
- The look is a request (`apply_look`): a backend asks the compositor to draw it and answers
|
||||
whether borders are being drawn, and one that draws nothing answers false, which is the default.
|
||||
It does nothing when it is asked for the look it applied last.
|
||||
- `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.
|
||||
@@ -973,6 +1026,10 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
|
||||
| What the backend sends is what the bridge carries out | tests: the commands of [`fixtures`] are what the backend's tests check it sends and what the bridge's tests answer it with, checking what KWin is asked to do for each | `the_commands_of_a_session_go_to_the_bridge_as_the_bridges_tests_answer_it`, `what the bridge sends for a session is what the daemon's tests read`, `a command for a window KWin no longer has is given back, and the rest are carried out` | none |
|
||||
| Everything the bridge sends over D-Bus is one string | type checker: [`kwin-api.d.ts`] gives `callDBus` one string argument | `tsc`, `every call goes to the daemon's names, with one JSON string` | none |
|
||||
| The bridge uses nothing a KWin script does not have | type checker: the library is ECMAScript 2016 alone, and KWin's API is what [`kwin-api.d.ts`] declares | `tsc` | a declaration KWin does not match: the VM tests run the bridge in KWin |
|
||||
| A border takes room around the windows only while the compositor draws it | framework path: [`border_manager::send_notification`] keeps the backend's answer in [`BORDER_DRAWN`], which [`Monitor::update_workspace_globals`] reads | `a_border_the_compositor_draws_takes_room_around_each_window_and_none_is_taken_without_one`, `a_look_is_a_command_once_and_says_whether_borders_are_drawn` | none |
|
||||
| The compositor is asked for the look after every event, every message and every retile, and only a changed look reaches it | framework path: [`WindowManager::process_event`], [`WindowManager::process_command`] and [`WindowManager::retile_all`] call [`border_manager::send_notification`], and a backend compares with the look it applied last | `the_border_messages_set_the_border_and_the_compositor_is_asked_for_it`, `a_look_is_a_command_once_and_says_whether_borders_are_drawn` | the same look applied twice by the KWin backend is not tested |
|
||||
| No outline is drawn inside a window, and a border is never thicker than the effect can draw | framework path: [`kwin::effects`](../../komorebi/src/kwin/effects.rs) sets every inner outline to 0 and clamps the width to 20 | `the_border_is_the_outer_outline_and_nothing_is_drawn_inside_the_window`, `a_border_thicker_than_the_effect_can_draw_is_the_thickest_it_can`, `vm-look` | none |
|
||||
| The effect komorebi loaded is unloaded, and the user's settings of it are put back, when komorebi stops using it or exits | framework path: the effect's state unloads what komorebi loaded, and [`Kwinrc`] puts the group back | `one_group_can_be_put_back_while_the_others_stay_changed`, `vm-look` | `SIGKILL`: the next run puts the settings back when it stops |
|
||||
| Queries never block on the compositor | convention only | none | the KWin backend's `cursor_pos` waits up to 250 ms |
|
||||
| Only the backend module reaches the compositor | convention only | none | none |
|
||||
|
||||
@@ -1091,6 +1148,15 @@ A window is shown, and ends up on a tile:
|
||||
stopped with `komorebic`.
|
||||
- [`nix/tests/vm/suites/kwin-restart`](../../nix/tests/vm/suites/kwin-restart/test.py): KWin
|
||||
restarting under the daemon.
|
||||
- [`nix/kde-rounded-corners.nix`](../../nix/kde-rounded-corners.nix): the build of the KWin
|
||||
effect that draws an outline around each window, and
|
||||
[`nix/tests/effects.nix`](../../nix/tests/effects.nix), the checks of the files each effect
|
||||
package installs.
|
||||
- [`komorebi/tests/borders.rs`](../../komorebi/tests/borders.rs) and
|
||||
[`komorebi/tests/border_commands.rs`](../../komorebi/tests/border_commands.rs): the room a drawn
|
||||
border takes, and the messages that set the border, against the fake;
|
||||
[`nix/tests/vm/suites/look`](../../nix/tests/vm/suites/look/test.py), the border in a real
|
||||
Plasma session, read from the pixels of a screenshot.
|
||||
- [`komorebi/tests/wm_events.rs`](../../komorebi/tests/wm_events.rs): the window manager
|
||||
driven end to end against the fake.
|
||||
- [`komorebi/tests/socket.rs`](../../komorebi/tests/socket.rs): the daemon over its socket,
|
||||
@@ -1168,6 +1234,13 @@ A window is shown, and ends up on a tile:
|
||||
[`set_backend`]: ../../komorebi/src/backend/mod.rs
|
||||
[`backend`]: ../../komorebi/src/backend/mod.rs
|
||||
[`with_backend`]: ../../komorebi/src/backend/mod.rs
|
||||
[`Look`]: ../../komorebi/src/backend/mod.rs
|
||||
[`Backend::apply_look`]: ../../komorebi/src/backend/mod.rs
|
||||
[`border_manager`]: ../../komorebi/src/border_manager/mod.rs
|
||||
[`border_manager::current_look`]: ../../komorebi/src/border_manager/mod.rs
|
||||
[`border_manager::send_notification`]: ../../komorebi/src/border_manager/mod.rs
|
||||
[`BORDER_DRAWN`]: ../../komorebi/src/border_manager/mod.rs
|
||||
[`WindowManager::retile_all`]: ../../komorebi/src/window_manager.rs
|
||||
[`Ring`]: ../../komorebi/src/ring.rs
|
||||
[`Monitor`]: ../../komorebi/src/monitor.rs
|
||||
[`Workspace`]: ../../komorebi/src/workspace.rs
|
||||
|
||||
@@ -372,3 +372,56 @@ what a Plasma session runs at login for a program that is not part of it, so
|
||||
ordered after `plasma-workspace` (`X-KDE-autostart-after`), as the module's unit is ordered after
|
||||
`plasma-core.target`: the daemon exits when KWin is not on the session bus. The entry and the
|
||||
unit do not go together, since the session bus gives its name to one komorebi.
|
||||
|
||||
## Why is KDE Rounded Corners built from source, and not taken from nixpkgs?
|
||||
|
||||
Because the version in nixpkgs draws its outline in the wrong place on KWin 6.8, the oldest
|
||||
KWin komorebi supports. At time of writing (2026-10-27, nixpkgs `d3b13ad`) nixpkgs has
|
||||
0.10.0, which puts the outline about 24 px too low, across the title bar. 0.11.0 is the
|
||||
release that handles the texture coordinates KWin 6.8 inverted, so
|
||||
[`nix/kde-rounded-corners.nix`](../../nix/kde-rounded-corners.nix) overrides the nixpkgs
|
||||
package with it ([PLATFORM.md](PLATFORM.md#kwin-effects)).
|
||||
|
||||
## Why are the effects built disabled by default?
|
||||
|
||||
So that they cannot load with their own defaults before komorebi configures them. KWin loads
|
||||
an effect that is enabled by default as soon as it starts, with the settings the effect has
|
||||
then, and KDE Rounded Corners at its defaults draws a one pixel black outline over the title
|
||||
bar of every window. Built with `EnabledByDefault` false, an effect is loaded only when
|
||||
something asks for it with `loadEffect`, which can come after its settings are written. That
|
||||
KWin then starts without the effect and loads it when asked was measured before the package
|
||||
was written ([PLATFORM.md](PLATFORM.md#kwin-effects)).
|
||||
|
||||
## Why does the compositor draw the borders, and not komorebi?
|
||||
|
||||
Because the compositor has the frames, the corners and the shadows of the windows, and komorebi
|
||||
has none of them. komorebi decides what the windows look like and describes it to the backend as a
|
||||
`Look` ([`Backend::apply_look`](../../komorebi/src/backend/mod.rs)); on KWin the effect KDE
|
||||
Rounded Corners draws it, and komorebi writes the effect's settings. The same code that decides the
|
||||
look then runs against the fake desktop, which records the look it was asked for.
|
||||
|
||||
## Why is the border the outer outline of the effect?
|
||||
|
||||
Because the effect's own defaults draw a black outline one pixel thick *inside* every window, over
|
||||
its title bar and contents, which is what an unconfigured install looks like. So komorebi sets
|
||||
every inner outline to 0 and uses the outer outline, which is drawn outside the window, in the gap
|
||||
the layout leaves between tiles. The effect draws the outer outline only in the shadow of the
|
||||
window (its shader stops where the window's texture is transparent), so it is at most 20 px thick,
|
||||
and a window that has no shadow has no border. komorebi does not take the title bar off a window
|
||||
to change that: removing it also removed the shadow, and the border with it, and Plasma 6.8 gives
|
||||
a window without a shadow one of its own ([PLATFORM.md](PLATFORM.md#kwin-effects)).
|
||||
|
||||
## Why does the layout leave room for the border only while it is drawn?
|
||||
|
||||
Because the border is outside the window: without room for it, it would fall on the window next
|
||||
to it. And because komorebi cannot know that a border is drawn. The effect may not be installed
|
||||
(KWin finds effects when it starts), or borders may be off, so the backend answers whether
|
||||
`apply_look` drew one, and the layout leaves room only after a yes. A compositor that draws no
|
||||
border takes none.
|
||||
|
||||
## Why does komorebi ask the effect to read its settings again after it loads it?
|
||||
|
||||
Because KWin keeps the copy of `kwinrc` it read when it started, and an effect reads its settings
|
||||
from that copy, also one loaded a moment ago. Writing the file and loading the effect leaves the
|
||||
effect with the settings the file had at the start of the session. `reconfigureEffect` makes it
|
||||
read them again, so komorebi calls it every time, after loading too.
|
||||
+72
-2
@@ -139,6 +139,10 @@ there. The desktop is not a workspace: komorebi counts the workspaces without it
|
||||
it is on the workspace it will come back to. It checks that KWin still lists the desktop before it
|
||||
sends another window there.
|
||||
|
||||
When borders are on, it also asks KWin to load KDE Rounded Corners, the effect that draws them,
|
||||
after writing the effect's settings into `kwinrc`, and asks it to read them again
|
||||
([KWin effects](#kwin-effects)). An effect KWin did not find is reported once in the log.
|
||||
|
||||
Every command of the window manager (move and resize, focus, raise, hide or restore, minimize,
|
||||
bring back, maximize, unmaximize or 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
|
||||
@@ -165,8 +169,9 @@ an owner again; the VM test `vm-kwin-restart` restarts KWin twice under a runnin
|
||||
|
||||
When it is stopped with `SIGINT`, `SIGTERM` or a `Stop` message on its socket, it brings back
|
||||
the windows it hid, waits until the commands that do so have reached the bridge, removes the
|
||||
parking desktop, 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
|
||||
parking desktop, unloads the border effect, if komorebi loaded it, puts back the values the keys it
|
||||
set in `kwinrc` had (`PerOutputVirtualDesktops`, and the keys of the border effect), or removes a
|
||||
key the user had not set, 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 for workspaces stay: they are the user's desktops from then on. A `StopIgnoreRestore`
|
||||
message stops it the same way, except that it does not bring the windows back: the parking desktop
|
||||
@@ -221,6 +226,7 @@ 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` | `/Effects` | `org.kde.kwin.Effects` | `isEffectSupported(s)`, `isEffectLoaded(s)`, `loadEffect(s)`, `unloadEffect(s)`, `reconfigureEffect(s)`, with `kwin4_effect_shapecorners` | when the look changes (the border is turned on, off or changed), and at exit |
|
||||
| `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 properties `desktops` and `count`, `createDesktop(us)`, `setDesktopName(ss)`, `removeDesktop(s)` | when a workspace has no desktop, and at start; `createDesktop` also for the parking desktop, the first time a window is hidden, and `removeDesktop` for it when komorebi stops and for one a killed run left |
|
||||
|
||||
@@ -235,6 +241,7 @@ since a read right after `createDesktop` has to see the new desktop.
|
||||
| `$KOMOREBI_CONFIG_HOME/komorebi.json` (`~/.config/komorebi/komorebi.json`) | komorebi's configuration, which komorebi never writes: read when the daemon starts, and again when it changes. `--config` names another file | the user's |
|
||||
| `$XDG_CONFIG_HOME/autostart/komorebi.desktop` (`~/.config/autostart/komorebi.desktop`) | the XDG autostart entry `komorebic enable-autostart` writes: `Exec=komorebi`, or `komorebi --config "FILE"`, and `X-KDE-autostart-after=plasma-workspace`, which a Plasma session starts komorebi from at login | the user's; `komorebic disable-autostart` removes it |
|
||||
| `$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_CONFIG_HOME/kwinrc`, group `[Round-Corners]` | the settings of the border effect, written when borders are on ([KWin effects](#kwin-effects)) | put back, with the rest of `kwinrc`, when borders are turned off and 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 |
|
||||
@@ -391,6 +398,69 @@ the batch moved, the client's answer included:
|
||||
The spikes measured the channel alone, with twenty windows in each batch, at 16, 19 and 20 ms
|
||||
([DESIGN.md](DESIGN.md#why-do-commands-go-to-the-bridge-as-the-answer-to-a-held-call)).
|
||||
|
||||
## KWin effects
|
||||
|
||||
An effect is a plugin of KWin's compositor that changes how windows are drawn. The flake
|
||||
builds the effects komorebi drives as packages of their own, from source:
|
||||
|
||||
| Package | Effect | Plugin id | Installed as |
|
||||
|---|---|---|---|
|
||||
| `kde-rounded-corners-komorebi` | [KDE Rounded Corners](https://github.com/matinlotfali/KDE-Rounded-Corners) 0.11.0, which draws an outline around each window | `kwin4_effect_shapecorners` | a C++ plugin, `lib/qt-6/plugins/kwin/effects/plugins/kwin4_effect_shapecorners.so` |
|
||||
|
||||
Each package is in the flake's `packages` for Linux and in `overlays.default`, which builds it
|
||||
with the `callPackage` of the nixpkgs it is applied to, so that it follows that nixpkgs' KWin.
|
||||
[`nix/tests/effects.nix`](../../nix/tests/effects.nix) has a check for each, which builds the
|
||||
package and inspects its files the way KWin finds them, without a session.
|
||||
|
||||
At time of writing (2026-10-27):
|
||||
|
||||
- **KWin finds effects only when it starts.** An effect installed while KWin runs cannot be
|
||||
loaded (`isEffectSupported` is false and `loadEffect` returns false) until KWin starts
|
||||
again, which in a session means logging out and back in.
|
||||
- **KWin loads every effect that is enabled by default when it starts**, with the settings
|
||||
the effect has then. KDE Rounded Corners 0.11.0 is enabled by default in its
|
||||
`metadata.json`, and at its defaults it draws a one pixel black outline inside every
|
||||
window, over its title bar. The package builds it with `"EnabledByDefault": false`: KWin
|
||||
starts without it (`loadedEffects` lists the built-in effects only), `isEffectSupported`
|
||||
is true, and `loadEffect` with `kwin4_effect_shapecorners` on `org.kde.KWin`'s `/Effects`
|
||||
loads it. The metadata is compiled into the plugin, which is where the check reads the
|
||||
flag, with `qtplugininfo`.
|
||||
- **KDE Rounded Corners 0.10.0, the version in nixpkgs, draws the outline about 24 px too low
|
||||
on KWin 6.8**: across the title bar at the top, the same distance below the frame at the
|
||||
bottom, and in the right place at the sides. KWin 6.8 inverted the texture coordinates of
|
||||
the offscreen window, and Breeze's shadow is deeper below a window than above it; the error
|
||||
is the difference of the two. 0.11.0 is the release that handles it.
|
||||
- **KDE Rounded Corners links `libkwin.so.6`**, so it is built against the KWin that loads
|
||||
it. With the package in a NixOS system's `environment.systemPackages`, KWin finds the
|
||||
plugin in `/run/current-system/sw/lib/qt-6/plugins/kwin/effects/plugins/`, and the plugin
|
||||
links the libkwin of the store path the running `kwin_wayland` comes from. The check
|
||||
asserts the same for the `kdePackages.kwin` of the flake's nixpkgs: the first directory of
|
||||
the plugin's `RUNPATH` that has `libkwin.so.6` is that KWin's `lib`.
|
||||
- **KDE Rounded Corners draws its outer outline in the window's shadow**: its shader stops
|
||||
where the window's texture is transparent. A window without a shadow has no outer outline,
|
||||
and the outline is at most 20 px thick.
|
||||
|
||||
### What komorebi writes for the border
|
||||
|
||||
KDE Rounded Corners reads its settings from the group `[Round-Corners]` of `kwinrc` (the names are
|
||||
those of the effect's `options.kcfg`). komorebi sets every outline, not only the one it uses:
|
||||
|
||||
| Key | Value |
|
||||
|---|---|
|
||||
| `OuterOutlineThickness`, `InactiveOuterOutlineThickness` | the border's width, 0 to 20 |
|
||||
| `OuterOutlineColor`, `InactiveOuterOutlineColor` | `r,g,b`: the focused window's border, and every other window's |
|
||||
| `Size`, `InactiveCornerRadius` | the corner radius |
|
||||
| `OutlineThickness`, `InactiveOutlineThickness`, `SecondOutlineThickness`, `InactiveSecondOutlineThickness` | `0`: nothing inside the window |
|
||||
| `ActiveOuterOutlineAlpha`, `InactiveOuterOutlineAlpha` | `255` |
|
||||
| `ActiveOuterOutlineUseCustom`, `InactiveOuterOutlineUseCustom` | `true`, so that the colors are komorebi's |
|
||||
| `ActiveOuterOutlineUsePalette`, `InactiveOuterOutlineUsePalette`, `OuterOutlineIsGradient`, `InactiveOuterOutlineIsGradient` | `false` |
|
||||
|
||||
komorebi then calls `reconfigureEffect` on `/Effects`: at time of writing (2026-10-27), KWin 6.8.1
|
||||
hands an effect the copy of `kwinrc` it read when it started, so the new values reach it only
|
||||
that way, also for an effect loaded a moment before. A screenshot of a session shows the border
|
||||
in the pixels just outside the frame the window has in KWin, on all four sides, in the focused
|
||||
and unfocused colors, and not inside the frame.
|
||||
|
||||
## Rendering in virtual machines and over RDP
|
||||
|
||||
At time of writing (2026-10-27):
|
||||
|
||||
+19
-2
@@ -141,8 +141,18 @@ the run.
|
||||
- `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, `desktop_names()` their names in order (the parking desktop
|
||||
of a stack is the one named `komorebi-park`), and `kwinrc(group, key)` a value
|
||||
of the user's `kwinrc`.
|
||||
of a stack is the one named `komorebi-park`), `kwinrc(group, key)` a value of
|
||||
the user's `kwinrc`, and `kwinrc_group(group)` every key of a group, which a
|
||||
test compares before and after komorebi to see that the user's settings are
|
||||
put back.
|
||||
- `effect_supported(name)` and `effect_loaded(name)` ask KWin whether an effect is
|
||||
installed (KWin found it when it started) and loaded, and `unload_effect(name)`
|
||||
unloads one, whoever loaded it.
|
||||
- `pixels` reads a screenshot: `pixels.pixel(image, x, y)` is the color of a
|
||||
pixel, `pixels.near(a, b)` compares two colors within a tolerance, since a
|
||||
compositor blends the edge of what it draws, and `pixels.ring(image, frame,
|
||||
color)` names the sides of a window's frame that have no ring of `color` just
|
||||
outside them, which is how a test sees a border.
|
||||
- `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
|
||||
@@ -161,6 +171,13 @@ Two traps are worth knowing about before writing a screenshot test:
|
||||
on it, so "the screenshot is not blank" passes while Plasma is still
|
||||
starting. `Kde.session` waits for the splash process to exit, and a test
|
||||
should check a pixel it knows, such as the middle of a terminal.
|
||||
- The panel comes after the shell. A window tiled before the panel was made is
|
||||
tiled under it, which hides the bottom of its border from a screenshot, and
|
||||
nothing tiles it again. `Kde.session` waits until the shell has made a panel. KWin takes
|
||||
the room for the panel a while after that, and a daemon learns of it up to a second later: a
|
||||
test that opens windows right after the daemon starts waits with
|
||||
`Kde.wait_for_panel_room` first. It is a wait and not a check, because a session that is too
|
||||
slow may never take the room.
|
||||
- NixOS wraps programs, so a process's name is the wrapper's (`.plasmashell-wrapped`),
|
||||
and `pgrep -x plasmashell` never matches. Match the command line instead, with
|
||||
a bracket in the pattern (`pgrep -f '[p]lasmashell'`) so that the shell running
|
||||
|
||||
Reference in new issue
Block a user