Build a user interface
Build retained, asynchronous interfaces that run in the Byte Engine render loop.
Use the early UI module to build retained, asynchronous interfaces inside the Byte Engine render loop.
An asynchronous component function receives a layout Context. It creates
elements in stable keyed slots, waits for events, and can mount child components
that return values. The runtime keeps state between evaluations, so your
application doesn't rebuild each interaction from the beginning.
engine.mount(async |ctx| {
let mut panel = ctx
.element("panel")
.container(|c| card(c).width(240.into()).flow(flow::column))
.await;
panel.element("title").text("Settings", |t| t.font_size(20.0)).await;
panel.element("clock").component(clock).await;
});Pass components as async closures or async functions that take
&mut EvaluationContext, such as async fn clock(ctx: &mut EvaluationContext).
Choose the main API
layout::engine::Engineevaluates retained UI and produces render data.ContextandContainerContextare the component-facing construction and event APIs.Container,Text,Image,Curve, andPathare the current built-in primitives. Declare a text field withtext_field: it's aTextthat receives text edits while focused.UiRenderPassturns evaluated UI render data into GPU draw work.ConcreteStyle,ConcreteLayer, andTransformhold styling and animation-oriented transforms; set opacity with theopacityproperty.
The layout layer stays small by design. Containers own sizing, positioning, flow, clipping, style, and visual data. Flow functions such as row, column, grid, and centered variants place children. Transforms are best treated as animation and presentation state, while position and sizing describe stable layout. A transform applies to the whole subtree: a scaled container scales its descendants' rectangles, hit bounds, clipping, curve points, stroke widths, and font sizes together, so one transform on a content layer zooms a canvas.
Handle events and focus
UI events are futures that your component can await.
A component can wait for pointer-style events, keys, text edits, timers, or render ticks.
Text input is app-owned: a text field emits edit deltas such as inserted and deleted characters, and application state decides how to apply them. Write the result back with update_text.
Components request and release focus explicitly. Send key and text-edit events to the focused element.
Read and change engine state
A component never holds the engine. Every change it makes is a future: declaring
an element, update_container, remove, reparent, focus requests, and
starting a component. Await it, and it writes straight into the engine while
your component runs, in the order you awaited them. The next layout sees the
change, and so do components that run after yours in the same evaluation.
Declarations and edits take a setup function that sets properties in place,
such as |c| c.width(240.into()).clip(false). The setters write into the
element where the engine stores it, so nothing is built, copied, or sent on the
way. Setup runs only when the declaration creates the element. An element that
already exists keeps its properties until you edit it. A plain function over
Properties holds a reusable look for both declarations and edits:
fn card(card: Properties<'_, Container>) -> Properties<'_, Container> {
card.corner_radius(8.0).style([fill, border])
}
let mut panel = ctx.element("panel").container(|c| card(c).width(240.into())).await;
panel.update_container(|c| card(c).opacity(0.5)).await;To keep steady screens free of allocations, pass text as a &str, a number, or
format_args!("{name} {score}") instead of a formatted String, and style
layers as an array, such as .style([fill, border]). The engine reuses the
storage of removed elements, render entries, and ended components, so a screen
that opens again allocates only one box for each component or mount it starts.
To animate, pass animate an element, a driver such as emphasized_out or
spring, and an async closure that writes one frame's value. The closure can
edit other elements it borrows, so one animation can move a card and fade its
content together:
animate(&mut card, emphasized_out(0.3), async |card, t| {
card.update_container(|c| c.opacity(t)).await;
label.update_text(|l| l.opacity(t)).await;
})
.await;Reads are futures that complete at once. Await them in the component:
let bounds = card.geometry().await;
let pointer = ctx.pointer().await;
let held = ctx.drag().await;
let score = ctx.with(|app: &App| app.score.get()).await;Context::with lends the application context you passed to
Engine::with_context. The host reaches the same value between evaluations
through Engine::ctx and Engine::ctx_mut.
Understand component lifetime
A component started with component runs until its future returns or until the
removal of the scope that started it, whichever comes first. A scope is the one a
mount created: when the mounted future completes or is dropped, its elements
are removed and every component started inside it ends, including components
those components started. Components started outside any mount live until they
return or the engine is dropped.
EvaluationContext::remove removes one element together with everything
declared under it: its descendants and the components started there. The
context it was called on stays valid only to declare the same key again, which
gets the same id. A mounted component awaited from outside the removed element
keeps running until its own future ends. Its elements are gone, so its updates
change nothing.
Build content at runtime
Context::element takes an ElementKey. An element's id is computed from its
parent's path and its key, so the same key under the same parent always
resolves the same retained element. A static name identifies a fixed part of a
component. A name made from data, such as one node of a graph, is keyed by its
content. Pass it as format_args!, which is hashed while it's formatted
without allocating. An owned String with the same content gives the same key:
let mut node = canvas.element(format_args!("node-{id}")).container(|c| node_frame(c, position)).await;
let mut wire = canvas.element(format_args!("wire-{from}-{to}")).curve(|c| wire_between(c, a, b)).await;Siblings under one parent need distinct keys. For a list, pair a name with the item's index:
for (index, row) in rows.iter().enumerate() {
list.element(("row", index)).container(|c| row_frame(c, row)).await;
}Declaring the same key twice under the same parent in one frame is an error: the engine logs it, ignores the second declaration, and fails a debug assertion.
Keep the element contexts as the handles to that content. Re-route a wire while
its ends move with EvaluationContext::update_curve, editing the path in place
so its segment buffer is reused. Changing only the segments repaints the curve
without replaying layout. Remove a node or a wire with
EvaluationContext::remove:
wire.update_curve(|c| c.clear_segments().cubic(from, from + tangent, to - tangent, to)).await;
node.remove().await;Drag a UI item onto an application target
The engine owns one pointer drag. Create a position action with
ActionBindingDescription::new("Mouse.Position").dragged_by("Mouse.LeftButton")
in your UI's input sink and forward its phases to the engine in normalized
window coordinates. Engine::press grabs the surface under the pointer from
the last evaluated frame and returns whether it found one. In this example,
accept_drop maps the released source to your data and validates the
application target before changing application state:
match phase {
ActionPhase::Started => {
engine.press(window_position);
}
ActionPhase::Updated => {
engine.drag_to(window_position);
}
ActionPhase::Ended => {
if let Some(drop) = engine.release(window_position) {
accept_drop(drop);
}
}
ActionPhase::Cancelled => {
engine.cancel();
}
}Capture the gesture in your UI's sink before gameplay processes the same
input, and continue forwarding motion and release outside the source.
Engine::hit answers what's under a point when a sink needs that for its own
capture decisions, such as refusing a drop over UI.
The grabbed surface receives the gesture as events, so it can react on its own.
It gets Events::Grabbed on press. Once the pointer travels past the drag
threshold, it gets Events::Dragged at the start of each Engine::evaluate in
which the pointer moved, with UiEvent::delta set to the offset from the press
point in layout units. When the grab ends by release or cancellation it gets
Events::DragEnded, with UiEvent::source set to the surface the drag was
dropped on, if any. Await all three in one loop, because an event with no
component waiting for it's discarded, and a press and release can arrive in
the same frame:
let mut origin = None;
loop {
let event = select! {
event = card.on(Events::Grabbed) => event,
event = card.on(Events::Dragged) => event,
event = card.on(Events::DragEnded) => event,
};
match event.kind {
Events::Grabbed => {
origin = card.geometry().await;
card.update_container(|c| c.depth(Depth::absolute(1))).await;
}
Events::Dragged => {
if let (Some(origin), Some(delta)) = (origin, event.delta) {
card.update_container(|c| c.transform(placed_at(origin.x() + delta.x, origin.y() + delta.y))).await;
}
}
_ => {
origin = None;
card.update_container(|c| c.depth(Depth::relative(1)).transform(Transform::identity())).await;
}
}
}Depth::absolute lifts the card out of its parent's flow and places it from
the viewport, so a translation by the drag offset from its grabbed geometry
follows the pointer. When scaling a preview, use
Transform::origin(UiPoint::zero()) to keep its top-left corner anchored.
The surface under the release point, and then each of its ancestors, gets
Events::Dropped with UiEvent::source set to the released source. The source
itself is skipped when finding that surface. The engine resolves the target at
the start of the next Engine::evaluate from the previous frame's hit
geometry, before components run, and queues the source's DragEnded after it,
so a target claims the source before the source settles. A target takes a
dropped element into its own layout with EvaluationContext::adopt, which
makes it the target's last flow child while keeping its id and properties:
loop {
let event = stack.on(Events::Dropped).await;
if let Some(card) = event.source {
stack.adopt(card).await;
}
}While a source is held, the surface under the pointer other than the source is
available as DragCapture::over, so the source can preview where a release
would land.
Engine::release still returns the DragDrop for applications that apply
drops outside the UI, so either side can act on it. An element can also move
itself under another parent with EvaluationContext::reparent.
Engine::cancel ends the interaction in progress: it restores the held source
and discards queued clicks, scrolls, key presses, and text edits. Call it when
the window loses focus or the user cancels. A changed viewport size cancels
from Engine::evaluate, because layout distances and the source's place move
with it. The UI supplies the gesture and geometry. Your application decides
which targets accept the item and how to apply it.
React to the pointer passing over a surface
Each Engine::evaluate compares the surface under the pointer with the previous
frame's. When it changes, the old surface gets Events::PointerExited and the
new one Events::PointerEntered, each followed by the ancestors that stopped or
started containing the pointer. An ancestor containing both surfaces hears
nothing, so a panel keeps its hover state while the pointer moves between its
children. A held drag source is skipped, so a drop target under a dragged item
still receives PointerEntered. Engine::hovered answers the same question at
the application level, for a cursor shape for example.
Curves take part once given a hit width: hit_width(width) in a curve's setup
lets the pointer find the curve within width layout units of its stroke, along its
whole length even where it runs beyond its declared size. A wire can then be
hovered, clicked, and dropped on like a container. The width follows the
inherited transform scale.
A container with an absolute position may sit partly outside its parent, including at negative coordinates, so a canvas can be panned past its edge without snapping its content. Flow-placed children are still kept inside the viewport.
Work within the current limits
Primitive UI layer
The module isn't a complete widget toolkit yet. Treat it as a retained primitive layer with an asynchronous interaction model.
Build higher-level widgets through small composed components before you add runtime machinery.
The UI renderer has fixed per-frame limits on clip masks, images, primitives, and glyphs. The UI reference lists them, and defines how depth orders elements and what text rendering guarantees.
Publish only changed renders
Applications should publish a render only when Render::revision changes. The
render source deduplicates repeated revisions anyway, so a republished unchanged
render never makes a sink rebuild.
Anything that must change pixels has to go through the tree: mutate elements through the evaluation context rather than by keeping visual state outside the engine. Placement, style, opacity, clipping, and transforms all live on retained elements, so the revision covers them. Changing the viewport size is the one input outside the tree, and both evaluation and rendering key on it.