Crate frust_widgets

Expand description

Baseline widget set: Text, Button, Image, Column/Row, Stack, ScrollView, CustomScrollView and its slivers, etc.

Ships the text leaf plus the primitive layout containers — Row/Column (FlexView), Stack, IndexedStack, Padding, Align, and SizedBox — built as View/Widget pairs over frust-core’s AnyView/ChildPod substrate. Containers own their children directly as ChildPods (the arena stays single-root); see frust_core::widget::ChildPod for the rationale.

§Shared child plumbing

The container modules build/rebuild/teardown their heterogeneous children through the authoring::build_child/authoring::rebuild_child/ authoring::teardown_child helpers and route pointer events through authoring::route_event (multi-child containers — Flex/Stack) or authoring::route_event_single (one-child wrappers — Padding/Align/SizedBox). Each child is an AnyView whose element (Box<dyn Widget>) is stored double-boxed inside a ChildPod, so a later rebuild can recover &mut Box<dyn Widget> to drive AnyView’s type-erased reconciliation.

That toolkit is public — see the authoring module — so a design system is authored outside this crate against exactly the surface the baseline widgets use themselves. No design-system catalog lives here any more: the three built-in ones ship as their own plugin crates (frust-glyph/frust-material/frust-cupertino), each depending on the frust facade alone, so the authoring boundary is now enforced by the crate graph rather than by a source scan.

Re-exports§

pub use drag::AUTO_SCROLL_EDGE_PX;
pub use drag::AUTO_SCROLL_MAX_PX_PER_S;
pub use drag::AutoScroll;
pub use drag::AutoScrollZone;
pub use drag::AutoScrollZoneWidget;
pub use drag::DRAG_THRESHOLD;
pub use drag::DragCoordinator;
pub use drag::DragHighlight;
pub use drag::DragKind;
pub use drag::DragPhase;
pub use drag::DragPolicy;
pub use drag::DragSession;
pub use drag::DragSourceId;
pub use drag::DragState;
pub use drag::DragStateChange;
pub use drag::DragSubscription;
pub use drag::DragTargetId;
pub use drag::DragTargetView;
pub use drag::DragTargetWidget;
pub use drag::DraggableView;
pub use drag::DraggableWidget;
pub use drag::GHOST_OPACITY;
pub use drag::HIGHLIGHT_FALLBACK;
pub use drag::ReorderableListView;
pub use drag::SourceFeedback;
pub use drag::auto_scroll_zone;
pub use drag::drag_target;
pub use drag::draggable;
pub use drag::draggable;
pub use drag::reorderable_list;
pub use either::Either;
pub use either::EitherOf3;
pub use either::EitherOf3Widget;
pub use either::EitherOf4;
pub use either::EitherOf4Widget;
pub use either::EitherOf5;
pub use either::EitherOf5Widget;
pub use either::EitherOf6;
pub use either::EitherOf6Widget;
pub use either::EitherOf7;
pub use either::EitherOf7Widget;
pub use either::EitherOf8;
pub use either::EitherOf8Widget;
pub use either::EitherWidget;
pub use either::either;
pub use nav::hero::HeroView;
pub use nav::hero::HeroWidget;
pub use nav::hero::hero;
pub use nav::navigator::BackPolicy;
pub use nav::navigator::NavigatorController;
pub use nav::navigator::NavigatorId;
pub use nav::navigator::NavigatorView;
pub use nav::navigator::NavigatorWidget;
pub use nav::navigator::PageBuilder;
pub use nav::navigator::PageVisibility;
pub use nav::navigator::PopResult;
pub use nav::navigator::PushOptions;
pub use nav::navigator::ReplaceOptions;
pub use nav::navigator::ResultCallback;
pub use nav::navigator::RouteChangeCallback;
pub use nav::navigator::VisibilityCallback;
pub use nav::navigator::navigator;
pub use nav::navigator::overlay_host;
pub use nav::path::Location;
pub use nav::path::PathPattern;
pub use nav::path::RouteParams;
pub use nav::route::NavRequest;
pub use nav::route::NavWaker;
pub use nav::route::RouteNavigator;
pub use nav::route_state::NavChange;
pub use nav::route_state::RouteStack;
pub use nav::router::DEFAULT_REDIRECT_LIMIT;
pub use nav::router::ErrorBuilder;
pub use nav::router::Redirect;
pub use nav::router::Resolution;
pub use nav::router::ResolvedPage;
pub use nav::router::Route;
pub use nav::router::RouteBuilder;
pub use nav::router::Router;
pub use nav::router::shell_route;
pub use nav::transition::PageTransition;
pub use nav::transition::Timing;
pub use nav::transition::TransitionSpec;
pub use nav::transition::TransitionState;
pub use physics::effect::OverscrollEffect;
pub use physics::parity::AlwaysScrollable;
pub use physics::parity::Bouncing;
pub use physics::parity::Clamping;
pub use physics::parity::DecelerationRate;
pub use physics::parity::NeverScrollable;
pub use physics::rubber_band::RubberBand;
pub use physics::MAX_FLING_VELOCITY;
pub use physics::MIN_FLING_VELOCITY;
pub use physics::ScrollMetrics;
pub use physics::ScrollPhysics;
pub use physics::Simulation;
pub use physics::SpringDescription;
pub use physics::Tolerance;
pub use pinch::PINCH_SLOP;
pub use pinch::PinchDetectorView;
pub use pinch::PinchDetectorWidget;
pub use pinch::PinchRecognizer;
pub use pinch::pinch_detector;
pub use scroll_controller::AnimateTo;
pub use scroll_controller::ScrollController;
pub use scroll_controller::ScrollSubscription;

