API reference

aster_blueprint::presented

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.

The one input engine: acknowledged-presentation pointer, key and focus handling shared by every interactive front-end.

[crate::interact::Driver] (compiled-graph screens) and ui::App (terse ui element trees) are thin front-ends over [Engine]. The engine owns an aster_ui::app::Presentation and does all of: hit testing against the last acknowledged geometry, router focus and Tab traversal, logical pointer capture, press anchors and continuity (StaleSnapshot / StaleGeometry cancellation), hover tracking and the settle loop (reconcile against the acknowledged plane, re-render, stage, acknowledge). See docs/INTERACTION.md and docs/1.0/PRESS-CONTINUITY-DESIGN.md.

What differs between front-ends is only what produces a presented scene and what the targets are. That is the [Surface] trait:

  • Driver implements it over a retained blueprint instance (scene nodes are found by the ModelKey the graph put on them);
  • App implements it over the ui layer (the painter puts a keyed hit node on every interactive element; the scene is rebuilt each frame).

A surface reports state changes through [Surface::take_change]: [Change::Model] stages a new model snapshot (a press in flight is then cancelled as stale), [Change::View] re-renders on the same snapshot (a paint-only repaint keeps a press alive; a geometry change does not).

Structs

structaster_blueprint::presented::Admitted

pub struct Admitted { /* see fields */ }

Interaction policy plane + node lookup for one produced scene.

