namespaceUser Interface3 propertiesUI apps only

datumhue.ui

The root content area — the entry point for building UI. Element constructors are methods on the UiElement handle it returns; layout and styling follow the shared NodeStyle option fields.

Returns handles: UiElement

Fields 3

Field	Type	Access	Description
`root`	UiElement	read-only	The app's root content area — the parent for top-level UI. Build on it with the constructor methods, e.g. `ui.root:panel{...}`.
`focused`	UiElement?	read-only	The element holding this app's input focus, so keys and pad activation go to it, always one the app created: focus on a link inside text reads as the text element holding it, and focus on a part of a composite widget (a number input's field or steppers, a date, time or color picker's popover, a menu's trigger) as the widget, whose own `focused` reads `false` because the link or the part holds focus; a move between the parts of one widget changes nothing. `nil` while none of this app's elements holds focus: while the app is not the input owner (another app is focused, or a workstation dialog is open), and while focus is on no element, on another app's or on a "Continue" chip the workstation shows. The `focus` event reports each change. Read-only.
`focus_navigation`	boolean	read/write	Whether the workstation moves this app's UI focus with the arrow keys, the D-pad and the left stick, and maps pad A to activation and pad B to cancel requests. Default `true`; each app has its own, not inherited by the apps it spawns. It acts while the app is the input owner and the open popover or menu holding focus, else its UI, holds at least one focusable widget, or a modal popover shows, so an app without one (a canvas game) is never affected. An arrow key the focused widget does not use, the D-pad and the left stick (past half-way; repeating after 400 ms, then every 90 ms) move focus to the nearest widget that way, within the open popover or menu holding focus (or the modal popover showing), else the whole app; the first such press with nothing focused there only focuses the `default_focus` widget, else the autofocus one, else the top-left one. A single-line text input gives up Up and Down, and a list or radio group the direction that would wrap it. On a slider, list, radio group, multi-line text input or a date picker's calendar the D-pad acts as the widget's own arrow keys; the left stick moves focus from any widget. Pad A acts as Enter, but never submits a text input, which focus has already readied for typing; LT and RT page and the right stick scrolls. The focus ring shows after key or pad input. The keys the pad stands for reach widgets only: `input` readers, bound actions, `on_key` and `on_text` never see them, and `input.last_source` stays `"gamepad"`. With `false`, widgets keep only their own keys. While it does not act, Escape, pad B and, outside a browser, the mouse back button make no cancel request, except Escape at a focused text input; the browser's or phone's Back always makes one. In a browser, a "Continue" chip the workstation shows for an operation that needs a recent press (your app's, or the workstation's, such as a sign-in) is navigated while it holds focus, whatever this says: no direction leaves it, pad A acts as Enter there, and Escape and pad B dismiss it. Takes effect at the next input; a non-boolean raises.

Types 31

ui.AlignContent

enum

Value	Description
`"default"`
`"start"`
`"end"`
`"flex_start"`
`"flex_end"`
`"center"`
`"stretch"`
`"space_between"`
`"space_around"`
`"space_evenly"`

Nested in: ui.NodeStyle

ui.AlignItems

enum

Value	Description
`"default"`
`"start"`
`"end"`
`"flex_start"`
`"flex_end"`
`"center"`
`"baseline"`
`"stretch"`

Nested in: ui.NodeStyle

ui.AlignSelf

enum

Value	Description
`"auto"`
`"start"`
`"end"`
`"flex_start"`
`"flex_end"`
`"center"`
`"baseline"`
`"stretch"`

Nested in: ui.NodeStyle

ui.Bounds

record

record 4 keys

Key	Type	Description
min	Vec2	Top-left corner, in UI px, relative to the calling app's content area (the window for the root app).
max	Vec2	Bottom-right corner.
size	Vec2	Border-box size (max - min).
center	Vec2	Center of the box.

Used by: UiElement.bounds

ui.CancelEvent

record

record 1 key

Key	Type	Description
source	"keyboard" \| "gamepad" \| "mouse" \| "system"	What made the request.

