Struct BuildCx 

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

What a View uses to describe itself during a build: theme access, interaction state, child building, layout boxes, painting and behavior.

Implementations

impl<'a> BuildCx<'a>

pub fn foreground(&self) -> Option<Color>

The text color of the view being built, if a view around it set one with Self::with_foreground. Colors do not cascade by themselves, so this is how a Kbd inside a filled button reads as part of the button.

pub fn with_foreground<R>( &mut self, color: Color, build: impl FnOnce(&mut Self) -> R, ) -> R

Builds what build builds with color as its Self::foreground. Layers opened inside it start without one, since they are not painted over this view.

pub fn theme(&self) -> &Theme

The theme in effect for this build.

pub fn ui_waker(&self) -> UiWaker

A handle that asks for a rebuild from another thread; see UiWaker.

pub fn labels(&self) -> Rc<Labels>

The words the components use here; see Localized.

pub fn theme_state(&self) -> State<Theme>

The app-wide theme as state: set it to switch themes at runtime.

pub fn links(&self) -> Links

Opens addresses: in the browser it navigates, on the desktop the system’s browser opens them. #name scrolls to the anchor of that name instead.

pub fn full_screen(&self) -> FullScreen

Puts the app in full screen and takes it out: the page’s full screen in the browser, a borderless full screen window on the desktop.

pub fn anchor(&mut self, node: NodeId, name: &str, offset: f32)

Marks the node as the place #name links scroll to, landing offset pixels below the top of its scroll container (the height of a bar pinned over it).

pub fn on_appear(&mut self, node: NodeId, handler: Rc<dyn Fn()>)

Calls handler once, after the first frame in which the node shows inside its scroll container: counters that start when they are seen, content loaded when it is reached. The handler runs outside the build, so it may set state.

pub fn time_linked(&mut self, node: NodeId, link: TimeLink)

Paints the node and its subtree with the effect link gives for the clock and the node’s frame, on every frame while it shows: a strip that keeps moving, a gentle float. It neither rebuilds nor lays out. With reduced motion the clock stands at zero.

pub fn scroll_progress( &mut self, node: NodeId, range: ScrollRange, progress: Rc<Cell<f32>>, )

Writes into progress, before each paint of the node, how far the scroll is along range from 0 to 1, for drawing that follows the scroll itself, such as a crate::QuadField. Effects that only move, fade or scale use Self::scroll_linked instead.

pub fn clipboard(&self) -> Clipboard

The system clipboard, for copy and paste handlers.

pub fn sound(&self) -> Sound

The system’s sound and voice.

pub fn file_picker(&self) -> FilePicker

The system’s chooser of files.

pub fn files_over(&self) -> bool

Whether files are being dragged over the window, for places that take them to show it.

pub fn on_file_drop( &mut self, node: NodeId, handler: Rc<dyn Fn(Vec<PickedFile>)>, )

Makes the node take files dropped on it.

pub fn viewport(&self) -> Size

The viewport size in logical pixels.

pub fn widget_id(&self) -> WidgetId

The identity of the view being built.

pub fn is_hovered(&self) -> bool

The pointer is over this view’s interactive element.

pub fn is_hover_within(&self) -> bool

The pointer is over this view or over any interactive element inside it.

pub fn use_state<T: 'static>(&mut self, init: impl FnOnce() -> T) -> State<T>

State owned by this view instance that survives rebuilds, like SwiftUI’s @State. Call it unconditionally and in the same order on every build; init runs only the first time. The state is dropped when the view stops being built.

pub fn is_pressed(&self) -> bool

The primary button went down on this view and has not been released.

pub fn is_focused(&self) -> bool

Keyboard focus is on this view.

pub fn is_focus_visible(&self) -> bool

Focus is on this view and came from the keyboard.

pub fn child(&mut self, view: &dyn View) -> NodeId

Builds a child view; its identity comes from its position among this view’s children.

pub fn keyed_child(&mut self, key: u64, view: &dyn View) -> NodeId

Builds a child with an explicit key, so it keeps its hover/focus state when siblings are inserted or removed (use it for dynamic lists).

pub fn children(&mut self, seq: &dyn ViewSeq) -> Vec<NodeId>

Builds every view of a sequence as children.

pub fn container( &mut self, style: LayoutStyle, children: &[NodeId], paint: Paint, ) -> NodeId

Creates a box that lays out children and paints paint behind them.

pub fn text( &mut self, text: &str, attrs: &TextAttrs, color: Color, style: LayoutStyle, ) -> NodeId

Creates a text leaf that wraps to the width its parent offers.

pub fn text_truncated( &mut self, text: &str, attrs: &TextAttrs, color: Color, style: LayoutStyle, ) -> NodeId