Modules§

authoring: The widget-authoring toolkit: the shared child plumbing, event routing and callback erasure every container/interactive widget is assembled from — the surface for authoring widgets, and whole design systems, outside this crate.
drag: Drag-and-drop session model: the DragCoordinator handle every draggable source and drop target in one scope shares.
either: Statically-typed branching views: the two-arm Either with its lazy either helper, and the three-to-eight-arm EitherOf3 .. EitherOf8.
icons: Vendored Material Symbols starter set — GENERATED, do not hand-edit.
keep_alive: keep_alive: keeps a lazy list’s row alive when it scrolls out of the list’s window — Flutter’s KeepAlive / AutomaticKeepAlive (widgets/automatic_keep_alive.dart), answered by sliver_list.
motion: Motion module: declarative single-child animation wrappers built over frust-core’s anim vocabulary (frust_core::AnimationController/frust_core::Curve/ frust_core::Tween/frust_core::Spring) and the paint-only push_layer/push_transform compositing primitives (frust_core::PaintScene).
nav: Imperative navigation: a retained page stack with push/pop/replace and per-page result callbacks, opaque-page paint culling, and test-pinned capture/focus/IME page-switch semantics.
physics: Pluggable scroll physics, mirroring Flutter’s ScrollPhysics contract: a chainable strategy object a scroll surface (today crate::ScrollView/ crate::ListView, hard-coded to one behavior) consults for user-offset mapping, boundary rejection, and post-release ballistic motion instead of having that math wired in directly.
pinch: Touch pinch recognition: PinchRecognizer, a pure two-contact state machine, and pinch_detector, a transparent wrapper view that feeds it.
scroll_controller: ScrollController: a cloneable, reactive-free handle onto a ScrollView or a ListView — the programmatic-scroll seam.

Macros§

visit_children: Implement Widget::visit_children for the container whose impl Widget block this is written in, forwarding the named fields in the order given.

Structs§