Used by: UiElement:on_cancel

Nested in: ui.TextInputOptions

ui.CancelSource

enum

Value	Description
`"keyboard"`	Escape, while `ui.focus_navigation` acts, at a focused text input, or at a focused "Continue" chip in a browser.
`"gamepad"`	Gamepad B (the east face button), while `ui.focus_navigation` acts or at a focused "Continue" chip in a browser.
`"mouse"`	The mouse back button outside a browser, while `ui.focus_navigation` acts. In a browser that button is the browser's back (`system`).
`"system"`	The browser's back (its button, a mouse back button, Alt+Left), the Android back gesture, the iPhone edge swipe, or `wm.send_cancel`.

Nested in: ui.CancelEvent

ui.ContextEvent

record

record 2 keys

Key	Type	Description
pos	Vec2	Where the request was made, in UI px relative to the top-left of your app's content area: the pointer, or for a key or gamepad request the center of the focused element's `bounds`.
source	"keyboard" \| "mouse" \| "gamepad" \| "touch"	The device that made the request.

Used by: UiElement:on_context

ui.DatePickerOptions

options

options 40 keys, 34 inherited

Key	Type	Default	Description
initial	integer	nothing is selected; the calendar opens on today's month and the time starts at 00:00	Initially-selected instant (Unix microseconds, UTC).
min	integer	no day is too early	Earliest selectable instant (Unix microseconds); earlier days are disabled.
max	integer	no day is too late	Latest selectable instant (Unix microseconds); later days are disabled.
enabled	boolean	true	Whether it starts enabled.
open	boolean	false	Start with the popover open.
on_change	function	no default	Called with the selected instant (Unix microseconds) when the user picks a day or edits the time. A programmatic `value` write does not fire it.

Also takes every key of ui.NodeStyle (34 keys).

Used by: UiElement:date_picker, UiElement:time_picker, UiElement:datetime_picker

ui.Display

enum

Value	Description
`"flex"`
`"grid"`
`"block"`
`"none"`

Used by: UiElement.display

Nested in: ui.NodeStyle

ui.DragEvent

record

record 5 keys

Key	Type	Description
phase	"start" \| "move" \| "end" \| "cancel"	What the drag did.
pos	Vec2	Pointer position in UI px, relative to the top-left of your app's content area.
delta	Vec2	Movement in UI px since the previous event of this drag; zero on `start`.
total	Vec2	Movement in UI px since the press. The drag starts only once the pointer has moved past its threshold, so it is not zero on `start`.
source	"keyboard" \| "mouse" \| "gamepad" \| "touch"	The kind of pointer driving the drag: a mouse (a pen in the browser too) or a touch contact.

Used by: UiElement:on_drag

ui.DragPhase

enum

Value	Description
`"start"`	The pointer moved past the slop since the press. From here the drag owns the pointer.
`"move"`	The pointer moved; at most once per frame.
`"end"`	The pointer was released, at the position of the last event.
`"cancel"`	The drag stopped without a release: a touch cancel, window focus loss, a workstation dialog opening over it, the element removed, hidden or taken out of layout, or its handler cleared.

Nested in: ui.DragEvent

ui.FlexDirection

enum

Value	Description
`"row"`
`"row_reverse"`
`"column"`
`"column_reverse"`

Nested in: ui.NodeStyle

ui.FlexWrap

enum

Value	Description
`"nowrap"`
`"wrap"`
`"wrap_reverse"`

Nested in: ui.NodeStyle

ui.FocusEvent

record

record 1 key

Key	Type	Description
other?	UiElement	The element on the other side of the move: for `on_focus` the one that held focus before, for `on_blur` the one taking focus, named as `ui.focused` names it (for a link inside text, the text element holding it; for a part of a composite widget, the widget). Nil when that is no element, an element since removed, one in another app or the workstation's "Continue" chip, and when focus stayed on one element that moved into or out of this subtree.

Used by: UiElement:on_focus, UiElement:on_blur

Nested in: ui.TextInputOptions

