Référence › Référence du langage › Product UI

Référence › Référence du langage

Cette page n’est pas encore traduite : voici la version anglaise.

Product UI

The screens of the product and what is on them.

On this page: ui · screen · dialog · overlay · row · column · grid · stack · spacer · label · gauge · bar · chart · telltale · image · list · table · button · toggle · slider · select · input · stepper · preview · var · custom · element · for · if · else · fits

The user interface of the product, in the component that owns the display: its device, its screens, laid out in rows and columns, and the elements bound to the model — what they show, what a press sends, where it goes. The words below are words only inside a ui { } (and its screens and layouts): elsewhere label, button or row are names like any other. docs/ui.md is the guide.

ui#

The user interface of the product, in the component that owns the display: the device (display 800x480, input touch, theme dark), and its screens — screen, dialog, overlay — laid out in row, column, grid and stack, with elements bound to the model (gauge speedo { value speed }, button stop "Stop" { on press send cmd STOP() }). The screens are the UI's states: it starts on the first (or initial), goto X and back move between them. archec checks what each element is bound to (ui-binding), what a press sends (ui-dead-press), the screens it cannot reach (ui-unreachable), the safety messages it shows (ui-safety), the fit on the display (ui-fit), contrast and labels (ui-a11y) and the translations (ui-text); archec ui prints the resolved model the previews and generators read. docs/ui.md.

  • Keywords: ui
  • Set: product ui
  • Where: inside component, inside system
  • Syntax: ui { display 800x480; input touch; theme dark; screen Id "Title" { row { gauge g { value v } } }; overlay Id { telltale … } }
Property Value Meaning
display any The display, WxH in pixels (display 800x480). Without it, the display of a part's hardware record (its board) is taken.
dpi number Pixels per inch of the display: with it, archec checks touch targets are at least 9 mm (ui-fit).
input touch | encoder | keys | pointer How it is used: touch (the default), encoder (a knob and a press), keys, pointer (a mouse).
theme any Its colors: dark or light, a theme constant (const ACME = { base: "dark", primary: "#00b0ff" }, then theme ACME) or the theme of a ui-kit the project uses (theme "acme/automotive-dark"); colors changes some.
density compact | normal | comfortable How much space things take: compact, normal, comfortable.
colors any The theme's colors changed, as a record: background, surface, foreground, muted, primary, danger, warning, ok ("#rrggbb" or a palette color). Contrast is checked (ui-a11y).
initial ident The screen it starts on (else the first).
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
satisfies list of requirement names Requirements this element satisfies (emitted to traces.yaml).
verifies list of requirement names Requirements this element verifies.
refines list of element names Elements this one refines.
realizes list of element names Elements (one layer up) this one realizes.
allocated-to list of element names Elements this one is allocated to.
deploys list of element names Elements this one deploys.
traces list of element names Generic trace to other elements.
ui {
  display 800x480
  input touch
  theme dark
  screen Driving "Driving" {
    row {
      gauge speedo { value speed; range 0..200; unit km/h }
      button stop "Stop" { style danger; on press send cmd STOP() }
    }
  }
  overlay Warnings {
    telltale brake "Brake fault" { on bus.BRAKE_FAULT; color amber }
  }
}

screen#

