Struct Launcher 

pub struct Launcher { /* private fields */ }

The windowed runner’s builder, made by app.

Every method takes and returns the launcher; Launcher::run opens the window and runs the event loop, Launcher::open opens it and hands the loop back as a PumpRunner.

Implementations

impl Launcher

pub fn chrome(self, chrome: Chrome) -> Self

Who draws the window chrome; see Chrome. The OS by default.

pub fn text_aa(self, aa: TextAa) -> Self

Glyph antialiasing; see TextAa.

pub fn frame_latency(self, frames: u32) -> Self

How many frames may be queued ahead of the one on screen, for every window. Two by default (kui_wgpu::DEFAULT_FRAME_LATENCY), which keeps every vsync fed at light load; one on Windows, where one already does. On macOS 14+ frames are paced to the display, so the second queued frame costs no latency; on Linux and under a pumped runner it reaches the screen one vsync later. KUI_FRAME_LATENCY overrides the value and KUI_FRAME_PACING=0 turns the pacing off. Values below one are one.

pub fn diagnostics(self, on: bool) -> Self

Whether the core looks for silent misconfigurations and the runner prints them to stderr (see diag). On in debug builds and off in release unless set, so a shipped app stays quiet.

pub fn devtools(self, on: bool) -> Self

Opens the app with the devtools panel docked beside it: the event stream, the runtime’s facts and the node tree. KUI_DEVTOOLS=1 in the environment asks the same of an app that never called this. Sugar for setup_core(|c| c.set_devtools(on)).

pub fn devtools_key(self, key: Accel) -> Self

Respells the chord that moves the keyboard into the devtools panel and back, and brings a hidden panel back, from its default Ctrl+Shift+I: Accel::parse("f12"), "mod+shift+d", any spelling a menu item takes. The panel’s other chords stay Ctrl+Shift+<letter>, and Ctrl+Shift+I is the app’s again. Sugar for setup_core(|c| c.set_devtools_key(key)).

pub fn setup_core(self, f: impl FnOnce(&mut Core) + 'static) -> Self

Runs f on the main window’s Core before its first frame: the place for what a core is told rather than declared in a view, such as a pinned theme, set_native_menus or the devtools. Every call adds one; they run in order.

pub fn core(self, core: Core) -> Self

Opens the main window on core rather than on one the launcher makes. Everything registered on it beforehand (fonts, images, sounds, tokens, a pinned theme, menus) reaches the window, and its session becomes the app’s, so a second window joins it and handles minted by an earlier headless frame keep drawing. The launcher’s own settings still apply on top, in order: Launcher::diagnostics, then KUI_DEVTOOLS, then every Launcher::setup_core. For a host that drew headless first, or built the core through a binding.

pub fn deferred_events(self) -> Self

Declares that the app answers an event after on_event returns, which only a host driving the loop itself can do (Launcher::open, PumpRunner): on_event keeps the event, the pump returns, the host runs its handler and submits the next view.

With it set, an input whose events reached the app does not ask for a frame itself; the host asks with PumpRunner::request_redraw once its handler has run, so a button’s release and what the release did land in one frame instead of two. Nothing else changes: a transition, a caret blink, a Waker wake or the OS’s own repaint still paint when they ask, and an input that reached nobody still asks for its own frame.

pub fn system(self, pinned: SystemEnv) -> Self

Pins part of env.system for this app’s windows. Every field of pinned that is not “cannot tell” is what the views read, over whatever the OS says, for as long as the app runs; the fields left at their default keep following the OS, and a change to one of those still arrives as the system event.

kui_native::app("mine").system(SystemEnv { motion: MotionPref::Reduced, ..Default::default() });

Use it to see the window a user who asked for less motion, or a dark appearance, would get. It is on the launcher rather than an environment variable so that a shipped app’s motion is decided in its own code; a headless core takes the same reading through core.env.system.

pub fn icon(self, rgba: Vec<u8>, width: u32, height: u32) -> Self

The icon every window of the app is created with: rgba is width by height pixels, four bytes each, row by row from the top left, alpha not premultiplied. Windows shows it in the title bar, Alt-Tab and the taskbar, X11 in the window manager’s; macOS and Wayland take the app’s icon from the bundle or the .desktop file and ignore this. Pass something a taskbar can shrink cleanly, 64 to 256 px. Panics when the pixels are not that size; Launcher::try_icon returns the reason instead.

kui_native::app("mine").icon(rgba, 64, 64);

On Windows, Launcher::icon_resource names the icon linked into the executable and wins over these pixels.

pub fn try_icon( self, rgba: Vec<u8>, width: u32, height: u32, ) -> Result<Self, String>

Launcher::icon for pixels that came from outside the program, refused with the reason rather than a panic. The launcher is consumed either way.

pub fn icon_resource(self, id: u16) -> Self

The executable’s icon resource id as every window’s icon, on Windows: the .ico a 1 ICON "app.ico" line in the program’s .rc links in, from which the title bar and the taskbar each load the frame drawn for their size. A resource the executable does not have is reported once on stderr, and Launcher::icon’s pixels are used if there are any. Nothing on other platforms, so an app passes both and each OS takes its own.

pub fn custom_titlebar(self) -> Self

Shorthand for .chrome(Chrome::Custom).

pub fn borderless(self) -> Self

Shorthand for .chrome(Chrome::Borderless).

pub fn size(self, w: f64, h: f64) -> Self

Initial inner size, logical px (KUI_WINDOW=WxH still overrides). Clamped into the min_size/max_size bounds, as the OS would.

pub fn min_size(self, w: f64, h: f64) -> Self

Smallest inner size the user may resize the window to, logical px. The OS enforces it; the initial size is clamped up into it.

pub fn max_size(self, w: f64, h: f64) -> Self

Largest inner size the user may resize the window to, logical px. A bound below the matching min_size loses to it, as on the OS side.

pub fn extension(self, ext: impl Extension + 'static) -> Self

Loads ext under its own name as its namespace. The slots it fills are declared as ui.slot("<name>/<slot>"). Panics when the name is already another extension’s namespace; two of one name need Launcher::extension_as.

pub fn extension_as( self, namespace: impl Into<String>, ext: impl Extension + 'static, ) -> Self

Loads ext under namespace, so the same extension loaded twice is two namespaces with two sets of slots and params. Panics on a namespace already taken, an empty one, or an extension whose slot names contain /.

pub fn try_extension_as( self, namespace: impl Into<String>, ext: impl Extension + 'static, ) -> Result<Self, String>

Launcher::extension_as for a caller that reports the refusal rather than panicking, such as a plugin named from outside the program. The launcher is consumed either way.

pub fn with_extensions(self, extensions: Extensions) -> Self

Takes an Extensions list already loaded, replacing any extension calls before it. For a host that built the list elsewhere, as the C binding does.

pub fn extensions(self, exts: Vec<Box<dyn Extension>>) -> Self

Launcher::extension for each, in order.

pub fn run<A: App>(self, app: A) -> Result<(), Box<dyn Error>>

Opens the main window and runs the event loop until the main window closes. Returns Ok then, or the error when the window or its renderer could not be made. One event loop per process: a process that has used Launcher::open opens again rather than calling run.

pub fn open<A: App>(self, app: A) -> Result<PumpRunner<A>, Box<dyn Error>>

Opens the window but keeps the event loop in the caller’s hands: the returned PumpRunner processes OS events only when PumpRunner::pump is called, so a foreign loop (libuv, a game loop, a test harness) can interleave with winit on the main thread. winit allows one event loop per process, but any number of runners in turn: a runner whose main window has closed parks the loop, and the next open on the thread takes it back.