A key komorebi does not read is dropped without a word, so a typo in
komorebi.json costs a restart and a look at the log to find. A file that is not
JSON, or has a value of the wrong kind, is not read at all, and the daemon says
so only in its log. `komorebic check` reads the file the way the daemon does,
without starting it, and says in words what is wrong, with the line when it is
the file.
The check parses the file as JSON, then as a StaticConfig; the first that fails
is an error that shows the line serde stopped at, with the two before it and a
caret. The keys come from the schema of StaticConfig at every level, so the
check knows every key komorebi reads: a key only another platform reads is
listed once as accepted and ignored, because one komorebi.json serves every
platform; a key nobody has is a warning with the nearest key that exists.
Windows' custom layouts are a warning that they are not supported yet, an
applications file that is not there is a warning, and so is a workspace that is
only a name, which komorebi does not tile. A workspace that has
initial_window_placement_rules and appends windows to a container, by its own
window_container_behaviour or the file's, gets a note: an appended window has no
place of its own to be given.
komorebic exits with status 1 if and only if a finding is an error. The usage
page says what each finding means.
A wallpaper that is not a file is an error, and one no theme can be made from is
a warning. check_configuration also returns what the file asks of the desktop
(Wants): whether it draws borders, which animation style it asks for, and
whether it has wallpapers.
The checks of the desktop and of the key bindings come with those features.
A window that opens goes after the focused container. A workspace can now say
another place for its windows: the primary or the secondary tile, before or
after the focused container, the end of the list, or a place by number, counting
from 1. The place is for every window, or for the windows that match a rule on
their program, app id, title or path; the rules are the conditions the ignore
and manage rules are made of, and the first that matches in key order decides. A
place that does not exist, such as the secondary tile of a workspace with one
container, is the default place.
A place is read from a name, a number or text that is a number. The
documentation of the setting shows a number and a map's keys can only be text,
and komorebi for Windows (83c4e11d) reads only text, so the form its own page
shows is refused there.
A place that was reserved with preselect-direction is used before the rules are
asked, and a locked container keeps its index. A workspace whose
window_container_behaviour is Append puts a window in the focused container, and
the rules are not used.
A workspace takes the rules from the key initial_window_placement_rules of its
entry in komorebi.json. The key is in schema.json and so in the typed config
option of the module, and the page docs/initial-window-placement-rules.md says
how to write it. vm-placement opens windows in a headless KWin and checks where
they go, by program, app id and title.
The schema that schemars derives for a place is an object with a Placement or an
Index key, which is not what is read or written, so a check against it refuses a
file that the daemon reads. The schema of PlacementTarget is written by hand
instead: a name, a number, or text that is a number. A file with a place of each
form is checked against schema.json, and the module's config option takes them.
Plasma keeps one wallpaper for each screen, not for each virtual desktop, so a
workspace that wants a picture of its own has nowhere to keep it in the shell.
komorebi sets the wallpaper of a screen when a workspace comes into view: the
workspace's own, else its monitor's. It does so however the workspace came into
view (a komorebic command, a pager, an application raising a window) and for the
workspace in front when it starts. A monitor and a workspace with no wallpaper
are left alone.
The Plasma shell sets it over D-Bus, with the call plasma-apply-wallpaperimage
makes, but for one screen. Backend::set_wallpaper asks for it every time a
workspace comes into view, and the KWin backend asks the shell what the screen
shows first, so a picture the user changed by hand is put back and one that is
already right is not touched. The request runs in the background, so switching
workspaces never waits for the shell, and goes on trying for about half a minute
when the shell is not up yet.
A wallpaper also gives the borders the colors of the palette made from its
picture, unless it says generate_theme is false, and theme_options choose the
variant and the color each border takes. The colors change before the workspace
is shown, so its borders are right at once.
komorebi.json takes the wallpaper of a monitor and the wallpaper of a workspace,
and a file that is read again shows the wallpaper of the workspace each monitor
has in front at once. vm-wallpaper runs against the real shell: set at start and
by workspace, a switch komorebi did not make, the colors of the borders, a
wallpaper changed by hand, the palette cache, and komorebi that starts before
the shell.
A theme gives the borders their colors, in place of choosing the color of each
kind of window: a Catppuccin theme, a Base16 theme or a palette of one's own,
with the color it gives each of the six kinds of border and its default for the
ones it does not name. The Theme message puts the six colors where the border
manager keeps them and asks for the look again. The palette of a picture is made
by the same generator as komorebi for Windows, which takes seconds for a large
picture, so each one is kept in the cache directory, in a file named for the
picture, a hash of its path, size and time of last change, and the variant: the
palette of a picture painted over, or of one of the same name in another folder,
is made again and not mistaken.
The themes come from komorebi-themes at the revision komorebi-layouts is at. It
pulls egui for its types, which the license list, the sources and the advisories
of deny.toml now have to allow, and the colors the border manager keeps are the
themes' own again.
A subscriber that asks for the changes of the state only is sent a Theme message
all the same: the colors of the borders are not part of the state, so a theme
never changes it, and the subscriber would not hear of the colors at all.
komorebi.json takes border_colours, a color for each kind of window as red,
green and blue or as a hex color, and a theme, which wins over them.
KWin has a focus policy that gives the focus to the window under the pointer, so
komorebi asks for it and follows where the focus goes, as it does for any change
of focus. Both implementations komorebi for Windows names are the same thing
here. The KWin backend sets the focus policy and no delay in the user's kwinrc
and has KWin read it, and puts the two keys back as the user had them when it is
turned off and, with every other setting, when komorebi exits. The state of the
daemon says whether it is on.
komorebic gets focus-follows-mouse and toggle-focus-follows-mouse. The session
node gets a pointer that a test drives from inside the guest: the program
komorebi-pointer makes an absolute device with uinput, and komorebi_vm.Pointer
sends it commands. vm-focus-follows-mouse moves it over each of two windows and
checks the focus, then the policy that is put back.
komorebi.json takes focus_follows_mouse, which is on with Windows or Komorebi,
and a file that leaves it out turns it off and gives the user's focus policy
back.
Loading a configuration asks the backend for the focus policy now, so the tests
that load one do it with a backend installed.
The window in front of every container is see-through, unless its container has
the focus on the focused monitor, so that the window being worked in stands out.
The opacity of a window is a property KWin has: komorebi sets it through the
bridge, as a fraction of 255, and KWin draws the window so. The window manager
keeps the opacity it gave each window and, after every event and message, sends
only the difference, makes a window opaque again when it should no longer be
see-through, and makes every one opaque when it stops. Windows an ignore rule
covers, and workspaces that do not tile, are left as they are.
The patched border effect already draws a window again when its opacity changes,
so the border follows it. komorebic gets transparency, transparency-alpha and
toggle-transparency, and the state of the daemon says what the settings are.
vm-features checks the pixels in the middle of a focused window and of one that
is not.
A monocled window is opaque on the focused monitor and see-through on another.
komorebi.json takes transparency, transparency_alpha and
transparency_ignore_rules.
An animation that moves a window at one pace all the way looks flat, and the
stock Geometry Change has one curve, an exponential ease out. The patched effect
reads a Curve setting, the name of one of Qt's easing curves. komorebi's styles
are those curves with Ease in front, so the look the backend is asked for names
the curve as Qt does, and the effect's settings have it next to the duration. A
cubic Bezier, which only a configuration can say, is not one of Qt's curves and
is an ease out. With the stock effect every style is that ease out.
komorebic gets animation-style, for every animation or the movement of windows
alone. vm-features puts two curves a few seconds into a 30 s move of the same
window and checks that they are in different places.
The animation key of komorebi.json takes a style too, for every kind of
animation or for one.
Windows that jump to their new places are hard to follow. komorebi animates
nothing itself: KWin's Geometry Change effect animates a window that a script
moves, and komorebi tells it how long that takes. The look the window manager
asks the backend for now has an animation, a duration that the settings give for
every kind of animation or, when one is set for the movement of windows, for
that one. The KWin backend writes the effect's settings into the user's kwinrc
(a duration, and no cross-fading, since a window going to its place changes
where it is and not what it shows), loads the effect when animation is on, and
unloads it and puts the settings back when it is off or komorebi exits.
komorebic gets animation, animation-duration and animation-fps. The module
installs the effect (effects.animation), and the session node sets the variable
that makes KWin load effects that animate under software rendering. vm-look
reads the screen a moment after a flip of the layout, with a 30 s animation and
without one.
The commands that change a stack turn the animation off while they run, as
komorebi does elsewhere, and komorebi.json takes an animation key (enabled,
duration and fps, each for every kind of animation or for one).
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.
A workspace rule sends the windows of an application to a workspace: an initial
rule once, when komorebi first sees the window, and a permanent rule every time,
so that a window the user takes away goes back. A rule is a rule on the window's
executable, class, title or path, with a monitor and a workspace index, or the
name of a workspace. It comes from komorebi.json (workspace_rules and
initial_workspace_rules of a workspace, made again from the file each time it is
read) or from komorebic (workspace-rule, initial-workspace-rule, their named
forms, and the commands that clear and enforce them).
The window manager looks at the rules before it handles each event about a
window it manages, and again when the configuration is loaded, so the windows
that were open when the daemon started are sent too. A window that leaves the
workspace in front is taken out of the layout and hidden, as the back of a stack
is, and it is put on the desktop of its new workspace, which is what it comes
back to and is tiled on when that workspace is shown. A window that moves
between workspaces that are not in front is put on the desktop of its new
workspace as well. A floating window that goes to another monitor is moved onto
it, and a workspace that does not exist yet is made.
komorebi.json is described as a JSON Schema, made from the Rust types that read
it: komorebic prints the schema of komorebi.json, of an applications.json, of a
notification and of a message, and the daemon answers the same four questions on
its socket. schema.json and schema.asc.json are committed (just jsonschema).
The module's config option is typed from the schema: schemars-nixgen makes
nix/komorebi-options.nix from schema.json (just nixgen), so a layout komorebi
does not have, or a value of the wrong kind, does not evaluate. The module
writes config as a komorebi.json and gives it to the daemon with --config.
configFile and the file the module writes are checked against the schema when
the system is built. applicationSpecificConfiguration takes files from GitHub,
and there are none by default, since no community file for Plasma is known.
Two checks keep the generated files honest without the tools that make them.
schema-fresh compares the schemas with what komorebic prints, and the hash on
the first line of the options with the schema. nix-options-validation evaluates
the options against the example configuration, written in Nix and in JSON.
nixos-module-eval also evaluates the module with the sources turned off: with
applicationSpecificConfiguration.enable = false the sources are left out of the
config that is written, and with no config either there is nothing to write and
the unit passes no --config. ARCHITECTURE has the guarantee row that names the
two checks.
Rules for particular applications can be kept in files of their own,
applications.json, which komorebi.json names with
app_specific_configuration_path: one path or a list. The ignore, manage and
floating rules of every application in a file are added to the lists the
configuration's own rules go in, so a file can be shared or kept apart from the
settings.
A path with no file behind it is skipped with a warning, since one komorebi.json
is meant to work on every platform and may name a file that only another
platform has; a file that is there and is not an applications.json is an error.
The titleless and tabbed rules of other platforms are read and do nothing.
komorebic/applications.json is a start for Plasma: it floats the calculators,
the screenshot tool, the authentication dialog and System Settings. A test opens
the windows it names.
The daemon takes its settings from a komorebi.json: the file --config names, or
the one in the config home ($KOMOREBI_CONFIG_HOME, else ~/.config/komorebi).
Without a file it runs on its defaults, as before.
StaticConfig reads the file in three steps, because the monitors are known only
after the backend has been asked. preload makes the window manager and applies
the settings that are process-wide, postload gives each monitor and workspace
the entry of its place (by the index display_index_preferences gives a monitor's
serial number id, else in order), and main asks KWin for a desktop for each
workspace the file lists. A watcher on the file sends the daemon a
ReloadStaticConfiguration about two seconds after it changes, whether an editor
wrote the file in place or renamed a new one over it, and a file that does not
parse changes nothing.
A workspace can change its layout, its work area offset and its layout options
with the number of its containers, from the file or with komorebic
(workspace-layout-rule, its named form and the two that clear), and
layout_defaults gives every workspace of a layout the options it sets none of.
One file is meant to serve every platform, so a key that does nothing on Plasma
is accepted and ignored. config_parity checks the example and the files of other
platforms; the keys of features that are not in yet are listed there, and the
test fails when a list names a key that is read.
The file also sets what the stacks, the float override, the floating layer and
monocle set while the daemon runs: window_container_behaviour, with its rules by
container count in a workspace, float_override, float_override_placement,
floating_layer_behaviour (for a monitor and a workspace too),
floating_layer_placement and monocle_focus_behaviour. Their features come before
this commit, but a file to put the keys in does not, so they are part of this
one.
komorebic gains configuration, generate-static-config and start --config. The
NixOS module gets configFile, which the unit gives the daemon as --config.
LGUG2Z