Struct Command 

pub struct Command<Msg> { /* private fields */ }

A batch of effects to run, possibly empty: background tasks, synchronous or asynchronous, and focus and scroll requests addressed by widget key.

Implementations

impl<Msg: Send + 'static> Command<Msg>

pub fn none() -> Self

No effect at all.

pub fn batch(commands: impl IntoIterator<Item = Command<Msg>>) -> Self

Groups several commands into one.

pub fn after(delay: Duration, message: Msg) -> Self

Delivers message once, after delay.

This waits without occupying anything: natively it is a task on the shell’s executor parked on the reactor’s timer wheel, and on the Web a setTimeout. A hundred pending timers are a hundred entries in a queue, not a hundred threads.

For a message that repeats, declare a Subscription::every instead — a subscription is a function of the state and stops when the state says so, where a chain of afters has to be stopped by hand.

pub fn perform(task: impl FnOnce() -> Msg + Send + 'static) -> Self

Runs a synchronous task in the background; its result becomes a message.

pub fn run(task: impl FnOnce() -> Option<Msg> + Send + 'static) -> Self

Runs a synchronous side effect; it may return a message (None for none).

pub fn perform_async<F>(future: F) -> Self

where F: Future<Output = Msg> + Send + 'static,

Runs an asynchronous future; its value becomes a message.

On the Web, which is single-threaded, the browser drives the future (spawn_local), so a real fetch can await without blocking. Natively it runs on the shell’s executor (the runtime module), which has a reactor: a future may wait on a timer or on a socket and costs nothing while it does.

Do not put a blocking call in here — that is what Command::perform is for. The executor has four worker threads, and a blocking call holds one of them for its whole duration.

pub fn run_async<F>(future: F) -> Self

where F: Future<Output = Option<Msg>> + Send + 'static,

Runs an asynchronous future for its side effect; it may return a message (None for none). The asynchronous counterpart of Command::run.

pub fn focus(key: impl Hash) -> Self

Requests focus for the widget carrying key — the field wrapped in keyed(key, …). The shell resolves it after the view is next built; it is typically returned when a form submission fails, to jump to the first invalid field (Form::first_invalid).

pub fn scroll(key: impl Hash, to: ScrollTo) -> Self

Moves a scroll region: the one named key goes where to says.

A scroll is not a function of the state — the same list, the same offset, and yet “go back to the top” happens once — so it is an effect and belongs here rather than on a widget. The offset it changes is state, and it stays where it was: in the runtime, beside every other offset, written by the frame this request is resolved into.

Named the way a focus request is named: the region is wrapped in keyed(k, …) and addressed by k. The framework’s own identities are hashes of a position in a tree, which an application cannot know and should not have to.

Resolved against the frame that follows, once and once only — the same rule as Command::focus. A request naming a region that frame has not got is dropped rather than kept waiting: an effect that outlived the state it was written for would arrive at a list that had since become somebody else’s.

Command::scroll("journal", ScrollTo::start())

pub fn sheet(key: impl Hash, to: SheetTo) -> Self

Moves a sheet: the one named key goes where to says — the reference’s DraggableScrollableController, as an effect.

For the reason a scroll is one: “raise the sheet” happens once, and the height it leaves behind is state that stays where every other sheet height is, in the runtime. Named the same way — the sheet, or anything around it, wrapped in keyed(k, …) — and resolved on the same terms: against the frame that follows, a sheet that has only just appeared included, and dropped if that frame has not got it. A finger on the sheet refuses it.

Command::sheet("places", SheetTo::size(1.0).animate(0.3, Curve::ease()))

pub fn is_empty(&self) -> bool

true when the command has no effect and no request of any kind.