mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-22 16:34:15 +01:00
feat(cli): turn key binding files into KDE static shortcuts
komorebi users keep their bindings to komorebic in a file of skhd, whkd or sxhkd. On Plasma under Wayland no client sees the keys of another, and the program that runs a command on a key is KDE's global shortcut daemon, which runs inside KWin. A binding that is one combo, pressed, the same in every application, in a file without modes, can be a static shortcut: a .desktop file that KWin reads by itself, that shows in System Settings and that works with no komorebi process at all. komorebic hotkeys compile reads a file of any of the three formats, plans it with komorebi-hotkeys in the mode it is given (auto, engine or static; the default is the crate's), prints the diagnostics of reading and planning, and writes the static shortcuts to $XDG_DATA_HOME/kglobalaccel or --output, replacing the files it wrote before and no other. --strict refuses a file with a warning or an error before writing anything, --dry-run says what a write would change, and --reload hands each new file to the running KWin. komorebic export-kde-shortcuts keeps the spike's interface for an skhdrc, in the static mode. Both are thin: the reading, the plan and the files are the crate's. The bindings that need the engine are counted; the daemon does not run them yet. docgen gives a subcommand of a subcommand a page of its own (hotkeys-compile.md). KOMOREBI_CONFIG_HOME, or ~/.config/komorebi, is where komorebic looks for a file it is not given. komorebic check gains a section for the key bindings, between the configuration and the desktop: the first key binding file of the config home, how many bindings it has and where they go, the lines that cannot be read (a warning, and the first five) and the bindings not realized as their own daemon would (a note), and whether the generated files in the shortcut directory are the ones hotkeys compile would write now (a warning with how many to add, to change and to remove). --configuration-only keeps it, as it looks at files. The VM test vm-keys-static boots a Plasma session with shortcut files that hotkeys compile wrote into the system profile at build time, presses their keys through QEMU's keyboard, and sees each command run, a % in one of them included; then it writes a binding in the middle of the session with export-kde-shortcuts --reload and presses it. The library gains Keys, which sends a combo as KDE writes it through QEMU's sendkey.
This commit is contained in:
1 parent
a2e7f12bd3
commit
e1a227434b
27 files changed
+1585
-36
No files matched your search
@@ -964,8 +964,9 @@ configuration or a wallpaper that is not there, a wallpaper no theme can be made
|
||||
that is only a name, which is not tiled, and a workspace that appends windows to a container and
|
||||
has placement rules, which are not used then (the workspace's `window_container_behaviour`, or the
|
||||
file's when it has none). [`check_configuration`] also returns the [`Wants`] of the file: whether
|
||||
it draws borders, which animation style it asks for and whether it has wallpapers. `komorebic`
|
||||
prints [`Report::render`] and exits with status 1 if [`Report::has_errors`].
|
||||
it draws borders, which animation style it asks for and whether it has wallpapers. The key binding
|
||||
file has a section of its own, which `komorebic` makes (see [Key bindings](#key-bindings)).
|
||||
`komorebic` prints [`Report::render`] and exits with status 1 if [`Report::has_errors`].
|
||||
|
||||
[`check_environment`] looks at the desktop, with D-Bus calls of its own on the session bus (they
|
||||
are in the table of [PLATFORM.md](PLATFORM.md#d-bus)), and `komorebic check --configuration-only`
|
||||
@@ -1633,6 +1634,27 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
|
||||
- [`tests/fixtures`](../../komorebi-hotkeys/tests/fixtures): the corpus, `<case>.skhdrc`,
|
||||
`<case>.whkdrc` and `<case>.sxhkdrc`, each case in every format that can express it.
|
||||
|
||||
### The front end
|
||||
|
||||
[`komorebic/src/hotkeys.rs`](../../komorebic/src/hotkeys.rs) is the command line over the
|
||||
crate, and decides nothing about what a file means. `komorebic hotkeys compile` reads a file (by default the
|
||||
first of `skhdrc`, `whkdrc` and `sxhkdrc` in the komorebi config directory, its format from
|
||||
the end of its name), plans it in the mode it is given (by default `PlanMode::default()`),
|
||||
prints the diagnostics of reading and of planning on standard error, and writes the static
|
||||
shortcuts to `$XDG_DATA_HOME/kglobalaccel` or `--output`, replacing the files it wrote before.
|
||||
With `--strict`, a diagnostic that is a warning or an error stops it before it writes
|
||||
anything. `--dry-run` writes nothing and prints what a write would change, and `--reload`
|
||||
hands each new file to the running KWin, which otherwise reads them at the next login.
|
||||
`komorebic export-kde-shortcuts` is the same for an skhdrc, in `PlanMode::Static`.
|
||||
|
||||
`komorebic check` has a section for the key bindings, between the configuration and the desktop.
|
||||
`hotkeys::check` finds the file as `compile` does, reads and plans it in the default mode, and
|
||||
returns [`Finding`]s: how many bindings the file has and where they go, how many lines cannot be
|
||||
read and left out (a warning) and how many bindings are not realized as their own daemon would
|
||||
(a note), each with the first five, and whether the generated files in the shortcut directory are
|
||||
the ones `kde::diff` says that plan would write. It reads no file the desktop has no part in, so
|
||||
`--configuration-only` keeps it.
|
||||
|
||||
### What is guaranteed, and by what
|
||||
|
||||
| Rule | Enforced by | Proof | Escape hatch |
|
||||
@@ -1654,6 +1676,12 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
|
||||
| Stopping the engine gives every key back | test, of the effects; carrying them out is the daemon's | `start_activates_the_default_mode_and_stop_gives_everything_back` | none |
|
||||
| The engine does no I/O and reads no clock | convention only | none | none |
|
||||
| The whkd reader reads a whkdrc as whkd does | test, on the files it is given | `every_whkdrc_of_the_corpus_reads_as_whkd_reads_it`, `the_example_of_whkds_readme_reads_as_whkd_reads_it` | none |
|
||||
| `hotkeys compile` writes the static shortcuts of the plan and nothing else, from a file of any format | test, through the binary | `compile_writes_the_same_shortcut_files_from_each_format`, `compile_in_engine_mode_writes_no_shortcut_and_removes_the_ones_it_wrote` | none |
|
||||
| `komorebic check` reads the key binding file `hotkeys compile` would read, the way it does | framework path: `check` and `export` share `find` and `diagnostics`, and call the same `parse` and `plan` | `the_first_file_of_the_three_formats_is_the_one_that_is_read`, `the_key_binding_file_of_the_config_home_is_read_and_a_line_it_cannot_read_is_a_warning` | none |
|
||||
| A line of the key binding file that cannot be read does not fail `komorebic check` | test, through the binary | `the_key_binding_file_of_the_config_home_is_read_and_a_line_it_cannot_read_is_a_warning` | none |
|
||||
| `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 |
|
||||
|
||||
## Where to look in the code
|
||||
|
||||
@@ -1686,7 +1714,8 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
|
||||
format.
|
||||
- [`komorebi/src/check.rs`](../../komorebi/src/check.rs): the checks of `komorebic check`, with
|
||||
their tests; [`komorebic/tests/check.rs`](../../komorebic/tests/check.rs) runs the command on
|
||||
configurations and on buses that are not there, and reads what it prints and its exit status;
|
||||
configurations, on key binding files and on buses that are not there, and reads what it prints
|
||||
and its exit status;
|
||||
[`nix/tests/vm/suites/check`](../../nix/tests/vm/suites/check/test.py), the desktop check against
|
||||
a real KWin, with the daemon running, with its script gone, with no daemon and with no KWin.
|
||||
- [`komorebi/src/process_event.rs`](../../komorebi/src/process_event.rs): what each event
|
||||
@@ -1836,6 +1865,11 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
|
||||
[`sxhkd.rs`](../../komorebi-hotkeys/src/sxhkd.rs);
|
||||
[`plan.rs`](../../komorebi-hotkeys/src/plan.rs) and [`kde.rs`](../../komorebi-hotkeys/src/kde.rs)
|
||||
for the shortcuts, [`engine.rs`](../../komorebi-hotkeys/src/engine.rs) for the engine.
|
||||
- [`komorebic/src/hotkeys.rs`](../../komorebic/src/hotkeys.rs): `export-kde-shortcuts` and
|
||||
`hotkeys compile`, and the key bindings section of `komorebic check`;
|
||||
[`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-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;
|
||||
|
||||
@@ -747,6 +747,9 @@ The cost is the robustness of static shortcuts: the engine works only while komo
|
||||
and a komorebi process that was killed leaves its keys registered and dead until they are
|
||||
released.
|
||||
|
||||
Which of the two is the default is still open for a decision. `PlanMode::default()` is the
|
||||
one place it is set, and `komorebic hotkeys compile` takes its default from there.
|
||||
|
||||
## Why does the engine grab and give back keys, instead of using KDE's own key sequences?
|
||||
|
||||
Because KDE's do not work for this, as measured on KWin 6.8.1 (2026-10-27). kglobalacceld
|
||||
|
||||
+36
-1
@@ -292,6 +292,31 @@ At time of writing (2026-10-27), the headless KWin of the VM tests (Plasma 6.8)
|
||||
major version from it. The check does not need the answer: without the line it says that KWin is
|
||||
there and its version could not be read.
|
||||
|
||||
## Global shortcuts
|
||||
|
||||
KDE's global shortcut daemon runs inside KWin 6.8: `kwin_wayland` owns `org.kde.kglobalaccel`
|
||||
on the session bus, and there is no separate `kglobalacceld` process. A KWin started with
|
||||
`--no-global-shortcuts`, as the headless VM tests start it, has none.
|
||||
|
||||
A static shortcut is a `.desktop` file in a `kglobalaccel` directory with
|
||||
`X-KDE-GlobalAccel-CommandShortcut=true` and the key in `X-KDE-Shortcuts`; KWin runs its
|
||||
`Exec` line on the key. `komorebic hotkeys compile` and `komorebic export-kde-shortcuts`
|
||||
write such files. What follows was measured at time of writing (2026-10-27) on KWin 6.8.1:
|
||||
|
||||
- KWin reads the files when it starts: those in `$XDG_DATA_HOME/kglobalaccel` and those in
|
||||
`share/kglobalaccel` of the data directories, the system profile of NixOS among them.
|
||||
- A file added while KWin runs is not read until something calls
|
||||
`doRegister(["<file name>", "_launch", "", ""])` on `/kglobalaccel`, which is what `--reload`
|
||||
does for each new file (through `busctl`); the shortcut then works at once. A file whose
|
||||
content changed keeps the old content until the next login, and a removed file stays
|
||||
registered until then too.
|
||||
- In `Exec`, `%` starts a field code, so a command's `%` is written `%%`.
|
||||
- A static shortcut ran its command 165 to 436 ms after the key, 233 ms at the median, over 8
|
||||
presses, in a virtual machine under HVF with 4 cores. A key held for 1.5 s ran the command
|
||||
once.
|
||||
- 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.
|
||||
|
||||
## Files and directories
|
||||
|
||||
| Path | What | Lifetime |
|
||||
@@ -309,12 +334,18 @@ there and its version could not be read.
|
||||
| `$XDG_CACHE_HOME/komorebi` (`~/.cache/komorebi`) | the palettes made from wallpapers, a file for each picture and variant, `NAME-HASH.base16.VARIANT.json` | never removed by komorebi; made again when the picture's path, size or time of last change differ |
|
||||
| `$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 |
|
||||
|
||||
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)).
|
||||
|
||||
## What `komorebic check` looks at
|
||||
|
||||
The key binding file is the first of `skhdrc`, `whkdrc` and `sxhkdrc` in `$KOMOREBI_CONFIG_HOME`,
|
||||
and the shortcut files it compares with are the generated `komorebi-*.desktop` files in
|
||||
`$XDG_DATA_HOME/kglobalaccel`; neither needs a bus.
|
||||
|
||||
Apart from the bus, it looks at the files that start komorebi at login, in this order, and says which
|
||||
it found first: `$XDG_CONFIG_HOME/autostart/komorebi.desktop` (the autostart entry),
|
||||
`$XDG_CONFIG_HOME/systemd/user/komorebi.service`, `/etc/systemd/user/komorebi.service` and
|
||||
@@ -348,7 +379,9 @@ either. An address with no bus behind it is the first error under [No KWin](#no-
|
||||
The config home, where komorebi looks for `komorebi.json`: a directory, in which `komorebic
|
||||
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.
|
||||
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.
|
||||
|
||||
### `XDG_RUNTIME_DIR`
|
||||
|
||||
@@ -374,6 +407,8 @@ The logs are written to `$XDG_DATA_HOME/komorebi` (`~/.local/share/komorebi` if
|
||||
`XDG_DATA_HOME` is not set), which the daemon makes before anything else: a home it cannot
|
||||
write to stops it at once. When `XDG_RUNTIME_DIR` is not set, the bridge and the socket go
|
||||
there too.
|
||||
`komorebic` writes static shortcuts to `$XDG_DATA_HOME/kglobalaccel` unless it is given
|
||||
`--output`.
|
||||
|
||||
### `KWIN_EFFECTS_FORCE_ANIMATIONS`
|
||||
|
||||
|
||||
@@ -184,6 +184,25 @@ the run.
|
||||
pointer lands within a pixel of where it is asked. The program itself is
|
||||
[`komorebi_vm/uinput.py`](../../nix/tests/vm/lib/komorebi_vm/uinput.py),
|
||||
whose arithmetic the `vm-lib` check tests.
|
||||
- `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).
|
||||
|
||||
## Pressing keys
|
||||
|
||||
A key test presses keys with QEMU's `sendkey` (`machine.send_key`), through
|
||||
`Keys`. The key reaches the guest's kernel as a key of the machine's virtual
|
||||
keyboard, and KWin sees it as it sees a person's: a global shortcut fires on
|
||||
it, and any other key goes to the focused window. QEMU holds the keys for 100
|
||||
ms, less than the delay before a key repeats. Phase 0 drove keys from a uinput
|
||||
device inside the guest instead, as the pointer is driven now; `sendkey` needs
|
||||
no helper program for keys, and on x86_64 under KVM `vm-keys-static` passed with
|
||||
it on its first run (2026-10-27).
|
||||
|
||||
Global shortcuts need the session node: the headless KWin runs with
|
||||
`--no-global-shortcuts`, so it has no `org.kde.kglobalaccel`. A static
|
||||
shortcut written into the system profile by the suite's `node` (as
|
||||
`vm-keys-static` does) is found when the session starts.
|
||||
|
||||
Poll for what the test needs with `wait_for`. A fixed sleep is too long on
|
||||
KVM and too short on TCG.
|
||||
|
||||
Reference in new issue
Block a user