voussoir

Multi-window

A window is a label, a page, and a command surface. Everything else (sending an event, closing it, narrowing it) addresses a window by that label.

Opening one

let label = app.open_window(WindowOptions {
    title: Some("Settings".to_owned()),
    width: Some(420.0),
    height: Some(320.0),
    entry: None,          // the app's entry page
    allowlist: None,      // the app's own surface
    ..Default::default()
})?;

// The window does not exist yet: creation happens on the UI thread. The label is
// already reserved, so this is safe to send now and delivered on `on_ready`.
app.emit_to(Some(&label), "settings:open", serde_json::json!(null));

open_window returns the resolved label rather than (). Two reasons, both practical:

From the page, __voussoir_open_window answers {"label": "..."} for the same reason.

Listing and closing

app.windows();              // ["main", "settings"], in opening order
app.close_window("settings");
await window.voussoir.windows();                    // same list
await window.voussoir.invoke("__voussoir_close_window", { label: "settings" });

The list is maintained by the shell, not by the page, so it stays true when a window is closed by the OS (the title bar) rather than by your code. A page that tracks labels itself drifts the first time a user closes a window the app did not close.

Addressing one window

app.emit_to(Some("settings"), "theme", json!({ "dark": true }));
app.emit_to(None, "broadcast", json!({ "save": true }));   // every window

emit_to(None, …) is the broadcast form; emit_to(Some(label), …) reaches exactly one window. Both go through the event loop proxy, so they are safe from any thread and are queued rather than synchronous.

Per-window narrowing

A window opened for untrusted content gets a smaller surface:

let preview = app.open_window(WindowOptions {
    title: Some("Preview".to_owned()),
    allowlist: Some(vec!["greet".to_owned()]),
    ..Default::default()
})?;

See Per-window allowlists for the intersection rule and what a denial looks like.

Closing the last window

When the last window closes, the app exits. If a window must survive (a tray app, a background sync), declare it on the tray config with keep_running so the event loop does not exit on the last close.

Next

Edit this page on GitHub