ui.ImageFit

enum

Value	Description
`"fill"`	Stretch to the element box, ignoring the source's aspect ratio.
`"contain"`	Largest aspect-preserving size that fits inside the box; the rest letterboxes.
`"cover"`	Smallest aspect-preserving size that covers the box; the overflow is clipped.
`"scale_down"`	Like contain, but never enlarges past the source's natural size.
`"integer"`	The largest whole multiple of the source's size, in device pixels, that fits the box, centered on whole device pixels; contain when not even one fits.
`"sharp"`	The contain size, drawn by scaling the source up by a whole multiple with nearest sampling and then smoothly down to the box, so texel edges stay crisp at any size.

Nested in: ui.ImageOptions

ui.ImageOptions

options

options 41 keys, 34 inherited

Key	Type	Default	Description
parent	UiElement	the app's content area	Parent element.
material	Shader	the texture shows unprocessed	Shader material for post-processing.
fit	"fill" \| "contain" \| "cover" \| "scale_down" \| "integer" \| "sharp"	"fill"	How the texture maps into the element box; aspect-preserving modes center in the box. `"sharp"` draws with its own shader, so it takes no `material`; neither `"integer"` nor `"sharp"` takes `auto_size`. `"integer"` scales a draw canvas's or scene's size in UI px, so on one whose texels are finer than that (a canvas without `pixel_perfect` on a HiDPI display, a scene) a texel covers a fraction of the multiple. Pair it with the source's `filter` set to `"nearest"`.
auto_size	boolean	false	For a draw canvas or scene: resize it to the element's size in UI px whenever the element resizes, so what it draws keeps its size in UI px instead of scaling with the element. A scene renders at its own size, so this also keeps one sharp. Raises on a plain image, whose resolution is fixed (use `fit`).
accessible_label	string	the image has no accessible name	Accessible name for assistive technology. Images carry no text, so unlike text-bearing widgets they derive no name of their own. Set it on images that convey meaning, and `decorative` on the rest.
decorative	boolean	false	Keeps the image out of what assistive technology reads, as `alt=""` does on the web: a screen reader passes over it. Set it on an image that only decorates, such as art beside text that says who or what it shows. Setting both this and `accessible_label` raises, and so does naming the image later.
tint	Color \| ThemedColor	the image shows its own colors	A color each texel is multiplied by, alpha included, so white leaves the image as it is and a lower alpha fades it. A theme token follows the theme.

Also takes every key of ui.NodeStyle (34 keys).

Used by: Scene:mount, Image:mount, DrawCanvas:mount

ui.JustifyContent

enum

Value	Description
`"default"`
`"start"`
`"end"`
`"flex_start"`
`"flex_end"`
`"center"`
`"stretch"`
`"space_between"`
`"space_around"`
`"space_evenly"`

Nested in: ui.NodeStyle

ui.LineMark

options

options 2 keys

Key	Type	Default	Description
line required	integer	no default	The 1-based line of the element's text it is on.
kind required	"error" \| "info" \| "added" \| "removed"	no default	What it says about the line.

Used by: UiElement.line_marks

ui.LineMarkKind

enum

Value	Description
`"error"`	A line in error: an `error_background` band, and `!` in the `error` color.
`"info"`	A line to look at: an `info_background` band, and `>` in the `info` color.
`"added"`	A line added: a `success_background` band, and `+` in the `success` color.
`"removed"`	A line removed: an `error_background` band, and `-` in the `error` color.

Nested in: ui.LineMark

ui.NodeStyle

options

options 34 keys Omitted keys keep the element's own layout and theme style.

