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 and icons of the family’s shared Preferences, as Family::preferences resolved them for this application. They win over Runtime::theme and over the same keys in Runtime::settings, which keeps the rest: reduced motion, pillar and slide.

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

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.