API reference

aster_blueprint::interact

Pre-1.0: signatures are not frozen. Generated from rustdoc JSON of the compiled crate; rustdoc JSON format version 60. Only public items are listed.

Interaction for blueprint UIs: typed state, bindings, automatic hover/press/focus/disabled flags, keyboard traversal and a headless driver.

"bind on_click -> update state -> re-render", with no event/intent kernels:

  • [Store]: small typed app state. A graph parameter with the same name as a store value (or an explicit [DriverBuilder::feed]) is fed from it, so a state change is evaluate + commit_for_renderer on the retained instance (no recompile).
  • [Target]: a clickable/focusable region (a ModelKey of the retained scene) with [Action] bindings. [Action]s mutate the store.
  • Flags <id>.hovered, <id>.pressed, <id>.focused, <id>.disabled are kept in the store automatically, so a Bool parameter of that name drives hover tints and focus rings as data.
  • [Driver]: owns instance + renderer and is a thin front-end over the shared [crate::presented::Engine] (the same engine ui::App runs on), so hit testing, focus, Tab traversal, press anchors and continuity are the existing acknowledged-geometry machinery (PRESS-CONTINUITY-DESIGN.md).

Press semantics: a click is press inside + release inside, with the pressed target's anchor valid. Leaving the target, pointer cancel, focus loss, the target becoming disabled, or a changed model snapshot / acknowledged geometry cancel the press (on_cancel, no click).

Model vs view: store changes made by actions or [Driver::set] are model changes and stage a new snapshot (cancelling a press in flight). Interaction flags and [Driver::set_view] are view changes: the snapshot is reused, so a paint-only repaint keeps a press alive and a geometry change does not.

Structs

structaster_blueprint::interact::Driver

pub struct Driver { /* see fields */ }

Headless interaction driver. All pointer queries run against the last acknowledged frame; every state change re-evaluates the retained instance, re-renders and re-acknowledges before the call returns. A thin front-end over [crate::presented::Engine] (the same engine ui::App runs on).

Methods

  • fn builder(instance: RetainedInstance, head: Headless) -> DriverBuilder
  • fn store(&self) -> &Store
  • fn image(&self) -> &Image — Last acknowledged frame.
  • fn tree(&self) -> &UiTree — Semantic tree of the last acknowledged frame, with interaction flags.
  • fn log(&self) -> &[Event] — Every event delivered so far.
  • fn instance(&self) -> &RetainedInstance
  • fn focused(&self) -> Option<&str> — Id of the focused target.
  • fn hovered(&self) -> Option<&str>
  • fn pressed(&self) -> Option<&str>
  • fn is_dirty(&self) -> bool — State changed but not yet rendered/acknowledged ([Driver::set_pending]).
  • fn write_png(&self, path: impl AsRef<std::path::Path>) -> headless::Result<()>
  • fn assert_snapshot(&self, golden: impl AsRef<std::path::Path>, tolerance: u8)
  • fn set(&mut self, name: &str, value: impl Into<Value>) -> Result<Vec<Event>, InteractError> — Model change + re-render. Cancels a press in flight (stale snapshot).
  • fn set_pending(&mut self, name: &str, value: impl Into<Value>) — Model change without rendering: input keeps using the last acknowledged geometry until [Driver::refresh] (or the next event).
  • fn set_view(&mut self, name: &str, value: impl Into<Value>) -> Result<Vec<Event>, InteractError> — View-only change (no new model snapshot): a press survives it unless acknowledged geometry changes.
  • fn run(&mut self, action: &Action) -> Result<Vec<Event>, InteractError> — Run action as if a binding fired.
  • fn refresh(&mut self) -> Result<Vec<Event>, InteractError> — Render pending changes and re-acknowledge.
  • fn move_to(&mut self, x: f64, y: f64) -> Result<Vec<Event>, InteractError> — Move the pointer to logical (x, y): hover enter/leave, cancels a press that leaves its target.
  • fn leave(&mut self) -> Result<Vec<Event>, InteractError> — Pointer leaves the window.
  • fn down(&mut self) -> Result<Vec<Event>, InteractError> — Primary button down at the current pointer position.
  • fn up(&mut self) -> Result<Vec<Event>, InteractError> — Primary button up at the current pointer position: a click if the press is still valid and inside its target.
  • fn cancel_pointer(&mut self) -> Result<Vec<Event>, InteractError> — Abort the pointer press in flight (on_cancel, no click).
  • fn click_at(&mut self, x: f64, y: f64) -> Result<Vec<Event>, InteractError>
  • fn click(&mut self, label: &str) -> Result<Vec<Event>, InteractError> — Click the target labelled label (or named by id) at its center.
  • fn click_id(&mut self, id: &str) -> Result<Vec<Event>, InteractError>
  • fn hover(&mut self, label: &str) -> Result<Vec<Event>, InteractError>
  • fn hover_id(&mut self, id: &str) -> Result<Vec<Event>, InteractError>
  • fn press(&mut self, label: &str) -> Result<Vec<Event>, InteractError> — Press and hold the labelled target (pair with [Driver::up]).
  • fn key(&mut self, key: Key) -> Result<Vec<Event>, InteractError> — Key down + up (no modifiers).
  • fn key_shift(&mut self, key: Key) -> Result<Vec<Event>, InteractError> — Shift+Tab, Shift+... etc.
  • fn key_with(&mut self, key: Key, mods: KeyModifiers) -> Result<Vec<Event>, InteractError>
  • fn key_down(&mut self, key: Key, mods: KeyModifiers) -> Result<Vec<Event>, InteractError> — Key down to the focused target. Tab/Shift-Tab traverse; Enter activates (press, release, click); Space presses (click on [Driver::key_up]). An explicit on_key binding replaces the activation.
  • fn key_up(&mut self, key: Key, mods: KeyModifiers) -> Result<Vec<Event>, InteractError>
  • fn focus_id(&mut self, id: &str) -> Result<Vec<Event>, InteractError> — Programmatic focus (like focus_request); refused for non-focusable or disabled targets.
  • fn blur(&mut self) -> Result<Vec<Event>, InteractError>

