pub trait ListBuilder<S>: Sizedwhere
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
Required Methods§
Sourcefn row_height(self, h: RowHeight) -> Self
fn row_height(self, h: RowHeight) -> Self
Row sizing: Uniform(h) (fastest) or Automatic (self-sizing).
Sourcefn on_activate(self, f: impl Fn(<S as RowSource>::Ref) + 'static) -> Self
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.
Sourcefn on_select(self, f: impl Fn(<S as RowSource>::Ref) + 'static) -> Self
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.
Sourcefn multi_select(self) -> Self
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.
Sourcefn on_selection(self, f: impl Fn(Vec<<S as RowSource>::Ref>) + 'static) -> Self
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.
Sourcefn selected_rows(self, rows: impl Fn() -> Vec<usize> + 'static) -> Self
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”.
Sourcefn selection(self, selected: impl Binding<Option<u64>>) -> Self
fn selection(self, selected: impl Binding<Option<u64>>) -> Self
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)Sourcefn scroll_to_end(self, trigger: Trigger) -> Self
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.
Sourcefn follow_end(self, threshold: f64) -> Self
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)Sourcefn on_end_reached(self, threshold: f64, f: impl Fn() + 'static) -> Self
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())Sourcefn scroll_to_row<T>(self, target: impl Binding<Option<T>>) -> Self
fn scroll_to_row<T>(self, target: impl Binding<Option<T>>) -> Self
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()));Sourcefn visible_rows(self, rows: impl Binding<Range<usize>>) -> Self
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.
Sourcefn header<P>(self, build: impl Fn() -> P + 'static) -> Selfwhere
P: Piece,
fn header<P>(self, build: impl Fn() -> P + 'static) -> Selfwhere
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.
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.
Sourcefn empty<P>(self, build: impl Fn() -> P + 'static) -> Selfwhere
P: Piece,
fn empty<P>(self, build: impl Fn() -> P + 'static) -> Selfwhere
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())Sourcefn content_padding(self, insets: impl Into<Insets>) -> Self
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.
Sourcefn reorderable(self, reorder: Reorder) -> Self
fn reorderable(self, reorder: Reorder) -> Self
Sourcefn swipe_leading(
self,
provider: impl Fn(usize) -> Vec<SwipeAction> + 'static,
) -> Self
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.
Sourcefn swipe_trailing(
self,
provider: impl Fn(usize) -> Vec<SwipeAction> + 'static,
) -> Self
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.
Sourcefn separators(self) -> Self
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.
Sourcefn inset_grouped(self) -> Self
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.
Sourcefn no_separators(self) -> Self
fn no_separators(self) -> Self
Draw no separator between rows, on a platform whose default draws one (iOS).
Sourcefn sections<K, P>(
self,
key: impl Fn(usize) -> K + 'static,
header: impl Fn(<S as RowSource>::Slot) -> P + 'static,
) -> Self
fn sections<K, P>( self, key: impl Fn(usize) -> K + 'static, header: impl Fn(<S as RowSource>::Slot) -> P + 'static, ) -> Self
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())),
)Sourcefn editing<M>(self, on: impl IntoReactive<bool, M>) -> Self
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".