Struct ViewCx 

pub struct ViewCx<R: Resource, T: 'static = <R as Resource>::State> { /* private fields */ }

Everything a view needs: reads of the resource state, bindings of controls to actions, local state, and custom surfaces.

T is what this scope reads — the resource state at the root, one item in a row built by ViewCx::each.

Implementations

impl<R: Resource, T: 'static> ViewCx<R, T>

pub fn record<P: Resource>( &self, record: &impl OtherRecord<P>, part: impl FnOnce(&mut ViewCx<P>) -> Element, ) -> Option<Element>

A part of the view over another record than the app’s own — the person’s own record (RecordEnv::person), a settings section (RecordEnv::settings) — built like a view of that record: its controls bind the record’s paths (cx.checkbox("high-contrast", Appearance::paths().high_contrast)) and verbs, its edits go to that record as the person, recorded in its history, and the part follows every change of it. None where the record cannot be held (a view of a past version).

impl<R: Resource, T: 'static> ViewCx<R, T>

pub fn live(&self) -> &Live<R>

The live resource state, for reads a binding does not cover.

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

Observe what this participant may do, without storing their role in the shared resource. Use this with Self::switch for an owner-only pane, or with a bound widget for a permission-specific label. Changes follow the host even when the document and write access stay unchanged. This controls presentation; the action door remains the authority.

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

Whether this participant may govern the room, observed: for an owner-only pane with Self::switch.

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

Whether this participant may only view, as state that follows role changes while the app runs.

pub fn item(&self) -> Option<&Id>

The item this scope stands for, inside an Each row.

pub fn history(&self, last: usize) -> LocalState<Vec<HistoryVersion>>

The resource’s last last versions, oldest first, kept current as the document moves: an in-app history list of what was done and by whom, each version addressable by the undo, restore and checkpoint actions every app publishes.

pub fn read<V>(&self, read: impl FnOnce(Option<&T>) -> V) -> V

Read the scope’s value now (at build time). For values that must follow the resource, use a binding such as Self::text.

pub fn local<V: Send + Sync + 'static>(&self, initial: V) -> LocalState<V>

Typed process-local view state: never persisted, shared or undone.

