UiElement

Remove the element and its children. Raises on ui.root (the app's own content area) — remove its children or individual elements instead.

Move the listed children of this element to the front, in the given order; the other children follow in their current order. The elements are kept, with their focus, hover, scroll, handlers and state; layout, navigation by the arrow keys and the Tab order follow from the next frame. A call that leaves the order as it is changes nothing. Raises when an entry is not a child of this element or repeats an earlier entry, before moving any.

Create an in-app navigation region under this element and return its Router. The region fills this element; declare routes with router:route and navigate with show/push/pop/go. Pages are retained (hidden) when backgrounded, so going back restores their scroll and state.

Returns the i-th radio option (1-based) of a radio group as a UiElement. Raises on a non-group element or an out-of-range index.

Returns the i-th row (1-based) of a list as a UiElement. Raises on a non-list element or an out-of-range index.

Set, replace, or clear (pass nil) the click handler at runtime. Fires only on an interactive element (a button).

Set, replace, or clear (pass nil) an open_button's pick handler at runtime — the path to bind a <open_button> declared in DHML from the hosting app. Called with the picked File / File[] / Dir on success (never on cancel); with none bound, a click opens no dialog.

Set, replace, or clear (pass nil) a save_button's save handler at runtime. Called with the read-only File handle after the bytes are committed (never on cancel).

Set the bytes a save_button writes at its next click, captured now. Pass nil to clear (a click then does nothing). The way to keep a save button's payload current — call it whenever the app's data changes. Raises on a non-widget element.

Set the text a copy_button places on the clipboard at its next click, captured now — a string or UTF-8 Bytes (non-UTF-8 raises). Pass nil to clear (a click then does nothing). The way to keep a copy button's payload current — call it whenever the app's data changes. Raises on a non-widget element.

The i-th row (1-based, display order — the sorted order while sorted) of a data table as a {column = value} table over its configured columns, holding the data's own values rather than the text the cells show; a cell missing from the data reads nil. Raises on a non-table element or an out-of-range index.

Set, replace, or clear (pass nil) the hover-enter handler at runtime. Fires when a pointer (the mouse or a touch) enters this element or any of its descendants.

Set, replace, or clear (pass nil) the hover-exit handler at runtime. Fires when the last pointer leaves this element and all of its descendants; a press held inside it keeps it entered until the press ends.

Set, replace, or clear (pass nil) the press handler (fires while held) at runtime. Fires only on an interactive element. Raises on a card button's content, whose presses are the card's.

Set, replace, or clear (pass nil) the release handler at runtime. Fires only on an interactive element. Raises on a card button's content, whose presses are the card's.

Set, replace, or clear (pass nil) the double-click handler at runtime. Fires on a second press within the double-click window. Fires only on an interactive element (a panel or button). Raises on a card button's content, whose presses are the card's.

Set, replace, or clear (pass nil) the focus handler. It fires when keyboard focus enters this element's subtree: the element, or an element inside it (a popover or menu hung from it or from an element inside it included), gains focus while focus is outside it. A move between two elements inside the subtree fires nothing, as with on_hover, and focus on a part of a composite widget is focus on the widget (see ui.focused), so a move between its parts fires nothing anywhere. It fires on any element, focusable or not, whatever moved focus: a press, Tab, focus navigation, focus(), focus moving off a removed or hidden element, a closing popover giving focus back, or your app losing focus and getting it back. Changes within one frame count as one move, to where focus ended up. For each move your on_blur handlers run before your on_focus handlers, each innermost element first. An on_blur follows once focus leaves, unless the element is removed first. Setting a handler on another app's element raises.

Set, replace, or clear (pass nil) the blur handler. It fires when keyboard focus leaves this element's subtree, for an element outside it or for none, and never for a move between elements inside it. It pairs with on_focus and follows its rules for what is inside the subtree, which focus changes count and the order handlers run in. An element removed while focus is inside it hears no on_blur: its handlers go with it. Setting a handler on another app's element raises.

Set, replace, or clear (pass nil) the element's cancel handler. While one is set, the element consumes every cancel request (Escape, gamepad B, Back) that reaches it: one made while focus is on it or inside it, or on datumhue.ui.root one made with nothing focused. Setting a handler on another app's element raises; a window manager sets one on the frame wm.wrap_app returned to take the requests the wrapped app leaves, and those any app living in its window leaves.

Set, replace, or clear (pass nil) the resize handler. It fires once after the element's first layout following the call (in the next frame when it is already laid out), then whenever either side of its laid-out border box changes by 0.5 UI px or more: at most once per frame, with the latest size, one frame after the layout, never for a move alone. size is the border-box size in UI px, nil when the element leaves layout (it or an ancestor gets display = "none"), and the size again when it returns, so it always agrees with bounds. On datumhue.ui.root it fires on window resize, Display size (zoom) change, window-manager bounds or inset changes, and snaps. Setting a handler on another app's element raises.

Set, replace, or clear (pass nil) the handler for changes to this element's own visible (a parent's does not count). It runs in the frame after the change, whatever made it: your own write, a light dismiss or cancel request closing a popover, or the workstation showing a window manager's frame when the framed app's init ends. Changes within one frame coalesce, and it runs only with a value that differs from the one it last reported, or from the element's value when the handler was first set; replacing the handler keeps that value. Setting a handler on another app's element raises.

