Configuration
Every config key with its default
The config file is optional. Matuwall reads it once at startup:
$XDG_CONFIG_HOME/matuwall/config.toml
~/.config/matuwall/config.tomlGenerate a complete one with every default:
matuwall --no-config --print-config > ~/.config/matuwall/config.tomlEvery key is optional. An invalid value warns and uses the default. A syntax error ignores the whole file. There is no hot reload.
Starter Config
[general]
directory = "~/Pictures/Wallpapers"
backend = "awww"
[window]
preview = false
position = "bottom"
background = "#11111bcc"
[grid]
columns = 5
visible_rows = 1
carousel = true
[thumbnail]
width = 300
height = 169[general]
| Key | Default | Description |
|---|---|---|
directory | "~/Pictures/Wallpapers" | Wallpaper directory, or an array of up to 8 |
recursive | false | Also scan subdirectories. Hidden and symlinked ones are skipped |
list | "" | List file used instead of directory. "-" reads stdin |
favorites | "~/.config/matuwall/favorites.txt" | File the f key adds to |
backend | "awww" | awww, sweetbg, plasma, command or auto |
Several directories:
directory = ["~/Pictures/Wallpapers", "~/Pictures/Photography"][window]
| Key | Default | Description |
|---|---|---|
preview | false | Show the selected wallpaper full-screen behind the panel |
close_on_focus_loss | false | Close when keyboard focus leaves |
close_on_apply | true | Close after Enter applies |
position | "bottom" | center, left, right, top or bottom |
background | "#11111bff" | Panel color. "none" draws no panel |
margin | 34 | Padding between tiles and panel edge |
edge_margin | 24 | Gap between panel and monitor edge. Ignored at center |
radius | 40 | Panel corner radius |
Layer shell namespaces for compositor rules:
| Surface | Namespace |
|---|---|
| Panel | matuwall |
| Preview | matuwall-preview |
[grid]
| Key | Default | Range | Description |
|---|---|---|---|
columns | 5 | 1..1024 | Max columns. In carousel mode, max visible tiles |
visible_rows | 1 | 1..1024 | Max rows in the regular grid |
carousel | true | boolean | Centered single-axis strip |
edge | "auto" | auto, clip, peek, fade | Carousel tiles at panel edges |
sort | "name" | name, color | Wallpaper order |
spacing | 16 | 0..4096 | Gap between tiles |
radius | 20 | 0..4096 | Tile corner radius |
border_width | 0 | 0..4096 | Border width. 0 disables it |
shadow_width | 12 | 0..4096 | Shadow fade width. 0 disables it |
ring_width | 0 | 0..4096 | Selection ring width. 0 disables it |
Matuwall may show fewer columns or rows to fit the monitor.
Carousel
top, bottom and center use a horizontal strip. left and right use a vertical one.
edge | Behavior |
|---|---|
clip | Cut tiles at the panel margin |
peek | Let tiles extend into the margin |
fade | Shrink and fade tiles as they leave |
auto | fade when background is fully transparent, else clip |
Sort by Color
sort = "color" orders by dominant hue, red to pink. Grey and black-and-white images come last.
- Colors are learned in the background. The first launch shows name order
- New wallpapers stay at the end until the next launch
- Delete
~/.cache/matuwall/colorsto relearn every color
[thumbnail]
| Key | Default | Range | Description |
|---|---|---|---|
width | 300 | 1..16384 | Tile width in logical pixels |
height | 169 | 1..16384 | Tile height in logical pixels |
[colors]
Colors use #rrggbb, #rrggbbaa or none.
| Key | Default | Colors |
|---|---|---|
tile | "#313244ff" | Placeholder tile |
border | "#585b70ff" | Thumbnail border |
shadow | "#00000066" | Thumbnail shadow |
ring | "#f2cdcdff" | Selection ring |
spinner | "#cdd0e6ff" | Loading dot |
[animation]
| Key | Default | Range | Description |
|---|---|---|---|
navigation_ms | 410 | 0..1000 | Navigation transition. 0 disables it |
zoom_percent | 10 | 0..10 | Selected tile growth. 0 disables it |
[input]
| Key | Default | Description |
|---|---|---|
mouse | false | Hover selects, wheel moves, left click applies |
[backend.*]
| Section | Key | Default | Description |
|---|---|---|---|
[backend.awww] | args | [] | Extra flags for awww |
[backend.sweetbg] | args | [] | Extra flags for sweetbg |
[backend.plasma] | args | [] | Extra flags for Plasma |
[backend.command] | apply | "" | Custom setter command |
See Backends.
[hooks]
| Key | Default | Description |
|---|---|---|
on_apply | [] | Commands run after a successful apply, up to 16 |
See Hooks.