Struct SurfaceCx 

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

What a surface receives when attached.

Implementations

impl<R: Resource> SurfaceCx<R>

pub fn record_actions<P: Resource>( &self, record: &impl OtherRecord<P>, ) -> Option<Actions<P>>

The published actions of another record than the app’s own — the person’s own record, a settings section: a hand surface binds its controls to the record’s verbs and field edits with them, as to its own, submits through Actions’ bindings, and offers them on its live rows (Actions::operation). None where the record cannot be held.

impl<R: Resource> SurfaceCx<R>

pub fn record(&self) -> Option<&RecordId>

The host-owned identity of the record this surface shows. A durable activation link can name it without relying on the last-open window. Absent in a historical view that cannot launch live work.

pub fn opener(&self) -> Option<OpenHere>

What RecordEnv::open_here does, kept for later: the input that asks for another record arrives after attaching (a file chosen in a picker). None in a past version and a capture.

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

Jobs the surface starts on its own, with nobody invoking an effect; their completions get &mut the surface (jobs.start::<Self>(…)). Keep the handle. See Jobs.

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

The resource’s published actions and the surface’s effects, for binding the toolkit controls a surface builds itself (a toggle, a dropdown, a button deep in its own widget tree) the way a view’s controls are bound: Actions::bind, Actions::bind_effect.

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

The live state, for a surface that reads it where it needs it (in draw, in an event) rather than copying what it was presented, and that asks for the parts of a large resource it shows (Live::demand).

pub fn file_history(&self) -> Option<FileHistorySource>

The file whose history History shows beside the resource’s, for an app that declares ResourceApp::FILE_HISTORY: set its target to the file the surface shows (the selected one) and open it from the surface’s own History command. None for any other app, and in a past version.

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

The id of the app the surface is part of, which its presence keys name (ResourceSelection::presence).

pub fn secrets(&self) -> SecretStore

The app’s secrets. A secret of one document item (a profile’s password) is cx.secrets().item(purpose, id).

pub fn files(&self) -> AppFiles

The app’s private file areas.

pub fn waker(&self) -> WakeHandle

Wakes the app from another thread — a worker’s result, a socket’s message — so the surface syncs and draws it without waiting for input.

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> Deref for SurfaceCx<R>

type Target = RecordEnv<R>

The resulting type after dereferencing.

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

Dereferences the value.