Set, replace, or clear (pass nil) the drag handler, for the mouse and touch alike. A primary press (the left mouse button or a touch contact) on the element or a descendant, including a button or checkbox inside it, arms a drag; the nearest element with a handler takes it once the pointer has moved more than 4 UI px (mouse) or 8 (touch) along either axis. A press on a slider, scrollbar, text input or color picker inside the element keeps its own drag, and a press in a popover or menu anchored inside it is the overlay's. For a touch, a scroll container inside the element takes the movement instead when it runs along an axis the container scrolls. From its start the drag owns the pointer: nothing under it clicks or activates, and it follows the pointer outside the element and the window until the release, a touch cancel, window focus loss, a workstation dialog opening over it, or the element being removed or hidden (visible = false, or display = "none" on it or an ancestor). Only the first touch contact drives a drag, and keyboard focus plays no part: a press that moves focus to another app keeps its drag. A replaced handler hears the rest of the drag; clearing the handler cancels it. Setting a handler on another app's element raises, and so does setting one on a card button's content, whose presses are the card's.

Set, replace, or clear (pass nil) the context handler: the element's actions are asked for, as the right-click menu or an item's Actions. It fires on a right-click (the right mouse button released over the element), a touch held 500 ms within 8 UI px of where it landed (that touch then clicks nothing, and neither scrolls nor drags), the Menu key or Shift+F10 while the element has keyboard focus, and gamepad X (the west face button) while it has focus and ui.focus_navigation acts. A request goes to the nearest element with a handler, walking up from the element under the pointer or the focused one within its app, and only that handler hears it; a request in a popover or menu popup anchored inside the element is the overlay's. A touch on a slider, scrollbar, text input or color picker keeps its press, so it makes no request. Input reads are unchanged: the key and the buttons still read as pressed. Setting a handler on another app's element raises, and so does setting one on a card button's content, whose presses and focus are the card's.

Move keyboard focus to this element. Takes effect on focusable widgets (a text input, button, checkbox, slider, radio group, or list); a no-op on elements that cannot hold focus. The focus ring shows when the last input came from the keyboard or a gamepad. Called while its app is not the input owner (another app is focused, or a workstation dialog is open), it moves no keys: the element gets focus when its app is the input owner again.

Set the color of a label's or link's text, or of a button's label. Pass a datumhue.theme.token(...) to follow the theme; omit / pass nil to re-follow the default text color. A disabled button shows the theme's disabled label color, and this one again once enabled.

Apply a shader material. Omit / pass nil to remove it.

Swap the image texture to a render-target source. Omit / pass nil to clear it.

Batch-update layout / style plus source, color, text, visible, or material. The sizes, padding, border width, corner radius, gaps, colors and fonts it writes stay as written through later theme and density changes. On a button, text and the font keys style its label. On a text input, the room its leading_icon, line numbers and clear button take adds to the padding it writes, so a percentage on a side one of them takes raises. A column flex_direction, a wrapping flex_wrap or a block or grid display raises too.

Cursor position in UI px from the top-left of the element's border box (bounds.min), at every zoom and stretch mode; negative or past bounds.size off the element. Nil off the window and while the element has no bounds.

Scale an element-relative position in UI px (what mouse_position returns) to the source's own pixels, or nil: an image's pixels, or a draw canvas's or scene's width and height, whatever resolution it renders at. Scene:screen_to_ray takes these pixels.

Create a child UI panel. Inside a card button it raises for on_press, on_release or on_double_click: the card's presses are its own.

Create a child interactive button. Without text the button is a card: the elements created under it form its content, the whole card is one focus stop and one pointer target (a press on any of its content activates it), and creating an interactive widget inside it raises, a table and a book page with links, widgets or chapter navigation included, as does a press or drag handler on its content. A button with text has a border of the theme's border_width unless border is set, outside its padding, so a button sized by its content is that much larger on each side; a card has a border only when border is set. A button that takes the theme's fills draws its border in the theme's button_border, which stands out from the surface under it. A disabled button, a button given a fill and a button in a menu draw their border in their fill.

Create a child button that opens a file dialog when clicked, and calls on_pick with what the person picks. Only the click opens the dialog, so your app cannot open one by itself. In a browser that does not let a web page change the person's files, a picked folder is read-only.

