Skip to main content

ListBuilder

Trait ListBuilder 

Source
pub trait ListBuilder<S>: Sized
where S: RowSource + 'static,
{
Show 25 methods // Required methods fn row_height(self, h: RowHeight) -> Self; fn on_activate(self, f: impl Fn(<S as RowSource>::Ref) + 'static) -> Self; fn on_select(self, f: impl Fn(<S as RowSource>::Ref) + 'static) -> Self; fn multi_select(self) -> Self; fn on_selection( self, f: impl Fn(Vec<<S as RowSource>::Ref>) + 'static, ) -> Self; fn selected_rows(self, rows: impl Fn() -> Vec<usize> + 'static) -> Self; fn selection(self, selected: impl Binding<Option<u64>>) -> Self where <S as RowSource>::Ref: SelectionKey; fn scroll_to_end(self, trigger: Trigger) -> Self; fn follow_end(self, threshold: f64) -> Self; fn on_end_reached(self, threshold: f64, f: impl Fn() + 'static) -> Self; fn scroll_to_row<T>(self, target: impl Binding<Option<T>>) -> Self where T: Into<RowTarget> + Clone + 'static; fn visible_rows(self, rows: impl Binding<Range<usize>>) -> Self; fn header<P>(self, build: impl Fn() -> P + 'static) -> Self where P: Piece; fn footer<P>(self, build: impl Fn() -> P + 'static) -> Self where P: Piece; fn empty<P>(self, build: impl Fn() -> P + 'static) -> Self where P: Piece; fn content_padding(self, insets: impl Into<Insets>) -> Self; fn reorderable(self, reorder: Reorder) -> Self; fn deletable(self, delete: Delete) -> Self; fn swipe_leading( self, provider: impl Fn(usize) -> Vec<SwipeAction> + 'static, ) -> Self; fn swipe_trailing( self, provider: impl Fn(usize) -> Vec<SwipeAction> + 'static, ) -> Self; fn separators(self) -> Self; fn inset_grouped(self) -> Self; fn no_separators(self) -> Self; fn sections<K, P>( self, key: impl Fn(usize) -> K + 'static, header: impl Fn(<S as RowSource>::Slot) -> P + 'static, ) -> Self where K: Hash, P: Piece; fn editing<M>(self, on: impl IntoReactive<bool, M>) -> Self;
}
Expand description

Builder methods of List, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.

Required Methods§

Source

fn row_height(self, h: RowHeight) -> Self

Row sizing: Uniform(h) (fastest) or Automatic (self-sizing).

Source

