feat(wm): ignore, manage and float rules

komorebi managed every normal window that is alive, and there was no way to keep
an application out of the layout. The rule engine decides whether a window is
managed: an ignore rule keeps the windows it matches out, unless a manage rule
matches them too, and a float rule puts a window in the floating windows of its
workspace when it opens. A rule matches a window by its title, its executable,
its class or the path of its executable. Plasma's shell and KRunner are ignored
from the start.

`komorebic ignore-rule` and `manage-rule` add a rule, `session-float-rule`
floats the focused window and the windows like it until the daemon stops,
`clear-session-float-rules` removes those rules, and `global-state` shows the
rules. The `DebugWindow` message says why a window is managed or not.

Applications often open a window before they give it its title, so the bridge
now reports a title change, and a window komorebi does not have is asked about
again when its title changes, for a rule on the title to decide.

The vm-commands sweep adds and shows rules, and a section of its own checks that
a window an ignore rule matches by its first title is tiled once it has another.
vm-kwin-events checks that a window giving itself another title reaches the
daemon as a title update.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:37 -07:00
1 parent c95be9391e
commit 1b10611022
32 files changed
+1755 -57

No files matched your search

+10
View File
@@ -0,0 +1,10 @@
```text
Clear all session float rules
Usage: clear-session-float-rules
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```text
Show a JSON representation of the current global state
Usage: global-state
Options:
-h, --help
Print help
```
+21
View File
@@ -0,0 +1,21 @@
```text
Add a rule to ignore the specified application
Usage: ignore-rule <IDENTIFIER> <ID>
Arguments:
<IDENTIFIER>
Possible values:
- exe: Executable name
- class: Role or subrole
- title: Window title
- path: Executable path
<ID>
Identifier as a string
Options:
-h, --help
Print help (see a summary with '-h')
```
+21
View File
@@ -0,0 +1,21 @@
```text
Add a rule to always manage the specified application
Usage: manage-rule <IDENTIFIER> <ID>
Arguments:
<IDENTIFIER>
Possible values:
- exe: Executable name
- class: Role or subrole
- title: Window title
- path: Executable path
<ID>
Identifier as a string
Options:
-h, --help
Print help (see a summary with '-h')
```
+10
View File
@@ -0,0 +1,10 @@
```text
Add a rule to float the foreground window for the rest of this session
Usage: session-float-rule
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```text
Show all session float rules
Usage: session-float-rules
Options:
-h, --help
Print help
```
+38 -10
View File
@@ -29,6 +29,9 @@ its place here.
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`]).
- **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).
- **Direction**: where an order goes from the focused container: a side of its tile
([`OperationDirection`]), or the next or the previous container of the workspace
([`CycleDirection`]).
@@ -108,9 +111,9 @@ 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 and not minimized, 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, 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.
## The KWin backend
@@ -324,9 +327,25 @@ area, and its id goes into a list of unmanaged windows that `handle_event` check
on any other event about a window; a `Manage` takes the id out of the list and is handled like a
`Show`. A `Destroy` takes the id out of the list too.
Whether a window is managed is [`Window::should_manage`]: the window has to be alive and normal,
and then the rules decide ([`should_act`]). An ignore rule that matches keeps the window out
unless a manage rule matches it too. The float rules do not decide whether a window is managed,
but a `Show` puts a window one matches in the workspace's floating windows instead of a container
(a `Manage` does not ask them). The rules live in process-wide lists in `lib.rs`:
`IgnoreRule` and `ManageRule` add a rule that names an application by one of the four
([`ApplicationIdentifier`]), and take the windows that it names exactly out of the containers of
the workspaces in front; `SessionFloatRule` adds a float rule made of the focused window's
executable, title and class, all three to be equal, and floats it, and `ClearSessionFloatRules`
takes those rules out again. `GlobalState` answers with the ignore and the manage rules
([`GlobalState`]), and `DebugWindow` with what [`Window::should_manage`] read of a window and
which rules matched ([`RuleDebug`]). A rule decides when a window is shown; the bridge reports
a title change (`caption`), which is a `TitleUpdate` event, and a `TitleUpdate` about a window
the index does not have, and that is not minimized, is sent again as a `Show`, so that a rule
about the title it has now decides.
`TogglePause` sets [`WindowManager::is_paused`]: while it is set, `handle_event` returns at once
for every event, and [`read_commands_uds`] hands only `TogglePause`, `State` and `Stop` to the
window manager. `UnmanagedWindowOperationBehaviour` sets
for every event, and [`read_commands_uds`] hands only `TogglePause`, `State`, `GlobalState` and
`Stop` to the window manager. `UnmanagedWindowOperationBehaviour` sets
[`WindowManager::unmanaged_window_operation_behaviour`]: with `NoOp`,
[`WindowManager::process_command`] refuses every message while the window the compositor has
focused is in no container of the focused workspace
@@ -402,7 +421,7 @@ module's unit.
holding one the same accessors (`containers()`, `focused_container_mut()`, ...).
- [`monitor`](../../komorebi/src/monitor.rs), [`workspace`](../../komorebi/src/workspace.rs),
[`container`](../../komorebi/src/container.rs), [`window`](../../komorebi/src/window.rs):
the four levels of the tree.
the four levels of the tree; `window` also has the rule engine ([`should_act`]).
- [`lockable_sequence`](../../komorebi/src/lockable_sequence.rs): inserting, removing and
swapping in a list where some elements are locked in place, which is how a workspace
changes its containers.
@@ -475,9 +494,9 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
| A test's backend does not outlive the test | framework path: [`with_backend`] restores the previous one on drop | `with_backend_puts_the_previous_backend_back_when_the_closure_panics` | none |
| A command about a missing window is an error, not a panic | test | `a_command_about_a_window_nobody_opened_is_an_error` and `a_command_about_a_closed_window_is_an_error` against the fake, `a_command_about_a_window_the_table_does_not_know_is_an_error_and_sends_nothing` against the KWin backend | none |
| A locked container keeps its index | framework path: a [`Workspace`] inserts, removes and swaps its containers through `LockableSequence` | `test_locked_containers_with_new_window`, `test_locked_containers_remove_window`, `a_window_that_opens_does_not_push_a_locked_container_from_its_index` | `containers_mut()` is the `VecDeque` itself |
| A window komorebi does not manage is never moved | framework path: `handle_event` asks [`Window::should_manage`] before it acts on any event but a destroy | `dialogs_and_other_non_normal_windows_are_left_alone` | none |
| A window komorebi does not manage is never moved | framework path: `handle_event` asks [`Window::should_manage`] before it acts on any event but a destroy | `dialogs_and_other_non_normal_windows_are_left_alone`, `an_ignore_rule_keeps_a_window_unmanaged` | `ManageRule` |
| A window the user unmanaged stays out of the layout until it is managed again | framework path: `handle_event` checks the list of unmanaged windows before it acts on any event but a removal | `unmanage_takes_the_focused_window_out_until_manage_takes_it_back` | none |
| A paused window manager moves no window | framework path: `handle_event` returns before anything else, and [`read_commands_uds`] drops every message but `TogglePause`, `State` and `Stop` | `while_paused_no_event_changes_the_layout_and_manage_takes_in_a_window_it_missed`, `while_paused_only_toggle_pause_state_and_stop_are_handled` | none |
| A paused window manager moves no window | framework path: `handle_event` returns before anything else, and [`read_commands_uds`] drops every message but `TogglePause`, `State`, `GlobalState` and `Stop` | `while_paused_no_event_changes_the_layout_and_manage_takes_in_a_window_it_missed`, `while_paused_only_toggle_pause_state_and_stop_are_handled` | none |
| A destroyed window leaves whichever workspace has it | framework path: the destroy is looked up in the index of managed windows, which is rebuilt at startup and before and after every event | `a_window_that_was_open_before_komorebi_started_is_removed_when_it_closes` | none |
| The daemon does not start without KWin, unless it is told to run against the fake | startup check: [`connect`] fails, and the daemon exits with the error, code 1 | `without_a_session_bus_komorebi_exits_with_an_error_naming_it` | `--fake-backend` |
| One komorebi per session | startup check: the session bus gives `org.komorebi.Bridge` to one connection | none | none |
@@ -525,7 +544,9 @@ A window is shown, and ends up on a tile:
[`WindowManager::process_event`], which hands it to `handle_event` and logs how long that
took. The end-to-end tests build the event themselves and call `process_event`.
2. `handle_event` asks [`Window::should_manage`], which asks the backend's `window(id)`
whether the window is alive and normal. If it is not, the event changes nothing.
whether the window is alive and normal, and then the rules whether it is to be managed. If
it is not, the event changes nothing. If a float rule matches it, it goes into the
workspace's floating windows and the steps below do not apply.
3. The index of managed windows is rebuilt from the containers. If the workspace in front
already has the window, or the index has it on another monitor or workspace, the event
creates nothing.
@@ -620,7 +641,9 @@ A window is shown, and ends up on a tile:
[`komorebi/tests/manage.rs`](../../komorebi/tests/manage.rs), minimizing, closing,
unmanaging and managing the focused window, and pausing;
[`komorebi/tests/padding.rs`](../../komorebi/tests/padding.rs), the paddings and the work area
offsets.
offsets; [`komorebi/tests/rules.rs`](../../komorebi/tests/rules.rs) and
[`komorebi/tests/rule_commands.rs`](../../komorebi/tests/rule_commands.rs), the rules and the
messages that add and show them.
- [`nix/tests/vm/suites/scrolling`](../../nix/tests/vm/suites/scrolling/test.py): the scrolling
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,
@@ -645,6 +668,11 @@ A window is shown, and ends up on a tile:
[`Container`]: ../../komorebi/src/container.rs
[`Window`]: ../../komorebi/src/window.rs
[`Window::should_manage`]: ../../komorebi/src/window.rs
[`should_act`]: ../../komorebi/src/window.rs
[`RuleDebug`]: ../../komorebi/src/window.rs
[`GlobalState`]: ../../komorebi/src/state.rs
[`MatchingRule`]: ../../komorebi/src/core/config_generation.rs
[`ApplicationIdentifier`]: ../../komorebi/src/core/mod.rs
[`Window::set_position`]: ../../komorebi/src/window.rs
[`Workspace::new_container_for_window`]: ../../komorebi/src/workspace.rs
[`WindowManager`]: ../../komorebi/src/window_manager.rs
+2
View File
@@ -41,6 +41,8 @@ daemon, ask it what it is doing and read its log.
window and pause the daemon, and
[Padding and work area offsets](usage/padding-and-offsets.md) how to put gaps around the tiles
and keep parts of a monitor free of them.
[Rules](usage/rules.md) explains how to keep an application out of the layout, always tile it, or
float its windows.
[Subscribing to notifications](usage/subscribing-to-notifications.md) explains how a program
such as a status bar follows what komorebi does. The [CLI reference](cli/start.md) has a page
for every `komorebic` command, generated from its help.
+5 -4
View File
@@ -1,7 +1,8 @@
# Managing windows
komorebi tiles every normal application window that KWin reports, and leaves dialogs, splash
screens and other windows that are not for tiling alone. The commands here act on the window
screens and other windows that are not for tiling alone, and the windows that [rules](rules.md)
say to ignore. The commands here act on the window
that has the focus in KWin, take a window out of the layout or back into it, and pause the
daemon.
@@ -34,7 +35,7 @@ komorebic manage
```
`komorebic manage` also takes in a window komorebi missed, such as one that opened while the
daemon was paused. The daemon forgets an unmanaged window when it closes, and when the daemon
daemon was paused, but not a window an ignore rule covers. The daemon forgets an unmanaged window when it closes, and when the daemon
stops.
## Commands while the focused window is not tiled
@@ -58,8 +59,8 @@ sets the behavior back to `op`: give the focus to a tiled window first.
[`komorebic toggle-pause`](../cli/toggle-pause.md) pauses the daemon, and the same command
resumes it. While it is paused, komorebi does not act on what KWin reports, so it moves no
window, and of its commands it carries out only `toggle-pause`, `state` and `stop`. The daemon's
state says whether it is paused, as `is_paused`.
window, and of its commands it carries out only `toggle-pause`, `state`, `global-state` and
`stop`. The daemon's state says whether it is paused, as `is_paused`.
```sh
komorebic toggle-pause
+71
View File
@@ -0,0 +1,71 @@
# Rules
A rule names an application by one of four things about its windows, and says what komorebi does
with them:
- `exe`: the name of the program's executable, such as `kate`;
- `class`: the app id of a Wayland window, such as `org.kde.kate`, or the class of an X11 window;
- `title`: the title of the window;
- `path`: the full path of the executable, such as `/usr/bin/kate`.
[`komorebic state`](../cli/state.md) shows them for every window komorebi has, as the `title`,
`exe`, `class` and `path` of its `details`.
## Ignoring an application
[`komorebic ignore-rule`](../cli/ignore-rule.md) makes komorebi leave the windows of an
application alone. A rule given this way matches a title or a class that starts or ends with what
it names, and an executable or a path that is exactly what it names. The windows it matches are
not tiled when they open, and the tiled windows of the workspaces in front whose executable,
class, title or path is exactly what it names leave the layout.
```sh
komorebic ignore-rule exe steam
komorebic ignore-rule class org.kde.kcalc
komorebic ignore-rule title "Picture-in-Picture"
```
`komorebic float-rule` is the same command. Plasma's desktop and panels (`plasmashell`) and
KRunner are ignored from the start.
[`komorebic manage-rule`](../cli/manage-rule.md) makes komorebi tile the windows of an
application that an ignore rule covers, from the next one that opens.
```sh
komorebic manage-rule class org.kde.plasmashell
```
[`komorebic manage`](managing-windows.md#taking-a-window-out-of-the-layout) does not take in a
window an ignore rule covers: a manage rule does.
## When a rule decides
A rule decides when a window opens. Applications often open a window before they give it its
title, so the title a rule sees then can be a placeholder. When the title of a window komorebi
does not have changes, komorebi asks the rules again, so a window that a title rule ignored while
it had its first title is tiled once its title no longer matches. A window komorebi tiles stays
tiled whatever its title becomes.
## Floating the windows of an application
[`komorebic session-float-rule`](../cli/session-float-rule.md) takes the focused window out of
the layout into the floating windows of its workspace, and adds a rule that floats every window
that opens with the same executable, class and title.
[`komorebic session-float-rules`](../cli/session-float-rules.md) shows those rules, and
[`komorebic clear-session-float-rules`](../cli/clear-session-float-rules.md) removes them: the
windows that float already stay floating.
```sh
komorebic session-float-rule
komorebic session-float-rules
komorebic clear-session-float-rules
```
A window that a float rule matches floats when it opens, and
[`komorebic toggle-float`](floating-windows.md) puts one in the layout.
## How long rules last
The rules given with these commands last until the daemon stops.
[`komorebic global-state`](../cli/global-state.md) shows the ignore and the manage rules the daemon
has, and its data directory.