pub fn on_open<O: Outcome>(&self, open: impl FnMut(&str) -> O + 'static)

Show the item a search hit opens: open runs with the hit’s anchor (a SearchEntry’s anchor) when the person picks the hit, or when an agent invokes the resource’s open action. Select the item, switch to its page, scroll it into view: set the LocalStates that show it, as the person’s own input would.

open may refuse an anchor it cannot show (a row that is gone) by returning Err; the person or agent is told why.

pub fn on_open_item( &self, open: impl FnMut(&Id) -> Result<(), Refusal> + 'static, )

Show the item of the resource a search hit or an agent’s open names: open runs with its id, and refuses one it cannot show (an item that no longer exists), which the person or agent is told. Anchors that name no item of the resource are refused for it.

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

Open the platform search with request, narrowed to this app or one part of it. Usually a control does this (Self::search_button); a custom handler calls Dispatcher::open_search on its dispatcher.

pub fn search_button(&self, request: SearchRequest) -> Button

The search launcher for this view’s chrome: an icon button that opens the platform search with request. Apps never draw a search field.

pub fn on_stage(&self, stage: impl FnMut(Option<&str>) + 'static)

Stage view state for a screenshot scenario: stage runs with the scenario’s name (None for a plain --shots) after the scenario’s actions applied and were laid out, and before the frame is captured. Set the LocalStates a scenario shows — a selection, an open dialog — the way the user’s input would. It never runs in a live window.

pub fn text(&self, read: impl Fn(&T) -> String + 'static) -> Text

Text that always shows read of the resource.

pub fn button( &self, label: impl Into<LabelKey>, submit: impl Submit<R>, ) -> Button

A button that submits one fully specified action: a verb with its arguments (Snippets::NEW_SNIPPET.with(..)), a field edit (p.favorite.set(true)) or a form (Form::submit).

pub fn form<P: Params<Resource = R>>(&self) -> Form<P>

The form of the verb whose parameters are P (cx.form::<bookmarks::Add>()): local values, never synced or undone, that controls bind to with the parameters’ paths (cx.input(form.paths().url)) and a button submits as one invocation (cx.button("bookmarks-add", form.submit())). The same form is answered for P everywhere in this scope.

pub fn input<M>(&self, field: impl Bindable<R, String, M>) -> TextInput

A text field for the text at field: a path into the record, whose committed edits replace it (Path::replace; the keystrokes of one word are one undo step), or into a form (Self::form).

pub fn checkbox<M>( &self, label: impl Into<LabelKey>, field: impl Bindable<R, bool, M>, ) -> Checkbox

A checkbox for the flag at field, a path into the record or a form; toggling sets it.

pub fn control<V, C, M>( &self, make: impl FnOnce(&LocalState<V>) -> C, field: impl Bindable<R, V, M>, ) -> C

where V: Settable + 'static, C: ActionControl<V>,

Any toolkit control for the value at field, a path into the record or a form, setting it with each committed value: cx.control(Slider::from_state, p.volume).

pub fn bind_declarations( &self, bind: impl Fn(&R::State) -> Vec<ActionDecl<R>> + 'static, )

Publish edits bound to this view’s local state — the folder shown, the row selected — on the resource beside its declared actions, as typed builders of its action: bind runs whenever the published tree is read, with the current resource state, and reads the local state it captured. Invoking one dispatches what it builds through the same permission check, confirmation and undo as any other action. The binding lasts as long as this view scope (a row’s ends with the row); an id the resource already publishes keeps the resource’s action unless the bound one refines it (tilo_resource::bind_declaration).

pub fn actions(&self) -> Actions<R>

The resource’s published actions, for binding controls built outside the view function: the rows a table, list or tree creates on demand.

pub fn value<V>(&self, read: impl Fn(&T) -> V + 'static) -> LocalState<V>

where V: PartialEq + Default + Clone + 'static,

A value that follows read of the resource, for any toolkit control built from a LocalState (Slider::from_state, Dropdown::from_state).

pub fn control_with<V, C>( &self, make: impl FnOnce(&LocalState<V>) -> C, read: impl Fn(&T) -> V + 'static, action: impl Binds<R, V>, ) -> C

where V: PartialEq + Default + Clone + 'static, C: ActionControl<V>,

A toolkit control bound to a verb: it shows read of the resource and invokes action with each committed value, for a value that is a verb’s argument rather than a field (cx.control_with(TextInput::from_state, |p| p.shape(&node), Project::SET_SHAPE.map(..))). The control is disabled when the action is not published. A field of the record is bound by its path instead (Self::input, Self::checkbox, Self::control).

pub fn switch<K>( &self, key: &LocalState<K>, part: impl Fn(&mut ViewCx<R, T>, &K) -> Element + 'static, ) -> Element

where K: Clone + PartialEq + 'static,

A part of the view chosen by view-local state — the detail pane of the selected item, the page of a wizard. The part is built again, with its own bindings, whenever key changes; the previous one is dropped.

pub fn surface<S, E>(&self, surface: S) -> Element

where S: ResourceSurface<R, E> + 'static, E: Effect,

Host a custom widget or renderer that takes part through the ResourceSurface contract, answering its effect vocabulary E (none unless it implements ResourceSurface<R, E>).

pub fn effects<E: Effect>( &self, handle: impl FnMut(E, &mut EffectCx<R>) -> EffectAnswer + 'static, ) -> EffectsHandle

Answer the effect vocabulary E — work with no document delta that a button, the palette, an agent or a script invokes — with handle, and publish E on the resource while this part of the view lives.

handle receives each invocation as a typed value. It finishes at once (Effected::done) or starts a job through the EffectCx (for an effect declared job); a job’s completion runs on the UI thread and changes the document through the context’s dispatcher. Handlers never run in History mode. Say which effects are unavailable or relabelled right now with EffectsHandle::status.

pub fn jobs(&self) -> Jobs<R>

Jobs the view starts on its own, with nobody invoking an effect: a fetch when what it shows changes. See Jobs.

pub fn effect_button<E: Effect>( &self, label: impl Into<LabelKey>, effect: &E, ) -> Button

A button that invokes one effect, through the same door (and the same confirmation, for a destructive one) as the palette.

impl<R: Resource, T: Model + 'static> ViewCx<R, T>

pub fn paths(&self) -> T::Paths<R>

The typed paths of this scope’s value: the record’s fields at the root, the item’s in a row of Self::each. Controls bind to them (row.checkbox("snippets-favorite", p.favorite)) and edits are made at them (p.favorite.set(true)).

Panics

Panics inside a row of a collection Self::each could not find among the fields of the value it was given.

pub fn each<I: Model + 'static>( &self, items: impl Fn(&T) -> &Collection<I> + 'static, row: impl Fn(&mut ViewCx<R, I>) -> Element + 'static, ) -> Each<R>

One row per item of a collection, kept in collection order: cx.each(|snippets| &snippets.snippets, |row| ...). A row is built once per item and retained while the item exists, so focus and caret inside it survive other items changing; rows are added, removed and moved only when the collection’s membership changes. In a row, Self::paths are rooted at its item. A row’s context menu (right-click, the Menu key or Shift+F10) offers the actions the resource publishes on its item, with the item already bound.

impl<R, T: 'static> ViewCx<R, T>

where R: Resource<State = R> + Model,

Binding controls to the record’s fields by path.

pub fn value_at<V>(&self, path: &Path<R, V>) -> LocalState<V>

where V: PartialEq + Default + Clone + 'static,

The value at path, as local state that follows it: for any toolkit control built from a LocalState, or a part of the view that shows it. It is read again only after changes that touched it.

pub fn route_graph_text( &self, values: &UiValues, ui_path: &str, path: Path<R, String>, )

Route a serialized screen’s text inputs over ui_path to the text field at path (UiValues::route): they show it and each edit replaces it.

pub fn route_graph_bool( &self, values: &UiValues, ui_path: &str, path: Path<R, bool>, )

Route a serialized screen’s checked controls over ui_path to the flag at path: they show it and each toggle sets it.

pub fn control_map<V, I, C>( &self, make: impl FnOnce(&LocalState<I>) -> C, path: Path<R, V>, show: impl Fn(&V) -> I + 'static, store: impl Fn(I) -> V + Send + Sync + 'static, ) -> C

where V: Settable + PartialEq + Default + Clone + 'static, I: PartialEq + Clone + Send + Sync + 'static, C: ActionControl<I>,

A toolkit control whose value is not the field’s own type: a slider (f64) for an optional hue (Option<f64>), a dropdown of names for a flag. It shows show of the value at path and sets the field to store of each committed value: cx.control_map(Slider::from_state, p.hue, |hue| hue.unwrap_or(0.5), Some).

Methods from Deref<Target = RecordEnv<R>>

pub fn open_here( &self, arguments: &[String], ) -> Result<ReplacementOutcome, String>

Open, in this window and in place of the record it shows, what a launch of the app naming arguments opens: the record ResourceApp::launch_record names, with its launch actions — the document a person chose with the app’s own Open. The window’s view is rebuilt for that record on the next frame. Refused in a past version and a capture.

The outcome answers once the host opened it, or why it could not.

Errors

Returns that the window cannot open another record.

pub fn people(&self) -> People

The names of the participants, for showing the ids actions record (People::name).

pub fn dispatcher(&self) -> Dispatcher<R>

Where edits go. Custom widgets keep a clone.

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

The dispatcher of the resource nested in this one at id, whose edits are this resource’s action wrap(edit): a rich-text body, a draft, a SQL buffer. See Dispatcher::child.

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

Who this view is for: the participant reading and editing through it, the same id an action they invoke reads as its author (ActionCx::author). Compare the authors the resource records with it (“your message”, “you reacted”) instead of keeping the reader in the resource state, which is the same for everyone. None in a view of a past version.

pub fn is_past(&self) -> bool

Whether this view shows a past version in History mode, drawn from a frozen document. It must start no work there: a surface that fetches, watches or spawns a worker is built without it and presents what the document holds.

pub fn read_only(&self) -> bool

Whether this participant may only view, when the view is built. Bound controls already follow permission changes on their own; to show or disable something else while the participant may only view, bind to ViewCx::read_only_state, which follows role changes while the app runs.

pub fn save_status(&self) -> LocalState<RecordSaveStatus>

Whether the record’s latest edits are durable, for a status line. Saving is automatic; there is nothing to save by hand.

pub fn mode(&self) -> RunMode

What the view is built for: a window someone uses, a past version in History, or a screenshot. Start work that reaches outside the process (an engine, a socket, a probe) only when it is live.

pub fn fixture<V: 'static>(&self) -> Option<Rc<V>>

The capture’s stand-in for a live source of type V (Fixture::provide); None outside a capture, or when the scenario provides none.

pub fn content(&self) -> Option<ContentStore>

The content store the host lent the app: opaque blobs by hash that outlive it. A capture’s holds the blobs its scenario put there.

pub fn launch(&self) -> LaunchInput<'_>

What the launch that opened this window named — the file a person opened the app with, its command line — for a view that shows what the launch’s actions (ResourceApp::launch) made: the note a launch imported, opened. Empty for a plain start and for a past version.

pub fn launch_arguments(&self) -> &[String]

What the window’s launch named (paths, URLs), for a view that acts on them beyond the actions the launch took: the file a save writes back to. Empty for a plain start, a past version and a capture.

pub fn launch_option(&self, name: &str) -> Option<&str>

The value of the app’s own option name (--purpose) the window’s launch named; see ResourceApp::OPTIONS. None for a past version.

pub fn launch_flag(&self, name: &str) -> bool

Whether the window’s launch named the app’s switch name; see ResourceApp::FLAGS.

pub fn take_lent<S: 'static>(&self) -> Option<S>

The service of type T the host that mounts the app in its own process lent it (HostContext::lend), taken once: the shell’s connection to the session’s process supervisor for a terminal it hosts. None in the app’s own process, and for a past version or a capture, which start nothing.

pub fn is_private(&self) -> bool

Whether the window is private (ResourceApp::PRIVATE_WINDOWS): its record, settings and files are thrown away with the process. A view keeps what it would otherwise remember on the device (visits, a session to restore) to itself.

pub fn settings<S>(&self) -> Setting<S>

where S: SettingsSchema + Clone + PartialEq + Send + Sync,

The app’s typed settings of type S, kept current while this scope lives. S declares whether they follow the person or stay on the device (Scope).

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

The device this window runs on: stable across launches, distinct on each of the person’s devices. None in a view of a past version. An action that records where something happened (a speed test run on this device) takes it as an argument, so every replica applies the same value.

pub fn person<P: Resource>(&self) -> Option<PersonRecord<P>>

The person’s own record of P (PersonRecord): theirs alone, kept in their own room and synced to their other devices, never to a collaborator, whatever room this record is in. None where the host keeps no records of the person’s (a view of a past version) or the record cannot be opened.

pub fn shared_person<P: SharedRecord>(&self) -> Option<PersonRecord<P>>

The person’s record P that one app keeps for all of theirs — their accounts, which Settings keeps: the same record on every device, held here too and converging with the keeper’s over the person’s own room. Changed only by its owner and editors (SharedRecord, PersonRecord::editable); for its owner it is Self::person.

pub fn storage(&self) -> &AppStorage

The app’s files, secrets and settings documents, as its host gave them. A secret of one document item is cx.storage().secrets().item(purpose, id).

pub fn outbox<E, O>( &self, outbox: Path<R, Outbox<E, O>>, owns: impl Fn(&R::State, &E) -> bool + 'static, run: impl FnMut(&Id, E, &mut EffectCx<R>) -> EffectAnswer + 'static, ) -> Projection

where R: Resource<State = R> + Model + 'static, E: Model + Clone + 'static, O: Serialize + DeserializeOwned + Default + 'static,

Carry out the entries of the Outbox at outbox that this device owns, and record how each settled.

Every replica holds the entries; owns says which are this device’s to carry out (the device whose disk a file operation names, the one holding the mail account). For each such pending entry the framework runs run in the live app — never in History or a capture — at once or as a job through its EffectCx, and records the answer with the outbox’s settle edit: content from outside, nobody’s undo step. The answer settles the entry: Effected::settled with how it went, Effected::value with the result O, or Effected::done for O’s default. An Err leaves the entry pending, to run again after the next change or when the returned Projection is told the outside changed (the server came back); a failure for good is a Settled::Failed.

pub fn outbox_awaited<E, O>( &self, outbox: Path<R, Outbox<E, O>>, owns: impl Fn(&R::State, &E) -> bool + 'static, run: impl FnMut(&Id, E, &mut EffectCx<R>) -> EffectAnswer + 'static, ) -> Projection

where R: Resource<State = R> + Model + 'static, E: Model + Clone + 'static, O: Serialize + DeserializeOwned + Default + 'static,

Self::outbox, where an entry is the outside half of the action that queued it: one an admitted invocation on this device queues runs at once under that invocation — cx.invocation() names it, and its custody authorises what the handler does for it (a native host that acts only on behalf of an invocation) — and the invocation completes only once its entries settled, failing with a failed one. Entries queued elsewhere, replayed or still pending after a restart run as Self::outbox runs them, with no invocation.

Trait Implementations

impl<R: Resource, T: 'static> Deref for ViewCx<R, T>

type Target = RecordEnv<R>

The resulting type after dereferencing.

fn deref(&self) -> &RecordEnv<R>

Dereferences the value.