Module ui 

The closed UI vocabulary widgets build their views from.

Every node is semantic: it says what something is (a label, a heading, a button), never how it looks. The host maps nodes to pixels using its theme, so every plugin gets the same style, and the same animations, without being able to break them.

Structs

Item

What a widget shows in the bar.

Node

A piece of UI. Build it with the functions in this module.

Notice

A notification to show on screen, from Widget::notices.

Panel

The contents of a popover. The host draws the surface, its background and its edges, and lays every popover out at the same width.

Reply

A field on a Notice to type an answer into, like a reply to a message.

Enums

Icon

A status symbol. It names what to show and how full it is; the host draws it in the text’s tone, at the text’s size. Fractions are 0.0 to 1.0.

Tone

The role of a piece of text. The theme decides the color.

Urgency

How much a Notice matters. The host decides what that looks like.

Functions

alternate

One of options at a time: the one at current, or the last one if it’s past the end. It’s as big as the biggest option, so it doesn’t change size when current does. The host fades from one to the other. Keep the options the same from one view to the next, so the host can tell which one is coming in.

app_icon

An application’s icon, found by its app id or window class (firefox, org.gnome.Nautilus) in the user’s icon theme. Sized like an icon, in the app’s own colors: a tone only dims it. Until the host has found it, or if there is none, it shows the id’s first letter.

badge

A short code in a small outlined box: a keyboard layout’s US.

button

column

Children stacked top to bottom.

counter

A number from range, with a unit after it ("%", "°", or ""), shown like a label. It keeps room for the widest number in range, so it doesn’t change width as it changes. When value changes, the host counts to it through every number in between.

detail

A named value on one line: the name dimmed at the start, the value at the end.

display

Its text, large: the one number a popover is about, like a battery’s charge.

empty

Takes up a grid cell, or nothing elsewhere.

expand

collapsed, or expanded once the pointer rests on this node, fading between them like a hover. Unlike hover, it’s only as big as what it shows, so the item grows to make room and the island springs along, and it reacts to the pointer over it, not the whole item: a workspace that shows every window when you point at it.

fill

Takes the free space in a popover row, pushing what follows to the end. Nothing in the bar.

grid

Cells laid out left to right in rows of columns, all the same width. A calendar, a keypad.

gulp

Keeps gulping, like a bottle being poured: the host swells content gently and steadily for as long as it’s on screen. For something filling up, like a charging battery’s percent.

header

The title of a popover page. Sub-pages get a back button with on_back; a trailing node sits at the far end (a switch, a count).

heading

A title, larger than a label. Meant for popovers.

hover

normal, or hovered while the pointer is over the item, fading between them like an alternate: an icon that shows its percent, a time that shows the date.

icon

A symbol, sized like a label.

image

An icon the plugin ships: an SVG or PNG file compiled into it with include_bytes!, told apart by its first bytes. Sized like an icon, in the file’s own colors: a tone only dims it, as with app_icon. The host draws it once, off the UI thread, and shows nothing in its place until then.

label

list

Rows stacked closely, usually list_items. In a popover, a long list scrolls instead of growing past a few rows.

list_item

A row in a popover list: a network, a device, a window. Give it a subtitle, a leading icon, a trailing node at the far end (a lock, an info button), mark the one in use with selected, and make it clickable with on_press. A long title fades out at the end rather than wrapping.

mark

Its content on a filled accent circle: today in a calendar.

meter

A bar filled to fraction (0.0 to 1.0), in its tone: a charge, a signal. The host eases it to a new value.

row

Children side by side, vertically centered.

section

A small caption over a group in a popover (“Output”, “Health”), with an optional trailing node at the far end.

separator

A thin horizontal line between groups.

slider

A value dragged along range: a volume. Sends on_change while dragging; add on_release to act once it’s let go, and step to snap.

switcher

A row of choices, one of them current: workspaces, output devices. Each option sends its message when clicked. The host marks the current option and moves the mark smoothly when current changes.

symbol

Like image, but only the file’s shape counts: it’s drawn in the text’s tone, like an icon. For a monochrome symbol the vocabulary doesn’t have.

tabs

Pages behind a row of tabs, one page showing at a time: a popover’s Output, Input and Apps. The host draws the tabs, switches pages when one is clicked and starts on the first each time the popover opens, so the plugin keeps no state for it. In the bar, only the first page shows.

text_input

A field to type into, showing value. Sends on_input with the new text on every change. It takes the focus when it appears, and while it has it, keys stay in the popover; Esc still closes it. on_submit is sent on Enter. One per popover page. A Tone::Critical tone marks it as wrong.

toggle

An on/off switch. Sends on_toggle when clicked; the host slides it over.