A screen: what the display shows at one time. The screens are the states of the UI: it starts on the first one (or the ui's initial), goto X and back move between them. Its children are laid out as a column.

  • Keywords: screen
  • Where: inside ui
  • Syntax: screen Id ["Title"] { on enter <action>; <elements and layouts> }
Property Value Meaning
description text What it is for, in prose.
on any on enter <action> when it is shown, on exit <action> when it is left.
padding number Space inside its edges, in pixels.
gap number Space between its children, in pixels.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
screen Driving "Driving" {
  row { gauge speedo { value speed } }
}

dialog#

A dialog: a screen shown over the current one until it is left (back, or goto). With when <condition> after its title, the model opens it: when the condition becomes true.

  • Keywords: dialog
  • Where: inside ui
  • Syntax: dialog Id ["Title"] [when <condition>] { on enter <action>; <elements and layouts> }
Property Value Meaning
description text What it is for, in prose.
on any on enter <action> when it is shown, on exit <action> when it is left.
padding number Space inside its edges, in pixels.
gap number Space between its children, in pixels.
when any A dialog the model opens: written after its title (dialog BrakeFault "Brake fault" when bus.BRAKE_FAULT { … }), it is shown over the screen that is up when the condition becomes true; leaving it (back) puts that screen back. A condition the safety analysis names must not be dismissible while it holds (ui-safety): enabled not bus.BRAKE_FAULT on its button.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
dialog Confirm "Stop the car?" {
  row {
    button yes "Stop" { style danger; on press send cmd STOP() }
    button no "Cancel" { on press back }
  }
}

overlay#

An overlay: shown over every screen, all the time — where telltales and warnings go, so no screen hides them.

  • Keywords: overlay
  • Where: inside ui
  • Syntax: overlay Id ["Title"] { on enter <action>; <elements and layouts> }
Property Value Meaning
description text What it is for, in prose.
on any on enter <action> when it is shown, on exit <action> when it is left.
padding number Space inside its edges, in pixels.
gap number Space between its children, in pixels.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
overlay Warnings {
  telltale brake "Brake fault" { on bus.BRAKE_FAULT; color amber }
}

row#

Its children side by side, left to right.

  • Keywords: row
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: row [id] { gap 8; align center; <elements and layouts> }
Property Value Meaning
gap number Space between its children, in pixels.
align start | center | end | stretch | between How its children line up across it: start, center, end, stretch; between spreads them along it.
padding number Space inside its edges, in pixels.
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
size small | normal | large | huge The text size of what it holds, unless they say their own: small, normal, large, huge.
color any The color of what it holds, unless they say their own: a palette color, a color of the project, or "#rrggbb".
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
row { gap 8; button a "A"; button b "B" }

column#

Its children one under the other.

  • Keywords: column
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: column [id] { gap 8; align center; <elements and layouts> }
Property Value Meaning
gap number Space between its children, in pixels.
align start | center | end | stretch | between How its children line up across it: start, center, end, stretch; between spreads them along it.
padding number Space inside its edges, in pixels.
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
size small | normal | large | huge The text size of what it holds, unless they say their own: small, normal, large, huge.
color any The color of what it holds, unless they say their own: a palette color, a color of the project, or "#rrggbb".
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
column { label a "A"; label b "B" }

grid#

Its children in a grid of columns columns, row by row.

  • Keywords: grid
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: grid [id] { gap 8; align center; <elements and layouts> }
Property Value Meaning
gap number Space between its children, in pixels.
align start | center | end | stretch | between How its children line up across it: start, center, end, stretch; between spreads them along it.
padding number Space inside its edges, in pixels.
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
size small | normal | large | huge The text size of what it holds, unless they say their own: small, normal, large, huge.
color any The color of what it holds, unless they say their own: a palette color, a color of the project, or "#rrggbb".
columns number How many columns.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
grid { columns 3; button a "1"; button b "2"; button c "3" }

stack#

Its children on top of one another (a picture with a label over it).

  • Keywords: stack
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: stack [id] { gap 8; align center; <elements and layouts> }
Property Value Meaning
gap number Space between its children, in pixels.
align start | center | end | stretch | between How its children line up across it: start, center, end, stretch; between spreads them along it.
padding number Space inside its edges, in pixels.
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
size small | normal | large | huge The text size of what it holds, unless they say their own: small, normal, large, huge.
color any The color of what it holds, unless they say their own: a palette color, a color of the project, or "#rrggbb".
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
stack { image map { src "map.png" }; label pos { text "${x}" } }

spacer#

Empty space that takes what is left in its row or column (grow).

  • Keywords: spacer
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: spacer [{ grow 1 }]
Property Value Meaning
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
row { label t "Title"; spacer; button x "Close" }

label#

Text, with values of the model in it (${expr}).

  • Keywords: label
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: label [id] ["text"] { text "…${expr}…"; size large; color c }
Property Value Meaning
text text What it says: a "string", with ${expr} for a value of the model ("Range ${bus.STATUS.range} m"); translated as the model's other texts ("…" en "…", or translations).
size small | normal | large | huge Its text size: small, normal, large, huge.
color any Its color: a palette color (amber, red, a color of the project) or "#rrggbb".
format string How a number is written: the decimals to keep (format "0.0").
icon ident An icon name, shown before its text (the target picks the glyph).
style primary | danger | quiet How it stands out: primary (the main action), danger (stops or removes something), quiet (secondary) — or a style of your own, a constant record of the properties it sets (const WARN = { color: "amber", size: "large", icon: "warning" }, then style WARN).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
label mode { text "Mode ${adcu.state}" }

gauge#

A dial for a number: its value between the ends of its range.

  • Keywords: gauge
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: gauge [id] ["Title"] { value expr; range lo..hi; unit u }
Property Value Meaning
value any The number it shows.
range range The values it shows or takes, lo..hi (the bound value's declared range when not said).
unit any The unit it shows (the bound value's when not said); a value in another unit is reported (ui-binding).
format string How a number is written: the decimals to keep (format "0.0").
color any Its color: a palette color (amber, red, a color of the project) or "#rrggbb".
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
gauge speedo "Speed" { value speed; range 0..200; unit km/h }

bar#

A bar filled to its value between the ends of its range (a level, a charge).

  • Keywords: bar
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: bar [id] ["Title"] { value expr; range lo..hi }
Property Value Meaning
value any The number it shows.
range range The values it shows or takes, lo..hi (the bound value's declared range when not said).
unit any The unit it shows (the bound value's when not said); a value in another unit is reported (ui-binding).
format string How a number is written: the decimals to keep (format "0.0").
color any Its color: a palette color (amber, red, a color of the project) or "#rrggbb".
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
bar battery "Battery" { value bms.soc; range 0..100; unit % }

chart#

A value over time: the last window of it.

  • Keywords: chart
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: chart [id] ["Title"] { value expr; range lo..hi; window 10s }
Property Value Meaning
value any The number it plots.
range range The values it shows or takes, lo..hi (the bound value's declared range when not said).
unit any The unit it shows (the bound value's when not said); a value in another unit is reported (ui-binding).
color any Its color: a palette color (amber, red, a color of the project) or "#rrggbb".
window duration How much of the past it shows (10s when not said).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
chart speed_trend "Speed" { value speed; window 30s }

telltale#

A warning light: lit while its on condition holds. Give it a text or an icon, not only a color (ui-a11y); a safety one belongs in an overlay (ui-safety).

  • Keywords: telltale
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: telltale [id] ["Text"] { on condition; color amber; icon i }
Property Value Meaning
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
color any Its color: a palette color (amber, red, a color of the project) or "#rrggbb".
icon ident An icon name, shown before its text (the target picks the glyph).
text text What it says: a "string", with ${expr} for a value of the model ("Range ${bus.STATUS.range} m"); translated as the model's other texts ("…" en "…", or translations).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
telltale brake "Brake fault" { on bus.BRAKE_FAULT; color amber; icon brake }

image#

A picture: a file (relative to this file) or an icon.

  • Keywords: image
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: image [id] { src "file.png"; alt "…" }
Property Value Meaning
src string The picture: a file relative to this .arche file.
alt text What it shows, for who cannot see it.
icon ident An icon name, shown before its text (the target picks the glyph).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
image logo { src "logo.png"; alt "Company logo" }

list#

A list of items: a bound array (each item's text) or fixed options.

  • Keywords: list
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: list [id] { value expr | options "a", "b"; on change … }
Property Value Meaning
value any The array it lists.
options any Fixed items, when not bound.
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
list modes { options "Sport", "Comfort", "Eco"; on change mode = value }

table#

Rows of a bound array of structs, a column per field (columns picks them).

  • Keywords: table
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: table [id] { value expr; columns a, b }
Property Value Meaning
value any The array of records it shows.
columns any The fields shown, in order (every field when not said).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
table objects { value adcu.objects; columns id, x, y }

button#

A button: does its on press action.

  • Keywords: button
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: button [id] "Text" { on press <action>; enabled expr; style primary|danger|quiet }
Property Value Meaning
text text What it says: a "string", with ${expr} for a value of the model ("Range ${bus.STATUS.range} m"); translated as the model's other texts ("…" en "…", or translations).
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
enabled any It can be used only while this holds (an expression: enabled adcu.state == Ready).
style primary | danger | quiet How it stands out: primary (the main action), danger (stops or removes something), quiet (secondary) — or a style of your own, a constant record of the properties it sets (const WARN = { color: "amber", size: "large", icon: "warning" }, then style WARN).
icon ident An icon name, shown before its text (the target picks the glyph).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
button engage "Engage" { enabled adcu.state == Ready; on press send cmd ENGAGE_REQ(true) }

toggle#

An on/off switch for a bool: shows value; a change sets it (a variable of the part) or does on change.

  • Keywords: toggle
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: toggle [id] "Text" { value var; on change <action> }
Property Value Meaning
value any The bool it shows (a variable of the part: a change sets it).
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
enabled any It can be used only while this holds (an expression: enabled adcu.state == Ready).
text text What it says: a "string", with ${expr} for a value of the model ("Range ${bus.STATUS.range} m"); translated as the model's other texts ("…" en "…", or translations).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
toggle lights "Lights" { value lights }

slider#

A number picked along its range: shows value; a change sets it or does on change.

  • Keywords: slider
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: slider [id] "Text" { value var; range lo..hi; step s }
Property Value Meaning
value any The number it shows (a variable of the part: a change sets it).
range range The values it shows or takes, lo..hi (the bound value's declared range when not said).
unit any The unit it shows (the bound value's when not said); a value in another unit is reported (ui-binding).
step number The step it moves by.
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
enabled any It can be used only while this holds (an expression: enabled adcu.state == Ready).
text text What it says: a "string", with ${expr} for a value of the model ("Range ${bus.STATUS.range} m"); translated as the model's other texts ("…" en "…", or translations).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
slider target "Target speed" { value target; range 0..130; step 5; unit km/h }

select#

One of options picked from a list.

  • Keywords: select
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: select [id] "Text" { options "a", "b"; value var; on change <action> }
Property Value Meaning
value any The option it shows (a variable of the part: a change sets it).
options any The choices: strings, or the values of an enum (options DriveMode).
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
enabled any It can be used only while this holds (an expression: enabled adcu.state == Ready).
text text What it says: a "string", with ${expr} for a value of the model ("Range ${bus.STATUS.range} m"); translated as the model's other texts ("…" en "…", or translations).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
select drive "Drive mode" { options "Sport", "Comfort", "Eco"; on change send cmd MODE(value) }

input#

A text field.

  • Keywords: input
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: input [id] "Text" { value var; placeholder "…"; on change <action> }
Property Value Meaning
value any The text it shows (a variable of the part: a change sets it).
placeholder text What it says while empty.
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
enabled any It can be used only while this holds (an expression: enabled adcu.state == Ready).
text text What it says: a "string", with ${expr} for a value of the model ("Range ${bus.STATUS.range} m"); translated as the model's other texts ("…" en "…", or translations).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
input name "Name" { value driver_name; placeholder "Driver" }

stepper#

A number changed by − and + by step, within range.

  • Keywords: stepper
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: stepper [id] "Text" { value var; range lo..hi; step s }
Property Value Meaning
value any The number it shows (a variable of the part: a change sets it).
range range The values it shows or takes, lo..hi (the bound value's declared range when not said).
unit any The unit it shows (the bound value's when not said); a value in another unit is reported (ui-binding).
step number The step of − and +.
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
enabled any It can be used only while this holds (an expression: enabled adcu.state == Ready).
text text What it says: a "string", with ${expr} for a value of the model ("Range ${bus.STATUS.range} m"); translated as the model's other texts ("…" en "…", or translations).
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
stepper volume "Volume" { value volume; range 0..10 }

preview#

A named preview: the screens in a state that matters (booting, driving, a brake fault at speed), by what the display reads set to sample values — bus.STATUS.speed = 88, ctrl.state = Autonomous, a variable of the ui — or from a keyframe of the system (from keyframe cold), or both. archec ui preview draws each one, VS Code's UI Preview shows them side by side, archec ui snapshot keeps a golden of each, a test case starts from preview Faulted, and the store's "Try it" opens on the first.

  • Keywords: preview
  • Where: inside ui
  • Syntax: preview Id ["Title"] [from keyframe k] [{ name = value; … }]
Property Value Meaning
description text What it is for, in prose.
keyframe ident The keyframe of the system it starts from (written from keyframe cold after its title).
set any One line of it: name = value, a name the ui reads (written without set).
preview Faulted "Brake fault at 88 km/h" {
  ctrl.state = Autonomous
  bus.STATUS.speed = 88
  bus.BRAKE_FAULT = true
}

var#

A variable of the ui: state of the display only (the tab shown, a text being typed). It is never sent on a bus and is not part of the formal model (archec verify); each target keeps it as UI state (a property in Slint and QML, a static in LVGL). Bindings read it, actions and controls set it.

  • Keywords: var
  • Set: the model
  • Where: inside ui
  • Syntax: var name[: Type] = value
Property Value Meaning
description text What it is for, in prose.
var tab = "Overview"

custom#

An element of your own, written for each target: a ``` block per target (web, lvgl, slint, qml); value is handed to it.

  • Keywords: custom
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: custom [id] { value expr; web ```html …```; lvgl ```c …``` }
Property Value Meaning
value any What it is handed.
on any What happens: on press <action> (a button), on change <action> (value is the new value), on long-press …; one line, or a { … } block of the action language — send port MSG(args), goto Screen, back, var = expr, if …, a function of the part. On a telltale, on <condition> lights it: a message (on bus.BRAKE_FAULT) or any bool expression.
web code Its HTML (the preview and the web target).
lvgl code Its C, for LVGL.
slint code Its Slint.
qml code Its QML.
description text What it is for, in prose.
visible any Shown only while this holds: an expression of the action language over the names the UI sees (visible adcu.state == Autonomous).
grow number Its share of the space left over in its row or column (0: its own size).
width number Its width in pixels, when not its own.
height number Its height in pixels, when not its own.
align start | center | end | stretch How it lines up in its row or column: start, center, end, stretch.
satisfies list of requirement names Requirements this screen or element satisfies: they trace to the UI (traces.yaml, and the UI model).
verifies list of requirement names Requirements this element verifies.
traces list of element names Generic trace to other elements.
custom radar {
  value adcu.objects
  web ```html
    <canvas id="radar"></canvas>
  ```
}

element#

An element of your own: written once with its parameters, used like a built-in one (Tyre("Front", bus.TPMS.front)). Each use is expanded into what it holds, so every target draws it with no code of its own. A bind parameter is given something a change can set (a variable of the part): a toggle or slider bound to it sets that. Written in ui { } or at the top of a file (any ui of the project may use it, a ui kit may ship it).

  • Keywords: element
  • Where: inside ui
  • Syntax: element Name(p: type, q: bind type) { <layouts and elements> }
Property Value Meaning
description text What it is for, in prose.
element Tyre(title: string, p: float32) {
  column {
    label { text title; size small }
    gauge { value p; range 0..4; unit bar }
  }
}

for#

What it holds, once for each item of a list (an array bound from the model), at most max times: an embedded display has no heap to spare, so the most rows ever drawn is part of the model (ui-bound when the array can hold more). The item is named in the bindings inside (${f.code}). Its rows go where it is written, in the row or column around it.

  • Keywords: for
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: for f in <list> max N { <layouts and elements> }
Property Value Meaning
max number The most items it draws.
for f in bus.FAULTS.active max 8 {
  label { text "${f.code}  ${f.text}" }
}

if#

What it holds, shown only while the condition holds (each of them gets it as its visible); an else after it, while it does not.

  • Keywords: if
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: if <condition> { … } [else { … }]
if bus.FAULTS.count == 0 { label ok "No fault" }
else { label n { text "${bus.FAULTS.count} faults" } }

else#

After an if (or an else if): what it holds, shown while none of the conditions before holds.

  • Keywords: else
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: else [if <condition>] { … }
if adcu.state == Ready { label r "Ready" }
else { label w "Wait" }

fits#

Layouts to pick from, the widest first: for each display the ui is built for, archec keeps the first that fits (ui-fit when none does).

  • Keywords: fits
  • Where: inside a screen, dialog or overlay, inside a row, column, grid or stack
  • Syntax: fits { <layout>; <layout> }
fits {
  row { gauge a { value speed; range 0..200 }; gauge b { value rpm; range 0..8000 } }
  column { gauge a { value speed; range 0..200 }; gauge b { value rpm; range 0..8000 } }
}