Struct Command 

pub struct Command<Msg> { /* private fields */ }

Work for the runtime, returned from App::update.

Implementations

impl<Msg: Send + 'static> Command<Msg>

pub fn none() -> Self

Nothing to do.

pub fn batch(commands: impl IntoIterator<Item = Self>) -> Self

Several commands, run in order.

pub fn quit() -> Self

Leaves the application after this update.

pub fn focus(name: impl Into<String>) -> Self

Moves keyboard focus to the widget named name with NodeMut::id. When no such widget is on screen yet, focus moves to it after the next frame if it appears there, so an update can show a widget and focus it at once.

pub fn set_theme(id: impl Into<String>) -> Self

Switches to theme id. An unusable theme falls back to the default and is reported in the environment’s diagnostics.

pub fn set_locale(code: impl Into<String>) -> Self

Switches the language to the locale that serves code: a locale code such as tr, or a language tag such as en-GB, which also sets the region; see I18n::select. An unknown language changes nothing and is reported in the environment’s diagnostics.

pub fn set_region(region: Option<&str>) -> Self

Sets the region whose conventions apply, such as GB, or with None leaves them to the language again; see I18n::set_region. A code that is not a region changes nothing and is reported in the environment’s diagnostics.

pub fn set_icon_mode(mode: IconMode) -> Self

Switches between Nerd Font, Unicode, ASCII or detected glyphs.

pub fn set_reduced_motion(reduced: bool) -> Self

Turns reduced motion on or off: layers appear at once and nothing breathes or spins. Has no effect while the QUVYTA_REDUCED_MOTION environment variable decides.

pub fn set_pillar(style: PillarStyle) -> Self

Draws every pillar in style over the theme’s choice.

pub fn set_slide(slide: bool) -> Self

Turns the one-cell slide of hovered and selected entries in list structures (lists, menus, trees, tables, tab rails, setting rows, dropdown options and tabs) on or off over the theme’s motion.slide. Buttons and other controls never slide.

pub fn copy(text: impl Into<String>) -> Self

Copies text to the system clipboard (OSC 52, which also works over SSH) and to the application’s in-process clipboard, which keeps pasting inside the application working on terminals without OSC 52.