Methods

  • fn new(scene: &Scene, entries: &[Entry<'_>], strict: bool) -> Result<Self, interact::InteractError> — Build the per-frame policy from entries, finding each node by its ModelKey. strict: a key missing from the scene is an error; otherwise that target simply gets no policy (zero-size/absent).

structaster_blueprint::presented::Ctl

pub struct Ctl<'a> { /* see fields */ }

Focus access for [Surface::adjust], against the acknowledged plane.

Methods

  • fn focused_key(&self) -> Option<ModelKey> — Key of the focused node.
  • fn focus(&mut self, id: Option<&str>) -> Result<(), interact::InteractError> — Focus id (or clear). Refused when the target is not focusable.

structaster_blueprint::presented::Engine

pub struct Engine { /* see fields */ }

The shared engine. Owns the presentation and the input state; all operations take the [Surface] they act on.

Methods

  • fn new(node_hint: usize, scale: f64) -> Result<Self, interact::InteractError> — node_hint: expected scene node count (the policy planes grow if a later scene is larger). scale: output scale (logical -> device px).
  • fn focused(&self) -> Option<&str>
  • fn hovered(&self) -> Option<&str>
  • fn pressed(&self) -> Option<&str>
  • fn hover_chain(&self) -> &[String]
  • fn pointer(&self) -> Option<[f64; 2]>
  • fn is_dirty(&self) -> bool — State changed but not yet rendered/acknowledged.
  • fn owed(&self) -> bool — A deferred pointer move or leave is waiting for [Engine::settle].
  • fn set_defer(&mut self, on: bool) — Defer the settle of pointer moves and leaves (off by default).
  • fn presentation(&self) -> &Presentation<()> — Read-only access to the presentation (acknowledged geometry, stamps).
  • fn live(&self) -> Live<'_>
  • fn mark(&mut self, change: Change) — Record a change made directly on the surface.
  • fn absorb<S: Surface + ?Sized>(&mut self, s: &mut S) — Pull the surface's pending change into the engine.
  • fn set_pointer(&mut self, at: Option<[f64; 2]>) — Set the pointer position without settling (wheel, scroll_at).
  • fn hit_at<'s, S: Surface + ?Sized>(&self, s: &'s S, p: [f64; 2]) -> Option<&'s str> — Target hit by the acknowledged geometry (outside the window = none).
  • fn move_to<S: Surface + ?Sized>(&mut self, s: &mut S, x: f64, y: f64) -> Result<(), interact::InteractError> — Move the pointer to logical (x, y).
  • fn leave<S: Surface + ?Sized>(&mut self, s: &mut S) -> Result<(), interact::InteractError> — Pointer leaves the window.
  • fn down<S: Surface + ?Sized>(&mut self, s: &mut S) -> Result<(), interact::InteractError> — Primary button down at the current pointer position.
  • fn up<S: Surface + ?Sized>(&mut self, s: &mut S) -> Result<(), interact::InteractError> — Primary button up: a click if the press is still valid and inside its target.
  • fn cancel_pointer<S: Surface + ?Sized>(&mut self, s: &mut S) -> Result<(), interact::InteractError> — Abort the pointer press in flight.
  • fn key_down<S: Surface + ?Sized>(&mut self, s: &mut S, key: Key, mods: KeyModifiers) -> Result<(), interact::InteractError> — Key down. The router performs Tab/Shift-Tab traversal; the surface sees the key next; Enter activates (press, release, click) and Space presses (click on [Engine::key_up]) the focused target unless the surface handled the key.
  • fn key_up<S: Surface + ?Sized>(&mut self, s: &mut S, key: Key, mods: KeyModifiers) -> Result<(), interact::InteractError>
  • fn focus_id<S: Surface + ?Sized>(&mut self, s: &mut S, id: &str) -> Result<(), interact::InteractError> — Programmatic focus; refused for non-focusable or disabled targets.
  • fn blur<S: Surface + ?Sized>(&mut self, s: &mut S) -> Result<(), interact::InteractError>
  • fn release_hold<S: Surface + ?Sized>(&mut self, s: &mut S) -> Result<(), interact::InteractError> — The hold in flight confirmed: end its press without a click (the surface ran the actions). A key that is still down stays down for this engine, so its repeats do not start a new hold.
  • fn settle<S: Surface + ?Sized>(&mut self, s: &mut S) -> Result<(), interact::InteractError> — Bring hover, focus and press in line with the acknowledged plane, and re-render until nothing changes. Hit testing for each pass uses the plane acknowledged before that pass's re-render.

structaster_blueprint::presented::Entry

pub struct Entry<'a> { /* see fields */ }

One interactive target as the engine's policy plane sees it.

Public fields

fieldtype
id&'a str
keyaster_ui::ModelKey
tabOption<u32>Some(rank): focusable (enabled, reachable); None: pointer only.

structaster_blueprint::presented::Live

pub struct Live<'a> { /* see fields */ }

What the engine reports to a surface when it asks for a frame: the interaction state the picture must show.

Public fields

fieldtype
hover&'a [String]Hover chain, topmost target first.
focusedOption<&'a str>
pressedOption<&'a str>
pointerOption<[f64; 2]>Logical pointer position (None = outside the window), for pointer-reactive surfaces.

structaster_blueprint::presented::Produced

pub struct Produced<'a> { /* see fields */ }

A produced, not yet staged frame: the scene it came from, the CPU frame and the policy plane. Borrowed from the surface that produced it.

Public fields

fieldtype
scene&'a aster_ui::Scene
frameaster_ui::Frame<'a>
admittedAdmitted

Enums

enumaster_blueprint::presented::Change

pub enum Change { None, View, Model }

How much a surface operation changed.

Variants

  • None
  • View — Re-render on the same model snapshot.
  • Model — New model snapshot (cancels a press in flight).

Trait implementations: Clone, Copy, Debug, Default, Eq, Ord, PartialEq, PartialOrd, StructuralPartialEq

enumaster_blueprint::presented::Flag

pub enum Flag { Hovered, Pressed, Focused }

An interaction flag the engine keeps in the surface (<id>.hovered, ...).

Methods

  • fn name(self) -> &'static str

Variants

  • Hovered
  • Pressed
  • Focused

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

enumaster_blueprint::presented::FocusOnPress

pub enum FocusOnPress { Router, Keep, To }

Where a pointer-down moves keyboard focus.

Variants

  • Router — The router's default: focus the hit target if focusable, else clear.
  • Keep — Leave focus alone.
  • To — Focus this target (or clear with None).

enumaster_blueprint::presented::Keyed

pub enum Keyed { Unhandled, Handled, Nav }

Whether a surface consumed a key.

Variants

  • Unhandled
  • Handled
  • Nav — The surface did not consume the key, but asks for a directional focus move.

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

Traits

traitaster_blueprint::presented::Surface

pub trait Surface

The front-end half: targets, bindings and the thing that renders.

Targets are identified by id strings so that state survives a surface that rebuilds its target list on every frame.

Required and provided methods

  • fn find(&self, id: &str) -> Option<usize> — Index of a live target.
  • fn by_key(&self, key: ModelKey) -> Option<&str> — Id of the live target that owns this node key.
  • fn disabled(&self, id: &str) -> bool — Disabled, or no longer present.
  • fn drag(&self, _id: &str) -> bool — A drag target keeps its press while the pointer leaves it and re-anchors after every frame of the gesture (sliders).
  • fn retained(&self) -> bool — true when scene nodes keep their identity across frames (a retained instance edited in place). false for a surface that builds a new Scene every frame: the engine then bridges node identity itself, by target id (see the module docs of [Engine]).
  • fn hover_chain(&self, top: &str) -> Vec<String> — Hover chain for the target under the pointer (itself first).
  • fn focus_on_press(&self, _hit: Option<&str>) -> FocusOnPress
  • fn fire(&mut self, id: &str, kind: EventKind) -> Result<(), interact::InteractError> — Record the event and run its bindings.
  • fn holds(&self, _id: &str) -> bool — A hold target: a press on it is not a click. It confirms when the surface says so (after the hold time), Enter holds like Space, and a release before that is Cancel(Released).
  • fn hover_moves(&self, _id: &str) -> bool — A target that wants the pointer position while it only hovers over it (no press), delivered through [Surface::pointer_hook] (fluids, parallax). Default: none.
  • fn captures_tab(&self, _id: &str) -> bool — Whether Tab / Shift+Tab go to the key handlers of the focused id (or an ancestor) instead of moving the focus. Ctrl+Tab / Ctrl+Shift+Tab then move the focus. Default: no.
  • fn set_flag(&mut self, id: &str, flag: Flag, on: bool) — Set an interaction flag (view state).
  • fn pointer_moved(&mut self, _at: Option<[f64; 2]>) — The hover pointer moved (or left: None). A pointer-reactive surface marks a view change.
  • fn pointer_hook(&mut self, _id: &str, _at: [f64; 2], _first: bool) -> Result<(), interact::InteractError> — Press/drag position over a drag target (view change).
  • fn on_key(&mut self, focused: Option<&str>, key: Key, mods: KeyModifiers) -> Result<Keyed, interact::InteractError> — Key-down to the focused target (or the surface's own scope). Tab traversal has already been done by the router.
  • fn nav_target(&self, _from: Option<&str>, _dir: Dir) -> Option<String> — The element that should take the focus for a direction, given the element that has it now (None: nothing has the focus). Default: no directional focus.
  • fn reveal(&mut self, _id: &str) -> bool — Scroll id into view when it sits scrolled out of a container the surface can scroll; true when something changed (a render is due). Default: no.
  • fn unreachable(&self, _id: &str) -> Option<String> — Why id cannot take the focus although it asks for it, when the surface knows (a scroll container it cannot drive).
  • fn adjust(&mut self, _ctl: &mut Ctl<'_>) -> Result<bool, interact::InteractError> — Called when the frame is consistent; may move focus (focus traps, programmatic focus requests). true = something changed, go again.
  • fn produce(&mut self, live: &Live<'_>) -> Result<Produced<'_>, interact::InteractError> — Produce the next frame (evaluate, lay out, rasterise).
  • fn presented(&mut self, live: &Live<'_>) -> Result<(), interact::InteractError> — The frame was acknowledged; refresh trees/flags for it.
  • fn take_change(&mut self) -> Change — Take the accumulated change since the last call.

Constants

constaster_blueprint::presented::POINTER

pub const POINTER: aster_ui::PointerId

The single primary pointer the engine drives.