Key	Type	Description
left	number \| string	Left anchor (px or "%").
right	number \| string	Right anchor (px or "%").
top	number \| string	Top anchor (px or "%").
bottom	number \| string	Bottom anchor (px or "%").
width	number \| string	Width (px or "%").
height	number \| string	Height (px or "%").
min_width	number \| string	Minimum width.
max_width	number \| string	Maximum width.
min_height	number \| string	Minimum height.
max_height	number \| string	Maximum height.
aspect_ratio	number	Width over height. An automatic width or height follows the other size through the ratio, and a minimum or maximum set on only the other axis carries over to it.
margin	number \| string \| table	Outer margin: scalar, string, or {top,bottom,left,right}; a table's missing sides are 0.
padding	number \| string \| table	Inner padding: scalar, string, or {top,bottom,left,right}; a table's missing sides are 0.
border	number \| string \| table	Border widths: scalar, string, or {top,bottom,left,right}; a table's missing sides are 0.
flex_grow	number	Flex grow factor.
flex_shrink	number	Flex shrink factor.
flex_basis	number \| string	Flex basis (px or "%").
align_self	"auto" \| "start" \| "end" \| "flex_start" \| "flex_end" \| "center" \| "baseline" \| "stretch"	Per-item cross-axis alignment.
flex_direction	"row" \| "row_reverse" \| "column" \| "column_reverse"	Main-axis direction.
flex_wrap	"nowrap" \| "wrap" \| "wrap_reverse"	Wrapping behavior.
justify_content	ui.JustifyContent	Main-axis distribution.
align_items	"default" \| "start" \| "end" \| "flex_start" \| "flex_end" \| "center" \| "baseline" \| "stretch"	Cross-axis alignment of items.
align_content	ui.AlignContent	Cross-axis distribution of wrapped lines.
gap	number \| string	Shorthand for row_gap + column_gap.
row_gap	number \| string	Row gap (overrides gap).
column_gap	number \| string	Column gap (overrides gap).
overflow	"visible" \| "clip" \| "clip_x" \| "clip_y" \| "hidden" \| "scroll" \| "scroll_x" \| "scroll_y"	Overflow handling. The scroll variants make the element a wheel-scrollable container; see the `scroll` / `scroll_max` element properties.
display	"flex" \| "grid" \| "block" \| "none"	Display mode. `grid` places children in the columns `grid_template_columns` gives, one column without it.
grid_template_columns	integer \| (number \| string)[]	The columns of a `grid` element. Its children fill them a row at a time, in child order, and a short last row keeps its columns' widths. A count, from 1 to 10000, gives that many columns sharing the width equally. A list gives one column per entry: a UI length other than `"auto"`, `"max_content"` for a column as wide as its widest child, or `"<n>fr"` for n shares of the width the other columns and the gaps leave. A shared column never narrows below 0 px, so content wider than it overflows it. `{}` leaves one column.
border_color	Color \| ThemedColor	Border color. Pass a `datumhue.theme.token(...)` to follow the theme and repaint on change.
border_radius	number \| string \| table	Corner rounding: scalar, string, or per-corner table.
z_index	integer	Stacking order.
outline	ui.Outline	Focus outline.
box_shadow	ui.Shadow \| ui.Shadow[]	Drop shadow: one shadow, or an array drawn back-to-front.

Extended by: book.MountOptions, ui.ButtonOptions, ui.CheckboxOptions, ui.CodeOptions, ui.ColorPickerOptions, ui.CopyButtonOptions, ui.DatePickerOptions, ui.ElemUpdateOptions and 16 more

ui.Outline

options

options 3 keys

Key	Type	Default	Description
width	number \| string	0	Outline thickness (px or "%").
offset	number \| string	0	Gap between the element edge and the outline.
color	Color	datumhue.color(0, 0, 0, 0)	Outline color.

Nested in: ui.NodeStyle

ui.Overflow

enum

Value	Description
`"visible"`
`"clip"`
`"clip_x"`
`"clip_y"`
`"hidden"`
`"scroll"`
`"scroll_x"`
`"scroll_y"`

Nested in: ui.NodeStyle

ui.OverflowWrap

enum

Value	Description
`"break_word"`	A word wider than the label breaks at a glyph; the label's smallest width stays its widest word.
`"normal"`	A word wider than the label runs past its box.

Used by: UiElement.overflow_wrap

Nested in: ui.LabelOptions

