Trait ResourceApp 

pub trait ResourceApp: 'static {
    type Resource: Resource;

    const ID: &'static str;
    const TITLE: &'static str;
    const ICON: Option<&'static str> = None;
    const BEHAVIOUR: ComponentBehaviour = ComponentBehaviour::DEFAULT;
    const OPENS: &'static [&'static str] = _;
    const ARGUMENTS: usize = 0;
    const DOCUMENT_HISTORY: bool = true;
    const ROOM_RECORD: bool = false;
    const OPTIONS: &'static [&'static str] = _;
    const FLAGS: &'static [&'static str] = _;
    const PRIVATE_WINDOWS: bool = false;
    const FILE_HISTORY: Option<FileHistory> = None;
    const ATTACHES_RUNTIME: bool = true;

    // Required method
    fn view(cx: &mut ViewCx<Self::Resource>) -> Element;

    // Provided methods
    fn label(state: &<Self::Resource as Resource>::State) -> String { ... }
    fn local_operations() -> Vec<ActionSpec> { ... }
    fn launch_record(input: &LaunchInput<'_>) -> Option<RecordId> { ... }
    fn launch(
        input: &LaunchInput<'_>,
        created: bool,
    ) -> Vec<Invoke<Self::Resource>> { ... }
    fn genesis(input: &LaunchInput<'_>) -> Vec<Invoke<Self::Resource>> { ... }
    fn commands() -> &'static [Command] { ... }
    fn helpers() -> &'static [Helper] { ... }
    fn catalog() -> Option<&'static EmbeddedCatalog> { ... }
    fn scenarios() -> &'static [&'static str] { ... }
    fn shot_viewport(scenario: Option<&str>) -> (u32, u32) { ... }
    fn fixture(fixture: &mut Fixture<Self::Resource>) { ... }
    fn scenario(name: Option<&str>) -> Vec<Invoke<Self::Resource>> { ... }
    fn scenario_input(
        name: Option<&str>,
        input: &mut FrameHarness,
    ) -> Result<(), String> { ... }
    fn seed(cx: &SeedCx<'_>) -> Vec<Invoke<Self::Resource>> { ... }
    fn records(records: &mut Records<'_>) { ... }
}

A framework app: one resource type and a view of it.

Everything else — storage, sync, collaboration, history, undo, permissions, the action palette, the agent and script door, search — is provided. See the module docs.

Required Associated Constants

const ID: &'static str

The application id, e.g. "so.tilo.scratchpad".

const TITLE: &'static str

The window and launcher title.

Provided Associated Constants

const ICON: Option<&'static str> = None

A named icon; defaults to the app id’s last segment.

const BEHAVIOUR: ComponentBehaviour = ComponentBehaviour::DEFAULT

How every window hosting the app treats it: focus after a rebuild, live appearance, and whether captures withhold it. An app that shows secrets declares capture_protected here, so the live launch, the shell and every other host of its component protect it alike; an on-screen keyboard declares its window an input surface.

const OPENS: &'static [&'static str] = _

Media types (type/subtype, lowercase) of the files the app opens when a host hands it one (a file association, a file dropped on its icon, a path of that type on its command line); Self::launch receives the file. "*/*" (ANY_MEDIA_TYPE) opens every file, a file whose name says nothing of its type as application/octet-stream.

const ARGUMENTS: usize = 0

How many arguments (paths, URLs) a launch may name; Self::launch_record and Self::launch receive them.

const DOCUMENT_HISTORY: bool = true

Whether the resource keeps document state whose versions History shows. An app whose state lives outside its document (a measurement, a device) sets false: it publishes no History actions and its window offers no History.

const ROOM_RECORD: bool = false

The app keeps one record per room, the room’s own, rather than one per window: every window of the app in the room opens that record, and the first one creates it (and applies Self::seed). A room’s conversation is such a record.

const OPTIONS: &'static [&'static str] = _

The app’s own command-line options that take a value (--purpose number or --purpose=number): how this window runs rather than what it opens. Self::launch reads them from its LaunchInput::option, views and surfaces from RecordEnv::launch_option.

const FLAGS: &'static [&'static str] = _

The app’s own switches, which take no value (--debug-hit-areas): LaunchInput::flag, RecordEnv::launch_flag.

const PRIVATE_WINDOWS: bool = false

Whether the app opens private windows (--private): a window on a profile of its own that is thrown away with the process — its record, settings and files never reach the person’s — and that attaches to no runtime, so nothing it shows syncs or is shared. It holds none of the person’s own records (RecordEnv::person answers None), and its view tells with RecordEnv::is_private.

const FILE_HISTORY: Option<FileHistory> = None

The history of a file of the mounted filesystem the app shows (the file selected in a file manager), a History scope beside the resource’s own: its versions are read, previewed and restored through the filesystem’s projection, not the app’s document. The app’s surface names the file with SurfaceCx::file_history.

const ATTACHES_RUNTIME: bool = true

Whether the app takes part in the workspace runtime of the room it is launched in. An app that only runs on this device (an imager on a platform without the runtime) says no.

Required Associated Types

type Resource: Resource