AlignView: A declarative alignment container. See the module docs.
AlignWidget: The retained widget for an AlignView.
Alignment: A relative alignment within a box: each axis runs -1.0 (start) through 0.0 (center) to 1.0 (end).
ButtonView: A declarative pressable button. See the module docs.
ButtonWidget: The retained widget for a ButtonView. The label is a nested crate::TextWidget owned as a ChildPod.
CanvasView: A declarative custom-painting canvas. See the module docs.
CanvasWidget: The retained widget for a CanvasView. See the module docs.
CheckboxView: A declarative checkbox. See the module docs.
CheckboxWidget: The retained widget for a CheckboxView.
ChildKey: A stable identity for a list child, so a container’s reconciliation can match a child to its live widget by key across reorders/inserts instead of by position — the difference between “the third row’s widget” and “row #42’s widget” when the list is shuffled.
ContainerView: A declarative decorated box. See the module docs.
ContainerWidget: The retained widget for a ContainerView. See the module docs.
CustomScrollView: A declarative scroll surface over a sequence of slivers. See the module docs.
DividerView: A declarative hairline separator. See the module docs.
DividerWidget: The retained widget for a DividerView. See the module docs.
EdgeInsets: Per-edge inset amounts, in logical pixels.
FlexChild: One child of a FlexView: an erased child view, its flex factor (0 = inflexible; > 0 = takes a proportional share of the free main space), and an optional ChildKey for keyed reconciliation.
FlexView: A declarative flex container. See the module docs.
FlexWidget: The retained widget for a FlexView. Holds a parallel children/flex pair (same length) so layout can index both without a per-child wrapper.
GestureDetectorView: A declarative gesture wrapper. See the module docs.
GestureDetectorWidget: The retained widget for a GestureDetectorView.
IconButtonView: A declarative pressable vector icon. See the module docs.
IconButtonWidget: The retained widget for an IconButtonView. The mark is a nested crate::IconWidget owned as a ChildPod.
IconData: A cheap-clone handle around an icon’s path data and its design box.
IconSource: A generated icon: SVG path d data plus the side length of its square design box.
IconView: A declarative icon. See the module docs.
IconWidget: The retained widget for an IconView.
ImageError: Error decoding image bytes via ImageSource::decode.
ImageSource: A decode-once, cheaply-clonable handle around a decoded RGBA8 image.
ImageView: A declarative description of an image.
ImageWidget: The retained widget for an ImageView.
IndexedStackView: A declarative indexed stack. See IndexedStack and the module docs.
IndexedStackWidget: The retained widget for an IndexedStackView.
KeepAliveHandle: A keep-alive request bound to the lazy-list row it was acquired in. See the module docs.
KeepAliveView: A keep-alive wrapper. See keep_alive.
KeepAliveWidget: The retained widget for a KeepAliveView: the child’s pod and the handle bound to its row (None outside a lazy list).
ListView: A declarative, virtualized vertical list. See the module docs.
ListViewWidget: The retained widget for a ListView: the materialized window of children (children[j] renders item keys[j]), the scroll offset + cached viewport, and the same fling bookkeeping as crate::ScrollWidget.
OverlayPlacement: A resolved placement request: which side, how it lines up, how far off the anchor it sits, and how it may move to stay inside the area.
OverlayPortalView: A declarative overlay portal. See overlay_portal.
OverlayPortalWidget: The retained widget for an OverlayPortalView.
OverlaySlot: One floated surface an owner hosts: the pod, where it goes, and the routing of the input the root sends back to it.
PaddingView: A declarative padding container. See the module docs.
PaddingWidget: The retained widget for a PaddingView.
PanZoomController: A cloneable handle onto a PanZoomView: drive it with jump_to/fit_to_bounds/ fit_rect and read where it stands with transform. Every clone shares one state, so the handle an app keeps in its state and the one attached to the view are the same.
PanZoomTransform: Where the content sits: view = offset + scale · content.
PanZoomView: A declarative pan/zoom container. See the module docs.
PanZoomWidget: The retained widget for a PanZoomView.
PlatformViewView: A declarative platform-view slot. See the module docs.
PlatformViewWidget: The retained widget for a PlatformViewView. See the module docs.
RadioView: A declarative radio button. See the module docs.
RadioWidget: The retained widget for a RadioView.
RepaintBoundaryView: A declarative retained-page boundary. See the module docs.
RepaintBoundaryWidget: The retained widget for a RepaintBoundaryView.
SafeAreaView: A declarative safe-area container. See the module docs.
SafeAreaWidget: The retained widget for a SafeAreaView.
ScaffoldView: A declarative scaffold. See the module docs.
ScaffoldWidget: The retained widget for a ScaffoldView.
ScrollInfo: A scroll observation snapshot handed to ScrollView::on_scroll.
ScrollView: A declarative vertical scroll surface. See the module docs.
ScrollWidget: The retained widget for a ScrollView: a thin owner of the viewport geometry (its own size, the child’s measured content, the child origin) around the crate’s shared scroll surface core, which runs the drag, fling, overscroll, nested-claim and controller machinery (the module docs’ Shared core).
ShieldView: A declarative z-shield wrapper. See shield and the module docs.
ShieldWidget: The retained widget for a ShieldView. See shield.
SizedBoxView: A declarative fixed-size box, optionally wrapping a child. See the module docs.
SizedBoxWidget: The retained widget for a SizedBoxView.
SliderView: A declarative slider. See the module docs.
SliderWidget: The retained widget for a SliderView.
SliverBoxView: A box child adapted to the sliver protocol. See the module docs.
SliverBoxWidget: The retained widget for a SliverBoxView: the child’s pod, plus whether the last sliver layout cut the child (so paint clips it).
SliverFillRemainingView: A box child filling the rest of the viewport. See the module docs.
SliverFillRemainingWidget: The retained widget for a SliverFillRemainingView: the child’s pod, the mode, and whether the last sliver layout cut the child (so paint clips it).
SliverFixedExtentListView: A lazy list of equal-extent rows. See the module docs.
SliverFixedExtentListWidget: The retained widget for a SliverFixedExtentListView: the materialised rows, the constraints rebuild windows against, and the near-edge state.
SliverGridView: A lazy grid of equal cells. See the module docs.
SliverGridWidget: The retained widget for a SliverGridView: the materialised cells, the constraints rebuild windows against, and the delegate.
SliverListView: A lazy, keyed list of rows that size themselves. See the module docs.
SliverListWidget: The retained widget for a SliverListView: the materialised rows and their identities, the parked keep-alive rows, the measured extents, the anchor, and the near-edge state.
SliverPaddingView: Insets around a sliver. See the module docs.
SliverPaddingWidget: The retained widget for a SliverPaddingView.
SliverPersistentHeaderDelegate: What a sliver_persistent_header shows: its extent range and how to build its content for a shrink offset — Flutter’s SliverPersistentHeaderDelegate.
SliverPersistentHeaderView: A sliver header with a min/max extent. See the module docs.
SliverPersistentHeaderWidget: The retained widget for a SliverPersistentHeaderView: the content’s pod, the build inputs it holds and the ones the last layout asked for, and a floating header’s effective scroll offset.
StackView: A declarative z-ordered stack. See the module docs.
StackWidget: The retained widget for a StackView.
TextInputView: A declarative text field, single-line by default. See the module docs.
TextInputWidget: The retained widget for a TextInputView.
TextView: A declarative description of a run of text.
TextWidget: Retained widget for TextView: caches the shaped TextLayout produced during layout for reuse in paint.
TextureView: A declarative view of an externally rendered scene texture. See the module docs.
TextureWidget: The retained widget for a TextureView.
ViewportWidget: The retained widget for a CustomScrollView: the children’s pods and what the last layout decided for each, the scroll position, and the shared scroll core (the module docs).

