API reference

aster_blueprint::dyntext

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.

Text bound to interaction state: the string (and colour) of a label is a function of the Store. Needs native-fonts except for [ellipsize], which works with any [TextMeasure].

Pipeline per render (Dynamic::prepare, run before graph evaluation):

  1. evaluate each bound string/colour; if nothing changed since last render, do nothing (counted as unchanged);
  2. otherwise apply the width policy ([ellipsize], real measurement);
  3. look the (font, size, colour, scale, string) up in a bounded LRU of prepared labels (hits) or shape + insert one into a ResourceArena (prepared), evicting the least recently used label that no element currently shows (evictions); if every cached label is in use the render is refused with DynTextError::Capacity;
  4. the resolver hands the graph the new Label; bounds come from the existing core.label.bounds.v1 kernel, so the node keeps its identity and the ordinary commit_for_renderer path admits (or atomically refuses) it.

Layout policy: an element has an anchor (x, y) and an optional reserved width. Without width the label is left-anchored and simply as wide as its text. With width the text is truncated with an ellipsis to fit and aligned (left/center/right) inside the reserved box, so neighbours never move. Callers that want true reflow can read DynTexts::metrics and drive their own layout solve from the store.

Structs

structaster_blueprint::dyntext::DynStats

pub struct DynStats { /* see fields */ }

Counters for the label cache (cumulative).

Public fields

fieldtype
preparedu64Labels shaped and inserted into the arena.
hitsu64A previously prepared label was reused from the LRU.
unchangedu64An element's inputs were identical to last render: no work at all.
evictionsu64Cached labels dropped to make room.

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

structaster_blueprint::dyntext::DynTexts

pub struct DynTexts(..)

Shared handle to a set of bound text elements. Clone it: give one clone to DriverBuilder::dynamic and keep one to read stats / metrics.

Methods

  • fn new(ts: Typesetter, cache_cap: usize) -> Result<Self, DynTextError> — cache_cap bounds the number of prepared labels kept (and the arena's slots); the command budget is cache_cap * 256.
  • fn add(&self, name: &str, text: Text) -> Result<&Self, DynTextError> — Register an element. Its graph names are <name>.x, <name>.y (length parameters), <name>.bounds and <name>.label (outputs) and host resource dyn.<name>; see blueprint_lines.
  • fn environment(&self) -> compiler::Environment — Compiler environment declaring every element's Label resource.
  • fn blueprint_lines(&self, name: &str, node: u64) -> String — Blueprint-text lines for element name using node ids node and node + 1 (identity + bounds). Splice them into a graph text.
  • fn compile(&self, text: &str) -> Result<compiler::Plan, Box<dyn std::error::Error>> — Compile graph text with this set's resource environment.
  • fn visual(&self, name: &str, node: u64, model_key: ModelKey) -> Result<retained::VisualSpec, Box<dyn std::error::Error>> — VisualSpec for element name (graph node key node, the identity node).
  • fn target(&self, name: &str, id: &str, model_key: ModelKey) -> Result<Target, DynTextError> — Inert [Target] labelled with the element's current full string (before truncation), so tree().assert_visible("Count: 3") works.
  • fn stats(&self) -> DynStats
  • fn cached(&self) -> (usize, usize) — Labels currently cached / the cap.
  • fn metrics(&self, name: &str) -> Option<TextMetrics> — Measured size of what element name currently shows.
  • fn shown(&self, name: &str) -> Option<String> — The (possibly ellipsized) string element name currently shows.
  • fn measure(&self, font: &str, size: f64, text: &str) -> Result<TextMetrics, LayoutError> — Measure with the shared typesetter (same cache as rendering).
  • fn prepare_now(&self, store: &Store, scale: f64) -> Result<(), DynTextError> — Prepare every element for store at scale, all-or-nothing: on error no element changes what it shows.

Trait implementations: Clone, Dynamic

structaster_blueprint::dyntext::Ellipsized

pub struct Ellipsized { /* see fields */ }

Result of [ellipsize].

Public fields

fieldtype
textString
widthf64Measured width of text (always <= max_w unless text is empty).
truncatedbool

Trait implementations: Clone, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::dyntext::Text

pub struct Text { /* see fields */ }

Spec of one bound text element. Build with [Text::bound].

Methods

  • fn bound(f: impl Fn(&Store) -> String + 'static) -> Self — Text whose string is a function of the store.
  • fn fixed(s: &str) -> Self — Constant text.
  • fn font(self, name: &str) -> Self — Font name registered on the [Typesetter].
  • fn size(self, size: f64) -> Self
  • fn color(self, c: [u8; 4]) -> Self
  • fn color_with(self, f: impl Fn(&Store) -> [u8; 4] + 'static) -> Self — Colour as a function of the store.
  • fn at(self, x: f64, y: f64) -> Self — Anchor: left edge of the reserved box and top of the text.
  • fn width(self, w: f64) -> Self — Reserved width: longer text is ellipsized to fit, shorter text is aligned inside it.
  • fn align(self, a: TextAlign) -> Self
  • fn ellipsis(self, e: &str) -> Self

Trait implementations: Clone

Enums

enumaster_blueprint::dyntext::DynTextError

pub enum DynTextError { Layout, Resource, Capacity, Unknown, Invalid }

Variants

  • Layout
  • Resource
  • Capacity — Every cached label is currently displayed: nothing can be evicted.
  • Unknown — No element with this name.
  • Invalid

Trait implementations: Clone, Debug, Display, Error, From<LayoutError>, PartialEq, StructuralPartialEq

enumaster_blueprint::dyntext::TextAlign

pub enum TextAlign { Left, Center, Right }

Horizontal placement inside a reserved width.

Variants

  • Left
  • Center
  • Right

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

Functions

fnaster_blueprint::dyntext::ellipsize

pub fn ellipsize(m: &mut dyn TextMeasure, font: &str, size: f64, text: &str, max_w: f64, ellipsis: &str) -> Result<Ellipsized, layout::LayoutError>

Fit text into max_w: unchanged if it fits, otherwise the longest character prefix (trailing spaces trimmed) followed by ellipsis whose measured width is <= max_w. If even the ellipsis does not fit the result is empty. Cuts fall on char boundaries (combining sequences may split).