Solium

Solium is the Wayland compositor of Lilium DE, written in Rust on Smithay and configured in Lua. Its window frames, its wallpaper and the desktop shell it hosts are QML running inside the compositor, in one engine, so the desktop can be one design that you change without rebuilding anything.

Captured by the compositor reading back its own framebuffer, in a nested session with the shipped configuration and nothing else, under the light theme Solium shipped until 2026-10-04 and not retaken yet: the shipped theme is now dark grey. The window on the left wears the default frame, a QML scene rendered in-process; the one on the right asked to draw its own and was let. The wallpaper is a QML file too. docs/modes.md has every mode, frame by frame.

Status

Alpha, and not yet anyone’s daily desktop. The first release, v0.1.0, will be a preview release, and it is not cut until the desktop is daily-drivable (the daily-drive label), the native preview shell is written (a bar at the bottom, a dock at the top, quick search, desktop icons, widgets with real data and a native lock screen), and there are packages: the point where it is ready for an open beta. docs/beta.md is that road. It is being readied for daily use, and the daily-driving trial that decides whether it is ready has not happened yet. What stands in the way is the daily-drive label, and the honest reasons are specific:

• A hosted shell is not yet a whole desktop (#169): it has no icons yet, and the preview shell itself is not written.
• Suspend and resume have never been tested (#64), and a session on the hardware sometimes starts with no input devices and stops itself (#48).
• Nothing has run unattended for hours on the hardware (#65).
• There is no explicit sync, so Vulkan and NVIDIA clients can stutter (#59).
• There are no touchpad settings, so no tap-to-click (#157); no volume, brightness, media or screenshot keys by default (#151); and logind’s lock and sleep requests are ignored (#153).
• There are no packages in a repository: a Fedora 44 package, or an install, is built from a checkout (#66).
• Two tiling bugs found in use are fixed, and stay open until real use bears that out: a window drawing past its tile over its neighbours (#133), and a closing window keeping its tile until its client had gone (#128).

Short of that trial, it has been checked on the hardware at commit dfc95ce, on a desktop with an NVIDIA RTX 3070 and on a Microsoft Surface Pro 7 (Intel Ice Lake integrated graphics), both on Fedora 44. On both, QML renders on the GPU and its animations run, the screens go off when idle, swaylock locks, and the Caps Lock and layout pill works with the shipped configuration. On the Surface Pro 7, closing the lid turned the screen off, though Solium has no lid handling of its own. Touch reaches applications’ windows, but nothing Solium draws itself reacts to touch yet (#181).

And a bug in a compositor takes the session with it. The ones that get found are the ones real use finds, which is why the trial matters more than the test suite.

What works today

• Layouts. Dwindle tiling, scrolling, floating and overview, each running per monitor, with a workspace per monitor or one for the whole desk. A minimum tile, with a new window overflowing to the next empty workspace (#134); applications’ own minimum and maximum sizes (#115); focus and move by direction, and floating and fullscreen toggles (#150); and a reload that keeps every layout as it was (#116, #118).
• Windows. A window exists from the keypress that launches it, and shows a loading window until its application has drawn; an X11 application’s window does not yet replace its loading window (#180). Relaunching a single-instance application that is already running brings its existing window forward where it is, instead of moving it into a new slot (#177). Closing and quitting fade out (#126, #127); a resize follows the drag (#113); a modal dialog floats over its parent (#72); a drag shows its icon (#57); and one stacking order serves drawing and clicks, with a fullscreen window covering the bars (#141, #142) and getting its place back after (#92). X11 clients work through XWayland, and menus and tooltips are placed, grabbed and kept on screen.
• Chrome. Eleven pane styles and per-corner rounding, QML on the GPU by default with a software fallback (#147), and cursor themes and the shapes clients ask for (#81, #24).
• Shells. shell = { scene = … } hosts one in the compositor’s own QML engine, one instance on every monitor (or on the one shell = { on = … } names), each reading its own monitor live as Solium.monitor (#161). It takes the pointer only where its items take input, so the windows under it can still be clicked (#173). It gets every mouse button, the wheel and the modifiers, a popup holds the pointer with Grab, and an item that asks with Solium.keyboard gets the keyboard (#163). A bar reserves its edge, whatever the scene’s size, with reserve on sol.surface or Solium.surface.reserve from QML (#162). Any layer-shell client works too; bars and lockers both get the frame callbacks they rely on (#149), and a hosted scene’s timers fire on an idle desktop (#164).
• Monitors. Several at once, each at its own refresh rate, arranged from the configuration or guessed; plugged in and unplugged while the session runs (#43); scaled, worked out from the panel or set. Screens go dark after ten minutes with nobody at the machine, and wlopm and swayidle can turn them off too (#54); the ten-minute screen-off has been seen working on both machines named above.
• Input. Keyboard layouts, with bindings that keep working under a non-Latin one (#132) and on shifted keys (#121). Escape reaches applications: the overview binds it only while it is open (#174). A small pill near the text field’s caret says Caps Lock is on, or which layout you just switched to; it is written in Lua and QML as configuration rather than in the compositor, and set with keyboard.indicator (#178). On touch screens, touch reaches applications’ windows and a tap focuses the window under it, but nothing Solium draws itself answers touch yet (#181).
• The lock and idle. The lock fails safe: the session is locked before the locker has drawn, and stays locked if the locker crashes. An idle inhibitor counts only while its window is on screen, and a browser’s D-Bus inhibitor holds the screens on too (#152).
• The session. Started from the login screen, Solium tells systemd and D-Bus where its display is and starts graphical-session.target and XDG autostart, and stops them when it ends (#146). Programs Solium starts get the environment Solium itself was started with, not the settings Qt has written into it since, and inherit no descriptor beyond stdio (#175).
• Protocols. xdg-shell, xdg-decoration, xdg-output, xdg-activation, xdg-dialog, wlr-layer-shell, wlr-screencopy, wlr-output-power-management, ext-session-lock, ext-idle-notify, idle-inhibit, cursor-shape, wp-viewporter, wp-fractional-scale, wp-presentation, wp-single-pixel-buffer, linux-dmabuf, relative-pointer, pointer-constraints, primary-selection, text-input-v3 and xwayland-shell. Both selections, copy and paste, cross the X11 boundary. text-input-v3 tells the compositor where the focused text field’s caret is; with no input method yet, no text is sent back (#26).

Not yet

No input method, so no IME and no on-screen keyboard (#26); no clipboard manager, which wants data-control (#52); no window rules (#56); no night light (#69); a virtual machine or a remote desktop cannot have Super (#58); and portal dialogs cannot be parented to the window that opened them (#67). Screenshots and recording come from wlr-screencopy, so grim and wf-recorder should work, but the portals, screen sharing included, have never been tested end to end (#83). Nothing the compositor draws reacts to touch yet (frame buttons, a hosted shell, the overview, window edges), though touch reaches applications’ windows (#181); touch gestures are the touch epic (#7) and come after v0.1.0. docs/gaps.md is everything not built yet, at length.

A first configuration

Everything is a file you write, and none of it needs the compositor rebuilt. ~/.config/solium/user.lua holds only what you want changed, and is merged over the defaults:

return {
    pane = "left",
}

Press super+shift+r and every open window is framed again, with its titlebar down the left side. solium --check says, without starting anything, whether the configuration would load, which bindings it made, which settings it sets that nothing reads, with what you probably meant, and whether every scene it declares at load and every pane style of your own builds without an error or a QML warning. A reload whose configuration fails to load keeps the session as it was, and says why in the log: ~/.local/state/solium/session.log for a session from the login screen or --tty, and the terminal for a nested one.

docs/ricing.md goes on from there, and Every setting lists what there is to set. Your own QML in ~/.config/solium/qml shadows what ships, file by file. A single Solium/Theme.qml there is meant to restyle every frame without copying the rest; until #88 is fixed, the shipped one still wins.

How it is built

Five ideas carry most of the design. Each is a choice with a cost, and the cost is named.

Chrome is QML, inside the compositor

Titlebars, the wallpaper, every pane style and the pointer Solium draws when no cursor theme is set are QML, rendered in-process through QQuickRenderControl and drawn as ordinary render elements. Not a shell talking to a compositor over a protocol — the same process, the same frame. A shell is hosted in that same engine, as QML written against Solium’s own API, through shell = { scene = ... } in the configuration: see docs/shell-boundary.md. Quickshell support was removed (#172).

That is why a titlebar can be reloaded while the session runs, why a hosted shell can read the same theme as the window frames, and why a decoration can be a gradient, a shader or a clock without the compositor learning what any of those are. It is also why Qt is a hard dependency and why the compositor drives Qt by hand. There is no Qt event loop: each frame advances Qt’s animations on the compositor’s clock, and between frames the compositor’s own event loop serves Qt’s timers and the descriptors Qt waits on, on that same clock, so a Timer fires on an idle desktop and costs a frame only when it changes something.

On the hardware, QML renders on the GPU: Qt draws into a buffer the compositor allocated, once a trial render in a short-lived child process has shown that works on this machine. Where it does not, QML renders in software and the log says why. solium --tty --qml gpu or --qml software (or SOLIUM_QML=) forces one, and the last log line beginning QML renderer: says which a session got — see dev/README.md.

A pane owns a window and its chrome

A pane is a window plus the layers drawn around it. Layers have a depth — behind, frame, above — and a bleed, which is how far past the window’s own rectangle a layer may paint. The client is drawn between them, which is the thing a single decoration file cannot express: a glow behind, a titlebar in front, and the window in the middle of its own frame.

A style is a folder under qml/panes/, so a pane style is a bundle you can copy, not a setting you can only choose from.

Everything a window does is one transform

Position, size, opacity, depth and rotation pivot are one Frame per window per moment, and animation is interpolation between two of them. A layout does not move windows; it says where they should be, and the transform layer gets them there. Which is why every mode animates identically and why a thumbnail in overview carries its own titlebar — the frame is part of the window’s transform, not a thing drawn beside it.

The policy is Lua, the arithmetic is a crate

Tiling, scrolling, floating and overview are Lua scripts: when to split, where a new window goes, what a key does. The arithmetic they ask for — the dwindle tree and the scrolling strip — is crates/layout, which knows nothing of windows and also arranges the boxes in dev/preview’s animation page. sol.present hands a script the same transform the compositor uses, so a layout somebody writes is not a second-class one. Bindings and the modes themselves live in Lua too, and --check will tell you what actually loaded — because a configuration that fails to parse at startup leaves a compositor with no layouts and no bindings at all, and that failure should cost a log line rather than a session.

Effects are fragment programs with declared inputs

An effect says what it needs — nothing, or its own pixels — and the compositor arranges the passes. What is behind it is the third input, the one a blur needs, and it is declared and not built yet. Rounded corners are a shader over the window’s own texture, which is why they apply to the pane rather than to the client, and why a corner radius can differ per corner so a titlebar and a window can meet more than one way.

Drawing is GLES2, through Smithay’s GlesRenderer, and the code says so rather than hiding behind Smithay’s generic renderer traits: a window drawn through four corners, the rounded-corner shader and QML on the GPU each need GLES or EGL, which those traits do not offer.

And the parts that are deliberately not ours

Solium does not draw a bar or own a notification of its own: it hosts the shell’s QML as configuration, and layer-shell clients beside it. It tells the session where its display is and leaves starting the rest to systemd. It blanks its screens after ten minutes alone and no other idle policy is its own: it reports idleness and lets a policy daemon act on the rest; it exposes wlr-screencopy and lets a portal record. docs/shell-boundary.md is where that line is drawn and defended.

Why this stack

Smithay is a Wayland compositor library, not a compositor. It hands over protocol plumbing, input and backends while leaving layout, rendering and policy to us — which is where a desktop environment’s character actually lives. niri is Rust-on-Smithay with working touch and gesture support, so the multi-form-factor path has a reference implementation rather than being a bet. Rust because a crash in a compositor takes the session with it, and memory safety removes an entire class of them.

GLES2, because Smithay has no Vulkan renderer — its backend::vulkan is device enumeration only — and niri, the reference implementation this stack was chosen for, uses GLES. The price is that a Vulkan backend would be a port, not a swap: the render elements are typed on GlesRenderer, the four-corner warp calls GL directly, rounded corners are a GLSL ES program, and QML on the GPU shares its buffers through EGL. The spike lists what each would need.

Documentation

All of it is also a website, https://lilium-linux.github.io/solium/, with reference pages made from the code.

Thanks to

• Smithay — Solium is a Smithay compositor, and most of what is hard about being one is Smithay’s work rather than this project’s: DRM, GBM, libinput, the seat, the protocol implementations. Its example compositor is also the first place to look when something here does not make sense.
• niri — the reference for how a serious Smithay compositor is actually put together, and the answer to more than one “surely this cannot be the way” while reading DRM code. Its scrolling layout is why lua/scrolling.lua exists to be compared against.
• Hyprland — where this started. Solium began as a Hyprland fork, and that work is archived: it proved the decoration and window-control ideas, and its post-mortem — including why an out-of-process QML shell was the wrong architecture — is in the lilium-de repository. The ideas carried over and none of the code did, but the case that a compositor is allowed to be beautiful and configurable at the same time was made there first.
• Quickshell — the demonstration that a desktop shell can be QML all the way down. Solium hosts QML inside the compositor rather than beside it, which is a different answer to the same question, and it is a different answer because Quickshell had already shown what the question was.

License

Solium is free software under the GNU General Public License, version 3 only (GPL-3.0-only).

The logo, logotype and default wallpaper are © 2026 Illia Kotomin, licensed CC BY-SA 4.0; see docs/brand.

Contributions are welcome; see CONTRIBUTING.md. Each contributor agrees once to the Contributor License Agreement; the pull request template carries the one sentence that does it. What came from other projects is listed, with its licence, in THIRD_PARTY.md.

Getting started

Building Solium, running it, installing it, and a first configuration. The first three sections are the README’s; the last two are the start of Ricing Solium, which goes on from there.

Building

Solium needs Rust 1.88 or newer (edition 2024), a C++17 compiler, Qt 6.5 or newer (Qt Quick and Qml), and the development files for Wayland, libinput, libudev, libseat, xkbcommon, GBM, EGL and libdrm. Lua is compiled in and needs nothing installed. The build also runs Qt’s moc on the headers of Solium’s own QML types; QT_MOC names it when the build cannot find it, and dev/README.md says where it looks.

Rust is easiest from rustup; a distribution’s own Rust works too if it is new enough. The system packages:

Fedora

sudo dnf install gcc gcc-c++ pkgconf-pkg-config wayland-devel libinput-devel \
    systemd-devel libseat-devel libxkbcommon-devel mesa-libgbm-devel \
    mesa-libEGL-devel libdrm-devel qt6-qtbase-devel qt6-qtdeclarative-devel

Arch Linux

sudo pacman -S --needed base-devel wayland libinput systemd-libs seatd \
    libxkbcommon mesa libdrm qt6-base qt6-declarative

Debian 13 and Ubuntu 24.10 or newer (older releases ship a Qt older than 6.5)

sudo apt install build-essential pkg-config libwayland-dev libinput-dev \
    libudev-dev libseat-dev libxkbcommon-dev libgbm-dev libegl-dev libdrm-dev \
    qt6-base-dev qt6-declarative-dev

openSUSE Tumbleweed

sudo zypper install gcc-c++ pkgconf qt6-base-devel qt6-declarative-devel \
    'pkgconfig(wayland-server)' 'pkgconfig(libinput)' 'pkgconfig(libudev)' \
    'pkgconfig(libseat)' 'pkgconfig(xkbcommon)' 'pkgconfig(gbm)' 'pkgconfig(egl)' \
    'pkgconfig(libdrm)'

Then, from the checkout:

cargo build            # target/debug/solium; add --release for an optimised build

Or in a container, on Fedora without the development packages. The image has the C toolchain and the libraries, and your own rustup install is mounted into it. It is an image of Fedora, and what it builds links that release’s libraries, so build it for the release you run: FEDORA_VERSION (44 by default) is a build argument of dev/Containerfile. On any other distribution, install the packages above instead. A release whose Qt is older than 6.5 cannot run Solium at all; a pull request from one still gets every check except the GPU one from CI.

podman build -t solium-build:fc44 -f dev/Containerfile dev/
SOLIUM_GATE_IMAGE=localhost/solium-build:fc44 dev/gate.sh

dev/gate.sh builds and runs every check; dev/README.md has the plain podman run for a build on its own, and CONTRIBUTING.md has the rest of what a change needs.

Running it

From a free TTY (Ctrl+Alt+F3), and not from inside a running desktop session — --tty takes the screen and will fight whatever else has it:

cargo build
./target/debug/solium --tty

Nested, as a window inside an existing session, for development:

./target/debug/solium

Once installed (the Fedora package or dev/install.sh, below), the command is solium: from a text console run solium --tty, and solium --probe, which is safe inside a running desktop, first shows what the hardware offers.

Three flags worth knowing:

solium --help lists every flag and the variables that change a session, and a flag Solium does not know is refused rather than started with.

super+shift+q ends the session and super+shift+r reloads the configuration without ending it. The rest of the bindings come from --check, because they belong to a script rather than to the compositor, and Key bindings lists every one that ships.

On the hardware, anything that goes wrong is also written to ~/.local/state/solium/session.log, synchronously — that log exists for the case where the screen is gone and the power button is the only way out.

Install

On Fedora 44, either build a package of the checkout and install it with dnf, or install from the checkout into ~/.local. The login screen offers Solium after either. Use one: with both, it lists Solium twice.

A Fedora package, a development snapshot of the commit checked out:

podman build -t solium-build:fc44 -f dev/Containerfile dev/   # once
dev/rpm.sh                                                     # prints the dnf line
sudo dnf install ./target/rpm/RPMS/x86_64/solium-0.0.0~git*.rpm

dev/rpm.sh builds the release binary in the build container, packages it with this machine’s rpmbuild (sudo dnf install rpm-build), checks the package unpacked, and prints the dnf line. It installs under /usr, so there is no other step, and sudo dnf remove solium takes it out. It is built for Fedora 44: copy the .rpm to another Fedora 44 machine and install it the same way, with no Rust or build image there. Another release needs a package built for it. dev/README.md has the details.

From a checkout, on Fedora 44 (or a Fedora with the same Qt):

podman build -t solium-build:fc44 -f dev/Containerfile dev/   # once
dev/install.sh
sudo install -Dm644 ~/.local/share/solium/solium.desktop /usr/local/share/wayland-sessions/solium.desktop

dev/install.sh builds a release binary in the build container, copies it and the shipped QML and Lua into ~/.local (--prefix picks another place), runs the installed copy’s --check, and prints the sudo line above — the one step that needs root, which it leaves to you. Then log out and pick Solium from the session list.

Getting back. The login screen remembers the last session, so from then on it offers Solium first: pick Plasma to return. Inside Solium, Ctrl+Alt+Backspace ends the session whatever your configuration says (unless the screen is locked), and so does super+shift+q in the shipped configuration. Ctrl+Alt+F3 switches to a text console, where you can log in and read ~/.local/state/solium/session.log. Solium handles both chords itself, so neither helps if Solium itself hangs.

What it installs is a copy: rebuilding or checking out another branch does not change it, and running dev/install.sh again replaces it. When the login screen’s session file is from an older install, it says so, and the sudo line has to be run again. It refuses while a Solium session is running from it, and while ~/.local/share/solium is a link, which it would otherwise delete through.

The rest of the session. It also puts solium-session.target and solium-autostart.target in ~/.config/systemd/user, and lilium-portals.conf in ~/.config/xdg-desktop-portal. The session file starts solium-session, which starts Solium as the session: Solium tells systemd and D-Bus where its display is and starts those targets, which start graphical-session.target and XDG autostart, and they are stopped again when it ends, a crash included. A Solium that has stopped answering ends itself five seconds after logout asks it to (session.stop_timeout), so that it is cleaned up after too. One Solium session runs per user at a time. Portals, the programs in ~/.config/autostart, and user services written for a graphical session then find Solium. A file there that you have edited, or linked, is left alone. The portal file sends screen capture to xdg-desktop-portal-wlr, which Fedora packages separately (sudo dnf install xdg-desktop-portal-wlr). The Fedora package puts the units in /usr/lib/systemd/user and the portal file in /usr/share/xdg-desktop-portal instead, and recommends xdg-desktop-portal-wlr, so dnf installs it; it also recommends foot, so super+return always has a terminal to open. A polkit agent, a keyring, applets and other separate programs start through XDG autostart or a user unit with PartOf=graphical-session.target. docs/shell-boundary.md says how, with the one command that starts Fedora’s KDE polkit agent under Solium. session.systemd = false in your configuration turns all of it off.

To remove it, dev/install.sh --uninstall, then the sudo rm -f /usr/local/share/wayland-sessions/solium.desktop it prints. Your ~/.config/solium and the session log stay.

Still to come (#66): COPR, so that dnf installs and updates Solium without a checkout, and an Arch PKGBUILD. dev/README.md has the details.

The thirty-second version

Two files, and the difference matters. user.lua is settings: a table of what you want changed, merged over the defaults, and everything you do not mention keeps shipping. Bindings are settings too — there is a bindings section, so adding a key does not cost you the second file. init.lua is the entry point — writing one replaces the shipped configuration entirely, layouts and modes included, and is what you want only when you are rewriting the session rather than adjusting it.

Almost everything on this page is user.lua.

Write ~/.config/solium/user.lua with only what you want changed:

return {
    gap = 4,
    pane = "reactive",
    tiling = { split = 0.618 },
}

It is merged over the defaults, key by key, through nested tables — so tiling = { split = ... } keeps the animations underneath it. Lists are replaced whole, because a list of column widths with one entry changed is a different list, not a longer one.

Every setting is the list of everything you can put in there, one row per section, and the configuration reference explains each key. Both are made from config.lua, the file that sets the defaults, so they cannot drift from it. Key bindings is every key that ships, and what it does.

Three guides go deeper than the recipes below:

Where things live

~/.config is $XDG_CONFIG_HOME when that is set, and ~/.local/state is $XDG_STATE_HOME.

For the files you write, your directory is searched first in every case but your colours. A file you write shadows the one that ships, and everything you did not write still comes from the shipped set — including its later improvements. Your own Theme.qml does not shadow the shipped one yet: the shipped Solium module is found first (#88). Don’t edit the shipped files in place: an install replaces them, and user.lua does the same job without being overwritten.

Ricing Solium

Everything below is a file you write. Nothing here needs the compositor rebuilt, and nothing needs you to copy the files that ship in order to change one thing in them.

Two commands are worth knowing first:

solium --check          # would my configuration run? which bindings survived? do its scenes build?
super+shift+r           # read it again, in the running session

--check is the one that saves afternoons. A configuration that fails to load is reported with the file and the line, and the running session keeps whatever it already had — so a typo costs a line of output rather than your windows.

It also reports the quieter failure: a setting the defaults do not define. tilling = { split = 0.6 } is perfectly good Lua and merges in perfectly cleanly, and then nothing ever reads it — so --check names it, suggests what you probably meant, and exits non-zero.

  2 unrecognised setting(s) -- written, merged, and read by nothing:
    open.scal                   did you mean open.scale?
    tilling                     did you mean tiling?

Then it builds every scene the configuration declares when it loads (the wallpaper, the shell, any sol.surface of your own) on one monitor, draws each once, and loads every pane style in your own qml/panes/, every layer included, with the pane style and loading scene SOLIUM_PANE and SOLIUM_LOADING name when they are set. A scene that fails to build, misses a required property or prints a QML warning while it is built fails the check too. It builds them in software, so a style that needs the GPU is named and not built, and a scene declared later, by a handler, is not seen.

Three things it cannot see, so that its silence means something: the contents of a list (monitors entries are replaced whole and not descended into), the keys inside keyboard, cursor and bindings — the first two are checked against a list, the third accepts anything you can press — and a value of the wrong type, since gap = "12" is a recognised key.

The thirty-second version

Two files, and the difference matters. user.lua is settings: a table of what you want changed, merged over the defaults, and everything you do not mention keeps shipping. Bindings are settings too — there is a bindings section, so adding a key does not cost you the second file. init.lua is the entry point — writing one replaces the shipped configuration entirely, layouts and modes included, and is what you want only when you are rewriting the session rather than adjusting it.

Almost everything on this page is user.lua.

Write ~/.config/solium/user.lua with only what you want changed:

return {
    gap = 4,
    pane = "reactive",
    tiling = { split = 0.618 },
}

It is merged over the defaults, key by key, through nested tables — so tiling = { split = ... } keeps the animations underneath it. Lists are replaced whole, because a list of column widths with one entry changed is a different list, not a longer one.

Every setting is the list of everything you can put in there, one row per section, and the configuration reference explains each key. Both are made from config.lua, the file that sets the defaults, so they cannot drift from it. Key bindings is every key that ships, and what it does.

Three guides go deeper than the recipes below:

Where things live

~/.config is $XDG_CONFIG_HOME when that is set, and ~/.local/state is $XDG_STATE_HOME.

For the files you write, your directory is searched first in every case but your colours. A file you write shadows the one that ships, and everything you did not write still comes from the shipped set — including its later improvements. Your own Theme.qml does not shadow the shipped one yet: the shipped Solium module is found first (#88). Don’t edit the shipped files in place: an install replaces them, and user.lua does the same job without being overwritten.

Recipes

A different frame

return { pane = "left" }

Eleven styles ship, and the pane styles’ README lists them with what each one is for. Reload and every open window is re-framed.

No frame at all

return { pane = "none" }

No bar, no border, and no QML scene built per window — which is different from a decoration that draws nothing: there is no scene to rasterise, so an undecorated desktop costs nothing per window. For a tiling layout whose own bar makes a titlebar redundant, or for taste. SOLIUM_PANE=none does it for one run.

Your own frame

Copy one you like into ~/.config/solium/qml/panes/ and edit it. A folder named top there shadows the shipped top, so you can keep using pane = "top" and mean yours. crates/solium/qml/panes/README.md is the contract: what a style declares, what each layer is told, what it can ask for, and what it costs.

A style is a folder holding a Pane.qml — what the frame reserves, and a list of layers, each its own QML scene at its own depth: behind the client, in the frame, or above it. A layer can also bleed past the window’s edge, which is how a border waves or a shadow reaches. A single QML file still works too and is still called a decoration; it lives in ~/.config/solium/qml/decorations/ and is one layer in the frame.

A layer is also told where the focused text field’s caret is, as caret, in the pane’s own space; whatever the configuration hands every pane with sol.pane_values{ key = value }, as values, which a delegated layer declares as property var values: ({}); and it can read the keyboard’s layout and locks as the Keyboard singleton. That is how KeyboardPillLayer {} draws the keyboard pill: the panes README’s What the compositor sets on every layer has each of them.

Rounded corners

// Pane.qml
client.radius: 12

A style may round the client’s own corners. The compositor cuts them as it draws the client: each of the window’s surfaces goes through a fragment program where it already is, so rounding buys no pass at all and no copy of the window, and a window that is tilted or pulled by a genie keeps its corners. client.radius: 0 is no effect at all rather than a radius of nothing, so a style that does not want it draws its client exactly as before, and nine of the eleven shipped bundles do not want it.

A rounded window that fades in or out is faded surface by surface, with no picture of it taken: where a subsurface overlaps its parent (a player’s video over its window, say) the two show through each other while the window is translucent. An opaque window looks as it always did. A fullscreen window has no frame, so it is drawn square; a maximised one keeps its corners.

pane = "rounded" is one that does, and is there to be looked at. Two things in it are worth copying. The radius is in logical pixels — the compositor multiplies by the monitor’s scale, so the corner is the same size on a HiDPI screen rather than half of it. And every layer of the style is told the number as clientRadius, so a bar or a border can hug the same curve:

// Frame.qml
property int clientRadius: 0   // written by the compositor
radius: clientRadius           // or clientRadius + 2, to hug it from outside

That split is the whole design: the compositor rounds the client, because those pixels belong to the application and only a shader can mask them, and QML rounds itself, because Rectangle.radius is free. A style that wants a rounded border around a square client sets only its own radius, and its client is drawn as an unstyled one is.

One corner at a time

Each corner can be given its own radius. Each of the four defaults to radius, so one key still means all four and nothing written before these existed changes:

// Pane.qml — square on top, round underneath
client.radius: 12
client.radiusTopLeft: 0
client.radiusTopRight: 0

A 0 here has to be written out. Squaring a corner is half of what these keys are for, so a corner that is absent follows radius and a corner that says 0 is square — leaving the key out is not a way of squaring it.

Every layer is told all four by name as well:

// Frame.qml
property int clientRadiusTopLeft: 0      // and TopRight, BottomLeft, BottomRight
property int clientRadius: 0             // still written: the LARGEST of the four

clientRadius survives and is the largest of the four, because what a layer does with one number is hug the window from outside — and a hug has to clear the biggest cut or it crosses the curve. A layer that cares about one corner reads that corner.

Two ways a titlebar meets a rounded window

The shipped pair, and the reason the corners are separable at all. Both reserve a band at the top; what differs is which corners the shader cuts and where the bar is drawn.

flush is the simpler of the two: with the client’s top squared there is nothing to fill, so the bar stops at the seam and stays in the frame, where the compositor copies it band by band.

rounded cuts all four, which leaves two notches inside the window where the client’s top corners were. Something has to be behind them or they show the wallpaper — so its bar is clientRadius taller than its band and sits at depth: "behind". Under the client it fills the notches and covers nothing; over the client the same rectangle would eat the client’s top clientRadius rows, which in a terminal is the top half of the first line.

What a window shows before its application exists

A window’s life starts when you ask for the application, not when the program gets around to connecting — it takes its place in the layout immediately, the other windows move aside, and the application appears inside it. What is in it meanwhile is yours:

return {
    loading = {
        scene = "window",       -- qml/loading/window.qml, or a path
        patience = 8000,        -- give up on it after this long, in ms
        reserves_a_slot = true, -- take a place in the layout straight away
        decorated = false,      -- draw the titlebar while it waits
        fade = 180,             -- how long the scene takes to dissolve, in ms
    },
}

reserves_a_slot = false is the quieter reading: the other windows only move aside once the application is really there. decorated = true gives the waiting window a titlebar, and therefore a close button for an application that is not coming.

fade is the dissolve as the application appears underneath. It is the compositor’s, not the scene’s: whether a window is see-through is a presentation transform, like where it is and how big, so the compositor applies it to the scene’s picture as it draws it (animation.md). Set fade = 0 to cut straight to the application.

Your own scene goes in ~/.config/solium/qml/loading/. It is handed the program’s name and how long it has waited; the one that ships uses only the name, on the grounds that the window already is the window and the one fact you do not otherwise have is which application you are waiting for.

SOLIUM_LOADING=mine        # ~/.config/solium/qml/loading/mine.qml
SOLIUM_LOADING=~/mine.qml  # anywhere

Your wallpaper

wallpaper = "~/Pictures/whatever.png",

~ is expanded, the image is cropped to fill rather than fitted, and wallpaper = false turns it off — which is what you want if you run swaybg, hyprpaper, or a shell that draws its own. A layer surface on the background layer is drawn over this one, so leaving both on means paying to rasterise a picture nobody sees.

A list gives each workspace its own, and it travels with that workspace:

wallpaper = { "~/Pictures/one.png", "~/Pictures/two.png" },

workspaces.lua puts each one in the same selection as its desk’s windows, so one animation carries both and the background stops being left behind when you switch. Fewer pictures than workspaces cycles. It costs a scene per desk on every monitor, built when it is declared, and one screen-sized rasterisation per desk you have actually visited, per monitor — which is why one image stays one static surface: every desk sharing a picture would make a wallpaper that slides pixel-identical to one that does not.

The more interesting part is that there is no wallpaper in the compositor. lua/wallpaper.lua calls one thing:

sol.surface("wallpaper", {
    scene = "wallpaper.qml",
    layer = "background",
    on    = "every-monitor",
    properties = { source = "wallpaper/solium.png" },
})

sol.surface draws any QML scene at any layer on any monitor, so a bar, a dock, a heads-up display or a debug overlay is the same call with a different layer and a different on:

sol.surface("clock", {
    scene = "clock.qml",
    layer = "top",
    on    = { x = 40, y = 40, w = 420, h = 90 },
    properties = { format = "HH:mm" },
})

layer is background, bottom, top or overlay, and each sits under the matching wlr-layer-shell layer — so a real bar covers a scripted one, and swaybg covers this wallpaper. on takes every-monitor, primary, a connector name, or a rect in the global space. Each monitor it is on gets a scene of its own, built when the surface is declared or the monitor arrives and dropped when the monitor goes, and inside it Solium.monitor is that monitor. sol.surface(name, false) removes one.

Declaring the same name again with the same scene writes the changed properties into the live scene rather than building it again, so an open popup or a running animation in it survives. A key left out of properties keeps the value the scene last had, and a dotted key such as ["panel.open"] = true reaches a grouped property. Only a different scene file builds it again.

interactive = true lets the pointer reach it, where its items take input: a MouseArea, a control such as a Button, a pointer handler other than HoverHandler, or an item marked Solium.input: true (shell-boundary.md has the whole list). Everywhere else the pointer goes to what is under it (state::tests::real_client::reflow_on_close::hosted::a_press_where_the_shell_draws_nothing_reaches_the_window_under_it). A surface without it holds neither a Grab nor the keyboard (state::tests::real_client::reflow_on_close::hosted::a_surface_the_pointer_does_not_reach_holds_no_grab, state::tests::real_client::reflow_on_close::hosted::a_surface_the_pointer_does_not_reach_holds_no_keyboard). The scene sends an action, with data if it has any, Solium.send("pressed", { id: 3 }), and whoever is listening is told:

sol.surface("panel", { scene = "panel.qml", layer = "overlay",
                       on = area, interactive = true })

sol.on("surface", function(surface, action, data)
    if surface == "panel" then
        sol.log("pressed " .. action)
    end
end)

An action of the compositor’s own vocabulary, windows.focus with { id: model.id } say, is done for you, by lua/actions.lua through sol.act (shell-boundary.md has the list).

That is the whole of how the Developer Tweaks panel works, and it is entirely in lua/tweaks.lua — the compositor has no idea what a tweak is.

reserve = { bottom = 48 } takes those edges out of the work area of every monitor the surface is on, whatever its size, so a bar scene drawn across the whole monitor reserves only its strip and the windows are placed above it. The scene can say it too, Solium.surface.reserve.bottom: 48, which wins for each edge it sets; shell-boundary.md, “Room of its own”, has how the windows re-flow when it changes (state::tests::real_client::reflow_on_close::hosted::a_declared_reserve_takes_its_edge_out_of_the_work_area).

Place a rect on the monitors event, not at the top of your script. Scripts load before the screens are known — on the hardware backend, before the GPU is even opened — so a rect computed at load time is computed against zeros. The event fires once when the monitors are first known, again on every hotplug and again on every reload, which is when a placement needs redoing anyway. A surface whose on is "every-monitor", "primary" or a connector name needs no event: declare it at the top of the script, and the compositor builds its scene on each monitor it names as that monitor arrives, as wallpaper.lua and shell.lua do. Only a rect computed from the monitors waits for them:

sol.on("monitors", function()
    local area = sol.monitor()   -- the active monitor's work area
    sol.surface("panel", { scene = "panel.qml", layer = "top",
                           on = { x = area.x, y = area.y, w = area.w, h = 40 } })
end)

sol.monitors() lists every monitor, with its name, its work area, its whole rect and whether it is primary, for a panel on a particular one.

Copy qml/wallpaper.qml to ~/.config/solium/qml/wallpaper.qml and the background becomes whatever QML can be:

import QtQuick

Item {
    required property string source

    Rectangle {
        anchors.fill: parent
        gradient: Gradient {
            GradientStop { position: 0.0; color: "#12002e" }
            GradientStop { position: 1.0; color: "#7c4dff" }
        }
    }
}

super+shift+r reloads it without ending the session. source is handed in whatever the configuration said, and a scene that ignores it — like the one above — is perfectly valid.

Your keyboard

keyboard = {
    layout  = "us,ua",
    options = "grp:alt_shift_toggle",
},

The first layout is the one you start in. super+shift+k cycles them and so does Alt+Shift, because grp: options are implemented inside the keymap and work without the compositor being involved — the binding exists so that the feature is discoverable from solium --check rather than from knowing xkb.

Bindings follow the key, not the layout. With a Cyrillic layout active, super+q is still the key us has Q on, and so is super+shift+k. A binding you write in the other alphabet, such as super+Cyrillic_shorti, gets that key first. A key the active layout already labels in ASCII keeps its own name: Russian puts . where us has /, so on Russian that key is super+period.

variant takes one per layout in the same order, blank for plain: layout = "us,ua", variant = ",dvorak" is ordinary US and Ukrainian Dvorak. options also carries compose:ralt, which is the nearest thing to an input method until #26 lands.

Leaving a name out means “whatever the session already said”: an empty name makes xkbcommon read XKB_DEFAULT_LAYOUT and its siblings, which is where a display manager puts it. So a machine already configured elsewhere keeps working, and writing it here takes precedence.

The repeat rate is the compositor’s own — no environment variable reaches it, and before this it could not be changed at all:

keyboard = {
    repeat_rate  = 40,   -- repeats per second. 25 by default
    repeat_delay = 350,  -- milliseconds before repeating starts. 200
},

The locks can be set too, and Num Lock on at login is the usual one:

keyboard = { num = true },

That turns Num Lock on when the session starts, and again at every super+shift+r. caps works the same way for Caps Lock. Each is set by pressing the keymap’s own key inside the compositor, so the application with the keyboard is told and the layout stays where it was.

sol.keyboard() reads all of it back to Lua — the layout names, which is active and its names (layout_name, Russian; layout_short, RU), whether Caps Lock and Num Lock are on, and the repeat settings — and sol.keyboard{ caps = false } sets a lock. sol.on("keyboard", function(state, changed) end) hears the layout or a lock change, however it changed, and never ordinary typing, nor what is pressed at the lock screen. QML reads the same as the Keyboard singleton, in a hosted scene and a pane style alike. sol.on("text_input", function(field, why) end) hears the focused text field: why is "field" when one is enabled or focused, "caret" when its caret moves and "framed" when its window goes fullscreen or comes back. A caret that moves twice before the next frame is told once, where it ended up.

The keyboard pill

Switch layout, or press Caps Lock, and a small capsule appears just below where you are typing: ⇪ while Caps Lock is on, EN or RU for a moment after a switch, after the one macOS shows. It is drawn in the theme’s accent with its glyph in accentInk, which in the shipped theme is a light grey capsule with a dark glyph and a soft shadow: it stands out on a dark window and on a light one.

It is not a compositor feature. It is the shipped configuration’s example of doing something with what the compositor publishes, and it is two ways of doing the same thing, so you can see both:

• Inside the window (show = "pane", the default). Every shipped pane style ends with one line, KeyboardPillLayer {}, a layer above the client that draws the pill at the pane’s caret — where the focused text field’s caret is, in the pane’s own space. Because it is part of the pane, it moves, scales and fades with its window. Your own style gets it by adding the same line. A window drawn with no frame — fullscreen, one that draws its own decorations, or every window when pane = "none" — has no pane style around it, so it gets the surface below at its caret instead: sol.text_input() says which, as framed.
• On a surface of its own (show = "surface"): an overlay sol.surface that lua/keyboard_indicator.lua places at the caret in the global space, from sol.text_input(), and moves again each time sol.on("text_input") says the caret moved.

The policy is the Lua file: it listens to sol.on("keyboard") and sol.on("text_input") and decides what shows and where. An application that says where its caret is only after a key, as kitty does, gets the pill on its screen for the first key and at its caret a few milliseconds later, when it says. Kitty says so only as it handles each key, before the shell has echoed it, so a pill that stays while you type, Caps Lock’s, can sit a cell behind the cursor until the next key. The look is QML, KeyboardPill in import Solium, on Theme. The compositor provides the data underneath — text-input-v3 for the caret, the keyboard’s state and its events — and knows nothing about pills. These are its defaults, from config.lua; any of them goes under keyboard in user.lua:

keyboard = { indicator = {
    show = "pane",            -- "pane", "surface", or false
    on = { layout = true, caps = true, num = false },
    caps_on_focus = true,     -- Caps' pill again when a field is focused with Caps on (needs on.caps)
    fallback = "surface",     -- with no caret: on the screen, or false
    position = "bottom",      -- where on the screen: "bottom", "center" or "top"
    duration = 1200,          -- ms a layout's pill stays
} }

The caret comes only from applications that say where it is through text-input-v3; for the others, fallback = "surface" shows the pill on the focused window’s monitor instead. To try it nested, SOLIUM_KEY_AT presses Caps Lock and a layout switch for you (dev/README.md). To change the policy, copy lua/keyboard_indicator.lua next to your configuration, where it is found first. To change the on-screen pill’s look, copy qml/indicator/keyboard.qml to ~/.config/solium/qml/indicator/; a pane style of your own can draw a pill of its own at caret in place of KeyboardPillLayer {}. KeyboardPill itself is in the shipped Solium module, which a copy cannot replace yet (#88). To have none, write keyboard = { indicator = false } in user.lua; a whole init.lua of your own can instead leave out require("keyboard_indicator").

Your monitors

The compositor cannot work out which screen is on the left. The kernel reports connectors in an order that has nothing to do with your desk, so it guesses — every connected screen driven, left to right in that order — and about half the time the guess is wrong.

You almost never want coordinates. Say what is beside what:

return {
    monitors = {
        { name = "DP-1", mode = "2560x1440@260", vrr = true, primary = true },
        { name = "DP-2", mode = "2560x1440@75", right_of = "DP-1", align = "end" },
        { name = "DP-3", above = "DP-1", transform = "90" },
        { name = "HDMI-A-1", enabled = false },
    },
}

solium --probe prints the connector names this machine has, without taking the screen from whatever is drawing on it. A name nothing answers to gets a line in the log rather than being ignored — a monitor arrangement that silently does nothing is the hardest kind to debug, and the usual cause is a name that does not exist here.

super+shift+r applies the placement keys (right_of, left_of, above, below, align, x, y), scale, primary and enabled without ending the session. mode, vrr and transform are read when a monitor is first lit, so on one that is already lit they wait until it is next plugged in — or until a reload with enabled = false and another with it back.

Refresh rate lives in mode. "2560x1440@165", the way every display tool on Linux writes one. Drop the @ part and you get the fastest mode at that resolution; drop mode entirely and you get the fastest mode at the preferred resolution, which is almost always what you want. Three words also work:

"best" is not "preferred", and the difference is the reason it is the default: the EDID’s preferred flag names a resolution and usually pairs it with a pedestrian 60 Hz. A 260 Hz panel reports 2560x1440@60 as preferred. Taking that literally drives a fast display slowly and makes every animation in the compositor look worse than it is. "preferred" is there for a monitor that is unstable at its fastest rate, which is a real thing and not something the automatic choice can know about.

A mode the monitor does not have warns and falls back rather than going black. solium --probe lists every mode each monitor offers, in exactly the form mode takes — which is the whole reason to run it:

  DP-1         connected, 36 modes, best 2560x1440@260, 600x340mm, 108 dpi, scale 1
                 2560x1440@260, 240, 200, 165, 144, 120, 100, 60  (preferred)
                 1920x1080@240, 120, 60, 50

scale is worked out for you, and you can override it. Left out, it comes from the panel’s own size: 2x above 192 dpi and 1x below, which is the number GNOME and KDE both use — matching them matters more than being right in the abstract, because it is what every monitor’s marketing and every forum answer is implicitly calibrated against. That puts a 13“ 4K laptop at 2x and a 27“ 4K at 1x, and the second of those is genuinely a matter of taste, which is why it is settable. Fractional values work.

solium --probe prints the dpi it measured and the scale it would choose, per monitor, at the end of each monitor’s first line above. That is the one number you need to decide whether to disagree. A monitor that reports no physical size says so there, and gets scale 1.

Scaling is not a zoom. Everything the compositor draws itself — titlebars, the loading window, the pointer — is rasterised at the monitor’s pixel count rather than drawn small and stretched, so a 2x screen gets twice the detail and not twice the blur. Your QML keeps working unchanged: it is laid out in logical units, so titlebarHeight: 32 is 32 logical pixels on every monitor and is drawn with as many real pixels as that monitor has.

vrr is off unless asked for. FreeSync, G-Sync compatible, Adaptive-Sync — the display’s refresh follows what is being drawn instead of the other way round, which is what removes tearing and stutter on anything that cannot hold a steady frame rate. It is not on by default because it interacts badly with some panels at low frame rates — visible flicker — and that is not something to turn on for somebody. The log says whether the connector actually offered it.

Three more are worth a sentence.

align is not cosmetic. A 1080p beside a 1440p leaves 360 rows belonging to no screen at all, and which end of the small monitor that dead strip is at decides where the pointer catches on its way past. "centre" halves the strip instead of putting all of it at one end, which is why it is the default; "end" lines the bottom edges up, which is what you want if both monitors stand on the same desk.

enabled = false frees a CRTC, not just the screen. A CRTC is the hardware that scans a buffer out, there are usually four, and a connector without one stays dark — so switching off a monitor you are not using is how you drive a fourth on a card with three.

A rotated monitor’s work area is portrait. transform changes the logical size, so every layout follows it without knowing anything about rotation, and the display pipeline does the turning.

Plugging in and unplugging work while the session runs. A monitor that arrives is driven with its entry above, as it would have been at startup, and the monitors event fires so anything placed per screen can be placed again. One that goes takes no windows with it: a window left on no screen is moved onto one that remains, and the layouts run again. dev/README.md has how to try it without reaching behind the desk.

Turning screens off

The screens go dark on their own after ten minutes with nobody at the machine, with no daemon to install. It is one number:

return { idle = { screens_off_after = 300 } }   -- seconds; 0 never does it

Ten minutes and not GNOME’s five, because GNOME dims first and Solium does not: here the first you know of it is the screen going dark. Anything that plays – a film, a call, a presentation – holds an idle inhibitor, and while that window is on screen the timer waits. When it lets go the ten minutes start again from then, so a film ending an hour in does not take the screen with it, and the next one in a playlist does not start in the dark. Nothing holds it off behind the lock screen, which goes dark like anything else.

Browsers ask over D-Bus instead. Chrome and Firefox keep the screen on during a film by calling org.freedesktop.ScreenSaver.Inhibit on the session bus, not through the Wayland protocol, so Solium owns that name while it runs, and what they hold counts like a window’s inhibitor: the timer waits, and so do swayidle’s timeouts. It goes when the browser lets go, closes or crashes, and holds nothing behind the lock screen. Firefox asks org.freedesktop.ScreenSaver first for a tab in view, before the portal. A program that asks the portal’s Inhibit reaches the same place through xdg-desktop-portal-gtk, which lilium-portals.conf gives Inhibit to, as long as no GNOME session runs on the same bus; KDE’s backend sends it to Plasma’s power manager, which is not there, so do not give Inhibit to kde. If another desktop already owns the name on the same bus – one running on another VT – it keeps it: Solium says so in its log and carries on without it. Nested, the name is owned only on the bus SOLIUM_SESSION_BUS names. To leave it alone altogether:

return { idle = { dbus_inhibit = false } }

Any key, click, scroll, touch or pointer motion turns every screen back on, however they went off, and that input is delivered as usual rather than swallowed. The case that decides it is typing a password at a lock screen that went dark: the first key is part of the password, and a compositor that ate it would fail the unlock for a reason nobody could see. A key release does not wake anything, so a binding that turns the screens off leaves them off when you let go of it.

A monitor that is off is not gone. It keeps its place in the arrangement, its work area and its windows; nothing is moved, no client is told a screen went away, and sol.monitors() still lists it, with power = "off". That is the difference from enabled = false, which takes a monitor out and frees its CRTC.

From a binding – none ships, since which key does this is a matter of taste:

sol.bind("super+F12", function() sol.monitor_power("all", "off") end)
sol.bind("super+shift+F12", function() sol.monitor_power("DP-2", "off") end)

Or leave it to swayidle. Solium speaks wlr-output-power-management, so wlopm works, and swayidle drives it without needing swaymsg. Turn the built-in one off so the two do not both do it:

return { idle = { screens_off_after = 0 } }

swayidle -w \
    timeout 300 'swaylock -f' \
    timeout 600 'wlopm --off \*' resume 'wlopm --on \*' \
    before-sleep 'swaylock -f'

wlopm on its own lists the monitors and whether each is on.

A window on a screen that is off is still told it may draw, once a second (idle.off_frame_interval, in milliseconds). Not telling it at all would freeze any program that waits for that inside its swap for as long as the screen is dark, which with the idle blank is all night. 0 stops them altogether, which is what sway does. A screenshot of a screen that is off is refused rather than left waiting.

Nested, there is no display to power off: a monitor that is “off” is drawn black and then not drawn at all, so all of the above can be tried in a window.

One workspace per screen, or one for the desk

Each monitor has its own workspace in view by default: super+2 switches the screen the pointer is on and leaves the other showing what it was, so a reference on the second monitor stays put while you move around on the first.

One line makes a workspace a whole desk instead, so a switch moves every screen together:

return { workspaces = { per_monitor = false } }

Neither is more correct — the difference is whether you think of your monitors as two screens or as one surface you happen to have cut in half.

Bars, docks and wallpapers

A shell — bar, dock and launcher together — can be hosted inside the compositor, in the same QML engine as the window frames, by naming its root file:

return { shell = { scene = "~/.config/solium/shell/shell.qml" } }

One scene on every monitor, or on the one shell.on names, written against Solium’s own QML API; shell-boundary.md has how to install one and what it is and is not given.

Two more settings are the shell’s. shell.outside_click is what a press outside one of its open popups does after closing it: "swallow", the default, or "pass", which also clicks what is under it. A table names popups by their Grab’s name: { default = "swallow", ["tray-menu"] = "pass" }. shell.keyboard.bindings is which compositor bindings still work while one of its fields holds the keyboard: "except_claimed" (the default: all but the keys the field claims), "all", or "none". The Ctrl+Alt escapes always work. A scene of your own drawn with sol.surface takes the same two, as outside_click and keyboard = { bindings = ... }. shell-boundary.md has Grab and Solium.keyboard.

A bar can also be an ordinary client over wlr-layer-shell, which means any panel already written for that protocol works. A surface names the output it wants and the compositor honours it, so a bar on every screen is one surface per screen, each reserving from that monitor’s work area. One that names no output gets the primary monitor.

A fullscreen window in front of the workspace its monitor is showing covers the top layer – a client’s bar, and one declared with sol.surface – and takes the clicks where the bar was, while the overlay layer (notifications, an OSD, a launcher) stays over it. It goes over the bars as it starts to grow and back under them once it has finished shrinking. To keep the bars over fullscreen windows:

return { fullscreen = { covers = "none" } }

See shell-boundary.md for why hosting is the design, and for both ways a shell attaches.

The preview shell

A fresh install is not a blank desktop. shell.scene above defaults to the compositor’s own preview shell – a bar along the bottom, built the same way any other shell is, on the public API shell-boundary.md describes and nothing else. It shows:

• the workspaces of this monitor, as page dots – the current one an accent pill, an occupied one filled – and a click switches;

• the running windows of this monitor’s current workspace, as chips – icon, title or app id, the focused one highlighted – and a click focuses one;

• the keyboard layout, once more than one is configured;

• a clock;

• a top dock: pinned apps, then a hairline, then running ones that are not pinned, each a theme icon with a dot under a running one. Autohidden by default – nothing is reserved, and it slides in when the pointer reaches the top edge, out a little after it leaves. A click on an app that is not running launches it (Solium.Apps, 03 §3.2.13); on one that is, focuses its most recently used window.

  return { preview = { dock = {
      pinned = { "org.mozilla.firefox", "kitty" }, -- desktop ids, left unset
                                                    -- the dock picks a
                                                    -- terminal, a file
                                                    -- manager and a browser
                                                    -- from what is installed
      visibility = "always",                       -- or "autohide" (default)
      icon_size = 48,                               -- default 40
  } } }
  

• quick search, super+d: a centred panel with a field, the live keyboard layout beside it, and results grouped into applications (matched by name and generic name), open windows (title or app id, with the workspace) and a few compositor commands that already exist – Overview, Tile windows, Fullscreen window, Reload configuration, Quit Solium. Arrow keys move the selection, Return activates it, Escape or a click outside closes.

  return { preview = { search = {
      key = "super+alt+space", -- default "super+d"
  } } }
  

  Cut from this first version (lua/preview/search.lua and qml/preview/Search.qml both say why, in full): the detail pane, a row’s own actions, Alt+digits, Ctrl+Return, the empty-query suggestions (there is no usage history yet to rank by), app keywords (the plain array this searches, sol.apps(), does not carry them – a real gap, not a corner cut), the settings and desktop-file sources, the container transform from the bar’s own search button (the bar has no search button yet either), and the “us,ru” layout-correction pass – it needs the compositor’s own keymap, which nothing here exposes yet.

• desktop icons: Solium.dirs.desktop ($XDG_DESKTOP_DIR, or user-dirs.dirs; nothing drawn, and nothing scanned, when it is unset or is $HOME), on their own surface – layer = "bottom", below ordinary windows, the same as a real desktop, and below the bar above – 96x100 cells with 48 px icons, column by column from the top right, folders first then by name. A click selects (Ctrl or Shift adds), a double-click opens: a regular file through its MIME type’s default application, a .desktop launcher through its own Exec= once trusted, asked for once in a small card. Live through inotify: a file that appears or disappears on the desktop updates the icons at once, no reload needed.

  return { preview = { desktop = {
      from = "top-left",                   -- or "top-right" (default)
      cell = { width = 110, height = 112 }, -- default 96x100
      labels = 1,                          -- label lines, default 2
      open = "single",                     -- or "double" (default)
      show_hidden = true,                  -- default false
  } } }
  

  Cut from this first version (crates/solium/src/folder.rs and qml/preview/Desktop.qml both say why, in full): dragging and saved positions (there is nowhere durable to keep them yet), the right-click menus, a rubber band, showing the desktop (super+ctrl+d needs a window-presenting pass this compositor does not have), Open With and thumbnails, MIME detection by content rather than by extension, and the arrow-key/Return navigation the design note asks for (nothing yet gives the desktop the keyboard on demand, so claiming it unconditionally would only fight the dock and quick search for focus).

Next pieces – the island, quick settings, a tray, and previews – need services this compositor does not have yet, and are not here. lua/preview/ and qml/preview/ are where all of it lives, so copying one file still changes one behaviour, exactly as Your own frame and Bars, docks and wallpapers above do it.

Two ways to turn it off, or replace it:

return { preview = false }

turns the whole preview shell off and leaves a blank desktop, as before it existed. Naming your own shell.scene – or SOLIUM_SHELL_SCENE for one run – replaces it outright: the preview shell only ever fills in a default nothing else set, and never overrides either one.

Your own pointer

The pointer can be a QML scene of yours, named the way a shell is:

return { cursor = { scene = "~/.config/solium/cursor/Cursor.qml", size = 32 } }

A path, ~ expanded, or a bare name looked for in ~/.config/solium/qml/ and then in the shipped QML (cursor::theme::tests::a_configured_scene_is_found_as_the_shells_is). SOLIUM_QML_CURSOR=<file> is the scene for one run, over the setting (cursor::theme::tests::the_environment_overrides_the_configured_scene). It draws every shape a window or the compositor asks for, ahead of any XCursor theme, and is told which one (models::pointer::tests::a_configured_scene_hears_every_named_shape). A window that sets a cursor of its own, or hides the pointer as a game does, still does over its own surface (cursor::tests::a_pointer_a_client_hides_stays_hidden_with_a_scene_configured). super+shift+r applies a change and builds the scene again when its files changed. A scene that does not load leaves the theme, and then Solium’s own arrow, to draw the pointer, says so in the log, and is tried again at the next reload (cursor::tests::a_reload_swaps_the_scene).

It reads Solium.cursor. shape is the shape asked for, by its CSS cursor name: default over a titlebar, text over a text field, ew-resize on a window’s left or right edge, and so on (models::pointer::tests::a_named_shape_reaches_solium_cursor_shape). pressed is whether a button is held, velocity how fast the pointer moved over the last frame in logical pixels a second along x and y, zero once it stops, scale the scale of the monitor it is on and size the configured cursor.size (models::pointer::tests::the_published_pointer_is_its_buttons_its_motion_its_monitor_and_its_size). It says one thing back, Solium.cursor.hotspot on its root: the point of its picture that sits on the pointer, its top-left corner unless it says. Its size is its root’s own width and height, up to 256 logical pixels a side, so a glow or a shadow can reach past size with the hotspot still on the point the pointer is at; a root that sets no size is size square (cursor::scene::tests::the_scene_is_drawn_at_its_own_size_with_its_hotspot_on_the_pointer).

An arrow, an I-beam over text, and a glow that breathes:

// ~/.config/solium/cursor/Cursor.qml
import QtQuick
import QtQuick.Effects
import QtQuick.Shapes
import Solium

Item {
    id: root
    readonly property int pad: 10        // room for the glow
    readonly property int size: Solium.cursor.size
    readonly property bool text: Solium.cursor.shape === "text"
    width: size + 2 * pad
    height: size + 2 * pad
    // The arrow points with its tip, the I-beam with its middle.
    Solium.cursor.hotspot: text ? Qt.point(pad + size / 2, pad + size / 2)
                                : Qt.point(pad, pad)

    // One breath, forever: the glow's strength and a tint in the arrow.
    property real breath: 0.25
    SequentialAnimation on breath {
        loops: Animation.Infinite
        NumberAnimation { to: 1; duration: 800; easing.type: Easing.InOutSine }
        NumberAnimation { to: 0.25; duration: 800; easing.type: Easing.InOutSine }
    }

    MultiEffect {                        // the glow, behind the drawing
        source: drawing
        anchors.fill: drawing
        shadowEnabled: true
        shadowColor: "#7aa2ff"
        shadowBlur: 1.0
        shadowOpacity: root.breath
    }

    Item {
        id: drawing
        x: root.pad
        y: root.pad
        width: root.size
        height: root.size
        readonly property real u: width / 24

        Shape {                          // the arrow
            anchors.fill: parent
            visible: !root.text
            ShapePath {
                fillColor: Qt.tint("white", Qt.rgba(0.48, 0.64, 1, 0.45 * root.breath))
                strokeColor: "#1c1c1e"
                strokeWidth: 1.6 * drawing.u
                startX: 0.8 * drawing.u; startY: 0.8 * drawing.u
                PathLine { x: 0.8 * drawing.u;  y: 16.3 * drawing.u }
                PathLine { x: 5.0 * drawing.u;  y: 12.5 * drawing.u }
                PathLine { x: 7.9 * drawing.u;  y: 19.1 * drawing.u }
                PathLine { x: 11.0 * drawing.u; y: 17.7 * drawing.u }
                PathLine { x: 8.2 * drawing.u;  y: 11.3 * drawing.u }
                PathLine { x: 13.7 * drawing.u; y: 10.9 * drawing.u }
                PathLine { x: 0.8 * drawing.u;  y: 0.8 * drawing.u }
            }
        }

        Rectangle {                      // the I-beam
            visible: root.text
            anchors.centerIn: parent
            width: 3 * drawing.u
            height: 16 * drawing.u
            color: "white"
            border.color: "#1c1c1e"
        }
    }
}

It animates on the compositor’s clock: a running animation asks for the next frame, and a scene with nothing running asks for none (cursor::scene::tests::an_animating_scene_asks_for_the_next_frame_only_while_it_animates). This one breathes forever: while the pointer is shown it is drawn on every refresh, and while it is not (a window hiding it or drawing its own, or the screens off) the breath is still stepped a frame apart, every 16 ms (qml::wake::tests::a_timer_beside_an_undrawn_animation_fires_with_no_frame_drawn). To let it rest, bind the animation’s running: to something the scene can see, such as Solium.cursor.pressed, the shape, or the velocity.

MultiEffect and ShaderEffect draw on the GPU path, which a session on the hardware uses by default (dev/wirecheck’s case 11 draws a pointer scene’s glow there). On the software path, which a nested session uses and qml.renderer = "software" chooses, they draw nothing, and the drawing under the glow is the whole pointer: that is why the breath is in the arrow’s tint as well. The picture is offered to the hardware cursor plane, as a theme’s is (cursor::scene::tests::a_scene_with_no_material_is_a_cursor_plane_element), and goes there when its size in device pixels fits the plane, commonly 64 or 128 pixels a side; there moving the mouse redraws nothing else. A larger one, such as this one at size = 32 on a 2x monitor (104 pixels a side), is drawn with everything else where the plane is smaller. Solium.region and Solium.material are accepted, and materials are off until #199: Solium.materialState reads "off" (qml::pointer::tests::a_region_and_a_material_are_accepted_and_materials_are_off).

Your own colours

Solium.Theme (crates/solium/qml/Solium/Theme.qml) is what every shipped frame, the loading window and the keyboard pill are drawn with, and a hosted shell that imports Solium can read it too. The shipped one is a dark theme of greys only, with no hue in it at all, the maintainer’s choice for now: near-black bars, light grey text, grey buttons, and an accent that is a light grey too (decorations.md lists every name). A shell that reads Theme.accent for its highlights gets that grey. The fallback pointer and the default wallpaper do not read it: their colours are fixed. A copy of Theme.qml in ~/.config/solium/qml/Solium/ is meant to restyle the frames, the loading window and such a shell at once, and does not work yet: the shipped module is found first (#88). Until then, a frame of your own (above) can carry colours of its own.

Your own animation feel

Named curves — linear, outCubic, outBack, inOutQuad, inOutCubic, spring — or four numbers, which are a cubic bezier’s control points:

return {
    tiling = { motion = { duration = 220, easing = { 0.34, 1.56, 0.64, 1 } } },
}

Those are the same four numbers CSS calls cubic-bezier and every easing generator on the internet hands out, so a feel you found elsewhere transfers directly. y may leave 0..1 — that is what overshoot is.

Going fullscreen and maximising are timed the same way, each on its own, and both glide by default: the window grows from where it is to cover its monitor, or its work area, and shrinks back. animate = false makes one instant and animate = true is the shipped motion again, and instant names the applications that change at once whatever animate says — a game or a video player, say:

return {
    fullscreen = {
        animate = { duration = 200, easing = "inOutCubic" },
        instant = { app_id = { "mpv", "gamescope" } },
    },
    maximize = { animate = false },
}

The application is told its new size the moment you press the key, and its last picture is stretched until it has drawn one at that size — through the glide and after it, for a quarter of a second past the landing at most, and then the window is shown at whatever size the application has. Once it has answered the window is drawn as it is, with nothing in between, so a fullscreen game or video can be shown directly. An instant change is just that: nothing is stretched or moved, and the window is drawn as it is on the next frame. An app id is what sol.windows() calls app_id.

Your own bindings

A bindings section in user.lua, merged like every other section:

return {
    bindings = {
        ["super+b"]       = "firefox",
        ["super+shift+s"] = { "sh", "-c", "grim -g \"$(slurp)\"" },
        ["super+n"]       = function() sol.spawn("kitty", "-e", "nvim") end,
        ["super+g"]       = false,
    },
}

A string is a command line split on spaces; a list is one already split, for an argument with a space in it; a function is anything else, with the whole sol API in scope; false removes a shipped binding outright.

A combination you bind belongs to the compositor from then on, and while the session is unlocked the application with the keyboard never receives it. So binding a plain key such as escape, f1 or return takes that key from every window. This is why the overview binds Escape only while it is open (#174). Key bindings lists every shipped one, so you can see what a key does before you take it over — super+g above is a demonstration that tilts a window.

A binding here replaces a shipped one on the same combination. On purpose: refusing a clash would let you add a binding and forbid you to change one, and changing one is what most people come here for. It is not silent — solium --check marks every combination this section took over, and lists the ones it removed:

    super+b                     config.bindings
    super+q                     config.bindings, replacing a shipped binding
  1 binding(s) removed by the configuration:
    super+g                     config.bindings

Reading that list is also how you find out an edit dropped a binding, and it is the only way to catch super+whoops: a combination is whatever you press, so nothing can check the name for you.

Writing your own ~/.config/solium/init.lua is the other way, and is for rewriting the session rather than adding to it — it replaces the entry point whole. It can still require everything that ships, including bindings, which must stay last: sol.bind lets the later call win, and that ordering is what puts your config.bindings on top of the shipped ones.

require("modes")
require("tiling")

sol.bind("super+return", function() sol.spawn("kitty") end)

require("bindings")

Moving around by keyboard

super+arrows and super+h/j/k/l focus the window that way, super+shift+arrows and super+shift+h/j/l move it, and super+alt+k moves it up – super+shift+k is the keyboard layout. At the edge of a screen both go on to the next one. super+f is fullscreen, super+shift+m maximised and super+shift+space floats a window over the layout; each key again puts it back, and fullscreen and maximised glide there and back (Your own animation feel times them). Rebind any of them in bindings:

return {
    bindings = {
        ["super+ctrl+h"] = function() sol.focus_direction("left") end,
        ["super+alt+k"]  = false,
    },
    tiling = { move = "split" },
}

In tiling a move trades tiles with the neighbour level with it that way, and in a grid the opposite key puts both back; move = "split" makes it split the neighbour’s tile instead, as Hyprland’s movewindow does. modes.md has what each layout does with a direction.

Your own mode

A mode is a Lua module that reacts to events — a window opening, closing or taking focus, a drag ending, the monitors changing, and the rest modes.md lists — and asks for placements. tiling.lua is Hyprland’s dwindle and scrolling.lua is niri’s model; each decides where windows go and when, and leaves the arithmetic of the tree and the strip to crates/layout. Copy either into your own directory and it takes over.

modes.md is the guide, with a whole working mode in forty lines and the two mistakes everyone makes first.

Worth knowing

Each layer of a frame is drawn over its canvas: the window’s outer rect, grown by whatever bleed the layer declares. On the hardware that is on the GPU by default; nested, or where the GPU trial at startup fails, it is in software on the CPU. Bars and borders are cheap because most of that canvas is untouched, but a frame that paints across the entire window every frame will cost you, so favour transitions that settle over ones that loop forever.

A layer is drawn again only when Qt marks its scene dirty — something it renders changed — or while an animation in it is running. So an idle window costs a flag read, not a rasterisation. A decoration that animates continuously (pulse does, while focused) is drawn on every frame for as long as it animates. The pane styles’ README has the rest, under What it costs.

Editor completion

Solium ships a definitions file for lua-language-server, lua/meta/sol.lua, which describes every sol.* function with its arguments. Point the server at it and your editor completes sol. and checks what you pass. A .luarc.json in ~/.config/solium, beside your user.lua:

{
    "runtime.version": "Lua 5.4",
    "workspace.library": ["/usr/share/solium/lua"]
}

That is where a package puts Solium’s Lua. dev/install.sh puts it in ~/.local/share/solium/lua, and in a checkout it is crates/solium/lua; write the whole path either way. Naming the lua folder rather than lua/meta also lets the server follow require("modes") and the other shipped modules. The same file is the Lua API page of the documentation site.

Desktop modes

A mode is a Lua file. Tiling is one, scrolling is one, overview is one, and so is whatever you write. The compositor holds no opinion about any of them.

That is not a boast about extensibility — it is the architecture’s test. If a new mode needs new Rust, the transform layer is missing something, and that missing thing is the bug rather than your mode. Overview is about a hundred lines of Lua for exactly this reason: it was written to find out whether the claim was true.

Every mode above is captured by the compositor reading back its own framebuffer, in a nested session with the shipped configuration. Each row starts at the keypress and is every other frame of a burst taken twenty milliseconds apart, so the pictures are about forty milliseconds apart and a row covers the first fifth of a second. The first row is a window opening from super+return: what opens is the loading window, which the terminal fills once it has started, later than this row reaches. The other three start from three terminals on top of one another and press super+space, super+t and super+s. One engine drew all four rows, which is the whole argument on one page: a window opening, overview entering, and two layouts arranging are the same interpolation with different targets.

The two ways to move a window

Everything a mode does comes down to one of these, and picking the wrong one is the most common mistake.

sol.place(id, { x = 0, y = 0, w = 960, h = 1080 })   -- where it LIVES
sol.present(id, { x = 40, y = 40, w = 320, h = 180 })   -- where it is DRAWN

place is the layout’s authority. The window is really that size; the client is told, and asked to redraw. Use it for arrangements — tiling, scrolling, a window snapping back after a drag.

A placed rect is a tile, and the window is held inside it. A client that will not shrink as far as you asked — a terminal on its cell grid, a browser at its minimum width — is cut to the rect rather than drawn over its neighbours, and its frame and its hit test stop at the rect’s edge too. A client smaller than the rect keeps its own size. Two things let go of that:

sol.place(id, { x = 0, y = 0, w = 400, h = 300, tile = false })  -- placed, not tiled
sol.unplace(id)                                                   -- no longer tiled

tile = false is for a window you place without tiling it; dialogs.lua centres a modal over its parent that way, because a dialog that grows after it is centred must not be cut to the size it was centred at.

Two more things a placement can say, both for a window whose application has an opinion about its size (#115):

sol.place(id, { x = 880, y = 420, w = 800, h = 600,            -- the window, smaller
                tile = { x = 12, y = 12, w = 2536, h = 1416 } }) -- than the tile it has
sol.place(id, { x = 12, y = 12, w = 1262, h = 1416, cramped = true })

tile as a rect is the tile a window sits inside when it is placed smaller than it – tiling.lua does this for a window centred at its own maximum size. The window lives at the rect you place; the tile is what its client is held inside, and what a drag on the window’s edge moves the seam from, because a seam is the tile’s edge and not the window’s. cramped = true says the tile is smaller than the window’s own minimum, and comes back in sol.windows(); see An application’s own size. Each placement says it afresh, so one that does not say it is not cramped, and neither is a window placed with tile = false or let go with sol.unplace. sol.unplace is for a layout letting go, and modes.use sends it for every window whenever the layout in charge changes — so a mode registered through modes gets it for free, and one that is not must send it itself. Maximising and fullscreen take a window out of its tile on their own, and the way back puts it in again. A script cannot see that a window is maximised or fullscreen, so a layout that places every window on every pass (as tiling.apply does, and dialogs.lua for every floated window) places those too. The window itself stays where it is, over the arrangement. A tile placed is kept as the tile the window goes back into; a placement with tile = false changes nothing, so a floated window goes back to where it floated. The one placement that moves such a window is a move by key onto another monitor: see Focus and move by direction.

present is a transform. The window still lives where it lived and the client never learns anything happened; it is simply drawn somewhere else. Use it for anything temporary — overview, an app switcher, a peek, a genie. Then:

sol.present_clear(id)   -- animate back to real geometry and stop transforming

The distinction is why leaving overview is exact rather than approximate. The layout was never disturbed, so there is nothing to restore.

A present that lands exactly on the window’s own frame (no rect, no rotation, full opacity: sol.present(id, {})) lets the window go, as sol.present_clear does, rather than holding it there.

sol.present_from(id, rect) is the third: draw the window at rect and animate it to where it lives. That is every “appears from somewhere” animation — a window opening, or growing out of a dock icon.

Depth and pivot

sol.present(id, { z = 2 })                       -- drawn in front
sol.present(id, { rotate_y = 20, pivot_x = 0 })  -- turns about its left edge

z is draw order and nothing else. Equal values keep the order the stack gave them, so the default costs nothing — and a window raised above its neighbour is still clicked where the layout put it, because rect stays the truth for input. It orders windows among themselves. With fullscreen.covers = "top", the default, the front window on the workspace in view is lifted into a band of its own while it is fullscreen, above the top layer and above any window’s z.

pivot is a fraction of the window, not pixels: (0.5, 0.5) is the centre and is the default, (0, 0) the top-left corner. Each axis defaults on its own — pivot_x = 0 means the left edge and says nothing about the vertical. Outside 0..1 means what it says rather than being clamped: pivot_x = 2 hinges the window about a line off to its right, which is a door on a frame beside it.

A number that cannot be drawn with is dropped rather than drawn: a NaN depth cannot be ordered against anything, a non-finite pivot puts every corner of the window at NaN, and both fall back to the default with a line in the log. An infinite z is kept — math.huge is a legible “above everything”.

Both belong to a window, so both are sol.present keys. sol.present_group takes neither, and that is deliberate: a pivot on a selection would have to overrule each member’s own — a member is drawn through one matrix, turning about one point — and a depth would raise a desk’s windows above the desk next door while leaving its own wallpaper behind, because depth orders the windows and scripted surfaces are drawn in fixed layers. Turning a whole desk as one shape needs a rectangle for the selection, which no group has yet.

Turning, fading and bending

The rest of what sol.present takes, all of it animated by the same clock and all of it combinable with a rectangle, z and a pivot:

sol.present(id, { opacity = 0.5 })                     -- the compositor's alpha
sol.present(id, { rotate_y = 35, perspective = 900 })  -- tilted, in perspective
sol.present(id, { deform = {                           -- pulled into a rectangle
    effect = "genie", axis = "down", spread = 1.4,
    to = { x = 900, y = 1400, w = 120, h = 24 },       -- or { window = id },
} })                                                   -- or { surface = name }

opacity is the compositor’s, not the client’s: 0 draws nothing, and a window at 1/255 or less takes no clicks. rotate_x, rotate_y and rotate_z are degrees, applied in that order about the pivot, and perspective is the viewer’s distance in pixels, which is what makes a receding edge shrink rather than merely narrow. None of them moves a click: the window is still clicked across its flat rectangle.

deform bends the window with a vertex effect from crates/effects. There is one, "genie": progress from 0 (where the window is) to 1 (all of it inside to, the default), spread for how much of the window moves at once (0 is rigid, 1 by default), and axis, "down", "up", "left" or "right", for which edge leads. to is required. { window = id } and { surface = name } are looked up again on every frame, so the effect follows its target as it moves; a rectangle is fixed. A target that no longer exists draws the window flat, and an effect name this build does not have is logged and ignored. Animating to a deform starts from none, and sol.present_clear animates back out of one.

sol.present_group takes opacity and the rotation keys too, applied on top of each member’s own, and a third argument, { duration = ..., easing = ... }, for a selection that moves at its own speed.

Moving more than a window

A transform names a selection, and a selection can hold things that are not windows at all:

sol.group("desk-2", {
    windows  = { 3, 7 },          -- by id
    surfaces = { "wallpaper-2" }, -- anything sol.surface declared
    monitors = { "DP-1" },        -- everything drawn on a screen
    monitor  = "DP-1",            -- which instance of each surface above
})
sol.present_group("desk-2", { x = -2560 }, { duration = 300 })
sol.present_group_clear("desk-2")
sol.group("desk-2", false)        -- take the name away

One call, one animation, one target. The wallpaper travels because it is in the selection — the compositor has no idea what a wallpaper is, and does not need one.

Three things to know before using it:

x and y are a displacement, not a destination. sol.present takes the rectangle a window is drawn at; a selection has no rectangle of its own, so { x = -2560 } means “a screen to the left of wherever each member already is”.

It composes with each member’s own transform. A window you have also sol.presented is drawn at its own rect plus its selection’s displacement, so a window tilted inside a moving desk stays tilted within it. The corollary is the one that catches people: a mode handing absolute rectangles to a window in a carried selection is placing them in that selection’s space. That is why overview.lua shows the desk in front of you rather than every desk at once.

Membership changes are animated. A window that leaves one selection for another would otherwise have the difference between the two displacements land on it in a single frame; instead it is held where it was drawn and animates from there, the same rule sol.present follows for a window entering a mode. The duration is whatever sol.animate last set.

A selection naming a window that has closed, or a surface nothing declared, simply does not contain it. There is nothing to clean up.

What a mode is told

sol.on("open",   function(id) end)                 -- a window's life began
sol.on("surface", function(surface, action, data) end) -- a hosted scene sent an action
sol.on("closing", function(id) end)                -- a close was asked for
sol.on("refused", function(id) end)                -- ...and declined: it is back
sol.on("close",  function(id) end)                 -- it is gone
sol.on("focus",  function(id) end)                 -- the keyboard moved
sol.on("activate", function(id, why) end)          -- a window asked to come forward: "launch" or "request"
sol.on("drop",   function(id, x, y) end)           -- a drag finished
sol.on("resize", function(id, edge_x, edge_y, horizontal_side, vertical_side) end)
sol.on("scroll", function(dx, dy) end)             -- a modified wheel turn
sol.on("click",  function(x, y) end)               -- only while grabbing input
sol.on("layout", function() end)                   -- the room windows get changed
sol.on("monitors", function() end)                 -- the screens are not the screens you knew
sol.on("restore",  function() end)                 -- you have replaced a running session
sol.on("direction", function(verb, dir) end)       -- a direction key: "focus" or "move", and which way
sol.on("keyboard", function(state, changed) end)   -- the layout, Caps Lock or Num Lock changed: "layout", "caps" or "num"
sol.on("text_input", function(field, why) end)     -- the focused text field: "field", "caret" or "framed"
sol.on("fullscreen", function(id, entering) end)   -- it went fullscreen, or left: answer with sol.animate
sol.on("maximize", function(id, entering) end)     -- it was maximised, or restored: the same

Every handler, and every binding, has 100 ms, on a clock the compositor starts for each one, so nothing a handler calls puts it off: past that it is stopped with an error in the log, which names the file and line it was written at and the file and line it was stopped at, so a loop in one cannot freeze the desktop, even inside a coroutine it makes, around a pcall, xpcall or load, which hand the stop on, or around sol.focus_direction, and the other listeners still run. The direction listeners’ time counts against the handler that called sol.focus_direction or sol.move_direction, so one stopped there stops that handler too. A __gc finalizer, and the __close of a to-be-closed variable in the function a stop interrupts, run where no hook does, so the deadline cannot stop a loop in either: keep them short. A listener stopped three times stays off until super+shift+r, and so does a done of sol.act, whose stops are counted the same way, by function: a done written inline is a new function at each sol.act, so it is stopped each time rather than taken out (script::tests::a_listener_that_never_returns_is_stopped_and_the_others_still_run, script::tests::a_binding_that_never_returns_is_stopped, script::tests::a_handler_that_calls_sol_deadline_is_still_stopped, script::tests::replacing_sol_deadline_leaves_each_listener_its_own_deadline, script::tests::a_listener_that_never_returns_inside_a_coroutine_is_stopped, script::tests::a_listener_that_retries_with_pcall_is_stopped, script::tests::an_xpcall_handler_that_never_returns_is_not_called_for_the_stop, script::tests::a_listener_that_retries_load_is_stopped, script::tests::a_binding_that_loops_on_focus_direction_is_stopped, script::tests::a_direction_listener_stopped_at_the_deadline_stops_its_caller_too, script::tests::a_close_run_after_a_stop_is_not_under_the_deadline, script::tests::a_gc_finalizer_is_not_under_the_deadline, script::tests::a_stopped_listener_is_logged_with_its_file_and_line, script::tests::a_stopped_binding_is_logged_where_it_was_written_and_stopped, script::tests::a_handler_stopped_at_its_focus_direction_is_logged_at_that_call, script::tests::a_listener_stopped_three_times_is_taken_out, script::tests::a_done_stopped_three_times_is_not_called_again, script::tests::an_inline_done_is_stopped_each_time_and_never_taken_out). An actions.override is a listener actions.lua writes for you, so its stop names actions.lua as where it was written, and the override’s own line as where it was stopped (script::tests::a_stopped_override_is_logged_where_it_was_stopped).

surface is how a sol.surface declared with interactive = true talks back: its scene calls Solium.send(action, data), and you are told the surface’s name, the action and its data, a table, a value or nil, every action in the order it was sent (script::tests::a_surface_action_reaches_lua_with_its_data, state::tests::real_client::reflow_on_close::hosted::two_actions_from_one_frame_both_reach_lua_in_order); sol.act(action, data, done) performs the compositor’s verbs, and lua/actions.lua hands it the ones a scene sends (shell-boundary.md says which; ricing.md has an example). Declaring the same surface again with new properties writes them into the live scene rather than rebuilding it. keyboard and text_input are for something that reacts to typing rather than to windows: ricing.md says when each fires and with what, and lua/keyboard_indicator.lua uses both. Eight of the rest are worth reading twice.

open fires when the window opens, and for a launched window that is before its application exists. A window started with sol.spawn begins its life when the user asks for the program: your mode is told then, gets to place the window then, and the application appears inside it later. That is loading.reserves_a_slot, which is on by default. A window its application opens by itself — a second browser window, a dialog — is told at its first frame instead. Nothing special is required of you for either — but it is why open is the event that puts a window into your arrangement, and layout is not. A layout keeps its own structure and adds to it on open; layout only means “re-run what you already hold”.

A close is three events, because a close is a request. The compositor cannot take a window away; it can only ask the application to go, and an application with unsaved work puts up a dialog and stays. So:

In that order. After closing exactly one of the other two follows, and refused never follows close: once a window has gone, nothing brings it back. A refused window is an ordinary window again, and closing it a second time starts over with a second closing. A window whose application quit on its own – exit, its own Quit, a crash – was never asked, so it gets close and nothing before it; it still fades out where it stood, from what the application last showed – in front of the windows it was in front of and behind the rest – while a layout that reflows at close grows its neighbours into the space, behind it. Its row is in close’s own snapshot, leaving, and in no snapshot after.

close still means gone, and nothing else. Anything a script keeps about a window – dialogs.forget, tiling.exiled – is dropped there and not at closing, because a window that was only asked may be about to come back. refused is not open: the window never went, and nothing about an arrival should run again.

While a window is between closing and whichever comes next, its row in sol.windows() says leaving = true (and so does its row in close’s own snapshot). After close it is in no snapshot but that one. It is fading where it stood whatever you do: the compositor pins the rectangle it is drawn at, so placing it moves nothing you can see, and it stays in front of any window you move into its space – as does a refused window while it fades back in. It also stays cut to the tile it was closed in, so a client wider than that tile does not spill or squash as it fades: sol.unplace, or tile = false, on a window that is leaving waits, and takes effect if a refused close brings it back. modes.use counts on that, since it lets every window go.

The shipped layouts close up at closing, while they are the layout in charge, and put the window back at refused; reflow_on_close = "when_gone" in their section of config.lua makes both events do nothing and leaves the reflow to close, which is how every close worked before #128. Closing up at once has one cost worth knowing: the compositor waits a second for an application to go before it takes the silence for a refusal, so one slower than that to quit is refused and then closes, and the layout moves three times – at the press, at refused, and at close.

A layout that listens for neither event hears exactly what it always heard – close, once the window is gone – so a mode written before these two existed keeps working unchanged, and keeps its slot for a closing window until the application has gone. To close up at once, handle closing, leave leaving windows out of any arrangement you build from sol.windows(), and put the window back on refused.

focus is heard for a new window too, in every mode and for an X11 window as much as a Wayland one. The compositor gives a window the keyboard at its first frame, once your open handler has placed it, and only if it is headed somewhere the user can see; it does that as sol.focus would, so you hear focus for it. If your open handler calls sol.focus itself, yours is the last word and the compositor does not give it again. A window launched with sol.spawn gets it the same way when its application arrives; a sol.focus for it during open finds no application yet to give it to.

activate says a window asked to be brought forward, with an activation token such as a notification you clicked hands it, and it comes after the compositor has answered. That answer is the same whatever the token: a window on a workspace nobody is looking at, or one being closed, is refused outright – it is not focused, you hear no focus, and the keyboard stays where it was. Anywhere else it is focused first and asked afterwards: you hear focus, and if your handler brings the window into view (the scroller scrolls its column onto the screen) it keeps the keyboard. If it is still somewhere nobody can see once the layouts have had their say, the keyboard goes back to a window on screen. Then you hear activate(id, why), and why says who asked:

"launch" is Firefox, Telegram, any GTK or Qt application that keeps one instance: sol.spawn opens a window for the launch, the program passes the launch on to the instance running, and that instance brings forward the window it already has, with the launch’s own token. That window is not the launch arriving. The window opened for the launch dissolves, as one whose application never came does, and you hear its close; the window brought forward keeps its id, its workspace and its tile – a tile the launch’s window split closes up again as that window goes – and you hear no open or close for it. So the view going to it is yours to do, and workspaces.lua does it, as a dock does for an application that is running – without that, a launch whose window is on another workspace shows nothing at all. A window the application opens for the launch, one per activation or from a launcher that forks, is the launch arriving as before: it appears in the window that was opened for it, and there is no activate.

"request" is followed by nothing in the shipped scripts because nothing checks where a token came from: any client can make one for itself, and a view that followed every request would be one any application could pull away from you.

resize gives you where the dragged edge should go, not where the pointer is and not a delta. edge_x and edge_y are in the same coordinates tree:layout returns and sol.place takes — one per axis, so a corner drag’s two seams each get their own.

A position rather than a delta, deliberately: a delta would be measured against a layout your own last response just changed, and the windows shake for as long as the button is held. But a position of the edge rather than of the pointer, also deliberately, and that is #124. A seam set from the cursor lands under the cursor, so a drag begun anywhere except exactly on the edge threw that edge across to the cursor on its first frame — half a border’s width for a border drag, and most of a window for super+right-button, which starts a resize from wherever inside the window you happened to press. Handed the edge instead, the same arithmetic makes the gesture relative: the edge starts where it already is and moves as far as the pointer moves.

“Where it already is” means where you put it — the rect your last sol.place for that window carried — and not where the client drew itself. The two differ whenever a client commits a size other than the one it was asked for, which a terminal on a cell grid does every time. Hand that back on a first frame and your seam moves by the client’s rounding before the pointer has travelled a pixel, so the compositor sends your own number back to you.

On an axis this drag does not move there is no dragged edge, and the pointer’s own coordinate comes through there instead. Check the side before using the coordinate — which is what the side is for — and you will never see it.

horizontal_side and vertical_side are the sides being dragged, not the axes: "left" or "right", "top" or "bottom", and nil for an axis this drag does not move. A corner drag fills both, because a corner drag moves one seam per axis. They were booleans until #120, and a boolean cannot choose a seam: a window sitting on the right of a vertical split has that split’s seam on its left, so “the horizontal axis is in play” was true whichever edge the hand was on, and dragging the right edge moved the left one instead. Hand the side straight to tree:drag_seam.

click only arrives while you hold input. sol.grab_input(true) takes keys and clicks away from clients, which is what a mode needs while it owns the screen. Release it when you leave, or nothing will ever reach a window again.

restore fires after a reload and never at startup. That asymmetry is the event. See below.

What survives super+shift+r

A reload throws the whole Lua state away and reads your files again. The session does not go with it: the windows, the monitors, the workspace in view and the layout in charge are all still exactly what they were. So your mode comes back as a stranger to a desktop it was running a moment ago, and it is entitled to exactly two things.

Whatever you handed to sol.keep.

local state = sol.keep("my-mode", { showing = 1 })

You get the table the last load left under that name, or the defaults the first time. Mutate it in place; the host takes a copy when the reload happens. It holds plain data — numbers, strings, booleans and tables of those — and the trees and strips sol.layout.tree() and sol.layout.scroller() make, which come back whole. A function in there cannot cross and is named in the log rather than dropped in silence.

Keep as little as you can. Anything you can work out again from sol.windows() and sol.monitors() should be worked out again, because a keep is a claim about the past that nothing checks.

An arrangement is the exception, because it cannot be worked out again: the window list says which windows there are, not where the user put them. The shipped layouts keep theirs. Before they did, a reload rebuilt each one from the window list, topmost first, and windows traded places (#118). A strip that comes back still has the widths the last file gave it, so scrolling.lua hands it the new ones with view:configure(config.scrolling).

And the world, re-announced: restore, then monitors, then layout.

restore is the moment every script has loaded, which is the earliest you can touch another module’s registrations — lua/modes.lua uses it to make the remembered layout active again, which it cannot do at its own top level because lua/tiling.lua has not registered itself yet. monitors then says the screens are what they are, and layout asks you to arrange.

Without this, a reload was a quiet way to lose the session: on workspace 3 it came back believing it was on workspace 1, put every window on desk 1, and drew the desk two screen-widths off-stage with no key that brought it back. That is issue #116, and both halves above are what it cost.

What a mode can ask

sol.windows()          -- every window: id, x, y, w, h, title, focused, monitor,
                       --                modal, parent, leaving, app_id, min, max,
                       --                cramped, shown
sol.monitors()         -- every monitor: name, x, y, w, h, whole, scale,
                       --                 transform, focused, primary, power
                       --   (x, y, w, h: the work area, less layer-shell
                       --   bars and hosted reserves)
sol.monitor()          -- the active monitor's work area
sol.monitor(id)        -- the work area of the monitor that window is on
sol.cursor()           -- { x, y }
sol.window_at(x, y, skip)  -- the id under a point, optionally skipping one

sol.windows() is a snapshot taken fresh for your handler, never a live view. A window closing while you hold its id is ordinary: place and present on an id that no longer exists do nothing rather than failing.

x, y, w and h are where the window lives, which is what the layout thinks. No field says where it is being drawn: a mode that presented it somewhere else knows, because it said so. To ask what the user is looking at, ask sol.window_at, which answers by what is on screen — the rectangle each window is drawn at, whether it is visible at all, and whether the monitor under the point is showing it.

power is "on" or "off". A monitor turned off, by sol.monitor_power or by idle.screens_off_after, keeps its place, its work area and its windows, and no monitors or layout event fires for it: keep arranging it as if it were lit, because input turns it back on exactly as it was.

modal is a window that says it is a modal dialog — a save prompt, a permissions box — and parent is the window it belongs to. A layout should leave a modal out of its arrangement and put it over its parent; dialogs.lua is that policy, shared by tiling.lua and scrolling.lua so the two cannot disagree. Onto its parent’s monitor, which is not always its own: a window is mapped at the origin and belongs to whichever screen that lands on, so a dialog for a window on the second screen arrives on the first one and has to be moved off it. dialogs.place is where that is decided, from the rect it is centred on rather than from the screen it was mapped on.

Dragging one is allowed and sticks: dialogs.dropped records where it was dropped as an offset from its parent, so the prompt you pushed off the sentence it was covering stays off it, and still follows the document when the layout moves it. Staying above that document is not the layout’s business at all — the compositor keeps a modal over its parent in the stack, whatever raises what (Solium::map_stacked).

parent has three values and it is worth knowing why. It is the parent’s id when there is a window to point at, false when the client named a parent that is not on screen — not mapped yet, not ours, or closed while its dialog was still up — and absent when no parent was ever named. So if window.parent then is the right question for “have I got something to centre on”, and window.parent == false is how you tell a lost parent from no parent at all.

min and max are how small and how large the window’s own application says it can be, { w = ..., h = ... } – in the same terms as w and h, frame included, so they compare with a tile directly – and absent when it limited neither side. 0 on one side is no limit on that side. They are what the client has committed, never a size it has asked for and not yet drawn to, and a change to either re-runs layout once per change. cramped is the layout’s own word coming back: true while the layout in charge last placed the window with cramped = true. app_id is the application’s name for itself – a Wayland application’s app_id, an X11 one’s WM_CLASS class – and empty until the application has arrived. shown is whether the application has been shown yet: false for a window launched with sol.spawn from its open until its application’s first frame, which is how a layout tells limits that arrive in time to decide where a window goes from limits that changed on a window already on screen.

skip on window_at exists because of one specific bug: a new window is already mapped and under the pointer, so asking “what am I pointing at” without skipping it names the window as its own split target.

A layout runs per monitor

There is one global coordinate space and every monitor is a rectangle in it. That is the whole mechanism: a window is on the second screen because its x lands there. There is no per-screen coordinate system and nothing to convert.

The consequence is the thing to get right. sol.monitor() answers one screen, so a mode that lays every window out against it piles both monitors’ worth of windows onto whichever one the pointer happens to be on. A layout is per monitor:

local monitors = require("monitors")

for _, each in ipairs(monitors.each()) do
    -- each.monitor is the rect; each.windows are the windows on it
end

monitors.each() always lists every monitor, including one with nothing on it — a layout has to hear about an empty screen, because that is what tells it the last window left.

Anything stateful is keyed by monitor as well as workspace. tiling.lua keeps a dwindle tree per pair and scrolling.lua a strip, via monitors.key:

local function tree_for(monitor)
    local key = monitors.key(workspaces.on(monitor), monitor)
    ...
end

Two reasons, and the second is the one that bites. The screens are different sizes, so a split or a column width that reads well on one is wrong on the other. And a window moved across has to leave one arrangement and join the other: a window in two trees is a window given two slots, and it ends up in whichever was laid out last. adopt is where that settles — missing from its new screen’s tree, still in its old one’s, both halves fixed in one pass.

One sol.animate for every screen. Two monitors rearranging at once is one movement; see animation.md on why the feel is set per batch and not per window.

A window is drawn only on the monitors it lives on

Its slot decides that, not its transform. A transform can move a window around its own monitors and off them; it cannot put it on somebody else’s.

This is worth knowing before you write a mode that moves a window a long way, because it is what makes such a mode work on more than one screen. Workspaces are the example. A workspace switch does not move windows — it draws the ones belonging to other workspaces a screen away, and with one monitor “a screen away” is off the desktop, which is how they are hidden. With two side by side, one screen away is the other monitor: switching the left screen’s workspace threw its windows onto the right screen, on top of what was already there.

The intent was always containment; one screen just made moving and hiding the same thing. So the rule is enforced where it belongs, and the slide stays one screen long — which is what makes it read as a slide. Offsetting by the whole desk instead would hide them correctly and look wrong: the window would leave the screen halfway through and the next arrive halfway through, with empty screen in between.

The slot and not the drawn rect, so a window straddling the bezel — dragged between screens, where the slot itself is on both — is still drawn on both.

Workspaces

config.workspaces.per_monitor decides whether each screen has its own workspace in view. On by default: super+2 switches the monitor the pointer is on and leaves the other showing what it was. Off, one switch moves every screen.

Both are real desktops, and the difference is what you take a workspace to be — a screenful, or a whole desk. workspaces.lua shares every line between them: which workspace a monitor shows is looked up by monitor either way, and with the setting off every monitor looks up the same entry.

Launching an application that is already running goes to its window where it is: workspaces.lua shows that window’s workspace on the window’s own monitor – so with per_monitor on, the screen in front of you goes on showing what it was if the window is on the other – and focuses it. That is its activate handler; see What a mode is told.

A workspace is a selection, one per monitor per workspace, named desk-<n>@<connector>. workspaces.lua declares it from the windows on that desk plus that desk’s background, and carries it with a single sol.present_group — which is why a per-workspace wallpaper travels with the switch. Set config.wallpaper to a list of images to get one; a single image belongs to the monitor and stays put, because every desk sharing one picture makes a wallpaper that slides indistinguishable from one that does not.

If you keep per-workspace state of your own, key it by monitor as well. monitors.key(workspaces.on(name), name) is the string tiling.lua and scrolling.lua both use, and tree_for takes only the monitor — the workspace that screen is showing is something workspaces knows, and threading it through every call site is how one of them ends up asking for the wrong screen’s.

workspaces.lua declares the workspaces it keeps with sol.workspaces{ arrangement, groups, windows } whenever they change, which is how a hosted shell’s Workspaces and WorkspaceList know them, and it answers workspaces.go and windows.send from a scene through actions.lua, when the configuration keeps that file and requires it before workspaces, as the shipped init.lua does: workspaces.lua looks for it once, as it loads. Without it, the configuration routes a scene’s actions itself, and workspaces.lua does not route them a second time. A configuration that keeps workspaces some other way, tags say, declares those, each <group>/<id> once. See shell-boundary.md.

monitors.active() is the monitor the pointer is on — where a new window goes, and what a binding pressed with no particular window in mind is about. It is the pointer and not the focused window on purpose: look at the second screen, click the empty desktop, press the key for a terminal, and a focus-based rule would open it on the screen you just looked away from.

The primary flag is a different question and answers a different one: it is where things belonging to one screen go — a layer surface that named no output, or a hosted shell or sol.surface declared with on = "primary". The hosted shell is on every monitor unless shell.on names one. It does not move, which is the whole point of it. See shell-boundary.md.

x, y, w, h are the work area — the monitor less whatever bars have reserved, layer-shell clients and hosted surfaces alike — and whole is the monitor itself, which is what a wallpaper or a fullscreen window covers. Both are in the global space, so either can be handed straight to sol.place. Copy the rect before adding keys to it; the one you were given belongs to the snapshot.

Focus and move by direction

sol.focus_direction("left")   -- or "right", "up", "down"
sol.move_direction("left")
sol.toggle_fullscreen(id)     -- fullscreen, or back; the focused window with no id
sol.toggle_maximize(id)       -- maximised, or back; the focused window with no id

The compositor does nothing with these but tell every direction listener the verb and the direction, and a direction that is not one of the four is an error. lua/direction.lua is the listener that ships, and it asks the layout in charge, by two functions on the table you gave modes.register:

function mine.focus_direction(dir) ... return true end
function mine.move_direction(dir) ... return true end

Answer false, or leave either out, and the key gets what a desktop with no layout in charge gets: focus goes to the nearest window that way, and a move trades places with it, each window keeping its size. tiling.lua answers false for focus from a window it does not tile – a dialog, or one floated with super+shift+space – so the keyboard still finds its way out of one.

Which window is that way depends on what kind of windows they are. A tile’s neighbour is wholly past its edge and level with some of it – a tile below and to one side is not to its side – and the nearest facing edge wins. Floating windows overlap and sit off on diagonals, so for them, failing any such neighbour, the nearest centre further that way counts too.

At a monitor’s edge both go on to the next monitor that way, and the desk it is showing. The next monitor is one wholly past this one’s edge, as wlroots has it: a portrait screen standing beside a landscape one is beside it and never below, and a smaller screen top-aligned next to a bigger one is above nothing. Of two that way, the one level with the window wins, so with two screens stacked beside a big one the window’s own height picks between them. On the next monitor the nearest centre counts for tiles as well, since a screen of another height may have nothing level with the window.

direction.find(from, dir, on, loose) is that search, for a layout’s own rectangles: on(name) lists them for a monitor, loose is the floating rule, and you get back the nearest, its monitor, and whether that meant crossing to another one.

Across a monitor a move takes the window alone: into the tile it arrives beside in tiling, into a column of its own in scrolling, and as far across the new screen as it was across the old one with no layout. The shipped keys, all of them replaceable in config.bindings:

Moving up on k is super+alt+k because super+shift+k cycles the keyboard layout. A window floated with super+shift+space is, to both layouts, what a dialog with no parent is: out of the arrangement, centred on its screen at the size it had, until the key puts it back. It stays floated through a reload.

super+shift+m on a fullscreen window leaves fullscreen for maximised, or, for one that was maximised before it went fullscreen, for where it was before either. super+f and super+shift+m act on Wayland windows only for now: an X11 window under XWayland does not go fullscreen or maximised by key.

A fullscreen or maximised window stays so when it is moved. On its own monitor the move happens behind it: in tiling it trades tiles with the one that way, and leaving fullscreen or maximised goes into the tile it has now. Onto another monitor it is fullscreen or maximised there, drawn on the workspace that monitor shows and keeping the keyboard, and leaving stays on that monitor: in its tile there, or with no layout at the same place on the new screen as it had on the old one. A window floated with super+shift+space and then made fullscreen stays fullscreen through every layout pass, and leaving goes back to where it floated.

Going fullscreen or maximised, and back

The compositor makes the change and the scripts choose how it looks. On the key, or when an application asks, the window is told its new size at once and lives at its new rectangle – the whole monitor it is on, its work area, or the place or tile it came from. Then fullscreen or maximize is told, (id, entering), and once every listener has run the window’s picture glides there from wherever it is drawn, through the same transform a layout’s glide uses, with the timing a listener set with sol.animate. With none set, the change is instant:

sol.on("fullscreen", function(id, entering)
    sol.animate({ duration = 260, easing = "outCubic" })
end)

lua/fullscreen.lua is the listener that ships, reading fullscreen and maximize in config.lua – animate, or false, and instant.app_id, each section on its own (ricing.md). The rest is the compositor’s, whatever the listener says:

• From what is on screen. Pressing the key again half way turns the window round where it is drawn, not where it was headed or where it came from (state::tests::real_client::fullscreen_glides::a_second_toggle_mid_flight_starts_from_where_the_window_is_drawn).
• Answered at once. The application is configured on the key, not when the glide lands (state::tests::real_client::fullscreen_glides::the_client_is_told_its_new_size_on_the_toggle), and the window is held at its new rectangle until the application draws at that size, as a window whose edge you drag is: its last picture is stretched into the rectangle the glide has reached, and after the glide lands, into the rectangle it landed on (state::tests::real_client::fullscreen_glides::a_slow_client_is_drawn_stretched_until_it_answers). An application that says nothing is held a quarter of a second past the landing, and then shown at the size it has (state::tests::real_client::fullscreen_glides::a_client_that_never_answers_is_drawn_as_it_is_once_its_patience_runs_out); an edge drag on it takes it over (state::tests::real_client::fullscreen_glides::an_edge_drag_takes_a_window_its_change_is_holding).
• Plain at rest. The transform is released when the glide lands, so a fullscreen game or video is drawn with nothing in between (state::tests::real_client::fullscreen_glides::a_window_glides_into_fullscreen_and_out_again). A monitor unplugged, a reload or a lock part of the way through changes that for nobody: the window comes to rest all the same (state::tests::real_client::fullscreen_glides::a_monitor_unplugged_mid_glide_leaves_the_window_at_rest, state::tests::real_client::fullscreen_glides::a_reload_mid_glide_leaves_the_window_at_rest, state::tests::real_client::lock_focus::a_lock_mid_glide_leaves_the_window_at_rest).
• Instant is nothing at all. A change with no motion – animate = false, an application on the instant list, no listener – puts no transform on the window and holds nothing: the next frame draws it as it is, as before the glide existed, and stops one in flight (state::tests::real_client::fullscreen_glides::an_instant_change_draws_the_window_as_it_is_on_the_next_frame, state::tests::real_client::fullscreen_glides::an_instant_change_part_of_the_way_through_a_glide_holds_nothing).
• Turned round, it keeps its way back. Pressed again before the application has drawn at the size it went back to, the rectangle kept for the next way out is the one it was told, not the monitor’s it has not left yet (state::tests::real_client::fullscreen_glides::turning_round_part_of_the_way_out_keeps_the_way_back).
• On its own monitor. A window grows to cover the monitor it is on, and shrinks back on it (state::tests::real_client::fullscreen_glides::a_window_on_the_second_monitor_glides_to_cover_that_one).
• Over the bars while it is big. A window going fullscreen goes over the bars as it starts to grow, and one leaving goes back under them once it has finished shrinking; a press goes to what is drawn there (state::tests::real_client::reflow_on_close::stacking::a_window_is_lifted_as_it_starts_to_grow_and_dropped_once_it_has_shrunk).
• Into its tile with its own motion. A window going back into a tile is placed by the layout, and the change’s glide replaces the layout’s (tests/scenarios/fullscreen-tiled.lua). It shrinks in front of its neighbours, whichever the layout placed last, and a sweep part of the way through leaves it there (state::tests::real_client::a_tiled_window_leaving_fullscreen_stays_in_front_while_it_shrinks).
• Not told twice. A listener that toggles the window back has that done at once and is not told it (state::tests::real_client::fullscreen_glides::a_listener_that_toggles_the_change_back_is_not_told_it_again).

The compositor’s move comes after the listeners’ commands, so a sol.present of the window in one is replaced by it. A window a mode was already presenting before the change – a thumbnail in the overview – is left where the mode draws it: the change is made, and the mode’s sol.present_clear brings the window to its new rectangle (state::tests::real_client::fullscreen_glides::a_window_a_mode_presents_stays_where_the_mode_draws_it).

The arrangements that ship

You do not have to compute geometry yourself.

local slots = sol.layout.grid(windows, area)          -- overview's grid
local slots = sol.layout.master_stack(count, area)    -- one big, the rest beside
local slots = sol.layout.strip(columns, area)         -- a row, with an offset

These are pure: windows in, rectangles out. Two are not, and cannot be:

local tree = sol.layout.tree()        -- dwindle
local scroller = sol.layout.scroller(config.scrolling)  -- niri's model

A dwindle tree is stateful because the arrangement is. Where a window lands depends on which window was split and where the pointer was, and no function of “how many windows are there” can recover that afterwards. Same for a scroller: which column is active and where the view sits relative to it are not in the window list.

They are held by the script that made one, not by the compositor:

tree:insert(id, target, x, y, options)
tree:insert_fitting(id, target, x, y, options)  -- the same, if it keeps options.minimum
tree:insert_largest(id, options)                -- the largest tile with room
tree:remove(id)
tree:contains(id)
tree:windows()
tree:layout(options)      -- the slots, to hand to sol.place; cramped = true on a
                          -- slot smaller than its window's own floor
tree:resize(id, "width", share, options)               -- keyboard: an axis
tree:drag_seam(id, "right", edge_x, edge_y, options)   -- pointer: a side
tree:swap(a, b)           -- two windows trade tiles; every split keeps its ratio

insert splits whatever it is pointed at, however small that leaves the halves. insert_fitting and insert_largest refuse a split that would leave a tile under options.minimum – { w = ..., h = ... }, frame included – and answer false with the tree untouched, so a layout can try one, then the other, then fall back to insert. That is what tiling.lua does; see below.

The two resize calls take different things on purpose. A drag names a side — the hand is on one specific edge, and which seam moves follows from that. A keypress names only an axis: super+equal means “wider” and says nothing about which neighbour gives up the room, so resize prefers the seam on the right or below and falls back to the other, with positive share always growing the window. Either way, a window flush against its container on that side has no seam there and nothing happens — the screen edge is not a seam.

drag_seam puts the named side of that window at edge_x (for "left" and "right") or edge_y (for "top" and "bottom"), reading only the one its side names — which is what lets a corner drag call it twice with one pair and have each axis take its own. Hand it the edge_x, edge_y a resize gave you and the gesture is relative; hand it the pointer and you have rebuilt #124. The ratio it computes is separately clamped to 0.05..0.95, so a window shoved hard against a seam stops there rather than vanishing, and to whatever keeps every tile on either side of the seam at options.minimum. Those clamps are the only bounds on a tiled drag: the compositor sends an unfloored edge, deliberately, because a floor measured in a window’s pixels cannot bound a seam’s position — see Tiling::drag_seam. A tile already under the minimum is not snapped up to it when grabbed, which would move it on the first frame: it cannot be shrunk further, and can be grown only while the tiles across the seam have room to give. A seam with a tile under the minimum on both sides therefore does not move at all, and that is what "allow" below usually leaves, since it halves a tile too small to split. resize is bounded the same way when it is given options; without them, as a script written before #134 calls it, only 0.05..0.95 applies.

options.floors is each window’s own floor, { [id] = { w = ..., h = ... } }, frame included: the smallest its application says it can be, or nothing for a window with no entry. Every call that takes options reads it. The tree lays each split out at the ratio it holds, then moves it just far enough for a window under its floor to reach it, taking the room from the other side down to its floors and options.minimum, and no further; the ratio it holds is left alone, so a window whose floor goes away hands the room back. insert_fitting and insert_largest refuse a split that would leave either window under its floor, and a seam stops at the floors beside it. A window the room is not there for is laid out short, and its slot says cramped = true. The scroller reads options.floors too, and never lays a column out narrower than the widest floor in it.

options is a monitor’s work area with gap, split, minimum and floors added — and, for the other arrangements, ratio (the master window’s share, for master_stack), column (a column’s share, for sol.layout.scrolling) and padding (around each thumbnail, for grid). Passing the monitor in rather than the tree asking for it is what lets one tree per workspace per monitor exist without any of them knowing about either. Copy the rect before adding keys — the one from sol.monitors() belongs to the snapshot.

A scroller holds columns, and each column holds windows stacked top to bottom:

scroller:insert(id, options)              -- a new column, right of the active one
scroller:insert_into_column(id, options)  -- into the active column instead
scroller:remove(id)
scroller:focus_window(id, options)        -- focus it, and bring its column into view
scroller:focus_sideways(by, options)      -- by columns: -1 left, 1 right
scroller:focus_vertically(by)             -- within the active column
scroller:move_column(by, options)         -- swap the active column with a neighbour
scroller:consume()                        -- pull the next column's focused window in
scroller:expel(options)                   -- push the focused window out into a column
scroller:move_to_column_of(id, target, options)  -- what a drop means here
scroller:widen(id, by, options)           -- by a share of the view, clamped
scroller:cycle_width(options)             -- through config.scrolling.widths
scroller:configure(config.scrolling)      -- new widths, same columns and view
scroller:scroll_by(dx)                    -- move the view, not the focus
scroller:focused()
scroller:contains(id)
scroller:windows()                        -- left to right, then top to bottom
scroller:layout(options)                  -- the slots, to hand to sol.place

Every column shares one width, so widen on any window in a column widens the column. Calls that move the focus to a column also bring it into view, which is what keeps a focused column from hanging off the edge of the screen. configure is for a strip sol.keep carried across a reload, which is not made again and would otherwise go on with the widths of the file it was made from.

Three more pure helpers sit beside strip: sol.layout.scrolling(count, options) lays out count columns, each options.column of the width, and sol.layout.scroll_to and sol.layout.strip_scroll_to answer how far to scroll to bring a column into view.

When a new window has no room

tiling.lua gives a new window the tile under the pointer, split across its longer side. When that would leave a tile under config.tiling.minimum it tries the tile’s other side — a wide, short tile with no room side by side may still have room one above the other — and when neither has room it works through config.tiling.overflow, in order, until a step places the window:

The default is { "largest", "workspace", "allow" }. A list that runs out ends in "allow" regardless, with a line in the log, because a window has to go somewhere.

“Empty” does not count a window that is being closed, unless reflow_on_close = "when_gone" is keeping its tile. With workspaces.per_monitor off it means empty on every screen, since that workspace is every screen at once. A window that belongs to no workspace in particular is on every one — the view carries it along — so it leaves none empty; with workspaces.follow_new_windows off every window is one. The workspaces are the fixed set workspaces.count() describes, so nothing is ever created.

With follow_overflow on, the view goes with the window as workspaces.go takes it, and the keyboard goes to the window. For a window launched with sol.spawn that happens when its application arrives: until then there is no client to give it to, and the keyboard can still be on the window the view has just left. Off, the window is placed in its tile over there, and the view and the keyboard stay where they were — the compositor gives a new window the keyboard only if it is headed somewhere the user can see. Each window with no room then goes to another empty workspace, since the one the window before went to is no longer empty, whether or not it has room.

The decision is made at open. For a window launched with sol.spawn that is before its application has connected, so a window that overflows is placed in its final tile, on its final workspace, in the same dispatch that opens it – not in this workspace first and moved later.

Only a window being opened overflows, and only while tiling is the layout in charge. Everything that puts an existing window back into a tree — tiling.adopt on switching tiling on, on a reload and on a monitor change; refused, for a close the application declined; a dialog that stops being modal; a drop — never sends it to another workspace, whatever the list says. One that has nowhere in particular to go takes the tile insert would choose, either way, then "largest", then "allow". A refused window and a dropped one go back to the tile they were in or were let go over, either way, and below the minimum if that is what it takes: the largest tile is somewhere else, and a refused window’s arrangement has to come back as it was. And while floating or scrolling is in charge, tiling.lua still keeps new windows in its trees for later, the same way, without sending any of them anywhere.

The minimum is a tile’s, not an application’s: the tile is decided before any application exists to have an opinion. An application’s own minimum is the next section.

An application’s own size

Some applications will not go under a size – Firefox has a minimum width – and a few will not go over one, and they say so. Before #115 nobody listened: the tile was split as though the application had said nothing, the application drew itself at the size it insisted on, and that tile and every one beside it were wrong. sol.windows() has the two sizes now, and tiling.lua listens by default. You have the last word and not the application, so all three settings in config.tiling are yours:

Anything but "ignore" is read as the default. Respecting a minimum means:

• a window under it is given a larger share, taken from the windows beside it, down to their own minimums and minimum and no further; the share goes back when the application’s minimum does;
• a new window that would crowd one goes where overflow says, since a split that leaves either window under its minimum is refused like one that leaves a tile under minimum. A window launched with sol.spawn has no application yet when it is placed, so only the minimums of the windows it would split are known then. Its own arrives with its application’s first commit, before its first frame: the tile it was given is rebalanced for it, and if that still leaves it cramped it is taken out and placed again, once, by the same rule – the tile under the pointer where it was launched, then overflow;
• a window whose minimum grows gets the arrangement rebalanced around it, the moment the application commits it;
• a seam stops where a window beside it reaches its minimum, by the drag and by the keyboard;
• and in the scrolling layout, a column is never narrower than the widest minimum in it.

A centred window’s edge still drags the seam, from the tile’s edge: tiling.lua places it with its tile as tile. And a floating window’s edge drag stops at its application’s minimum and maximum, because the frame would otherwise show a size the application is about to refuse. That one is the compositor’s, not a layout’s, so it has a setting of its own, and sizes.lua hands it over as it loads, with client_size_ignore, through sol.client_sizes:

An application in tiling.client_size_ignore is not believed there either.

Cramped. When the room is not there – two windows that each need more than half the screen, side by side – the window is laid out smaller than its minimum anyway. Its application draws itself at the size it insists on and the picture is cut to the tile (#133), so it still does not cover its neighbours. tiling.lua says so once in the log, with the numbers:

tiling: window 1 needs at least 2500 wide, frame included, and its tile is 2364x1416; it is cramped, and its application's picture is cut to the tile

and places the window with cramped = true, which sol.windows() then says until the window has room again. A layout that says it is also run once more by the compositor, so a handler reading sol.windows() in that same layout pass sees it. A bar that wants to show it reads it there:

-- A strip across the top that names the windows short of room.
local function show_cramped()
    local short = {}
    for _, window in ipairs(sol.windows()) do
        if window.cramped and not window.leaving then
            short[#short + 1] = window.title
        end
    end
    local screen = sol.monitor()
    sol.surface("cramped", {
        scene = "cramped.qml",
        layer = "top",
        on = { x = screen.x, y = screen.y, w = screen.w, h = 24 },
        properties = { windows = table.concat(short, ", ") },
    })
end
sol.on("layout", show_cramped)
-- A window going is not a `layout`, and `close` still lists it, as leaving.
sol.on("close", show_cramped)

Re-declaring a surface with the same properties changes nothing, and a changed list is written into the live scene rather than rebuilding it; cramped.qml is any scene with a required property string windows. On the top layer the strip goes under a fullscreen window, as a bar does (fullscreen.covers); overlay keeps it over one. A window that is cramped and then has room again is named in the log again the next time it is short.

A whole mode

Above: three tiled windows at rest with their QML frames, super+space into overview, and super+space again, each a second after the key. The last frame differs from the first by zero pixels (magick compare -metric AE on the two captures), which is the property that matters — a mode that cannot put the desktop back exactly is a mode nobody will use twice. All of it is lua/overview.lua.

This is real and it works. Save it as ~/.config/solium/mymode.lua. A mode is loaded by init.lua, and the shipped one does not know about yours, so copy the shipped init.lua to ~/.config/solium/init.lua — it is share/solium/lua/init.lua under the prefix Solium was installed to (/usr for the Fedora package, ~/.local for dev/install.sh), and crates/solium/lua/init.lua in a checkout — and add require("mymode") after its require("scrolling"). Your copy then replaces the shipped file entirely: it keeps what it had when you copied it and does not pick up what a later version adds, so compare the two after an update.

-- Two columns on every monitor: the most recently raised window on the right,
-- the rest stacked on the left. Dialogs float over the window they belong to.
local modes = require("modes")
local monitors = require("monitors")
local workspaces = require("workspaces")
local dialogs = require("dialogs")

local mine = { active = false }
local gap = 12

local function arrange()
    if not mine.active then return end

    -- The desk each monitor is showing, without windows on their way out.
    local shown = {}
    for _, window in ipairs(workspaces.visible()) do
        if not window.leaving then
            shown[#shown + 1] = window
        end
    end

    sol.animate({ duration = 220, easing = "outCubic" })

    local placed = {}
    local function put(id, rect)
        sol.place(id, rect)
        placed[id] = rect
    end

    for _, each in ipairs(monitors.each(shown)) do
        local area = each.monitor
        local windows = {}
        for _, window in ipairs(each.windows) do
            if not dialogs.floats(window) then
                windows[#windows + 1] = window
            end
        end

        if #windows > 0 then
            local half = (area.w - gap * 3) / 2
            -- The most recently raised window takes the right half.
            put(windows[1].id, {
                x = area.x + gap * 2 + half, y = area.y + gap,
                w = half, h = area.h - gap * 2,
            })
            -- The rest share the left half, top to bottom.
            local rest = #windows - 1
            if rest > 0 then
                local tall = (area.h - gap * (rest + 1)) / rest
                for index = 2, #windows do
                    put(windows[index].id, {
                        x = area.x + gap,
                        y = area.y + gap + (index - 2) * (tall + gap),
                        w = half, h = tall,
                    })
                end
            end
        end
    end

    -- Dialogs last, over whatever they belong to, on that window's screen.
    dialogs.place(shown, monitors.named, placed)
end

sol.on("open",   arrange)
sol.on("close",  arrange)
sol.on("layout", arrange)

function mine.started() arrange() end
function mine.toggle() modes.use("mine") end

modes.register("mine", mine)
sol.bind("super+y", mine.toggle)

return mine

Seven things in there are the conventions rather than the content.

Register with modes, do not keep your own on/off flag. A layout is a choice of one. Two layouts both placing every window means the second one to run wins and the arrangement looks like whichever that happened to be — and switching away from one leaves its windows where it put them. modes.use(name) turns the others off, calls their stopped, lets every window out of its tile, and calls your started. Calling it with the mode already current falls back to floating, so one key toggles.

Guard on active. Your handlers stay registered when your mode is off.

sol.animate before the batch, not per window. It applies to everything queued after it, so every window in one arrangement moves over the same interval on the same clock. Setting it per window is how an arrangement ends up looking like several separate animations that happen to overlap.

Only the desk in view. sol.windows() lists the windows of every workspace; workspaces.visible keeps the ones on the desk their monitor is showing. The others stay where they were last placed, and are carried a screen away by the workspace’s own selection, so a slot given to one of them is a hole on the desk you are looking at.

One monitor at a time. monitors.each hands you each screen with its own windows, and each.monitor is that screen’s work area. Laying everything out against sol.monitor() piles every screen’s windows onto the one the pointer is on.

Skip what is leaving, and leave dialogs to dialogs. A window being closed is still in the snapshot, leaving = true — close’s own snapshot included — and a layout that places it keeps room for a window that is going. A modal dialog belongs over its parent, and dialogs.place puts it there, on the parent’s screen, once every arrangement has been decided.

Most recently raised first. sol.windows() is topmost-first, which is the order a hit test wants. That is not the same as newest: clicking an older window raises it, and it becomes windows[1].

Modes that are not layouts

overview.lua is worth reading as the other shape a mode takes: it grabs input, transforms every window onto a grid with present, and clears them on the way out. It never calls place, so the layout underneath is untouched and leaving is exact.

It binds escape on the way in and takes it away with sol.unbind on the way out, because a bound key never reaches the application with the keyboard: bound for good, Escape was taken from every window (#174). Whether it is up is kept with sol.keep, because the grab and the thumbnails outlive super+shift+r, so a reload with the overview open binds Escape again, and Escape still leaves it. A mode that needs a key only while it is up should do the same.

That file is also the architecture’s proof, and its comment says so — the app switcher is that with a row instead of a grid, peek is it with one window at the cursor, and the icon-to-window genie is it with a dock icon named as the thing the window comes out of. If any of those ever needs new Rust, the transform layer is missing something.

Worth knowing

solium --check prints every binding it registered and will tell you an edit dropped one. super+shift+r reloads while the session runs, so a mode can be written against a desktop you are using.

A configuration that fails to load is reported with the file and the line, and the running session keeps whatever it already had. A typo costs a line of output rather than your windows.

See also: animation.md for how the feel is configured, ricing.md for the settings a mode should read rather than hardcode.

Animation

There is one animation engine and one clock. Every window that moves — a tiling rearrangement, entering overview, a window opening or closing, the genie super+m plays — moves through the same code. That is not tidiness: it is why modes cannot animate inconsistently with each other, which is the usual way a desktop ends up feeling assembled rather than designed.

The shape of it

An animation is a duration and a curve, and it is set on the batch rather than on the window:

sol.animate({ duration = 240, easing = "outCubic" })
sol.place(a.id, slot_a)
sol.place(b.id, slot_b)
sol.place(c.id, slot_c)

Everything queued after sol.animate uses it. Three windows rearranging is one movement over one interval on one clock — set the feel per window and you get three animations that happen to overlap, which looks like it.

duration is milliseconds. Leave either key out and that half keeps what it had.

Curves

Sampled from the engine itself rather than drawn to illustrate it, so what is plotted is what runs: each panel is Curve::at from crates/animation, for every curve Curve::all() names. The five with a fixed shape are drawn over 400 ms, and would take whatever duration they are given; the spring is drawn over the 445 ms Spring::settle_time says it takes, which for a spring is an outcome rather than a setting. dev/preview plots any of them live from the same engine, one at a time, and is the thing to reach for.

Six have names:

The distinction between outBack and inOutQuad is the one worth internalising. A window arriving wants a little overshoot — it reads as landing. A window travelling from one place to another wants easing at both ends — overshoot on something that was already on screen reads as a wobble.

inOutCubic is inOutQuad with more of both ends: it holds back longer at each and crosses the middle faster. Reach for it when the distance is the point — the super+m genie pulls a window across most of the screen into a strip at its bottom edge, and wants to feel like it — and for inOutQuad when a window is only moving between two slots.

spring ignores duration entirely; a spring arrives when it arrives. Its parameters (stiffness, damping, mass, initial velocity) are not settable from Lua yet — you get the default, which settles in a little under half a second (445 ms) with a small overshoot. A gesture’s throw speed belongs in its initial velocity and that is why the parameter exists; wiring it to a real gesture belongs to the touch and gestures epic, #7, after v0.1.0.

Any curve at all

Four numbers instead of a name, and they are the two control points of a cubic bezier from (0,0) to (1,1):

sol.animate({ duration = 220, easing = { 0.34, 1.56, 0.64, 1 } })

These are exactly the four numbers CSS calls cubic-bezier, so a feel you found on any easing site transfers directly by pasting it. The named curves above are the ones worth a name; this exists so that a feel nobody anticipated does not need a compositor release.

y may leave 0..1 — that is what overshoot is. x is clamped to 0..1, because x outside that is not a curve a clock can walk along: time would have to run backwards to reach it.

Give it something that is neither a name nor four numbers and it warns and keeps the default rather than failing. Give it an unknown name and the same. A wrong easing should cost you a line in the log, not the session.

Where the feel actually lives

Almost none of it should be in your mode. config.lua declares it, and your mode reads it:

tiling = {
    motion = { duration = 240, easing = "outCubic" },
    -- The shorter feel for a window snapping back after a drag.
    snap = { duration = 180, easing = "outCubic" },
},
scrolling = {
    motion = { duration = 260, easing = "outCubic" },
    snap = { duration = 200, easing = "outCubic" },
},
workspaces = { motion = { duration = 300, easing = "outCubic" } },
open      = { motion = { duration = 220, easing = "outBack" }, scale = 0.88 },
loading   = { fade = 180 },
fullscreen = { animate = { duration = 260, easing = "outCubic" }, instant = { app_id = {} } },
maximize   = { animate = { duration = 220, easing = "outCubic" }, instant = { app_id = {} } },

These are the numbers config.lua really has. The block used to print open as 200 / outCubic / 0.92 and to carry a dock = { morph = ... } line, and #117 deleted both from config.lua for the same reason: nothing read either of them. open.lua held 220 / outBack / 0.88 as local constants, so the advertised numbers described an animation nobody had ever seen, and the script’s won when the two were wired together — those are what the animation was tuned against. There is no dock, so dock.morph configured a component that does not exist, and --check now reports that spelling as an unrecognised key.

So changing how tiling feels is one line in ~/.config/solium/user.lua:

return { tiling = { motion = { duration = 160, easing = "outBack" } } }

A mode that hardcodes its own durations is a mode nobody can tune, which is the whole reason these are here rather than in the Lua that uses them. tiling.lua takes config.tiling.motion and passes it straight to sol.animate; that is the pattern to copy.

Two of them are worth explaining because the reason for the number is not obvious:

• snap is shorter than motion. A window returning after a drag is answering something you just did with your hand, and a long animation there reads as lag rather than polish.
• open overshoots, and is the only one that does. outBack goes past the window’s real size and settles back, which is why it starts at 0.88 rather than nearer 1 — a small overshoot needs somewhere to have come from.

Closing

A window you close shrinks to 0.86 of its size and fades out over 190 ms, on inOutQuad (present::CLOSING). The compositor plays that before it tells the application to close, so the window can still paint while it goes, and by default the layout moves the other windows into its place at once (reflow_on_close; modes.md has the events). A window whose own application closes it fades the same way, from the last picture it drew (#126), and so does a loading window whose application never arrives, once loading.patience runs out.

An application can refuse: by saying nothing for a second after it is asked, or by answering with a dialog. Then the window comes back. A layout that puts it back moves it over the layout’s own duration; if nothing places it, it fades back in where it vanished over 150 ms, on outCubic.

None of these numbers is in config.lua yet, so none can be tuned: they are the exception to the rule above, and so are overview’s 260 and 200 ms, which live in overview.lua.

Animations you should not write

Some things must not be animated, and the reasons are worth knowing before you try:

A resize you are dragging. input/resize.rs says it in a comment: the window has to be under the pointer’s corner this frame. An animation puts it where the pointer was a hundred milliseconds ago, which reads as lag rather than as polish. tiling.lua passes { duration = 0 } while a seam is being dragged for exactly this reason. Animate motion the user did not personally drag.

A locked pointer. Nothing to animate — the cursor does not move at all, which is the point of a lock.

A scene fading itself out. The dissolve from a loading window to its application is the compositor’s, not the scene’s. Whether a window is see-through is a presentation transform, like where it is and how big, so the compositor applies it to the scene’s picture as it draws it. On the software renderer a scene could not do it anyway: Qt repaints only what it thinks changed, onto the pixels already there, so each half-transparent frame lands on its own opaque previous one and nothing fades. loading.fade is the setting.

What it costs

Drawing is damage-driven: a still screen draws nothing at all. An animation therefore has to ask for the next frame, and everything in the engine does — but it means an animation that never ends is a compositor that never stops drawing. The pulse pane style animates continuously while its window is focused, and keeps the compositor drawing for as long as it does. That is a fair trade you are making knowingly; making it by accident is not.

The clock is read fresh rather than sampled once per frame, and there is a test asserting so. That is not an optimisation, it is a correctness property: a cached clock froze whenever the screen was still, so a binding pressed after a quiet minute started its animation a minute in the past and was already finished by the time anything drew it. Animations that work only if you have been doing something are worse than none.

QML runs on the same clock. An animation in a pane style, a sol.surface scene or a hosted shell advances on the compositor’s clock, which each frame brings up to date before Qt’s events are delivered, so it cannot drift against the window transforms beside it. Between frames, the compositor’s own event loop serves Qt’s timers and the descriptors Qt waits on, on that same clock. So a QML Timer fires on time on an idle desktop, and costs a frame only when it changes what the scene draws (#164). The keyboard pill’s timed hide is such a Timer.

See also: modes.md for what to animate, ricing.md for the settings file.

Decorations, and other things the compositor draws

Most of what the compositor draws that is not a client’s window is QML, hosted in-process: the window frames, the loading window, the wallpaper, a shell you name in the configuration, any other scene a script declares, and the pointer when a scene of your own is named for it or no cursor theme is set (see shell-boundary.md for the shell). There is nothing to compile and no Rust to touch: write a file, name it, press super+shift+r.

Two things on screen are not QML: a pointer from an XCursor theme, which is the theme’s own picture, and the rounded corners cut into a client, which are a fragment program the compositor runs over the client’s pixels.

The property-by-property contract for a frame lives next to the styles, at crates/solium/qml/panes/README.md, and so does the one list of the styles that ship. This is the guide: what the pieces are, how to write one, and what it costs.

Three terminals tiled, in the default top style over the default wallpaper: the focused window’s titlebar is white, the other two light grey. Below, the same three in overview. Taken under the light theme Solium shipped until 2026-10-04 and not retaken yet: the shipped theme is now dark grey, the focused titlebar a shade lighter than the others (Colours and fonts). Both halves are the same QML. In overview each frame scales with the window it belongs to rather than being redrawn at a new size, because a frame is part of the window as far as the transform layer is concerned, which is why a mode can scale a window at all without knowing what a titlebar is.

What is QML, and where it comes from

Your own directory is ~/.config/solium/qml/, and for everything in that table but the pointer it is searched first. A file you write shadows the shipped one of the same name, and everything you did not write still comes from the shipped set, including its later improvements. A folder under panes/ counts only if it has a Pane.qml in it, so an empty one does not replace the shipped style of that name. There is no registry: nothing has to be listed anywhere for a style to be found.

The shipped pointer is the exception: ~/.config/solium/qml/cursor.qml does not replace it. A pointer of your own is a scene you name, which a bare name finds in that directory first. The pointer below says how.

Writing a pane style

A style is a folder. Pane.qml is its manifest: what the frame reserves from the client, and a list of layers. Each layer is its own QML scene, drawn at its own depth: behind the client, in the frame (over the client), or above the frame. panes/border/ is the smallest, and the one to read first:

// panes/border/Pane.qml
import QtQuick
import Solium

PaneStyle {
    insets.top: 3
    insets.right: 3
    insets.bottom: 3
    insets.left: 3

    requires: []

    Layer { depth: "frame"; name: "border"; source: "Frame.qml" }
    KeyboardPillLayer {}
}

The last line is the keyboard pill every shipped style draws at the focused text field’s caret; leave it out and the style draws none (the panes README, “The keyboard pill”).

// panes/border/Frame.qml, shortened
import QtQuick
import Solium

Item {
    id: frame

    property int insetTop: 0         // set by the compositor, from Pane.qml
    property bool focused: false     // set by the compositor

    Rectangle {
        anchors.fill: parent
        color: "transparent"         // the client shows through
        border {
            width: frame.insetTop
            color: frame.focused ? Theme.accent : Theme.edgeInactive
        }
        Behavior on border.color { ColorAnimation { duration: Theme.normal } }
    }
}

Five things about that are the whole model.

A layer’s root covers the window’s entire outer rect, frame and client together, not a strip at the top. Whatever it does not paint stays transparent and the client shows through. That is why a bar can be on any side, or there can be no bar at all. A layer that declares bleed gets a larger canvas, the window grown by that much, and bleedLeft and bleedTop say where the window is inside it.

The insets are what the style reserves, declared once on the manifest, and the compositor hands the same four numbers to every layer as insetTop, insetRight, insetBottom and insetLeft. Reserve nothing and the style becomes an overlay: it draws over the client and never moves it.

focused, pointerInside, title and the sizes are written for you when they change, so reacting to focus or to the cursor is a binding rather than a subscription. pointerInside is true while the pointer is anywhere over the window, including over the client, which is how a border can follow a cursor that is over a text editor. So are caret, where the focused text field’s caret is when this window has it, and values, whatever the configuration handed every pane with sol.pane_values{ ... }; the Keyboard singleton is there to read as well. The panes README says what each holds.

action is how a button asks for something. Set it to "close" or "maximize"; the compositor takes it and clears it, so a press is acted on once, on release.

onButton is how a button keeps a press from dragging the window. A press on the frame starts a window move unless a layer says the pointer is over a button, and the property the compositor reads for that is a boolean called onButton. The shipped top style keeps it next to the name of the button under the pointer:

property string hovered: ""                       // which button, or ""
readonly property bool onButton: hovered !== ""   // what the compositor reads

MouseArea {
    anchors.fill: parent
    hoverEnabled: true
    onContainsMouseChanged: frame.hovered = containsMouse ? "close" : ""
    onClicked: frame.action = "close"
}

A layer whose buttons do not declare onButton has its buttons drag the window instead of pressing, which looks like broken buttons rather than like a missing property. hovered on its own is not read by anything. Five of the shipped styles with buttons, left, bottom, pulse, reactive and reveal, declare hovered and not onButton, so their buttons may not press (#158). top is the one to copy.

Two more things a style author meets. Presses reach a layer only inside the band the insets reserve; hover goes everywhere, presses do not, so a button drawn over the client or out in the bleed cannot be clicked. And a tiled window can be small: the shipped bars hide the title, then their buttons, when there is no room for them (#133), and a style of yours should plan for a small paneWidth too.

The full list of what a layer is told and what is read back, depth and bleed in detail, and client.radius for rounding the client itself, are in the panes README.

One QML file with an Item at its root is still a style, called a decoration: put it in ~/.config/solium/qml/decorations/ and name it. It is one frame layer, and it declares its own insetTop and the rest, because it has no manifest. A bundle is found first, so a file there named like a shipped style (top.qml) never draws; give it a name of its own.

Sizes are logical, always

A frame is laid out in logical pixels and rasterised at whatever its monitor’s scale is. insets.top: 3 is three logical pixels on a 1x screen and six real ones on a 2x screen, and Theme.fontSize behaves the same way.

Nothing is required of you for that to work, and that is the point: there is no scale property to read and no arithmetic to do. It is worth knowing only so that you do not try. A frame that multiplied its own sizes by a scale would be twice as big as it asked to be, and a frame that hardcoded device pixels would be a different size on each monitor.

The compositor rasterises the scene at logical × scale and hands Qt the ratio between the two, so a titlebar on a HiDPI screen gets more detail rather than more blur. Test it with SOLIUM_OUTPUTS=2 and a scale on one of them; see dev/README.md.

Colours and fonts

Nothing in a frame should contain a hex code. Solium.Theme has nineteen properties:

• colours: surface, surfaceInactive, edge, edgeInactive, text, textDim, control, controlInactive, accent, warning, danger, accentInk (what is drawn on the last three);
• metrics: titlebarHeight, gap, margin;
• type: fontFamily, fontSize;
• chrome durations, in milliseconds: quick, normal.

The frames, the loading window, the keyboard pill and a hosted shell that imports Solium all read that one singleton, so a colour changed there changes all of them.

The shipped colours are greys, every one: red, green and blue the same. That is the maintainer’s decision for now: a dark theme in black, greys and white, with no accent hue and none of the logo’s or the wallpaper’s colours. The bars are near-black, the focused one a shade lighter, with light grey titles, dimmer on the windows without the keyboard; accent is a light grey, which the keyboard pill’s capsule is drawn in; and warning and danger, which the maximise and close buttons turn under the pointer, are two greys told apart by shade and by the glyph each then shows. A light scheme, or colour accents, would be a change of the values only: the names stay. qml::hosting_tests::every_colour_the_theme_publishes_is_a_grey holds the shipped file to it. And a grey drawn see-through over the wallpaper takes the wallpaper’s colour, so the bars of top, reactive and reveal, pulse’s breathing line, proximity’s border and the Developer Tweaks panel are opaque (tests/scenarios/pane-top-drawn.lua, tests/scenarios/pane-bars-opaque.lua, tests/scenarios/pane-pulse-drawn.lua, tests/scenarios/pane-proximity-drawn.lua, qml::hosted::tests::the_tweaks_panel_is_opaque_and_grey).

The fallback pointer and the default wallpaper do not read it; their colours are fixed. A copy of Solium/Theme.qml in ~/.config/solium/qml/Solium/ is meant to be how you change it, and does not work yet: the shipped module is found first (#88). A frame that hardcodes a colour is a frame that stops matching the moment anyone changes anything.

The pointer

With no scene of your own named for it, the pointer is the machine’s XCursor theme whenever there is one:

cursor = { theme = "Adwaita", size = 24 },

theme is a directory under ~/.icons, ~/.local/share/icons or /usr/share/icons. size is in logical pixels, 8 to 256, and is multiplied by each monitor’s scale. With either left out, XCURSOR_THEME and XCURSOR_SIZE decide, and then 24 pixels and no theme. A reload applies a change. An application can name the shape it wants, an I-beam or a resize arrow, through cursor-shape, and gets it from the theme; a shape the theme lacks falls back to that theme’s own arrow. Over a frame the compositor sets the pointer itself: the arrow over a titlebar, and the matching resize arrow on each edge.

Solium’s own pointer at 24 pixels, magnified eight times: over the dark part of the wallpaper, and over a focused top titlebar as it was under the earlier light theme. It is what you get with no scene and no theme set anywhere, or with a theme named that is not installed, and it is QML: qml/cursor.qml. Its colours are fixed rather than taken from Theme, a white body with a dark outline, because the pointer sits on whatever a client drew and has to stay legible on black and on white alike.

It is one arrow for every shape. A pointer of your own is a scene, named the way a shell’s is, cursor = { scene = "~/.config/solium/cursor/Cursor.qml" }, or SOLIUM_QML_CURSOR=<file> for one run. It draws every shape ahead of any theme, is told which one through Solium.cursor.shape, can be larger than size and can animate; a reload builds it again after an edit. ricing.md has an example, and shell-boundary.md what it is given.

Which windows get a frame, and what a failure looks like

Every window is offered a frame drawn by the compositor. A client that insists on drawing its own frame gets to, and is left without one; so are menus and tooltips, and a fullscreen window. pane = "none" (or SOLIUM_PANE=none) draws no frame at all and builds no QML scene per window.

A style that cannot be loaded (a name that is nowhere, a layer whose QML does not build, or a requires this session cannot meet) leaves each window it was for bare: no frame and no space reserved for one, and a line in the log saying so (#90). Fixing the file and pressing super+shift+r frames the windows opened after that; a window already left bare stays bare until it is opened again.

What it costs

Which path QML renders on decides most of this. On the hardware it is the GPU by default, when a trial render at startup passes. Nested it is software, and so it is with qml.renderer = "software", when the trial fails, or when the last GPU start in the compositor did not work. The log line that begins QML renderer: says which one a session got, and why.

On both paths, an idle layer costs a flag read: Qt is asked each frame whether the scene has anything new, and the compositor draws only then. Bleed is paid for in full, because every pixel of the larger canvas is drawn each time the layer changes, so a bar throwing spikes upward should ask for bleed: { "top": 48 } rather than 48.

A layer that is usually empty, as the keyboard pill’s is, can bind dormant to “nothing to show”. While it is true the layer is not drawn and nothing of it is blended over the client; in software it also lets go of its image, and on the GPU it keeps the buffer it was last drawn into. The panes README, “What it costs”, has the details.

On the GPU, each layer is drawn by Qt’s OpenGL scene graph straight into a buffer the compositor allocated, and nothing is copied or uploaded. A window being resized moves its layers onto a new buffer rather than rebuilding them, so their animations carry on through it.

In software, Qt rasterises a changed layer on the CPU, and the compositor copies it into a buffer and uploads it. A frame layer that paints only inside its own insets has only those bands copied, and the upload is the one box around them: for a titlebar that is about 4% of the window, and for a style that reserves all four sides it is the whole window. A layer that reserves space and paints outside it has to say so with property bool overlay: true, or what it paints outside is not copied. A layer at behind or above, a layer with any bleed, and every layer of a style that reserves nothing are overlays already.

requires: ["gpu"] is for a style that needs the GPU path. The software scene graph does not implement ShaderEffect, and Canvas does not appear to paint on it, so a style using either would draw wrong in software without a word. Declaring it means that on a software session, nested ones included, the style is refused and its windows are left bare, with the unmet term in the log. gpu is the only term there is, and a term this build has never heard of is refused too.

Animation inside a frame

Nothing to declare: a transition runs at the screen’s refresh rate, and a loop with a pause in it survives the pause.

A layer that never stops animating never stops costing anything. The one measurement there is dates from 2026-09-06, on the software path before the GPU one existed: with the pulse style animating at the screen’s full rate, the whole compositor used about a tenth of a core. pulse runs its animation only while its window is focused, so an unfocused window costs nothing. Making that trade knowingly is fine; making it by accident is not.

QML animations run on the compositor’s clock rather than Qt’s own timer, so a titlebar easing in step with its window stays in step.

The loading window

The other scene worth writing. It is what is inside a window between the user asking for an application and the application existing, and the window is already real by then: it has its slot, the other windows have moved aside, it can be closed.

It is handed program and waited. The one that ships uses only the name, on the grounds that the window already is the window, and the one fact you do not otherwise have is which application you are waiting for.

import QtQuick
import Solium

Item {
    id: card
    property string program: ""
    property int waited: 0

    Rectangle {
        anchors.fill: parent
        color: Theme.surface
        Text {
            anchors.centerIn: parent
            text: card.program
            color: Theme.text
            font { pixelSize: Theme.fontSize + 8; family: Theme.fontFamily }
        }
    }
}

The rest of loading in config.lua decides what the wait looks like: patience (how long before a window whose application never came is given up), reserves_a_slot (whether the others move aside at once), decorated (whether its frame is drawn meanwhile, which gives you a close button for an application that is not coming) and fade.

Do not fade it out yourself when the application arrives. The compositor does that, over loading.fade. Whether a window is see-through is a presentation transform, like where it is and how big, so the compositor applies it to the scene’s picture as it draws it. On the software renderer a scene could not do it anyway: Qt repaints only what it thinks changed, onto the pixels already there, so each half-transparent frame lands on its own opaque previous one and nothing fades.

Trying things quickly

SOLIUM_PANE=left       ./target/debug/solium     # one run, one pane style
SOLIUM_LOADING=mine    ./target/debug/solium     # one run, one loading scene
solium --check-qml path/to/thing.qml             # does it even load?

--check-qml loads one file and prints ok and its path, or what Qt reported, without starting a compositor, and exits with 1 when anything did not load. On a Pane.qml it loads every layer the style names in source: too, and a broken one fails the check by name. It loads in software, so it cannot build a requires: ["gpu"] style: it says so and leaves that style’s layers unloaded, which is not a failure. --check <file.qml> is the same check. Porting a scene means walking a chain of “type X unavailable” errors, and doing that through a real session costs ten seconds a link.

super+shift+r in a running session reads the configuration again, drops the QML cache and rebuilds every frame. Windows keep their slots and each client is resized to whatever the new style left it, so a frame can be written against a desktop you are using. While SOLIUM_PANE is set, it decides the style and pane = does not.

With --debug-mode, the Developer Tweaks panel is shown at startup and super+shift+d hides and shows it. It lists every style it finds, yours included, under “Pane style” (bundles) and “Decoration” (single files), and switches the style live. It also has presentation effects for the focused window and a reload button.

What ships

The shipped styles, and the demonstrations kept with the tests, are listed once, in the panes README. top is the default.

See also: ricing.md for the settings, animation.md for the engine that moves the windows these are drawn around, shell-boundary.md for what belongs to a shell rather than to the compositor.

Where Solium ends and a shell begins

Solium is the compositor. A shell — the bar, the dock, the launcher — is a project of its own, in its own repository, and it runs inside Solium as its configuration: its QML is hosted in the compositor’s own engine, beside the window frames, the pointer and every other scene the compositor draws. That is the line, and it is not where a Wayland tutorial would put it.

Where it is today:

• A shell is named in the configuration, shell = { scene = "<its root QML file>" }, and hosted in-process through sol.surface, by lua/shell.lua. The shipped configuration names none.
• A shell is QML written against Solium’s own API: import Solium for Theme, Keyboard, Monitors, Windows, WindowList, Workspaces, WorkspaceList, Grab and the attached Solium object (Solium.monitor, Solium.input, Solium.surface.reserve, Solium.keyboard, Solium.status), and Solium.send for what it asks Lua to do (below). Quickshell support was removed (#172); Quickshell itself may add Solium support on its own side.
• The pointer can be a scene of its own the same way, cursor = { scene = "<its QML file>" }, given what the pointer is doing as Solium.cursor (below).
• A shell that runs as its own program — Waybar, a Quickshell instance run on its own, any wlr-layer-shell panel — is supported too, as an ordinary client. It needs nothing from the configuration and gets nothing from the compositor’s engine.

The rest of this file is why hosting is the design, how to host one, and exactly what a hosted shell is given and what it is not.

The requirement that decides the architecture

An object should be able to move from the dock into a window’s titlebar.

Not “look similar in both”. Move — one object, travelling, unbroken.

That single requirement rules out the conventional answer. If the shell is a separate process painting its own pixels, then a dock icon and a titlebar are two scene graphs in two processes with two stylesheets, and an object cannot cross between them; the best available is a fake — dissolve one, appear in the other — which is exactly the kind of thing this project exists not to build.

The same requirement, in a weaker form, rules it out again: “the shell changes colour, so the decorations change too” is trivial when there is one theme object, and a synchronisation problem forever when there are two.

So: one engine

The compositor hosts one QML engine. Window decorations are scenes in it, and so is a hosted shell’s bar, dock and launcher. A scene that imports Solium gets the same Solium.Theme singleton the frames read, because there is only one of it.

That gives, in order of how hard they would otherwise be:

• One design system. Solium.Theme (crates/solium/qml/Solium/Theme.qml) is what the window frames and the loading window are drawn with, and any hosted scene that imports Solium can read it. Changing a colour there changes the titlebars and a shell that uses it together, with no rebuild, because they read the same object and not two copies. A shell brought in with a theme of its own keeps its own until it is pointed at this one. Two of the compositor’s own scenes keep fixed colours instead: the fallback pointer, which has to stay legible over whatever a client drew, and the default wallpaper.
• Objects that travel, planned. The aim is that an item can leave the dock and land in a titlebar, one object the whole way. None of it is built, and it will not be a reparent: every scene has a QQuickWindow of its own, so each is its own scene graph, and an item cannot move from one to another. The plan is a flight or a morph: a third, live instance of the same component, drawn over both ends while they are hidden and moved on the compositor’s clock. One engine is what lets that instance be the component itself, with the same theme, rather than a picture of it.
• No protocol for shell geometry, planned. A hosted dock’s icon rectangles need not be published to the compositor, because the compositor’s engine already has them. The plan is for a scene to name an item as an anchor (Solium.region) and for an animation to aim at that name, read again on every frame, so a genie follows an icon while it moves and can never animate against a stale copy. Nothing of that is built yet; it is tracked under Later in #169. Today a genie aims at a window, a sol.surface scene or a fixed rectangle (modes.md). Only a dock that runs as its own program would need a protocol to hand its rectangles over.

This is the arrangement Apple has, and it is unavailable to anyone configuring an existing compositor. It is the reason for writing one.

Hosting a shell

Naming it

In ~/.config/solium/user.lua (or your own config.lua):

return {
    shell = { scene = "~/.config/solium/shell/shell.qml" },
}

~ is expanded. The scene is drawn on every monitor, one instance each, over the windows and across the whole monitor; each instance reads its own monitor as Solium.monitor. shell = { on = "primary" }, or a connector name, draws one instance instead (script::tests::the_shell_is_on_every_monitor_unless_the_configuration_names_one). It takes the pointer only where its items take input, as “Clickable only where it takes input” under What a hosted shell is given says; everywhere else the pointer goes to the windows under it. super+shift+r picks up a change to the setting, and tries again a scene that would not load, so a typo in the shell costs a reload rather than the session (state::tests::real_client::a_reload_tries_again_a_scene_that_would_not_load). Editing a file under the scene’s own directory rebuilds the scene with no reload at all: that is checked every half second while frames are being drawn. false, the default, hosts nothing, and taking the setting out takes the shell away on the next reload.

A reload does not rebuild a hosted scene. sol.surface declared again with the same scene file writes the properties that changed into the live scene, so an open popup, a running animation or a half-typed query survives super+shift+r; only a different scene file builds the scene again (scripted::tests::a_redeclared_property_is_written_into_the_live_scene).

SOLIUM_SHELL_SCENE=<file> overrides the setting for one run. It is how dev/run-shell.sh hosts a shell under development without touching the configuration you normally run; see dev/README.md.

Installing one next to your configuration

A shell is its own repository. Clone it beside your configuration and name its root file:

git clone <the shell's repository> ~/.config/solium/shell

shell = { scene = "~/.config/solium/shell/shell.qml" },

A shell that imports its own files by relative path needs nothing more.

solium --check-qml <file> loads one file without starting a compositor and prints ok or what Qt reported, which is the quick way through a chain of “type X unavailable” errors. It exits with 1 when the file does not load.

What a hosted shell is given

A canvas. One scene per monitor, each the size of its whole monitor, on the top layer: over the windows, under a layer-shell client’s own top layer surfaces, and covered by a fullscreen window unless fullscreen.covers says otherwise (scripted::tests::a_surface_on_every_monitor_has_one_live_scene_per_monitor). It gets pointer motion, every mouse button as itself, the wheel, and the modifiers held, so a MouseArea or a WheelHandler works as it does anywhere (qml::hosted::tests::a_right_press_reaches_a_mouse_area_as_the_right_button, qml::hosted::tests::the_wheel_reaches_a_wheel_handler_with_its_angle). Each event carries its time, so a double press is a double-click and a TapHandler counts its taps, by Qt’s own double-click interval and distance (qml::hosted::tests::a_double_press_on_a_mouse_area_is_one_double_click, qml::hosted::tests::a_tap_handler_counts_taps_by_when_they_happened, qml::hosted::tests::two_presses_further_apart_than_the_interval_are_two_single_clicks). The wheel with super held stays the compositor’s (state::tests::real_client::reflow_on_close::hosted::super_and_the_wheel_stay_the_compositors_over_a_scene), and while the session is locked none of it reaches the scene (state::tests::real_client::lock_focus::the_wheel_over_a_hosted_scene_is_not_the_scenes_while_locked, state::tests::real_client::lock_focus::a_button_let_go_behind_the_lock_is_not_held_after_it). A press the scene held when the session locked is cancelled, not clicked: a MouseArea, a Button or a TapHandler holding it hears canceled (state::tests::real_client::lock_focus::the_lock_lets_go_of_a_hosted_scenes_press_and_its_hover, qml::hosted::tests::a_press_let_go_of_unseen_is_cancelled_not_clicked). A monitor that arrives gets its instance there and then, and one that goes takes its instance with it (scripted::tests::an_instance_goes_with_its_monitor_and_comes_with_a_new_one). It reads where it is from Solium.monitor, below; screenInfo is gone.

Clickable only where it takes input. The compositor asks the live item tree under the pointer, so a point is the scene’s only where a visible, enabled item that is not fully transparent takes input: any item that accepts mouse buttons — a MouseArea, a Qt Quick Controls control such as a Button or a TextField, a TextInput or TextEdit, a Flickable (a ListView among them), a PathView, a MultiPointTouchArea — a pointer handler other than HoverHandler, such as a TapHandler or a DragHandler, a link in a Text with an onLinkActivated handler, or an item marked Solium.input: true. An item at opacity 0, itself or through an ancestor, takes nothing, though Qt would still deliver to it (qml::hosted::tests::the_item_tree_decides_what_a_point_claims). The rest of a Text takes no press, nor does a link nothing handles, and a plain label takes nothing at all (qml::hosted::tests::a_text_takes_a_press_only_on_a_link). Solium.input: "hover" takes the pointer’s motion and leaves presses to what is under it, which is how an edge strip reveals a hidden dock. A HoverHandler on an item that takes no press itself takes only the motion in the same way, and a press there goes to what is under it. Solium.input: false takes an item out. An item’s shape counts, through its containmentMask, so a rounded popup’s corners pass clicks through; a mask written in QML has to be typed, function contains(point: point): bool, or Qt ignores it, and it answers for the whole item, its bounds too. A disabled handler takes nothing (qml::hosted::tests::a_disabled_handler_claims_nothing), and an open Qt Quick Controls popup, a Popup, a Menu or a ComboBox’s list, takes the points it is drawn on, though Qt draws it in the window’s overlay rather than under the scene’s root (qml::hosted::tests::an_open_controls_popup_claims_its_press), and Solium.input written on the Popup is that item’s (qml::hosted::tests::solium_input_on_a_controls_popup_is_its_items). A popup is laid out against the whole scene, so a Menu opens where it is asked to (qml::hosted::tests::a_controls_popup_is_laid_out_against_the_whole_scene), and a modal one takes every point of its scene while it is open, as Qt’s own modality does (qml::hosted::tests::a_modal_popup_takes_every_point_of_its_scene_while_it_is_open). Everywhere else the window under the shell gets the press and the wheel (state::tests::real_client::reflow_on_close::hosted::the_wheel_where_the_shell_draws_nothing_is_the_windows_under_it), and where the scene takes a press, the window under it does not have the pointer, nor the keyboard when focus follows the mouse. A press the scene took is its until every button is up, wherever the pointer goes meanwhile, and the pointer keeps the shape it had at the press (state::tests::real_client::reflow_on_close::hosted::a_press_where_the_shell_draws_nothing_reaches_the_window_under_it, state::tests::real_client::reflow_on_close::hosted::a_release_after_dragging_off_a_shell_button_reaches_the_scene, state::tests::real_client::reflow_on_close::hosted::a_press_a_scene_holds_keeps_its_shape_over_a_resize_border, state::tests::real_client::reflow_on_close::hosted::focus_follows_the_mouse_through_a_shell_only_where_it_takes_no_press, qml::hosted::tests::the_item_tree_decides_what_a_point_claims).

Popups that hold the pointer. Grab { name: "tray-menu"; target: menu; active: menu.visible; onDismissed: menu.close() } holds the pointer for the scene while it is active (qml::hosted::tests::a_grab_is_held_while_active_and_dismissed_on_request): motion and the wheel go to it wherever the pointer is, and no window has the pointer, nor its frame, nor the keyboard when focus follows the mouse (state::tests::real_client::reflow_on_close::hosted::while_a_grab_is_held_the_pointer_is_the_scenes, state::tests::real_client::reflow_on_close::hosted::while_a_grab_is_held_the_wheel_is_the_scenes, state::tests::real_client::reflow_on_close::hosted::while_a_grab_is_held_no_window_takes_focus_frame_or_cursor_from_the_pointer). Its target is an item or a Qt Quick Controls Popup, a Menu among them; anything else has no points, so every press dismisses the grab, and the log says so (qml::hosted::tests::a_controls_popup_is_a_grabs_target). A press inside its target is the scene’s, even where no item there takes input (state::tests::real_client::reflow_on_close::hosted::a_press_inside_the_grab_target_reaches_the_scene). With more than one Grab of a scene active, a press inside any of their targets is the scene’s, and the newest one’s name is the one outside_click is looked up by (qml::hosted::tests::a_scenes_newest_grab_is_reported_and_every_active_one_counts). A press outside it dismisses it: every active Grab of the scene hears dismissed, newest first (qml::hosted::tests::a_scenes_newest_grab_is_reported_and_every_active_one_counts), and the press is then swallowed, its release with it, or passed on to whatever is under it when outside_click says "pass" (state::tests::real_client::reflow_on_close::hosted::a_press_outside_a_grab_dismisses_it_and_is_swallowed_by_default, state::tests::real_client::reflow_on_close::hosted::with_outside_click_pass_the_dismissing_press_reaches_the_window_under_it). However a grab ends, swallowed, passed, or let go of by its scene, the window under the pointer has the pointer back at once, or, when the scene holds a press as it ends, at that press’s release, so a click there with no motion before it reaches it (state::tests::real_client::reflow_on_close::hosted::a_swallowed_outside_press_gives_the_pointer_back_to_the_window_under_it, state::tests::real_client::reflow_on_close::hosted::a_popup_that_closes_by_itself_gives_the_pointer_back_to_the_window_under_it, state::tests::real_client::reflow_on_close::hosted::a_surface_taken_away_gives_the_pointer_back_to_the_window_under_it, state::tests::real_client::reflow_on_close::hosted::a_popup_closed_during_a_press_inside_it_gives_the_pointer_back_at_the_release). shell.outside_click in config.lua is the hosted shell’s, "swallow" by default, and a table names grabs, { default = "swallow", ["tray-menu"] = "pass" } (script::tests::the_shell_takes_its_outside_click_from_the_configuration, state::tests::real_client::reflow_on_close::hosted::a_policy_named_for_the_grab_beats_the_default). Any other value, in the word or in the table, fails the configuration’s load (script::tests::an_unknown_outside_click_is_refused). One grab is held at a time, and one another scene takes dismisses it (state::tests::real_client::reflow_on_close::hosted::a_grab_another_scene_takes_dismisses_the_one_held). A surface the pointer does not reach, declared interactive = false, holds no grab, and its scene’s grabs dismiss none (state::tests::real_client::reflow_on_close::hosted::a_surface_the_pointer_does_not_reach_holds_no_grab); one declared so while it holds a grab hears it dismissed (state::tests::real_client::reflow_on_close::hosted::a_surface_declared_again_out_of_the_pointers_reach_dismisses_the_grab_it_held). A press the scene already held when its grab began keeps the pointer until its release, so a button whose press opens a menu is let go of as usual (state::tests::real_client::reflow_on_close::hosted::a_press_held_when_a_grab_begins_keeps_the_pointer_until_its_release). A game’s pointer lock is let go while a grab is held, at once even while a press of the game’s own still keeps the pointer on it, and comes back after it (state::tests::real_client::reflow_on_close::hosted::a_grab_suspends_a_pointer_lock_and_the_lock_comes_back_after, state::tests::real_client::reflow_on_close::hosted::a_grab_begun_during_a_press_on_a_locked_window_lets_go_of_the_lock_at_once), and locking the session dismisses it (state::tests::real_client::reflow_on_close::hosted::locking_the_session_dismisses_a_hosted_grab). No grab is held behind the lock; one a scene takes there is held once the lock is gone (state::tests::real_client::lock_focus::a_grab_a_scene_takes_behind_the_lock_is_held_once_it_is_gone).

The keyboard, when an item asks. TextField { Solium.keyboard.wants: activeFocus; Solium.keyboard.claims: [ "Escape", "Return", "Up", "Down" ] } takes the keyboard while it is visible and wants it (qml::hosted::tests::a_field_that_wants_the_keyboard_reports_its_claims, qml::hosted::tests::an_invisible_field_does_not_hold_the_keyboard). When more than one visible item of a scene wants it, the one with active focus holds it, else the one that came to want it last, and only that item’s claims count (qml::hosted::tests::the_holder_is_the_focused_wanting_item_else_the_one_that_wanted_last). Every hosted scene’s window is active from the start, so focus: true gives a field activeFocus; bind wants to it, because the compositor takes the keyboard back by taking that focus away. Whatever wants is bound to, a scene the keyboard was taken back from does not take it again until an item asks anew: it comes to want it, is shown again, or takes active focus again (qml::hosted::tests::a_scene_let_go_of_takes_the_keyboard_again_only_when_asked_anew). Written on a container around the field, wants works too: the field inside loses its focus when the keyboard is taken back, and taking it again asks anew for the container (qml::hosted::tests::a_let_go_takes_the_focus_from_a_field_inside_the_container_that_wants_the_keyboard). Written on a Qt Quick Controls Popup, which is no item, Solium.keyboard is the popup’s own, its activeFocus and its being open, so a search popup is Popup { focus: true; Solium.keyboard.wants: activeFocus; TextField { focus: true } } (qml::hosted::tests::a_field_in_a_popup_that_wants_the_keyboard_takes_the_keys); on anything that is neither an item nor a Popup it holds nothing, and the log says so. Such a popup holds the pointer with a Grab and the keyboard at once: a press outside it dismisses it and the window under the pointer has the pointer back, and the keyboard once the field lets go (state::tests::real_client::reflow_on_close::hosted::a_search_popup_holding_the_pointer_and_the_keyboard_gives_both_back_when_dismissed). The window that had the keyboard loses it meanwhile, still reads as the focused window and is drawn focused, and gets it back when the field lets go (state::tests::real_client::reflow_on_close::hosted::the_window_gets_the_keyboard_back_when_the_shell_lets_go). Text comes from the compositor’s own keyboard state, so typing works with any layout active, Russian included (input::tests::russian_typed_through_the_compositor_reaches_a_hosted_text_field, input::tests::while_the_shell_holds_the_keyboard_russian_letters_reach_it_as_cyrillic), and with Control held a letter is named by the one your Latin layout has on that key, as Qt names it, so ctrl+a and ctrl+z work with Russian active (input::tests::ctrl_a_selects_all_in_a_hosted_text_field_on_russian), and a key held repeats at the keyboard’s own rate (input::tests::a_held_key_repeats_into_the_scene_at_the_keyboards_rate, input::tests::a_held_key_noticed_late_still_repeats_at_the_keyboards_rate), unless your keymap says it does not, as it says of a modifier, AltGr among them, and of a group toggle such as grp:alt_shift_toggle (input::tests::a_held_modifier_does_not_repeat_into_the_scene, input::tests::a_held_group_toggle_does_not_repeat_into_the_scene). A group toggle never repeats, even on a key that does, as grp:alt_space_toggle’s is (input::tests::a_held_group_toggle_on_space_does_not_repeat_into_the_scene). The compositor’s bindings keep working, super+q on Russian among them, except the keys the item claims, which are the field’s (input::tests::an_unclaimed_super_binding_still_fires_on_russian_while_the_shell_holds_the_keyboard, input::tests::a_claimed_key_reaches_the_scene_and_not_its_binding); a claim is spelled as sol.bind spells a key. shell.keyboard.bindings in config.lua is "except_claimed" by default, which is that: every binding but the claimed keys. "all" keeps every binding, claimed or not, and "none" gives the shell every key (input::tests::with_bindings_all_a_claimed_binding_wins, input::tests::with_bindings_none_even_super_bindings_reach_the_scene, script::tests::the_shell_takes_its_keyboard_bindings_from_the_configuration). Any other value fails the load too (script::tests::an_unknown_keyboard_bindings_is_refused), and a reload that changes it applies from the next key, while the shell holds the keyboard (state::tests::real_client::reflow_on_close::hosted::a_bindings_policy_redeclared_while_the_shell_holds_the_keyboard_applies_at_once). The Ctrl+Alt escapes always work (input::tests::the_escape_hatches_beat_a_shell_that_holds_the_keyboard). Clicking a window or sol.focus takes the keyboard back (state::tests::real_client::reflow_on_close::hosted::clicking_a_window_ends_the_shells_hold, state::tests::real_client::reflow_on_close::hosted::sol_focus_ends_the_shells_hold), and so does locking the session; no scene holds it behind the lock, and one that asks there has it once the lock is gone (state::tests::real_client::lock_focus::no_scene_holds_the_keyboard_while_the_session_is_locked). The pointer crossing a window does not take it back, even with focus following the mouse (state::tests::real_client::reflow_on_close::hosted::the_pointer_crossing_a_window_does_not_end_the_shells_hold). One scene holds it at a time (state::tests::real_client::reflow_on_close::hosted::a_hold_another_scene_takes_returns_to_the_window_the_first_took_it_from), and a scene whose monitor is unplugged gives it back (state::tests::real_client::reflow_on_close::hosted::a_monitor_unplugged_while_its_scene_holds_the_keyboard_gives_it_back). A surface the pointer does not reach, declared interactive = false, holds no keyboard, as it holds no grab, since nothing could click it to take the keyboard back; one declared so while its scene holds it gives it back (state::tests::real_client::reflow_on_close::hosted::a_surface_the_pointer_does_not_reach_holds_no_keyboard, state::tests::real_client::reflow_on_close::hosted::a_surface_declared_again_out_of_the_pointers_reach_gives_the_keyboard_back). The compositor’s own Qt loads no input method from your session, so IBus and the like do not run inside it (launch::tests::the_compositors_qt_takes_no_input_method_from_the_session); the programs it starts still get yours (launch::tests::a_spawned_program_gets_the_input_method_the_compositors_qt_does_not).

The compositor’s clock and frames. Its animations advance on the same clock as every window transform, a running animation asks for the next frame, and the scene is redrawn only when Qt says it changed. Qt is served between frames too: a Timer fires on time on an idle desktop, and what Qt waits on a descriptor for — a socket, an answer from another thread — arrives when it is ready, with no frame drawn unless the scene changed. A Timer is on that same clock, so one beside an animation nothing draws still fires.

The Solium QML module. Theme above all: the colours, fonts and metrics the frames are drawn with. Everything import Solium brings is written unqualified, as Theme is: the singletons Theme, Keyboard (“The keyboard, live”, below), Monitors (“Its monitor, live”, below), Windows (“Windows, live”, below) and Workspaces (“Workspaces, as the configuration has them”, below); the types Grab (“Popups that hold the pointer”, above), WindowList (“Windows, live”) and WorkspaceList (“Workspaces, as the configuration has them”); the pane-style types PaneStyle and Layer, and the keyboard pill’s KeyboardPill and KeyboardPillLayer (the panes README); and the attached Solium object, which any item can read, with exactly ten members: Solium.monitor, the monitor this instance of the scene is on (below); Solium.input, true, false or "hover" (above); Solium.surface.reserve.top, right, bottom and left (“Room of its own”, below); Solium.keyboard.wants and claims (above); Solium.status, the text sol.status set (“Workspaces, as the configuration has them”, below); Solium.send(action, data), what it asks Lua to do (below); Solium.cursor, the pointer, and the hotspot a pointer scene sets (What a pointer scene is given); and Solium.region, Solium.material and Solium.materialState, which every item accepts and nothing reads until materials exist (#199), materialState reading "off" till then (qml::hosted::tests::the_attached_type_shares_the_solium_uri_with_the_shipped_module, qml::pointer::tests::a_region_and_a_material_are_accepted_and_materials_are_off). Nothing else is public: Insets, ClientTreatment and ClientShadow are internal, and the row types have no name, so a shell’s own Monitor.qml is not shadowed (qml::hosted::tests::a_shell_file_named_like_a_row_is_still_the_shells), and Window is still Qt Quick’s in a scene that imports both (qml::hosted::tests::a_quick_window_is_still_qt_quicks_beside_the_windows_model), and a shell’s own Workspace.qml is its own (qml::hosted::tests::a_shell_file_named_like_a_workspace_is_still_the_shells). A shell’s own file named like a type or singleton the compositor registers (Grab, Keyboard, Monitors) is hidden by it: a Monitors.qml beside a scene is the Monitors model there, and a scene that creates one does not build, so name such a file otherwise (qml::hosted::tests::a_shell_file_named_like_a_singleton_is_hidden_by_it). A Theme.qml of your own in ~/.config/solium/qml/Solium/ is meant to override the shipped one, and does not yet: the shipped module is found first (#88). The attached Solium object and Grab belong to a hosted scene, which sol.surface builds on a monitor. Elsewhere (a pane’s layers, the loading window, the pointer’s scene, the fallback pointer) they build and do nothing: Solium.monitor is an absent row with an empty name and present: false, Solium.surface.reserve reserves nothing, and Solium.keyboard and a Grab hold nothing (qml::hosted::tests::a_scene_hosted_on_no_monitor_reads_an_absent_monitor, qml::hosted::tests::an_unhosted_scene_may_bind_a_reserve_and_reserves_nothing, qml::hosted::tests::an_unhosted_scene_may_bind_the_keyboard_and_holds_nothing). Solium.input changes nothing there either, since what reaches a pane’s layers is decided by the pane, not by the scene’s item tree. Theme and Keyboard are the same in every scene.

Its monitor, live. Solium.monitor is the row of the monitor this instance is on: name, whole and area (rectangles in the global space, area being the work area), scale, transform, primary, and present (valid reads the same). It changes in place, once per frame and all at once, when the monitor does, and a monitor that goes reads present: false and keeps its name; the same monitor coming back is the same row again (qml::hosted::tests::a_published_monitor_reaches_solium_monitor_in_its_scene). Until the compositor publishes a monitor, its row carries only the name, and present and valid read false (qml::hosted::tests::the_attached_type_shares_the_solium_uri_with_the_shipped_module). A scene that wants its own coordinates subtracts whole.x and whole.y. transform is spelled as sol.monitors() spells it: "normal", "_90", "_180", "_270", "flipped", "flipped90", "flipped180" or "flipped270", and not "90" or "flipped-90" as sol.monitors{ ... } takes it (models::monitors::tests::a_turned_monitor_row_names_its_transform_as_smithay_does). Monitors is every monitor, as a list model with the same roles and a count, and Monitors.get(name) one of them; a changed value is one dataChanged for that role alone (qml::hosted::tests::the_monitors_model_lists_every_row_and_changes_one_role_at_a_time). Rows also say what is reserved on each edge (top, right, bottom and left: what the work area lost there, layer-shell zones and hosted reserves together), whether the monitor’s power is "on" or "off", whether the pointer is on it and whether it is the active one, the monitor in front of you (models::monitors::tests::a_monitor_row_says_what_is_reserved_and_where_the_pointer_is, models::monitors::tests::on_two_monitors_only_the_pointers_is_active_and_each_says_its_own_edges). Monitors.get(name) of a monitor that is not there answers a row carrying only that name, which becomes the monitor when it is plugged in; one that goes leaves the list and keeps its last values, so read present before them (qml::hosted::tests::the_monitors_model_lists_every_row_and_changes_one_role_at_a_time). In a delegate of Monitors, scale and transform are the delegate item’s own properties, so read those two as model.scale and model.transform (qml::hosted::tests::a_monitors_delegate_reads_scale_and_transform_through_model). The rows are published with a frame, so while every monitor is off none is published, and power reads "off" only while another monitor is drawn.

Windows, live. Windows is every window, a list model built from the compositor’s own panes and updated in place once per frame: id, title, appId, pid, xwayland, monitor, workspace, focused, focusOrder (0 is the most recently focused, and a window that closes leaves no gap), urgent (it asked for attention nobody could see, until it is focused), fullscreen and maximized (as the compositor last set them, without waiting for the application), modal, parent, state (loading from the click, shown, closing) and onStage (state::tests::real_client::reflow_on_close::hosted::a_window_row_carries_where_it_lives_and_its_focus, state::tests::real_client::reflow_on_close::hosted::focus_order_is_most_recent_first, state::tests::real_client::reflow_on_close::hosted::a_closed_window_leaves_no_gap_in_focus_order, state::tests::real_client::reflow_on_close::keyboard_at_open::a_refused_activation_marks_the_window_urgent_until_it_is_focused, state::tests::real_client::reflow_on_close::keyboard_at_open::a_genuine_activation_of_a_window_its_own_frame_hides_does_not_keep_the_keyboard, state::tests::real_client::reflow_on_close::hosted::a_maximised_window_reads_maximized_at_once). In a delegate they are model.id, model.state and model.parent: id is QML’s own word, and the item’s own state and parent win over the roles (qml::hosted::tests::a_delegate_reads_id_state_and_parent_through_model). A window is listed from the moment it is launched, before its application draws, unless loading.reserves_a_slot is off; until then it has no pid, which reads -1 (state::tests::real_client::reflow_on_close::hosted::a_window_still_loading_is_listed_as_loading). An X11 window’s pid is the process Xwayland names for the window’s own X connection, -1 when it names none, and never Xwayland’s own (models::windows::tests::an_x11_window_is_never_given_the_pid_of_its_connection). workspace is the first workspace the configuration declared the window on (below), and reads "" until a declaration names it (state::tests::real_client::reflow_on_close::hosted::workspace_rows_count_their_windows_and_say_which_is_shown). It is the workspace’s id, not its <group>/<id> key, and a group’s ids are not unique across monitors (“2” exists in every group), so filtering on it without also filtering on monitor lists workspace 2 of every monitor. WindowList { monitor: Solium.monitor.name; sort: "mru" } is a filtered, sorted view, never reset: monitor, workspace, app and onStage filter, an empty one (or onStage left unset) keeping every window, and sort is "", the order windows opened, or "mru", the most recently focused first. A delegate on a WorkspaceList binding workspace: model.key matches nothing, since key is the <group>/<id> row key and workspace wants the id alone: WindowList { monitor: Solium.monitor.name; workspace: model.id }, or read the workspace row’s own windows list instead. Windows.focused is never null and follows focus, and with no window focused it reads present: false and is empty, not the window focused last (qml::hosted::tests::the_focused_facade_is_empty_with_nothing_focused); Windows.get(id) is one window’s row, which reads valid: false once the window has gone. It is a lookup with no change signal of its own, so a binding reads Windows.count beside it, as { Windows.count; return Windows.get(id) } does, to be asked again as windows come and go. Rows say where a window lives, not where it is drawn this frame (qml::hosted::tests::the_windows_model_filters_sorts_and_keeps_its_facades). A retired row (valid: false) is kept for 10 s after it leaves, then freed, and nothing marks count changed at that moment — only a window or workspace coming or going does. Read it again through Windows.get(id) (or the workspace equivalent) rather than holding the row itself past that grace period, or a reference kept in a var can outlive it.

Workspaces, as the configuration has them. The compositor does not know what a workspace is: Lua declares them with sol.workspaces, and the shipped workspaces.lua does so whenever they change (script::tests::the_shipped_workspaces_declare_what_each_monitor_shows, script::tests::a_window_that_opens_is_declared_on_the_workspace_its_monitor_shows). Workspaces is every workspace declared, joined with the windows: key (<group>/<id>), id, name, col, row, group, monitors, active (its group shows it), focused (shown by the group of the monitor in front of you), occupied (how many windows are on it), urgent and hasFullscreen (of a window on it), hidden and windows (state::tests::real_client::reflow_on_close::hosted::workspace_rows_count_their_windows_and_say_which_is_shown). WorkspaceList { monitor: Solium.monitor.name } is one monitor’s group, Workspaces.showing(name) what that monitor shows, Workspaces.current what the monitor in front of you shows, each empty, never null, while nothing is shown, and Workspaces.arrangement the declared shape, { kind, columns, rows }. A per-monitor bar binds showing(Solium.monitor.name): a singleton cannot know which instance asks. Solium.status is the text sol.status set, the same in every scene (qml::hosted::tests::the_workspaces_model_its_list_and_its_facades, models::tests::publish_models_carries_the_workspaces_the_status_and_the_arrangement). A workspaces widget switches with Solium.send("workspaces.go", { id: model.id, monitor: Solium.monitor.name }), and sends a window away with Solium.send("windows.send", { id: window.id, workspace: "2" }), both answered by workspaces.lua (script::tests::a_workspaces_go_from_a_scene_switches_the_monitor_it_names, script::tests::a_windows_send_from_a_scene_moves_the_window_it_names). Each takes that form only, a workspace being a whole number or its digits, and windows.send only for a window that is open; any other form, { id, monitor } or a workspace 2.5 among them, moves nothing and is logged (script::tests::a_workspaces_go_from_a_scene_switches_the_monitor_it_names, script::tests::a_windows_send_names_its_window_by_number_or_digits_and_logs_any_other_form). A declaration naming a monitor or a window the compositor does not have leaves it out, with any group left with no monitor, and so does one declaring a workspace twice among the groups that stay, keeping the first; the log names each once (models::workspaces::tests::a_declaration_naming_an_unknown_monitor_or_window_drops_them, models::workspaces::tests::an_unknown_monitor_or_window_is_logged_once_per_name, models::workspaces::tests::a_workspace_declared_twice_is_one_row, models::workspaces::tests::a_workspace_of_a_group_left_out_is_not_logged_as_declared_twice).

Installed applications, and their icons. Apps (03 §3.2.13) is every installed, visible application (NoDisplay and Hidden entries are left out at the source, not filtered in a scene), a row model like Windows and Workspaces: entries is itself (so ListView { model: Apps.entries } and ListView { model: Apps } are the same list), and Apps.get(id) a facade that is never null, with valid false for an id nothing installed answers – so a pinned app that was removed is a ghost, not a hole, the same Ruling 17 convention Windows and Workspaces already keep. Apps.ready is false until the first scan completes. A row: id (the desktop file id), name, genericName, icon (an image://solium/icon/... URL, ready for an Image), categories, keywords. A scene launches one with Solium.send("apps.launch", { id }), routed to the compositor’s existing spawn path (launch.rs) the same way windows.focus is; a running app is found by joining Windows’ appId to an Apps row’s id in the scene or in Lua, not by anything Apps itself tracks (no running, no windowCount here yet – qml/preview/Dock.qml is the one place in this tree that does that join, and its own file doc says why it is one WindowList per app rather than a single pass over Windows). sol.apps() is the same list, read from Lua, for config written against what is actually installed (lua/preview/dock.lua’s first-run pins) – but, like sol.windows() and sol.monitors(), only meaningfully inside a dispatch: a .lua file’s top level runs before the first real snapshot arrives, so sol.apps() there reads empty (lua/preview/dock.lua‘s own module doc works through this). image://solium/icon/<name>?size=48&scale=2 is the one provider behind Apps’ own icon and anything else a scene wants a theme icon for, by plain name (an absolute path is refused, not resolved – P1, icon.rs’s module doc). What is cut from this version of both: inotify (a scan is redone wholesale, synchronously, at startup and on a reload, not on every directory change); a cache in the icon provider (every request re-walks the theme chain); sol.icons{ theme = ... } (the theme is always GTK’s settings.ini, then Adwaita, then hicolor); SVG rasterises only where the Qt installation has the imageformats/libqsvg plugin, which this project’s own container image does not ship, so a PNG icon resolves everywhere this builds and an SVG-only one falls back to the default glyph there.

The desktop folder, live. Folder (04-ui.md §4.9) is every entry of Solium.dirs.desktop, a row model like Apps: uri, name, displayName (a launcher’s own Name=, else name), mime, icon (ready for image://solium/icon/, as Apps’ own is), isDir, isLauncher, trusted, hidden and modified. Unlike Apps, a row that leaves the folder is gone outright, not a ghost (nothing pins a desktop file the way a dock pins an app id), and unlike Apps’ wholesale rescan on a reload only, Folder is live: crate::folder::Watcher holds one inotify watch on the directory, polled every frame, and any change rescans the whole folder, wholesale, exactly the way Apps already prefers a simple rescan over incremental tracking. Empty, and costing nothing to watch or scan, with Solium.dirs.desktop empty. Solium.dirs.desktop is $XDG_DESKTOP_DIR, or the same key read from user-dirs.dirs, empty when neither names one or it names $HOME itself – a user whose whole home is “the desktop” gets no icons drawn over every file in it (crate::folder::desktop_dir).

A scene asks the compositor to do something about one entry the same way it asks anything else, Solium.send(action, data), answered by lua/actions.lua forwarding to sol.act (the folder service alongside windows, workspaces and apps): folder.open { uri } runs it – a regular file through the default application for its MIME type (the freedesktop mimeapps.list/mimeinfo.cache convention, crate::folder::default_app_id), a .desktop launcher through its own Exec= once trusted – launched the same way apps.launch launches, through crate::apps::launch_argv and the same Command::Spawn, so it gets the same clean environment and loading window. folder.trust { uri } marks a launcher trusted, durably, so it will run: tried first, gio set <file> metadata::trusted true itself answers “not supported” on this machine (GIO’s metadata:: namespace needs the gvfs metadata daemon, which nothing here can assume is running), so trust is kept the simplest durable way this repo already has instead – a plain file of trusted absolute paths under $XDG_DATA_HOME/solium/desktop-trust (crate::folder::Trust), the same fs::write shape session.rs and launch.rs already use for small state. sol.store would be the natural fit once it exists. done’s reason here adds "unknown-file" (no such entry), "no-handler" (no default application for the MIME type) and "untrusted" (an un-trusted launcher) to the vocabulary above – not yet listed there, the same gap apps.launch’s own "unknown-app" already left.

What is cut from this version: a subdirectory is one isDir row, not walked (a folder window is a scene’s own concern, not here yet); MIME detection is /usr/share/mime/globs2’s extension table, by hand, with no content sniffing; hidden follows only the leading-dot convention, not a .hidden list; folder.open_with (quick search as an app picker) and a durable, position-aware store once sol.store exists are both Later (crates/solium/src/folder.rs’s own module doc has the rest).

The keyboard, live. Keyboard, written unqualified like Theme, is the keyboard every scene reads, a window’s frame as much as a shell: layout (the live layout’s index into layouts, from 0), layoutName ("Russian"), layoutShort ("RU", the short name xkb’s own rules give it), layouts (every layout’s name, in order, as layoutName spells each), caps and num, each notifying as it changes, and changed(what) once in each frame in which the layout, Caps Lock or Num Lock really changed, what being "layout", "caps" or "num", and never for ordinary typing (models::keyboard::tests::the_keyboard_singleton_changes_once_for_a_layout_switch_and_a_caps_toggle). Before the keymap is known, layoutName and layoutShort read "". It is published once a frame, beside the monitors. It has no row types of its own, so the one name it takes in import Solium is Keyboard itself, as Theme takes Theme. It says what the keyboard is, where Solium.keyboard, above, is how an item asks for it, and a switch made while a scene holds the keyboard is told all the same (keyboard_change::tests::a_switch_made_while_a_scene_holds_the_keyboard_is_told_and_the_scene_types_with_it). Lua hears the same changes through sol.on("keyboard", ...), but for those made at the lock screen (state::tests::real_client::lock_focus::a_caps_toggle_at_the_lock_screen_is_not_told_to_the_configuration), and reads the focused text field’s caret with sol.text_input(), hearing it move through sol.on("text_input", ...), once a pass of the event loop at most (text_input::tests::text_input_is_told_when_the_caret_moves_once_a_pass).

Room of its own. A surface reserves edges of its monitor whatever its size. Lua declares it, reserve = { bottom = 48 } on sol.surface, and the scene can say it too, Solium.surface.reserve.bottom: bar.hidden ? 0 : 48, which wins for each edge it sets (state::tests::real_client::reflow_on_close::hosted::a_scene_reserve_overrides_its_edge_and_reflows_the_layout_once). A negative value, such as -1, gives that edge back to the declaration (qml::hosted::tests::a_negative_scene_reserve_gives_the_edge_back_to_the_declaration). Each edge of the work area loses its layer-shell zone and every reserve on it, added together (state::tests::real_client::reflow_on_close::hosted::two_surfaces_reserving_one_edge_take_both), and sol.monitors() and Solium.monitor.area are what is left (state::tests::real_client::reflow_on_close::hosted::a_declared_reserve_takes_its_edge_out_of_the_work_area). The reserving surface itself still covers its whole monitor (state::tests::real_client::reflow_on_close::hosted::a_reserving_surface_is_drawn_across_the_whole_monitor), so quick settings, a popup or a morph can grow out of a bar over the windows without changing the reserve, and no window moves when it opens (state::tests::real_client::reflow_on_close::hosted::a_panel_growing_out_of_the_bar_moves_no_window, qml::hosted::tests::a_panel_grown_out_of_the_bar_leaves_the_reserve_as_it_was). When the reserve does change, the layout runs once, in the dispatch that changed it, and the windows glide into the new work area with the layout’s own motion from that instant, on the compositor’s clock, which is the clock the bar’s animation runs on too (state::tests::real_client::reflow_on_close::hosted::a_reserve_the_scene_changes_at_a_press_reflows_the_tiled_windows_once_from_that_instant, state::tests::real_client::reflow_on_close::hosted::a_reserve_declared_again_or_taken_away_reflows_the_windows_once_each), and that includes a change a sol.on("surface", ...) handler makes, which re-flows the windows at the click that sent the action (state::tests::real_client::a_reserve_an_action_handler_changes_reflows_the_windows_in_the_clicks_dispatch). So bind it to where the bar is going, never to an animated value. A change the scene makes on its own, from a Timer, is read after the frame it was made in (state::tests::real_client::reflow_on_close::hosted::a_reserve_a_scene_changes_on_its_own_is_read_after_the_frame).

A way back to the configuration. Solium.send("windows.focus", { id: model.id }) sends a named action with data, an object, a value or nothing (qml::hosted::tests::solium_send_queues_every_action_with_its_data_in_order). Lua hears it as sol.on("surface", function(surface, action, data) ... end), with the surface’s name and the data as a table, a value or nil, in a dispatch after the one that sent it, every action in the order sent, and decides (script::tests::a_surface_action_reaches_lua_with_its_data, script::tests::an_action_with_no_data_reaches_lua_as_nil, state::tests::real_client::reflow_on_close::hosted::two_actions_from_one_frame_both_reach_lua_in_order). The shipped lua/actions.lua sends the vocabulary on to sol.act, the compositor’s one entry point for its verbs: windows.focus, windows.close, windows.fullscreen and windows.maximize, each with { id = <window id> } (state::tests::real_client::reflow_on_close::hosted::windows_focus_from_a_scene_focuses_the_window). sol.act’s data crosses as JSON, as a surface’s properties do, nested at most 64 deep and 65 536 values in all, a table counted once for each place it is in: a table nested deeper or holding more, or one that contains itself, is an error in the handler that sent it, not a crash or a stall of the compositor (script::tests::data_that_contains_itself_is_an_error_in_the_handler, json::tests::a_table_of_more_than_65536_values_is_an_error_not_a_stall). sol.act(action, data, done) answers an attempt id, and done(ok, reason) hears once whether it was done, after it was; reason is "unknown-action", "unknown-window", "bad-data", for a windows.focus behind the lock "locked", or, for a windows.fullscreen or windows.maximize of an X11 window, which the compositor cannot send there, "unsupported" (no test can make an X11 window, so that one is read in Solium::act), and a window still loading, one sol.windows() lists before its application has arrived, is "unknown-window" to all but windows.close (script::tests::sol_act_returns_an_attempt_and_done_hears_the_outcome_once, state::tests::real_client::reflow_on_close::hosted::sol_act_answers_why_it_could_not, state::tests::real_client::reflow_on_close::hosted::sol_act_tells_done_once_the_window_was_asked_to_close, state::tests::real_client::reflow_on_close::hosted::sol_act_on_a_window_still_loading_answers_unknown_window_but_closes_it, state::tests::real_client::lock_focus::sol_act_focus_behind_the_lock_is_answered_locked). It is told once the whole dispatch that ran sol.act is applied, a hotplug’s or a reload’s handlers included, and a done that acts again is told again in that dispatch, 16 rounds at most, the rest at the next one (state::tests::real_client::reflow_on_close::hosted::done_is_told_after_every_command_of_the_batch_that_ran_its_act, state::tests::real_client::reflow_on_close::hosted::a_sol_act_in_a_hotplugs_handler_hears_done_in_the_hotplugs_dispatch, state::tests::real_client::reflow_on_close::hosted::a_sol_act_in_a_reloaded_configuration_hears_done_in_the_reloads_dispatch, state::tests::real_client::reflow_on_close::hosted::a_done_that_acts_again_each_time_it_is_told_costs_rounds_not_the_session). Each done has the whole 100 ms handler deadline of its own, and one stopped at it does not stop the next (script::tests::a_done_that_never_returns_is_stopped_and_the_next_done_still_hears_its_outcome). What a done asked for in the run that was stopped is dropped, the attempts it started with it, so a retry that acts again and then never returns is stopped once, not every round; and its stops are counted by function, as a listener’s are, so one stopped three times is not called again until a reload, while a done written inline is a new function at each sol.act, and is stopped each time rather than taken out (script::tests::what_a_stopped_done_asked_for_is_dropped, script::tests::a_done_stopped_three_times_is_not_called_again, script::tests::an_inline_done_is_stopped_each_time_and_never_taken_out, state::tests::real_client::reflow_on_close::hosted::a_done_that_acts_again_and_never_returns_does_not_stall_every_dispatch). A workspaces.* action is the configuration’s to answer, since the compositor does not know what a workspace is: a file answers one with actions.override(name, function(data, surface) ... end), and until one does, sol.act answers it "unknown-action". An action outside the vocabulary goes only to the listeners for its surface, as a tweak’s does to tweaks.lua (script::tests::actions_lua_routes_the_vocabulary_and_leaves_the_rest_alone). An override is a surface listener of its own, under the same 100 ms deadline as every listener, so one stopped three times is taken out alone: every other action is still routed, and its own goes to sol.act again; a later override of the same name replaces it, and one of nil gives it back to sol.act (script::tests::an_override_stopped_three_times_is_taken_out_alone, script::tests::a_later_override_of_the_same_name_replaces_the_earlier_one, script::tests::an_override_of_nil_gives_its_action_back_to_the_compositor). A scene that sets a string property named action, as scenes did before Solium.send, is heard the same way, after what it sent, with no data (surface::tests::queued_actions_come_first_and_the_old_action_property_last). Anything Lua can do — sol.spawn, switching workspaces, any binding — a hosted shell can ask for this way.

What a pointer scene is given

The pointer is a scene too, when the configuration names one: cursor = { scene = "~/.config/solium/cursor/Cursor.qml" }, found as shell.scene is, or SOLIUM_QML_CURSOR for one run. It is built in the same engine as every other scene and is given this (ricing.md has an example):

• Every named shape. It is drawn for every shape a window names over its surface, through cursor-shape, and for every one the compositor asserts over its own chrome: the arrow over a titlebar, the resize arrows on the edges. No theme is asked (models::pointer::tests::a_configured_scene_hears_every_named_shape). A window that attaches a cursor surface of its own, or hides the pointer, is still drawn as it asked, over its own surface (cursor::tests::a_pointer_a_client_hides_stays_hidden_with_a_scene_configured).
• Solium.cursor, published once a frame for as long as a pointer scene is configured, and read the same in every scene: shape, the shape by its CSS cursor name (default, text, pointer, ew-resize, and so on); pressed; velocity, a point in logical pixels a second over the last frame, zero once the pointer stops; scale, the scale of the monitor under the pointer; and size, the configured cursor.size (models::pointer::tests::a_named_shape_reaches_solium_cursor_shape, models::pointer::tests::the_published_pointer_is_its_buttons_its_motion_its_monitor_and_its_size). A pointer that moved asks for the frame after, which publishes it standing still, and with no pointer scene nothing is published at all (models::pointer::tests::a_moving_pointer_asks_for_the_frame_that_says_it_stopped, models::pointer::tests::nothing_is_published_with_no_scene).
• A size of its own. The root’s width and height, up to 256 logical pixels a side, which the compositor reads and never writes, so a binding on them holds; a root that sets neither is cursor.size square (qml::pointer::tests::a_scene_sized_by_its_root_keeps_its_own_size).
• A hotspot. Solium.cursor.hotspot on its root is the point of its picture that sits on the pointer, the top-left corner by default. The picture is placed so that point is where every hit test asks, at every scale (qml::pointer::tests::the_hotspot_the_root_sets_is_the_scenes, cursor::scene::tests::the_scene_is_drawn_at_its_own_size_with_its_hotspot_on_the_pointer).
• The compositor’s clock. An animation in it runs on the clock every other scene’s does and asks for the next frame while it runs; at rest it asks for none (cursor::scene::tests::an_animating_scene_asks_for_the_next_frame_only_while_it_animates). ShaderEffect and MultiEffect draw on the GPU path (dev/wirecheck’s case 11); on the software path they draw nothing and the scene’s plain drawing is what shows.
• The cursor plane. Its picture is a Kind::Cursor element on both paths, so it is offered to the hardware cursor plane, and goes there when its size in device pixels fits the plane (commonly 64 or 128 pixels a side); a larger one is composited like any other element. A picture that reads the backdrop would be composited whatever its size; nothing can until materials exist (cursor::scene::tests::a_scene_with_no_material_is_a_cursor_plane_element).
• Only the monitors it reaches. It is drawn on each monitor its picture reaches onto, both of two while it crosses the edge between them, and not on the others (cursor::scene::tests::a_picture_is_drawn_only_on_the_outputs_it_touches).
• A reload that swaps it. super+shift+r builds it again when the file, any QML in its directory or the directories under it, or cursor.size changed, as an edit anywhere in a shell does, or when it would not load last time; one that would not load leaves the theme and the shipped arrow to draw the pointer (cursor::tests::a_reload_swaps_the_scene).

It is not hosted on a monitor and takes no input: Solium.monitor is the absent row, and Solium.send, Grab and Solium.keyboard do nothing in it. With no scene configured, nothing of this runs: the pointer is the theme, and then qml/cursor.qml, as before (cursor::tests::with_no_scene_configured_the_pointer_is_drawn_as_before).

What it is not given

Said plainly, because a shell that loads is easy to mistake for one that works:

• No compose or dead keys in a hosted field, and no input method: a field types what the key types.
• No clipboard of the session’s. ctrl+c and ctrl+v in a hosted field copy and paste within the compositor’s own Qt: what a window copied cannot be pasted into it, nor the other way round.
• No icons. There is no image:// provider for the icon theme. Driving the compositor goes through Solium.send and Lua.
• No touch. A scene takes no touch: a tap where it takes a press triggers nothing there, and neither reaches nor focuses the window under it; elsewhere a touch reaches the window under the shell, as the pointer would (state::tests::real_client::reflow_on_close::hosted::a_touch_on_a_shell_button_neither_reaches_nor_focuses_the_window_under_it). Scenes getting touch is #181; gestures are the touch epic #7, after v0.1.0.

What is still a client

Ordinary applications, over xdg-shell.

And any shell that is a program of its own, over wlr-layer-shell: Waybar, a wallpaper program, a Quickshell instance started as a process, a lock screen. They are started like any other program and need nothing from the configuration. Their top layer is drawn over a hosted shell, and the compositor reserves their exclusive zones from the work area.

Where a client’s bar goes, with more than one monitor

A layer surface names the output it wants, and the compositor honours it. That is how a client shell puts a bar on every screen: one surface per output, each with its own exclusive zone, each reserving from that monitor’s work area.

A surface that names no output gets the primary monitor — the one primary = true picks out in monitors, or the first if nothing does. Not the monitor the pointer is on, which is what it briefly was: a dock connects once, at startup, and pinning it to whichever screen the mouse happened to be over then means it appears somewhere different depending on where the mouse was left. That looks like the compositor placing it at random, because it is.

sol.monitors() gives a script the list, with primary and focused flags, so a shell written in Lua can decide for itself which screens get a bar.

What hosting costs, honestly

A hosted shell cannot crash independently of the compositor. A separate process can be restarted; a QML error in the dock takes the session with it unless the compositor is careful. So:

• Every scene is loaded defensively. A scene that fails to load is skipped and logged; it never stops the compositor starting.
• Scene errors are contained per surface — a broken dock must not take the window frames with it.
• An edit that does not parse leaves the last scene drawing.

That is the trade being made deliberately: robustness through care inside one process, in exchange for a desktop that can actually do what the design asks for. A shell that would rather have a separate process’s robustness can have it, as a client, and gives up the one engine to get it.

How the rest of the desktop starts

Whatever Solium loads itself starts with it and needs nothing below: its own QML scenes, and everything init.lua declares. A shell that Solium loads through its configuration is one of those, and needs none of this either. Every other program of the desktop is a separate process, and on a systemd machine it is started by the user’s systemd, or by D-Bus when something first asks for it. That covers a polkit authentication agent, a keyring, applets such as nm-applet, a bar that is a program of its own, and the portals.

So Solium tells both where it is (#146), when it is started as the session. The session file starts solium-session, which runs solium --tty --session. Once its Wayland socket is up, Solium sends WAYLAND_DISPLAY, XDG_CURRENT_DESKTOP (Lilium, unless the session file’s DesktopNames set it already) and XDG_SESSION_TYPE=wayland to systemd’s user manager (SetEnvironment) and to D-Bus activation (UpdateActivationEnvironment). It sends them again with DISPLAY once XWayland has one. Then it starts solium-session.target, which starts graphical-session.target, and solium-autostart.target, which starts xdg-desktop-autostart.target. session.rs has the tests, and the_calls_reach_systemd_and_dbus_as_their_methods checks the calls on the wire.

On the way out Solium stops solium-session.target, which takes the autostart target with it, and unsets the variables in systemd, so a Plasma login afterwards does not inherit a dead socket. It does so on a clean exit, and on SIGTERM (how logind ends a session), SIGINT or SIGHUP (signals.rs). A Solium that cannot stop, because something inside it has stopped answering, ends itself session.stop_timeout (five seconds) after the signal, or at once when the same signal comes again half a second or more later. Neither that nor a crash gives Solium the chance to clean up, so solium-session does it once Solium has gone, if the target is still active. If Solium failed before it started the target, while it waited up to five seconds for XWayland, solium-session unsets the variables, as long as no other desktop holds graphical-session.target (dev/install-check.sh checks each case).

Two things are left behind even so. A SIGKILL of the whole session, which systemd sends to whatever of it is still running once its stop timeout has passed (45 seconds on Fedora 44), takes solium-session with it; the next Solium session stops any target an earlier one left running before it says anything. And under dbus-daemon, the D-Bus activation environment keeps the variables, because D-Bus has no call that removes one. Fedora’s dbus-broker hands UpdateActivationEnvironment on to systemd’s SetEnvironment (its launcher names that method), so there the unset should clear them for D-Bus activation too; that has still to be seen on a real session.

One Solium session runs per user at a time: solium-session holds a lock for as long as its session runs, and refuses to start a second, which would take the first one’s target for a leftover and stop it.

When Solium is not the session, it tells nobody. solium --tty started by hand, from a text console, leaves systemd and D-Bus alone: a desktop on another VT shares them, and its display is not Solium’s to replace. A nested Solium leaves the session it runs in alone for the same reason. And a Solium session that finds graphical-session.target already held by another desktop of the same user leaves systemd and D-Bus to that desktop, and says so in the log.

session.systemd = false turns all of it off. session.autostart = false leaves out solium-autostart.target, and so XDG autostart, while solium-session.target and every unit attached to it still start. dev/install.sh puts both targets in ~/.config/systemd/user and lilium-portals.conf in ~/.config/xdg-desktop-portal.

A program that should start with a Solium session can do it in one of two ways.

XDG autostart. Put a .desktop file in ~/.config/autostart, or in /etc/xdg/autostart for every user. systemd’s autostart generator turns each into a service when xdg-desktop-autostart.target starts. It skips any whose OnlyShowIn= does not name Lilium, whose NotShowIn= does, or that says X-systemd-skip=true:

[Desktop Entry]
Type=Application
Name=Network applet
Exec=nm-applet --indicator
OnlyShowIn=Lilium;

A systemd user unit. It is tied to the graphical session, so it stops when Solium does, and attached to solium-session.target, so it starts whether autostart is on or not:

[Unit]
Description=A bar
PartOf=graphical-session.target
After=graphical-session.target

[Service]
ExecStart=/usr/bin/waybar
Restart=on-failure

[Install]
WantedBy=solium-session.target

Save it as ~/.config/systemd/user/bar.service and enable it with systemctl --user enable bar.service. WantedBy=graphical-session.target also starts it under any other desktop that runs a systemd session, such as Plasma or GNOME. solium-session.target starts it only under Solium.

Polkit agents and keyrings start the same way, and most say which desktops they are for. Fedora’s KDE polkit agent, for instance, ships /etc/xdg/autostart/polkit-kde-authentication-agent-1.desktop with OnlyShowIn=KDE; and X-systemd-skip=true, so autostart skips it under Lilium, and a copy of it would be skipped too. It also ships plasma-polkit-agent.service, which is already PartOf=graphical-session.target, so a single command starts it with every Solium session, autostart on or off:

systemctl --user add-wants solium-session.target plasma-polkit-agent.service

A keyring that D-Bus starts on demand, such as KWallet’s kwalletd6, needs no entry: once the environment is exported, the first program that asks for a secret starts it. It is not unlocked with the login password, though. Under Plasma, plasma-kwallet-pam.service runs /usr/libexec/pam_kwallet_init, which hands the wallet what PAM kept at login, through the socket named by PAM_KWALLET5_LOGIN. Solium does not export that variable to systemd, and the script does nothing without it, so the wallet asks for its password the first time it opens.

Summary

History: the dock that proved it

The first in-compositor dock was compositor code — shell.rs and sol.dock — and it was taken back out, as the compiled-in bar before it had been: it made the compositor own a design, a font stack and a layout it had no reason to, and it hid the question of how a replaceable shell attaches instead of answering it. layer.rs records that for the bar, and surface.rs for the dock. The answer is the one above: the shell is configuration, and the compositor hosts whatever the configuration names.

The dock was a QML scene rendered by the same host that draws the window frames, importing the same Solium.Theme, reserving its own strip out of work_area. The morph was the whole argument made concrete: pressing an icon fired a dock event carrying the rectangle that icon occupies, a script spawned the program and handed that rectangle to sol.present_from, and the window grew out of it. Captured frame by frame in docs/morph.png, a record of 2026-09-06 and of a dock that no longer exists — 460x208 near the dock, then 928x504, 1192x672, settled at full size about a third of a second later.

sol.present_from is still there and still does that. What is missing is a dock to give it a rectangle. config.lua carried a dock.morph duration for the day one exists, and #117 removed it — nothing had ever read it, and a setting configuring a component that does not exist cannot be told apart, from outside, from one that is broken. --check reports that spelling as an unrecognised key now, and a dock brings its settings back to that spot when it arrives.

None of that is reachable from a separate process. A client dock can pass a rectangle over IPC, but by the time the window exists the two are separate scenes and nothing holds both at once to interpolate between them. That is why a shell is hosted here rather than run beside the compositor as a program of its own: hosted, its icons are in the same engine as the window frames, so the flight planned above can be a live instance of the icon’s own component rather than a fake.

Pane styles

A pane is one window and its decoration. A style is the folder that says what that looks like: a Pane.qml naming what the frame reserves and a list of layers, each its own QML scene, each at its own depth.

There is nothing to compile and no compositor code to touch: write a folder, name it in your configuration, and it draws every window.

-- ~/.config/solium/user.lua
return { pane = "left" }

A name is one of the folders here, or one of your own in ~/.config/solium/qml/panes/ – yours shadows a shipped one of the same name. A path is anywhere. SOLIUM_PANE=left does the same thing for one run, which is the quicker way to try one.

Press super+shift+r and the running session picks up the change: the configuration is read again, the QML cache is dropped, and every pane is rebuilt. Windows keep their slots, and each client is resized to whatever the new style left it.

Everything the shipped layers draw with – colours, fonts, spacing – comes from Solium.Theme, the same singleton the loading window reads, and a hosted shell that imports Solium can read it too. The shipped theme is dark and has no hue in it: near-black bars, light grey titles, grey buttons, and an accent that is a light grey too. The fallback pointer and the default wallpaper do not read it: their colours are fixed. Nor, in part, does the keyboard pill: its capsule is Theme.accent and its glyph and label Theme.accentInk, but its shadow is fixed black. A Solium/Theme.qml of your own in ~/.config/solium/qml/ is meant to restyle all of them without touching anything that ships, and does not yet, because the shipped module is found first (#88).

The styles with buttons – top, bottom, left, reveal, reactive and pulse – tell close from maximise without a colour: under the pointer each turns its own grey (Theme.danger, the lighter, and Theme.warning) and shows its glyph on it in Theme.accentInk, × to close and + to maximise. crates/solium/tests/scenarios/pane-buttons-drawn.lua points at each and reads the pixels.

The manifest

Pane.qml is the entry point, and its root is a PaneStyle. It declares structure; it never draws. The compositor builds it once at 1x1, reads what it says, and throws it away.

import QtQuick
import Solium

PaneStyle {
    insets.top: 32
    requires: []

    Layer { depth: "behind"; bleed: 24;            Rectangle { anchors.fill: parent } }
    Layer { depth: "frame";  source: "Frame.qml" }
    Layer { depth: "above";  bleed: { "top": 48 }; source: "Spikes.qml" }
}

Insets are on the style and never on a layer. The client is placed once and every layer sees the same client rect, so three layers each declaring insets would be three answers to one question.

A folder without a Pane.qml is not a style. A bare name skips it and goes on to the next place it would have looked, so an empty panes/top/ of your own does not quietly replace the shipped top with a window that has no frame.

In a checkout of the repository, crates/solium/tests/fixtures/panes/example/ is the format written out in full – all three depths, both spellings of bleed, inline content and delegated content – and

solium --check-qml crates/solium/tests/fixtures/panes/example/Pane.qml

says whether it still parses. It loads every layer the style names in source: too, prints ok for each file or what Qt reported, and exits with 1 when any of them does not build, naming the file.

A style that cannot be loaded – a layer that will not build, a requires that cannot be met, a name that is nowhere – leaves each window it was for with no frame at all and no space reserved for one, and says so in the log (#90). Fixing it and pressing super+shift+r frames the windows opened after that; one already left bare stays bare until it is opened again.

Layers

Content is written inline or delegated with source:, and the syntax does not change between the two. Each layer is rasterised into a scene of its own and becomes its own element in the frame, which is what lets the client’s surface sit between two layers of one style – the thing a single QML file can never do.

Layers at one depth are drawn in declaration order, the later one on top. Pointer input goes to every layer. When more than one layer sets action for the same press, the topmost is the one acted on.

A delegated layer’s root is an ordinary Item. It is its own scene, with no parent to read anything off, so it declares the properties it uses itself.

What the compositor sets on every layer

Every frame:

When they change, in place, and to a frame built later as well:

A layer drawing at the caret is drawn with its window, so whatever the window is doing – moving, scaling in a thumbnail, fading – the drawing does too. Every layer can also read the keyboard, Keyboard in import Solium: the live layout, its names, and whether Caps Lock and Num Lock are on (docs/shell-boundary.md, “The keyboard, live”). The attached Solium object and Grab are a hosted shell’s. In a layer they build and do nothing, and Solium.monitor reads an absent row with an empty name (docs/shell-boundary.md, “The Solium QML module”).

Once, at build, because neither ever changes for a style:

Of these, PaneStyle declares only bleedLeft and bleedTop. The four inset names and the five clientRadius names reach only a delegated layer that declares them on its root. An inline layer reads its manifest instead: insets.top and the other three, client.radius, and client.radiusTopLeft and the other corners, where -1 means the corner follows client.radius. It has no clientRadius.

Read back by the compositor:

A layer declares only the ones it uses; one that positions nothing against the window declares no bleedTop and is handed a property it ignores.

A layer whose buttons do not declare onButton has them drag the window instead of pressing. The shipped top keeps the name of the button under the pointer in a hovered string of its own and derives the flag from it:

property string hovered: ""
readonly property bool onButton: hovered !== ""

hovered on its own is read by nothing. left, bottom, pulse, reactive and reveal declare hovered and not onButton, so their buttons may not press (#158).

The pointer arrives as ordinary mouse events, in the layer’s own coordinates, while it is anywhere over the window – including over the client, which is how a border can follow the cursor. When it leaves, the layer is told with a position outside itself, so MouseArea.containsMouse goes false on its own. A layer with bleed is given the pointer in its own canvas, so a click lands on whatever that layer drew there. Presses are narrower than hover: they reach the layers only inside the band the insets reserve, so a button drawn over the client, out in the bleed, or in a style that reserves nothing cannot be pressed. Touch reaches no layer: a finger on a frame’s close or maximise button, or on its edge, presses nothing and resizes nothing (#181), though outside the tablet and phone form factors the tap still focuses the window.

What it costs

QML renders on one of two paths: the GPU, the default on the hardware when a trial render at startup passes, or software, which is what a nested session, qml.renderer = "software" and a failed trial get. The log line that begins QML renderer: says which.

On both, anchors.fill: parent fills the canvas, which is the pane grown by the bleed this layer declared – not the window. Bleed is a cost and not a permission: the canvas is that much larger, and every pixel of it is drawn again when the layer changes. A bar throwing spikes upward should ask for { "top": 48 } rather than 48, and not pay for three sides it never touches. It is also a promise rather than a request: the layer is clipped to the canvas it asked for, so no one style can force a full-screen repaint every frame.

On the GPU a layer is drawn straight into a buffer the compositor allocated, and nothing is copied or uploaded.

In software a changed layer is rasterised on the CPU, copied and uploaded. A layer that stays inside the style’s own insets has only those bands copied, and the upload is the one box around them: for a titlebar that is about 4% of a window, and for a style that reserves all four sides it is the whole window. A layer that reserves space and paints outside it must say so, or what it paints outside is not copied:

property bool overlay: true

Declare it only if you need it; the alternative is usually to reserve the couple of pixels you were painting over. A layer at behind or above, a layer with any bleed, and every layer of a style that reserves nothing are overlays already and need not say it. On the GPU the property changes nothing.

A layer that is usually empty can say so. Every layer costs what its canvas costs whether or not anything is in it: a buffer that size, and an element blended over the client wherever the client changes, and in software the whole canvas copied and uploaded at every step of a resize. A layer that binds dormant to “nothing to show” is left out of the frame while it is true, so nothing of it is blended or uploaded, and on the frame it goes to sleep it lets go of its image, so waking is a resize that draws it afresh. On the GPU its scene keeps the buffer it was last drawn into until it is drawn again, and one dormant from its first frame never has one larger than a pixel. It is a general mechanism – any layer may bind it, and nothing in the compositor knows what a layer is for – and the keyboard pill below is the shipped user. Wake it from something it is told (values, caret, focused): a dormant layer’s own animations ask for no frames.

A rounded client costs no pass. client.radius is drawn as the client is: each of its surfaces goes through a fragment program where it already is, so rounded/ and flush/ cut the client’s corners at no extra cost, with no pass and no copy of the window, and keep them while the window is tilted or pulled by a genie. A rounded window that fades in or out is faded surface by surface, with no picture of it taken: where a subsurface overlaps its parent (a player’s video over its window, say) the two show through each other while the window is translucent. An opaque window looks as it always did.

Animations need nothing declared. Qt is asked each frame whether the scene has anything new to draw, and the compositor draws only then – so an idle layer costs a flag read, a transition runs at the screen’s refresh rate, and a loop with a pause in it survives the pause. Bear in mind only that a layer which never stops animating never stops costing anything. The one measurement, from 2026-09-06 on the software path before the GPU one existed, is the whole compositor at about a tenth of a core with pulse animating at the screen’s full rate. Bind an endless animation to focused, as pulse and the wave demonstration do, and an unfocused window costs nothing.

What is here

none is not a folder: pane = "none" draws no frame and builds no scene per window.

Each of those eight is one frame layer, which is what every decoration was before styles had layers, and the keyboard pill’s layer, described below. The rest are here to show what layers add:

And four demonstrations, which are not shipped and are never offered by name. They live with the test fixtures in a checkout, in crates/solium/tests/fixtures/panes/, and SOLIUM_PANE=<that path>/<name> puts one on every window:

The keyboard pill

Every style here ends with one line:

PaneStyle {
    Layer { depth: "frame"; source: "Frame.qml" }
    KeyboardPillLayer {}
}

KeyboardPillLayer, in import Solium, is an inline layer at above that draws KeyboardPill – the small capsule saying Caps Lock is on, or which layout you just switched to – just below the pane’s caret, or above it when the pane has no room below. It shows what the configuration hands it, values.keyboard_indicator, and nothing when that says not to: the policy is lua/keyboard_indicator.lua, set by keyboard.indicator in config.lua, and docs/ricing.md has the whole of it. A style of your own gets the pill by adding the same line, and a style without it has none. A window drawn bare – fullscreen, one drawing its own decorations, or every window under pane = "none" – has no style around it at all, and the configuration draws its pill on a surface instead.

KeyboardPill shows what its cue says and decides nothing. cue is { what, serial, hold, duration, after }. what is "caps" (an outlined ⇪), "layout" (Keyboard.layoutShort), "num" (⇭), or "" to hide at once. A cue is taken only when its serial is new, so handing the same cue again shows nothing. With hold: true it stays until the next cue. Otherwise it hides after duration milliseconds (1200 when not given), or, when after names one of the three, shows that one instead, held. While accepts is false, a new cue hides it rather than showing. It is the capsule, 28 high and at least 32 wide, in Theme.accent with its glyph or label in Theme.accentInk, with a margin of 14 on every side for its shadow, and it centres the capsule in itself. KeyboardPillLayer hands it values.keyboard_indicator, which the configuration sets as { show, cue }, and draws only while show is true and the pane’s caret is valid.

It is a layer of its own because it draws over the client, and in software a frame layer that reserves a band copies only that band. So it costs one more scene per window. While no pill is on show it is dormant, which is nearly always: not drawn, nothing blended over the client, and in software no image kept. It is drawn only from the cue that shows a pill until that pill has faded. A style that leaves the line out pays nothing for it at all. crates/solium/tests/scenarios/keyboard-pane-drawn.lua draws it in top, reads its pixels, and reads when it is dormant.

One QML file is still a decoration

A style can also be a single .qml file with an Item at its root, under ~/.config/solium/qml/decorations/, named the same way. It is one layer at frame, and it declares its own insetTop/insetRight/insetBottom/ insetLeft rather than being told them – a single file has no manifest, so it is the only place those numbers can live. It has no manifest to add KeyboardPillLayer {} to either, so with keyboard.indicator.show = "pane" its windows show no keyboard pill: draw one at caret yourself (with property bool overlay: true, since it paints over the client), or set show = "surface".

Nothing ships as one any more: the eight above were single files until the pane-styles work moved them into folders. The path stays because those files exist on people’s machines, and because a style needing neither layers nor bleed should not have to become a folder to say so.

Configuration

This page is config.lua, the file that sets every default, with its comments as the text and its settings as the code. To change a setting, write only that setting in ~/.config/solium/user.lua; Every setting is the index.

Every setting the configuration can reach, in one place.

Values were scattered across the layout scripts as local constants, which is hardcoding written in a scripting language. A setting nobody can find is not a setting. Nothing here needs the compositor rebuilt.

Don’t edit this file: an install replaces it, and it is also the defaults. Write only what you want changed in ~/.config/solium/user.lua ($XDG_CONFIG_HOME/solium/user.lua when that is set) and it is merged over these:

return {
    gap = 4,
    pane = "reactive",
    tiling = { split = 0.618 },
}

Nested tables merge key by key, so tiling = { split = ... } keeps the animations below it. Lists are replaced whole, because a list of widths with one entry changed is a different list, not a longer one.

Not here yet, because nothing reads them from this file (#159):

• Whether focus follows the pointer, natural scrolling, and the key held to drag a window: SOLIUM_FORM_FACTOR picks all three, and SOLIUM_DRAG_MODIFIER the key alone.
• The terminal super+return opens: SOLIUM_TERMINAL, or bind super+return yourself in bindings below.
• The overview’s animations, fixed in lua/overview.lua at 260 ms in and 200 ms out.
• How long a closing window takes to fade, fixed in the compositor at 190 ms.

gap

Space between windows and around the work area, in logical pixels.

The default:

gap = 12,

wallpaper

The wallpaper.

The one that ships is the default; a path replaces it, and false turns it off. Turn it off if you run swaybg, hyprpaper or a shell that draws its own – a layer surface on the background layer is drawn over this one, so leaving both on means paying for a picture nobody sees.

wallpaper = "~/Pictures/whatever.png",
wallpaper = false,

A list gives each workspace its own background, and it travels with that workspace: workspaces.lua puts it in the same selection as the desk’s windows, so one animation carries both and the wallpaper stops being left behind when you switch.

wallpaper = { "~/Pictures/one.png", "~/Pictures/two.png" },

Fewer pictures than workspaces cycles. It costs a scene per desk on every monitor, built when it is declared, and one screen-sized rasterisation per desk you have actually visited, per monitor, which is why a single image stays a single static surface: every desk sharing one picture makes a wallpaper that slides pixel-identical to one that does not, so it would be memory spent on nothing to look at.

~ is expanded. The image is cropped to fill the screen rather than fitted, so nothing is letterboxed.

What actually draws it is lua/wallpaper.lua and qml/wallpaper.qml, and that is the more interesting part: there is no wallpaper code in the compositor at all. It is a short script around one sol.surface call, which draws any QML scene at any layer on any monitor – so a bar, a dock or a heads-up display is the same call with a different layer. Copy qml/wallpaper.qml to ~/.config/solium/qml/ and the background can be a gradient, a shader or a clock. super+shift+r reloads it. A copy that still shows source needs the picture named by its path here: the shipped one is found beside the shipped QML, not beside yours.

The default:

wallpaper = "solium",

shell

A shell: the bar, the dock, the launcher.

A shell is a project of its own, with its own repository, and it runs here as your configuration: its QML is hosted in the compositor’s own engine, beside the window frames. Name its root file:

shell = { scene = "~/.config/solium/shell/shell.qml" },

false, the default, hosts none. ~ is expanded. It is drawn once on every monitor, over the windows, across the whole monitor, and each instance reads its own monitor as Solium.monitor. on = "primary", or a connector name, draws one instead. It takes the pointer only where its items take input, and the windows under it get the rest (a_press_where_the_shell_draws_nothing_reaches_the_window_under_it). See the_shell_scene_is_read_from_the_configuration and the_shell_is_on_every_monitor_unless_the_configuration_names_one. SOLIUM_SHELL_SCENE overrides this, because that is set per run. super+shift+r picks up a change. See docs/shell-boundary.md for installing one and for what the compositor provides to a shell it hosts.

Its bar keeps the windows out of its strip by saying so in the scene, Solium.surface.reserve.bottom: 48, and quick settings growing out of it move no window. See a_panel_growing_out_of_the_bar_moves_no_window.

outside_click: what a press outside an open popup of the shell does, after closing it: “swallow” (macOS and iOS do this), or “pass” to also click what is under it. A table names popups by their grab’s name:

outside_click = { default = "swallow", ["tray-menu"] = "pass" },

See the_shell_takes_its_outside_click_from_the_configuration and a_press_outside_a_grab_dismisses_it_and_is_swallowed_by_default.

What it asks for, Solium.send("windows.focus", { id: ... }) in its QML, reaches sol.on("surface", ...), and lua/actions.lua has the compositor do the window actions. See windows_focus_from_a_scene_focuses_the_window.

keyboard.bindings: while the shell holds the keyboard (a search field, a password), which compositor bindings still work: “except_claimed” (the default; every binding but the keys the field claims), “all”, or “none” (every key but the Ctrl+Alt escapes goes to the shell). See the_shell_takes_its_keyboard_bindings_from_the_configuration and a_claimed_key_reaches_the_scene_and_not_its_binding.

A layer-shell bar (Waybar and the like) needs nothing here: it is an ordinary client, and you start it as one.

The default:

shell = {
    scene = false,
    on = "every-monitor",
    outside_click = "swallow",
    keyboard = { bindings = "except_claimed" },
},

preview

The compositor’s own preview shell: a bar, built as configuration on the same public API shell above describes (lua/preview/, qml/preview/; see docs/ricing.md). On by default, so a fresh install shows live workspaces, windows, the keyboard layout and a clock rather than a blank desktop.

preview = false,

Turns it off. Naming your own shell.scene above, or user.lua’s own shell, always wins over it either way – this only ever fills in a default nothing else set.

A table instead of true reaches the top dock (lua/preview/dock.lua, 04-ui.md §4.6): preview = { dock = { pinned = { "org.mozilla.firefox", "kitty" }, visibility = "always", icon_size = 48 } }. pinned is a list of desktop ids; left unset, the dock picks the first installed terminal, file manager and browser itself. visibility is "always" or "autohide" (the default).

Quick search (lua/preview/search.lua, 04-ui.md §4.7) opens on super+d: preview = { search = { key = "super+alt+space" } } binds a different one instead. It searches installed applications, open windows and a few compositor commands; see docs/ricing.md for what is cut from this first version.

Desktop icons (lua/preview/desktop.lua, 04-ui.md §4.9) show Solium.dirs.desktop ($XDG_DESKTOP_DIR, or user-dirs.dirs; empty draws nothing): preview = { desktop = { icons = true, from = "top-right", cell = { width = 96, height = 100 }, labels = 2, open = "double", show_hidden = false, reveal_on_click = false } }. icons = false turns them off; from is "top-right" (the default) or "top-left"; open is "double" (the default) or "single". See docs/ricing.md for what is cut from this first version (dragging and saved positions, right-click menus, showing the desktop, Open With, thumbnails).

The default:

preview = true,

keyboard

The keyboard: its xkb layouts (layout, variant, options, model, rules, active), the locks (caps, num), the repeat rate, and the keyboard pill.

No xkb name is set here, and that means “whatever the session already said”. Every name below is an xkb name, and leaving one out makes xkbcommon fall back to the matching XKB_DEFAULT_* environment variable – which is where a display manager or a ~/.profile usually puts it, and which worked before any of this existed. Naming one here takes precedence.

keyboard = {
    layout  = "us,ua",
    variant = ",",
    options = "grp:alt_shift_toggle,compose:ralt",
    model   = "pc105",
},

• layout: a comma-separated list. The first is the one you start in; the log line keyboard says what the session ended up with.
• variant: one per layout, in the same order, and blank for “plain”. “us,ua” with “,dvorak” is US ordinary and Ukrainian Dvorak.
• options: xkb options, comma separated. grp: ones switch layout and are handled inside the keymap, so they work without the compositor being involved. compose:ralt gives a compose key, which is the nearest thing to an input method until #26 lands.
• model: rarely worth setting; “pc105” is assumed by the rules.
• rules: the xkb rules, rarer still. Blank, like the others, falls back to the environment.
• active: which of the layouts is live, counting from 1. A number past the last layout is warned about and changes nothing.
• caps: Caps Lock on or off, and num the same for Num Lock: num = true here turns Num Lock on when the session starts and again at every reload. Set by pressing the keymap’s own key inside the compositor, so the layout stays where it was.

The repeat rate is the compositor’s own, not xkb’s, so no environment variable reaches it and this is the only place it can be set:

• repeat_rate: repeats per second after the delay. 25 is the default.
• repeat_delay: milliseconds held before repeating starts. 200.

super+shift+k cycles the layouts, and it is one call of the same function, so a binding of your own can switch them the same way:

sol.bind("super+shift+k", function()
    local kb = sol.keyboard()
    sol.keyboard{ active = kb.active % #kb.layouts + 1 }
end)

sol.keyboard() with no argument returns the layout names, which one is active and its names (layout_name, “Russian”, and layout_short, “RU”), whether Caps Lock and Num Lock are on, and the repeat settings. sol.on("keyboard", function(state, changed) end) hears the layout or a lock change, however it changed, and a hosted scene or a pane style reads the same in QML as the Keyboard singleton.

keyboard.indicator

The keyboard pill: a small capsule near where you are typing that says Caps Lock is on (⇪) or which layout you just switched to (EN, RU), after the one macOS shows. It is configuration and not a compositor feature – lua/keyboard_indicator.lua is its policy and reads this table; the QML draws it from the data the compositor publishes, in Theme’s accent – so it is the example to copy for anything of your own that reacts to the keyboard or the caret. Delete require("keyboard_indicator") from init.lua and it is gone. See docs/ricing.md, “The keyboard pill”.

The default:

indicator = {
    -- Where it is drawn:
    --   "pane"     inside the window, just below the text field's
    --              caret, or above it when there is no room. Each
    --              shipped pane style draws it with one line,
    --              `KeyboardPillLayer {}`, and moves, scales and fades
    --              it with the window. A style of your own without
    --              that line draws none. A window drawn with no frame
    --              -- fullscreen, one drawing its own decorations, or
    --              any window under `pane = "none"` -- gets the
    --              "surface" pill at its caret instead.
    --   "surface"  on a surface of its own over everything, at the
    --              caret on screen, moved after it as the
    --              application says its caret has moved.
    --   false      nowhere; `indicator = false` says the same.
    -- The caret is known only from applications that say where it
    -- is, through the `text-input-v3` protocol; for the rest, see
    -- `fallback`.
    show = "pane",
    -- Which changes show it: switching layout, Caps Lock, Num Lock.
    -- A lock's pill stays while the lock is on and goes the moment it
    -- is off; a layout's goes after `duration`, and hands back to the
    -- lock's if one is on.
    on = { layout = true, caps = true, num = false },
    -- Show Caps Lock's pill again when a text field is focused while
    -- Caps Lock is on, as macOS does. Only while `on.caps` is true.
    caps_on_focus = true,
    -- With no caret to go to -- an application that says nothing about
    -- one, or no text field focused -- "surface" draws it on the
    -- focused window's monitor, and false draws nothing.
    fallback = "surface",
    -- Where on the monitor that is: "bottom", "center" or "top",
    -- centred across it.
    position = "bottom",
    -- How long a layout's pill stays, in milliseconds.
    duration = 1200,
},

bindings

The keys, and what they do.

The shipped bindings are sol.bind calls in init.lua, and init.lua is the session’s entry point – so until #117 the only way to add one key was to write your own copy of that file and adopt two hundred lines of layout wiring, mode setup and terminal detection along with it, or to edit a file the next update overwrites. Neither of those is a setting. This table is: it is merged over these defaults exactly as tiling and scrolling are, so a user.lua holding nothing but a binding is a complete configuration.

bindings = {
    ["super+b"]       = "firefox",
    ["super+shift+s"] = { "sh", "-c", "grim -g \"$(slurp)\"" },
    ["super+n"]       = function() sol.spawn("kitty", "-e", "nvim") end,
    ["super+g"]       = false,
},

Four forms, each the shortest way to write what it means:

• a string: a command line, split on spaces. The common case is a program and no arguments, and that should read like one.
• a list: the same, already split, for an argument with a space in it – the shell quoting above is one argument, not three.
• a function: anything else. The whole sol API is in scope, so this is a binding in exactly the sense init.lua’s are.
• false: unbind. A shipped binding you do not want is otherwise unremovable, and binding it to a function that does nothing is not the same thing: the compositor would still swallow the key.

The combination is written the way you would say it and normalised by the compositor, so super+shift+q and Shift+Super+Q are one binding.

A binding here replaces a shipped one on the same combination, rather than being an error. Two reasons, the second deciding. The first is consistency: sol.bind has always let the later call win, so a clash refusing here would make this table alone behave unlike the primitive underneath it. The second is that refusing would permit adding a binding and forbid changing one, and changing one is what people come here to do: super+q closing a window is a choice, not a law, and “you may not rebind it” leaves editing init.lua as the only way – which is the fault this section exists to remove.

Replacing is not the same as replacing quietly. solium --check prints every binding this table produced, marks the ones that took a shipped combination over, and lists the ones it removed, so a clash you did not intend costs a line of output rather than an afternoon wondering why a key stopped working.

Applied by lua/bindings.lua, from the last line of init.lua, because that ordering is the replacement – “the later call wins” only puts these last if they are read last. In your own init.lua, keep require("bindings") last for the same reason.

One thing this cannot check: a combination is whatever you press, so there is no list of valid names to compare yours against. super+whoops binds successfully and never fires. --check prints what was bound, which is the only honest answer available – read it and look for the key you meant. The documentation’s Key bindings page lists every binding that ships, and what each does.

super+return opens SOLIUM_TERMINAL, or else the first terminal that is installed. There is no setting for it yet (#159), so to choose one here, bind the key: ["super+return"] = "foot".

The keys that get around a desktop by direction (#150) are replaced here like any other. They ship in direction.lua and modes.lua:

super+arrows, super+h/j/k/l          focus the window that way
super+shift+arrows,                  move it that way, and at a
  super+shift+h/j/l, super+alt+k     screen's edge onto the next one
super+f                              fullscreen, and back
super+shift+m                        maximised, and back
super+shift+space                    float over the layout, and back

Up on k is super+alt+k because super+shift+k cycles the keyboard layout (init.lua). What a direction does is the layout’s: see tiling.move below, and docs/modes.md. Pressed with either half of us,ru live: the_direction_and_window_keys_fire_while_russian_is_active.

bindings = {
    ["super+ctrl+h"] = function() sol.focus_direction("left") end,
},

The default:

bindings = {},

cursor

The pointer.

Empty means “whatever the session already said”, exactly as keyboard above does and for the same reason: XCURSOR_THEME and XCURSOR_SIZE are what GTK, Qt and every other toolkit on this machine follow. A display manager or a ~/.profile usually sets them, and a compositor that quietly overrode them would be the one thing on screen drawing a different pointer from everything else.

cursor = { theme = "Adwaita", size = 24 },
cursor = { scene = "~/.config/solium/cursor/Cursor.qml", size = 32 },

• scene: a QML scene to draw the pointer with, configured the way shell.scene is: a path (~ is expanded), or a name looked for in ~/.config/solium/qml/ and then the shipped QML. It is drawn for every shape, ahead of any theme, and reads Solium.cursor: the shape asked for (default, text, pointer, ew-resize…), pressed, velocity, scale and size. It sets Solium.cursor.hotspot on its root, and is as big as its root says, so a glow can reach past size. It may animate. A window that draws its own cursor, or hides it as a game does, still does over its own surface. SOLIUM_QML_CURSOR=<file> is the scene for one run, over this. docs/ricing.md has an example.
• theme: the name of an XCursor theme – a directory under ~/.icons, ~/.local/share/icons or /usr/share/icons. ls /usr/share/icons lists the ones this machine has. Naming one here takes precedence over XCURSOR_THEME.
• size: how big the pointer is, in logical pixels, between 8 and 256. Multiplied by each monitor’s scale, so 24 is 24 pixels on a 1x screen and 48 device pixels on a 2x one – which is why a single number is still right on a desk with monitors at different scales. Takes precedence over XCURSOR_SIZE. Outside that range it is ignored, with a line in the log, and the next source has its turn – not clamped, because a pointer three pixels across is as hard to find as no pointer at all and nobody meant to ask for one.

So the order is: what is written here, then the environment, then 24 logical pixels and no theme at all.

No theme is not a missing pointer. Solium draws its own from qml/cursor.qml, and that is what you get with no scene and no theme set here, nothing in the environment, or a theme named that turns out not to be installed – the log says which. It is a white arrow with a dark outline, in fixed colours rather than the theme’s, because a pointer has to read over whatever a client drew, and it is one arrow for every shape. A scene that would not load is drawn as no scene is, with a line in the log, and a reload tries it again.

A shape your theme does not have is the one case that does not reach it. Applications name the cursor they want – an I-beam over text, a resize arrow on an edge – and a theme is free to have drawn only some of them; the missing ones fall back to that theme’s own arrow, so a themed session stays wholly themed rather than mixing two designs.

Applied on reload, so trying a theme or a scene out is super+shift+r; a scene whose files changed is built again then. The compositor call is sol.cursor_theme(...); sol.cursor() is a different function that answers with where the pointer is.

The default:

cursor = {},

qml

How QML – the frames, the pointer, the wallpaper – is rendered.

• renderer: “auto” renders on the GPU when a trial render in a separate process passes, and in software when it fails or times out, or when this build’s last GPU start in the compositor did not work (see dev/README.md); nested, it is software. “gpu” skips the trial and “software” never uses the GPU. Anything else warns and means “auto”. --qml <mode>, then SOLIUM_QML, then SOLIUM_QML_GPU override this.
• probe_timeout: how long the trial may take, in milliseconds, before it is killed and QML renders in software.

Read when the compositor starts; a reload does not change it, because Qt cannot change scene graph once started. The last log line that begins “QML renderer:” says which one this session got, and why. Tests: qml/renderer.rs and the_shipped_configuration_asks_for_auto.

The default:

qml = {
    renderer = "auto",
    probe_timeout = 5000,
},

monitors

The monitors.

Empty means “work it out”: every connected screen is driven, left to right in the order the kernel enumerated the connectors, top edges aligned. That is right about half the time, and wrong in a way you can see and fix in one line.

monitors = {
    { name = "DP-1", mode = "2560x1440@260", vrr = true, primary = true },
    { name = "DP-2", mode = "2560x1440@75", right_of = "DP-1", align = "end" },
    { name = "DP-3", above = "DP-1", transform = "90" },
    { name = "HDMI-A-1", enabled = false },
},

name is the connector name; solium --probe prints the ones this machine has, and a name nothing answers to gets a line in the log rather than being ignored. Everything else is optional:

right_of, left_of, above, below   beside another monitor, by name.
                                  Prefer this to x and y: it does not
                                  go stale when a resolution changes,
                                  and a chain resolves whatever order
                                  you write the list in.

align = "start" | "centre"        which way the *other* axis lines up
      | "end"                     when placed beside something taller
                                  or wider. "centre" is the default.
                                  A 1080p beside a 1440p leaves 360
                                  rows belonging to no screen, and
                                  this decides which end they are at
                                  -- which is where the pointer will
                                  catch on the way past.

x, y                              the top-left corner outright, in the
                                  one global space every monitor is a
                                  window onto. `y` is how much lower
                                  one screen sits than another, which
                                  is what a monitor on a taller desk
                                  actually needs.

mode = "2560x1440@260"            resolution and refresh rate. The
                                  refresh is optional -- "2560x1440"
                                  alone means the fastest mode at that
                                  size. A table `{ w = , h = ,
                                  refresh = }` does the same thing, for
                                  generating a configuration rather
                                  than writing one.

                                  Three words also work:
                                    "best"       the highest refresh at
                                                 the preferred
                                                 resolution. The
                                                 default.
                                    "preferred"  exactly what the
                                                 monitor's EDID says,
                                                 refresh included --
                                                 for one that is
                                                 unstable at its
                                                 fastest.
                                    "widest"     the largest
                                                 resolution, fastest at
                                                 that size.

                                  "best" is not "preferred": the
                                  EDID's preferred *flag* names a
                                  resolution and usually pairs it with
                                  a pedestrian 60 Hz. A 260 Hz panel
                                  reports 2560x1440@60 as preferred,
                                  and taking that literally drives a
                                  fast display slowly and makes every
                                  animation look worse than it is.

                                  A mode the monitor does not have
                                  warns and falls back; `--probe` says
                                  how many each one offers.

vrr = true                        variable refresh rate, where the
                                  monitor and the driver both offer it
                                  -- FreeSync, G-Sync compatible,
                                  Adaptive-Sync. The display's refresh
                                  follows what is actually being drawn
                                  instead of the other way round, which
                                  is what removes the tear and the
                                  stutter on anything that cannot hold
                                  a steady frame rate. Left alone by
                                  default, because it interacts badly
                                  with some panels at low frame rates
                                  (visible flicker) and that is not a
                                  thing to turn on for somebody.

transform = "90"                  rotation, anticlockwise, as degrees:
                                  "normal", "90", "180", "270", or the
                                  same with a "flipped-" prefix. A
                                  rotated monitor's work area is
                                  portrait, so every layout follows it
                                  without knowing about it.

enabled = false                   do not drive it. It also frees its
                                  CRTC for another screen, which
                                  matters on a card with more
                                  connectors than CRTCs.

primary = true                    the monitor a layer-shell surface
                                  that names no output goes on, and
                                  the one a hosted shell
                                  (`shell.on = "primary"`) or a
                                  `sol.surface` (`on = "primary"`) is
                                  drawn on when told to. Without this
                                  it is the first monitor -- stable,
                                  but not a choice anybody made.

scale = 2                         how many device pixels to a logical
                                  one. Everything doubles in size: a
                                  window, a titlebar, the pointer, and
                                  the compositor's own QML is
                                  rasterised at that many pixels
                                  rather than stretched.

                                  Left out, it is worked out from the
                                  panel's own size -- 2x above 192 dpi,
                                  which is the number GNOME and KDE
                                  both use, and 1x below. That puts a
                                  13" 4K laptop at 2x and a 27" 4K at
                                  1x, and the second of those is
                                  genuinely a matter of taste, which
                                  is why this is settable. `--probe`
                                  and the log both print the dpi it
                                  measured.

                                  Fractional values work; between 0.5
                                  and 8. A fraction outside that is
                                  warned about and the scale worked
                                  out instead, as far likelier a typo
                                  than a request; a whole number
                                  outside it, such as 0 or 10, is
                                  worked out instead with no warning.

super+shift+r applies a change to the placement keys, scale, primary and enabled without ending the session. mode, vrr and transform are read when a monitor is first lit, so on one already lit they wait until it is next plugged in, or a reload with enabled = false and another with it back.

A monitor plugged in while the session runs is driven with its entry here, and one unplugged leaves its windows on the monitors that remain.

A monitor can also be turned off without being taken out: it keeps its place, its work area and its windows, and only the display goes dark. Three things do it – idle below, sol.monitor_power from a binding, and any client speaking wlr-output-power-management, which is wlopm and swayidle driving it. Any key, click, scroll, touch or motion turns every screen back on, and is delivered as usual: the first key typed at a lock screen that went dark is part of the password.

sol.bind("super+F12", function() sol.monitor_power("all", "off") end)

sol.monitors() says which are off, as power = "on" or "off".

The default:

monitors = {},

idle

When nobody is at the machine.

Solium tells idle daemons how long it has been left alone (ext-idle-notify) and lets a video player, a call or a game say “not now” (idle-inhibit). This is the part it does itself, so that no daemon is needed for the screens to go dark at night.

idle.screens_off_after

Seconds without a key, a click, a touch or the pointer moving before every screen is turned off. 0 never does.

Ten minutes: GNOME blanks at five, but dims the screen first and Solium does not, so here the first sign is the screen going dark. Anything that plays holds an idle inhibitor, and while one is on a screen this waits – a film does not go dark – and starts again from when it lets go, so the next film in a playlist does not start in the dark. Nothing holds it off behind the lock screen, which goes dark like anything else.

Running swayidle instead? Set this to 0 and give it the screens:

swayidle -w timeout 300 'swaylock -f' \
            timeout 600 'wlopm --off \*' resume 'wlopm --on \*' \
            before-sleep 'swaylock -f'

The default:

screens_off_after = 600,

idle.off_frame_interval

How often, in milliseconds, a window on a screen that is off is still told it may draw. Throttled rather than stopped: a program that waits for that inside its swap would otherwise stop dead for as long as the screen is dark. 0 stops it, which is what sway does.

The default:

off_frame_interval = 1000,

idle.dbus_inhibit

Answer the other way programs ask for the screens to stay on: org.freedesktop.ScreenSaver on the session bus, which is what Chrome and Firefox call during a film instead of the Wayland idle inhibitor. Such an inhibitor holds the blank above off – and swayidle’s timeouts – like one on a window in view, goes when the program that took it closes or crashes, and holds nothing behind the lock screen. false leaves the name to whoever else wants it. Nested, it is owned only on the bus SOLIUM_SESSION_BUS names.

The default:

dbus_inhibit = true,

session

Telling the rest of the session that Solium is its desktop.

Portals, programs D-Bus starts on demand, ~/.config/autostart and user services written for “a graphical session” are all started by systemd or by D-Bus, and they find the display only if they are told where it is. Read when the session starts, so a reload does not change it. systemd and autostart count only when Solium is started as the session: the session file’s solium-session, which runs solium --tty --session. solium --tty by hand and a nested run leave the session around them alone, unless SOLIUM_SESSION_BUS names a bus to tell instead. stop_timeout counts however Solium was started. The tests are in session.rs: a_reload_leaves_the_session_as_it_began, a_manual_tty_start_tells_nobody, a_nested_run_tells_nobody_unless_it_is_given_a_bus, the_target_is_stopped_and_the_variables_unset_on_exit, session_systemd_false_tells_nobody_anything and session_autostart_false_starts_the_session_without_autostart.

session.systemd

Tell systemd’s user manager and D-Bus activation WAYLAND_DISPLAY, DISPLAY, XDG_CURRENT_DESKTOP and XDG_SESSION_TYPE, and start solium-session.target, which starts graphical-session.target and every unit you have attached to it. On exit the target is stopped and the variables unset. false does none of it.

The default:

systemd = true,

session.autostart

Whether solium-autostart.target starts beside it: XDG autostart, the programs in ~/.config/autostart and /etc/xdg/autostart, which is how a polkit agent, a keyring or nm-applet usually start. false leaves autostart out, and solium-session.target, with whatever is attached to it, still starts.

The default:

autostart = true,

session.stop_timeout

How long, in milliseconds, SIGTERM, SIGINT or SIGHUP waits for Solium to stop cleanly, however it was started. The first of them stops it the way a quit binding does. If it is still running this long afterwards, something inside it has stopped answering, and it ends at once. The same signal again, half a second or more after the first, ends it at once too. Tests in signals.rs: a_process_that_cannot_stop_ends_when_its_stop_timeout_has_passed, the_same_signal_twice_ends_a_process_that_cannot_stop and the_same_signal_twice_at_once_is_one_request.

The default:

stop_timeout = 5000,

pane

How every window is framed.

A style is a folder under qml/panes holding a Pane.qml: what the frame reserves from the client, and a list of layers, each its own QML scene at its own depth – behind the client, in the frame, or above it. A name is one of the folders below, or one of your own in ~/.config/solium/qml/panes, which shadows a shipped one of the same name. A path is anywhere.

• "top": a titlebar above the window (the default)
• "left": a titlebar down the left side
• "bottom": a titlebar underneath
• "border": no bar, just a frame
• "reactive": a border lit where the cursor is, with a bar
• "proximity": a border that answers the pointer arriving and leaving
• "reveal": a bar that slides out of the window’s edge on approach
• "pulse": a bar with an animation running in it
• "rounded": the window’s own corners cut round, with a bar that fills the two notches at the top
• "flush": a window with a square top and a rounded bar sitting flush on it
• "shadow": a drop shadow behind the window, from stacked rectangles rather than a blur
• "none": no frame at all: no bar, no border, and no QML scene built per window. For a desktop with no window furniture, or a tiling layout whose own bar makes a titlebar redundant.

“rounded” and “flush” cut the client’s corners as it is drawn, at no extra cost: no pass and no copy of the window. The panes README, qml/panes/README.md, has what each style is made of and costs. SOLIUM_PANE overrides this, for one run.

A single QML file still works and is still called a decoration: drop one in ~/.config/solium/qml/decorations and name it here. It is one layer in the frame, which is what every style was before folders.

This setting was called decoration when a style was one file. The old name is still read – see the bottom of this file.

The default:

pane = "top",

loading

What a window does between being asked for and its application arriving. A window’s life starts when you ask for it, not when the program gets around to connecting – these decide what that looks like.

loading.scene

Which QML draws it. A name is one of the scenes in qml/loading, or one of your own in ~/.config/solium/qml/loading, which shadows a shipped one of the same name. A path is anywhere. SOLIUM_LOADING overrides this, because that is set per run.

The default:

scene = "window",

loading.patience

How long to keep a window open for an application that never arrives, in milliseconds. After that the layout is told the window has gone, and the window fades out of its place with the same fade a window you close plays, the scene it was showing fading with it. There is no application to ask, so there is nothing to wait for and nothing to refuse. A window whose scene would not load has nothing on screen to fade, and goes at once.

An application that was already running does not arrive either: it answers the launch by bringing forward the window it has, and the window opened for the launch goes the same way the moment it does, without waiting this long. The view goes to the window it brought forward, on its own workspace (activate in docs/modes.md, and relaunching_an_application_whose_window_is_on_another_workspace_keeps_it_there_and_brings_it_into_view).

The default:

patience = 8000,

loading.reserves_a_slot

Whether it takes its place in the layout straight away. With this off, the other windows only move aside once the application is really there – less eager, and some people will prefer it.

The default:

reserves_a_slot = true,

loading.decorated

Whether the frame is drawn while it waits. The room it takes is reserved either way, so the window does not change shape when the application arrives; this only decides whether the bar is on screen meanwhile. On, and you get a close button for an application that is not coming. Off, and the scene has the whole window.

The default:

decorated = false,

loading.fade

How long the scene takes to fade off the application that replaced it, in milliseconds. It is drawn over the window, so what is underneath is already the application. 0 cuts straight to it.

The default:

fade = 180,

resize

What a window looks like while you are dragging its edge.

A client cannot be resized; it can only be asked, and it answers when it gets round to it – a few milliseconds for a terminal, rather more for a browser. The compositor no longer waits for that answer: the rectangle you are dragging is what it draws, from the first frame, and the client’s last picture fills it until the real one arrives. This decides what that filling looks like, which is entirely taste.

resize.fill

“stretch” scales the last picture into the new rectangle. Smooth, momentarily soft while a slow client catches up, and what most compositors do. The default.

“hold” leaves the picture at its own size where there is room for it, so nothing is resampled and what you see uncovered as the window grows is the pane underneath. Crisp instead of smooth. A window being made smaller is still scaled down, because a picture larger than the window it is in would spill over its neighbour.

“scene” draws the window’s QML scene over it – the same one a window wears before its application has painted. Today that only reaches a window resized before its application ever arrived; anywhere else it behaves as “hold”.

Whatever this says, a client that refuses the size it is offered – Firefox will not go under its minimum width – stops being stretched the moment it says so, and the window takes the size the client chose when you let go of the edge.

The default:

fill = "stretch",

fullscreen

A fullscreen window: what it covers, and how a window goes fullscreen and comes back (super+f, or the application asking).

fullscreen.covers

What a fullscreen window covers, when it is the one in front on the workspace its monitor is showing.

“top”, the default: the top layer, so a bar – a client’s, like Waybar, or one declared with sol.surface – goes under a fullscreen video or game, and the video takes the clicks where the bar was. The overlay layer stays over it: notifications, an OSD, a launcher. A window going fullscreen goes over the bars as it starts to grow, and one leaving goes back under them once it has finished shrinking.

“none”: nothing, and the bars stay over fullscreen windows.

Anything else is named in the log, and the default kept.

The default:

covers = "top",

fullscreen.animate

How a window grows to cover its monitor, and shrinks back to where it was: from wherever it is drawn, as a window a layout moves glides, so pressing the key again half way turns it round where it is. The application is told its new size the moment the key is pressed, and its last picture is stretched until it has drawn one at that size: through the glide and after it, for a quarter of a second past the landing at most, and then the window is shown at the size the application has. Once it has answered the window is drawn as it is, with nothing in between, so a game or a video can be shown directly.

duration is in milliseconds and easing is a curve, by name or as four numbers, as for every motion here (docs/animation.md). false makes every change instant – nothing is moved or stretched, and the window is drawn as it is on the next frame – and true is the motion below again:

fullscreen = { animate = false },

Change this default and SHIPPED in lua/fullscreen.lua with it: that is the motion animate = true turns back on.

The default:

animate = { duration = 260, easing = "outCubic" },

fullscreen.instant

Applications that go fullscreen and back at once whatever animate says, by their app id: the name app_id gives each window in sol.windows(). A game, or a video player started fullscreen, may want to be there at once:

fullscreen = { instant = { app_id = { "mpv", "gamescope" } } },

Empty as shipped, so every application animates. A list is replaced whole, so the list you write is the whole list.

The default:

instant = { app_id = {} },

maximize

How a window is maximised to fill the work area of its monitor, and restored (super+shift+m, or the button on its frame). The same two settings as fullscreen’s and read the same way, but on their own: a maximise can move differently from a fullscreen, or not at all, and changing one changes nothing about the other.

maximize.animate

How a window grows to fill the work area and shrinks back, as fullscreen.animate says for going fullscreen: a duration and an easing, false for instant, or true for the motion below.

maximize = { animate = false },

Change this default and SHIPPED in lua/fullscreen.lua with it.

The default:

animate = { duration = 220, easing = "outCubic" },

maximize.instant

Applications that are maximised and restored at once whatever animate says, by app id, as fullscreen.instant lists them.

The default:

instant = { app_id = {} },

floating

floating.client_limits

Whether a floating window’s edge drag stops at its application’s own minimum and maximum size (#115). The layouts’ say in the matter is tiling.client_minimum and tiling.client_maximum; this one is the compositor’s, because no layout is asked about a floating drag.

“respect”, the default: the frame you drag never shows a size the application is about to refuse. “ignore”: the drag goes wherever the pointer does, as before #115, and an application that refuses the size is treated as the end of resize above says. An application in tiling.client_size_ignore is not believed here either. Anything else is read as “respect”.

The default:

client_limits = "respect",

tiling

tiling.split

Where a split falls, as a share of the window being divided. Hyprland calls this dwindle:default_split_ratio.

The default:

split = 0.5,

tiling.minimum

The smallest a tile may be, frame included, in logical pixels.

A new window that would make a tile smaller than this goes where overflow says instead. And a seam cannot be dragged, or moved from the keyboard, to make a tile smaller than this. A tile that is already smaller does not jump when you grab it, and cannot be made smaller still; it can be grown only while the tiles across the seam have room to give. So a seam with a tile under this on both sides does not move at all – and that is what "allow" below usually makes, since it halves a tile too small to split.

A tile and not an application’s own minimum size: a window you launch from here is given its tile the moment you ask for it, before its application has started, so there is no application yet to ask. An application’s own minimum is client_minimum below.

0 on a side is no minimum on that side.

The default:

minimum = { w = 160, h = 96 },

tiling.client_minimum

Whether an application’s own minimum size gets a say (#115). Some applications will not go under a size – Firefox has a minimum width – and say so. You have the last word, not the application: this is where you give it.

“respect”, the default: a window is laid out at least as large as its application’s minimum wherever the arrangement has the room. It is given a larger share, taken from the windows beside it down to their own minimums and minimum above, and the share goes back when the application’s minimum does. A new window that would crowd one goes where overflow says. A seam stops where a window beside it reaches its minimum. And in the scrolling layout, a column is never narrower than the widest minimum in it.

Where the room is not there, the window is laid out smaller anyway and its application’s picture is cut to the tile. One line in the log says so, with the numbers, and the window is cramped = true in sol.windows() until it has room: docs/modes.md has a bar that shows it.

“ignore”: laid out as though no application had a minimum, which is how tiling behaved before #115. Anything else is read as “respect”.

The default:

client_minimum = "respect",

tiling.client_maximum

What a window whose tile is larger than its application’s maximum size does with the rest of the tile.

“center”, the default: it is its maximum size, in the middle of the tile. Dragging its edge still moves the seam, from the tile’s edge. “ignore”: it sits in the tile’s top-left corner at the size its application chose, as before #115. Anything else is read as “center”.

The default:

client_maximum = "center",

tiling.client_size_ignore

Applications whose sizes are not believed at all, by app_id: a Wayland application’s own, or an X11 one’s WM_CLASS class. sol.windows() lists each window’s. A window of one of these is laid out as though its application had said nothing, minimum and maximum alike, and a floating drag of it is not held to them either – for an application that claims a size it does not mean. For instance { “steam”, “org.gnome.Nautilus” }.

The default:

client_size_ignore = {},

tiling.overflow

Where a new window goes when splitting the tile under the pointer would make a tile smaller than minimum – side by side and one above the other, since a tile with no room one way may have it the other. Tried in order; the first with room wins.

• "largest": split the largest tile on this workspace that has room for it
• "workspace": open it on the next empty workspace of the monitor it opened on. The workspaces are the fixed set workspaces describes, so when none is empty this step does nothing and the next one runs. A window that belongs to no workspace in particular is on all of them, and with workspaces.follow_new_windows off that is every window – so then none is empty.
• "allow": split the tile under the pointer anyway, below minimum

A list that runs out without placing the window – one with no “allow” – ends in “allow” all the same, with a line in the log: a window has to go somewhere. Put “workspace” first and a window goes straight to the next empty workspace once the tile under the pointer is full; leave “workspace” out and no window ever changes workspace for want of room.

Only a window being opened overflows, and only while tiling is the layout in charge. A window already open that goes back into the arrangement – tiling switched on, a reload, a monitor change, a close the application refused – never leaves its workspace for this: it takes a tile with room if there is one and a tile under minimum if there is not. A refused window and a dropped one go back to the tile where they were, whatever its size.

The default:

overflow = { "largest", "workspace", "allow" },

tiling.follow_overflow

Whether the view goes with a window that opened on another workspace, the way super+<n> takes it there. The keyboard goes to the window – for one launched from a binding, once its application has put up its window; until then it is not on the new window, and can still be on the one you were working in, a screen away by then.

false opens it there and leaves you, keyboard and all, where you are. Each window with no room then goes to another empty workspace, since the one the window before went to is no longer empty – whether or not it has room – until none is left empty.

The default:

follow_overflow = true,

tiling.motion

The default:

motion = { duration = 240, easing = "outCubic" },

tiling.snap

The shorter feel for a window snapping back after a drag.

The default:

snap = { duration = 180, easing = "outCubic" },

tiling.reflow_on_close

When the other windows close up around one you close.

“immediate”, the default: the moment you close it. The window fades out where it stood, in front of its neighbours as they grow into its space. If the application refuses to go – an unsaved-changes prompt – the window comes back split off whichever window now covers where it was, which is its old neighbour when nothing else has moved, at split rather than the ratio it had.

The compositor waits a second for an application to go before it takes the silence for a refusal. One slower than that to quit – some Electron and Java applications, a browser saving its session – is put back and then goes, so its neighbours grow, shrink back and grow again. “when_gone” moves them once.

“when_gone”: once the application has actually quit. Its tile stays reserved for the length of the fade and for however long the application then takes, and a refusal has nothing to put back. This is how every close behaved before #128.

Either way, only while tiling is the layout in charge.

Anything else is read as “immediate”.

The default:

reflow_on_close = "immediate",

tiling.move

What a keyboard move (super+shift+arrows, #150) does with the window it moves towards: the tile wholly past it that way and level with it, never one off on a diagonal.

“swap”, the default: the two trade tiles, and every split keeps its axis and its ratio. Where the tile it left is the one that way from the tile it took, as in a grid, the opposite move puts both back. niri moves windows this way; sway and Hyprland reshape the tree instead, which is what a dragged seam does not survive.

“split”: the window leaves its tile and splits the neighbour’s across that tile’s longer side, as a window opening in it would, as Hyprland’s movewindow does. Pressed again, it goes on into the next one.

At the edge of a monitor either way goes onto the next monitor, in beside the tile it arrives at. Anything else is named in the log and read as “swap”. with_tiling_move_split_a_move_goes_into_the_neighbours_split, in_tiling_focus_and_move_reach_the_neighbour_in_each_direction and in_tiling_a_tile_off_on_a_diagonal_is_not_that_way.

The default:

move = "swap",

scrolling

scrolling.widths

The widths a column cycles through with super+r, as shares of the view.

Read by sol.layout.scroller since #117. Before that the strip used the constant list in crates/layout/src/scroller.rs and these two lines were a description of it – so a configuration asking for quarters got thirds, and nothing anywhere said which of the two had been believed.

An entry that is not a share of a view – zero, negative, above 1, not a number at all – is dropped with a line in the log, and a list with nothing usable left falls back to this one. Refused rather than clamped, for the reason cursor.size is: a column at 0.001 of the screen is as unusable as no column, and nobody meant to ask for one.

The default:

widths = { 1 / 3, 1 / 2, 2 / 3 },

scrolling.default_width, scrolling.motion

Which of them a new column opens at, and where the cycle starts. 1-based, the way Lua counts. Past the end of the list is the last width, with a line in the log.

The default:

default_width = 1,
motion = { duration = 260, easing = "outCubic" },

scrolling.snap

The shorter feel for bringing a column into view.

The default:

snap = { duration = 200, easing = "outCubic" },

scrolling.reflow_on_close

When the strip closes the gap a window you close leaves: the moment you close it (“immediate”, the default), or once the application has actually quit (“when_gone”, how it was before #128). A window whose application refuses to go comes back in a column of its own after the window that was before it; one that was first comes back first. Anything else is read as “immediate”. The same setting as tiling.reflow_on_close, kept apart so the two layouts can be set differently – and with the same cost for an application slower than a second to quit, which closes the gap, opens it and closes it again.

The default:

reflow_on_close = "immediate",

workspaces

workspaces.per_monitor

Whether each monitor has its own active workspace.

On, super+2 switches the screen the pointer is on and leaves the other showing whatever it was: a reference on the second monitor stays put while you move around on the first. This is what sway, Hyprland and niri do, and what most people expect.

Off, one switch moves every screen at once, so a workspace is a whole desk rather than a screenful. That is GNOME’s model, and it is the right one if you think of your two monitors as one surface you happen to have cut in half.

Only matters with more than one monitor.

The default:

per_monitor = true,

workspaces.arrangement, workspaces.columns, workspaces.rows

“horizontal”: workspaces sit in a row and slide sideways. “vertical”: a column, sliding up and down. “grid”: both, columns wide and rows tall.

The arrangement decides which way a switch travels, and that is the whole difference between the three: a workspace to the right of this one enters from the right, because that is where it is.

It also decides how many there are: columns in a row, rows in a column, columns times rows in a grid – so four, as shipped.

The default:

arrangement = "horizontal",
columns = 4,
rows = 2,

workspaces.spread, workspaces.motion

How far apart workspaces sit, as a fraction of the screen. Above 1.0 there is a gap of empty space between them mid-slide, which reads as distance rather than as a cut.

The default:

spread = 1.06,
motion = { duration = 300, easing = "outCubic" },

workspaces.follow_new_windows

Whether a new window joins the workspace you are looking at.

The default:

follow_new_windows = true,

There is no dock.

A dock section sat here offering items and morph, and nothing in the compositor or in any script had ever read either of them – lua/init.lua says as much in as many words, where the genie’s target rectangle is a hardcoded strip of screen “because there is no dock yet”. Removed by #117 rather than wired up, because there is nothing to wire it to: a setting that configures a component which does not exist cannot be told apart, from out here, from one that is broken. When a dock arrives it brings its settings back to this spot. Until then --check reports the old spelling as an unrecognised key, which is the truth.

open

open.motion

The animation a window arrives with.

These read 200 / outCubic / 0.92 until #117, and open.lua had never looked at them: it held 220 / outBack / 0.88 as local constants, so what was written here described an animation nobody had ever seen. Wiring the two together meant choosing which pair was the default, and the script’s won – those are the numbers the animation was actually tuned against and the ones every session so far has been watching. Taking the advertised pair instead would have changed how every window on every machine opens, as a side effect of correcting a comment.

The default:

motion = { duration = 220, easing = "outBack" },

open.scale

How small it starts, as a share of the size it ends up. outBack overshoots, so it grows a little past that and settles back.

The default:

scale = 0.88,

genie_spread

How much of a window trails behind it in the genie, for the Developer Tweaks panel’s version of that effect (--debug-mode only).

Declared here because tweaks.lua already reads config.genie_spread and falls back to this number. An undeclared key that works is the same fault as a declared one that does not, read from the other side: nothing tells you it is there, and the unrecognised-key report below would call a working setting a typo.

The default:

genie_spread = 1.4,

How user.lua is read

The rest of config.lua is the code that merges your file over the defaults above and reports what it could not have meant. Its comments are the explanation; the code is folded under each.

A list is a table with a [1]; anything else with keys is a section to descend into. Crude, and right for every shape in this file.

local function is_list(value)
    return type(value) == "table" and value[1] ~= nil
end

Sections whose key set is not the one written above them.

merge reports every key a user’s file sets that these defaults do not define – which is what catches tilling = { ... }. Three sections would be reported wrongly by that rule, and each needs saying out loud rather than being quietly skipped:

• keyboard, cursor: their xkb and cursor keys are left out on purpose, because leaving them out means “whatever the session already said” – see their comments. Those key sets belong to sol.keyboard and sol.cursor_theme in the compositor, so they are written out here: the defaults cannot carry them without changing what leaving them out means. keyboard.indicator is the one key the defaults do define, and is checked against them.
• bindings: open by construction. A key combination is whatever you press, so there is no list to check one against.

This table is checked against the compositor, and was wrong when it shipped. #117 wrote here that a reader growing a key and this list not being updated to match would report that key as a typo, and called that failure loud. It was not loud at all: active was missing from the day this was written, sol.keyboard has always read it, init.lua passes it straight through, and so keyboard = { layout = "us,ru", active = 2 } – the only shape of configuration that has an active worth naming – was told its working setting is read by nothing, and solium --check exited 1 over it. Which is worse than the silence #117 replaced: --check is sold as “did my configuration work”, and one wrong answer there teaches people to stop reading it.

A hand-restated list drifts, so a comment asking the next person to remember is not the fix. every_key_a_section_accepts_is_one_the_compositor_reads in script.rs hands each of these functions a table that records what is looked up in it and compares the two sets, in both directions: a key only the compositor reads is a working setting called a typo, and a key only this list has is #117’s own fault from the other side.

local open_sections = {
    keyboard = {
        rules = true,
        model = true,
        layout = true,
        variant = true,
        options = true,
        repeat_rate = true,
        repeat_delay = true,
        -- Which of several layouts is live. `sol.keyboard{ active = 2 }` is
        -- also how the cycle binding in `init.lua` switches it.
        active = true,
        -- Caps Lock and Num Lock, on or off. `sol.keyboard{ caps = false }`
        -- from a binding turns Caps Lock off.
        caps = true,
        num = true,
    },
    cursor = { theme = true, size = true, scene = true },
    -- `true` rather than a set of names: everything is accepted.
    bindings = true,
}

The one key a user may write that these defaults deliberately do not define. See the read-across at the bottom of this file.

Accepted, and deliberately never suggested: nearest is not shown this table. It used to be, and so decoraton was answered with “did you mean decoration”, which sends somebody to correct a typo into a spelling that is deprecated – past the key that actually configures this, which is pane. An alias exists so a file written before the rename keeps working, not so a new file can be steered into using it.

local legacy = { decoration = true }

Keys the user’s file set that nothing here defines, as dotted paths.

local unrecognised = {}

How many single-character edits turn one word into the other.

Plain Levenshtein, two rows. Cheap enough not to think about: it runs only on a key that is already known to be wrong, against a handful of candidates of a dozen characters each, once per configuration load.

local function distance(from, to)
    local previous = {}
    for column = 0, #to do
        previous[column] = column
    end
    for row = 1, #from do
        local current = { [0] = row }
        for column = 1, #to do
            local substitution = previous[column - 1]
            if from:sub(row, row) ~= to:sub(column, column) then
                substitution = substitution + 1
            end
            current[column] = math.min(previous[column] + 1, current[column - 1] + 1, substitution)
        end
        previous = current
    end
    return previous[#to]
end

The nearest key that does exist, when one is near enough to be worth naming.

Two edits, which is tilling to tiling and scal to scale but not dock to pane. A suggestion that is wrong is worse than none: it sends somebody to rewrite a line that was not the problem.

local function nearest(key, base, accepted)
    local best, best_distance = nil, 3
    local function consider(candidate)
        if type(candidate) ~= "string" then
            return
        end
        local apart = distance(key:lower(), candidate:lower())
        if apart < best_distance then
            best, best_distance = candidate, apart
        end
    end
    for candidate in pairs(base) do
        consider(candidate)
    end
    if type(accepted) == "table" then
        for candidate in pairs(accepted) do
            consider(candidate)
        end
    end
    return best
end

Merge over onto base, and say what could not have been meant.

path is where we are, for the report; accepted is the extra key set in force here, from open_sections – true for a section that accepts anything, a table of names for one whose names live elsewhere, nil for the ordinary case where base itself is the list of what exists.

legacy is read straight out of the upvalue rather than handed in as an accepted set, because the two are accepted for opposite reasons: an open_sections name is the current spelling and is worth suggesting, and a legacy name is the old one and is not.

Checking on the way in, before the assignment, because after it the key exists in base and the evidence is gone.

local function merge(base, over, path, accepted)
    for key, value in pairs(over) do
        local where = path and (path .. "." .. tostring(key)) or tostring(key)
        -- `legacy` is consulted here and not passed to `nearest`: an old
        -- spelling still works, and is still not what to suggest. Only at the
        -- top level, which is where the alias is.
        local known = accepted == true
            or base[key] ~= nil
            or (accepted and accepted[key])
            or (path == nil and legacy[key])
        if not known then
            local meant = nearest(tostring(key), base, accepted)
            -- Qualified the same way the key is, so the suggestion is something
            -- you can paste: inside `tiling` the fix is `tiling.split`, not
            -- `split`.
            if meant and path then
                meant = path .. "." .. meant
            end
            unrecognised[#unrecognised + 1] = { key = where, meant = meant }
        end
        if type(value) == "table" and type(base[key]) == "table"
            and not is_list(value) and not is_list(base[key]) then
            merge(base[key], value, where, open_sections[where])
        else
            base[key] = value
        end
    end
    return base
end

require searches the user’s directory first, so this finds ~/.config/solium/user.lua when there is one and nothing when there is not.

Having no user file and having a broken one both make require fail, and they must not be treated alike: a typo that silently changes nothing is the worst way to lose an afternoon. Only “no such module” is quiet; anything else is raised, so solium --check reports it and a reload keeps whatever was already running.

local found, user = pcall(require, "user")
if found then
    if type(user) == "table" then
        merge(defaults, user)
    else
        error("user.lua must return a table, got " .. type(user), 0)
    end
elseif not tostring(user):match("module 'user' not found") then
    error(tostring(user), 0)
end

Say what was merged and will never be read.

merge used to validate nothing at all, so a user.lua saying tilling gained a section by that name, read by nothing, for ever – and solium --check, the one command whose job is answering “did my configuration work”, said it loaded fine. It had loaded fine. It was not doing what the file said, and there was no way to tell those two apart from the outside (#117).

Reported rather than refused. A key nothing reads has no effect by definition, so raising here would trade a setting that does nothing for a session that does not start – and on a reload, for a session that keeps the old configuration while you correct a spelling. sol.unknown puts each one in the log for a running session and in front of solium --check, which exits non-zero when there is one.

What this cannot see, stated rather than implied:

• Lists are replaced whole and never descended into, so the keys inside a monitors entry are not checked here. mode misspelled as moed is merged as written and the monitor keeps its default mode.
• keyboard, cursor and bindings are the sections above; the first two are checked against a list this file restates, the third against nothing.
• A value of the wrong type is not this check’s business. gap = "12" is a recognised key and passes.

for _, entry in ipairs(unrecognised) do
    sol.unknown(entry.key, entry.meant)
end

pane was called decoration when a style was a single QML file rather than a folder. Merging a user.lua that sets the old key leaves pane at its default, so without this the setting would silently stop working – which is the worst way to lose an afternoon, and the thing the alias exists to prevent. Read across only when the new name was not also given: someone who wrote both meant the one they had to look up.

if found and type(user) == "table" and user.decoration ~= nil and user.pane == nil then
    defaults.pane = user.decoration
end

And the old key does not survive into the table the compositor reads. merge above copied it in, so without this the configuration carries both pane and a decoration that is no longer a setting – inert today, and exactly what a later pass validating pairs(config) would flag against a key the compositor itself wrote. Unconditional: the read-across above takes its value from user, never from here.

defaults.decoration = nil

return defaults

Every setting

One row for each top-level setting in config.lua, and each links to where the configuration reference explains it. A setting is written in ~/.config/solium/user.lua, which holds only what you change:

return {
    gap = 4,
    tiling = { split = 0.618 },
}

Key bindings

The 81 bindings the shipped configuration makes, as solium --check lists them, with where each is made and what it calls. None of them belongs to the compositor: each is a sol.bind call in a script, so any of them can be changed or removed from the bindings section of user.lua (how), and solium --check then lists what your configuration replaced or removed.

Two chords are the compositor’s own and are not listed: ctrl+alt+backspace ends the session whatever the configuration says, except while the screen is locked, and ctrl+alt+F1 to ctrl+alt+F12 switch virtual terminal.

Nor is a key a mode binds only while it is up, because solium --check lists what the configuration binds as it loads: escape leaves the overview, and is bound only while the overview is open, so that the rest of the time it reaches the application with the keyboard.

init.lua

Solium’s default configuration.

direction.lua

Focus and move by direction (#150).

modes.lua

Which layout is in charge.

overview.lua

Overview: every window scaled onto a grid.

scrolling.lua

Scrolling: columns and a moving view, as niri does it.

tiling.lua

Tiling: dwindle, as Hyprland does it.

workspaces.lua

Workspaces, as a presentation.

The Lua API

Everything the compositor puts in the sol table, transcribed from sol.lua, the definitions file lua-language-server reads for completion (how to set it up). A test fails when the compositor and that file disagree about any of its 98 names.

Most calls queue a command and return nothing. The commands a handler queues are applied together when it returns, in the order it queued them, and every animated one uses the timing sol.animate last set in that handler. Desktop modes is the guide to using them.

Events

What sol.on can listen for.

sol

sol.keep(name, defaults)

State that survives super+shift+r.

Answers the table the last configuration kept under name, or defaults on the first load. Mutate it in place and the next reload gets what you left in it. It may hold numbers, strings, booleans, tables of those, and the trees and strips sol.layout makes, eight tables deep; anything else is named in the log and left out. Asked for twice under one name, it is the same table both times.

Parameters:

• name: string
• defaults: table

Returns table.

sol.lua:319

sol.windows()

Every window a layout may arrange, topmost first.

A snapshot taken for this handler, not a live view. A window that closes while you hold its id is ordinary: place and present on an id that no longer exists do nothing.

Returns sol.Window[].

sol.lua:327

sol.apps()

Every installed, visible application (NoDisplay and Hidden entries are left out at the source), by name.

A snapshot taken for this handler, not a live view, and – unlike sol.windows() and sol.monitors() – empty at the top level of a configuration file: it reads before the first real one arrives, and before the index has even scanned once on a first start. A scene reads Solium.Apps instead, which is live from the moment it is drawn.

Returns sol.App[].

sol.lua:338

sol.surface(name, options)

Draw a QML scene: a wallpaper, a bar, a dock, a heads-up display.

Declaring a name again with the same scene changes the live scene: changed properties are written into it, and on a monitor it was already on a new on, layer or interactive keeps it, so what the scene holds survives (an open popup, a running animation). A monitor it newly covers gets a scene built from the current properties, and one it leaves drops its scene. Only another scene file builds it again. A key left out of properties keeps the value the scene last had. A dotted key (["panel.open"] = true) reaches a grouped property. false or nil takes the surface away. Each monitor it is on gets a scene of its own, built when the surface is declared or the monitor arrives and dropped when the monitor goes; Solium.monitor inside it is that monitor. A scene file that is not there is logged, and built once it is there, at the next reload, change of monitors or changed declaration; a scene that will not load is logged once per monitor and not tried again until another scene is declared or the configuration is reloaded.

Parameters:

• name: string
• options: sol.SurfaceOptions|false|nil

sol.lua:359

sol.keyboard(options)

Read the keyboard, or change it.

With no argument, answers the layouts, which one is live, its short name, whether Caps Lock and Num Lock are on, and how keys repeat. With a table, changes what it names and leaves the rest alone, so a binding that switches layout does not reset the repeat rate. sol.on("keyboard", ...) hears the layout and the locks change.

Also called as:

• sol.keyboard() returns sol.KeyboardState

Parameters:

• options: sol.KeyboardOptions (optional)

Returns sol.KeyboardState|nil.

sol.lua:371

sol.text_input()

The focused text field and where its caret is, or nil when the window with the keyboard has no text field enabled.

Kept by the text-input-v3 protocol: an application with a text field focused says so, and says where its caret is. Applications that do not speak it, and X11 ones, never have one. sol.on("text_input", ...) hears a field being enabled or focused, its caret moving, and its window being framed or left bare.

Returns sol.TextField|nil.

sol.lua:382

sol.monitors(rows)

Read the monitors, or arrange them.

With no argument, answers every monitor. With a list, drives and places the monitors it names; a row with no name is logged and skipped.

Also called as:

• sol.monitors() returns sol.Monitor[]

Parameters:

• rows: sol.MonitorPlacement[] (optional)

Returns sol.Monitor[]|nil.

sol.lua:391

sol.workspaces(declared)

Say what the workspaces are. The compositor does not know what a workspace is: workspaces.lua is the whole feature, and this is how a hosted shell’s Workspaces model learns it. Declare again whenever it changes; the same declaration twice costs nothing. Monitors and windows the compositor does not have are left out, with any group left with no monitor, and so is a workspace whose <group>/<id> an earlier one in a group that stays already has; each is logged once.

Parameters:

• declared: sol.WorkspaceDeclaration

sol.lua:423

sol.monitor_power(which, mode)

Turn a monitor’s display off or on, or every monitor’s with "all".

The monitor keeps its place, its work area and its windows. Any key, click, scroll, touch or pointer motion turns every screen back on. A mode that is neither "on" nor "off" is an error; a name no monitor has is a line in the log.

Parameters:

• which: string — A monitor’s name, or "all".
• mode: "on"|"off"

sol.lua:434

sol.idle(options)

Set the idle blank: config.idle, which the shipped init.lua hands over.

Parameters:

• options: sol.IdleOptions (optional)

sol.lua:439

sol.monitor(id)

The work area of the monitor a window is on, or of the active monitor when no window is named or the id is unknown.

Parameters:

• id: integer (optional)

Returns sol.Rect.

sol.lua:445

sol.cursor()

Where the pointer is.

Returns sol.Point.

sol.lua:449

sol.window_at(x, y, skip)

The window drawn at a point, asked the way the compositor asks it: against where windows are drawn, on the monitors that draw them.

skip leaves one window out, which is what makes it useful while dragging: the dragged window is always the one under the pointer.

Parameters:

• x: number
• y: number
• skip: integer (optional)

Returns integer|nil (id).

sol.lua:460

sol.present(id, options)

Draw a window somewhere other than where it lives, animated.

A transform: the window keeps its place and its client is told nothing, so sol.present_clear puts it back exactly. Input follows the rect it is drawn at.

A present that lands exactly on the window’s own frame (no rect, no rotation, full opacity) lets the window go, as sol.present_clear does, rather than holding it there.

Parameters:

• id: integer
• options: sol.PresentOptions (optional)

sol.lua:474

sol.present_from(id, options)

Draw a window at a rect and animate it to where it lives: every “appears from somewhere” animation. The rect is required.

Parameters:

• id: integer
• options: { x: number, y: number, w: number, h: number, opacity?: number }

sol.lua:481

sol.debug_mode()

Whether the compositor was started with --debug-mode or with SOLIUM_DEBUG_MODE set. The Developer Tweaks panel asks this.

Returns boolean.

sol.lua:486

sol.reload()

Read the configuration again, without ending the session.

A configuration that fails to load leaves the running one in place. See sol.keep and the restore event for what a reload carries.

sol.lua:493

sol.pane(name)

Choose how every window is framed, at once.

A name is a folder under ~/.config/solium/qml/panes or the shipped qml/panes, or a single file under ~/.config/solium/qml/decorations; a path is anyone’s; "none" draws no frame. SOLIUM_PANE, when set, wins over the name given here.

Parameters:

• name: string (optional)

sol.lua:503

sol.pane_values(values)

Hand values of the configuration’s own to every layer of every pane.

Every layer’s root reads them as one object, values, which PaneStyle declares for an inline layer and a delegated layer declares itself (property var values: ({})): so a setting the configuration reads can reach the QML that draws by it, and the compositor never knows what the setting is. Each call merges its keys into what is there, so two scripts each handing their own keep both; a key, once given, keeps its last value until the configuration is reloaded, which starts with none. Values are what sol.surface’s properties take. A window opened later is told them too.

Parameters:

• values: table

sol.lua:522

sol.decorations()

Every frame style sol.pane could be given, found in the folders the compositor looks in: sorted, bundles first, each name once.

Returns sol.DecorationEntry[].

sol.lua:527

sol.loading(options)

Set what a window does between being asked for and its application arriving.

Parameters:

• options: sol.LoadingOptions

sol.lua:532

sol.client_sizes(options)

Set whose own size limits a floating window’s edge drag is held to.

floating = "ignore" lets the drag go wherever the pointer does; anything else believes every application. ignore lists applications, by app_id, whose limits are never believed.

Parameters:

• options: { floating?: "respect"|"ignore", ignore?: string[] } (optional)

sol.lua:541

sol.resize(options)

Set what fills a window while a resize drag is ahead of its client.

"stretch" (the default) scales the last picture; "hold" leaves it at its own size; "scene" draws the window’s QML scene, which today reaches only a window resized before its application painted. Another name is logged and the default kept.

Parameters:

• options: { fill?: "stretch"|"hold"|"scene" } (optional)

sol.lua:551

sol.fullscreen(options)

Set what a fullscreen window covers.

"top" (the default) covers the top layer, so bars go under it; "none" leaves bars over it. Another name is logged and the default kept.

Parameters:

• options: { covers?: "top"|"none" } (optional)

sol.lua:559

sol.cursor_theme(options)

Set the pointer’s XCursor theme, size and scene. Applied at once, so a reload is how a theme or a scene is tried, and a scene whose files changed is built again. Not sol.cursor, which says where the pointer is.

Parameters:

• options: sol.CursorOptions (optional)

sol.lua:566

sol.qml(options)

Choose how QML renders, and how long the GPU trial may take.

Read once, when the compositor starts, before any scene does; a reload does not change it. --qml, SOLIUM_QML and SOLIUM_QML_GPU override it.

Parameters:

• options: sol.QmlOptions (optional)

sol.lua:574

sol.session(options)

Say how this session is announced, and how long a signal to end waits.

Read once, when the compositor starts; a reload does not change it. Who is told: the session bus, when Solium is started as the session with solium --tty --session; nobody, for a --tty start by hand or a nested run, unless SOLIUM_SESSION_BUS names a bus to tell instead. The shipped init.lua calls it with config.session.

Parameters:

• options: sol.SessionOptions (optional)

sol.lua:585

sol.present_clear(id)

Stop presenting a window: animate it back to where it lives.

Parameters:

• id: integer

sol.lua:590

sol.group(name, selection)

Name a selection of windows, surfaces and monitors, so one transform can carry them together.

Declaring the name again replaces the membership and keeps the transform, so a mode that rebuilds its groups on every pass does not restart its own animation. false or nil takes the name away.

Parameters:

• name: string
• selection: sol.Selection|false|nil

sol.lua:601

sol.present_group(name, shift, motion)

Move, fade or turn a selection as one.

Composes with each member’s own sol.present, so a window tilted inside a moving desk stays tilted within it. motion sets this call’s own timing; left out, it is whatever sol.animate set.

Parameters:

• name: string
• shift: sol.Shift (optional)
• motion: sol.Motion (optional)

sol.lua:612

sol.present_group_clear(name, motion)

Animate a selection back to where its members live.

Parameters:

• name: string
• motion: sol.Motion (optional)

sol.lua:618

sol.animate(options)

Set the timing for every animated command queued after this one in the same handler. Left unset, it is 220 ms and "outCubic". In a "fullscreen" or "maximize" listener it is also how the window’s own move is timed; there, left unset, the move is instant.

Parameters:

• options: sol.Motion

sol.lua:626

sol.focus(id)

Give a window the keyboard.

Parameters:

• id: integer

sol.lua:631

sol.toggle_fullscreen(id)

Make a window fullscreen, or give it back its place if it already is. With no id, the focused window; with nothing focused, nothing happens.

Parameters:

• id: integer (optional)

sol.lua:637

sol.toggle_maximize(id)

Maximise a window to its monitor’s work area, or give it back its place if it already is. With no id, the focused window; with nothing focused, nothing happens.

Parameters:

• id: integer (optional)

sol.lua:644

sol.focus_direction(dir)

Move the keyboard to the window beside the focused one. Every direction listener is told ("focus", dir), and the layout in charge answers (lua/direction.lua). Anything but the four directions is an error. The listeners’ time counts against the handler that called this, so one stopped at the deadline stops that handler too.

Parameters:

• dir: "left"|"right"|"up"|"down"

sol.lua:653

sol.move_direction(dir)

Move the focused window in a direction: direction listeners are told ("move", dir). Tiling trades it with its neighbour, scrolling moves it within or between columns, and a fullscreen or maximised window moved to another monitor stays so there. Anything but the four directions is an error. The listeners’ time counts against the handler that called this, so one stopped at the deadline stops that handler too.

Parameters:

• dir: "left"|"right"|"up"|"down"

sol.lua:663

sol.place(id, options)

Put a window where it lives: the layout’s call.

The client is told the size and asked to redraw. The rect is a tile unless tile = false: a client that will not shrink to it is cut to it rather than drawn over its neighbours. A rect is required.

Parameters:

• id: integer
• options: sol.PlaceOptions

sol.lua:673

sol.unplace(id)

Let a window go from its tile, when a layout stops arranging it. modes.use sends this for every window when the layout in charge changes.

Parameters:

• id: integer

sol.lua:679

sol.close(id)

Ask a window to close. A request, not a kill: its application may refuse.

Parameters:

• id: integer

sol.lua:684

sol.act(action, data, done)

Perform an action of the vocabulary: the same names a scene sends with Solium.send, windows.focus, windows.close, windows.fullscreen and windows.maximize, each with { id = <window id> }; the last two toggle. data is handed over as a surface’s properties are, so a table nested deeper than 64 or holding more than 65 536 values, or one that contains itself, is an error in the handler. Queued like every other request, and answered by done(ok, reason) once the compositor has acted, in a handler of its own; reason is "unknown-action", "unknown-window", "bad-data", for a windows.focus behind the lock "locked", or, for a windows.fullscreen or windows.maximize of an X11 window, which the compositor cannot send there, "unsupported". A window still loading is "unknown-window" to all but windows.close. A done that calls sol.act again is told again in the same dispatch, 16 rounds at most, and the rest at the next one. Answers the attempt’s id, one no earlier sol.act answered. A workspaces.* action is not the compositor’s: the file that keeps the workspaces answers it, with actions.override in lua/actions.lua. An override is a surface listener of its own, under the same deadline, so one stopped three times is taken out alone, and its action goes to sol.act again.

Also called as:

• sol.act(action: "windows.focus"|"windows.close"|"windows.fullscreen"|"windows.maximize", data: { id: integer }, done?: fun(ok: boolean, reason?: string)) returns integer

Parameters:

• action: string
• data: any (optional)
• done: fun(ok: boolean, reason?: string) (optional)

Returns integer (attempt).

sol.lua:712

sol.spawn(program, ...)

Start a program, with its arguments as separate strings: sol.spawn("foot", "-e", "htop").

The program gets the environment Solium was started with, not what Qt and the libraries it loads have written into Solium’s own since. On top of that: WAYLAND_DISPLAY naming this compositor; DISPLAY naming its own Xwayland, or removed when there is none; XDG_CURRENT_DESKTOP, which is Lilium unless the session named one; XDG_SESSION_TYPE=wayland when it is unset; and XDG_ACTIVATION_TOKEN and DESKTOP_STARTUP_ID, naming the window opened for it. It holds no file descriptor beyond stdin, stdout and stderr. stdin and stdout are /dev/null, and stderr is Solium’s.

Parameters:

• program: string
• ...: string

sol.lua:728

sol.which(program)

Whether a program can be found on PATH. A name with a / in it is checked as a path. Nothing is run.

Parameters:

• program: string

Returns boolean.

sol.lua:734

sol.quit()

End the session. Ctrl+Alt+Backspace does the same and cannot be rebound.

sol.lua:738

sol.grab_input(grabbed)

Take input away from clients, or give it back.

While a script holds it, keys it has not bound are swallowed, pointer presses go to click listeners, and focus stops following the pointer. Release it when you leave, or nothing reaches a window again.

Parameters:

• grabbed: boolean

sol.lua:747

sol.status(text)

Say which mode is in charge. The compositor keeps the text and logs a change at debug level, and a hosted shell reads it as Solium.status; nothing the compositor draws itself shows it.

Parameters:

• text: string

sol.lua:754

sol.bind(combo, handler, note)

Bind a key combination to a function.

The combination is normalised, so super+shift+q and Shift+Super+Q are one binding. A later call for the same combination replaces the earlier one. While the session is unlocked, a bound combination never reaches the application with the keyboard. A key a mode needs only while it is up is bound when the mode starts and taken away with sol.unbind when it stops, as overview.lua does with escape. note is a short phrase saying where the binding came from, which solium --check prints beside it.

Parameters:

• combo: string
• handler: fun()
• note: string (optional)

sol.lua:770

sol.bound(combo)

Whether a combination is bound, in whatever spelling it is given.

Parameters:

• combo: string

Returns boolean.

sol.lua:775

sol.unbind(combo, note)

Take a binding away. The combination then reaches the application with the keyboard again. With a note, solium --check lists the combination as removed by the configuration.

Parameters:

• combo: string
• note: string (optional)

sol.lua:783

sol.unknown(key, meant)

Report a setting nothing reads. config.lua calls this for each key of a user.lua its defaults do not define; solium --check lists them and exits with 1. meant is a near-miss suggestion.

Parameters:

• key: string
• meant: string (optional)

sol.lua:791

sol.on(event, handler)

Listen for an event. Listeners are added, never replaced, and one that fails is logged while the others still run.

A listener runs under a 100 ms deadline: one that takes longer is stopped with an error and logged with the file and line it was written at and the file and line it was stopped at (for an actions.override, the listener actions.lua writes for it, and the override’s own line), the other listeners still run, and one stopped three times is taken out until the configuration is reloaded. The stops are counted by function, so a function listening for two events counts the stops of both, and from its third on is taken out of each event it is stopped in. Bindings, and each done of sol.act, run under the same deadline, and a stopped binding is logged the same way. A done is struck by function too, and one stopped three times is not called again until the configuration is reloaded; a done written inline is a new function at each sol.act, so it is stopped each time rather than taken out. What a done asked for in the run that was stopped is dropped. The compositor starts each one’s clock itself, so nothing a handler calls puts it off. pcall, xpcall and load hand the stop on rather than catch it, and xpcall’s message handler is not called for it. A __gc finalizer, and the __close of a to-be-closed variable in the function a stop interrupts, run where no hook does, so the deadline cannot stop a loop in either.

Also called as:

• sol.on(event: "open"|"focus"|"closing"|"refused"|"close", handler: fun(id: integer))
• sol.on(event: "activate", handler: fun(id: integer, why: "launch"|"request"))
• sol.on(event: "drop", handler: fun(id: integer, x: number, y: number))
• sol.on(event: "resize", handler: fun(id: integer, edge_x: number, edge_y: number, horizontal_side: "left"|"right"|nil, vertical_side: "top"|"bottom"|nil))
• sol.on(event: "scroll", handler: fun(dx: number, dy: number))
• sol.on(event: "click", handler: fun(x: number, y: number))
• sol.on(event: "surface", handler: fun(surface: string, action: string, data: any))
• sol.on(event: "direction", handler: fun(verb: "focus"|"move", dir: "left"|"right"|"up"|"down"))
• sol.on(event: "layout"|"monitors"|"restore", handler: fun())
• sol.on(event: "text_input", handler: fun(field: sol.TextField, why: "field"|"caret"|"framed"))
• sol.on(event: "keyboard", handler: fun(state: sol.KeyboardState, changed: "layout"|"caps"|"num"))

Parameters:

• event: sol.Event
• handler: function

sol.lua:830

sol.log(message)

Write a line to the compositor’s log, at info level.

Parameters:

• message: string

sol.lua:835

sol.decoration

The old name for sol.pane, from when a style was a single QML file. The same function.

sol.layout

The standard arrangements, from crates/layout. The pure ones take a count or a list and a sol.LayoutOptions and answer rects; tree and scroller make an arrangement the script holds.

sol.layout.master_stack(count, options)

One large window and the rest stacked beside it.

Parameters:

• count: integer
• options: sol.LayoutOptions

Returns sol.Rect[].

sol.lua:885

sol.layout.tree()

A dwindle tree, held by the script that made it. Stateful because where a window lands depends on which window was split and where the pointer was.

Returns sol.Tree.

sol.lua:890

sol.layout.scroller(options)

A scrolling strip of columns, held by the script that made it.

Reads widths and default_width from the table given, which is meant to be config.scrolling; with none it uses the built-in widths.

Parameters:

• options: { widths?: number[], default_width?: integer } (optional)

Returns sol.Scroller.

sol.lua:898

sol.layout.strip(columns, options)

A row of columns, each holding a stack, with options.offset as how far the view has scrolled.

Parameters:

• columns: sol.Column[]
• options: sol.LayoutOptions

Returns sol.Rect[].

sol.lua:905

sol.layout.strip_scroll_to(index, columns, options)

The view offset that brings column index (counting from 1) fully into view, moving as little as possible.

Parameters:

• index: integer
• columns: sol.Column[]
• options: sol.LayoutOptions

Returns number (offset).

sol.lua:913

sol.layout.scrolling(count, options)

A row of count windows at options.column of the width each, with options.offset as how far the view has scrolled.

Parameters:

• count: integer
• options: sol.LayoutOptions

Returns sol.Rect[].

sol.lua:920

sol.layout.scroll_to(index, count, options)

The view offset that brings window index (counting from 1) of count fully into view in sol.layout.scrolling.

Parameters:

• index: integer
• count: integer
• options: sol.LayoutOptions

Returns number (offset).

sol.lua:928

sol.layout.grid(sizes, options)

A grid of thumbnails, as close to square as the count allows. Each size keeps its aspect ratio inside its cell; overview uses this.

Parameters:

• sizes: sol.Rect[]
• options: sol.LayoutOptions

Returns sol.Rect[].

sol.lua:935

A dwindle tree

A dwindle tree from sol.layout.tree(). Every call that takes options reads options.floors first, and lays the tree out in options as the work area.

Tree:insert(id, target, x, y, options)

Add a window by splitting target, or the tile under x, y when there is no target. Splits however small that leaves the halves.

Parameters:

• id: integer
• target: integer (optional)
• x: number (optional)
• y: number (optional)
• options: sol.LayoutOptions

sol.lua:953

Tree:insert_fitting(id, target, x, y, options)

insert, refusing a split that would leave a tile under options.minimum or a window under its floor: the same side first, then the other axis. Answers false and leaves the tree alone when neither fits.

Parameters:

• id: integer
• target: integer (optional)
• x: number (optional)
• y: number (optional)
• options: sol.LayoutOptions

Returns boolean (inserted).

sol.lua:964

Tree:insert_largest(id, options)

Split the largest tile that has room for another window at options.minimum, or answer false and leave the tree alone.

Parameters:

• id: integer
• options: sol.LayoutOptions

Returns boolean (inserted).

sol.lua:971

Tree:remove(id)

Take a window out of the tree.

Parameters:

• id: integer

sol.lua:976

Tree:resize(id, axis, by, options)

Move a seam from the keyboard: by is a signed share that grows the window when positive. The seam on the right or below is preferred, and the other one used only when there is none. Without options there is no minimum.

Parameters:

• id: integer
• axis: "width"|"height"
• by: number
• options: sol.LayoutOptions (optional)

sol.lua:986

Tree:drag_seam(id, edge, edge_x, edge_y, options)

Move a seam from a drag: put the named side of the window at edge_x (for "left" and "right") or edge_y (for "top" and "bottom"). Hand it what the resize event gave you. Clamped to 0.05..0.95 and to options.minimum.

Parameters:

• id: integer
• edge: "left"|"right"|"top"|"bottom"
• edge_x: number
• edge_y: number
• options: sol.LayoutOptions

sol.lua:998

Tree:contains(id)

Whether a window is in the tree.

Parameters:

• id: integer

Returns boolean.

sol.lua:1003

Tree:windows()

Every window in the tree, in tree order.

Returns integer[].

sol.lua:1007

Tree:swap(a, b)

Trade the tiles of windows a and b and change nothing else: every split keeps its axis and its ratio, so a second swap puts it back.

Parameters:

• a: integer
• b: integer