mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-19 15:18:40 +01:00
feat(kwin): the daemon registers with KGlobalAccel
A static shortcut can only be one combo, pressed, the same in every application. Modes, chord chains, release bindings and per-application bindings need komorebi to hold the keys and decide what each press does: the engine of komorebi-hotkeys, a state machine with no I/O. This commit runs it against KWin's global shortcut daemon, which KWin 6.8 runs inside itself on the session bus. kwin::hotkeys owns the component komorebi in kglobalaccel, with one action per combo, named after the combo (Alt+H). An activation of the engine is setShortcutKeys(id, [[combo]], 6), with a doRegister the first time; a deactivation is setInactive, after which the key reaches the focused window again. The calls of one event are sent without waiting for each other's answers, which Phase 0 measured at 60 calls in 2.4 ms. globalShortcutPressed and globalShortcutReleased of /component/komorebi feed the engine; globalShortcutRepeated is ignored, so a held key runs its binding once. A komorebic command runs the komorebic next to the daemon with its words when they need no shell, anything else runs through sh -c. The calls are computed by Registry, which is pure and tested; the D-Bus part is proved by the VM test. The engine hears the presses at the path /component/komorebi and does not ask kglobalaccel for the object with getComponent. kglobalaccel makes the object when the component gets its first action, so a start with no key to grab (every binding is for an application other than the one with the focus) has none to ask for: getComponent fails with NoSuchComponent, and an engine that asked would never start. A signal is matched by the path it comes from, so the presses are heard as soon as there is an object. PLATFORM.md says so. kglobalaccel keeps the actions and the grabs of a client that was killed, so a start is an idempotent reconcile: the actions of the component that the keymap names are taken over and released unless the default mode wants them, the others are unregistered. A stop releases and unregisters everything, from KWinBackend::shutdown, which SIGINT, SIGTERM and the Stop message all go through. The daemon takes --keybindings FILE, --keybindings-format skhd|whkd|sxhkd (by default from the file's name) and --keybindings-mode (the mode komorebic hotkeys compile wrote the static shortcuts in, so that the daemon leaves those to KDE); without --keybindings it reads the first of skhdrc, whkdrc and sxhkdrc in the config directory (HOME_DIR, KOMOREBI_CONFIG_HOME). It logs one line about the file and the diagnostics at debug level. An engine that cannot start is logged and the window manager runs without keys; the fake backend runs none. The VM test vm-keys-engine starts the daemon in a Plasma session with an skhdrc in the config directory, presses its keys (a command, one through a shell, komorebic retile reaching the daemon), kills the daemon and sees its keys stay registered, starts it with another file and sees the old keys unregistered and the new ones work, and stops it with komorebic stop, after which no key is registered and none runs. The library gains spawn_komorebi, kill_spawned_komorebi and shortcut_actions, and Checks.finish names the checks that failed, since nix build shows only the last lines of a failed run. The suite's node turns the module's unit off: the test runs daemons of its own.
This commit is contained in:
1 parent
e1a227434b
commit
b49c4fab0a
16 files changed
+1109
-21
No files matched your search
@@ -1655,6 +1655,28 @@ read and left out (a warning) and how many bindings are not realized as their ow
|
||||
the ones `kde::diff` says that plan would write. It reads no file the desktop has no part in, so
|
||||
`--configuration-only` keeps it.
|
||||
|
||||
### The engine in the daemon
|
||||
|
||||
[`komorebi/src/kwin/hotkeys.rs`](../../komorebi/src/kwin/hotkeys.rs) runs the engine against
|
||||
kglobalaccel, on a session bus connection and a thread of its own. The daemon reads the file
|
||||
it is given with `--keybindings` (or the first it finds in the config directory), plans it in
|
||||
`--keybindings-mode`, and hands the plan's engine keymap to `kwin::hotkeys::start`, unless the
|
||||
plan needs no engine. A failure to start is logged, and the window manager runs without keys.
|
||||
|
||||
- **Calls**: each effect becomes calls on `/kglobalaccel` (`Registry`): an activation is
|
||||
`setShortcutKeys(id, [[combo]], 6)`, preceded by `doRegister` the first time; a deactivation
|
||||
is `setInactive`. The calls of one event are sent together, and only those for one action
|
||||
wait for each other.
|
||||
- **Signals**: `globalShortcutPressed` and `globalShortcutReleased` of `/component/komorebi`
|
||||
are the engine's presses and releases. `globalShortcutRepeated` is not listened to.
|
||||
- **Commands**: a `komorebic` command runs `komorebic` (the one next to the daemon) with its
|
||||
words when it needs no shell, and anything else runs through `sh -c`, as processes the
|
||||
daemon does not wait for.
|
||||
- **Start**: the component's actions that the keymap names are taken over, and released
|
||||
unless the default mode wants them; the others are unregistered.
|
||||
- **Stop**: every key is released and every action unregistered, from
|
||||
`KWinBackend::shutdown`, which every way the daemon stops goes through.
|
||||
|
||||
### What is guaranteed, and by what
|
||||
|
||||
| Rule | Enforced by | Proof | Escape hatch |
|
||||
@@ -1682,6 +1704,11 @@ the ones `kde::diff` says that plan would write. It reads no file the desktop ha
|
||||
| `komorebic check` says when the shortcut files are not the ones `hotkeys compile` would write | test | `shortcut_files_that_are_not_the_ones_of_the_plan_are_a_warning_that_says_how_many`, `shortcut_files_the_file_does_not_call_for_are_a_warning_until_compile_replaces_them` | none |
|
||||
| `--strict` writes nothing when a diagnostic is a warning or an error | test, through the binary | `strict_refuses_a_file_with_a_warning_and_writes_nothing` | none |
|
||||
| KWin runs a static shortcut's command on its key, from the system profile at the start of a session and from the user's directory after `--reload` | VM test | `vm-keys-static` | none |
|
||||
| An effect becomes the calls that carry it out, and an action is registered once | test | `Registry` doctest, `a_start_with_nothing_left_behind_registers_and_grabs_the_default_mode` | none |
|
||||
| A start takes over the keys a killed daemon left, releases those the default mode does not want, and unregisters the actions its keymap does not name | test, of the calls; VM test, against kglobalaccel | `a_start_takes_over_the_keys_of_a_killed_komorebi_and_drops_the_rest`, `vm-keys-engine` | none |
|
||||
| A stop of the daemon unregisters every action | framework path: `KWinBackend::shutdown` calls `kwin::hotkeys::stop`, and both ways to stop call it; VM test | `vm-keys-engine` (`komorebic stop`) | `SIGKILL` leaves the keys until the next start |
|
||||
| A press of a grabbed key runs its binding's command, `komorebic` without a shell where it needs none | test, of the process; VM test | `command` doctest, `a_press_runs_the_command_and_changes_no_key`, `vm-keys-engine` | none |
|
||||
| Holding a key runs its binding once | convention only: the transport listens to `globalShortcutPressed` and not to `globalShortcutRepeated` | none (measured in PLATFORM.md) | none |
|
||||
|
||||
## Where to look in the code
|
||||
|
||||
@@ -1870,6 +1897,10 @@ the ones `kde::diff` says that plan would write. It reads no file the desktop ha
|
||||
[`komorebic/tests/hotkeys.rs`](../../komorebic/tests/hotkeys.rs), what they write.
|
||||
- [`nix/tests/vm/suites/keys-static`](../../nix/tests/vm/suites/keys-static/test.py): static
|
||||
shortcuts run by a real KWin.
|
||||
- [`komorebi/src/kwin/hotkeys.rs`](../../komorebi/src/kwin/hotkeys.rs): the engine against
|
||||
kglobalaccel, and
|
||||
[`nix/tests/vm/suites/keys-engine`](../../nix/tests/vm/suites/keys-engine/test.py), keys
|
||||
pressed in a real KWin with the daemon running.
|
||||
- [`komorebi-hotkeys/tests`](../../komorebi-hotkeys/tests): the corpus test and the comparison
|
||||
with `whkd-parser`.
|
||||
- [`nix/nixos-module.nix`](../../nix/nixos-module.nix): the NixOS module;
|
||||
|
||||
+45
-12
@@ -196,20 +196,22 @@ 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 brings back
|
||||
the windows it hid, waits until the commands that do so have reached the bridge, removes the
|
||||
parking desktop, unloads the effects it loaded, puts back the values the keys it set in `kwinrc`
|
||||
had (`PerOutputVirtualDesktops`, the focus policy, and the keys of the effects), 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 is removed all
|
||||
the same. The file `bridge.js` stays in the runtime
|
||||
the windows it hid, unregisters the keys of its engine, waits until the commands that do so have
|
||||
reached the bridge, removes the parking desktop, unloads the effects it loaded, puts back the
|
||||
values the keys it set in `kwinrc` had (`PerOutputVirtualDesktops`, the focus policy, and the keys
|
||||
of the effects), 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 is removed all the same. 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, per-output desktops
|
||||
on, and the parking desktop with the hidden windows on it, until the next start replaces the
|
||||
script and the socket, sends the windows on the parking desktop to the first workspace's desktop
|
||||
and removes the desktop, and its stop puts the setting back (the backup in the runtime
|
||||
directory keeps the user's value), or the session ends.
|
||||
directory keeps the user's value), or the session ends. It also leaves the keys of its engine
|
||||
grabbed: they are swallowed, and run nothing, until the next start takes them over and unregisters
|
||||
those its key bindings no longer have.
|
||||
|
||||
### A headless KWin
|
||||
|
||||
@@ -260,6 +262,9 @@ What komorebi calls:
|
||||
| `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 |
|
||||
| `org.kde.plasmashell` | `/PlasmaShell` | `org.kde.PlasmaShell` | `evaluateScript(s) -> s`, `wallpaper(u) -> a{sv}`, `setWallpaper(sa{sv}u)` | when a workspace with a wallpaper comes into view ([The Plasma shell](#the-plasma-shell)) |
|
||||
| `org.kde.kglobalaccel` | `/kglobalaccel` | `org.kde.KGlobalAccel` | `allActionsForComponent(as) -> aas` | when the engine starts |
|
||||
| `org.kde.kglobalaccel` | `/kglobalaccel` | `org.kde.KGlobalAccel` | `doRegister(as)`, `setShortcutKeys(as, a(ai), u) -> a(ai)`, `setInactive(as)`, `unRegister(as)` | when the engine grabs and lets go of keys, and when it starts and stops |
|
||||
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `AddMatch(s)`, for `globalShortcutPressed` and `globalShortcutReleased` of `/component/komorebi` | when the engine starts |
|
||||
|
||||
What komorebi listens to, for the machine sleeping and the screen being locked:
|
||||
|
||||
@@ -317,6 +322,34 @@ write such files. What follows was measured at time of writing (2026-10-27) on K
|
||||
- The VM test `vm-keys-static` presses the keys of shortcut files in the system profile, and of
|
||||
one written and handed over in the middle of the session.
|
||||
|
||||
The engine registers its keys itself, in the component `komorebi`, with one action per combo
|
||||
named after the combo (`Alt+H`); an action's id is `["komorebi", "Alt+H", "komorebi",
|
||||
"Alt+H"]`. What was measured of that interface at time of writing (2026-10-27), on KWin
|
||||
6.8.1 in a virtual machine under HVF with 4 cores:
|
||||
|
||||
- `setShortcutKeys(as id, a(ai) keys, u flags) -> a(ai)` takes a list of key sequences, each
|
||||
a struct of one Qt key code per key of the sequence, and returns the keys it set. Flags 6
|
||||
(`SetPresent | NoAutoloading`) grab the key at once, whatever kglobalaccel saved for the
|
||||
action. A key that another action has is not set: the answer is not what was asked for, and
|
||||
komorebi logs a warning.
|
||||
- A grabbed key does not reach the focused window, a bare key (`H`, `Escape`) included, and
|
||||
each tap is a `globalShortcutPressed` and then a `globalShortcutReleased` signal
|
||||
(`ssx`: component, action, timestamp) on `/component/komorebi`. The signal reached a client
|
||||
2.5 ms after the key at the median (2.2 to 3.9 ms, 20 presses), also after another window
|
||||
had taken the focus.
|
||||
- A key held for 1.2 s sent one pressed signal, 15 `globalShortcutRepeated` and one released
|
||||
signal, in that order.
|
||||
- After `setInactive`, the key reaches the focused window and no signal is sent;
|
||||
`setShortcutKeys` grabs it again. Sixty such calls, sent without waiting for the answers,
|
||||
were all answered in 2.4 ms, and the state afterwards was right.
|
||||
- A client that is killed leaves its actions and its grabs: the key stays swallowed and its
|
||||
signal is sent to nobody until `unRegister`.
|
||||
- A sequence of two keys (`[[Meta+A, B]]`) is accepted and stored, but never fires: the
|
||||
second key reaches the focused window.
|
||||
- `getComponent` fails until the component has an action, so the engine does not ask for the
|
||||
object of its component: it listens at the object's path, `/component/komorebi`, which a
|
||||
signal is matched by, and a start with no key to grab is a start all the same.
|
||||
|
||||
## Files and directories
|
||||
|
||||
| Path | What | Lifetime |
|
||||
@@ -335,7 +368,7 @@ write such files. What follows was measured at time of writing (2026-10-27) on K
|
||||
| `$XDG_DATA_HOME/komorebi/komorebi.log.YYYY-MM-DD` | the daemon's log, with colors, which `komorebic log` follows | a file a day (the UTC date), never removed by komorebi |
|
||||
| `$XDG_DATA_HOME/komorebi/komorebi_plaintext.log.YYYY-MM-DD` | the same log without colors | as above |
|
||||
| `$XDG_DATA_HOME/kglobalaccel/komorebi-*.desktop` | the static shortcuts `komorebic hotkeys compile` and `komorebic export-kde-shortcuts` write, each with `X-Komorebi-Generated=true` | replaced at every write: the files with that key are removed, and no other |
|
||||
| `$KOMOREBI_CONFIG_HOME/{skhdrc,whkdrc,sxhkdrc}` | the key binding file `komorebic hotkeys compile` reads when it is given none (the first that exists), and the skhdrc of `export-kde-shortcuts` | the user's |
|
||||
| `$KOMOREBI_CONFIG_HOME/{skhdrc,whkdrc,sxhkdrc}` | the key binding file `komorebic hotkeys compile` and the daemon read when they are given none (the first that exists), and the skhdrc of `export-kde-shortcuts` | the user's; the daemon reads it once, at start |
|
||||
|
||||
Without `XDG_RUNTIME_DIR` the bridge and the socket are in `komorebi` in the local data
|
||||
directory instead, with the logs (see [`XDG_DATA_HOME`](#xdg_data_home)).
|
||||
@@ -380,8 +413,8 @@ The config home, where komorebi looks for `komorebi.json`: a directory, in which
|
||||
configuration` and the daemon look for the file. Without it the config home is
|
||||
`~/.config/komorebi`, whatever `XDG_CONFIG_HOME` is. When it is set and is not a directory, the
|
||||
daemon and `komorebic` panic when they first need the config home, and say so. Environment
|
||||
variables in it are expanded (`$HOME/komorebi`). `komorebic hotkeys compile` looks in it for the
|
||||
key binding file it is not given.
|
||||
variables in it are expanded (`$HOME/komorebi`). The daemon and `komorebic hotkeys compile` look
|
||||
in it for the key binding file they are not given.
|
||||
|
||||
### `XDG_RUNTIME_DIR`
|
||||
|
||||
|
||||
@@ -106,7 +106,9 @@ check also runs `ruff` and `ty` over it. The driver type checks every
|
||||
the run.
|
||||
|
||||
- `Checks` counts checks and fails once, at the end, so that one failure does
|
||||
not hide the ones after it. `finish()` prints `passed: N failed: M`.
|
||||
not hide the ones after it. `finish()` prints `passed: N failed: M`, and its
|
||||
error names the checks that failed, which `nix build` shows in the last lines
|
||||
of the run.
|
||||
- `Kde` is one KWin session. `Kde.headless(machine, name, size=, outputs=,
|
||||
scale=)` starts the units and waits for KWin to own its name on the private
|
||||
bus. `wid`, `rect`, `title` and `active` read windows through `kdotool`,
|
||||
@@ -187,6 +189,11 @@ the run.
|
||||
- `Keys(machine).send("alt-shift-k")` presses a combo on the machine's
|
||||
keyboard, written as KDE writes it in lower case with `-` between the keys
|
||||
(`meta` and `super` are the left Super key).
|
||||
- `spawn_komorebi(*args)` starts a daemon of the test's own in the session
|
||||
node's Plasma session, logging to the file `komorebi_log()` reads;
|
||||
`kill_spawned_komorebi()` kills it with `SIGKILL`; `shortcut_actions()` lists the
|
||||
actions komorebi has registered with kglobalaccel. A suite that spawns its own
|
||||
daemon turns the module's unit off in its `node`.
|
||||
|
||||
## Pressing keys
|
||||
|
||||
|
||||
Reference in new issue
Block a user