structaster_blueprint::interact::DriverBuilder

pub struct DriverBuilder { /* see fields */ }

Methods

  • fn dynamic(self, d: impl Dynamic + 'static) -> Self — Add a [Dynamic] resource provider (e.g. bound text).
  • fn store(self, store: Store) -> Self
  • fn target(self, t: Target) -> Self
  • fn feed(self, param: &str, f: impl Fn(&Store) -> Literal + 'static) -> Self — Feed graph parameter param from a function of the store (use when the parameter name/type does not match a store value directly).
  • fn resources(self, r: impl ResourceResolver + 'static) -> Self
  • fn build(self) -> Result<Driver, InteractError> — Render the first acknowledged frame and return the driver.

structaster_blueprint::interact::Event

pub struct Event { /* see fields */ }

One delivered interaction event (the bindings for it have already run).

Public fields

fieldtype
targetString
kindEventKind

Methods

  • fn new(target: &str, kind: EventKind) -> Self

Trait implementations: Clone, Debug, Eq, PartialEq, StructuralPartialEq

structaster_blueprint::interact::Store

pub struct Store { /* see fields */ }

Small typed app-state store (ordered, deterministic).

Methods

  • fn new() -> Self
  • fn with(self, name: impl AsRef<str>, value: impl Into<Value>) -> Self
  • fn set(&mut self, name: impl AsRef<str>, value: impl Into<Value>)
  • fn get(&self, name: impl AsRef<str>) -> Option<&Value>
  • fn has(&self, name: impl AsRef<str>) -> bool — Whether name holds a value of any kind.
  • fn toggle(&mut self, name: impl AsRef<str>) -> bool — Flip Bool name (a missing or non-bool key counts as false, so it becomes true) and return the new value: st.toggle("open") in an [Action::custom], the direct twin of [Action::toggle].
  • fn inc(&mut self, name: impl AsRef<str>, by: i64) -> i64 — Add by to Int name (a missing or non-int key counts as 0) and return the new value: the twin of [Action::inc].
  • fn bool(&self, name: impl AsRef<str>) -> bool — false when missing or not a bool.
  • fn int(&self, name: impl AsRef<str>) -> i64 — 0 when missing or not an int.
  • fn scalar(&self, name: impl AsRef<str>) -> f64 — Scalar or int as f64; 0.0 otherwise.
  • fn text(&self, name: impl AsRef<str>) -> &str
  • fn iter(&self) -> impl Iterator<Item = (&str, &Value)>
  • fn list(&self, name: impl AsRef<str>) -> &[Value] — The items of list name (empty when missing or not a list).
  • fn len(&self, name: impl AsRef<str>) -> usize — Number of items in list name (0 when missing or not a list).
  • fn is_empty(&self, name: impl AsRef<str>) -> bool — true when list name has no items (or is missing).
  • fn strings(&self, name: impl AsRef<str>) -> Vec<String> — The Text items of list name as owned strings (other items are skipped).
  • fn push(&mut self, name: impl AsRef<str>, value: impl Into<Value>) -> Result<(), String> — Append to list name, creating it when missing. Refused when the key holds a non-list.
  • fn remove_at(&mut self, name: impl AsRef<str>, index: usize) -> Option<Value> — Remove and return item index of list name (None when out of range).

Trait implementations: Clone, Debug, Default, PartialEq, StructuralPartialEq, ViewportExt

structaster_blueprint::interact::Target

pub struct Target { /* see fields */ }

A generic interactive region: a keyed scene node plus bindings.

Methods

  • fn new(id: &str, key: ModelKey) -> Self — id is what tests/params use (<id>.hovered); key the node's ModelKey.
  • fn inert(id: &str, key: ModelKey) -> Self — Tree-only node: appears in the [UiTree] but receives no input.
  • fn kind(self, kind: &str) -> Self
  • fn label(self, label: &str) -> Self — Label text that click("Save") and assert_visible find.
  • fn label_with(self, f: impl Fn(&Store) -> String + 'static) -> Self — Label computed from state, e.g. |s| format!("Count: {}", s.int("count")).
  • fn focusable(self, order: u32) -> Self — Keyboard focusable, Tab order order (ties: painter order).
  • fn disabled(self, disabled: bool) -> Self — Initial value of the <id>.disabled flag.
  • fn on_click(self, a: Action) -> Self
  • fn on_press(self, a: Action) -> Self
  • fn on_release(self, a: Action) -> Self — Fires on a completed release, just before on_click.
  • fn on_cancel(self, a: Action) -> Self — Fires when a press is cancelled (left target, focus lost, stale, ...).
  • fn on_hover(self, enter: Action, leave: Action) -> Self
  • fn on_focus(self, a: Action) -> Self
  • fn on_blur(self, a: Action) -> Self
  • fn on_key(self, key: Key, a: Action) -> Self — Key-down while this target is focused. Overrides Enter/Space activation for that key.

Trait implementations: Clone

Enums

enumaster_blueprint::interact::Action

pub enum Action { Set, Toggle, Add, Custom, Seq, Push, RemoveAt }

A typed state mutation.

Methods

  • fn emit(e: impl Into<Emission>) -> Action — Emit a field (and its visible part) at the pointer when the action runs. Needs [kine_fx()] in the root overlay. Action::emit(Shockwave::new(V2::ZERO)): the origin given is replaced by the pointer.
  • fn set(name: impl AsRef<str>, value: impl Into<Value>) -> Self
  • fn toggle(name: impl AsRef<str>) -> Self
  • fn inc(name: impl AsRef<str>, by: i64) -> Self
  • fn add(name: impl AsRef<str>, by: f64) -> Self
  • fn copy(text: impl AsRef<str>) -> Self — Put text on the app clipboard (the one App::set_clipboard plugs the host's into) and announce "Copied". The app moves it out of the reserved Text key ~copy once the action has run, so it works from a click, a key or a timer.
  • fn copy_key(key: impl AsRef<str>) -> Self — [Action::copy] of whatever Text key holds when the action runs.
  • fn paste_into(key: impl AsRef<str>) -> Self — Replace Text store key key with the clipboard's text (CRLF becomes LF; a text field's caret goes to the end of it) and announce "Pasted". An empty clipboard changes nothing and announces "Clipboard is empty"; a key that holds something other than Text is an action error.
  • fn custom(f: impl Fn(&mut Store) + 'static) -> Self
  • fn seq(actions: impl IntoIterator<Item = Action>) -> Self
  • fn push(name: impl AsRef<str>, value: impl Into<Value>) -> Self — Append a value to a list key: Action::push("log", "hello") (Store::with("log", Vec::<String>::new())).
  • fn push_with(name: impl AsRef<str>, f: impl Fn(&Store) -> Option<Value> + 'static) -> Self — Append a value computed from the store (a record built from the draft, a timestamp...); returning None appends nothing. Chain a Action::set(draft, "") in [Action::seq] to clear the input.
  • fn remove_at(name: impl AsRef<str>, index: usize) -> Self — Remove item index of a list key.
  • fn clear(name: impl AsRef<str>) -> Self — Empty a list key.
  • fn scroll_to_end(id: &str) -> Self — Re-stick a stick_to_bottom() scroll with .id(id) to the end (a "jump to latest" button, or after sending).
  • fn set_theme(name: &str) -> Self — Switch the app theme by name (\"paper-light\", a built-in or one registered with App::register_theme). The App applies it without rebuilding: store, focus and motion survive.
  • fn set_title(title: &str) -> Self — Set the window title (the reserved ~title store key). A native window follows it at runtime; headless it is only the key. An empty title restores the one the window was opened with.
  • fn toggle_theme(a: &str, b: &str) -> Self — Flip between two themes by name: Action::toggle_theme("mission-dark", "paper-light").
  • fn clamped(self, min: f64, max: f64) -> Self — Clamp the result of an [Action::inc]/[Action::add] to [min, max].
  • fn apply(&self, store: &mut Store) -> Result<(), String> — Apply to store; a missing key or type mismatch is an Err and leaves that step's value unchanged.

Variants

  • Set
  • Toggle
  • Add — Add to an int (by an int) or scalar (by int or scalar), optionally clamped.
  • Custom
  • Seq
  • Push — Append the value computed from the store to a list (None appends nothing).
  • RemoveAt — Remove item index of a list (out of range is a no-op).

Trait implementations: Clone, Debug

enumaster_blueprint::interact::CancelReason

pub enum CancelReason { Left, PointerCancel, FocusLost, Disabled, StaleSnapshot, StaleGeometry, Retired, Released }

Variants

  • Left — Pointer left the target (or was released outside it).
  • PointerCancel
  • FocusLost
  • Disabled
  • StaleSnapshot — Model state changed under the press.
  • StaleGeometry — Acknowledged geometry/policies changed under the press.
  • Retired — The node left the acknowledged plane.
  • Released — A hold target (El::on_hold, hold_button) was released before its time was up.

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::interact::EventKind

pub enum EventKind { Enter, Leave, Press, Release, Click, Cancel, Focus, Blur, Key }

Variants

  • Enter
  • Leave
  • Press
  • Release
  • Click
  • Cancel
  • Focus
  • Blur
  • Key

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::interact::InteractError

pub enum InteractError { NoTarget, Disabled, Obscured, Action, Param, Render, Cancelled }

Variants

  • NoTarget — No interactive target with this label/id.
  • Disabled — The target is disabled; nothing changed.
  • Obscured — Something else is on top at the target's center.
  • Action — An action failed (missing key or type mismatch). State may be partly updated.
  • Param — A store value cannot feed the parameter of that name.
  • Render — Render / presentation failure (text of the underlying error).
  • Cancelled — A strict click (App::click_id_strict): the press was cancelled, so nothing was clicked.

Trait implementations: Clone, Debug, Display, Error, PartialEq, StructuralPartialEq

enumaster_blueprint::interact::Value

pub enum Value { Bool, Int, Scalar, Text, Color, List, Record }

A typed app-state value.

Methods

  • fn field(&self, name: &str) -> Option<&Value> — Field name of a [Value::Record].
  • fn as_text(&self) -> &str — The text of a Text value ("" for anything else).
  • fn as_int(&self) -> i64 — The int of an Int value (0 for anything else).
  • fn text(&self, name: &str) -> &str — Text field name of a record, "" when missing.
  • fn int(&self, name: &str) -> i64 — Int field name of a record, 0 when missing.
  • fn to_literal(&self, ty: ValueType) -> Option<Literal> — The graph literal for a parameter of type ty, if representable.

Variants

  • Bool
  • Int
  • Scalar
  • Text
  • Color
  • List — An ordered list of values (a message log, rows): grow it with [Action::push] / [Store::push], shrink it with [Action::remove_at] / [Store::remove_at].
  • Record — A named-field record, usually a list item: build with [record], read with [Value::field].

Trait implementations: Clone, Debug, From<&str>, From<String>, From<Vec<&str>>, From<Vec<String>>, From<Vec<Value>>, From<[u8; 4]>, From<bool>, From<f64>, From<i32>, From<i64>, PartialEq, StructuralPartialEq

Traits

traitaster_blueprint::interact::Dynamic

pub trait Dynamic

A state-dependent resource provider, prepared before every render (see dyntext::DynTexts). prepare runs first and may refuse: the render is then abandoned before evaluation, so the scene is unchanged.

Required and provided methods

  • fn prepare(&self, store: &Store, scale: f64) -> Result<(), String> — Bring prepared resources up to date with store at output scale.
  • fn params(&self) -> Vec<(Symbol, Literal)> — Graph parameters this provider owns (override store-derived values).
  • fn resolve_prepared(&self, name: &Symbol, value_type: ValueType) -> Option<RuntimeValue> — Prepared host resource by name, if this provider owns it.

Functions

fnaster_blueprint::interact::record

pub fn record<K: Into<String>, V: Into<Value>>(fields: impl IntoIterator<Item = (K, V)>) -> Value

A record value: record([("who", Value::from(2)), ("body", Value::from("hi"))]).

Constants

constaster_blueprint::interact::THEME_KEY

pub const THEME_KEY: &str

The reserved store key holding the active theme name; see [Action::set_theme].

constaster_blueprint::interact::TITLE_KEY

pub const TITLE_KEY: &str

The reserved store key holding the window title; see [Action::set_title]. Empty (the default) means "whatever the host was started with". A native host shows it as the window title and follows changes.