What a view gives the element it stands in to do, besides drawing it: a context menu, a
toolbar shown on hover and focus, and a swipe. Each is a described component that
attaches (crate::component::Semantics::attaches): it draws nothing where the view puts
it, and belongs to the view it stands in. A list item holds those of its row
(super::ListItemProps::attached), so the list runs them for each row: the menu on a
right-click, the Menu key or a long press, the toolbar while the row is hovered or holds
focus, the swipe under the finger.
Badge widget — the non-interactive member of the chip family: a small
pill typically anchored over another element (avatar, icon, row). Three
contents:
Banner — an inline, semantic alert strip. Unlike a super::toast::Toast
(transient, auto-expiring) a banner is a persistent in-flow message the
person resolves or dismisses: “You’re offline — changes will sync when you
reconnect”, “This file has unsaved changes”, “You’re in a private window”.
BlockEditor: a stack of RichTextLine-backed blocks (paragraph, heading, lists, code,
divider) with split-on-Enter, merge-on-Backspace, arrow-key navigation and markdown-shortcut
promotion (# -> H1, etc). No demotion once a block is a heading, and promotion only fires on
an empty paragraph, matching the slash-menu convention.
The capture tool: one see-through bar to take a screenshot, record, or
float a live picture in picture of a selection, a window, the screen or
the strip.
ChangeMark: what someone else changed that the person has not seen yet
(task-legibility §3), as one pill in the changer’s colour: their face, and the task run it
was part of. Activating it shows what they did.
Time-series charts — Chart (a full line/area plot with grid lines,
axis ticks and a legend) and Sparkline (a compact, chromeless
variant for inline trend cells).
The shared multi-line code-editing widget: a retained Widget that
puts real code editing — caret, selection (shift/drag, word-wise),
clipboard, undo/redo, IME, and a multiline a11y node — on the sameTextInput core every other text field
uses. On top of that it adds a gutter with line numbers and a
current-line highlight, syntax highlighting through a pluggable
Highlighter (the widget owns rendering/caret/selection, the app
owns the language tokenizer, and every colour comes from the OS
Theme), and soft-tab / indent handling.
Event-driven: each press latches a DragTarget so a drag continues
to track the cursor even after it leaves the widget rect (see
wants_pointer_capture). All visuals pull colours from theme tokens —
no literal palette values live in this file.
What a completion drawer offers and in which order: the sources a field completes from
(ui.Completion(trigger: "@", from: …)), and the rows a typed token shows from them.
ContextMenu primitive — a right-click / long-press invoked list of
actions with optional separators. Standalone owners draw it in their
overlay pass. open_anchored opts into measured, viewport-bounded geometry;
legacy open_at callers retain their point placement and fixed rows.
A context menu over any element: right-click it, or press the Menu key
or Shift+F10 while focus is inside it, and the shared ContextMenu
opens with the commands its owner offers there and then.
Action-bound controls: the capability a widget provides when it owns an
ActionEmitter (a button, a checkbox, a custom
painted control), and the walks the host uses to reach every control in a
retained tree.
Which pointer shape a laid-out surface shows at a point: one rule for
every host (the native App, the harness the browser page drives, the
installed shell’s chrome), so a window edge, a text field or a link
reads the same everywhere.
DataTable primitive — sortable, resizable, virtualized tabular view. Sort is non-destructive:
rows stay in insertion order and an index view carries the display order, so
DataTable::sort_by_with re-applies the remembered comparator whenever local rows change,
while DataTable::from_model delegates order and paging to TableModel. Its sparse
viewport keeps memory proportional to what is shown.
Reusable drag-to-reorder interaction model — the single source of
truth for live-reflow list reordering (weather’s saved cities today;
notes, playlists, contacts next).
DragRun: a run of items — a dock’s icons, a toolbar’s tiles, a row of
cards — in which an item can be picked up and moved to another place, and
a resource from elsewhere (an app, a file, a search result) can be dropped
in.
EmptyState — the centered “there’s nothing here yet” placeholder almost every list-shaped
app hand-rolled (Inbox with no mail, a feed with no articles): one theme-driven widget for an
optional large Icon in tertiary ink (or an illustration the app paints in the same slot),
a title in the Title role, an optional one-sentence message in secondary ink s3
under it, and an optional primary action s4 under the text.
File-picker dialog widget: the system file chooser, which the shell shows for the FileChooser
portal and for an app’s path request, and any “open / save file from app menu” flow. It draws
and hit-tests itself; the host positions it as a modal sheet and drains
FilePicker::take_outcome.
The file list: a folder’s entries as the toolkit’s DataTable, with a
Name, a Size and a Modified column. It is the one list of files on the
desktop: the file manager’s folder view and the system file chooser both
show it, so a folder reads, sorts, selects and scrolls the same wherever
a person meets it.
FloatingList — the one floating option list: a Panel of rows that
scrolls, arms a row for the pointer and the keys, and places itself
beside its anchor.
Turning a flood of individual changes into a small number of things a
person can name, collapse and restore to. History surfaces show
groups, expanding to individual changes on demand.
Interactive image viewer with pan + zoom semantics, unlike the static
crate::widget::Image widget: scroll-wheel zoom, click-drag pan, and
a deterministic “fit to viewport” reset. Interaction state (zoom, pan,
drag origin) lives on the widget directly; CRDT reflection is out of scope.
ListRow: one row of a content list (a message, a contact, a request, a file, a device), as a
retained widget and as the ListRowFace immediate painter with identical geometry.
MediaTransport: what is playing and the controls that steer it, as one band of real controls —
art and song, like and lyrics, shuffle, previous, play/pause, next and repeat over the scrubber,
the queue and the volume.
The @ picker every rich-text field offers: typing @ and a few letters
lists the workspace’s people and agents under the caret, narrowed as the name
is typed, and picking one puts a mention of them in the text — one marked
run naming their participant id (Mark::Mention),
not prose that happens to start with @.
Shared content body for a text-entry ModalDialog: PromptBody
drops in as the content C while the dialog owns the backdrop, title, footer and Esc, and
the body renders an optional caption, an optional field label and a TextInput with
selection, clipboard and accessibility. The host reads the result with PromptBody::value.
What plays, painted the one way every player surface paints it: Music’s
transport and its Now Playing page, the shell’s Quick Settings card, the
lock screen and the desk.
Compact, theme-aware page preview for print queues, scan flows, file
inspectors, and document pickers. It communicates page shape and progress
without pretending to rasterize content that is not available.
PageSidebar — a shared, reorderable page/slide preview rail: the PDF
reader’s page rail and the presentation editor’s slide rail both drive
this one widget. It owns the list geometry, scroll, drag-to-reorder
(via DragController), a right-click menu, and an optional “add”
affordance, emitting PageSidebarEvents the host applies to its model.
The stock pictures a super::PictureChoice shows: what a visual
setting looks like, drawn by the toolkit from the live theme, so an app
names the picture a value stands for and never paints one itself.
PictureChoice: a choice among pictures, for a setting whose meaning is
visual (a text size, a pointer size, a colour filter). Each option is a
tile showing its Picture over its name; the chosen tile carries the
selected edge.
The one widget shell every chart kind shares: layout, title, hover,
keyboard and touch inspection, activation, the legend toggles and the
accessibility tree. A chart kind only supplies its marks — geometry, hit
testing and painting — through PlotMarks; its builder name is an
alias of Plot over those marks (Heatmap is Plot<HeatmapMarks>).
The design system’s primitives (docs/design-language.md, “Primitives”): the only way to build
these things. Each owns its padding, radius, colour and motion; callers pass content, never
geometry or colour.
ProgramStepView: one step of an agent’s task as everyone who follows it sees it
(docs/designs/app-language/agent-ux.md, “Working shows work”): the tilolang program the
agent ran, read-only and coloured in a raised well; what it answered, line by line, with the
resource each line names as a reference chip that opens it; what it changed, as rows that
undo; and what it proposes, as cards the person confirms or declines.
PropertyList: labelled values (a contact’s details, a file’s metadata,
a certificate’s fields), as a retained widget and as the
PropertyListFace immediate painter with identical geometry.
QuickTile — a Quick Settings control. Its glyph, name and state line sit on a tile filled
with the on colour while the control is on, and a press anywhere on it switches the control.
The name takes one line and the state line up to two, broken after a word and elided only
past that. A tile whose control has a section of its own (the networks under Wi-Fi) gives it a
chevron half, set apart by a hairline, that turns as the section opens.
A single editable line of text wrapping a local-mode TextInput, the
leaf cell of a block editor. The inner TextInput handles cursor
placement, selection, IME, copy/paste; RichTextLine adds:
Shared scrollbar interaction model — the single source of truth for
thumb geometry, thumb dragging, and track paging used by every
scroll-capable widget in the toolkit (Scrollable, DataTable,
DocumentViewport).
SearchField — the in-content filter: a field with a leading magnifier,
an editable TextInput, a trailing clear button and a reserved slot for
the match count.
The one password prompt: every secret Tilo asks for — a Wi-Fi passphrase, a polkit password, a
VPN login, an unlock, a SIM PIN — is asked by this component, drawn the same by the shell and by
apps.
Selection handles for a canvas: the frame around what is selected, its
resize handles at the corners and (once the frame is big enough on
screen, or always with SelectionHandles::with_edges) at the middle of
each edge, and its rotation handle above
(unless SelectionHandles::without_rotation: a crop, a text box, a clip),
drawn in your colour and hit-tested at a constant size on screen whatever
the zoom.
SlashMenu — the popover / opens inside a
BlockEditor block: a
FilterMenu over every block kind the editor makes, plus the commands
its host answers (a picture, a link to another page, a page inside this
one). Filtering matches keywords as well as labels, so /h2 finds
“Heading 2”; each row shows the Markdown that makes the same block.
Inline completion in a text field: :shortcode offers the catalogue’s
emoji and @name offers the workspace’s people and agents, in the one list
beside the caret.
How much a time grid (a calendar’s week, a schedule) shows of each item,
decided from the width of one day column and the theme’s type, so every
app that lays out days in columns follows one rule.
ToggleGroup — the segmented control: a strip of segments of which one is chosen (or, before
the person has chosen, none). Clicking a segment chooses it and fires on_change with the new
index.
The toolbar: a measured strip of commands with a shared ContextMenu
for overflow, so every command stays reachable however narrow the window.
The extent cache is the sole source for intrinsic sizing, fitting and placement.
Pointer intent for chrome that hides along a window’s top edge until the person reaches for
it: the decorations of a maximized window (its title, Full screen, Restore and close) and,
in a Tilo app that puts its header there, the app’s header row with them as one bar.
TransportFace: the previous, play/pause and next controls of a media
player, for a painted host that owns its hit-testing (a music bar, a
video’s controls).
A window standing on a desktop, as a described component: what a shell draws for a place on a
floating desk (shell.md §4, frame_classic) and for a strip of places (strips_view),
which is the same thing.
One bounded page from a widget-owned remote root catalogue. next_cursor
is meaningful only while exhausted is false and is never interpreted by
a different widget or document revision.
A reusable action-intent queue for controls, including custom widgets.
Widgets call emit from any interaction path. Mounted shared
controls install independent host custody; custom producers should use
new_in with their actual owner domain. The private take
path remains only as explicitly unqualified migration compatibility.
A proposal on screen: its title, the model’s note, the change as a diff
(or a value’s before and after), which model answered and where it ran,
exactly what is sent, and Accept and Reject.
Standard actions in declaration/focus order: secondaries, then primary.
Unspecified buttons use measured content sizing; explicit sizes remain manual.
Each wrapped line aligns to the trailing edge.
The history of a document, grouped: runs of typing fold into one band that opens to its
changes, each day’s changes sit under the day’s heading, and a change’s menu offers
reverting it.
A command palette entry contributed by an app. Invoked with a mutable
CRDT handle and the app’s root ObjId so the command can mutate state
directly (matching quick-ui’s direct-mutation event model).
A breakpoint or pane width authored at 1× for a painted app’s
crate::widget::SidebarDrawer, resolved against the theme once when
the tree is built. NavShell reads its widths from the metrics and
applies the same rule to them.
A field that suggests completions under it as it is typed into: a search over a site’s
catalogue, a mention, a command. The suggestions are what the view gives it; a chosen one
fills the field and is reported.
A small pill on another element: how many new things there are, a dot for something new, a
short status (“Owner”, “Beta”), or the mark of unsaved changes. It is never pressed.
What an immediate-mode Banner::paint shows: severity, leading icon,
title, optional message, up to two actions and whether it offers a
dismiss control.
A message that stays in the page until it is resolved or dismissed: “You’re offline”, “This
file changed on disk”, “Storage is almost full”. Its kind decides its glyph and colour; it
carries a title, a message under it, up to two actions inside its box, and a dismiss button.
It opens and closes in place, what follows moving with its edge.
One bar control that stands for people: their faces, a label and a press. A chip with faces
opens who is here, an invite opens the host’s own invite flow; a press reaches the view’s
press event, which is the same action the palette, scripts and agents invoke.
The idle fade of an overlay scroll bar: fully visible for a moment after
scrolling, then fading out, unless something holds it (the pointer near
the bar, a drag, keyboard focus, reduced motion, an always-visible bar).
One timer for Scrollable and painted super::ScrollRegions, so every
bar in the system appears and fades alike.
A labelled level as a bar: a disk’s use, a quota, a battery. Its label stands over the
track’s start and its readout over its end; the fill turns warning, then danger, as it
fills, unless the share has no status.
A document: its paragraphs with their formatting, and each reference in it as the reader’s
own inline view of what it refers to (a person with their name, a channel, a task with its
number), resolved under their permissions. Bound to a document’s field it edits it, each
edit written back as the value now reads and a change from elsewhere shown when the person
is not typing there; given a value it shows that, read-only, and activating a reference
opens it.
One card of a lane: a summary of the resource it stands for, which a press opens. The card is
its body: a row given as its body is shown as a card — the row paints the surface, wraps its
title and stands its facts under it — so what the card says is written once, and the row is
what assistive technology reads as the lane’s item. The card itself is the container around
it, with no role of its own.
Cards in lanes, side by side: a kanban board, a pipeline, tasks by status. Dragging a card
to another place in its lane or into another lane is reported by the card or lane it lands
at; each card also opens, and offers its commands on its context menu, so nothing needs a
drag.
Where a page is, as the path to it: each place it is in, a chevron between them, the page
itself last. Pressing a place goes there. Where the path does not fit, its middle gives way
first, the first place and the page itself staying.
An immediate-mode button: the Button look for a canvas host that owns
its own hit-testing. Built fluently:
ButtonFace::new(rect, "Save").role(ButtonRole::Primary).hovered(hit).
A button: pressing it does one thing. Its role says what kind of thing, which decides its
whole look: the window’s one primary action, a destructive one, or an ordinary one.
A face painted at logical coordinates and appended, translated, on later
frames while the widget keeps its size: a widget that only moves (a
scrolled row, a reflowed toolbar) costs no shaping or encoding.
A live window the capture tool can take, whether or not it is on this
output now. virtual_rect is its place in Tilo’s continuous desktop;
visible_rect is the part of it on this output.
Reflows its cards into equal, aligned columns by width. Each row is as
tall as its tallest card; cards share the row’s height so their footers
line up, and a row of short cards stays short.
Cards in equal, aligned columns: the apps of a store, the devices of a network, the
paragraphs of a review. Each card is a resource, and pressing one opens it.
What someone else changed of a resource that the person looking has not seen yet: who, in
which task run, and whether they made, changed or removed it. The host fills all but of
from the resource’s versions; activating it shows what they did.
A box that is marked or not, bound to what it edits (whether to be told of a reply, which
rows a bulk action takes). A labelled box is one target, its label included.
A compact pill for a tag, a filter or a token: what a note is tagged with, a recipient, an
applied filter. Pressing it opens or applies what it names; a chip that can be taken away
has a trailing remove button; a filter chip shows whether it is on.
Wraps the multiline TextInput core and enables its gutter +
syntax-highlight path, so all caret/selection/clipboard/undo/IME/a11y
behaviour is the one shared implementation.
Code to read or write, with line numbers and its language’s colouring. What is typed edits
the text it is bound to, each edit spliced in, never written over.
A colour, picked from a saturation and value field, a hue strip, the red, green and blue
sliders, or a hex field; a palette of quick picks sits under them when given.
A grid of swatches, one chosen (a palette of accents): the chosen cell carries the ring.
Each swatch is a colour by its hex text, shown in the theme’s own samples.
A widget’s composition: the element tree it rebuilds at every layout, or
keeps across layouts until it is invalidated (Composed::build_layout_kept), and
lays out as the only child of its own node, plus the box it was given and
whether the owner asked for a rebuild. The owning widget forwards its tree
methods here.
Each bool below is an independent builder toggle (background, height
fill, padding, grow behaviour) set at construction time, not a state
machine with meaningful combinations to enumerate — a bitflags/enum
refactor would ripple across every one of Container’s call sites in
the crate for no behavioural gain.
A context menu of the view it stands in: a right-click, the Menu key or a long press opens
it. Its commands come first, as the view placed them; the system adds what the item offers
that the view did not place and a typing field to filter them. A destructive command runs
at once and is undone afterwards, never confirmed first.
A selectable row of a short list whose items carry real controls (a
layers panel with each layer’s thumbnail, name and switches; a list of
versions with a restore button): a crate::widget::Row of widgets
standing in the list row’s selection lift.
A selectable row of a short list whose items carry their own controls (a layers panel, each
layer’s name beside its switches): a press none of its controls took chooses the row, and the
chosen row is lifted off the ground it stands on.
A conversation, drawn as every conversation is drawn: each line on its own side, runs of one
person’s consecutive messages under their name once, a divider where the day changes, and the
time and the delivery state under your own.
Payload published when a tab drag ends outside the row’s band; the shell hit-tests the release
against other strips and delivers it or returns it to source. The source group is already
detached.
A table of resources as columns and rows: the attributes of a device, the songs in a
library, the rules of a firewall. Each row is the resource it stands for and says what its
columns read in it; pressing a header sorts by that column, and selecting or activating a
row reports the row’s resource.
The app’s side of a DatePicker that stands outside the app’s own
surface (a calendar’s month navigator in the shell’s sidebar): the app
shows its day with Self::show and takes the days the person chose
with Self::take_chosen. The app’s day stays the one truth; the
picker reads the feed at every sync and update (DatePicker::fed_by).
A day, shown as the person reads a day (with the time it is due at) and picked from a
calendar that opens over it. A date that may be empty can be cleared, and the time it is due
at is picked in the same popover, in the time slot.
A modern chronological scrollbar face plus its ephemeral interaction
state. It intentionally has no document binding: scroll position and
density are per-user presentation preferences, not shared collection data.
A region of a window laid out and drawn at another density
(crate::tokens::Density): a data-heavy sidebar or list at compact
while the rest of the window stays comfortable. Rows, rhythm and tables
inside it take the region’s density; controls and text keep their size.
Content a view builds only while it is open (a tile’s details under
it, a row’s section), standing in a column as a band
(crate::widget::Disclosing::Band).
Content a view shows only while something is open (a tile’s details under it, a row’s
section), standing in a column. When the view starts showing it, it unrolls from its top
while what follows moves down with its edge; when the view stops, it rolls up. Under reduced
motion it lands at once.
Rows that keep one open at a time. Clone it into every row of the group;
a view that rebuilds its rows keeps the group and keys the rows
(DisclosureRow::keyed).
A row whose body opens in place under it: a device’s details, a run’s log, a setting’s
options. Its chevron turns as it opens, and what follows moves down with it. A press on the
row, Enter or Space opens and closes it.
Whether a disclosure row is open, its reveal and its body’s open height:
what outlives the row when the view that owns it rebuilds it. Clones
share one state.
Content that fills its column above a bar that stays at the column’s foot: a
conversation above its composer. The bar stands in the column’s page, a section’s gap under
the content and the page’s gutter at its sides and below.
The composing viewport widget: wraps content (a child widget or a draw
closure), owns the zoom/pan input, and paints scrollbars on top. See the
module docs for when to prefer the standalone ViewportState kernel
instead.
Shapes drawn with the design system over a box of their own: a ring, a gauge, a small
chart, a diagram. Colours are theme roles and widths tokens; a press reports which shape.
Where files go: drag them here, or press the button to choose them (an import, a picture to
swap, a file to open). At rest it is a dashed edge around a glyph and a title; while a drag
hovers it takes your colour.
An immediate-mode dropdown: the closed Dropdown look for a painted
host (a camera’s controls, a reader’s settings) that owns its own
hit-testing. Pair it with an option crate::widget::Popover
(Popover::new().with_items(..), opened with
open_at(face.field_rect(theme), Some(selected))) for the list.
One of a short list, chosen from a field that opens the list: a project, a sort order, a
unit. The chosen one shows in the field; the list filters as it is typed into.
Reaching for something that waits at a display’s edge (a desk widget’s
quiet form): the same transit-versus-aim reading as HoverIntent,
for targets that are not under the pointer yet.
A name that is typed over where it stands: a document’s title, a tab’s name, a list item’s.
Reading, it is text; pressed, it is a field whose Enter or click away commits the edit and
whose Escape keeps the name it had.
The document as a host lends it to one pass that may change it: read
freely, changed only through a typed action the action host applies (a
resource’s dispatcher applies it), so every change is an action that is
attributed, recorded in history and undone like any other.
Direct CRDT mutation is rejected at the widget boundary:
Separate facts in one row, each an optional glyph and its text, with space between them and
no separator glyph: “12 files”, “3 MB”, “Edited today” are three facts. Where the row is too
narrow, the facts that matter least give way first.
One visible label and what it labels: a standard control (which takes
the label as its accessible name, so it is read once), a custom element,
or nothing for a control row. Help copy reads under the label while the
label stands beside the control, and under the control once stacked;
validation copy always stays with the control.
Content with a filter: a SearchField::filter in a band above the
content, narrowing the first Filterable inside it. Ctrl+F (⌘F)
focuses the field. A navigation shell’s filter slot is the same field
wired with sync_filter.
What a document’s find offers beyond matching text under Match case and
Whole word: replacing matches, a regular expression, a byte view’s hex
digits. The find’s options offer just these.
What a find over one Findable has found: how many matches, which is
current, and the query and content they were found for. The FindBar
keeps one, and so does the window bar’s search
(crate::widget::WindowSearch): one engine, whatever draws the field.
A floating list of rows under (or, without room, above) an anchor: the
one menu list behind crate::widget::Autocomplete, a code editor’s
caret completion, the filter and slash menus, a dropdown’s open list and
every context menu.
A form under its title, on a page: the title in LargeTitle (or none,
FormPage::untitled) with an optional header action, an optional
description, then the form, on the readable column aligned to the
leading edge, scrolling vertically, with optional pinned actions.
with_max_content_width(None) resets only the readable-width override.
Fraction thresholds (inclusive lower bounds) at which a gauge switches
from success → warning → danger. The default mirrors the dashboard
convention: >= 0.85 danger, >= 0.6 warning, else success.
Domain-free canvas. Supplied controls retain their framework action bindings.
The canvas paints only connections; applications own typed graph resources.
One column’s header row as the shell laid it out: what its title says against what the row
gave it, and what its actions kept of their labels and their place in the row.
The window’s sync status in a header row: quiet text, right-aligned
against the row’s trailing controls, announced politely when it changes.
A header row keeps one, paints it into the room its own layout leaves
(Self::paint) and lists it among its children for assistive
technology.
An author that acted for someone: an agent’s change is the agent’s, on
behalf of its person, in every history (an app’s, the Files history, and
what the history actions return).
Not crypto material — just enough metadata to render a per-author
colour dot, display name, and a short identity hash for
disambiguation when two authors share a name.
One entry of a history as people read it. Opaque: only ever compared
for equality (revert/restore callbacks pass it back to the caller). The
caller picks the byte layout — UUID-v4 today, a content hash later.
Empty fields are “match everything” so a freshly-constructed filter
behaves like no filter at all. The chrome owns the filter (not the
widget) so the host can persist it across remounts, e.g. a workspace
switch, without poking at widget internals.
The window’s History control in a painted header row: what the host
offered, the pointer’s hover over it, and a press waiting to go through
the History door. Modelled on crate::search::SearchOpener: return
Self::take from ActionControls::take_control_invocation.
Controls shown over the trailing edge of the view they stand in while it is hovered or
holds focus: quick reactions, Reply. Tab reaches them from the view.
One glyph from the icon set, in the theme’s ink: a kind of thing beside its name, a status
mark. It says nothing to assistive technology, so the words beside it carry the meaning.
A picture with a crop its four corners set (a scanned page, a photo to trim): drag a corner
to move it, or an edge’s arrow keys, and it reports the crop each time it changes. The
picture is letterboxed in its box; the crop is a share of the picture, never of the box.
A picture: artwork, a photo, a cover. Its bytes are read from its address as it arrives; a
picture that is not here yet keeps its place, and one whose bytes cannot be read shows the
error mark, never nothing.
A picture to look at closely: scroll to zoom at the pointer, drag to pan, and a reset to the
whole picture. It fills its box; the picture is letterboxed inside it.
Shared vector controller/Joy-Con silhouette used in device pickers and
shortcut help. It intentionally uses theme strokes instead of bundled
vendor artwork, so it stays crisp at every scale and in high contrast.
The keys of a shortcut as drawn keycaps, in the person’s own keyboard legends (“Strg” on a
German keyboard, the Command key on a Mac), beside the command it runs. Never a typed string.
Where the inspector stands this frame, in the window’s coordinates: the
one frame a retained inspector is laid out in and a painted one draws
its body into, docked beside the content or, in a window too narrow to
dock it, as the sheet up from the window’s foot
(NavShell::inspector_frame, InspectorLink::frame).
A handle on the shell’s inspector for an app painting inside it, as
super::WindowBarLink is for the bar’s slots: what
NavShell::inspector_frame last laid out, and requests the shell runs
at its next sync or update.
A retained strip of key hints: a chord’s drawn keycaps on a row’s
trailing edge (a shortcut that cannot be changed), or several chords
side by side, a sibling gap apart. Never a joined string.
Shortcuts and what they do, side by side: each hint the drawn keycaps of a chord and its
label (“Enter Save”, “Esc Cancel”), in the person’s own keyboard legends. Never a sentence
with a separator glyph.
Private, process-local physical press state shared across page recomposition.
It contains no entered text or logical input history and never edits a document.
One logical line’s highlight result: ordered, non-overlapping Spans
(gaps render in the default text colour) plus the HlState the next
line begins with.
A hyperlink: primary ink with an underline, opening what it names when pressed, activated by
Enter or Space, or from assistive technology. A link that names a resource opens it; one
whose view gives it an activate acts.
Immediate-mode list row. Build one per row per frame, measure it for
its height, then paint it into the rect you laid out: the row’s outer
rect, the list’s content edge grown by row_bleed on both sides.
A row of a list: what an item is, in one line, with the start of its content under it and a
quiet fact on its trailing edge. Pressing it activates it: a list opens what it shows.
A manual region whose children keep their standard rendering and interaction.
The policy measures children, places every child, and returns its desired size.
It can run repeatedly before painting and must not change child topology.
Rectangles are relative to this region, represented by Taffy’s logical f32.
Safe child-indexed measurement/placement services supplied by the host.
Measurements solve current retained topology; they never apply geometry or
rebuild widgets. Actual placement participates in the normal host settlement.
Explicit invalidation for inputs captured by a retained Manual policy.
After changing an input, call Self::invalidate and schedule a normal
host layout frame. This handle does not schedule a window redraw itself.
Cards in a grid: a library, an album’s covers, a shelf of books, a set of channels. The cards
reflow into as many columns as fit, every row’s text as tall as its tallest so titles line up;
justified, they make rows of photos that span the width at each picture’s own shape.
What is playing and the controls that steer it, as one band: the art and the song, like and
lyrics, shuffle, previous, play/pause, next and repeat over the scrubber, the queue and the
volume. It stands across the window’s foot, under every column.
A button that opens a menu anchored to its own rect
(crate::widget::Button::with_menu): a header’s More button, a
toolbar’s sort menu. The menu opens under the button, lines up with
whichever of its edges keeps it in the window, and flips above near the
bottom; Enter, Space or a click opens it, and the button reads as
expanded while it is open.
A modal dialog: a title, any content widget, and up to three footer
actions, over a scrim that covers the window. Generic over the content
type so callers pass any Widget without boxing.
A question over the window: a dimmed page, a sheet with a title, the view’s content, and up
to three answers. Escape or a click on the scrim closes it; Enter fires the main answer,
except in a destructive question, where Enter is the safe one.
The immediate-mode sheet for a painted host that keeps its own state (a question
with three answers, a confirmation over a canvas): it lays the sheet out, paints it
with hover, press and keyboard focus on its actions, keeps that layout for
hit-testing and turns input into a SheetResponse; the host paints only its body.
The one window shell: a sidebar of places, an overview list, the content and an inspector,
side by side while they fit and one at a time, with Back, when they do not. The header of
each column holds its title, its count and its actions.
Immediate-mode number stepper: − value +, the face of a
NumberInput. Inline (the default) it is the toolbar stepper of
NumberInput::compact, bare steppers either side of the value;
Self::framed gives the secondary steppers of the framed control,
whose value the host’s field draws.
The head of a detail view: an avatar or an icon, the object’s name in
Title and one Caption line under it, rhythm.tight apart, on the
content edge (“Ada Lovelace / [email protected]”, a password’s site).
The head of a detail view: an avatar or a glyph, the thing’s name as a title and one
caption line under it, “Ada Lovelace” over “[email protected]”, a password’s site over its
address.
A vertical overlay scroll bar. The host keeps its own offset and gives
the bar the area it scrolls (Self::track) and its ScrollMetrics
each time; the bar keeps the drag, the hover and the idle fade, and the
theme’s sizes and motion policy as last given (Self::set_theme).
A find a view ran on its own rather than through the window’s search: an
action went to a match of query (an agent’s “go to result”). The
window’s search shows it: its field holds the query, and it steps on from
match current.
A page of sections: optional head items (a summary, a filter), then
sections spaced rhythm.group apart, on a readable column aligned to
the leading edge of the column it fills, scrolling vertically. It has
no title of its own: the shell’s header titles the page. Actions that
must stay reachable while it scrolls are pinned under it with
Page::with_pinned_actions.
A page’s shape in a print queue, a scan or a document picker: a sheet of paper with the
lines a page holds, and “Page n of m” under it. It shows the shape and the progress, never
the content, which it does not have.
A rail down a document’s side: one numbered thumbnail per page, the page open lifted, and,
unless read-only, pages that can be dragged to reorder, copied, moved and added.
One page of a stack, in the place a view shows it, with the page it replaced leaving while
the view swaps the two: a panel that opens a deeper page of its own, and Back that slides it
away again.
The pressable targets of a widget that paints its own content (a
calculator’s keys, a map’s markers, a timeline’s clips): the same hover,
press, focus and activation the retained controls have, for rects the
host lays out itself.
Horizontal pan of one run of groups (the whole row, or one lane): canvas-x is the unscrolled
coordinate, scroll_x how far it is panned past the viewport’s edge.
One remote participant’s live presence (caret/selection), published by a
multi-participant widget under that participant’s identity. Same key and
payload shape as the local window’s own presence (Writer: wp_block key,
byte offsets into the caret block).
A form’s person: who is doing it, shown as their avatar and name, and picked from the
workspace’s members and agents. “Me” picks the person the view is shown to, “No one” clears
it.
A choice among pictures whose meaning is visual: a text size, a pointer size, a colour
filter. Each tile shows its picture over its name, and the chosen tile carries the
selection edge.
Where a band stands in its container, as the container a rebuild makes
in its place can recognise it: the container (its kind, its width and
the kinds of the other widgets in it, in order), how many of those come
before the band, and the space the container keeps above it.
A button that opens a popover anchored to its own rect
(crate::widget::Button::with_popover): a filter’s options, a share
sheet’s details. A click, Enter or Space opens it and closes it again;
the button reads as expanded while it is open.
The body of a prompt popover (Popover::prompt): a caption, one
field and a hint under it. Enter submits what was typed; Escape closes
the popover without it.
Where the previews of a tree on this thread report, shared with the host that hands the
compositor each window’s live picture there: the same handle, so a preview that moves moves
its picture.
How far something is: a transfer, an import, a sync. Without a value it is under way with no
known end, a segment sliding across the track. A measured level (a disk, a quota) turns
warning and then danger as it fills.
How full something is, as a ring: a countdown, a download, the one hero reading of a screen
(a speed test). A regular or large ring holds its readout and what it measures.
A label column shared by several property lists, so their values line
up (the lists of one Section share one on
their own). Clone the handle into each list with
PropertyList::shared_column.
A read-only value as a control: the value a Field
shows where it cannot be edited (an account id, a generated key), in
primary ink with its kind’s text treatment and an optional trailing copy
action. Unbreakable kinds are elided before the action.
Holds the source bytes plus the cached encoded matrix. Re-encodes when
the payload changes via set_payload — the pairing-channel screen
calls it every few seconds as the broker rotates the nonce.
A message quoted where another answers it, or in the reply banner over the composer: a rule
at its leading edge, who wrote it and the start of what it says. With dismiss it has a
close button (the banner: “stop replying”).
One strip’s pills and how they move: what a host keeps per strip it
paints (a message’s reactions), so a reaction arriving appears and a
count changing cross-fades.
The reactions on something: a pill per emoji with how many reacted, yours drawn on;
pressing one adds or takes back your reaction, and the add button opens the emoji picker for
another. Each reports the emoji (on toggle(e)).
Optional on HistoryEntry — when present, the widget renders the
row with the struck-through summary, suppresses the [Revert] chip,
and exposes the redactor + reason on hover.
A field to type rich text into, bound to the rich text it edits: each reference a
completion picks is written as a reference, which every reader sees as their own inline
view of what it names.
One line of text, edited in place: a block editor’s cell, a composer’s message. It carries
its text and its inline marks, and reports the keys that would carry the edit out of the
line itself (Enter, Shift+Enter, Backspace at the start), so a host composing several lines
can split or join them.
A fixed-capacity rolling window of samples — the store behind a live,
streaming chart or sparkline. Once full, every push drops
the oldest sample, so as_slice always reads oldest →
newest and can be handed straight to Series or Sparkline::paint.
What a list tells its row delegate about the row it builds, besides the model and the
row’s place in it: the row’s selection, and whether it stands open into its item.
The grid a list row lays its content out on, as the row paints it: where its title starts and
ends, where the facts column stands and how wide the room for it is, and whether the title was
cut short.
A row’s selection with its neighbours’, for a delegate that paints its
own selection: a run of selected rows is one lift
(crate::chrome::RowJoin), with no rule between rows.
A seek bar held by the pointer or a finger, for a surface that paints
its own controls and routes its own input (the shell’s cards). The host
hands in the face it paints, so the press, the drag and the paint read
one geometry.
The find engine behind a window’s search, run where the app’s widgets
are: by the window for an app in its process, by the app’s own runtime
for an app in a process of its own. It finds or narrows when the query
changed, follows the content when it changed under the search, steps, and
stops when the search closed.
The results overlay. Populate it with set_groups each
time the query changes, drive selection with the keyboard or pointer, and
drain activations with take_activated.
An immediate-mode section header for a painted host, with the retained
SectionHeader’s geometry: the title on the content edge, the count
after it, the action’s label on the trailing edge, one fixed height.
The retained control and painted strips share one touch recognizer.
Only a completed single-finger gesture chooses; cancellation, a second
finger, a removed strip or an externally changed selection refuses it.
One labelled data series. data is sampled left-to-right across the
plot; color is the line/area tint; legend is the label shown in the
chart’s legend strip (empty string = omit from the legend).
Whose a window is that someone else shared with the workspace, as the
bar of the window it opens here says while the window is in front: their
name, “Ana’s window”, with their face.
Who can see a window its person shared with a workspace where each
person lays out their own windows: the workspace, by name, and the people
in it now, as the window’s bar says while the window is in front.
What the sheet stands in: area reaches from the highest the sheet may
rise to the window’s foot; peek is how much of what it holds shows
while it peeks; grip is the grip’s height; least_half is the least
a half-height sheet must hold (the panel’s width where it docks): in a
window too short for that, half height is the whole height, so what it
holds keeps the room it needs.
The change a retained row shows, as ListRow::shown_change reads it: who made it, what
they are called, what they did (the sentence under the title), and what assistive
technology hears of it.
How strong a radio signal is (a Wi-Fi network, a mobile network), as four bars of rising
height, one icon square in size. It names itself by its level: “Strong signal”.
The shape of content still on its way, drawn where it will stand and at its size, so nothing
moves when it arrives. It never shimmers, and it says “Loading” to assistive technology.
The frames a host skipped because their layout failed, and when it last
said so. Every host (native, headless, the browser) skips such a frame
and keeps showing the last one, so input still lands and the next frame
lays out again. A layout that keeps failing would fail on every frame,
so the first failure is reported in full and later ones at most once a
minute, with how many frames were skipped since.
A value along a track: a level, a volume, a share. Dragging the knob or pressing the track
sets it, and the arrow keys step it; Shift drags finely. It reads its own value when said.
One finger on a slider, read as the pointer held down: the value jumps to
where the finger lands, follows it while it moves (on or off the track)
and settles where it lifts. Every Tilo slider reads touch through this,
the Slider widget and the shell’s own drawn sliders alike, so a finger
works wherever a mouse does.
Compact, chromeless trend line — no axis, grid, title or legend. Just
the area fill + line, sized to fill its rect. Drop one into a table cell
or a stat card to show a recent trend.
Something under way whose length is not known: four dots turning. It holds still under
reduced motion. Where the share done is known, a progress bar or ring says how far it is.
The divider between two panes: hit-testing, hover, dragging, keyboard
steps, painting and its accessible separator node. ResizableSplit
keeps one; a host that paints its panes itself (a query editor over its
results, a source beside its preview) keeps one too, sets its rect each
layout and lays its panes out in SplitHandle::pane_rects.
The share of a two-pane split the first pane takes, clamped to bounds
so neither pane collapses. One model for ResizableSplit and for
painted hosts (SplitHandle).
Children painted on top of one another, each position: Absolute and
anchored at the stack’s top-left. There is deliberately no alignment
option: a child that wants a corner or the centre positions itself (a
Column/Row with its own insets and justify, or a Container with
with_centered_max_width), so the stack stays a pure z-order primitive
and the layer’s geometry is owned by the layer. If a caller needs the
stack itself to anchor, add an opt-in that maps to inset on the child
node rather than changing this default.
A set of stat tiles that reflows by width: all in one row when they fit,
then half per row (a 2×2 for four), then one per row. Tiles are separated
by space, never boxed.
A set of stat tiles that reflows by width: all in one row when they fit, then half per row
(a 2 by 2 for four), then one per row. The tiles are separated by space, never boxed.
One number and what it measures, on the content ground: a dashboard’s reading, a backup’s
size. A tile reads top to bottom: its label, the value with its unit, a note, which way it
moved, and a sparkline of its recent readings. A tile that opens a detail is pressed.
A non-interactive status: a RowStatus dot and a Caption sentence on
the content edge (“Engine running”, “3 containers stopped”), for a list’s
footer or a detail’s state.
A status in a sentence: a dot in the status’s colour and a caption beside it, “Engine
running”, “3 containers stopped”. For a list’s footer or a detail’s state; it is never
pressed.
Where a person is in a short sequence: a setup wizard’s steps, an import’s. Each step is a
station with a disc and its name; a done one carries a check and may be gone back to. Too
narrow for its stations, it reads “Step 2 of 4” over the current step.
One display’s share of a strip partitioned across displays: each holds its own groups, laid out
and clipped inside its lane only, so none straddles a seam and panning one never reveals
another’s.
A retained surface of one level around one child, padded by the
level’s rhythm. A Surface inside a surface of the same level paints
no ground of its own.
What swiping the view it stands in across does: it follows the finger, uncovers the
command and runs it when let go past the threshold, or springs back.
Whoever opened a tab on a shared desktop, when it is not this desktop’s person and they may not
rearrange it: no close, a drag that springs back, and hovering names them.
A selected-text command requested from a field’s context menu. The host can
execute this asynchronously (translate, rewrite, explain, grammar review)
without putting model or network work in the widget’s input path.
A text action’s result for the range it was requested for. It applies
only while the range still holds original: the field may have been
edited, by the person or a collaborator, while the action ran.
A block of wrapped text in one style, starting at its rect’s leading top
corner and wrapping to the rect’s width: a reader’s body, a page’s
paragraph, a note’s prose. The shared way to paint running text on a
surface a host owns; the host never draws it run by run.
The grips of a text selection on a touchscreen: at its start a stem
down the first selected line’s leading edge with a knob above it, at
its end a stem down the last line’s trailing edge with a knob below,
in the selection’s accent. A finger drags either end; the knobs are hit
at a constant target on screen whatever the zoom.
A field to type text into, bound to the text it edits. Each edit is spliced into that text,
never written over it, so people typing in the same text at once all keep what they typed.
One line of words in a role, measured and centred on a point or aligned
in a box: the bar’s clock reading, a live activity’s headline, an
overlay’s timer. It is the shared way to put a single string on a
surface; a host never draws a bare text run of its own.
A title over a secondary line, with an optional third line under it, in fixed roles and at
fixed gaps: a file’s name over its folder, a person over their role. Each line is one line,
cut short with an ellipsis; two facts never share a line.
The time of day a day is due at: the hour and the minute it is due at, with “Remove time”
beside them, or a quiet “Add time” while it has none. It stands in the time slot of a
DateField, so the day and its time read as one fact.
A time of day, as three spinners for hours, minutes and seconds: the arrows step a spinner
and so does the wheel over its cell. It is the time in the person’s own zone today.
A moment shown as how long ago it was, or how far ahead: 2 min ago, Yesterday, in 3 min, in the person’s language and time zone. It changes when what it says does, and wakes
the window for nothing else.
A small set of choices, one of which is made: an alignment, a density, a unit. The chosen
one is a thumb lifted off the track. What switches what a window shows is ViewTabs.
A switch: the same two states as a checkbox, for a setting that takes effect at once rather
than when a form is sent. Its knob slides to the side it turns to.
A strip of commands: plain buttons in a row, groups split by hairlines, toggles that stand
lifted while on. However narrow the window, every command stays reachable: those that do not
fit go to a More menu at the end, the least important first.
One controller owned by crate::app::App — not one tooltip widget per
control — is what makes tooltips work for every widget exposing
Widget::tooltip with zero per-app
wiring, and guarantees at most one chip on screen. Timing is wall-clock
through an injected now: Instant, so it’s unit-testable.
One annotation along a scroll track: where a search hit, a change or a
diagnostic sits in the content, painted as a short mark across the
track so the person sees where to scroll.
What each of a band’s controls does, as a view gives them: the band reports what the person
pressed, and the view’s action does the rest. A control the view gives None is left out.
What a tree list works out of its rows, for the rows it builds: how deep each stands, which
of them are folded away, which have subtasks, and which stand under the row they follow. The
list fills it as it mounts rows; a row’s builder reads it, and the person’s folding stays
with the list, so a row folded away stays folded while its neighbours come and go.
A tree of nodes: a file explorer, a project’s files, the layers of a drawing, a book’s
pages. Each node is the resource it stands for; opening a branch shows the nodes under it,
and selecting or activating a node reports its resource.
The divider as a widget, for a list built of widgets: a band across its column with its
label at the trailing end, over the first line the reader had not read.
A video with its playback controls over it: play/pause, the scrubber, the volume, mute and
fullscreen. The app’s player is the one truth; what the person does reaches the view as its
events.
Tabs that switch what a window’s content shows: a request’s Params, Headers and Body, a
container’s Logs and Stats. Assistive technology meets them as a tab list whose chosen tab
is selected, not checked.
The pure zoom/pan state kernel. Owns the zoom factor and the scroll
offsets, derives the content↔screen transform, and reduces input events
(wheel, drag, arrow keys) into new state. Render-agnostic and cheap to
clone — a host stores one of these and drives it from its own event +
draw paths. See the module docs for the two usage shapes.
A long list of rows that costs only the rows on screen: each is built when it scrolls into
view. Selection follows the person’s choice and is reported with the item it shows; the list
is one focus stop.
A page, live: a browser’s content, a help document, a web app embedded in a view. Its
address bar, navigation and permission prompts belong to its host: this is the page alone,
and the app reports what the page navigated to as its events.
Where the wells of a tree on this thread report, shared with the window policy that places
the windows they stand for: the same handle, so a well that moves moves its window.
Turns fractional-detent scroll deltas into whole steps. No quiet-time
decay: it would stop slow scrolling from ever accumulating a whole
detent, and a stale sub-detent balance is harmless since it clears the
next time the user reverses direction.
A child shown only while a condition holds. While it does not, the
child is out of its container’s flow: no box, no gap around it, no
paint, no focus and no accessibility node. The condition is read on
every synchronization, so state that changes it (a LocalState, the
document) shows or hides the child on the next frame; the child keeps
its own state while hidden.
The shell’s own buttons in the window’s bar, for an app that paints
inside the shell’s content column and declares the bar itself: it
starts its declaration from Self::slots (the sidebar toggle, Back
while it goes anywhere, the inspector’s toggle) and hands what the
person did in the bar to Self::event first, as an app that owns its
shell does with NavShell::window_toolbar and
NavShell::window_toolbar_event.
The failure face filling a window: the banner centred in the area at the
readable width, standing at rest from its first frame (the window’s
arrival brings it in).
WindowFrameProps built: layers on the window surface, the content (under the frame’s
own bar while it needs one) and the controls over its bar’s trailing end.
A window’s live picture, at the rectangle the preview stands at: the compositor draws the
window’s own pixels there, so the preview draws nothing and takes no input.
What the window says about its changes in the header row: quiet text
(“Working offline…”), and the one thing the person can do about it when
there is one (Retry), as a button beside it.
A typed, device-local request from app content to shell chrome. Keeping
this on the common app contract lets both in-process tiles and future IPC
adapters use one destination without an app reaching into compositor
state or pretending a status toast completed the navigation.
A semantic, UUID-addressed mutation emitted by the optional action bridge.
It intentionally contains no Automerge object ids, making it safe to replay
on another replica or use from apps with a different document layout.
The edge of the screen a bar or a dock stands on: the side of its body the content is. A
square body casts no rule from it (bars cast none, design-language.md); it says which way a
floating, rounded body’s hairline faces and how a view lays its content out.
What the shell’s content is, so it knows the narrowest the content still works at; below that
the window shows one column at a time. Apps say what their content is, never how wide it is.
What a history entry did, as the history and activity views mark,
filter and group it. Read from the change itself (its entry and what it
wrote), not from the transport that carried it.
Drained by the host via FilePicker::take_outcome once per frame;
None means “user hasn’t decided yet”. The terminal variants resolve
the host’s oneshot::Sender<Option<Vec<PathBuf>>>.
A lightweight icon descriptor usable before the full asset pipeline lands.
Glyph is a Nerd Font / unicode codepoint (existing approach in both
the iced file-explorer and quick-terminal). Named is a symbolic name for
future theme-driven icon resolution.
What a row of a folded menu (MenuItem::fold_numbered) stands for: the command
whose index the row was given, or the indices of the run of commands a group row
opens, in the order the person meets them.
Mirrors the variants of the shell’s consumer-facing
quick_shell::shell::state::GrantScope plus an explicit
PromptChoice::Deny for the negative path. Held one-shot on
PermissionPrompt::pending_choice until the host drains it.
Commands for the compositor-owned recording session. Keeping controls in
the same semantic intent stream as Start makes shell chrome, shortcuts and
future remote controls share one state machine.
The part of a run an item belongs to, as a bar or a dock is built: the items that lead
(a bar’s mark and menus, a dock’s launcher), those in the centre (a bar’s clock), those
that trail (the people and the status), and the ones between groups, which push the groups
apart as a spacer does. A dock is one compact group at the centre of its edge, so its
items are all Leading and its run is packed.
One shape of a Drawing. Coordinates and sizes are fractions of the drawing’s box (0.5
is its middle); angles of an arc are fractions of a turn, from the top, clockwise.
What a structural change a subtree reported (Widget::take_structure_change)
asks of its host. Ordered: a change joined with a larger one is the larger.
What a tab’s content is doing, marked in place of its icon: loading, or making sound. A sound
mark is a control, and a click is reported by TabBar::take_mark_click.
The syntactic category a run of source falls into. The editor never
hard-codes a colour for these — the theme’s syntax palette resolves each
to a concrete colour, so syntax tracks the active theme in light, dark
and high contrast.
Persisted width of a [crate::WindowGroup], as a fraction of the
strip’s usable width — a stored pixel count would mean a different
screen share on every monitor.
How many lines a card’s title may take before it is cut with an ellipsis: a card is a small
document, and its title says what it is without being opened.
The seam’s hit zone is the slot plus one grab zone of each neighbour
(RESIZE_HANDLE_PX inside each window), so every window edge, seam or
outer, has the same size of target. Half of the 20 px total each side.
This is the strip’s inter-group gap: the row declares no gap of its own
and lets the handle supply the whole footprint, so anything that walks
the strip’s canvas (GroupRow::usable_per_group) has to step by this
between adjacent groups.
The event a component fires when a reference in its text is activated, carrying the
reference (the mention mark’s value): what its host opens when the view gives the event
nothing of its own.
Wallpaper under a strip’s tiled windows, so their bottom border and corners stand clear of the
screen edge; a maximized or fullscreen window takes the band.
Wallpaper a desktop keeps at both ends of a strip, as the leading inset and, through usable
width, at the trailing end: without it a window at either end has its border, corners and shadow
(e2: blur 8) cut off by the screen edge.
Wallpaper between the bar’s band and the top of a strip, so a window’s top edge and corners
stand on it rather than against the bar, while both still read as one stack.
The unscaled title-bar height: a floating window’s title bar is a Bar
(HIG §9.1/§9.6), so it takes metrics.bar_height — the same 40 px the
top bar, a toolbar and the shared Button use. Live geometry reads the
ui_scaled token from the theme the window was laid out with
(FloatingWindow::title_bar_height); this constant is for callers that
need the reference value in a const context.
One step of a tree’s nesting (VirtualList::with_tree): the disclosure gutter a row’s
content stands in by, from the leading edge of its own depth, where the chevron that folds
what stands under it hangs.
A wheel’s touch gesture ends when it pauses this long: a trackpad keeps
reporting while the fingers move and through the momentum after they
lift, and a spun mouse wheel’s notches come well inside it.
The storage’s own end, over four million strips: a drag cannot reach it,
even resting at the display’s edge while the strip scrolls under it, so
there is no widest window anyone can feel. (Ten strips used to be the
limit, which an edge drag that scrolls the strip reaches in seconds.)
Bounds of what a width can store, not of what a person may choose: a
group may be a sliver of a share up to any number of strips wide, the
strip scrolls. Windows’ own minimum and maximum sizes are the apps’ to
state (xdg_toplevel hints, a Tilo app’s compact layout); the only limit
of ours is WIDTH_FLOOR_PX.
Trait every in-process app implements so the shell can host it inside a
TileContent::App. AppWidget: Widget means the shell always falls
through to the widget contract for layout, draw, and events.
A widget that can be shown as a card: what a card component (a board’s
BoardCard) asks of the one widget it was given, so the card is that
widget’s own surface and what it says is written once. Asked as a capability, so a widget
wrapped in a host’s pane, a context menu or any other decorator still answers.
Optional cross-device continuation capability for an app root, deliberately separate
from Widget: ordinary controls have no resumable app state, while roots that do expose it through
Widget::provide without weakening their UI integration.
A pluggable, per-line source tokenizer. The CodeEditor owns rendering,
caret, and selection; a Highlighter owns only the language lexing —
mapping a line of source to coloured Spans. SyntaxHighlighter
covers every language with a grammar; hand it (or a wrapper that adds
app-specific spans) to CodeEditor::with_highlighter.
An app’s presentation of the changes in its History. Asked once per
listed change each time the list changes, so answering is cheap: it reads
the entry’s facts, nothing else.
The space a list leaves above its first row and below its last
(VirtualList::with_edges), part of what it scrolls: a page’s top and
bottom spacing around rows that are a page’s content, one by one.
An app whose views are queries over its resources: the window’s search
turns the view shown into a query view, and closing it returns to the
view before.
The box a widget fills when it is the answer of a read: what an
ArrivingView showing it must have reserved. A list row reports its
kind, a media card its aspect.
A row widget says where its own hover actions stand, so the list reports the place to press
one without knowing what the host built its row of (VirtualList::row_action_rect). A row
without actions provides none; ListRow provides its own.
A row that says where its title stands, for the field renaming it in place to stand over
it, in the role the title reads in: asked for through
capability.
A row that paints the selection the list holds for it, asked for through
capability_mut: a view wraps the row it
places in its swipe and its hover toolbar, and the list reaches the row through them.
Panic-free node construction, used by every build_layout implementation
in this module. TaffyTree::new_leaf and new_with_children are typed
-> TaffyResult<NodeId> for API generality, but taffy 0.10’s
implementation shows neither can return Err: new_leaf always
inserts and returns Ok, and new_with_children only fails for a child
NodeId belonging to a different tree, which never happens here since
every child passed in was just built in this same tree by the calls
immediately above each call site. Widget::build_layout returns a bare
NodeId (not a Result) across every implementor, so surfacing a
theoretical error here would mean threading a Result through the whole
toolkit for a branch that can’t be taken.
An app that runs a History of its own inside a desktop window (an app
shown in a region of the host’s scene). The window presents its History
control in the tab row, as one more control of the window, so the app
draws no History band of its own.
The failure face: title says what failed (never an app’s name, which
its window already shows), reason says why. The caller adds the way to
try again with Banner::with_action.
Measure the leading column that fits every badge in badges, so a list
of rows with badges of different lengths keeps one title edge. Pass the
result to every row’s ListRowFace::leading_column. A Section
does this for the retained rows it holds.
Measure the host tree and settle allocation-dependent styles before calling
Widget::apply_layout. App and the headless runner use this same solver.
Manual hosts may use it with the maps from their current build_layout.
Raw Taffy layout still works for ordinary Grid tracks, but cannot resolve
CardGrid’s below-minimum single-column fallback without this adjustment.
A Control’s fill: the shared hover tier when hovered, otherwise a quiet
floor on the same ramp, so a row reads as a surface rather than bare text
on the panel. Both states sit on one ordered ramp, so hover is always the
more prominent.
The device pixels per logical pixel of the display a layout is for: every
tree the toolkit solves rounds its edges onto that grid
([solve_layout]), so an edge lands on a device pixel at 1.5 as at 2.
1 outside a host’s layout pass.
A window’s application mark at any size: the app’s own artwork when it
has some, else the app-kind glyph its tab pill wears, scaled up from the
pill’s 14 px design size. Every surface that names a window by its app
(the tab pill, the window switcher, the overview) paints this one mark.
Draw child unless what it paints misses the viewport. Off-viewport widgets stay dirty, so they
re-emit when scrolled back in. A widget ends every layer it begins: the render service refuses a
scene that leaves a clip open, and with it the whole frame; debug builds check that here, naming
the widget.
Lay out at scale device pixels per logical pixel until the guard is
dropped: a host enters it around its whole layout pass (solving and
placing, with every tree a widget solves of its own), with its display’s
scale. A scale that is not a finite positive number is 1.
event as a widget drawn offset (logical pixels) from where it is
laid out meets it: a pointer or touch position moved back by offset,
so content on its way (a band disclosing above it, a pane gliding) is
hit-tested where it is drawn (motion::Pose::to_local). Every other
event, and any event at a zero offset, passes through untouched.
The colours of role in interact, the one source for the retained and immediate-mode
painters; edge is None where the fill defines the shape or there is no face.
The first widget of root’s subtree, root included, that is a T, to
change: a view or a page wraps the widget it places (a row’s swipe around
its row, a docked page around its list), so a caller reaches it wherever
it sits.
How far past a control’s face its ink may reach under theme: the focus
ring, the ground-coloured line that parts it from a fill of your colour,
and their antialiasing. A 2 px mark stroked centred on a rect reaches no
further, so a region drawn as a part of its own pads its bounds by this.
Used by both widgets so the wording stays uniform with every other
“time ago” label (crate::format::relative). Re-renders every frame,
so the label freshens naturally as now advances — no clock plumbing
needed.
Begin holding windows still: each window then held with
TileHost::hold_content draws its recording until
release_windows. Returns whether a hold began.
Whether child holds the pointer for its subtree: it latched a drag, or a menu or modal
is open somewhere in it. A container that hands input to its children asks this before
routing by place, so a press over an open menu reaches the menu wherever the container
stands and whichever sibling lies under it.
The first letters of the first and the last word, upper-cased:
"Ada Lovelace" gives "AL", "Grace Brewster Hopper" gives "GH",
"ada" gives "A". Words without a letter are skipped, so "Tilo 4"
gives "T", never "T4".
Padding per side in CSS order (top, right, bottom, left). Negative values
are clamped to zero: taffy treats a negative inset as undefined and a
caller subtracting an overlap can otherwise drift below it.
Lay aspects (width / height) out in justified rows width wide: each
row is filled at target_height, then scaled so it spans the width
exactly. The last row keeps the target height instead of stretching,
capped at the height of the row above it.
Returns one rect per item, relative to the origin.
The window area content is seen through while it is being placed: the
viewport of the nearest enclosing scroll view (intersected with any
outer one), or None when nothing clips it. A collection reads it in
Widget::apply_layout to keep only the rows near what is shown laid
out; drawing culls against PresenceCtx::should_cull instead. It is in
effect too while a scroll view collects its content’s damage and while
the host plans its copies (Widget::for_each_child_in_clip).
Room the window’s controls (Full screen, Restore, close) take at the
trailing end of an app’s header row that holds the window’s bar: three
of the row’s icon buttons, a row gap apart.
From a widget’s update: an animation of its own moved or resized what
it lays out (a glide, a jump in progress, a give springing back, a pane
gliding open, a reveal growing a pill), so the last layout no longer
stands. The host lays the window out again in this frame; it is no
change of the model, and nothing syncs.
Tell the host that what a widget presents to the resource surface (the
resources, actions or semantic controls it declares) changed on input it
did not mark handled and without a document edit: hovering a menu row
that opens a nested menu. The host keeps the published resource tree
across bare pointer motion, so such a widget must call this or the tree
agents and assistive technology read would go stale. Clicks, keys and
handled events outside the explicit view-only scroll contract republish.
Tell the host that the wheel event being dispatched was consumed only to
move a scroll container’s view: every widget under the pointer refused
it, and the container took it as a pan of its own offset. The host then
keeps the published resource tree and skips the full sync, exactly as
for a root that declares Widget::view_only_scroll, provided the
dispatch changed no document, focus or declared presentation. A scroll
container that does anything else with the wheel must not call this.
A point packed as the one number an event’s at carries: y in whole
logical pixels above x, each below a million, so a window’s coordinates
survive the round trip.
The square body of a bar standing edge to edge in the screen’s own edge,
in rect: the theme’s bar finish over its own panel ground and the edge
the theme gives it along its foot. Bars cast no rule at the screen’s edge
(design-language.md), so a square body paints no outline; a shell’s bar
paints this and its controls on top.
Paint one Control: its fill with the derived rest edge at the Control
radius, and the toolkit’s 2 px focus ring when focused. The one painter
for every tile, card, power row, edit row and list row a host draws, so
they cannot drift apart.
Lay everything painted next under the disabled veil, over the shape the
control draws as its bounds: a disabled control is its rest face dimmed as
one group, at full-strength edges so it still reads where it stands. The
caller pops the layer once its face is painted.
Paint one match highlight over rect, the span of the matched glyphs —
never a whole line or block. Every match is a wash of the searcher’s own
selection colour; the current one is stronger and outlined so it can be
told apart at a glance.
The keyboard focus ring around a pressable surface of radius: your
colour, 2 px, just outside the surface so it never covers its content.
Composites that own their focus (rows, cards) paint it themselves; a
painted surface with its own hit-testing calls this.
The value a held knob would land on, label, on a chip above the knob,
kept over the slider’s own span so it never leaves the control it reads.
The one readout every held slider shows: the retained Slider and an
immediate-mode seek bar (a shell card’s) alike.
Paint the pending input method composition on a shaped line. Editors
supply the segment from their own projection (proportional formula text
or a fixed-width code line); its appearance follows the shared input role.
Paint the rule a Divider draws along edge of rect, inside it, for
a surface painted by hand. surface is the ground it stands on when that
is not surfaces.base (as Divider::on).
Paint the see-through material over rect at radius: half the panel
ground over the blurred backdrop, its floating shadow outside it only (a
shadow under the body would darken what shows through) and the floating
hairline. Only for chrome over pixels the person is choosing
(docs/design-language.md, “Material and transparency”). Returns the
theme a child standing on it paints with.
The rail a warning or a failure keeps beside its text, so a row’s status
is scannable without taking another line; plain information carries no
colour, so the rail means something wherever it appears.
Paint level over rect: its shadow, its fill and its edge. Returns the
theme a child standing on it paints with (Theme::on_ground): ink,
lifts and the raised well re-measured against the level’s fill.
Whether a strip panned to scroll can be drawn in canvas coordinates: the retained canvas spans
the content from no pan to the furthest, plus pad past either end.
From Widget::apply_layout: whether taffy is a tree its widgets are
being placed again from unchanged (placing_again_in). A widget that
lays out a tree of its own solves it, so its children are placed anew.
How many of a row’s items, widths wide in the row’s order with gap
between them, stand in width beside a door door wide ([give_way]);
the rest are behind the door, in the same order. A row does not reorder
its commands to fit more of them, because the order is what makes them
findable.
Every resource widget’s subtree publishes, as the host’s action
catalogue collects them. A host that embeds components under its own
root (a desktop surface) reads what its search offers through this.
Route event through a container’s children, first handler wins. A child latching a drag gets
it exclusively, so the drag survives the cursor crossing a peer that would claim it first; a
child holding an open modal owns input the same way.
Derive native semantic-action provenance for actionable synthetic nodes in
a custom widget’s accessibility tree. This is the intended low-level escape
hatch: authors draw anything they want, provide stable semantic targets,
and opt those targets into the shared action route with one method call.
Whether the person holds Shift right now, as the window’s last
modifier change said. Shift is how a person skips a confirmation that
Undo makes unnecessary: a menu row that asks first runs at once, and
the host’s question is not asked (see action_palette).
The one rule of every confirmation a person is asked: Shift skips it,
if and only if Undo takes the action back (can_be_undone, from the
action’s contract). What Undo cannot take back is asked, Shift or not.
A wheel event’s sideways travel in logical pixels when horizontal motion
dominates, positive for a wheel turned (or fingers scrolling) rightward,
which scrolls content toward its later columns; None for vertical
motion. Winit reports pixels physical, so they are divided by
scale_factor, and a line is a notch of the wheel’s own metric. The
desktop’s window strip and the app under the pointer read a wheel by this
one rule.
Solve the layout of the tree under root within available: what
TaffyTree::compute_layout does, for a widget or an app that lays a
panel out in a tree of its own.
Carry field’s edits to the Filterable in content: call after
routing each event. The field shows the count the view reports, and its
“Search everywhere” escalation narrows to the view’s scope.
The app’s model, lent to a widget pass. The toolkit only passes it on to
children; the layer that owns the model reads it (the document runtime
through crate::doc::document). A host passes its model by reference
and it coerces: widget.sync(&mut doc, &root).
A draw callback supplied to DocumentViewport::from_draw. It receives
the content→screen Affine already composed with the host transform, so
the closure paints in content space and the viewport handles the
zoom + pan. The viewport rect is supplied for clipping decisions.
Opaque cross-line carry so multi-line constructs — block comments, fenced
code — survive from one line to the next. 0 is the document start; a
Highlighter owns the meaning of every other value. Line-local
highlighters ignore it and always return 0.
Colours spans of a field’s text from the theme: each (range, colour)
is a byte range of the text and the ink it takes (a reference in a
formula, in the colour of the cells it outlines).