Enums§

Axis: The axis a FlexView lays its children along.
BorderStyle: A border’s stroke style, set via ContainerView::border_style. Solid by default; ContainerView::border alone (with no .border_style call) keeps the pre-existing solid-only behavior unchanged.
ButtonStyle: Visual style variant for Button. Additive: the default preserves today’s only look byte-for-byte under every theme. See the module docs for the full role-mapping intent.
CrossAxisAlignment: How children are aligned along the cross axis.
ImageFit: How an Image’s laid-out box relates to its source’s natural pixel size at paint time.
MainAxisAlignment: How children are distributed along the main axis.
OverlayAlign: How a floated surface lines up with its anchor on the cross axis.
OverlayAnchor: What a slot places its surface against.
OverlaySide: The side of the anchor a floated surface opens on.
ScrollAxis: The axis a CustomScrollView scrolls along, re-exported so its axis builder needs no direct frust-core import. The axis a viewport scrolls along — Flutter’s Axis, as a sliver’s SliverConstraints.axis reads it.
SliverGridDelegate: How a sliver_grid divides its cross axis into cells — Flutter’s two stock SliverGridDelegates. Spacings are logical px; child_aspect_ratio is a cell’s cross-axis extent over its main-axis extent (width over height in a vertical grid).
TextureFit: How a TextureView places its texture in the widget’s box.