Like Self::text, on one line that ends with … when it does not fit. Screen readers still get the whole text.

pub fn measure_text(&mut self, text: &str, attrs: &TextAttrs) -> Size

Measures text without creating a node, e.g. to place a caret.

pub fn empty(&mut self) -> NodeId

An empty box that takes no space.

pub fn on_click(&mut self, node: NodeId, handler: Rc<dyn Fn()>)

Calls handler when the node is clicked, or activated with Enter/Space while focused.

pub fn semantics(&mut self, node: NodeId, semantics: Semantics)

Describes the node to screen readers; see Semantics.

pub fn focusable(&mut self, node: NodeId, corner_radius: f32)

Makes the node reachable with Tab; the focus ring uses corner_radius.

pub fn cursor(&mut self, node: NodeId, icon: CursorIcon)

Shows icon while the pointer is over the node, and makes it hoverable.

pub fn on_key(&mut self, node: NodeId, handler: KeyHandler)

Receives key presses while the node is focused (make it Self::focusable). Return true from the handler to stop the default handling (Tab, Enter…).

pub fn on_drag(&mut self, node: NodeId, handler: DragHandler)

Receives pointer drags that start on the node (sliders, splitters…).

pub fn clip(&mut self, node: NodeId)

Clips the node’s children to its frame.

pub fn scroll_offset(&self) -> Point

This widget’s scroll offset (for its scrollable element), as of this build.

pub fn scroll_viewport(&self) -> Option<Size>

The visible size of this widget’s scroll container in the last layout, or None before its first layout. Virtualized views use it with Self::scroll_offset to build only the visible rows.

pub fn keyed_child_frame(&self, key: u64) -> Option<Size>

The size that the keyed child built with key ended up with in the last layout, if it asked with Self::report_frame: for a view that places its children by how much room each one took, before building them again.

pub fn set_scroll_offset(&mut self, offset: Point)

Scrolls this widget’s scroll container to offset after the build (clamped to its content), e.g. to keep a selected row visible.

pub fn now(&self) -> f64

Seconds since the app started, as of this build. Reading it does not schedule anything; use Self::wake_at to be rebuilt later.

pub fn observe_activity(&mut self, observer: ActivityObserver)

Watches the whole UI while this view is built: each painted frame, the pointer and clicks. For recording what happens, as a flight recorder does. It runs on every frame, so it has to be quick. The last call of a build wins.

pub fn ask_for_access_tree(&mut self)

Asks that Self::observe_activity be told what is on screen once this frame is painted, as UiActivity::Described. Building that description costs more than a frame should, so it comes only when asked for.

pub fn wake_at(&mut self, time: f64)

Asks for a rebuild at time (seconds, the same clock as Self::now): toasts that expire, carousels that advance, spinners that turn.

pub fn motion(&mut self, node: NodeId, motion: Motion)

Declares how node animates; see Motion. Call it in the same order on every build, or give the motion a Motion::key.

pub fn animated<T: Animatable + 'static>( &mut self, target: T, transition: Transition, ) -> T

A value that eases toward target, for what Motion does not cover: numbers that feed layout or custom drawing. Call it in the same order on every build. It rebuilds the UI on each frame while it moves, so prefer Motion when you can.

pub fn animated_numbers( &mut self, target: &[f64], transition: Transition, ) -> Vec<f64>

Numbers that go from where they are to target along a tween, in full f64 precision: a counter, or a chart’s data changing. A new target while they move starts from where they are, with no jump. When the count of numbers changes, or under reduced motion, or for a spring, they take the target at once. Call it in the same order on every build, as with Self::animated.

pub fn appear(&mut self, key: u64, transition: Transition) -> f32

How far a view has appeared, from 0 to 1, since it was first built: for content that draws itself in, such as a chart’s data. A new key starts it over. Under reduced motion, or with motion off, it is 1 from the start. Call it in the same order on every build, as with Self::animated.

pub fn reduced_motion(&self) -> bool

The user asked for less motion, in the system settings or in the theme. Motion already respects this; check it for motion you draw yourself.

pub fn measure_content(&mut self, node: NodeId)

Asks the runtime to report the size of the content of node, read back with Self::measured_content on the next build.

pub fn report_frame(&mut self, node: NodeId)

Makes the size this node ended up with readable on the next build, with Self::scroll_viewport, and builds again when it changes: for a view that arranges itself by the room it got.

pub fn measured_content(&self) -> Option<Size>

The size of the content of this view’s measured node in the last layout.

pub fn shortcut(&mut self, key: Key, command: bool, handler: Rc<dyn Fn()>)

Registers an app-wide keyboard shortcut for as long as this view is built. With command, it needs Cmd (macOS) or Ctrl held, e.g. Cmd/Ctrl+K.

