Struct BuildCx 

pub struct BuildCx<'a> { /* private fields */ }

Per-frame, read-only context for App::build.

The runner snapshots the app’s crate::Theme before calling build and exposes it through cx.theme() / cx.palette() so app code can branch on the active palette (a custom widget that picks between two non-token colors based on dark vs. light, for instance). BuildCx is the explicit handle for this — token references inside widgets resolve through the palette automatically and don’t need it.

Future fields like viewport metrics or frame phase will live here so the API stays additive: adding a new accessor on BuildCx doesn’t break apps that ignore the context.

Implementations

impl<'a> BuildCx<'a>

pub fn new(theme: &'a Theme) -> Self

Construct a BuildCx borrowing the supplied theme. Hosts call this once per frame after App::theme and before App::build. Hosts that own a crate::state::UiState should chain Self::with_ui_state so the app can read interaction state (hover) during build via Self::hovered_key / Self::is_hovering_within.

pub fn with_ui_state(self, ui_state: &'a UiState) -> Self

Attach the runtime’s crate::state::UiState so build-time accessors (hovered_key, is_hovering_within) can answer. When omitted, those accessors return None / false — useful for headless rendering paths that don’t track interaction state.

pub fn with_diagnostics(self, diagnostics: &'a HostDiagnostics) -> Self

Attach a HostDiagnostics snapshot for this frame. Hosts call this when they want apps to surface debug overlays (e.g. the showcase status block); apps that don’t read diagnostics() pay nothing for it. Headless render paths leave it None.

pub fn with_viewport(self, width: f32, height: f32) -> Self

Attach the logical-pixel viewport size for this frame. Hosts chain this so apps can branch on viewport metrics during build (responsive layout, phone-vs-desktop splits) without threading surface size through their own state. Headless render paths without a meaningful viewport leave it unset.

pub fn with_safe_area(self, sides: Sides) -> Self

Attach the host’s reported safe-area insets in logical pixels. Hosts chain this when platform chrome (on-screen keyboard, notch, status bar, home indicator) is obscuring some band of the viewport. Apps read it via Self::safe_area / Self::safe_area_bottom and inset their interactive content accordingly. Hosts that don’t report safe-area metrics omit this; apps see Sides::zero() from the read accessors.

pub fn diagnostics(&self) -> Option<&HostDiagnostics>

Per-frame diagnostic snapshot from the host (backend, frame cadence, trigger reason, etc.), or None when the host did not attach one. Apps display this in optional debug overlays.

pub fn theme(&self) -> &Theme

The active runtime theme for this frame.

pub fn palette(&self) -> &Palette

Shorthand for self.theme().palette().

pub fn viewport(&self) -> Option<(f32, f32)>

Logical-pixel viewport (width, height) the host attached for this frame, or None for headless render paths. Apps use this to branch layout on viewport metrics — see Self::viewport_below for the common phone-vs-desktop breakpoint case.

pub fn viewport_width(&self) -> Option<f32>

Logical-pixel viewport width the host attached for this frame, or None when no viewport is available. Convenience for the common single-axis branch (cx.viewport_width().map_or(false, |w| w < 600.0)).

pub fn viewport_height(&self) -> Option<f32>

Logical-pixel viewport height the host attached for this frame, or None when no viewport is available.

pub fn viewport_below(&self, threshold: f32) -> bool

True iff the attached viewport’s width is strictly less than threshold logical pixels. Returns false when no viewport is attached so headless / desktop-default paths fall through to the wider branch — apps that want the opposite default can match on Self::viewport_width directly.

Use for the common breakpoint split:

if cx.viewport_below(600.0) {
    phone_layout()
} else {
    desktop_layout()
}

pub fn safe_area(&self) -> Sides

Logical-pixel safe-area insets the host reports for this frame (Sides::zero() when nothing was attached). Today this is populated only by damascene-web when the on-screen keyboard shrinks the visual viewport — bottom carries the keyboard height; future native mobile hosts will additionally populate top for status-bar / notch and bottom for home-indicator.

Apps inset their root layout (or just the focused-input region) by these amounts so interactive content doesn’t sit underneath platform chrome. The runtime does not auto-apply this — apps decide where the inset matters.

pub fn safe_area_bottom(&self) -> f32

Convenience: just the bottom inset, in logical pixels. Most commonly the soft-keyboard height.

pub fn hovered_key(&self) -> Option<&str>

Key of the leaf node currently under the pointer, or None when nothing is hovered or this BuildCx was built without a UiState (headless rendering paths).

Use for branching the build output on hover state without mirroring it via App::on_event handlers — e.g., a sidebar row that previews details in a side pane based on what’s currently hovered.

For region-aware queries (parent stays “hot” while a child is hovered), prefer Self::is_hovering_within.

pub fn is_hovering_within(&self, key: &str) -> bool

True iff key’s node — or any descendant of it — is the current hover target. Subtree-aware, matching the semantics of crate::tree::El::hover_alpha. Returns false when this BuildCx has no attached UiState or when key isn’t in the current tree.

Reads the underlying tracker, not the eased subtree envelope — the boolean flips immediately on hit-test identity change.

pub fn hovered_scene_point(&self) -> Option<&ScenePointPick>

The scatter point currently under the cursor in a chart3d scene, if any — the 3D analogue of hovered_key.

Scene points aren’t Els, so they can’t emit PointerEnter/Leave like 2D widgets; this surfaces the same hover pick that draws the built-in tooltip chip (ScenePointPick carries the scene id + mark + point index). Use it to drive a detail panel / highlight / linked view on hover — branch the build on cx.hovered_scene_point() without an on_event handler. Picked a frame late (fine for hover UI) and honours the chip’s depth-occlusion + behind-camera culling.

Trait Implementations

impl<'a> Clone for BuildCx<'a>

fn clone(&self) -> BuildCx<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for BuildCx<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Copy for BuildCx<'a>