Constants§

DEFAULT_CACHE_EXTENT: How far past each end of the visible region a CustomScrollView lays children out by default, in logical px — Flutter’s RenderAbstractViewport.defaultCacheExtent.
DEFAULT_MAX_SCALE: The largest scale a PanZoomView allows unless max_scale says otherwise.
DEFAULT_MIN_SCALE: The smallest scale a PanZoomView allows unless min_scale says otherwise.
DEFAULT_OFFSET: The default gap between an anchor and the surface placed against it, in logical px.
DEFAULT_PADDING: The default margin a placed surface keeps from every edge of the area, in logical px — the viewport padding the collision clamp works against.

Functions§

Align: Position child within the align’s box per alignment.
Button: PascalCase alias for button, matching the container view-fn vocabulary.
Checkbox: PascalCase alias for checkbox.
Column: A vertical flex (Axis::Vertical) of inflexible children — the common sugar. Use FlexView::new with flexible children when some should expand.
GestureDetector: Wrap child in a gesture detector (no recognisers until one is attached, e.g. with GestureDetectorView::on_tap or GestureDetectorView::on_long_press).
Icon: PascalCase alias for icon.
IconButton: PascalCase alias for icon_button, matching the container view-fn vocabulary (see crate::Icon/crate::Button’s own aliases).
Image: Create an image view over a decoded ImageSource, defaulting to ImageFit::Contain.
IndexedStack: Keep every child of children mounted and show only the one at index.
Padding: Inset child by insets on each edge.
Radio: PascalCase alias for radio.
Row: A horizontal flex (Axis::Horizontal) of inflexible children — the common sugar. Use FlexView::new with flexible children when some should expand.
SizedBox: A box that forces width/height where Some, passing through where None.
Slider: PascalCase alias for slider.
Stack: Overlay children in a z-order stack (first child at the bottom).
TextInput: PascalCase alias for text_input.
button: Create a button labelled label that runs on_press against the app state when released inside its bounds.
canvas: Create a canvas that paints by calling paint(scene, size, ctx) every time it actually repaints — full-bleed by default (see CanvasView::expand). See the module docs for the local-space/clip contract and the builder methods that round out the declaration.
checkbox: Create a checkbox reflecting checked, labelled label, that fires on_toggle(state, !checked) on release inside its bounds.
colored_box: A childless ContainerView — the leaf/background family. See the module docs.
column: An empty vertical flex, ready for fluent children (no any(..) wrapping).
container: Wrap child in a ContainerView — the single-child wrapper family. See the module docs.
custom_scroll_view: A vertical CustomScrollView over slivers.
divider: A horizontal hairline of color, [DEFAULT_THICKNESS] (1px) thick, filling the available width. color is a required argument, not defaulted — see the module docs’ “Color: required, no Theme dependency” section.
flexible: A flexible child taking flex proportional shares of the free main-axis space.
icon: Create an icon view over any IconData source (a generated IconSource, or a user path via IconData::from_path), at the default 24.0 logical size with the theme’s on_surface color.
icon_button: Create a pressable vector icon painting mark, labelled label for accessibility, that runs on_press against the app state when released inside its bounds. See the module docs.
indexed_stack: An empty indexed stack selecting index, ready for fluent children (no any(..) wrapping). See IndexedStack.
inflexible: An inflexible child, sized to its natural main-axis extent.
keep_alive: Keep child’s lazy-list row alive outside the list’s window (see the module docs). Transparent everywhere else: child is laid out, painted and routed to exactly as if it stood alone.
keyed: An inflexible child tagged with a stable ChildKey, for a list whose items reorder, insert, or delete between frames.
list_view: Create a virtualized ListView — the free-function spelling of ListView::builder. builder may return any View; it is erased here.
overlay_portal: Float overlay above the whole app, anchored to child’s bounds — the declarative half of the portal.
pan_zoom: Wrap child in a pan/zoom view: identity transform, scale bounds DEFAULT_MIN_SCALE..=DEFAULT_MAX_SCALE, no inertia.
place: Place a content-sized surface against anchor inside area.
platform_view: Reserve layout space for a native platform view created by view_type (the "dev.frust.<Factory>" convention), filling its container by default (see [SlotSize::Expand]). See the module docs for the full builder contract.
radio: Create a radio reflecting selected, labelled label. Attach a callback with RadioView::on_select; a radio with none is inert (still paints and captures the press, but never fires) — the same optional-callback shape a design system’s own list-item row uses.
repaint_boundary: Paint child through a retained-page boundary: its body is recorded once and composited from the renderer’s cached page on every later frame where nothing under it changed — see the module docs. Layout, hit-testing and semantics are the child’s own, unchanged.
row: An empty horizontal flex, ready for fluent children. See [column].
safe_area: Pad child by the window’s resolved safe-area insets — all four edges enabled by default (opt an edge out with .left/.top/.right/.bottom), never less than .minimum (zero by default) on an enabled edge. The enabled edges’ insets are consumed: child’s subtree reads zero safe-area padding there (see the module docs).
scaffold: Scaffold body under no chrome — attach app_bar/bottom_bar/fab with the builder methods below.
scroll_view: Wrap child in a vertical ScrollView — the free-function spelling of ScrollView::new.
selection_toolbar: Build the baseline framework-drawn selection-toolbar view for request: a pill of text buttons for whichever verbs request.actions enables. See the module docs.
shield: Mark child as frust content that must keep receiving pointer input even where it paints over an interactive platform-view slot (the z-shield — see the module docs).
slider: Create a slider at value (clamped to 0.0..=1.0) that fires on_change(state, new_value) as it is dragged.
sliver_box: Adapt child — any box view — to a sliver: it scrolls by its own main-axis extent and paints the part of itself inside the viewport. See the module docs.
sliver_fill_remaining: Fill what is left of the viewport with child — with a scroll body by default; see SliverFillRemainingView::has_scroll_body and the module docs.
sliver_fixed_extent_list: A lazy list of item_count rows, each item_extent logical px along the scroll axis, whose row at index is builder(index) — reconciled by item index, with ListView::builder’s contract. See the module docs.
sliver_fixed_extent_list_keyed: sliver_fixed_extent_list reconciled by the stable key key_of(index) instead of by item index, with ListView::builder_keyed’s contract: key_of runs once per materialised row per rebuild, and a duplicate key in one window trips a debug_assert!. See the module docs.
sliver_grid: A lazy grid of item_count cells, the cell at index being builder(index), laid out by SliverGridView::delegate (two square cells per row unless set) — reconciled by item index. See the module docs.
sliver_grid_keyed: sliver_grid reconciled by the stable key key_of(index) instead of by item index, with sliver_fixed_extent_list_keyed’s contract.
sliver_list: A lazy list of item_count rows, the row at index being builder(index) keyed by key_of(index), each as long along the scroll axis as it lays itself out. See the module docs.
sliver_padding: Surround sliver with insets: the main-axis insets scroll before and after it, the cross-axis insets narrow it. A NaN, infinite or negative inset is treated as 0.0. See the module docs.
sliver_persistent_header: A header sliver that shrinks from delegate.max_extent to delegate.min_extent as it scrolls, its content rebuilt by delegate.build for the current shrink offset. It scrolls away like a box unless made pinned or floating. See the module docs.
stack: An empty z-order stack, ready for fluent children (no any(..) wrapping).
text: Create a text view rendering content with default styling (16px). Its glyph color defaults to the active theme’s on_surface role, falling back to black when no theme is set; an explicit TextView::color overrides both.
text_input: Create a controlled text field showing value that fires on_change(state, new_text) on every edit.
texture_fit_rect: The rect (relative to the widget’s own origin) a natural-sized texture is drawn into inside a dest-sized box under fit.
texture_view: A view drawing the scene texture registered under scene_texture_id, full-bleed and TextureFit::Contain by default. See the module docs.