Desktop icons and widgets

Desktop Icons

The [desktop] section puts a grid of pinned icons on the wallpaper: applications, files and folders. Double-clicking an item opens it — an application launches, a file opens in its default handler, and a folder opens your file manager. Clicking selects, dragging rearranges, and dropping one icon onto another swaps their places. The grid lines are only drawn while you are dragging.

Right-clicking an icon offers Open, Open with… (files and folders), Rename and Remove from desktop. Right-clicking bare desktop offers Add application…, Add file or folder…, Organize (compact the icons) and Change background… (jump to the wallpaper settings).

Add application… opens a searchable list of everything installed, each with its own icon — type to filter, arrow keys and Enter to pick, Escape to dismiss. It searches names, generic names and the keywords a desktop entry declares, so “internet” finds your browser. Add file or folder… opens the file picker, where folders are selectable as well as browsable.

Everything here is also editable under Settings → Shell → Desktop, which is where the pinned list is easiest to manage.

[desktop]
enabled = true
cell_width = 96
cell_height = 96
spacing = 12
padding = 24
icon_size = 48
show_labels = true

[[desktop.items]]
kind = "app"
target = "/usr/share/applications/firefox.desktop"
column = 0
row = 0

[[desktop.items]]
kind = "folder"
target = "/home/user/Documents"
label = "Docs"
column = 1
row = 0

Desktop Settings

Key	Type	Default	Description
enabled	boolean	false	Whether the icon grid is drawn at all
cell_width	number	96	Width of one grid cell, in logical pixels (minimum 32)
cell_height	number	96	Height of one grid cell (minimum 32)
spacing	number	12	Gap between cells
padding	number	24	Inset from the usable edges of the screen
icon_size	number	48	Rendered icon size within a cell (minimum 8)
show_labels	boolean	true	Whether each icon’s name is drawn under it

The number of columns and rows is not configurable — it is derived from each monitor’s usable area, so the same icon list fits displays of different sizes. The usable area excludes whatever your panels reserve, so an icon is never hidden behind a bar.

Turning enabled on or off takes effect after a restart when no wallpaper is configured, because it decides whether the background surface is created at all. With a [background] wallpaper already set, the surface exists either way and the change applies live. Every other key here applies live.

Desktop Items

Each [[desktop.items]] block pins one thing. The settings UI and the desktop’s own “Add…” menu write these for you.

Key	Type	Default	Description
target	string		Absolute path. Required — an entry without one is ignored
kind	string	inferred	"app", "file" or "folder"
label	string	derived	Renames the icon. Omit to use the app’s own name or the basename
column	number	0	Grid column, counting from 0 at the left
row	number	0	Grid row, counting from 0 at the top

target is a path in every case, including applications — an app is pinned by the path to its .desktop file (usually under /usr/share/applications), not by a desktop id, so an entry in your own home directory works too.

kind is re-derived from the target whenever it disagrees with what is actually on disk, so a hand-edited file cannot end up opening a directory as though it were a document. Clearing a label in the rename field restores the original name.

An item whose target no longer exists is drawn dimmed rather than removed, so an unplugged drive or an offline network mount does not cost you your arrangement.

Items on a cell that does not exist on a smaller monitor are drawn in the nearest free cell on that monitor only; the position you gave them is kept, so plugging the larger display back in restores the layout.

Desktop Widgets

Alongside the icons, the grid holds widgets — cards that take a rectangle of cells rather than a single one, and that you resize by dragging a corner. Right-click bare desktop and choose Add widget… to place one; right-click a widget for Remove. Widgets are dragged from anywhere on the card, and their own buttons still work: a press that moves is a drag, one that does not is a click.

Seven types ship:

type	Name	What it draws
media_player	Media player	What is playing over MPRIS: art, title, transport, and a progress bar as the card grows
weather	Weather	The current conditions and a forecast strip, over a sky animated to match
moon_phase	Moon phase	Tonight’s Moon drawn at its actual phase, with the times it rises and sets and what the phase means for tides, night light and eclipses
fortune	Fortune	A line from fortune(6) over a lamp, with a button that asks for another
tux	Tux	A penguin with something nice to say each day
analog_clock	Analog clock	The time on a dial, with an hour hand and a minute hand and no second hand
stocks	Stock market	Your watchlist: each ticker’s price, its move today and where it sits in the day’s range

[[desktop.widgets]]
type = "moon_phase"
id = "moon_phase"
column = 4
row = 0
column_span = 3
row_span = 2

Key	Type	Default	Description
type	string		One of the types above. Required — an entry without one is ignored
id	string	the type	This widget’s identity, so two of a kind can be told apart
column	number	0	Grid column of the top-left cell
row	number	0	Grid row of the top-left cell
column_span	number	1	Width in cells, clamped to what the type allows
row_span	number	1	Height in cells, clamped to what the type allows

A span outside what a type allows is clamped when it is drawn rather than rewritten in the file, so a layout authored when a widget allowed more room comes back at full size if that changes again. A type this build does not know is drawn as a placeholder and kept in the file, so an entry from a newer version survives a downgrade and there is still something to right-click.

An icon in a widget’s way is moved aside; a widget in an icon’s way refuses the drop, since there is no exchange of places to make between one cell and six. Organize compacts the icons and never moves a widget.

The Moon phase widget

The phase, the illuminated fraction and the age of the Moon are the same everywhere on Earth, so this widget needs no configuration and works out of the box. Two things do depend on where you are, and both come from the location you set for the weather (Settings → Shell → Modules → Weather, or [modules.weather] location):

• Moonrise and moonset, printed for the current day. A day with neither — which happens about once a month, and for weeks at a time inside the polar circles — says so rather than showing blanks.
• Which way up the disc is drawn. South of the equator the Moon is seen rotated half a turn, so a waxing crescent is lit on the left.

With no weather location set, the shell uses the same one-off IP lookup the weather does; if that is unavailable too, the card drops those two lines and keeps everything else.

The analog clock widget

No configuration, and no second hand — deliberately. A hand that sweeps seconds is a repaint every second, on every monitor, for as long as the card is on screen; this one wakes when the minute changes and is idle in between, so a clock on the desktop costs nothing to leave there. The hour hand still moves continuously between the numerals, so half past six looks like half past six.

The face buys its detail from the size you give it: at one cell it draws the twelve hour marks, at two it adds the sixty minute marks, and larger still it sets the hour numerals inside them. It is drawn in your theme — the dial takes control_surface, the marks and hands foreground, and the pivot accent — so it changes with everything else when you change themes.

The stock market widget

The same watchlist as the bar’s stock market strip ([modules.stocks]), from the same poll: a ticker added from the strip’s popup appears on the widget straight away, and the two always show the same price. Each row is the ticker, its price and its move today; widen the card and it adds the company name and a bar showing where the price sits between today’s low and high, with the stretch since the open drawn in the day’s colour. Click a row to open its page on Yahoo Finance.

It is drawn in your theme — the card is the theme’s popup surface, the text its popup_foreground and muted, the range marker its accent — and the green and red are darkened or lightened just enough to read on whatever popup_background the theme has. With no tickers on the list it offers a button to the setting that holds them.