feat(kwin): wallpapers for monitors and workspaces

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.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:49 -07:00
1 parent e6ddb5a7c9
commit 2b116ea2a3
25 files changed
+1881 -135

No files matched your search

+6 -3
View File
@@ -41,8 +41,8 @@ These stay as they were when the file leaves them out: `default_workspace_paddin
`default_container_padding`, `display_index_preferences`, the four settings of the borders, each
color of `border_colours` the file does not name, the theme and the animation, when the file has no
`animation`. The rules add up, as
[Rules](#rules) says. A workspace the file lists gets its name, padding, offsets and rules from
its entry, and its layout when the entry names one; a workspace the file does not list is left as
[Rules](#rules) says. A workspace the file lists gets its name, padding, offsets, rules and
wallpaper from its entry, and its layout when the entry names one; a workspace the file does not list is left as
it is.
[`komorebic generate-static-config`](../cli/generate-static-config.md) prints the settings the
@@ -165,7 +165,9 @@ A monitor that has no preference takes the first entry nobody's preference names
other monitor has taken.
A monitor entry can also have a `floating_layer_behaviour`, which is the one its workspaces take
unless they have their own, and which comes before the one for every monitor.
unless they have their own, and which comes before the one for every monitor, and a `wallpaper`,
the picture the monitor shows while one of its workspaces is in front, unless that workspace has
one of its own ([Wallpapers](wallpapers.md)).
A monitor takes as many workspaces as its entry lists, and KWin gets a virtual desktop for each,
named for it. A workspace has these keys:
@@ -189,6 +191,7 @@ named for it. A workspace has these keys:
| `window_container_behaviour_rules` | none | `{ "2": "Append" }`: the behavior the workspace has once it has 2 containers or more |
| `float_override` | the default | Whether every window that opens on this workspace floats |
| `floating_layer_behaviour` | the default | What a window that opens while this workspace is on its floating layer gets: `Tile` or `Float` |
| `wallpaper` | none | The picture the monitor shows while this workspace is in front, instead of its monitor's: `{ "path": "~/Pictures/sea.png" }`, and `generate_theme` and `theme_options` for the borders' colors ([Wallpapers](wallpapers.md)) |
A workspace that names no `layout` and does not say `"tile": true` does not tile: its windows
stay where they open. A workspace with `layout_rules` tiles. Otherwise a workspace tiles.
+70
View File
@@ -0,0 +1,70 @@
# Wallpapers
A monitor, or a workspace of it, can have a wallpaper: the picture the monitor shows while that
workspace is in front. A workspace's own wallpaper is shown instead of its monitor's, and a
workspace that has none shows its monitor's. komorebi sets the wallpaper when a workspace comes
into view, however it comes: a [`komorebic`](../cli/focus-workspace.md) command, or a pager, a
shortcut, or an application raising a window of another workspace. It sets it when it starts too,
for the workspace that is in front. A monitor and a workspace with no wallpaper are left alone.
Plasma keeps one wallpaper for each screen, not for each virtual desktop, so komorebi changes the
screen's wallpaper as its workspace changes, as komorebi does on Windows and macOS.
## Setting wallpapers
The wallpapers are in `komorebi.json` ([Configuration](configuration.md)): a `wallpaper` in the
entry of a monitor and one in the entry of a workspace. The first entry of `monitors` is the first
monitor, and so on; the entries of `workspaces` are the workspaces of that monitor, in order. A
file that is read again, because it changed, shows the new wallpaper of the workspace in front at
once.
```json
{
"monitors": [
{
"wallpaper": { "path": "~/Pictures/dunes.png" },
"workspaces": [
{ "name": "code" },
{ "name": "chat",
"wallpaper": { "path": "~/Pictures/sea.png",
"theme_options": { "theme_variant": "Light", "single_border": "Base09" } } }
]
}
]
}
```
A `path` may start with `~` or have environment variables in it (`$HOME`), and may have spaces in
it. The picture fills the screen and is cropped where it does not fit. The monitor has the
`dunes.png` of the example, and the second workspace has `sea.png`.
A request for a wallpaper never holds up komorebi: switching workspaces does not wait for the
Plasma shell. The shell is asked what the screen shows before it is told anything, so a wallpaper
you changed by hand is put back when its workspace is shown again, and a wallpaper that is already
right is not touched.
## The colors of the borders
A wallpaper also gives the borders their colors, unless it says `"generate_theme": false`. The
palette of the picture, made by the generator komorebi for Windows uses, is a Base16 theme, so the
borders of a workspace with a warm picture are warm and those of a workspace with a cool picture
are cool ([Themes](themes.md) has what the six kinds of border take by default). They change with
the workspace, so the colors are right when the workspace comes into view.
`theme_options` choose the variant of the palette, `"theme_variant": "Dark"` (the default) or
`"Light"`, and which color of the palette each kind of border takes, `single_border`,
`stack_border`, `monocle_border`, `floating_border`, `unfocused_border` and
`unfocused_locked_border`, each one of `Base00` to `Base0F`. `bar_accent` is read and not used:
there is no komorebi bar here.
A palette takes seconds to make for a large picture, so each one is kept in
`$XDG_CACHE_HOME/komorebi` (`~/.cache/komorebi`), in a file named for the picture, a hash of its
path, size and time of last change, and the variant. A picture with fewer than eight colors has no
palette: its wallpaper is set, and the borders keep the colors they had.
## When the Plasma shell is not there
The shell is another process, and komorebi may start before it does. komorebi asks again for about
half a minute, with longer waits between the tries, and then says once, in its log, that it is
leaving wallpapers alone until the shell answers. A session with no Plasma shell has no wallpapers
to set, and nothing else in komorebi is affected.