pub fn scroll_with_widget(&mut self, node: NodeId)

Makes the wheel over node move what this widget scrolls, for a part that follows the scroll without being inside it, such as frozen row names.

pub fn shortcut_with_shift( &mut self, key: Key, command: bool, handler: Rc<dyn Fn()>, )

Like Self::shortcut, for a key that also needs Shift. Register it before the same key without Shift, which would otherwise answer first.

pub fn on_context_menu(&mut self, node: NodeId, handler: Rc<dyn Fn(Point)>)

Calls handler with the pointer position on a secondary (right) click.

pub fn on_context_menu_in( &mut self, node: NodeId, handler: Rc<dyn Fn(Point, Rect)>, )

The same, also saying the element’s absolute frame, for a menu that depends on where inside the element it was opened.

pub fn on_pointer_move( &mut self, node: NodeId, handler: Rc<dyn Fn(Point, Rect)>, )

Calls handler with the pointer position and the element’s absolute frame whenever the pointer moves over it, for something that depends on where inside it the pointer is. is_hover_within says when it left.

pub fn request_focus(&mut self)

Moves keyboard focus to this widget’s focusable element after the build, scrolling the containers around it until it shows.

pub fn modifiers(&self) -> Rc<Cell<Modifiers>>

Keyboard modifiers as of the latest input event, readable from click handlers (e.g. Shift-click to extend a selection).

pub fn scrollable_virtual(&mut self, node: NodeId, horizontal: bool)

A scroll container in both directions whose content is rebuilt on every scroll (see Self::scroll_viewport).

pub fn wheel_scrolls_sideways(&mut self, node: NodeId)

Makes a wheel that only turns up and down move this scroll container sideways, for a strip with nothing to scroll in the other direction.

pub fn scroll_horizontally(&mut self, node: NodeId)

Lets a scroll container (see Self::scrollable) scroll sideways too.

pub fn translate(&mut self, node: NodeId, offset: Point)

Moves the node’s children by offset when painting (e.g. a header that follows a body’s horizontal scroll).

pub fn pin(&mut self, node: NodeId, top: f32)

Keeps the node on screen while its parent scrolls past, top pixels below the top of the scroll container around it, and lets it leave with the bottom of the parent: CSS position: sticky. It is moved when frames are placed, so clicks, focus and assistive technology find it where it shows. See crate::Sticky.

pub fn scroll_track(&mut self, node: NodeId, top: f32, length: f32)

Marks the node as the track of a scroll scene: content pinned top pixels below the top of the scroll container for length pixels of scrolling. Links inside it that measure crate::ScrollRange::Scene run from 0 to 1 over that length. See crate::ScrollScene.

pub fn scroll_linked(&mut self, node: NodeId, link: ScrollLink)

Paints the node and its subtree with the effect link gives for the current scroll position, worked out on every paint without rebuilding. Layout and hit testing are unaffected. See crate::ScrollLinked.

pub fn on_pinch(&mut self, node: NodeId, handler: Rc<dyn Fn(f32)>)

Calls handler on a zoom gesture over the node, with how much larger was asked for relative to now: 0.02 is 2% larger, and a negative value is smaller.

pub fn on_double_click(&mut self, node: NodeId, handler: Rc<dyn Fn()>)

Calls handler on a double click on the node.

pub fn scrollable(&mut self, node: NodeId)

Makes the node a vertical scroll container: its children scroll with the wheel or trackpad, are clipped, and a scrollbar shows while they move. Give the node LayoutStyle::overflow_hidden so it does not grow to fit.

pub fn scrollbar_outside(&mut self, node: NodeId, by: f32)

Puts this scroll container’s scrollbar by past its right edge, in the room around it.

pub fn overlay( &mut self, anchor: NodeId, placement: Placement, view: &dyn View, on_dismiss: Option<Rc<dyn Fn()>>, )

Builds view as a floating layer above the rest of the UI, placed relative to anchor. on_dismiss is called on a click outside the layer and its anchor, or on Escape.

pub fn keyed_overlay( &mut self, key: u64, anchor: NodeId, placement: Placement, view: &dyn View, on_dismiss: Option<Rc<dyn Fn()>>, )

Like Self::overlay, for a layer that must stay the same one when other layers before it come and go. A plain overlay is told apart by its place among them, so a new one before it makes it start over, and animate in again.

pub fn floating_overlay( &mut self, anchor: NodeId, placement: Placement, view: &dyn View, )

Builds view as a layer that stays open beside the UI, like a chat in a corner: it is under every menu and dialog, wherever it is built, keeps its state when they open, and is not closed by a click outside it.

Trait Implementations

impl Debug for BuildCx<'_>

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

Formats the value using the given formatter.