Struct Image 

pub struct Image { /* private fields */ }

An image, fitted by fit into whatever box it ends up with.

Implementations

impl Image

pub fn new(image: ImageHandle) -> Self

An image at its own size, fitted with BoxFit::Contain by default.

pub fn memory(bytes: &'static [u8]) -> Self

An image decoded from embedded bytes — what include_bytes! gives, and the answer to “how do I just show my logo”.

Image::memory(include_bytes!("../assets/logo.png")).width(96.0)

The bytes are decoded once per process, not once per frame. A view is rebuilt every frame and decoding a PNG is not free, so the result is kept in a shared store keyed by where the bytes live — see frus_core::cached for why an address is the right key and why the 'static bound is what makes it sound.

Failure paints nothing. A file that is not an image does not become one on the next frame, so the failure is remembered rather than retried, and the widget occupies whatever box it was given without drawing into it. That is the reference’s behaviour for an image with no error widget supplied, and Image::error is how an application asks what went wrong.

Decoded at the size shown: see Image::cache_width.

A large picture is decoded on a background thread, so the frame that first shows it does not stop for the tens of milliseconds a photograph takes: until it is there the image is State::Loading and shows its placeholder, as a network image does, and the frames keep coming. One of at most QUICK_DECODE_PIXELS — an icon, a logo, an avatar — is decoded at once, since it takes less time than the thread would to pick it up and a blink as it came in would be the only difference. The Web, which has no threads, decodes every picture at once.

Needs the images feature, which is on by default. Without it this reports a missing decoder rather than panicking — the same rule the bundled fonts follow.

pub fn network(url: impl AsRef<str>) -> Self

An image fetched over the network, decoded and shown when it arrives.

Image::network("https://example.com/ada.png").width(240.0)

The first frame that asks starts the request and reports State::Loading; every later frame is a lookup. That is what makes this safe to write in a view, which runs sixty times a second — a fetch per frame would be sixty requests for one picture. The interface keeps drawing while anything is in flight, so the frame that shows the picture does happen without the application arranging it.

There is no loading or error slot here, and that is the framework’s model rather than a gap. A view is a function of state, and this state is readable: Image::state answers, and the application writes the match it would have written anyway.

let photo = Image::network(&url).width(240.0);
match photo.state() {
    State::Loading => CircularProgressIndicator::new().boxed(),
    State::Failed(why) => text(why).boxed(),
    State::Ready => photo.boxed(),
}

Size it before asking: the size is what it is fetched and decoded at, and one set after the question is a second request at the new size.

A closure stored in the widget would say the same thing in a place the application cannot see it, and would need the widget to carry the message type for the sake of a branch the view can already take.

The request starts the first time the image is asked about — laid out, painted, or asked its state — since that is when the size to decode it at is known (see Image::cache_width). An image built and dropped without any of those fetches nothing.

Needs a registered fetcher — frus_core::set_image_fetcher — which the shell installs on the way up when built with the net feature. Without one this fails with a message saying so, rather than waiting for ever.

pub fn state(&self) -> State<'_>

Where this image has got to: here, on its way, or never coming.

An embedded image is State::Loading only while a large one decodes on its thread; Image::network is loading until its bytes are here and decoded.

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

Why there are no pixels, if there are none.

An application that wants to put something else in the gap — a placeholder, a message, a retry — asks here and builds it itself. That is a match in the view rather than a closure the widget stores, which is the honest shape while the pixels are something the application already holds.

An image still loading has no error: it has not failed, it has not arrived. Image::state is the one that tells the three apart.

pub fn handle(&self) -> Option<ImageHandle>

The decoded pixels, once they are here: None while they are on their way or when they will never come. This is how a picture loaded by Image::memory or Image::network is painted by something other than an Image — a decoration, an avatar — with the same loading and the same cache (milestone 647).

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

Sets the width, in logical pixels. With no height, the height follows from the image’s own ratio.

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

Sets the height, in logical pixels. With no width, the width follows from the image’s own ratio.

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

Both at once.

pub fn cache_width(self, pixels: u32) -> Self

Decodes the picture this many physical pixels wide, whatever the file’s own width; the height follows from the image’s own ratio unless cache_height is given too, in which case the picture is decoded at the smallest size, at its own ratio, that covers both. Never larger than the file.

A twelve-megapixel photograph shown as a thumbnail does not need 48 MB of pixels, and on a phone a grid of them is how an application is killed for memory.

Without it, an image given a width or a height is already decoded at that size times the screen’s pixel ratio, rounded up a little; this is for one that is not — sized by its parent — or one that wants a different size. An image given neither, and none of these, is decoded at the file’s own size, which is also its own size on screen: setting this on one changes the size it takes.

Only an image this widget decodes — Image::memory, Image::network — is affected. One made with Image::new is the pixels the application gave it.

pub fn cache_height(self, pixels: u32) -> Self

cache_width, for the height.

pub fn full_resolution(self) -> Self

Decodes the file at its own size, however small the box: for a picture that is shown larger than its box says — under a zoom, a scale transform, a hero flight to a full-screen view — and must stay sharp there.

pub fn fit(self, fit: BoxFit) -> Self

Changes the fit mode.

pub fn alignment(self, alignment: impl Into<AlignmentGeometry>) -> Self

Where the image sits in a box it does not fill, and which part of it survives a box it overflows. Centre by default, as in the reference.

It is the same anchor either way round: aligning to the top means the top of the box for a letterboxed image and the top of the image for a cropped one, which is the answer a photograph of a person wants in both cases.

pub fn tint(self, tint: Color) -> Self

A multiplied tint, white leaving it unchanged — for bitmap icons, say.

pub fn opacity(self, opacity: f32) -> Self

Draws the image at a fraction of its opacity, 1.0 being fully opaque.

Unlike a group opacity this needs no layer: an image is one primitive, so the fade goes into the tint it is already multiplied by.

pub fn semantic_label(self, label: impl Into<String>) -> Self

What a screen reader says instead of the picture.

A picture with no label is a picture nobody reading by ear can see, and until this existed every image in every application was one: the vocabulary had frus_core::Role::Image in it and nothing ever emitted it.

Say what the picture is, not that it is a picture — a reader is already told the role. If it carries no meaning of its own, do not label it: reach for exclude_from_semantics instead.

pub fn exclude_from_semantics(self, exclude: bool) -> Self

Leaves the image out of the tree a screen reader walks.

The right answer for decoration — a divider, a texture, a shape behind a heading. Announcing those interrupts a reader with something that was never meant to be read, and an empty label would still announce the role. This is the reference’s excludeFromSemantics, and like it, it wins over any label given.

pub fn match_text_direction(self, match_direction: bool) -> Self

Mirrors the image horizontally when the reading direction is right-to-left.

Off by default, which is the reference’s default and the right one: an image is a picture rather than a run of text, and a photograph of a person does not want to be flipped because the interface is in Arabic. It is a per-image decision, so it is a per-image switch.

Turn it on for a picture that points: an arrow meaning forward, a speech bubble with a tail, a hand indicating the next step. Those follow the direction the reader’s eye travels, and in RTL that is the other way round.

pub fn placeholder(self, placeholder: impl Into<ImagePlaceholder>) -> Self

What stands in while the pixels are on their way, and what the picture crosses over when they arrive.

Takes a colour, a Skeleton, or another Image — see ImagePlaceholder. Without one the box stays empty and the picture appears in a single frame, which is what an image has always done here and what a list of thumbnails should not do.

Image::network(url).width(120.0).placeholder(Skeleton::new().height(90.0))

pub fn fade_duration(self, seconds: f32) -> Self

How long the crossing takes, in seconds. IMAGE_FADE — the reference’s 700 ms — unless a caller says otherwise. 0.0 is a hard cut with a placeholder before it.

pub fn fade_curve(self, curve: Curve) -> Self

The crossing’s curve; Curve::ease_out by default, so the picture arrives quickly and settles.

Trait Implementations

impl From<Image> for ImagePlaceholder

fn from(image: Image) -> Self

Converts to this type from the input type.

impl<Msg> Widget<Msg> for Image

fn anim_target(&self) -> Option<f32>

Where the crossing is going: all the way over once the pixels are here, and nowhere at all until then.

Only claimed when there is a placeholder, so an image without one costs the runtime nothing and keeps the behaviour it has always had.

fn anim_duration(&self) -> f32

The crossing has a duration in one direction only.

Coming in it takes its time: that is the whole point. Going back — a source replaced at the same place in the tree, so the widget is loading again — it is instant, because there is nothing left to cross from. The pixels of the picture that was there are already gone by the time this is asked; tweening down would fade the placeholder in over three quarters of a second while nothing else was drawn, which reads as a stall rather than as a change.

This is also what answers do not restart on a rebuild. The value lives against the widget’s place in the tree and survives every rebuild, so nothing restarts while the source stands still; and a source that changes passes through not ready, which resets it to nought in one frame and lets the next arrival cross properly. No record of which image this timeline is about is needed, because the journey through the middle is the record.

fn style(&self) -> Style

Layout style (handed to frus-layout).

fn children(&self) -> &[Box<dyn Widget<Msg>>]

The widget’s children (possibly empty).

fn paint(&self, bounds: Rect, status: Status, theme: &Theme, scene: &mut Scene)

Paints the widget’s own decoration, according to its status (hover / focus / cursor / selection) and the current theme.

fn anim_curve(&self) -> Curve

Easing curve of the animated value’s transition (anim_target). Default: linear.

fn on_click(&self) -> Option<Msg>

Message to emit on click (None = not clickable).

fn semantics(&self) -> Option<SemanticsProperties>

The widget’s accessibility annotation (role, label, value, state), exposed to assistive technologies through the AccessKit tree. None = no semantics of its own (a layout container — its children, though, may have some). See frus_core::SemanticsProperties.

fn opaque(&self) -> bool

Whether a press that lands on this widget and on nothing inside it stops here.

fn key(&self) -> Option<u64>

Stable identity key (independent of the position among siblings). None = positional identity. See crate::Keyed.

fn debug_name(&self) -> &'static str

Short name of the widget — for the inspector and diagnostic dumps. Defaults to the name of the concrete type, without module path or generics (each implementation gets its own monomorphised copy of this default body). Transparent wrappers (Box, crate::Keyed…) delegate to their content.

fn describes(&self) -> Option<Description>

What this widget says about its child’s subtree, when it knows something the child cannot know about itself — the crate::Semantics wrapper, and nothing else so far.

fn on_edit(&self, _edit: &mut Edit, _key: &Key) -> Option<Msg>

Applies a key to the focused widget: mutates the edit state (cursor/selection) and returns a message if the value changes.

fn positional_click( &self, _local_x: f32, _local_y: f32, _width: f32, _height: f32, ) -> Option<Msg>

Positional click: a message emitted according to where the click landed (local coordinates from the widget’s top-left corner, within the width × height box), taking priority over on_click. For clickable sub-regions — e.g. the suffix icon of a crate::TextField (clear / reveal) or a chart point (milestone 221). None (the default) = no sub-region; the shell falls back to on_click.

fn cursor_icon( &self, _local_x: f32, _local_y: f32, _width: f32, _height: f32, ) -> Option<Cursor>

Shape of the system cursor wanted at the local position (local_x, local_y) inside the widget’s width × height box (milestone 205): Some(Cursor::Pointer) over a clickable sub-region (a suffix icon…), None (the default) = no opinion, the shell keeps the default cursor. Does not affect clicking; this is purely the pointer’s appearance on hover.

fn cursor_at( &self, _local_x: f32, _local_y: f32, _width: f32, _scroll_cursor: usize, ) -> Option<usize>

Cursor index matching a local position (px from the widget’s top-left corner) — for placing the caret on click. local_y picks the line in a multi-line field (ignored on a single line).

fn text_metrics( &self, _width: f32, _cursor: usize, ) -> Option<(f32, f32, f32, f32)>

SingleChildScrollView metrics of a multi-line field, for a widget width and a cursor: (content height, visible box height, caret top, caret height), in content space (px). The shell uses them to register the scrollable region and to keep the caret in view. None otherwise.

fn text_viewport(&self, _rect: Rect) -> Option<Rect>

Frame (input box) of a multi-line field within its rect — the area where the text scrolls, below the label. Used to place the scrollbar and the scrollable region exactly on the box. None otherwise.

fn caret_vertical( &self, _width: f32, _cursor: usize, _down: bool, _page: bool, _goal_x: Option<f32>, ) -> Option<(usize, f32)>

Moves the caret vertically in a multi-line field and returns (new index, visual column used).

fn selected_text(&self, _edit: &Edit) -> Option<String>

The currently selected text (for copy/cut).

fn text_value(&self) -> Option<&str>

The field’s whole value, if this widget is a text field — to give the IME its input context (suggestions). None otherwise.

fn selection_text(&self) -> Option<&str>

The words this widget shows, if it takes part in a SelectionArea: a Text, and nothing that is not made of words. The walk registers such a widget as a text stop when it is inside an area, so that a selection can begin, end and pass through it.

fn selection_hit( &self, _local_x: f32, _local_y: f32, _width: f32, ) -> Option<usize>

The character boundary of selection_text nearest a local position (px from the widget’s top-left corner) in a box width wide — the layout the widget was drawn with, which is what a press is hit against.

fn selection_grip( &self, _width: f32, _index: usize, _start: bool, ) -> Option<SelectionHandle>

The handle that hangs from character boundary index of this widget’s words — the start handle when start, the end handle otherwise — in local coordinates, for a widget width wide: where it is painted, and so where a finger takes it. None for anything that is not a text.

fn area_toolbar( &self, _context: ToolbarContext, ) -> Option<Option<&dyn Widget<Msg>>>

The bar a SelectionArea offers over its selection, for context, when the application has said what it holds (SelectionArea::selection_toolbar): Some of the bar, or Some(None) for no bar at all. None for anything else — and for an area that was told nothing — whose texts then offer Copy and Select all.

fn region_toolbar( &self, _context: ToolbarContext, _width: f32, _range: (usize, usize), ) -> Option<(Rect, &dyn Widget<Msg>)>

The bar over the part of a selection area’s selection that lies in this widget — range, in characters — for context, and the box it is placed against in local coordinates, for a widget width wide. None for anything that is not a text, or when the list for context is empty.

fn takes_typing(&self) -> bool

Whether this widget takes typing: a field that can be changed, which is what the software keyboard is for. A text field that may only be read and selected — a read_only one, a Text made selectable — answers false: it has a caret and a selection, and no use for a keyboard sliding up over the words being read.

fn replace_value(&self, _value: String) -> Option<Msg>

The message that puts value in this field: the one typing would have produced, for a value the framework restores rather than the user typing it.

fn word_at(&self, _index: usize) -> Option<(usize, usize)>

Range (start, end) of the word around the given index (for double-click).

fn selection_handles( &self, _width: f32, _edit: &Edit, _scroll_y: f32, ) -> Option<[SelectionHandle; 2]>

The two handles of the selection in edit, start then end, for a field width wide whose content is scrolled down by scroll_y — where they are painted, and so where a finger takes them. None when there is no selection, or this is not a text field.

fn selection_toolbar( &self, _context: ToolbarContext, ) -> Option<&dyn Widget<Msg>>

The bar this field shows over its selection (Cut, Copy, Paste, Select all — see crate::ToolbarItem) for context, or None when there is none to show: this is not a text field, or the application’s list for that context is empty.

fn selection_anchor( &self, _width: f32, _edit: &Edit, _scroll_y: f32, ) -> Option<Rect>

The box the bar is placed against, in the field’s local coordinates: the selection’s, or the caret’s when nothing is selected. Like selection_handles it is the paint’s own geometry.

fn edit_action(&self) -> Option<EditAction>

The editing action pressing this widget performs on the focused field, for a button of the bar that carries no message (see crate::EditAction).

fn shortcut_bindings(&self) -> &[(KeyStroke, Intent)]

Keystrokes this subtree binds to intents — see crate::Shortcuts.

fn shortcut_callbacks(&self) -> &[(KeyStroke, Msg)]

Keystrokes this subtree binds straight to messages — see crate::CallbackShortcuts.

fn action_bindings(&self) -> &[(Intent, Msg)]

Intents this subtree answers — see crate::Actions.

fn action_listeners(&self) -> &[(Intent, Msg)]

Intents this subtree watches without answering — see crate::ActionListener.

fn on_keystroke(&self) -> Option<Rc<dyn Fn(KeyStroke) -> Option<Msg>>>

Every keystroke reaching this subtree, handed to a closure — see crate::KeyboardListener. None (the default) is not a listener.

fn focusable(&self) -> bool

If true, the widget can take keyboard focus (click or Tab).

fn on_focus_change(&self, _focused: bool) -> Option<Msg>

Message for the focus arriving in or leaving this widget’s subtree (milestone 660) — the reference’s onFocusChange: true when the focused widget is now this one or inside it and was not, false the other way. The shell asks once a frame, after the focus has moved, every widget on the two paths from the root that the move changed, the one that lost it first.

fn on_tap_outside(&self) -> Option<Msg>

Message for a press outside this widget while it holds the focus (milestone 660) — the reference’s onTapOutside: sent before the press moves the focus.

fn autofocus(&self) -> bool

If true, a focusable widget takes the focus when it appears: a menu’s first row when the menu opens, a field on a screen made to type into (milestone 605). Where the focus came from is remembered, and it goes back there when this one goes.

fn descendants_focusable(&self) -> bool

If false, nothing inside this subtree can take focus — the reference’s ExcludeFocus. A dimmed panel behind a sheet is still drawn and still measured; it simply stops being somewhere Tab can land.

fn focus_skip_traversal(&self) -> bool

If true, this subtree’s focus stops are skipped by Tab while remaining focusable by a click — the reference’s ExcludeFocusTraversal. The two are separate questions: a toolbar button may be reachable with the pointer and still not belong in the keyboard’s order.

fn focus_order(&self) -> Option<f32>

A traversal order for this subtree’s focus stops, smallest first — the reference’s NumericFocusOrder. None leaves them in tree order, which is where everything sits until someone says otherwise.

fn focus_group(&self) -> bool

If true, this subtree is a traversal group: an order set inside it is resolved among its own members and nowhere else, so a reordered dialog does not reshuffle the page behind it.

fn autofill_hints(&self) -> &[AutofillHint]

What this field is for, so the platform can fill it in — see AutofillHint. Empty (the default) is a field that takes no part in autofill at all.

fn autofill_group(&self) -> bool

If true, this subtree’s fields are one form — the reference’s AutofillGroup. A service shown a password with no username beside it has nothing to save the pair under.

fn draws_own_focus(&self) -> bool

If true, the widget draws its focus indicator itself (the driver then does not stroke the generic ring). E.g. TextField.

fn draggable(&self) -> bool

If true, the widget responds to pointer dragging (sliders, handles).

fn drag_track(&self) -> DragTrack

Where along a draggable widget its drag lands (milestone 648): how far in from each end the travel starts, and whether it runs from the right in a right-to-left reading direction. The fraction on_drag and its edges are given is measured along that travel. The default is the whole width, left to right.

fn on_thumb_drag( &self, _thumb: usize, _moment: ThumbDrag, _fraction: f32, ) -> Option<Msg>

Message for a moment of a drag on one of this widget’s thumbs (milestone 651), on a DragMode::Thumbs track: thumb is the one the press picked, 0 for the start, and fraction the pointer’s place along the travel. A press that has picked none yet sends nothing.

fn on_drag(&self, _fraction: f32) -> Option<Msg>

Message produced while dragging, fraction being the relative horizontal position (0.0..=1.0) within the widget’s bounds.

fn on_drag_start(&self, _fraction: f32) -> Option<Msg>

Message produced when a value drag begins — on the press, before the first on_drag.

fn on_drag_end(&self, _fraction: f32) -> Option<Msg>

Message produced when a value drag ends — on the release, with the fraction the pointer finished on.

fn on_drag_delta(&self, _dx: f32) -> Option<Msg>

Message produced by a horizontal drag expressed as a delta: dx is the movement (logical px) since the last event. For handles that accumulate (column resizing), unlike on_drag (an absolute fraction, e.g. a slider). The shell tries it before on_drag; a widget implements only one of the two.

fn hero_tag(&self) -> Option<u64>

If this widget is a shared element, its tag. Two heroes with the same tag on the two sides of a route transition are one thing in two places. See crate::Hero.

fn drag_payload(&self) -> Option<u64>

If this widget can be picked up and dropped elsewhere, what it carries. See crate::Draggable.

fn drag_needs_long_press(&self) -> bool

Does this item lift on a long press rather than on the first movement? The answer inside a scrollable, where a plain drag belongs to the scroll.

fn drag_ghost_opacity(&self) -> f32

How solid the item left behind looks while a copy of it is being dragged.

fn on_dropped(&self, _accepted: bool) -> Option<Msg>

Message sent when a drag of this item ends, true if a target took it.

fn drop_zone(&self) -> bool

Is this widget a drop target? See crate::DragTarget.

fn accepts_drag(&self, _payload: u64) -> bool

Would this target take payload? Only asked of a drop target.

fn on_drop(&self, _payload: u64) -> Option<Msg>

Message sent when an accepted item is dropped on this target.

fn accepts_files(&self, _paths: &[PathBuf]) -> bool

Would this target take these files, dragged onto the window from outside the application? Only asked of a drop target; none takes files unless it says so. See crate::DragTarget::on_files.

fn on_files_dropped(&self, _paths: Vec<PathBuf>) -> Option<Msg>

Message sent when accepted files are dropped on this target.

fn reorder_index(&self) -> Option<usize>

If this widget is a reorderable header, its column index. The shell uses it to identify the source column (on press) and the target column (under the pointer on release) of a reordering drag.

fn on_reorder(&self, _to: usize) -> Option<Msg>

Message emitted when this header (the source) is dropped on column to. The widget knows its own index and the on_reorder(from, to) callback.

fn reorder_axis(&self) -> ReorderAxis

Movement axis of this reorderable (default ReorderAxis::Horizontal): the shell orients the drag preview (ghost + insertion indicator) accordingly. Kanban cards return ReorderAxis::Vertical.

fn reorder_inserts(&self) -> bool

Is a horizontal reorderable dropped between its neighbours, like a list’s row, rather than into the place of the one under the pointer, like a table’s column? false by default, which is the table.

fn reorder_draggable(&self) -> bool

Can this reorderable be picked up as a drag source? true by default for every reorderable. A target-only slot — the drop zone at the end of a Kanban column — returns false: a card can be dropped there, not lifted from it (otherwise the drag would raise an empty ghost that moves nothing).

fn reorder_droppable(&self) -> bool

Can this reorderable be dropped onto? true by default, and the mirror image of reorder_draggable: a source-only grip — a list row’s drag handle — returns false.

fn reorder_announcement(&self, _to: usize) -> Option<String>

What to say to a screen reader once this reorderable has been moved to to — the spoken counterpart of the ghost, for someone who cannot see it land.

fn announce(&self) -> Option<String>

Text to announce to the screen reader when this widget is activated (mouse click or Enter/Space) — a live region reads it out loud. Describes the effect the activation produced (“Sorted by Name ascending”, “All rows selected”), for the blind user who cannot perceive the visual change. None = nothing to announce (the default).

fn stack(&self) -> bool

If true, the widget is a stack: its children are superimposed layers (the same box), rendered in order (the last one on top).

fn sticky_header(&self) -> bool

If true, the widget is a section with a sticky header (crate::StickyHeader): its first child is painted, and takes taps, at the top of what is visible of the section, over the second (milestone 602).

fn custom_layout(&self) -> Option<CustomLayout<'_>>

If the widget places its children with a function — a crate::CustomMultiChildLayout — the function and one key per child. The children are then laid out and placed in the walk, by the function, and not in this node’s layout (milestone 601).

fn continuous(&self) -> bool

If true, the widget animates continuously (driven by time, not by a target): the framework keeps redrawing. E.g. CircularProgressIndicator.

fn repaint_boundary(&self) -> bool

If true, this widget is a repaint boundary: its subtree is cached (primitives + interaction maps) and reused as is as long as its geometry and the interaction state of its descendants do not change — a widget animating elsewhere no longer forces it to repaint. See crate::Container::repaint_boundary and paintcache.rs.

fn scroll_content(&self) -> Option<&dyn Widget<Msg>>

If the widget is a scrollable container, returns its content.

fn virtual_list(&self, _viewport: Size) -> Option<VirtualList<'_, Msg>>

If the widget is a virtualised list, returns its description (item count, height, factory). Only the visible items are built.

fn page_view(&self) -> Option<PagedView<'_, Msg>>

If the widget is a paged view, returns its description (page count, axis, factory). Like a virtualised list, only the visible pages are built.

fn on_page_changed(&self, _page: usize) -> Option<Msg>

Message sent by a paged view when the page on screen changes.

fn on_scroll(&self, _position: ScrollPosition) -> Option<Msg>

Message sent by a scroll region when its offset changes — the reading half of crate::ScrollPosition.

fn scroll_grain(&self) -> f32

How far this region must move before it says so again, in pixels; 0 — the default — reports every change.

fn intrinsic(&self) -> Option<(IntrinsicAxis, Option<f32>)>

If the widget takes one axis from its content’s preferred size, returns that axis and the step its measurement is rounded up to. See crate::Intrinsic.

fn overflow_box(&self) -> Option<Overflow>

If the widget lays its child out to constraints of its own, which the child may exceed, returns them. See crate::OverflowBox.

fn constraints_transform(&self) -> Option<ConstraintsTransform>

The box this widget gives its child as a function of the box it was offered, with the child laid out in it separately and the box then sized to what came back. None — the default — means the child shares this node’s layout, as everything ordinary does. See crate::ConstraintsTransformBox.

fn animated_size(&self) -> Option<SizeAnimation>

If the box this widget’s constraints_transform makes follows its child’s size over time rather than at once, how (milestone 594). See crate::AnimatedSize.

fn size_factor(&self) -> Option<(f32, f32)>

If the box this widget’s constraints_transform makes is a multiple of its child’s size — (across, down), 1 for as big as the child — the multiples (milestones 596 and 597). See crate::SizeTransition and crate::Aligned::width_factor.

fn clips_to_box(&self) -> bool

Whether the box this widget’s constraints_transform makes cuts its child to itself. A reveal does; an anchor with a factor lets its child spill (milestone 597).

fn layout_builder(&self) -> Option<&dyn Fn(Size) -> Box<dyn Widget<Msg>>>

If the widget builds its content from its actual box, returns the size → widget factory. The content is built on the fly: no retained state and no overlay (like a virtualised list item).

fn scroll_overlay(&self) -> Option<&OverlayBuilder<Msg>>

If the widget draws something over its scroll region, returns the offset → overlay factory. See crate::ScrollOverlay.

fn scroll_axis(&self) -> Axis

SingleChildScrollView axis (or axes), for a scrollable container.

fn scroll_physics(&self) -> Option<ScrollPhysics>

The edge and fling behaviour of a scrollable container, when this widget wants one in particular. None — the usual answer — leaves the choice to the application, which defaults to what the platform does.

fn scrollbars(&self) -> Option<Scrollbars>

Whether this area draws a scrollbar, when it wants its own answer rather than the application’s. None — the default — follows the application, which follows the platform. See crate::Scrollbars.

fn thumb_visibility(&self) -> Option<bool>

Keep this area’s scrollbar on screen, instead of letting it fade away when the area stops moving (scrollbar.dart:214).

fn ime(&self) -> Ime

What the software keyboard should be, when this widget is the focused editable one.

fn overlay(&self) -> Option<(&dyn Widget<Msg>, Placement)>

If the widget is a portal, returns its floating content and its placement.

fn overlay_dismiss(&self) -> Option<Msg>

Message emitted when the scrim of a modal is clicked (dismissal), if any.

fn overlay_scrim(&self, _theme: &Theme) -> Option<Color>

The colour of the scrim behind this widget’s modal overlay, when it wants one in particular. None — the usual answer — leaves it to the scheme’s scrim role at the framework’s own opacity.

fn overlay_traps_focus(&self) -> bool

If true, this widget’s anchored overlay (a menu…) traps focus: Tab and the arrow keys cycle within its focusables while it is open (the keyboard pattern of menus). Modal (scrimmed) overlays already trap by default; a tooltip or an autocomplete list (focus stays on the field) do not. Default: false.

fn anim_transform(&self) -> Option<TransformValues>

Target transform of an animated one (Transform::animated): the runtime tweens the scales and the turn through anim_duration/anim_curve and hands the interpolated value back through Runtime::anim_transform, which the paint walk reads in place of the static transform_scale/transform_rotate. None = the transform does not move.

fn anim_initial(&self) -> Option<f32>

Where the animated value starts when the widget appears. None, the default: at its target, with no transition, so a switch shown on is simply on. A widget that plays something from its start when it appears — an animation — says Some(0.0), and the value travels to its target in anim_duration from the first frame (milestone 691).

fn opacity_group(&self) -> Option<f32>

If the widget is an opacity group, returns the (target) opacity [0,1] applied to its whole subtree as one: the paint walk wraps its primitives in a composited layer at that opacity — no double-blending where they overlap. None = not a group. Combined with anim_target, the opacity animates (a group fade).

fn anim_color(&self) -> Option<Color>

Target background colour of an animated background (Container::animated_color): the runtime tweens it (through anim_duration/anim_curve) and hands the interpolated value back in Status::anim_color. None = no animated colour.

fn anim_size(&self) -> Option<Size>

Target size of an animated size (Container::animated_size): the runtime tweens it (through anim_duration/anim_curve) and the interpolated size is injected at layout (see effective_style). None = fixed size.

fn anim_radius(&self) -> Option<BorderRadius>

Target corner radius of an animated radius (Container::animated_radius): the runtime tweens it and hands the interpolated value back in Status::anim_radius. None = fixed radius.

fn anim_padding(&self) -> Option<Insets>

Target padding of an animated padding (Container::animated_padding): the runtime tweens it and the interpolated padding is injected at layout (see effective_style). None = fixed padding.

fn anim_offset(&self) -> Option<(f32, f32)>

The pair of fractions this node’s offset rule is made of, animated: an alignment’s two fractions, or a slide’s. None — the default — leaves the rule reading the widget’s own numbers.

fn anim_pins(&self) -> Option<Positioning>

Target pins of an animated stack layer (crate::AnimatedPositioned): the runtime tweens them and the interpolated pins are read where the stack lays its layers out. None — the default — leaves Widget::positioned alone.

fn anim_fractions(&self) -> Option<(Option<f32>, Option<f32>)>

Target fractions of an animated share of the parent (FractionallySizedBox::animated), as (width factor, height factor): the runtime tweens them and the interpolated pair is injected at layout (see effective_style), like the size and the padding. None = fixed factors.

fn anim_text_style(&self) -> Option<TextStyle>

Target text style an animated subtree is heading for (AnimatedDefaultTextStyle). None = the subtree inherits whatever it inherits.

fn alignment_geometry(&self) -> Option<AlignmentGeometry>

Alignment of the single child within the box: the walk offsets the child through the free space according to the alignment’s fractions, resolved against the reading direction (physical or directional — see frus_core::AlignmentGeometry). Being continuous, a Tween<Alignment> read in view() slides the child. None = default flex placement.

fn transform_translate(&self) -> Option<(f32, f32)>

Paint offset (dx, dy) applied to the widget’s whole subtree: the render and the hit-test are offset without touching layout (siblings do not move, the child may overflow its box). Continuous → a Tween read in view() slides the subtree. None = no offset. See crate::Transform.

fn translate_fraction(&self) -> Option<(f32, f32)>

Paint offset as a fraction of the child’s own size (fx, fy): (0.5, 0.0) slides the subtree half its own width to the right. Added to Widget::transform_translate, and offsetting the render and the hit-test the same way, without touching layout. None = no offset.

fn transform_scale(&self) -> Option<(f32, f32, Alignment)>

Paint scaling (sx, sy, pivot) of the whole subtree: the render and the hit-test are scaled — per axis — around the pivot (a frus_core::Alignment within the box), without touching layout. Stays axis-aligned (a scaled rect is still a rect). None = no scaling. See crate::Transform.

fn transform_rotate(&self) -> Option<(f32, Alignment)>

Paint rotation (angle, pivot) of the whole subtree: the subtree is painted rotated by angle radians (clockwise) around the pivot (a frus_core::Alignment within the box), without touching layout. The render goes through a rotated composited layer; the hit-test counter-rotates the point. None = no rotation. See crate::Transform.

fn clip_shape(&self) -> Option<ClipShape>

Shape clip of the whole subtree: the paint walk wraps its primitives in a composited layer whose frus_core::ClipShape (rounded corners, ellipse) modulates the alpha — whatever falls outside the shape is erased, edges antialiased. None = no shape clip. See crate::ClipRRect, crate::ClipOval.

fn style_themed(&self, _theme: &Theme) -> Style

The widget’s style once the theme has had its say — the layout half of the caller ?? theme ?? framework chain.

fn theme_override(&self, _inherited: &Theme) -> Option<Box<Theme>>

The theme this widget imposes on itself and its subtree, given the one it inherits. None — the default — means “whatever came down from above”, which is what every widget but crate::Themed answers.

fn media_override(&self, _inherited: MediaQuery) -> Option<MediaQuery>

The surface this widget imposes on itself and its subtree, given the one it inherits. None — the default — means “whatever came down from above”, which is what every widget but MediaScope answers.

fn scaffold_override(&self) -> Option<ScaffoldInfo>

The shell this widget imposes on its subtree: what a Scaffold knows about itself and its slots do not.

fn scroll_behavior_override(&self) -> Option<ScrollBehavior>

The ScrollBehavior this widget puts in force for its subtree, or None — the default — for whatever came down from above. Only ScrollConfiguration answers otherwise. Applied by the same four walks as Self::scaffold_override: the scrollables under it record what it decides when they are registered (milestone 616).

fn build_themed(&self, _theme: &Theme)

Builds this widget’s subtree from the ambient theme, for the widgets that defer that decision — see ThemeBuilder. Does nothing by default, which is what all but a handful of widgets want.

fn build_in(&self, _id: WidgetId, _runtime: &Runtime, theme: &Theme)

Self::build_themed, for the few widgets that also need who they are and what the frame remembers to compose their subtree. An AnimatedSwitcher keeps what it is letting go of in the runtime, under its own identity, and that is reachable nowhere else before its children are read.

fn expand(&self, _id: WidgetId, _runtime: &Runtime, _theme: &Theme)

Builds what this node stands for, before anything else is asked of it.

fn switches(&self) -> bool

Whether this node is an AnimatedSwitcher. An identity is a position, so a switcher and the widget that comes to stand where it stood have the same one: this is how the runtime tells the switcher still being there from its having gone, and forgets what it kept for it.

fn system_ui_style(&self) -> Option<SystemUiOverlayStyle>

What the system bars over this widget should look like — see AnnotatedRegion. None for every widget but that one; a transparent wrapper forwards it, or a keyed region would say nothing.

fn ink(&self, _theme: &Theme) -> Option<InkStyle>

If the widget takes ink — the splash a tap leaves on a material surface — the shape and colour to splash in. None = no ink, which is the default: a widget has to ask.

fn foreground(&self, _theme: &Theme) -> Option<BoxDecoration>

A decoration painted over this widget’s children rather than behind them: the reference’s foregroundDecoration.

fn paints_over(&self) -> bool

Whether this widget paints over its own children too, with paint_over (milestone 652). false by default, which spares the walk the status it would compute for it.

fn paint_over( &self, _bounds: Rect, _status: Status, _theme: &Theme, _scene: &mut Scene, )

Paints over this widget’s children, after its subtree, in the box and with the status Widget::paint is given — the reference’s foregroundPainter, for what a widget draws that its children must not cover. A range slider’s thumbs are one: each thumb’s focus stop is a child, and the halo it paints belongs under the thumb.

fn layer_filter(&self, _cx: FilterContext) -> Option<LayerFilter>

The pixel effects this widget applies to its whole subtree: a blur, a colour transform, a mask, or a filter over what is painted underneath. The paint walk drains the subtree into a composited layer and hands the filter to the renderer, exactly as it does for an opacity group or a shape clip.

fn backdrop_group(&self) -> bool

true when this widget is a backdrop group: the backdrops below it that ask to be shared are filtered once between them. See crate::BackdropGroup.

fn text_baseline(&self, _theme: &Theme) -> Option<f32>

The widget’s own text baseline: the distance from the top of its box down to the line its letters sit on. None — the default — means this widget has no text of its own, and whatever is inside it answers instead.

fn ignores_baseline(&self) -> bool

true when this subtree should be left out of a parent’s baseline alignment: it has a baseline, and the parent is to pretend it does not. An icon beside a label, where the label is what the row should line up on. See crate::IgnoreBaseline.

fn fill_axes(&self, _theme: &Theme) -> FillAxes

The axes this widget asks to fill: on each, it takes the room the parent leaves it rather than shrink-wrapping its children. FillAxes::NONE means shrink-wrap on both.

fn soft_extent(&self) -> FillAxes

The axes on which this widget’s size is only a default (milestone 590): the room on offer replaces it wherever the widget is asked to fill that axis and the layout can grant it — alone in a box, or across a row or a column. Where it cannot, along a line shared with other children, the default stands.

fn main_axis_floor(&self, _theme: &Theme) -> Option<f32>

The width below which this widget must not be squeezed when its parent runs horizontally — a line of text that would rather run past the end of a row than be folded into a column of single words. None means squeeze freely.

fn tile_shape(&self) -> Option<f32>

If this container gives all of its children the shape of a tile, the width / height ratio to impose on each of them. None = each child keeps its own shape.

fn positioned(&self) -> Option<Positioning>

If this is a layer pinned against its crate::Stack’s edges (crate::Positioned), what it pins. None = an ordinary layer, sized and placed by the stack’s own fit and alignment.

fn stack_fit(&self) -> StackFit

How this stack sizes its unpinned layers (crate::StackFit). Unset, Passthrough: each is handed the stack’s box, and one with a size of its own keeps it. Meaningless unless Widget::stack is true.

fn stack_measured(&self) -> bool

Whether this stack is as big as its largest unpinned layer (milestone 639), as crate::Stack is, rather than the size its own style says. Meaningless unless Widget::stack is true.

fn stack_clips(&self) -> bool

Whether this stack cuts its layers at its edges. Unset, it does.

fn stack_direction(&self) -> Option<TextDirection>

The reading direction this stack resolves its alignment and its layers’ start and end pins in, when it names one. Unset, the theme’s.

fn stack_visible(&self) -> Option<usize>

Which layer of this stack is shown: the one at that index paints and takes input, and every other one is laid out and then silenced — not drawn, not clickable, not read out. None, the default, shows all of them.

fn keep_visible(&self, _size: Size, _theme: &Theme) -> Option<KeepVisible>

The box this widget asks the scroll region around it to keep in view, in its own coordinates, with a key naming which box it is.

fn scroll_reverse(&self) -> bool

Whether this scrollable runs from the far end (crate::SingleChildScrollView::reverse): the content is anchored to the end of the viewport and offsets are counted from there. Meaningless unless Widget::scroll_content is Some.

fn scroll_padding(&self) -> Insets

The insets a scrollable area puts around its content, inside the viewport.

fn baseline_target(&self) -> Option<f32>

If the widget positions its child by the child’s baseline (crate::Baseline), the distance from the top of this box at which that baseline should land. None = not a baseline box.

fn clip_path(&self) -> Option<&Path>

If the widget clips its child to an arbitrary path (ClipPath), returns the path in local coordinates (origin at the box’s top-left corner). The walk offsets it to the screen and wraps it in a layer whose mask (the path) erases the outside. Takes priority over Widget::clip_shape. None = no path clip. See crate::ClipPath.

fn dismissible(&self) -> Option<DismissSpec>

If the widget is a dismissible item (crate::Dismissible), its configuration for this frame. The shell gives a mostly-sideways drag on it to the dismissal and a mostly-up-and-down one to the enclosing scrollable. None = not dismissible.

fn on_dismissed(&self, _direction: DismissDirection) -> Option<Msg>

The message a dismissed item dispatches, once it has flown out and its gap has closed. None = the swipe is shown but removes nothing.

fn sheet(&self) -> Option<&SheetSpec>

If the widget is the moving panel of a crate::DraggableScrollableSheet, its configuration for this frame. The layout makes it as tall as the retained height, and the shell shares a finger on it between the sheet and the scroll areas inside. None = not a sheet.

fn on_sheet_dismissed(&self) -> Option<Msg>

The message a sheet dispatches once it has been lowered to nothing. None = it cannot be dismissed, or says nothing when it is.

fn refresh(&self) -> Option<RefreshSpec>

If the widget is a refresh area (crate::RefreshIndicator), its configuration for this frame. Any scrollable inside it routes the movement its physics refuses at the top edge into the pull, instead of into the overscroll glow. None = not a refresh area.

fn on_refresh(&self) -> Option<Msg>

The message a refresh area dispatches when an armed pull is released. None = the pull is shown but asks for nothing, which is what an area still waiting for its on_refresh looks like.

fn barrier(&self) -> Option<ModalBarrier>

What the widget withholds from the frame on behalf of its whole subtree: input targets, primitives, accessibility nodes. The walk visits the subtree normally and then discards whatever it added to the selected registries, so a target registered deep inside is caught just as surely as one at the top. None = nothing withheld (the default). See crate::ModalBarrier, crate::IgnorePointer, crate::AbsorbPointer, crate::Visibility, crate::ExcludeSemantics.

fn interactive(&self) -> Option<(f32, f32)>

If the widget is an interactive viewport (InteractiveViewer), returns its scale bounds (min, max). The paint walk renders its child in a transformed layer (retained scale + translation, clipped to the viewport); the shell routes drag → pan and wheel/pinch → zoom. None = not an interactive viewport. See crate::InteractiveViewer.

fn fitted(&self) -> Option<BoxFit>

If the widget fits its child to its box (FittedBox), returns the frus_core::BoxFit: the walk measures the child at its natural size, scales it according to the fit and centres it (composited layer, hit-test through M⁻¹). None = not a fitter. See crate::FittedBox.

fn rotated_quarter_turns(&self) -> Option<i32>

If the widget rotates its child by quarter turns (RotatedBox), returns the number of quarters. Unlike Transform, this affects layout: the box swaps its dimensions for an odd number. None = not a RotatedBox. See crate::RotatedBox.

fn navigator(&self) -> Option<(f32, bool)>

If the widget is a screen navigator, returns (progress, push?). Its children ([screen] or [outgoing, incoming]) are rendered full-window with a sliding transition.

fn navigator_gesture(&self) -> bool

Whether a finger drives the navigator’s transition — a back gesture — so that it follows the finger linearly (milestone 620).

fn navigator_clips(&self) -> bool

Whether a navigator clips its pages to its own box. true, which is the reference’s default (Clip.hardEdge) and the only sane one: a screen sliding in comes from outside the box and has to stop at its edge.

fn navigator_retained(&self) -> usize

How many of a navigator’s first children are kept but not shown: the pages under the one on show. They are built, so what their components hold survives, and they are not laid out, drawn or given input. 0, the default, is a navigator that shows every page it holds.

fn on_long_press(&self) -> Option<Msg>

Message emitted by a long press (a press held ~500 ms without movement). The long press pre-empts the click: the release that follows does not emit on_click.

fn on_double_tap(&self) -> Option<Msg>

Message emitted by a double tap: two taps on this widget in quick succession (within 300 ms and 100 px of each other, the reference’s numbers). While one is possible, a first tap’s on_click waits out those 300 ms, so that the second tap of a double tap is not also a tap.

fn on_secondary_tap(&self) -> Option<Msg>

Message emitted by a secondary tap: a click of the secondary mouse button, usually the right one.

fn pointer_listener(&self) -> bool

Whether this widget hears the pointer’s raw events (milestone 586): a press inside it, and then that pointer wherever it goes until it lifts; and a mouse’s hover.

fn on_pointer_event(&self, _event: ListenerEvent) -> Vec<Msg>

The messages for one raw event of the pointer, on a widget that is a pointer_listener. Several, when listeners wrap each other at the same place.

fn hover_region(&self) -> Option<HoverRegion>

Whether this widget is a region the mouse enters and leaves (milestone 583), and how: the cursor it asks for while the pointer is over it, and whether it hides the regions behind it. None for anything that is not one.

fn on_hover_event(&self, _event: HoverEvent) -> Option<Msg>

Message for the pointer entering, moving over or leaving this region — one whose hover_region is set.

fn pan_axis(&self) -> Option<PanAxis>

Which way this widget takes a drag, if it takes one at all (milestone 582): the shell then reports it through on_pan. Inside a scroll, a drag along the scroll’s axis stays the scroll’s unless this axis claims it.

fn on_pan(&self, _event: PanEvent) -> Option<Msg>

Message for one moment of a drag — its start, a movement, its end — on a widget whose pan_axis is set.

fn wants_title_bar(&self) -> bool

Whether this widget wants the title bar’s line for itself (milestone 640): a WindowMenuBar’s row. The shell gives it the line where the system allows it.

fn title_bar_role(&self) -> Option<TitleBarRole>

What this widget is to the system on the title bar’s line, which acts on it: the window’s icon or its three buttons (milestone 640).

fn pan_value(&self, _event: PanEvent, _value: f32, _rtl: bool) -> Option<f32>

A drag that moves this widget’s own animated value (anim_target) — a switch’s thumb following the finger (milestone 638). Given a moment of the drag, the value now and whether the text runs right to left, the value to hold it at; None leaves it alone. The shell holds the value there while the finger is down, and when it lifts lets it settle from there, asking on_value_release what that means.

fn on_value_release(&self, _value: f32) -> Option<Msg>

Message for a drag that moved this widget’s value letting go at value — a switch flips when its thumb was let go past half way (milestone 638).

fn on_key(&self, _key: &Key) -> KeyResponse<Msg>

Key received while bubbling leaf→root: the focused widget gets it first, then each ancestor as long as the response is Ignored. (E.g. an OverlayPortal consumes Escape to close itself.)

fn measure(&self, _theme: &Theme) -> Option<MeasureFn<'_>>

Measure under constraints: for a widget whose size depends on the space offered (a paragraph that wraps…), returns the closure wired into taffy. None = size fixed by style(). Contract: must be Some if and only if Widget::measure_key is.

fn measure_key(&self, _theme: &Theme) -> Option<u64>

Fingerprint of the content Widget::measure depends on (text, style…), mixed into the relayout fingerprint: without it, two different contents with the same style would be conflated by the cache and would keep a stale geometry. Contract: Some if and only if measure() is.