Struct Dispatcher 

pub struct Dispatcher<R: Resource> { /* private fields */ }

Submits a view’s edits. Cloneable; clones share one queue.

Two doors, one path. submit and apply queue an invocation the host resolves after the event, exactly as a control bound to an action would. apply_now applies one typed action immediately, inside the event or the settle pass (Widget::settle), for an editor that must see the result of its own edit before the next keystroke (the paragraph a split created, the cell a table insert made). Both check the participant’s permission, apply through the replayable executor with attribution, and are undone per author.

A drag as one undo step

A slider or a drag handle a surface draws itself applies each value it passes through with apply_now, so the document — and every collaborator — follows the drag live. The resource declares that one value continues the one before it (Resource::coalesces: the same field of the same item), which makes the whole drag one step, and the surface calls settle when the pointer is let go, so the next drag is a step of its own:

fn coalesces(previous: &Action, next: &Action) -> bool {
    matches!((previous, next), (Action::SetLevel(..), Action::SetLevel(..)))
}

// In the surface's `handle_event`:
WindowEvent::CursorMoved { .. } if self.dragging => {
    let _ = self.dispatch.apply_now(&mut ctx.edits(), &Action::SetLevel(level));
}
WindowEvent::MouseInput { state: ElementState::Released, .. } => {
    self.dragging = false;
    self.dispatch.settle();
}

A toolkit slider bound with ViewCx::control instead invokes its action once per drag when built with Slider::commits_on_release.

Implementations

impl<R: Resource> Dispatcher<R>

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

Who edits through this dispatcher: the participant this view is for, the same id an action they invoke reads as its author (ActionCx::author). None in a view of a past version, which nobody edits.

pub fn is_past(&self) -> bool

Whether the view shows a past version in History mode, drawn from a frozen document. Such a view must start no work: no worker, no network, no files. A surface that would fetch or watch something presents what the document holds instead.

pub fn read_only(&self) -> bool

Whether edits from this participant will be refused, as of now: it follows role changes while the app runs. Surfaces use it to present themselves read-only instead of letting an edit bounce.

pub fn read_only_state(&self) -> LocalState<bool>

Self::read_only as observable state, for a widget that shows or disables something while the participant may only view.

pub fn permission_state(&self, need: ActionNeed) -> LocalState<bool>

Whether the host currently allows what need is, as observable view state. It follows changes even when writing remains allowed and the resource document does not change. Bind it to a conditional pane or label; action invocation still checks the host’s current authority.

pub fn standing_source(&self) -> impl Fn() -> Option<Standing> + 'static

The participant’s standing in the workspace as the host keeps it when called: who they are, the workspace’s policy and what bounds them. For a runtime that decides its own invocations (a tilolang program’s) by the policy the door decides by. None outside a host.

pub fn govern_state(&self) -> LocalState<bool>

Whether the participant may govern the workspace (invite, grant, change its settings), as observable view state: for an owner’s pane.

pub fn arrived_state(&self) -> LocalState<bool>

Whether what the workspace holds has arrived, as observable view state: false while the window’s workspace has not finished its first sync with its host (ui_core::workspace_sync), when a record joined from it may still be missing the content its creator wrote. True outside a workspace that syncs with a host, and for a host’s own view of a record, which holds what the workspace holds.

pub fn may(&self, need: &ActionNeed) -> bool

Whether the participant may, as of now, do what need is: an undoable change for most edits, one of the comments for a reply.

pub fn may_govern(&self) -> bool

Whether the participant may, as of now, change the workspace’s settings.

pub fn is_shared(&self, people: &People) -> bool

Whether the record is shared: someone else belongs to its workspace, or is in it with people now. Where it is, reactions are offered.

pub fn may_apply(&self, action: &R::Action) -> bool

Whether the participant may apply action (tilo_resource::need_of).

pub fn refused(&self) -> LocalState<Option<Refused>>

The last edit or effect submitted here that was refused — denied permission, unavailable, failed — and why, for a view to show. An edit waiting for the user’s confirmation is not refused.

pub fn landed(&self) -> LocalState<Option<Landed>>

The last submission of this view the door applied, with what it answered: the ids a “new” verb minted (Landed::minted), for a surface that opens what it just created.

pub fn say_when_kept(&self, text: impl Into<String>)

Say text of what was just submitted here (“Added Buy milk”) once it is kept: at once in a record nobody else decides, once the workspace accepts the change in a shared one, and never when the workspace refuses it (Self::refused says why instead). The text shows through Self::said.

