Types

The records, enums, aliases and opaque types of the builtin schema. The language's own types (int, float, bool, text, color, length, duration, T?, [T], Async<T> and the rest) are in spec.md, section 7.1.

Records

`AccessPoint`

A Wi-Fi network in range, from the last scan; access points of one network name are one entry (the strongest). Keyed by ssid.

Keyed by ssid.

Field	Type
`ssid`	`text`	The network's name.
`strength`	`float`	Signal strength, 0 to 1.
`secure`	`bool`	It needs a password: a WPA, WPA2 or WPA3 personal or a WEP network, which `connect_with` joins (a network menu's password field). An open or Enhanced Open network takes none, and an enterprise (802.1X) one joins through its saved profile, with `connect()`.
`active`	`bool`	It is the network joined (`network.ssid`); not while it is still being joined or being left (`network.connecting`, `network.disconnecting`).

Method

action connect() Joins it: with its saved connection if there is one, else a new one (for a secure network NetworkManager asks its secret agent for the password; iwd joins only a network it knows this way); an enterprise (802.1X) network with no saved profile is refused (it is set up in the system's network settings, or iwd's provisioning file). A failure, including one NetworkManager reports later (no password, a wrong one, a timeout), is network.failed.

action connect_with(password: text) Joins a secure network with password (its WPA key or WEP key), saved in its connection: a network menu's password field. On any other network it fails. A failure is network.failed.

Method
`action connect()`	Joins it: with its saved connection if there is one, else a new one (for a `secure` network NetworkManager asks its secret agent for the password; iwd joins only a network it knows this way); an enterprise (802.1X) network with no saved profile is refused (it is set up in the system's network settings, or iwd's provisioning file). A failure, including one NetworkManager reports later (no password, a wrong one, a timeout), is `network.failed`.
`action connect_with(password: text)`	Joins a `secure` network with `password` (its WPA key or WEP key), saved in its connection: a network menu's password field. On any other network it fails. A failure is `network.failed`.

`ActionRun`

(lockmon) A declared action's commands as they run, read through the action's name: rec.running, rec.started and rec.stop() for action rec(…) […]. Only an action's name reads as one.

Field	Type
`running`	`bool`	A command of it runs: true while any does (an action with a result may run several at once).
`started`	`Date?`	When the command running longest started, to the minute; null while none runs.

Method
`action stop()`	Stops every command of it now running, and the re-run queued behind one: SIGINT to each one's process group, SIGTERM 2 s later, SIGKILL 2 s after that.

`App`

An installed app, from its desktop entry (watched live).

Keyed by id.

Field	Type
`id`	`text`	Its desktop entry id (`org.gnome.Nautilus`, `kde-dolphin`: the entry's path below `applications/`, `/` as `-`, without `.desktop`).
`name`	`text`	Its name, in the user's language.
`comment`	`text?`	Its comment, if the entry has one.
`icon`	`text`	Its icon: `image h.app.icon`. An icon name of the desktop's icon theme, or a path; `application-x-executable` when the entry names none the theme has.
`categories`	`[text]`	Its desktop entry categories.
`actions`	`[AppAction]`	The actions its entry offers besides starting it (`New Window`, `New Private Window`), keyed by `id`: a launcher's or a dock's menu, `for a in h.app.actions { button a.name { on click { a.launch() } } }`.

Method
`action launch()`	Starts it (its `Exec` line, detached; in a terminal when the entry asks for one) and counts the launch for frecency: `on activate { h.app.launch() }`.

`AppAction`

One of an app's desktop actions ([Desktop Action new-window]).

Keyed by id.

Field	Type
`id`	`text`	Its id in the desktop entry (`new-window`).
`name`	`text`	Its name, in the user's language.
`icon`	`text?`	Its own icon, when it names one the icon theme has (or a path).
`app`	`text`	The `id` of the app it belongs to (`App.id`).

Method
`action launch()`	Starts it (its own `Exec` line, as `launch()` starts the app's) and counts as a launch of its app for frecency.

`AudioDevice`

An audio sink or source, from PipeWire.

Keyed by id.

Field	Type
`id`	`int`	Its PipeWire id.
`name`	`text`	Its node name.
`description`	`text`	A readable description of it.
`volume`	`float rw`	Volume, 0 to 1, on the cubic scale `wpctl` and `pactl` show (above 1 when another program amplified it). Writable: `audio.sink.volume -= dy * 0.05`; every channel takes the new value.
`muted`	`bool rw`	Muted. Writable: `audio.sink.muted = !audio.sink.muted`.
`icon`	`text`	An icon name for its volume and mute state.
`default`	`bool`	It is the default device.

Method
`action make_default()`	Makes it the default device.

`AudioMeter`

A peak meter audio.levels runs: an item of audio.meters.

Keyed by device.

Field	Type
`device`	`int`	The device it reads (`AudioDevice.id`).
`bands`	`[float]`	Its latest spectrum: 64 bands from low to high pitch, each 0 to 1; empty while the device is quiet.

`AudioStream`

A program's audio stream, from PipeWire: what it plays or records.

Keyed by id.

Field	Type
`id`	`int`	Names it while it lives: PipeWire's `object.serial` for it, which, unlike its global id, no later stream takes.
`app`	`text`	The program's name, such as `Firefox`.
`icon`	`text`	An icon name for the program.
`direction`	`StreamDirection`	`output` while it plays, `input` while it records a source (a microphone in use), `monitor` while it records what a sink plays (a visualiser, a recorder of the desktop's sound): a microphone light is `audio.streams.any(s => s.direction == input)`.
`volume`	`float rw`	Its own volume, on the scale a device's uses. Writable: `st.volume = v`.
`muted`	`bool rw`	Muted. Writable: `st.muted = !st.muted`.

`BluetoothDevice`

A Bluetooth device: one paired with the adapter (bluetooth.devices) or one in range (bluetooth.nearby), keyed by address.

Field	Type
`address`	`text`	Its address.
`name`	`text`	Its name.
`connected`	`bool`	It is connected.
`battery`	`float?`	Its battery, 0 to 1, when it reports one.
`icon`	`text`	An icon name for its kind.
`connecting`	`bool`	A `connect()` or `pair()` of it runs (pairing, trusting, connecting), until it ends; of several calls running, the one asked last shows.
`disconnecting`	`bool`	A `disconnect()` of it runs, until it ends; of several calls running, the one asked last shows.

Method
`action connect()`	Connects to it; a failure is `bluetooth.failed`. Asked again while a connect or pair of it runs (a double click), it is dropped.
`action disconnect()`	Disconnects from it; a failure is `bluetooth.failed`. Asked again while one runs, it is dropped.
`action pair()`	Pairs with it, trusts it (so it may reconnect on its own) and connects to it: how a `nearby` device is added. One already paired is trusted and connected. Strand asks for no PIN or passkey: BlueZ pairs through the system's pairing agent if one runs, else without one (most headphones, mice, keyboards and phones). A device that insists on a PIN fails. A pairing not done within a minute is cancelled and fails. Asked again while one runs (a double click), it is dropped. A failure is `bluetooth.failed`.
`action forget()`	Forgets it: unpaired and removed from the adapter, so it leaves `devices`. Asked again while one runs, it is dropped. A failure is `bluetooth.failed`.

`Canvas`

What canvas { draw: (c) => … } draws on, with the paint API the renderer uses.

A live handle, not data: it compares, but persist and settings files cannot store it.

Field	Type
`width`	`float`	The canvas width.
`height`	`float`	The canvas height.

Method
`fn fill(paint: paint, evenodd: bool = false)`	Fills the shapes drawn since the last paint with `paint`, or the whole canvas when there are none. `evenodd: true` fills by the even-odd rule, so a shape drawn inside another cuts a hole in it (a ring is two circles); unset, overlapping shapes all fill.
`fn stroke(paint: paint, width: length = 1)`	Strokes the shapes drawn since the last paint with `paint`, `width` wide.
`fn line(x1: float, y1: float, x2: float, y2: float)`	A line from (`x1`, `y1`) to (`x2`, `y2`).
`fn rect(x: float, y: float, w: float, h: float)`	A rectangle at (`x`, `y`), `w` wide and `h` high.
`fn circle(x: float, y: float, r: float)`	A circle centred at (`x`, `y`) with radius `r`.
`fn text(t: text, x: float, y: float)`	Text `t` at (`x`, `y`).
`fn move(x: float, y: float)`	Starts a path of your own at (`x`, `y`): `c.move(0, 40); c.to(20, 10); c.to(40, 30); c.stroke($accent, 2)` draws a polyline.
`fn to(x: float, y: float)`	A line from the path's current point to (`x`, `y`). With no path open (at the start, after `close`, a paint, a `rect` or a `circle`), it starts one at (`x`, `y`).
`fn arc(x: float, y: float, r: float, from: angle, to: angle)`	An arc of the circle centred at (`x`, `y`) with radius `r`, from angle `from` to angle `to`: `0deg` points right and angles grow clockwise, as `rotate` turns, so `to` past `from` turns clockwise (at most one whole turn). It joins the open path with a line to its start, or starts one there: `c.move(20, 20); c.arc(20, 20, 16, from: -90deg, to: 30deg); c.close(); c.fill($accent)` is a pie slice. An `atan2` angle runs from -180deg to 180deg: an arc from `135deg` to one turns back past 180deg, so add `360deg` to an angle below the start (`to: a < 135deg ? a + 360deg : a`).
`fn close()`	Closes the open path with a line back to where it started.

`ClipboardEntry`

One entry of the clipboard's history: a text or an image copied, newest first, keyed by id.

Field	Type
`id`	`int`	Its identity, kept while it is in the history (across restarts).
`text`	`text`	Its text, or "" for an image.
`image`	`text?`	An image's file, which `image` draws (`image e.image ?? ""`), or null for a text.
`size`	`int`	Its size in bytes, as copied.
`time`	`Date`	When it was last copied.

Method
`action copy()`	Makes it the selection again; it moves to the front of the history: `on click { e.copy() }`.
`action remove()`	Removes it from the history, its image file with it.

`Connection`

A connection saved in NetworkManager (a Wi-Fi network joined before, a wired profile, a VPN, a WireGuard tunnel): an item of network.connections, keyed by its UUID.

Keyed by id.

Field	Type
`id`	`text`	Its UUID, which stays when it is renamed: the key.
`name`	`text`	Its name, as the network settings show it (`Home`, `Work VPN`).
`kind`	`ConnectionKind`	What kind of network it is: `if c.kind == vpn { … }`.
`active`	`bool`	It is up (activated; not while it is still being brought up).

Method
`action up()`	Brings it up (NetworkManager's `ActivateConnection`, on the device NetworkManager picks): a VPN toggle's `on`. It is followed until it is up; a failure, including one NetworkManager reports later (a secret missing, a timeout), is `network.failed(name, error)`. Over iwd it fails.
`action down()`	Takes it down (`DeactivateConnection`). When it is not up, or over iwd, it fails, as `network.failed(name, error)`.

`Date`

A date and time of day, such as clock.today.

Field	Type
`year`	`int`	The year.
`month`	`int`	The month, 1 to 12.
`day`	`int`	The day of the month, 1 to 31.
`weekday`	`int`	The day of the week.
`hour`	`int?`	The hour, 0 to 23; null for a date without a time of day (`clock.today`, a calendar's days). `clock.now` and a notification's `time` have one: `n.time.format("%H:%M")`.
`minute`	`int?`	The minute, 0 to 59; null when `hour` is.

Method
`fn month_start() -> Date`	The first day of its month: `clock.today.month_start()`.
`fn add(days: int = 0, months: int = 0, years: int = 0) -> Date`	Moves by days, months and years, keeping its time of day: `month.add(months: -1)`.
`fn format(pattern: text) -> text`	Formats with a strftime pattern: `month.format("%B %Y")`.

`Day`

A cell of a month grid, from calendar.days(month).

Keyed by date.

Field	Type
`date`	`Date`	The day's date.
`in_month`	`bool`	It falls in the month asked for; the grid is padded with the days of the months around it.
`today`	`bool`	It is today.
`weekend`	`bool`	It falls on a weekend.

`Drop`

What another program drops on an element (design.md, "Drag and drop"): files, an app or text, as on drop(d: Drop, at: int). kind says which; the other fields are empty. A drag inside the shell delivers the drag: source's own value instead (on drop(p: Pin, at: int)).

Field	Type
`kind`	`DropKind`	What was dropped: `files`, `app` or `text`.
`files`	`[path]`	The dropped files.
`app`	`App?`	The dropped app.
`text`	`text`	The dropped text.

`File`

A file a from dir service lists: service walls from dir "~/Pictures/walls" { files: [File] }, then for f in walls.files key f.path { image f.path }.

Keyed by path.

Field	Type
`path`	`text`	Its full path.
`name`	`text`	Its name, without the directory.
`modified`	`Date`	When it last changed, to the minute.
`size`	`int`	Its size in bytes.

`Filesystem`

A mounted filesystem, keyed by path.

Field	Type
`path`	`text`	Where it is mounted: `/`, `/home`.
`device`	`text`	The device it is on: `/dev/nvme0n1p2` (the mount's source).
`usage`	`float`	The fraction in use, 0 to 1, as `df` counts it (used over used plus free).
`used`	`float`	Bytes in use.
`total`	`float`	Bytes in all.
`free`	`float`	Bytes free to a user (space reserved for root left out).

`Hit`

A launcher search result: the app, its score and the matched ranges.

Keyed by app.id.

Field	Type
`app`	`App`	The app found.
`score`	`float`	Its score: fuzzy match plus frecency (higher first).
`ranges`	`[Range]`	The matched character ranges of its name: `marks: h.ranges`. Empty when the query matched its keywords or generic name instead.

`IdleTimeout`

A timeout idle.after was asked about, and whether the seat has been idle that long.

Keyed by timeout.

Field	Type
`timeout`	`duration`	How long without input it waits for.
`idle`	`bool`	The seat has had no input for at least `timeout`.

`Key`

A key press: on key(k: Key).

Field	Type
`name`	`text`	The key's name, such as `Escape`, `Return` or `a`.
`text`	`text`	The text the key types; empty for keys that type none.
`ctrl`	`bool`	Ctrl is held.
`shift`	`bool`	Shift is held.
`alt`	`bool`	Alt is held.
`logo`	`bool`	The logo (Super) key is held.

`Node`

A node of the tree: self, or an element given an id:.

A live handle, not data: it compares, but persist and settings files cannot store it.

Field	Type
`hover`	`bool`	The pointer is over it (latched while dragging).
`pressed`	`bool`	A pointer button is held down on it.
`focused`	`bool`	It has keyboard focus. On a `window` (its `id:`), the compositor has it focused (its `activated` state): `w.focused`.
`selected`	`bool`	It is the selected item of a `list`; arrow keys move the selection.
`width`	`float`	Its laid-out width. `when self.width < 300 { … }` is a container query, with 4 px hysteresis so it cannot flicker.
`height`	`float`	Its laid-out height.
`open`	`bool`	A `popup` (or another surface) is open: from the moment its `open` turns true (or the pointer opens a `trigger: hover` one) until it turns false, as its exit pose starts. False on other elements. `when cal.open { bg: $surface.hi }` styles an anchor while its popup shows.
`box`	`Rect`	Its laid-out box, in its surface's logical pixels from the top-left corner of the surface's box (paint offsets, transforms and poses not applied). A popup's own box is where it sits in the surface it opens from; a bar's, panel's or OSD's is at 0, 0. It updates a frame after layout moves it, and springs like any value: `x: item.box.x - row.box.x ~ $motion.spatial`. It may drive anything that does not lay it out again, through any chain of bindings: paint props (`x`, `y`, `opacity`, colours, transforms; a surface's effects), the size of a `place: absolute` element it is not inside, or what is on another surface that reads nothing back; a load error shows the loop otherwise. A loop through another node's `width` or `height` with no `box` on it is a warning, `check::size_loop`.
`pointer`	`Point?`	The pointer over it, in its laid-out box (0, 0 is its top-left corner as layout put it; its paint offsets and transforms, and its ancestors', are undone, as for a slider), once a frame while it moves or the node moves under it; null while the pointer is not over it. While a left-button press that began on it is held it stays set, wherever the pointer goes (outside the box too), in the frame the node had when the press began: what the drag moves (its `x`, its layout, its surface's margins) does not move the frame, so `on change self.pointer { if self.pressed { px = px0 + (self.pointer?.x ?? grab.x) - grab.x } }` (`grab` a `Point` kept when the press began) follows the pointer without feeding back. An `on change` of only nodes' input state (`pointer`, `hover`, `pressed`, `focused`, `selected`) is an input handler, never throttled.
`maximized`	`bool`	A `window` the compositor maximised. False on other elements.
`fullscreen`	`bool`	A `window` the compositor made fullscreen. False on other elements.
`tiled`	`bool`	A `window` the compositor tiles against another window or a screen edge on any side: drawn square there, with no shadow. False on other elements.
`decorated`	`bool`	A `window` whose title bar and borders the compositor draws (`decorations: server` where it offers them). While false the config draws its own: `if !w.decorated { TitleBar }`. False on other elements.
`blank`	`bool`	A `thumbnail` with nothing to show, which draws nothing: its window went, its screen could not be captured, or inside a `lock` its monitor has no still from before the lock (it was plugged in while locked). `when still.blank { … }` styles that monitor's lock its own way. It turns true a frame after the thumbnail is first drawn, and false when a frame comes. False on other elements.

Method
`action move()`	`w.move()` moves a `window` with the pointer, from a handler of the press that is still held (`on change bar.pressed { if bar.pressed { w.move() } }`): a title bar the config draws.
`action resize(edge: Anchor)`	`w.resize(bottom_right)` resizes a `window` with the pointer from that edge or corner, from a handler of the press that is still held.
`action minimize()`	Minimises a `window`.
`action maximize()`	`w.maximize()` maximises a `window`, or restores it when it is maximised.
`action fullscreen()`	`w.fullscreen()` makes a `window` fullscreen, or restores it when it is fullscreen.
`action close()`	Closes a `window` as the compositor's close button does: its `open: <-> x` is written false.

`Notification`

A desktop notification, keyed by id.

Field	Type
`id`	`int`	Its identity.
`app`	`NotificationApp`	The app that sent it.
`summary`	`text`	Its summary line.
`body`	`text`	Its body, which may hold basic markup (`markup: basic`).
`image`	`text?`	An image it carries, if any: a path.
`urgency`	`Urgency`	`low`, `normal` or `critical`.
`timeout`	`duration?`	How long the sender asked it to show; null leaves it to the shell: `after n.timeout ?? 6s { n.expire() }`.
`persistent`	`bool`	The sender asked it never to expire (an `expire_timeout` of 0): a shell keeps its popup with `after n.timeout ?? 6s while !n.persistent { n.expire() }`.
`time`	`Date`	When it arrived.
`actions`	`[NotificationAction]`	The buttons it offers; none on one remembered from an earlier run (`notifications.remember`), whose sender cannot hear them.
`progress`	`float?`	How far along what it reports is, 0 to 1 (the sender's `value` hint, a percentage), null when it says none: `meter n.progress ?? 0`.
`category`	`text?`	The kind of event it reports (the `category` hint: `email.arrived`, `transfer.complete`), null when the sender gives none.
`desktop_entry`	`text?`	The desktop entry of the app that sent it (the `desktop-entry` hint), null when the sender gives none.
`can_reply`	`bool`	The sender takes a typed reply (an `inline-reply` action, which is not among `actions`): `if n.can_reply { input … }`. Strand offers senders inline replies only while the config names `can_reply` or `reply`, so a sender keeps its own Reply button otherwise. False on one remembered from an earlier run.

Method
`action expire()`	Ends its popup, as a timeout does; it stays in `all`, still open (its actions still reach the sender) until dismissed.
`action dismiss()`	Closes it: `on secondary { n.dismiss() }`.
`action activate()`	Invokes its default action: `on click { n.activate() }`.
`action reply(text: text)`	`n.reply(text)` sends `text` to the sender as its inline reply (to that sender alone, never to other programs on the bus) and closes it (unless it is resident); nothing when it takes no reply.

`NotificationAction`

A button a notification offers.

Keyed by id.

Field	Type
`id`	`text`	Its identity: the key the sender gave it.
`label`	`text`	Its label: `button a.label`.
`notification`	`int`	The notification it belongs to.

Method
`action invoke()`	Invokes it: `on click { a.invoke() }`. The sender is told; the notification closes unless it is resident.

`NotificationApp`

The app that sent a notification.

Field	Type
`name`	`text`	The app's name.
`icon`	`text`	The app's icon: an icon name or a path.

`Output`

A monitor as the compositor's output configuration sees it, on or off, keyed by name: what a display settings page shows and changes with outputs.apply.

Field	Type
`name`	`text`	Its connector name, such as `DP-1`: the same as `Screen.name` while it is on.
`description`	`text`	A readable description of it.
`make`	`text`	Its maker, or "" when the compositor does not say.
`model`	`text`	Its model, or "" when the compositor does not say.
`serial`	`text`	Its serial number, or "" when the compositor does not say.
`enabled`	`bool`	It is on: shown, and part of the layout.
`mode`	`OutputMode?`	The mode it shows, or null while it is off.
`preferred`	`OutputMode?`	The mode the monitor prefers, if it names one.
`modes`	`[OutputMode]`	Every mode it can show, each once, in the compositor's order (plain data: `for m in o.modes key join("x", m.width, m.height, m.refresh)`).
`x`	`int`	Its left edge in the layout, in logical pixels (its last place while it is off).
`y`	`int`	Its top edge in the layout, in logical pixels.
`scale`	`float`	Its scale factor (`1.5`).
`transform`	`OutputTransform`	Its rotation (counter-clockwise, as `wl_output` counts) and flip.
`adaptive_sync`	`bool`	Adaptive sync (variable refresh rate) is on.
`physical_width`	`int`	Its physical width in millimetres, or 0 when unknown.
`physical_height`	`int`	Its physical height in millimetres, or 0 when unknown.

`OutputChange`

One output's part of a configuration for outputs.apply and outputs.test, named by name: a null field keeps what the output has, so OutputChange(name: o.name, scale: 1.5) changes only its scale.

Field	Type
`name`	`text`	The output it changes (`Output.name`).
`enabled`	`bool?`	Turns it on or off.
`mode`	`OutputMode?`	The mode to show: one of its `modes`, or a size and rate (the listed mode of that size nearest the rate within 0.5 Hz, else a custom mode; a rate of 0 takes the fastest listed one).
`x`	`int?`	Its left edge in the layout, in logical pixels.
`y`	`int?`	Its top edge in the layout, in logical pixels.
`scale`	`float?`	Its scale factor, from 1/256 (the protocol's step) up.
`transform`	`OutputTransform?`	Its rotation and flip.
`adaptive_sync`	`bool?`	Adaptive sync on or off.

`OutputMode`

A mode an output can show: its size in hardware pixels and its refresh rate. An output's modes list them; OutputMode(width: 2560, height: 1440, refresh: 144) names one for OutputChange.mode.

Field	Type
`width`	`int`	Its width in hardware pixels (before scale and rotation).
`height`	`int`	Its height in hardware pixels.
`refresh`	`float`	Its refresh rate in Hz (`59.951`), or 0 when it has no fixed rate.

`Player`

One MPRIS player: an item of media.players, with the fields and actions media has for the active one.

Keyed by id.

Field	Type
`id`	`text`	Its bus name, such as `org.mpris.MediaPlayer2.spotify`: the key.
`name`	`text`	Its name, such as `Spotify` or `mpv` (its MPRIS `Identity`, else its bus name's last part).
`active`	`bool`	`media.*` follows it now.
`playing`	`bool`	It is playing.
`title`	`text?`	The track's title.
`artist`	`text?`	The track's artist.
`album`	`text?`	The track's album.
`art`	`text?`	The album art, as `media.art` shows it.
`position`	`float rw`	Fraction of the track played, 0 to 1. Writable: seeks this player, as writing `media.position` seeks the active one.
`elapsed`	`duration`	Time played.
`length`	`duration?`	The track's length, when known.
`can_next`	`bool`	It can skip to the next track.
`can_previous`	`bool`	It can go back to the previous track.
`can_seek`	`bool`	Writing `position` seeks it.

Method
`action play_pause()`	Plays or pauses it.
`action next()`	Skips it to the next track.
`action previous()`	Takes it back to the previous track.
`action select()`	Makes it the player `media.*` follows, until it leaves or another player starts playing: `on click { p.select() }`.

`Point`

A point (self.pointer), logical pixels.

Field	Type
`x`	`float`	From the left.
`y`	`float`	From the top.

`PolkitRequest`

A program asking polkit for something that needs a password first (pkexec, a settings page changing the system): what the dialog shows. polkit.request is the one being answered.

Field	Type
`action_id`	`text`	The polkit action asked for (`org.freedesktop.policykit.exec`).
`message`	`text`	What polkit says it is for, in your language ("Authentication is needed to run `/usr/bin/bash' as the super user").
`command`	`text?`	The command it would run, with its arguments, as the program asked (`pkexec`'s: "/usr/bin/sh -c rm -rf /tmp/x"), or null for a request that runs none (a settings page's). Show it: `message` names only the program, so it is what tells one `pkexec sh -c …` from another.
`icon`	`text`	The icon the program named for it (a theme icon name), or "".
`user`	`text`	The user whose password is asked for: you, or an administrator when the action needs one. Another of `users` is picked with `polkit.choose(user)`.
`users`	`[text]`	Every user polkit would take a password from for it (the administrators, or only you), each once; `user` is one of them.
`prompt`	`text`	What the password check asks ("Password: "), as PAM says it; "" while it asks nothing (an answer being checked, a fingerprint reader waiting).
`echo`	`bool`	The answer to `prompt` may be shown as it is typed (PAM asks for a name, not a secret).
`info`	`text`	What PAM last told the user, as it said it ("Place your finger on the fingerprint reader"), or "".

`PowerDevice`

A power source UPower reports besides the combined battery: a laptop's own batteries, a mouse's, a headset's. Keyed by id.

Field	Type
`id`	`text`	Its UPower object path.
`name`	`text`	Its model name, or its kernel name when it has none.
`kind`	`text`	What it is: `battery`, `ups`, `mouse`, `keyboard`, `headset`, `phone`, `tablet`, `gaming_input` or `other`.
`percent`	`float`	Charge, 0 to 1.
`charging`	`bool`	It is charging.
`icon`	`text`	An icon name for its charge and state.

`Range`

A span of characters: from start up to, not including, end.

Field	Type
`start`	`int`	The first character.
`end`	`int`	Just past the last character.

`Rect`

A box in logical pixels: a laid-out node's (id.box), or a window's place on its screen (win.rect).

Field	Type
`x`	`float`	Its left edge.
`y`	`float`	Its top edge.
`width`	`float`	Its width.
`height`	`float`	Its height.

`Screen`

A monitor. id is its identity (make, model and description, with #2 for a second identical one): what a bar instance is keyed and pinned by, kept across a replug to another port. name is the connector (DP-1).

Keyed by id.

Field	Type
`id`	`text`	Its identity: make, model and description, with `#2` for a second identical one. Kept across a replug to another port.
`name`	`text`	Its connector name, such as `DP-1`.
`make`	`text`	Its maker.
`model`	`text`	Its model.
`description`	`text`	A readable description of it.
`scale`	`float`	Its scale factor.
`width`	`float`	Its width in logical pixels.
`height`	`float`	Its height in logical pixels.
`focused`	`bool`	It has keyboard focus.

`TrayItem`

An item in the system tray (StatusNotifierItem), keyed by id.

Field	Type
`id`	`text`	Its identity: its bus name and object path.
`title`	`text`	Its title.
`icon`	`text`	Its icon: `image item.icon`. An icon name, or the path of a picture (an icon the app ships, or pixels it sent).
`tooltip`	`text?`	Its tooltip, if it has one.
`status`	`text`	`Active`, `Passive` or `NeedsAttention`.
`menu`	`TrayMenu`	Its menu.

Method
`action activate()`	Its primary action: `on click { item.activate() }`. An item that is only a menu (`ItemIsMenu`: most libappindicator apps) opens its menu instead (`menu.opened`), as the StatusNotifierItem spec asks. The app is told where: the bottom-left corner of the element pressed, in its screen's logical pixels (where an app showing a menu of its own puts it).
`action secondary()`	Its secondary action, told where as `activate()` is.
`action scroll(dy: float)`	Scrolls on it by `dy` wheel notches (one click is 1, a touchpad sends fractions; positive is down, as `on scroll(dy)` gives it). The app gets 120 per notch, positive up, as KDE's tray sends it.

`TrayMenu`

A tray item's menu (DBusMenu).

Field	Type
`item`	`text`	The tray item it belongs to.
`items`	`[TrayMenuItem]`	Its entries, as the app last laid them out; empty when the item has no menu.
`opened`	`bool`	It is open: true from `open()` until `close()` (or the item going away). A popup shows it with `open: item.menu.opened`, and calls `item.menu.close()` when it closes. One flag per item, not per screen: a bar on every screen keeps which screen opened it (`on secondary { item.menu.open(); menu_screen = screen }`, `open: item.menu.opened && menu_screen == screen`).

Method

action open() Opens it: on secondary { item.menu.open() }. The app is told it opens (and may update its entries first), and opened becomes true; a popup { open: item.menu.opened … } drawing items is what shows a DBusMenu, and nothing shows without one. An item without a DBusMenu shows its own menu. An item that is only a menu (ItemIsMenu, or one refusing Activate) opens it on item.activate() too.

action close() The popup closed: the app is told, and opened becomes false.

`TrayMenuItem`

An entry of a tray item's menu (DBusMenu), keyed by id.

Field	Type
`id`	`int`	Its id in its menu.
`item`	`text`	The tray item whose menu holds it.
`label`	`text`	Its label, without mnemonic underscores.
`enabled`	`bool`	It can be chosen.
`kind`	`text`	`standard` or `separator`.
`toggle`	`text`	`none`, `checkmark` or `radio`.
`checked`	`bool`	Its check mark or radio button is on.
`icon`	`text?`	Its icon: an icon name, or the path of the picture the app sent.
`shortcut`	`text?`	Its keyboard shortcut, if it has one (`Control+S`).
`children`	`[TrayMenuItem]`	Its submenu's entries; empty when it has none.

Method
`action activate()`	Chooses it: the app is told it was clicked.
`action open()`	Opens its submenu: the app is told (and may update the entries first).

`VideoStream`

A program taking video over PipeWire.

Keyed by id.

Field	Type
`id`	`int`	Its PipeWire id (the program's stream).
`app`	`text`	The program's name, such as `Firefox`.
`source`	`VideoSource`	Where the video comes from: `camera` when any source it takes is a camera, else `screencast` (a screen or window cast).

`Window`

A toplevel window, from ext-foreign-toplevel-list, with what the compositor's IPC adds.

Keyed by id.

Field	Type
`id`	`text`	Its identity: the compositor's id when its IPC is used, else the protocol's identifier.
`title`	`text`	Its title: `windows.focused?.title`.
`app_id`	`text`	The app's id, such as `firefox`.
`icon`	`text`	An icon name for its app: its desktop entry's icon, else its app id (lowercased when only that is in the icon theme).
`workspace`	`int?`	The workspace it is on, when known.
`focused`	`bool`	It has focus.
`minimized`	`bool`	It is minimised.
`maximized`	`bool`	It is maximised.
`fullscreen`	`bool`	It is fullscreen.
`urgent`	`bool`	It asks for attention.
`app`	`App?`	The installed app it belongs to, found from its app id (the desktop entry's id, `StartupWMClass`, a reverse-DNS id's last part, its name): `win.app?.categories`. Null when no entry matches.
`rect`	`Rect?`	Its place and size on its screen, logical pixels from the screen's top-left corner, from the compositor's IPC: a tiled niri window (which scrolls with its column) and the standard protocols have none. Hyprland tells no move of a floating window, so there it is as of the window's last other change.

Method
`action focus()`	Raises and focuses it.
`action close()`	Asks it to close.
`action minimize()`	Minimises it.
`action maximize()`	`win.maximize()` maximises it, or restores it when it is maximised.
`action fullscreen()`	`win.fullscreen()` makes it fullscreen, or restores it when it is fullscreen.
`action move_to(ws: Workspace)`	`win.move_to(ws)` moves it to workspace `ws`, the focus staying where it is (on the compositors' IPC: Hyprland, sway, niri).

`Workspace`

A workspace, from ext-workspace-v1, keyed by id.

Field	Type
`id`	`int`	Its identity.
`name`	`text`	Its name.
`focused`	`bool`	It is the focused workspace (at most one is; with the standard protocols alone and several screens, none is).
`active`	`bool`	It is shown on its screen (one per screen).
`occupied`	`bool`	It holds windows.
`urgent`	`bool`	A window on it asks for attention.
`screen`	`text`	The name of the screen it is on.
`windows`	`[Window]`	Its windows, keyed by `id`.

Method
`action focus()`	Switches to it: `on click { ws.focus() }`.

Enums

A variant is written bare where its enum is expected (edge: top).

Enum	Variants
`Align`	`start`, `center`, `end`, `stretch`, `baseline`
`Anchor`	`center`, `top`, `bottom`, `left`, `right`, `top_left`, `top_right`, `bottom_left`, `bottom_right`
`Axis`	`vertical`, `horizontal`, `both`. Which way a `scroll` scrolls.
`Blend`	`normal`, `screen`, `add`, `multiply`, `overlay`, `difference`
`BlurFallback`	`tint`, `none`
`Cap`	`butt`, `round`, `square`
`ConnectionKind`	`wifi`, `ethernet`, `vpn`, `wireguard`, `other`. What kind of network a connection is: a Wi-Fi network, a wired one, a VPN, a WireGuard tunnel, or another kind (a bridge, a modem, a hotspot shared over Bluetooth).
`CornerStyle`	`round`, `squircle`
`CursorShape`	`default`, `pointer`, `text`, `crosshair`, `grab`, `grabbing`, `move`, `not_allowed`, `wait`, `progress`, `help`, `context_menu`, `cell`, `copy`, `alias`, `no_drop`, `all_scroll`, `zoom_in`, `zoom_out`, `col_resize`, `row_resize`, `ew_resize`, `ns_resize`, `nesw_resize`, `nwse_resize`, `n_resize`, `e_resize`, `s_resize`, `w_resize`, `ne_resize`, `nw_resize`, `se_resize`, `sw_resize`
`Curve`	`linear`, `ease_in`, `ease_out`, `ease_in_out`, `in_back`, `out_back`, `out_elastic`, `out_bounce`, `standard`, `emphasized`
`Decorations`	`server`, `none`. Who draws a `window`'s title bar and borders: `server`, the compositor where it offers to, or `none`, the config.
`DropKind`	`files`, `app`, `text`
`Edge`	`top`, `bottom`, `left`, `right`
`EffectKind`	`lightning`, `sparks`, `shimmer`, `ripple`, `aurora`
`Ellipsis`	`none`, `start`, `middle`, `end`
`Fit`	`cover`, `contain`, `fill`, `none`
`GraphStyle`	`line`, `steps`, `bars`
`HitKeyword`	`none`
`InputKind`	`text`, `password`. What an `input` holds: `type: password` masks it (docs/grammar.md).
`Instant`	`instant`
`Justify`	`start`, `center`, `end`, `space_between`, `space_around`, `space_evenly`
`Keyboard`	`none`, `on_demand`, `exclusive`
`Layer`	`background`, `bottom`, `top`, `overlay`
`Markup`	`none`, `basic`
`OutputTransform`	`normal`, `rotate_90`, `rotate_180`, `rotate_270`, `flipped`, `flipped_90`, `flipped_180`, `flipped_270`. An output's rotation and flip, as `wl_output` (and niri) name them: counter-clockwise, so sway's clockwise `transform 90` is `rotate_270`; `flipped_90` is flipped about the vertical axis, then rotated 90 degrees.
`Place`	`flow`, `absolute`
`PopupAnchor`	`pointer`. A popup opened where the press that opened it went down.
`PopupTrigger`	`open`, `hover`
`PoseName`	`none`, `fade`, `slidefade`
`RadiusKeyword`	`full`
`Screens`	`all`, `focused`
`Shape`	`rect`, `circle`, `pill`, `cookie`, `clover`, `burst`, `flower`, `gem`, `sunny`, `triangle`, `pentagon`, `hexagon`, `heart`
`SizeKeyword`	`auto`
`SpectrumStyle`	`bars`, `mirror`, `wave`, `line`
`StreamDirection`	`output`, `input`, `monitor`. Whether a program's audio stream plays (`output`), records a microphone or another source (`input`), or records what a sink plays (`monitor`: a visualiser, a recorder of the desktop's sound).
`SwapKind`	`none`, `disc`, `dissolve`, `pixelate`
`Urgency`	`low`, `normal`, `critical`
`Variant`	`tonal_spot`, `vibrant`, `expressive`, `neutral`, `monochrome`, `fidelity`, `content`, `rainbow`, `fruit_salad`
`VideoSource`	`camera`, `screencast`. Where a program's video comes from: a camera, or a screen (or window) cast.
`WifiSecurity`	`open`, `enhanced_open`, `wep`, `wpa`, `wpa2`, `wpa3`, `enterprise`. How a Wi-Fi network is secured. `enhanced_open` is OWE (open, but encrypted); `enterprise` is 802.1X.

Aliases

Alias	Is
`AppId`	`text`

Opaque types

Values with no structure a program can see, made by functions and read by props.

Easing, Filter, HitArea, Mask, Palette, Pose, Spring, Sprite, SwapTransition, TokenSet

Types

#Records

#AccessPoint

#ActionRun

#App

#AppAction

#AudioDevice

#AudioMeter

#AudioStream

#BluetoothDevice

#Canvas

#ClipboardEntry

#Connection

#Date

#Day

#Drop

#File

#Filesystem

#Hit

#IdleTimeout

#Key

#Node

#Notification

#NotificationAction

#NotificationApp

#Output

#OutputChange

#OutputMode

#Player

#Point

#PolkitRequest

#PowerDevice

#Range

#Rect

#Screen

#TrayItem

#TrayMenu

#TrayMenuItem

#VideoStream

#Window

#Workspace

#Enums

#Aliases

#Opaque types

Records

`AccessPoint`

`ActionRun`

`App`

`AppAction`

`AudioDevice`

`AudioMeter`

`AudioStream`

`BluetoothDevice`

`Canvas`

`ClipboardEntry`

`Connection`

`Date`

`Day`

`Drop`

`File`

`Filesystem`

`Hit`

`IdleTimeout`

`Key`

`Node`

`Notification`

`NotificationAction`

`NotificationApp`

`Output`

`OutputChange`

`OutputMode`

`Player`

`Point`

`PolkitRequest`

`PowerDevice`

`Range`

`Rect`

`Screen`

`TrayItem`

`TrayMenu`

`TrayMenuItem`

`VideoStream`

`Window`

`Workspace`

Enums

Aliases

Opaque types