fn on_activate(self, f: impl Fn(<S as RowSource>::Ref) + 'static) -> Self

Open, play, or otherwise activate a row. Desktop lists use double-click or Enter; touch lists use a tap. Selection callbacks remain independent.

Source

fn on_select(self, f: impl Fn(<S as RowSource>::Ref) + 'static) -> Self

Called with the selected row when the native list reports a selection: the key for a plain-data source, the row’s Elem handle for a store source.

Source

fn multi_select(self) -> Self

Allow selecting several rows at once, where the toolkit supports it (docs/list.md has the matrix; single-selection backends fall back to one row at a time). Every selection change calls Self::on_selection with the full set of selected rows.

Source

fn on_selection(self, f: impl Fn(Vec<<S as RowSource>::Ref>) + 'static) -> Self

Called with the full set of selected rows (row order, empty = cleared) whenever the selection changes: the multi-select analogue of Self::on_select. Also fired by single-selection backends with a one-element (or empty) set.

Source

fn selected_rows(self, rows: impl Fn() -> Vec<usize> + 'static) -> Self

Reactively sync the native selection to rows (row indices; empty clears). Re-runs whenever the closure’s tracked reads change; the toolkit applies the sync without re-emitting a selection event. Drive it from app state to build “Clear selection”.

Source

fn selection(self, selected: impl Binding<Option<u64>>) -> Self
where <S as RowSource>::Ref: SelectionKey,

Two-way single selection by key, for a list of day-model store rows: selected holds the selected row’s key (None for no selection). A row the user picks writes its key, clearing the selection writes None, and a key the app writes selects that row and scrolls it into view, following the row through inserts and moves.

ⓘ
list(scene.items, row_view).selection(scene.selected)
Source

fn scroll_to_end(self, trigger: Trigger) -> Self

Scroll the list to its end whenever trigger fires, e.g. a “jump to latest” button on a chat timeline. Fire it with day_reactive::Trigger::notify. No-op while the list is empty. The scroll targets the native list (NSTableView/UITableView/GtkListView/QListView/RecyclerView), so it respects the platform’s own scroll physics. To keep following new rows by itself, see Self::follow_end.

Source

fn follow_end(self, threshold: f64) -> Self

Follow the end of the list (docs/list.md “Following the end”): when the rows change while the list’s end is within threshold points of the bottom of the viewport, the list scrolls to its new end, so a chat timeline or a log keeps its newest row in view. A reader who has scrolled further up than threshold is left where they are; they rejoin by scrolling back down, or through Self::scroll_to_end.

The distance comes from the native list (Cap::ListViewport). A toolkit that does not report it follows every change.

ⓘ
list(items(move || messages.get(), |m| m.id), message_row).follow_end(40.0)
Source

fn on_end_reached(self, threshold: f64, f: impl Fn() + 'static) -> Self

Call f when the user comes within threshold points of the end of the list: the moment to load the next page (docs/list.md “Reaching the end”). It fires once on the way in, and again only after the end has left that distance and returned, or after the number of rows changed, so a handler that appends rows is called again when the reader reaches the new end. A page that leaves the end within threshold fires it again once its rows are laid out, with no scroll; a call that adds no rows re-arms nothing, so it is never called in a loop. An empty list does not fire it. Needs Cap::ListViewport.

ⓘ
list(rows, row_view).on_end_reached(400.0, move || feed.load_more())
Source

fn scroll_to_row<T>(self, target: impl Binding<Option<T>>) -> Self
where T: Into<RowTarget> + Clone + 'static,

Programmatic scroll-to-row (docs/list.md “Programmatic scrolling”): each Some(target) written to the binding scrolls there, realizing the row if it was virtualized away, and the binding then resets to None, so the same row can be sent twice in a row. The same contract as scroll(..).scroll_target(..). A RowTarget names the row, where it lands and whether the scroll animates; a binding of plain indices works too, each one a RowTarget::new(row).

ⓘ
let jump = Signal::new(None);
list(rows, row_view).scroll_to_row(jump);
button(res::str::newest()).action(move || jump.set(Some(0)));
// With options:
jump.set(Some(RowTarget::new(250).align(RowAlign::Center).instant()));
Source

fn visible_rows(self, rows: impl Binding<Range<usize>>) -> Self

The rows in view (docs/list.md “Visible rows”), written to rows as the list scrolls: a half-open range of row indices, rows.start the first row with any part showing and rows.end one past the last, empty while no row is in view. Section headers and the list’s own header and footer are not rows. Use rows.start with a heading overlay for a floating group header. No periodic timer is used. Where Cap::ListViewport is unsupported the range holds the first visible row only.

Source

fn header<P>(self, build: impl Fn() -> P + 'static) -> Self
where P: Piece,

Content above the first row that scrolls with the rows (docs/list.md “Header, footer and empty state”): a search summary, a hero, a banner. build runs when the list first shows it. It is not a row: nothing selects, swipes or counts it.

Source

fn footer<P>(self, build: impl Fn() -> P + 'static) -> Self
where P: Piece,

Content below the last row that scrolls with the rows: a “loading more” spinner, a count, a sign-off. The same contract as Self::header.

Source

fn empty<P>(self, build: impl Fn() -> P + 'static) -> Self
where P: Piece,

What the list shows in place of its rows while it has none (docs/list.md “Header, footer and empty state”), centered in the viewport, between the header and the footer if the list has them. It goes when the first row arrives and returns when the last one leaves.

ⓘ
list(rows, row_view).empty(|| label(res::str::no_messages()).secondary())
Source

fn content_padding(self, insets: impl Into<Insets>) -> Self

Space around the list’s content, inside the scrolling area: the top and bottom scroll with the rows (the last row clears a floating composer or tab bar), the sides inset every row. Takes a number for all four sides or an Insets.

Source

fn reorderable(self, reorder: Reorder) -> Self

Let the user drag rows into a new order (docs/list.md): the list is reorderable exactly when it carries a Reorder, whose handler applies the move to the app’s data.

ⓘ
list(rows, row_view)
    .reorderable(Reorder::new(move |from, to| scene.move_item(from, to)).guard(keep_pinned))
Source

fn deletable(self, delete: Delete) -> Self

Let the user delete rows with the platform’s delete gesture (docs/list.md): the list is deletable exactly when it carries a Delete, whose handler applies the removal to the app’s data.

ⓘ
list(rows, row_view)
    .deletable(Delete::new(move |i| scene.remove_at(i)).label(res::str::delete()))
Source

fn swipe_leading( self, provider: impl Fn(usize) -> Vec<SwipeAction> + 'static, ) -> Self

Offer swipe actions on the row’s leading edge, the reading-direction start, where the platform reveals them as the user drags the row aside (probe Cap::ListSwipeActions; docs/list.md has the matrix; a backend without the affordance shows nothing, so pair each action with an explicit control for the rest). provider runs at gesture time with the row index, so the offer can reflect the row’s current state (“Mark as Read” vs “Mark as Unread”). Keep it pure and fast; it runs inside the platform’s swipe callback; the actions’ handlers run later, at the event drain. A full swipe across activates the edge’s first action.

Source

fn swipe_trailing( self, provider: impl Fn(usize) -> Vec<SwipeAction> + 'static, ) -> Self

Offer swipe actions on the row’s trailing edge, the reading-direction end. Same contract as swipe_leading.

Source

fn separators(self) -> Self

Draw a separator under each row. It is the host’s separator, drawn at the row boundary and never by row content (docs/list.md): it aligns with the native selection and stays put while a macOS/iOS swipe slides the row past it, exactly as Mail’s separators do. Unset, each platform keeps its default (iOS draws them, the desktops don’t); see Self::no_separators for the other override. A backend without a separator mechanism ignores this (the docs matrix says which); don’t re-create the old hand-drawn hairline there. Rows separate by their pitch.

Source

fn inset_grouped(self) -> Self

Draw the list as the platform’s inset grouped list: rounded groups of rows set in from the edges, one per section, as iOS Settings and Safari’s History do (docs/list.md “Appearance”). iOS and macOS draw it; the other platforms draw their plain list.

Source

fn no_separators(self) -> Self

Draw no separator between rows, on a platform whose default draws one (iOS).

Source

fn sections<K, P>( self, key: impl Fn(usize) -> K + 'static, header: impl Fn(<S as RowSource>::Slot) -> P + 'static, ) -> Self
where K: Hash, P: Piece,

Group the rows into sections, each opened by a header row (docs/list.md “Sections”). key runs with each row index when the rows change and names the row’s section: a new section, and a header, starts wherever the key differs from the row before, so sort the rows by section first. header builds a section’s header from the slot of its first row, the same slot a row builder gets, and rebinds it as its cell recycles.

Headers are the platform’s own: macOS group rows and UIKit section headers, which pin to the top of the list while their section scrolls under them; the other toolkits pin a copy of the current header the same way (Cap::ListSections). A header is never selected, activated or swiped, and row indices everywhere (selection, swipe offers, selected_rows, scroll_to_row, visible_rows) still count rows only. A header sizes to its content even when the rows are Uniform.

A row drags only within its own section, the platforms’ rule for grouped tables: a drop past either end of the section lands at that end, and the reorderable guard sees row indices. A sectioned list offers no native swipe-to-delete, since deleting a section’s last row would take its header with it.

ⓘ
list(items(move || articles.get(), |a| a.id), article_row)
    .sections(
        move |i| articles.with(|a| a[i].feed_id),
        |slot| label(move || slot.field(|a| a.feed_title.clone())),
    )
Source

fn editing<M>(self, on: impl IntoReactive<bool, M>) -> Self

Put the list in the platform’s editing mode (docs/list.md): on iOS, the rows show their delete controls (where a Delete offers one) and reorder grips (where a Reorder moves them), and a tap still activates the row. Reactive, so an Edit/Done button can toggle it, and the change animates.

Probe Cap::ListEditing. The other toolkits have no separate editing mode: their rows drag, swipe and open menus as they are, so the list renders as if this were off.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§

Source§

impl<S, DecoratedInner> ListBuilder<S> for Decorated<DecoratedInner>
where S: RowSource + 'static, DecoratedInner: ListBuilder<S> + Piece,

Source§

impl<S> ListBuilder<S> for List<S>
where S: RowSource + 'static,