pub fn read_clipboard( message: impl FnOnce(Option<String>) -> Msg + 'static, ) -> Self

Reads the clipboard and delivers its text, or None when there is none. Like the paste key and Paste menu entries it tries, in order: the system clipboard through its tool (wl-paste, xclip or xsel, pbpaste; run without a shell, briefly, off the drawing thread), the terminal’s clipboard through an OSC 52 query (many terminals do not answer, so the wait is short), and the text copied last inside this application (by a widget, a selection or Command::copy). The message arrives in a later update once the text is known; drawing never waits for it. Text pasted with the terminal’s own paste arrives as Event::Paste instead.

pub fn perform(work: impl FnOnce() -> Msg + Send + 'static) -> Self

Runs work on a background thread and delivers its message when done. Drawing never waits for it.

pub fn confirm(confirm: Confirm<Msg>) -> Self

Asks the user a question in a dialog the runtime shows over the application, and delivers the message of their answer: the confirm message, or the cancel message (if any) for Cancel, Esc and the close mark. Cancel, the safe answer, has focus when the dialog opens. Several requests stack; the newest is answered first.

use qframe::prelude::*;

enum Msg {
    AskRemove,
    Remove,
}

fn update(msg: Msg) -> Command<Msg> {
    match msg {
        Msg::AskRemove => Command::confirm(
            Confirm::new("Remove container?", Msg::Remove).message("Its volumes are deleted too.").danger(),
        ),
        Msg::Remove => Command::none(),
    }
}

pub fn toast(toast: Toast<Msg>) -> Self

Shows toast in the toast corner, above everything else. It slides in, stays for its duration (paused while the pointer is on it) and slides out; a click on its close mark dismisses it.

It never covers an open dialog or other modal layer: it keeps to the rows between its corner and the dialog, and when there is no room there it waits, its time stopped, until there is, such as when the dialog closes.

pub fn dismiss_toast(key: impl Into<String>) -> Self

Removes the toast shown with Toast::key key.

pub fn toast_corner(corner: Corner) -> Self

Stacks toasts in corner from now on; bottom right by default.

pub fn task(task: Task<Msg>) -> Self

Starts task on a background thread. Its Started event is applied before this update returns; progress, messages and the outcome arrive as the work goes on.

pub fn cancel_task(id: TaskId) -> Self

Asks task id to stop: its sleeps wake at once, TaskCx::is_cancelled turns true and it ends as TaskOutcome::Cancelled. Asking a finished task does nothing.

pub fn handoff(handoff: Handoff<Msg>) -> Self

Hands the terminal to another program and waits for it: the application leaves raw mode and the alternate screen, the program runs attached to the real terminal, and afterwards the screen is taken back and drawn again in full. Use it for programs that talk to the user themselves, such as sudo asking for a password, an editor or a pager. The message of Handoff::new arrives once the application has the screen back. Several handoffs run one after another.

use qframe::prelude::*;
use qframe::runtime::{Handoff, HandoffOutcome};

enum Msg {
    Edit,
    Edited(HandoffOutcome),
}

fn update(msg: Msg) -> Command<Msg> {
    match msg {
        Msg::Edit => Command::handoff(Handoff::new("vi", Msg::Edited).arg("notes.md")),
        Msg::Edited(_) => Command::none(),
    }
}

pub fn handoff_detached(handoff: DetachedHandoff<Msg>) -> Self

Hands the terminal to a program until it writes its first line, then takes the screen back and leaves the program running in the background, its standard input and output piped to the application. Use it for a program that asks the user something on the terminal and then serves the application, such as a privileged helper started through pkexec. See DetachedHandoff for the whole course; it queues with Command::handoff, one after another.

use qframe::prelude::*;
use qframe::runtime::{ChildLine, DetachedHandoff, DetachedOutcome};

enum Msg {
    Start,
    Started(DetachedOutcome),
    Said(ChildLine),
}

fn update(msg: Msg) -> Command<Msg> {
    match msg {
        Msg::Start => Command::handoff_detached(
            DetachedHandoff::new("sh", Msg::Started).args(["-c", "echo ready; cat"]).on_line(Msg::Said),
        ),
        Msg::Started(_) | Msg::Said(_) => Command::none(),
    }
}

pub fn map<B: Send + 'static>( self, map: impl Fn(Msg) -> B + Send + Sync + 'static, ) -> Command<B>

The same work delivering map(message) wherever it would deliver message, so a screen with messages of its own can return its commands from the application’s update:

use qframe::prelude::*;

mod search {
    use qframe::prelude::*;

    pub enum Msg {
        Run,
        Found(usize),
    }

    pub fn update(msg: Msg) -> Command<Msg> {
        match msg {
            Msg::Run => Command::perform(|| Msg::Found(3)),
            Msg::Found(_) => Command::none(),
        }
    }
}

enum Msg {
    Search(search::Msg),
}

fn update(msg: Msg) -> Command<Msg> {
    match msg {
        Msg::Search(msg) => search::update(msg).map(Msg::Search),
    }
}

Every kind of work is carried over: a message the work of Command::perform or a Task produces later on its own thread (its result, what it sends while it runs, its events), the answers of Command::confirm, the action and presses of a toast, the clipboard text of Command::read_clipboard, the message after a Command::handoff, and the messages of a Command::handoff_detached and of the child it leaves running. Work without messages (focus, theme, copy, cancelling a task) is unchanged.

map runs on the threads of that background work, and one command can hold several of them, so it is shared rather than copied: it must be Send and Sync, and it is never required to be Clone. An enum variant such as Msg::Search or a closure over Send + Sync values qualifies.