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

Action

Something the widget can do, from Widget::actions, for the dormer: the host’s search dialog. Typing finds it by its title, subtitle and keywords, and picking it sends message to the widget.

Choices

Options to pick from on a Notice, like the answers to a question: one, which a click sends, or several, checked and then sent together.

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, or at a wider one if it asks (Panel::wide).

Pixels

A picture as its pixels, for a Notice whose picture came as bytes rather than a file: RGBA, 8 bits a channel, row after row with nothing between them.

Reply

A field on a Notice to type an answer into, like a reply to a message: several lines, Enter sends and Shift+Enter starts a new line.

Shortcut

A key, with the modifiers held for it: Ctrl+K. Build it with shortcut.

Enums

Change

What a line of a diff is.

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.

Key

A key a Shortcut names. There is no Escape: it always closes the popover (D-41).

Mark

Where a step of a timeline stands. The host draws it as the step’s mark on the line.

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

action

An action titled title that sends message when picked.

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

center

content centered across the panel’s width: a cover, a title, a row of controls. Text in it stays on one line, cut and faded at the edges of its room if it’s too long. In the bar, it’s just content.

column

Children stacked top to bottom.

counted

Its content with count in a red badge at its top right, overlapping it a little: unread notifications on a bell. At 0 there’s no badge. The host grows the badge in and out and counts through the numbers in between; past 99 it shows 99.

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.

cover

A picture a program hands over at runtime, by URL: a track’s cover art. file:// and https:// URLs load; the host fetches, crops it square and rounds it, off the UI thread, and keeps the few latest. Drawn at icon size, or big with Node::large. Until it’s there, or if it can’t be loaded, fallback shows in its place. A tone only dims it.

detail

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

diff

A change to a file, titled with its name: lines added, removed, and some unchanged ones around them. The host counts what was added and removed.

display

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

divider

A separator with a short caption in the middle of it, like the time between two turns of a conversation.

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 leading picture goes before the title, a subtitle under it (where it is, what it’s about), and 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.

keys

A shortcut drawn as keycaps, [Ctrl] [K], to say which key does something. It only shows the keys; to bind one, give a list_item a shortcut.

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 shortcut presses it from the keyboard. A long title fades out at the end rather than wrapping.

literal

Text exactly as typed, not prose: a path, a command, a name in code. It doesn’t wrap: when it doesn’t fit, its end fades out.

mark

Its content marked with a ring: today in a calendar.

markdown

Text written in Markdown, as people and programs write messages: paragraphs, emphasis, code, lists, quotes, headings, code blocks and tables. The host sets it in its own type and colors, wrapped to the width it has. Links show as links but don’t open: the bar starts no programs.

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.

scroll

Its content, scrolling in a popover once it’s taller than the host allows a page to grow: a conversation, a long document. With Node::bottom it keeps its end in view. In the bar it’s just its content.

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.

shortcut

A key to press, for list_item’s shortcut or to show with keys: shortcut('1'), shortcut('k').ctrl().

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.

sprite

A little animation the plugin ships, like a pixel-art mascot: frames are PNG or SVG files compiled in with include_bytes!, all the same size, and order lists which frame shows when, by index into frames. The host keeps the frames’ shape and picks the height (a little under a label’s in the bar, taller in a popover), scaling pixels up whole, never blurred: ship pixel art at its own size. The host shows a frame for a quarter of a second. It plays the loop a couple of times when it shows up or changes, then rests on the first frame of order; Node::looping keeps it going. A tone only dims it.

step

One step of a timeline: content, marked on the line as mark. A leading node, like a small picture, stands on the line in place of the mark. Outside a timeline it’s just its content.

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_area

A field to type several lines into, showing value: a message. It grows with its text up to a few lines, then scrolls. Sends on_input with the new text on every change, and on_submit on Enter; Shift+Enter starts a new line. In a popover it takes the focus when it appears, like a text_input. One per popover page.

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.

timeline

Steps one after another, strung on a line: what someone did, in order. Each child is a step, whose mark says where it stands; other nodes count as steps marked Mark::Note.

toggle

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