pub fn said(&self) -> LocalState<Option<String>>

What Self::say_when_kept said that was kept, for the view to show and then clear.

pub fn effect<E: Effect>(&self, effect: &E)

Invoke one of the app’s effects (dispatcher.effect(&Backups::BackUp)) through the same door as a button bound to it: permission, the effect’s availability and a destructive effect’s confirmation are checked, then its handler runs. A participant who may only view still invokes the effects declared kind = "read".

pub fn is_own_gesture<E: Effect>(&self, effect: &E) -> bool

Whether the person at this device may do effect at once, as their own gesture on the surface: a shortcut, a pointer gesture, a row of the surface’s own menu, whose arguments the gesture itself supplied (the clipboard they paste). Like a keystroke, such a gesture is its own confirmation, so a surface told true performs the effect itself. The confirmation a destructive declaration asks for stays with the callers who supply its arguments — the palette, a script, an agent — because automation is the same door: under any invocation (an invoked action, an effect’s handler or completion, a dispatcher lent to one) this is false, and the surface submits the effect (Self::effect) for the host to check and confirm as for any caller. So it is in a past version, and when the participant’s role does not grant what the declaration needs.

pub fn effect_on<E: Effect>(&self, row: &str, effect: &E)

Invoke effect as the live row row offers it (LiveRow::effect): under the row’s contract, so a confirmation the row asks for (typing the name of the device it erases) is asked here too.

pub fn submit(&self, submit: impl Submit<R>)

Submit a field edit (dispatcher.submit(p.favorite.set(true))) or a verb (dispatcher.submit(Snippets::DELETE.with(id))) through the door, after the event, as a control bound to it would.

An effect’s invocation (Invoke::effect) reaches its handler as Self::effect does.

pub fn submit_on_its_own(&self, submit: impl Submit<R>)

submit what the app does on its own, for nobody’s gesture: a read receipt, keeping a record in step with what is shown. It goes through the same door and permissions; a refusal is told in Self::refused and logged, but never said over the window as if the person had pressed something and been refused.

pub fn may_invoke(&self, invoke: &Invoke<R>) -> bool

Whether the participant may take invoke: what its declaration, or the typed value it applies, needs. One this resource does not declare (an edit bound to a surface’s view state) is left to the host, which checks what its published action needs. A surface asks before work that only feeds a write (an index it would keep with a row), so a participant who may not make the write is not sent it.

pub fn open_search(&self, request: &SearchRequest)

Open the platform search with request, narrowed to this app or one part of it (SearchRequest::within). Searching is a view, so a participant who may only view can search too.

pub fn share_link(&self, resource: &str)

Ask for the link to resource (this resource or one nested in it, such as an item) as a control bound to its share-link would: the framework copies it to the clipboard and reports it in Self::landed, or why there is none in Self::refused. A link grants nothing, so a participant who may only view asks too.

pub fn open_link(&self, href: &str) -> Result<(), String>

Open what href, a tilo://open#… address a link in this view’s text carries, names: the app that keeps that resource shows it, started first when no window does.

pub fn open_reference( &self, app: &str, record: Option<&str>, reference: &ResourceRef, )

Open reference, which app keeps in its record (None: the app’s own record of the workspace), where it lives: its app opens at it, launched first when no window shows it. The open is an action like any other, admitted as the person under their grants; a refusal is told in Self::refused as open.

pub fn through_host(&self, invoke: &Invoke<R>)

Send invoke, an action of this resource, to the session’s host instead of applying it here. The host decides it as the person’s, as it decides any caller’s, may first put it to the person on its own sheet (what a run asks is answered there, never by the app), and then directs it back to be applied. A refusal is told in Self::refused.

pub fn invoke_on<T: Resource>(&self, actions: &Actions<T>, invoke: Invoke<T>)

Run invoke, one of the actions actions publishes (another record’s, such as a settings section), through the host as a control bound to it runs it: where another provider keeps the record, it runs there. From an effect’s handler or completion it continues that effect, as its caller’s. A refusal is told in Self::refused.

pub fn apply(&self, action: &R::Action)

Submit one typed action value — an edit with no named declaration, such as a drag’s final geometry. The door applies it after the event; if it refuses it, Self::refused says why.

pub fn group<T>(&self, edits: impl FnOnce() -> T) -> T

