Components

All components live in nirvana_protocol::scene and come in with use nirvana_protocol::prelude::*. Each has a constructor and chainable setters, and becomes a Node with .into() (containers take impl Into<Node>, so inside a .child(…) you rarely write it).

The shape of a window

Three shells, for three kinds of applet:

Page

A centred column of content with a large title. For an applet that is one screen of settings or one list.

Page::new()
    .title(tr("Sound"))
    .subtitle(tr("Output, input and what plays where."))
    .child(group)

.wide() gives the column more room. .key(…) names the page, so that replacing it with another plays the entrance of a new page.

SplitView

A glass sidebar of destinations on the left, one page on the right. For an applet with several screens (Settings).

SplitView::new()
    .sidebar_item(SidebarItem::new("nav.wifi", tr("Wi-Fi")).icon("wifi").selected(true).value(tr("Home")))
    .sidebar_item(SidebarItem::new("nav.sound", tr("Sound")).icon("speaker"))
    .child(self.page())

SidebarItem also takes .detail(…) (a second line), .busy(true), .action(icon, label) (a small button at the edge, which sends click to <id>.action), .context() (right click), .reorder(group) and .drop_target().

Pane

A working surface instead of a column of settings: a toolbar, a scrolling body, an optional bar of actions and a status bar. For tools (Calculator, Files, the Terminal). Used alone or as the content of a SplitView.

Pane::new()
    .tool(Text::new(tr("Calculator")).style(TextStyle::Headline))
    .tool(Button::icon_only("history", "clock", tr("History")).plain())
    .child(body)
    .status(Text::new(tr("12 items")).style(TextStyle::Footnote))

Grouping and layout

Group and Row

The workhorse. A Group is an inset rounded list; a Row is one line of it: an icon, a title and subtitle on the left; a value, controls and an accessory on the right.

Group::new()
    .header(tr("Network"))
    .footer(tr("Known networks are joined automatically."))
    .child(
        Row::new(tr("Wi-Fi"))
            .id("open.wifi")                 // the whole row is clickable
            .icon("wifi")
            .value(tr("Home"))
            .accessory(Accessory::Chevron),
    )
    .child(Row::new(tr("Airplane Mode")).trailing(Switch::new("airplane", self.airplane).label(tr("Airplane Mode"))))

Group has .loading(true) (a spinner by the header) and .key(…).

Stack

Free layout where rows do not fit: children in a line, with a gap from the tokens.

Stack::horizontal().gap(Gap::Sm).wrap().child(a).child(b)
Stack::vertical().gap(Gap::Lg).align(Align::Center)

Gap: Xs, Sm, Md, Lg, Xl. Align: Start, Center, End, Stretch. Justify: Start, Center, End, Between.

Text and marks

Icons are named (wifi, trash, search, folder, settings, …): about 150 glyphs on a 24 px grid. A tint passed for an icon tile is accepted and ignored: tiles are quiet by design.

Controls

Button

Button::new("join", tr("Join")).primary()
Button::new("forget", tr("Forget This Network")).destructive()
Button::new("more", tr("More")).plain().size(Size::Small)
Button::icon_only("refresh", "refresh", tr("Refresh"))   // the label is for assistive technology

Variants: .primary() (one per view), secondary (the default), .plain(), .destructive(). Also .icon(name), .size(Size::Small | Regular | Large), .fill() (as wide as its place), .disabled(true), and .opens_menu(): the click then carries the point to open a Menu at.

The rest

Over the window

Sheet

A modal question or a detail view. Add it as a child of the page while it is open.

Sheet::new(tr("Forget “Home”?"))
    .id("forget")                       // Escape and a click outside send `dismiss` here
    .message(tr("This computer will no longer join it automatically."))
    .action(Button::new("forget.cancel", tr("Cancel")))
    .action(Button::new("forget.confirm", tr("Forget")).destructive())

A sheet can hold children (.child(…)): a field for a password, a few rows. The actions share the width, the primary one on the right.

Menu

A popup at a point: the answer to a right click, or to a button with .opens_menu().

// in event:   "row" if event.is("context") => self.menu_at = event.point(),
// in render:
if let Some(point) = self.menu_at {
    pane = pane.child(
        Menu::new("menu", point)
            .item(MenuItem::new("menu.open", tr("Open")))
            .item(MenuItem::new("menu.rename", tr("Rename…")).shortcut("F2"))
            .separator()
            .item(MenuItem::new("menu.delete", tr("Move to Trash")).destructive()),
    );
}

A click elsewhere, Escape, or the window losing focus sends dismiss to the menu’s id: set menu_at = None then, and after any item is chosen. MenuItem also has .icon(…), .checked(true), .disabled(true).

Data

Files

Live components

These are created once and kept across renders; their content does not come from the scene.

Guided steps

For something done in a few steps, one question at a time: Wizard (a rail of steps on glass, a page, back and next), ChoiceCard (a large choice that says what choosing it means), DiskMap (a disk drawn to scale), ProgressRing (long work, its parts ticked off), Persona (a person as they type themselves in), BrandMark (the system’s mark). The installer and the welcome are made of these.

The shell’s own

Dock, DockItem, Start, AppGrid, AppTile, AppRow, Hud, Toast, Desktop, LockScreen, InfoCard, LayoutSwitch, WeatherView: the pieces the dock, the launcher, notifications, the desktop and the lock screen are built from. An ordinary applet has no use for them, but they are components like the rest, and the shell applets are worth reading for how they are used.

Tokens instead of numbers