Struct Runtime 

pub struct Runtime<A: App> { /* private fields */ }

Configures and runs an application in the terminal.

Implementations

impl<A: App> Runtime<A>

pub fn new(app: A) -> Self

A runtime for app with built-in files only.

pub fn theme_dir(self, dir: impl Into<PathBuf>) -> Self

Loads theme files from dir.

pub fn theme_source( self, file: impl Into<String>, text: impl Into<String>, ) -> Self

Loads a theme file given as text, such as one compiled in with include_str!, so an installed program needs no files beside it. file names it in diagnostics and its stem is the theme id, the way a directory names its files. Text given this way wins over Runtime::theme_dir.

pub fn icon_dir(self, dir: impl Into<PathBuf>) -> Self

Loads icon set files from dir.

pub fn icon_source( self, file: impl Into<String>, text: impl Into<String>, ) -> Self

Loads an icon set given as text, such as one compiled in with include_str!, so an installed program needs no files beside it. file names it in diagnostics and its stem is the icon set id, the way a directory names its files. Text given this way wins over Runtime::icon_dir.

This is also how an application gives its own icons: keys the built-in set lacks, such as category.internet, are drawn by every widget that takes an icon key, in whatever set the theme chooses and in the glyph mode in use. A key the built-in set has, such as check, restyles the framework’s icon only while a theme names this set; see IconSetRegistry.

pub fn locale_dir(self, dir: impl Into<PathBuf>) -> Self

Loads locale files from dir.

pub fn locale_source( self, file: impl Into<String>, text: impl Into<String>, ) -> Self

Loads a locale file given as text, such as one compiled in with include_str!, so an installed program needs no files beside it. file names it in diagnostics. Text given this way wins over Runtime::locale_dir.

let english = "[meta]\nname = \"English\"\ncode = \"en\"\n[app]\ngreeting = \"Hello\"\n";
Runtime::new(Hello).locale_source("en.toml", english).run()

pub fn keymap_file(self, file: impl Into<PathBuf>) -> Self

Layers keymap file over the built-in keymap.

pub fn keymap_source( self, file: impl Into<String>, text: impl Into<String>, ) -> Self

Layers a keymap given as text over the built-in keymap, such as one compiled in with include_str!, so an installed program needs no files beside it. file names it in diagnostics. Text given this way wins over Runtime::keymap_file.

let keys = "[app]\nsave = \"ctrl+s\"\n";
Runtime::new(Hello).keymap_source("keymap.toml", keys).run()

pub fn theme(self, id: impl Into<String>) -> Self

Starts with theme id instead of the default.

pub fn settings(self, settings: &Settings) -> Self

Starts with the theme, language, icon mode and reduced motion saved in settings, so the first frame already looks the way the user left it. Saved values win over Runtime::theme.

pub fn preferences(self, preferences: &Preferences) -> Self

Starts with the language, theme, icons and reduced motion of the ecosystem’s shared Preferences, as Ecosystem::preferences resolved them for this application. They win over Runtime::theme and over the same keys in Runtime::settings, which keeps the rest: pillar and slide.

let ecosystem = Ecosystem::QUVYTA;
let settings = Settings::load_member(&ecosystem, "hello");
let prefs = ecosystem.preferences("hello", &I18n::builtin());
Runtime::new(Hello).settings(&settings).preferences(&prefs).run()

pub fn member(self, ecosystem: Ecosystem, app: &str) -> Self

Runs the application as member app of ecosystem, in one call: its own settings are loaded with Settings::load_member, the shared preferences resolved with Ecosystem::preferences in the language files this runtime loads, and both applied before the first frame, as Runtime::settings and Runtime::preferences apply them.

While the application runs, the ecosystem’s folder is watched. When the shared file or the application’s own file changes, say because another application switched the theme for the whole ecosystem, the preferences are resolved again without writing anything and what changed is applied at once: language, theme, icons and reduced motion, and the pillar when the application’s own file changed it. A value the application chose for itself stays, since resolving gives it first. App::preferences hears the start and every change, so a settings screen can show the new values.

The watch uses the system’s own events and a thread that sleeps until the folder changes; it costs nothing while nothing changes. Where the folder cannot be watched (no home folder, a platform without a folder watch, the system’s limit on watches reached), the application runs with what it started with, as before. The watch ends with the run.

Settings or preferences also given with Runtime::settings or Runtime::preferences are used as given and not read a second time, so an application moving over can keep its own reading for now.

Runtime::new(Hello).member(Ecosystem::QUVYTA, "hello").run()

pub fn member_in( self, ecosystem: Ecosystem, config_dir: impl Into<PathBuf>, app: &str, ) -> Self

member with config_dir as the ecosystem’s folder instead of this platform’s, for an application that keeps its settings where it chooses, and for a demo.

pub fn run(self) -> Result<()>

Takes over the terminal and runs until the application quits. The terminal is restored on return and on panic.

Signals

On Unix the run catches SIGTERM, SIGINT and SIGHUP and ends gracefully instead of dying on the spot: the application hears the cause through App::terminating, may save, and quits; see Termination for what each signal does and the grace it leaves. The loop is woken the moment a signal arrives, even while it waits for a key or a deadline.

Every way out ends in bounded time: after the grace the run quits without the application, a second SIGTERM or SIGINT quits at once, and when the loop itself is stuck the process is ended a second later all the same, by the signal, after the terminal is restored. The terminal is left in application mode in no case while it exists; after a hangup nothing more is written to it.

During a Handoff, and a DetachedHandoff until the program’s first line, the program owns the terminal’s foreground. A signal the application catches meanwhile is passed on to the program, which ends the way it would have as a job of the shell; the application then takes the terminal back and hears the signal itself. A hangup reaches the program from the system anyway.

Once run returns the signals have their usual effect again.

Errors

Returns I/O errors from loading asset directories or from the terminal.