The resource this app edits.

Required Methods

fn view(cx: &mut ViewCx<Self::Resource>) -> Element

Build the view. Called once for the live app, and again for every historical version History mode shows (with a read-only context), so it must build widgets and nothing else.

Provided Methods

fn label(state: &<Self::Resource as Resource>::State) -> String

The label of the open resource in the palette and in history.

fn local_operations() -> Vec<ActionSpec>

View and effect operations of this app’s presentation, published on the same resource as Resource::local_operations. A shared resource type (rich text) does not know about one app’s chrome. Document mutations do not belong here. History does not either: it is the resource’s own history, not a toggle beside it.

fn launch_record(input: &LaunchInput<'_>) -> Option<RecordId>

The record a launch naming input opens: the file’s own record (RecordId::identify_file), a record derived from it (RecordId::derived), a minted one. None, the default, opens the record the app would open anyway: the one the window showed last, else the room’s default. Asked by a launcher that picks the record (the command line, a test host), before the record is opened, so it must not depend on anything but input.

fn launch(input: &LaunchInput<'_>, created: bool) -> Vec<Invoke<Self::Resource>>

The actions a launch naming input takes once its record is open; created when this launch created the record, so actions that fill a new record (the source of a new project) are taken only then. They go through the same door as every control: checked against the participant’s permissions, attributed, undoable and in history. A launch that shows something rather than changing the resource (a link to one item, a file to look at before acting on it) invokes one of the app’s effects (Invoke::effect) through the same door. A capture launched on nothing takes none: its scenario stages the record.

When the record was already there, LaunchInput::record reads it as it is: a launch on a file can tell that the file changed since the record last read or wrote it.

fn genesis(input: &LaunchInput<'_>) -> Vec<Invoke<Self::Resource>>

What a record a launch naming input creates starts with besides the resource’s initialize: the content of the file it was launched on. The actions are written into the record’s genesis, so they must depend on nothing but input — two devices that each create the record of one file converge on one document only if both write the same genesis. They are nobody’s edit: no history entry, no undo.

fn commands() -> &'static [Command]

The commands the app’s binary runs instead of opening a window.

fn helpers() -> &'static [Helper]

The helpers the app’s binary also is (Helper), asked in order before the app starts.

fn catalog() -> Option<&'static EmbeddedCatalog>

The app’s message catalog, loaded before its view is built in every host that mounts the app, so the view’s lookups find its messages.

fn scenarios() -> &'static [&'static str]

Named screenshot scenarios for --shots --scenario NAME; --shots-dir captures every one.

fn shot_viewport(scenario: Option<&str>) -> (u32, u32)

The viewport a capture of scenario (None for a plain --shots) is drawn at, unless --viewport names one: a narrow scenario’s phone-sized window.

fn fixture(fixture: &mut Fixture<Self::Resource>)

Prepare what a capture of fixture.scenario() shows that its actions cannot stage, before the view is built: typed stand-ins for live sources, scratch files, content-store blobs, other people’s versions and collaborators. Runs only for a capture, whose views are built in RunMode::Capture. See Fixture.

fn scenario(name: Option<&str>) -> Vec<Invoke<Self::Resource>>

The actions that stage the resource for a capture: Some(name) for --shots --scenario NAME, None for a plain --shots. They apply through the same door as every control; then the views stage their view state (ViewCx::on_stage, ResourceSurface::stage) and the frame is captured. See stage.

fn scenario_input( name: Option<&str>, input: &mut FrameHarness, ) -> Result<(), String>

What a person does in the scene that the scenario’s actions and staged view state cannot show: text typed into an editor, a drag held over its drop target, a menu opened with a right click. Driven on input through the window’s own event path after the actions and staging, so the frame shows the app’s real answer to that input. Must be deterministic, like the rest of the scenario.

Errors

Returns why the input could not be given (its target is missing).

fn seed(cx: &SeedCx<'_>) -> Vec<Invoke<Self::Resource>>

What a brand-new record starts with that depends on who creates it or where: the creator as its owner, a first-run import of settings that already exist on this device. Everything that depends on neither is the resource’s initialize, which is the same on every device so that two people creating the same record converge on one.

The actions apply once, right after the genesis, attributed to the creator and recorded as content from outside: they sync like any edit but are nobody’s undo step, so a first Ctrl+Z does not take the seed back. A collaborator who creates the same record concurrently seeds it too, so a seed sets values rather than adding rows.

fn records(records: &mut Records<'_>)

The records the app keeps besides the one it shows: the person’s own records and the settings sections that are resource models. Each is opened with the window and published beside the app’s resource, so the palette and agents change it whether or not a view has shown it, and tilo-app surface commits its surface with the app’s.

fn records(records: &mut Records<'_>) {
    records.person::<WatchHistory>().settings::<Playback>();
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl ResourceApp for FeedbackComposer

const ID: &'static str = "so.tilo.feedback-composer"

const TITLE: &'static str = "Feedback"

const DOCUMENT_HISTORY: bool = false

const PRIVATE_WINDOWS: bool = true

const BEHAVIOUR: ComponentBehaviour

type Resource = FeedbackDraft