ui.PickMode

enum

Value	Description
`"file"`	One file; `on_pick` receives a `File`.
`"files"`	One or more files; `on_pick` receives a `File` array.
`"dir"`	A directory; `on_pick` receives a `Dir`.

Nested in: ui.OpenButtonOptions

ui.PopoverAlign

enum

Value	Description
`"start"`	Align to the anchor's leading edge.
`"center"`	Center on the anchor.
`"end"`	Align to the anchor's trailing edge.

Nested in: ui.PopoverOptions

ui.PopoverNavigation

enum

Value	Description
`"auto"`	While it shows and holds focus, the arrow keys, the D-pad and the left stick stay in it.
`"modal"`	While it shows, focused or not, the arrow keys, the D-pad, the left stick, Tab and cancel requests stay in it: the first press lands inside, and a request with nothing in it focused reaches its `on_cancel`. A widget left focused behind it gets no key, the gamepad's included: they go where they go with nothing focused. Nothing behind it scrolls under PageUp, PageDown, Home, End or the gamepad's triggers: they page what scrolls in it, from behind it too.
`"none"`	Never holds them, as a toast should not: the arrow keys move out of it as from any other widget.

Nested in: ui.PopoverOptions

ui.PopoverSide

enum

Value	Description
`"top"`	Above the anchor.
`"bottom"`	Below the anchor.
`"left"`	Left of the anchor.
`"right"`	Right of the anchor.

Nested in: ui.PopoverOptions

ui.Shadow

options

options 5 keys

Key	Type	Default	Description
color	Color	datumhue.color(0, 0, 0)	Shadow color.
x_offset	number \| string	0	Horizontal offset (px or "%").
y_offset	number \| string	0	Vertical offset (px or "%").
spread_radius	number \| string	0	Amount the shadow grows beyond the element box.
blur_radius	number \| string	0	Blur radius.

Nested in: ui.NodeStyle

ui.Syntax

enum

Value	Description
`"lua"`	Lua: keywords, strings, numbers, comments, names being called and `datumhue`.

Nested in: ui.CodeOptions, ui.TextInputOptions

ui.TableColumn

options

options 3 keys

Key	Type	Default	Description
column required	string	no default	Source column name.
label	string	the column name	Header text.
format	string	each cell shows its value unformatted	Cell format for numeric columns, e.g. `"{:.2}"` or `"{value} ms"` (the chart tick-format dialect). Non-numeric columns ignore it.

Nested in: ui.TableOptions

ui.TextPurpose

enum

Value	Description
`"text"`	Any text: the full keyboard.
`"search"`	A search query: a keyboard for search; a one-line field's Enter key reads Search.
`"email"`	An email address: a keyboard with @ and a period.
`"url"`	A web address: a keyboard with / and a period.
`"number"`	A number: the digit keypad with a decimal separator.

Nested in: ui.TextInputOptions

`/` or `Ctrl` `K`	Search
`↑` `↓` `Enter`	Pick a result
`Tab`	Next result filter
`j` `k`	Next or previous entry
`[` `]`	Previous or next page
`y`	Copy a link to the current entry
`?`	These shortcuts
`Esc`	Close

datumhue.ui

Fields 3

Types 31

ui.AlignContent

ui.AlignItems

ui.AlignSelf

ui.Bounds

ui.CancelEvent

ui.CancelSource

ui.ContextEvent

ui.DatePickerOptions

ui.Display

ui.DragEvent

ui.DragPhase

ui.FlexDirection

ui.FlexWrap

ui.FocusEvent

ui.ImageFit

ui.ImageOptions

ui.JustifyContent

ui.LineMark

ui.LineMarkKind

ui.NodeStyle

ui.Outline

ui.Overflow

ui.OverflowWrap

ui.PickMode

ui.PopoverAlign

ui.PopoverNavigation

ui.PopoverSide

ui.Shadow

ui.Syntax

ui.TableColumn

ui.TextPurpose

Try

Recently viewed

Settings

Keyboard shortcuts

On this page