Submit every edit edits makes through this dispatcher (or a clone of it) as one action: one change, one version in history, one undo step. For a gesture that is several edits — split a linked clip pair, delete a selection — which the user takes back with one Ctrl+Z.

One action is one undo step by default; a group is the explicit exception. Groups nest: the outermost one submits. A group of one edit submits that edit unchanged.

pub fn begin_group(&self) -> DispatchGroup<R>

Open a group that submits when the returned guard drops: the group for code whose edits are spread over a scope, such as one input event of a custom surface.

pub fn submit_now( &self, edits: &mut Edits<'_>, submit: impl Submit<R>, ) -> Result<(), ActionError>

Apply a field edit (p.title.splice(..)) or a verb to the document edits lends, now, as Self::apply_now applies a typed action: for an editor that must see its own edit before the next keystroke.

One that needs confirming (a destructive verb, a removal) is not applied now: it goes to the host’s door, which asks first, and applies once the person agreed, as Self::submit does.

Errors

Returns why the submission does not build, or as Self::apply_now.

pub fn submit_gesture( &self, edits: &mut Edits<'_>, submit: impl Submit<R>, ) -> Result<(), ActionError>

Self::submit_now of the person’s own gesture on the surface: the button they pressed, the shortcut they typed, with arguments the gesture itself supplied. Like a keystroke, such a gesture is its own confirmation, so a destructive verb the surface offers with its own way back (a message held so Undo takes it back unsent) applies now. What has no way back (#[action(irreversible)]) is still asked first. The confirmation stays with the callers who supply the arguments themselves (the palette, a script, an agent): under any invocation, an effect’s handler, custody or a past version this is Self::submit_now, and the host asks as for any caller.

Errors

As Self::submit_now.

pub fn submit_confirming( &self, edits: &mut Edits<'_>, submit: impl Submit<R>, ) -> Result<(), ActionError>

Self::submit_gesture of a choice the person picked that is confirmed before it goes ahead, though Undo would take it back: Delete in a message’s context menu. The host asks with the same question it asks for any confirmation; holding Shift skips it, and the choice applies at once as the person’s gesture, if and only if Undo takes it back (ui_core::widget::shift_skips_confirmation). What Undo cannot take back is asked, Shift or not.

A control the person presses is its own confirmation (Self::submit_gesture); this is for a choice made from a list of them, where a slip of the pointer picks the neighbour.

Errors

As Self::submit_gesture.

pub fn apply_now( &self, edits: &mut Edits<'_>, action: &R::Action, ) -> Result<(), ActionError>

Apply one typed action to the document edits lends — an event’s, or a settle pass’s — now, attributed to the participant, with history recording what the action did. One event’s actions are one undo step, and an action that continues the previous one (Resource::coalesces, the next letter of a word) joins its step. An action that needs confirming (a destructive verb, a removal) is not applied now: it is submitted to the host’s door, which asks the person first (Self::apply).

Errors

Returns ActionError::Refused for a participant who may only view, and the action’s own refusal; nothing is written either way.

pub fn apply_confirmed( &self, edits: &mut Edits<'_>, action: &R::Action, ) -> Result<(), ActionError>

Self::apply_now of an action the person already confirmed, as the host applies it once they agreed: what a test resolving the queue as confirmed applies.

Errors

As apply_now.

pub fn child<C: Resource>( &self, id: &str, wrap: impl Fn(C::Action) -> R::Action + 'static, ) -> Dispatcher<C>

The dispatcher of a resource nested in this one at id — a note’s rich-text body, a draft’s SQL — whose every edit is this resource’s action wrap(edit).

The child is edited like a root: its named actions, apply, group and apply_now take C’s own actions, coalesce into undo steps by C’s Resource::coalesces, and history names them after C’s labels. Underneath, each applies as this resource’s action: the same permission check, history, undo and replay. Queued invocations are addressed to the child resource id, so this resource publishes the child at the same id with the same wrap ([tilo_resource::publish_child] in Resource::children), which is also what lets the palette, agents and scripts reach it.

pub fn settle(&self)

End the gesture the last immediate actions belonged to: the pointer was let go of a slider or a drag handle. The next action starts a step of its own even when it would continue the last one (Resource::coalesces), so two drags of one slider are two undo steps while every value one drag passes through is one.

pub fn app_id(&self) -> &'static str

The id of the app whose resource this is, which presence keys name (ResourceSelection::presence).

Trait Implementations

impl<R: Resource> Clone for Dispatcher<R>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.