diff --git a/docs/dev/ARCHITECTURE.md b/docs/dev/ARCHITECTURE.md index 7909d708..4237ff79 100644 --- a/docs/dev/ARCHITECTURE.md +++ b/docs/dev/ARCHITECTURE.md @@ -1672,8 +1672,11 @@ plan needs no engine. A failure to start is logged, and the window manager runs - **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. +- **Modes**: a mode switch is the engine's deactivations and activations, carried out like + any others; the daemon logs the mode after each change. - **Start**: the component's actions that the keymap names are taken over, and released - unless the default mode wants them; the others are unregistered. + unless the default mode wants them; the others are unregistered. The engine starts in the + default mode. - **Stop**: every key is released and every action unregistered, from `KWinBackend::shutdown`, which every way the daemon stops goes through. @@ -1693,7 +1696,7 @@ plan needs no engine. A failure to start is logged, and the window manager runs | An `Exec` line runs the command as written (quoting, `%%`) | test | `exec_lines_are_quoted_for_the_desktop_entry_spec` | none | | The sample configuration plans into the same 50 shortcut files from each format | test | `the_sample_plans_into_the_same_shortcut_files_in_every_format` | none | | After every event, the active set is the one the engine wants for its state, and each effect changes it (no combo is activated twice) | framework path: every event handler that changes the state ends in the one reconcile step, which diffs two sets | `a_chain_activates_its_next_keys_until_it_ends`, `a_mode_has_its_own_keys` | none | -| A key the engine does not want reaches the application | convention only: kglobalacceld must be told with `setInactive`, by the daemon | none | none | +| A key the engine does not want reaches the application | framework path: the daemon turns every deactivation into `setInactive` (`Registry::calls`); VM test | `entering_a_mode_lets_the_keys_of_the_other_go_and_grabs_its_own`, `vm-keys-engine` (a bare H in a mode and out of it, seen by `wev`) | none | | A scoped key is active only for an application a scope gives an action | test | `a_scoped_key_is_active_only_where_it_does_something` | none | | 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 | @@ -1708,6 +1711,7 @@ plan needs no engine. A failure to start is logged, and the window manager runs | 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 | +| Entering a mode lets go of the keys of the mode it leaves and grabs its own, a bare key among them | test, of the calls; VM test | `entering_a_mode_lets_the_keys_of_the_other_go_and_grabs_its_own`, `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 diff --git a/docs/usage/running-komorebi.md b/docs/usage/running-komorebi.md index d2a33e8d..142fb149 100644 --- a/docs/usage/running-komorebi.md +++ b/docs/usage/running-komorebi.md @@ -81,6 +81,10 @@ komorebic hotkeys compile --mode auto komorebic start -- --keybindings-mode auto ``` +The daemon realizes the modes of an skhdrc (and the chains of an sxhkdrc that stay open) +itself: while a mode is active, only its keys are taken, and every other key reaches the +window as usual. The log says which mode the daemon is in after each change. + A daemon that is killed leaves its keys swallowed until it is started again; `komorebic stop` gives them back. diff --git a/komorebi/src/kwin/hotkeys.rs b/komorebi/src/kwin/hotkeys.rs index d457ee88..c05c3a59 100644 --- a/komorebi/src/kwin/hotkeys.rs +++ b/komorebi/src/kwin/hotkeys.rs @@ -26,6 +26,16 @@ //! for ([`command`]): `komorebic` with the words of a `komorebic` command, when they need no shell, //! and `sh -c` with anything else. //! +//! # Modes +//! +//! A mode is the engine's alone: entering one is a set of deactivations (the keys of the mode +//! left, which reach the focused window again) and activations (the keys of the mode entered), +//! carried out like any others, and the command the mode runs when it is entered. The daemon +//! logs the mode it is in after each change (`key bindings: the mode is now resize`). The keys +//! of a mode, a bare `H` or `Escape` among them, are swallowed only while the mode is the one +//! the engine is in. A start puts the engine in the default mode, whatever mode an earlier +//! komorebi was in. +//! //! # Start and stop //! //! kglobalaccel keeps an action, and the grab of its key, until it is unregistered: a komorebi @@ -523,6 +533,7 @@ async fn serve( let _ = started.send(Ok(())); loop { + let mode = engine.mode().to_string(); let effects = tokio::select! { Some(signal) = pressed.next() => { let (component, action, _): (String, String, i64) = signal.body().deserialize()?; @@ -555,6 +566,9 @@ async fn serve( else => return Ok(()), }; + if engine.mode() != mode { + tracing::info!("key bindings: the mode is now {}", engine.mode()); + } for effect in &effects { spawn(effect); } @@ -630,6 +644,49 @@ mod tests { ); } + #[test] + fn entering_a_mode_lets_the_keys_of_the_other_go_and_grabs_its_own() { + let keymap = keymap( + ":: resize : notify-send resize\nalt - r ; resize\nalt - h : echo h\n\ + resize < h : echo resize\nresize < escape ; default\n", + ); + let known = combos(&keymap); + let mut engine = Engine::new(keymap, EngineOptions::default()); + let mut registry = Registry::default(); + registry.startup(&[], &known, &engine.start()); + let now = Instant::now(); + + let effects = engine.on_pressed(known["Alt+R"], now); + + assert_eq!(engine.mode(), "resize"); + assert_eq!(effects[0], Effect::Shell("notify-send resize".into())); + let (h, escape) = (known["H"], known["Esc"]); + assert_eq!( + registry.calls(&effects), + [ + Call::Release(known["Alt+H"]), + Call::Release(known["Alt+R"]), + Call::Register(h), + Call::Grab(h), + Call::Register(escape), + Call::Grab(escape), + ] + ); + + // back in the default mode: registered once, so only grabbed again + let effects = engine.on_pressed(escape, now); + assert_eq!(engine.mode(), "default"); + assert_eq!( + registry.calls(&effects), + [ + Call::Release(h), + Call::Release(escape), + Call::Grab(known["Alt+H"]), + Call::Grab(known["Alt+R"]), + ] + ); + } + #[test] fn a_press_runs_the_command_and_changes_no_key() { let keymap = keymap("alt - h : komorebic retile\n"); diff --git a/nix/tests/vm/suites/keys-engine/default.nix b/nix/tests/vm/suites/keys-engine/default.nix index d15ad003..930a102f 100644 --- a/nix/tests/vm/suites/keys-engine/default.nix +++ b/nix/tests/vm/suites/keys-engine/default.nix @@ -3,10 +3,14 @@ kind = "session"; timeoutMinutes = 10; node = - { config, ... }: + { config, pkgs, ... }: { # the test starts, kills and stops its own daemon, with the key bindings it writes services.komorebi.enable = false; - environment.systemPackages = [ config.services.komorebi.package ]; + environment.systemPackages = [ + config.services.komorebi.package + # a window that prints the keys it gets + pkgs.wev + ]; }; } diff --git a/nix/tests/vm/suites/keys-engine/test.py b/nix/tests/vm/suites/keys-engine/test.py index 6244dee0..c373f550 100644 --- a/nix/tests/vm/suites/keys-engine/test.py +++ b/nix/tests/vm/suites/keys-engine/test.py @@ -78,4 +78,47 @@ checks.check( not kde.wait_for(lambda: ran("keys-engine-alt-j"), timeout=3), ) +# modes: entering one grabs its keys, a bare H among them, and lets the others go to the window +kde.spawn("stdbuf -oL wev", log="/tmp/wev.log") +if not kde.wait_for(lambda: kde.wid_by_class("wev") != "", timeout=30): + raise AssertionError("wev did not open") +kde.activate(kde.wid_by_class("wev")) + + +def typed(key: str) -> int: + """How many presses of `key` reached wev.""" + # wev prints a sym line after the press and after the release of a key + presses = f"grep -A1 'state: 1 (pressed)' /tmp/wev.log | grep -cE 'sym: {key} +\\('" + out = machine.execute(presses)[1].strip() + return int(out or "0") + + +def reaches_wev(key: str, presses: int) -> bool: + return kde.wait_for(lambda: typed(key) >= presses, timeout=5) + + +start( + ":: resize : touch /tmp/keys-modes-entered\n" + "alt - r ; resize\n" + "resize < h : touch /tmp/keys-modes-h\n" + "resize < escape ; default\n" +) +keys.send("h") +checks.check("in the default mode H reaches the focused window", reaches_wev("h", 1)) +checks.check("Alt+R enters the mode and runs its command", press("alt-r", "keys-modes-entered")) +checks.check( + "the daemon logs the mode it is in", + kde.wait_for(lambda: "the mode is now resize" in kde.komorebi_log()), +) +checks.check("in the mode H runs its binding", press("h", "keys-modes-h")) +checks.check("and does not reach the window", typed("h") == 1) +keys.send("esc") +checks.check( + "Escape goes back to the default mode", + kde.wait_for(lambda: "the mode is now default" in kde.komorebi_log()), +) +keys.send("h") +checks.check("back in the default mode H reaches the window again", reaches_wev("h", 2)) +kde.komorebic("stop") + checks.finish()