Create a child button that opens a save dialog when clicked and atomically writes source to the chosen file. The click is the user gesture. On success on_save fires with the read-only File handle; cancel fires nothing. With no source set the click does nothing.

Create a child button that places its source text on the system clipboard when clicked. The click is the user gesture — there is no programmatic copy, so an app can neither read nor spam the clipboard on its own. On success on_copy fires; a failed write logs. With no source set the click does nothing.

Create a child link styled as link text. Clicking it opens url in a new browser tab; opening only ever happens from this user click, so an app cannot open URLs on its own. url must be http, https, or mailto (any other scheme raises). Hovering shows the destination host.

Create a date picker: a field that opens a calendar popover. Selecting a day fires on_change with the selected instant (Unix microseconds); read/write it via value (nil until picked). Build / decode the value with time.from_calendar / time.calendar.

Create a time picker: a field that opens a popover with 24-hour HH:MM steppers. Editing the time fires on_change with the selected instant (Unix microseconds).

Create a combined date+time picker: a calendar popover with 24-hour HH:MM steppers. Picking a day or editing the time fires on_change with the selected instant (Unix microseconds).

Create a color picker: a field (a swatch + the hex string) that opens a popover with a saturation/value square, a hue strip, a live preview, a hex field, and optional preset swatches. Dragging, committing the hex, or clicking a preset fires on_change with the picked color (sRGB). Read or write the current color via the value property; a programmatic write is silent.

Create a child checkbox. State is the checked property; on_change fires on user toggles.

Create a child horizontal slider. State is the value property; on_change fires continuously while dragging.

Create a child numeric input: a number field with -/+ steppers. State is the value property; on_change fires on field edits and steps.

Create a child radio group. State is the selected property (1-based); on_change fires on user selection.

Create a child selectable list. State is the selected property (a 1-based index, or an index array when multi); on_change fires on user selection.

Create a child data table bound to a DataHandle: a header row over a scrolling body that reads only the rows in view, copying no row into Lua. State is the selected property (a 1-based display index, or an index array when multi); on_change fires on user selection. tbl:row(i) reads one row on demand.

Create a child text input. Its content is the text property; on_change fires on each user edit and on_submit on Enter (single-line). Its children share the row inside its padding with its text, after it unless reorder lists them first, and its layout keys act on that row. A column flex_direction, a wrapping flex_wrap or a block or grid display raises, here and in update, as does assigning a block or grid display. In a row aligning its items at their baselines, a single-line text input aligns at the bottom of its line of text, where its caret ends. A multi-line one aligns at the bottom of the area inside its padding. A child laid out in the row with its text can change this; a popover, a child whose display is none and one given left, top, right or bottom in its options or update cannot. The first such child aligned at its baseline (by its align_self or the input's align_items) gives the input its baseline, or, with none, the first such child reorder lists before the text. An auto top or bottom margin keeps a child from aligning at its baseline.

Create an overlay popover anchored to this element, positioned on side/align with gap, auto-flipped to stay on-screen. Fill it with child widgets; show/hide via the visible property.

Create a dropdown menu anchored to this element: a label trigger button and a popup you fill with child widgets (each item carries its own callback). Clicking the button toggles the popup; clicking outside or pressing Escape closes it; activating a button item runs it and closes the menu.

Create a child text label.

Create a child code element: source code drawn as a book page draws a code listing, on the theme's surface_sunken fill in its normal text size, following theme and density switches. It wraps at its width, between two characters where a run with no space is wider than it. It takes no focus, keys or presses, so a press on it reaches the element holding it, and it may go inside a card button. Assistive technology reads it as code, with its source as the value.

Create a child touch stick: a thumb stick a touch drives. The element's box is the area a touch can start it in; an axis the style leaves unsized is 2 * radius UI px. A touch that starts on it is the stick's until it ends: input.touches() and the elements under it never see it. While it holds the stick, stick, deflection and pressed follow it, and the stick adds to your app's input.action_vector past a 0.25 dead zone. A mouse click never moves it. Raises inside a card button.

Create a child touch button that holds a named action down while a touch holds it: from the touch's start until it ends, wherever the finger moves, input.is_action_down reads true, and is_action_pressed and is_action_released each read true in one tick, whether or not bind_action bound the name. A touch that starts on it is the button's until it ends; the mouse and keys never press it. Removing, hiding or disabling a held button releases it. Raises inside a card button.

Scroll a multi-line text input so its 1-based line shows. While the line's first row is not wholly in view, the text scrolls to put that row in the middle, or as near as the text's ends allow; a line already in view leaves the text where it is. Then the scroll containers holding the input move, innermost first, as for an element Tab focuses, so the line shows in the window and above an on-screen keyboard. The caret, the selection and focus stay where they are, no keyboard opens and on_change does not fire. Called before the input is first laid out, it takes effect once it is. Raises on a single-line text input or any other element, and for a line below 1 or past the last.