This page lists every item that sigil exports at the crate root and in sigil::prelude. Each item has a signature, a one-line purpose, and an example. Every example on this page compiles as a doctest of the sigil crate.
The package is sigil-ui. The library is sigil. The API can change between 0.x releases.
use sigil::prelude::*;fn main() -> AppResult<()> { sigil::run(AppConfig::new("App").terminal(), || text("Hello"))}
use sigil::prelude::*;fn main() -> AppResult<()> { sigil::run(AppConfig::new("App").terminal(), || text("Hello"), )}
The default feature desktop gives the window host. The feature terminal gives the terminal host. A terminal-only program uses default-features = false, features = ["terminal"]. The crate README lists every Cargo feature. For task-oriented examples, see Recipes.
Crate root
Modules are public so that you can name an item by its path, for example sigil::style::Token. Prefer the prelude and the functions in this table.
Name
Signature
Purpose
geometry
mod geometry
Points, rectangles, and sizes in logical and physical pixels, and the device scale factor.
prelude
mod prelude
The application import surface.
a11y
mod a11y
Accessibility tree construction.
animation
mod animation
Easing, springs, and keyframes.
animation_runtime
mod animation_runtime
Animators that drive signals each frame; clock() -> Signal<f64> is a signal of seconds that advances by the real frame time on every painted frame while its owner lives, and running_clocks() counts live clocks. A clock keeps the host painting but does not count in active_count(), so settling ignores it. Reduced motion does not stop a clock; check MotionPrefs::reduced() to hold motion still.
app
mod app
Application host, configuration, and theme files.
bidi
mod bidi
Bidirectional text: paragraph levels, visual order, and ParagraphBidi::visual_step for caret motion. text::bidi re-exports it.
clipboard
mod clipboard
Clipboard trait and the installed clipboard.
events
mod events
Event routing, handlers, and focus.
hal
mod hal
Input events, keys, and geometry types.
icons
mod icons
Bundled icon glyphs (feature scene).
kernel
mod kernel
Node tree, builders, and roles.
layout
mod layout
Layout styles and the layout engine.
profile
mod profile
Frame timing counters.
reactive
mod reactive
Signals, effects, owners, and intervals.
renderer
mod renderer
The GPU and CPU renderers (feature scene).
scene
mod scene
The CommandScene display list.
shell
mod shell
The window shell (feature desktop).
style
mod style
Paint, themes, tokens, and metrics.
tasks
mod tasks
Async tasks and cross-thread dispatch.
terminal
mod terminal
The terminal host (feature terminal). On Unix, SIGTERM, SIGHUP, and SIGINT restore the terminal and return from sigil::run; the application owns process cleanup and exit status.
text
mod text
Fonts and text shaping (feature scene).
widgets
mod widgets
Widget builders.
wgpu
extern crate wgpu
The wgpu version that the renderer uses (feature scene).
Builder of a file dialog. Each pick returns a Picked signal that turns from Pending to Ok(None) on cancel or Ok(Some(path)). The in-app picker returns one path from open_files().
dialog::Picked
type Picked<T> = Signal<Status<Option<T>, Infallible>>
Run configuration: title, size, host, theme file, web canvas. A title converts to a config with the defaults; AppConfig::new(title) starts the builder. window() selects the window host and terminal() the terminal host. Without a call, the host is the window when feature desktop is on, else the terminal. A host method exists only with its feature, so a build without that host does not compile the call. canvas names the web canvas element. user_zoom scales the UI; the default is 1.0. frameless(true) removes the window frame. overlay(true) opens a transparent accessory window; anchor places it on the screen. theme_file loads the theme from a file and reloads it when the file changes. quit_on_ctrl_c is true by default. frame_interval sets the wait between terminal host frames; the default is 1/60 s (60 Hz).
AppResult
type AppResult<T> = Result<T, Error>
Result of the application functions.
Error
struct Error
Opaque application error.
Host
struct Host
Embed host: build, route, lay out, and paint one tree. set_caps(HostCaps) tells widgets what the host can show.
Emit the next scene from the frame's FrameDelta and the scene this host emitted last, copying the commands of every subtree that did not change. prev must be the scene returned by the previous emit_since on this host, or the previous one when nothing changed since. reset_emit forgets the copies, so the next call emits every node; call it when prev was replaced or dropped.
use sigil::prelude::*; imports every item in this section.
Application
Name
Signature
Purpose
Host::mount_hot
fn mount_hot<N: IntoNode>(&mut self, root: impl Fn() -> N + 'static) (feature hot, not wasm)
Mount root through the subsecond jump table and connect to the dx devserver once. After each patch the next Host::frame calls root again, keeps the theme, and restores focus to the node with the same role and name path. sigil::run does this for its root.
The nodes whose paint or layout changed since the last take_delta, and whether nodes were added, removed, or reordered. Host::frame takes it once per frame and passes it in FrameInfo::delta; an embedder that drives its own loop takes it after layout and before Host::emit_since.
A handle an effect keeps to report that its node changed outside a rebuild. record adds the node to the next FrameDelta; use DeltaKind::Layout when the change can move or resize it.
Builder that container and most widgets return. NodeBuilder::from(text(..)) or .into() puts any widget builder into a Vec<NodeBuilder>; the result is the widget's own node, so .layout(), .class(), and accessibility settings called on it apply to the widget. children_reactive builds the children again each time a signal that the closure reads changes. children_keyed reconciles the children by key, like for_each. with attaches a typed value to the node (NodeExtensions). hittable(false) lets pointer events pass through the node. The accessibility methods set what screen readers get for the node.
fn show<A: IntoNode, B: IntoNode>(cond: impl Reactive<bool>, then: impl Fn() -> A, otherwise: impl Fn() -> B) -> NodeBuilder
Mounts then() while cond is true and otherwise() while it is false. cond is a Signal<bool> or a closure. The mounted branch keeps its node until cond flips.
One child per item, reconciled by key. A row whose key stays keeps its node and state; new keys mount, missing keys unmount, and the order follows items. render runs for every item on each change, and only the rows of new keys mount. A row reads signals to update in place. A row helper fn row(item: &T) -> impl IntoNode captures the borrow under edition 2024; return a concrete builder such as NodeBuilder, or write -> impl IntoNode + use<>.
Mounts the view of the case whose key equals key, or otherwise when no case matches. Without keep_alive, only the active case is mounted and the others unmount. With keep_alive(true), a case mounts the first time it is active, and after that it is hidden while inactive, so it keeps its state. show is the two-way form.
Shows one view for each Status variant. A view that is not set shows nothing. Panicked(msg) goes to the error view as E::from("task panicked: {msg}"). Each status change mounts the view again.
The one text node. source is a &str or String (static), a Signal<T: Display> (live), or a closure Fn() -> String (recomputed when the signals it reads change). .nowrap() keeps it on one line.
Layout description of a node. fill_width, fill_height, and fill take the full size of the parent on that axis. grow also sets an auto minimum size to 0, so the node can shrink below its content. pane(w, h) is flex_column().fixed_size(w, h).gap(4.0). grid_area sets the start column and row.
Override the layout of a widget builder or an image. layout sets only the fields its LayoutStyle sets; the widget keeps the rest. map_node queues a change to the root NodeBuilder of the widget, for example .map_node(|n| n.on_added(f)). The widget applies queued changes once, after its own build.
A row or column is as wide as its content. When a child fills, with a Fill width or a grow factor in a row, the container takes the width that its parent offers, and a row shares that width among its children. A text_field fills, so a row with a field and a button keeps the button on screen.
See Units for the rules that map rows, cols, and em to pixels and cells.
Reactive value. set skips a value equal to the current one; update always notifies. Two handles are equal when they name the same signal, so a store of signals can itself live in a signal.
A value source: a Signal<T>, a closure Fn() -> T, or a plain value (bool, String, &'static str as Reactive<String>, Vec<T> or [T; N] as Reactive<Vec<T>>). Show/hide, invalid_when, and the content widgets diff, mermaid, and sparkline take one. disabled on every widget takes one, so .disabled(move || name.get().is_empty()) needs no derived.
A task whose runs take an argument: run_with(arg) calls make(arg), so one task serves many targets, such as staging one path.
Task
struct Task<T, E, A = ()> (Copy); run() when A is (), run_with(arg: A), cancel(), status() -> Status<T, E>
run sets Pending, aborts the previous run, and starts a new one; a result from a replaced run is dropped. cancel aborts the run in flight and sets Pending back to Idle; a finished status stays, and a result that arrives after cancel is dropped. status reads and subscribes; it needs T: Clone and E: Clone. The owner's cleanup aborts a pending run.
Start a future now, off the UI thread, and write its result to the signal. Runs once and cannot be cancelled; the owner's cleanup aborts it. For work that reruns or cancels, use task. For a future that owns state it cannot rebuild, such as a channel receiver.
tasks::sleep
async fn sleep(duration: Duration)
Wait inside a spawned future without blocking a thread. Uses the tokio timer on native and setTimeout on the web.
tasks::blocking
async fn blocking<T: Send + 'static, F: FnOnce() -> T + Send + 'static>(f: F) -> T
Run blocking work, such as a subprocess or a file read, inside a task or spawn future without stalling a runtime worker. Native: runs f on the tokio blocking pool. Web: runs f inline. A panic in f makes the task Panicked. Cancelling the task drops the result; f still runs to the end.
tasks::TaskWorkers
#[non_exhaustive] enum TaskWorkers { Auto, Fixed(NonZeroUsize) }; default Auto
Worker threads of the native task runtime. Auto uses one per CPU.
Like AsyncRuntime::new, with a worker count. The native runtime starts on the first spawn, so an app that never spawns owns no worker threads.
tasks::TaskHandle
abort(), is_finished() -> bool
A task from Scheduler::spawn on AsyncRuntime. The owner's cleanup aborts it. Native tasks run on tokio; web tasks run on wasm_bindgen_futures::spawn_local.
Attach event handlers to a NodeBuilder or to any widget builder that implements WidgetLayoutExt. On a widget builder the handler goes on the root node of the widget, after the handlers of the widget. autofocus() gives the node keyboard focus when it mounts, and again each time a focus scope that holds it, such as a modal, opens; focus_when(trigger) focuses it each time the signal changes, with no NodeId plumbing. link(f) receives the URL when a link inside the node, such as one in markdown, is clicked; the deepest handler on the path gets it. on_selection_copy(f) receives the text and the clipboard result each time a selectable_text region inside the node copies a selection.
A key plus modifiers. parse reads the names label() prints, in either form (⇧⌘K or Shift+Super+K), plus cmd, ctrl, alt, option; an unknown name is a ShortcutParseError. label() prints it for the running platform: ⇧⌘K on macOS, Shift+Super+K elsewhere; label_for picks the style explicitly. primary uses events::PRIMARY: Command on macOS, Control elsewhere, for example Shortcut::primary(LogicalKey::character("s")) for Cmd+S or Ctrl+S.
events::PRIMARY
const PRIMARY: ModifiersState
The platform's primary shortcut modifier: Command (META) on macOS, Control elsewhere, including wasm32.
Key
keyboard_types::NamedKey
A named key such as Key::Enter.
LogicalKey
LogicalKey::named(key), LogicalKey::character(s)
A named key or a character.
ModifiersState
keyboard_types::Modifiers
Modifier flags such as CONTROL.
KeyEvent
struct KeyEvent { key, physical, modifiers, repeat, phase, text }
A key press or release.
KeyPhase
enum KeyPhase { Down, Up }
Press or release.
PointerEvent
struct PointerEvent
A pointer event. capture_pointer() sends the following moves and the release to the node that asked, and only to it: they do not bubble to its ancestors. position is relative to the handler's node; window_position is in window coordinates. pointer_id tells touch contacts apart (0 for the mouse); pressure and tilt are Some for touch and pen input that reports them.
Theme, tone, focus ring, presence, and animation of a NodeBuilder. visible_when keeps the node mounted and hides it while the source is false; show mounts and unmounts instead. paint_when applies the paint from its closure while the source is true. presence animates the node in and out.
Theme values. The direction, locale, and strings apply to the whole tree: a right-to-left theme mirrors padding, margins, insets, flex row order, and start/end alignment; number_field and date_field parse and format with the locale; built-in labels such as Close and Cancel come from the strings.
style::Direction
enum Direction { Ltr, Rtl }; is_rtl(), `Direction::from_name("ltr"
"rtl")`
Layout direction. .with(Direction::Ltr) on a node keeps it and its children left to right in a right-to-left theme, as code_edit does.
Number and date rules as data. Locale::default() is . decimals, no grouping, and year-month-day with -.
style::Strings, style::StringKey
struct Strings; Strings::english(), from_table(&[(StringKey, &str)]), with(key, value), set, get(key), fill(key, args); enum StringKey, StringKey::from_name (snake_case, for example "close")
The built-in labels a theme carries, with English defaults. fill replaces {0}, {1} placeholders.
Theme::resolve_color
fn resolve_color(&self, key: ColorKey) -> Rgba8
Resolve a color key. Order: runtime override, theme table, built-in value. An unknown Custom name panics in debug builds and paints missing_token_fallback with one tracing warning per name in release builds.
Focus ring settings. theme_color sets the ring color from a theme token.
Paint calls write to one store per node. A later call wins for each property that it sets, whether it is a Paint method, a state variant, or .layout. A background, border, or size that you set on a widget holds in every state, over the widget's own defaults. To keep a widget's hover and press feedback in another color, set .tone(..) instead of a color. On a widget builder, the Paint methods win over width, height, grow, and layout for the same property.
A single-line text input. leading and trailing place a node, such as an icon, inside the field border; the input fills the rest. clearable shows a clear button while the value is not empty; it empties the value, fires change, and puts focus back on the input.
A multi-line text editor. autofocus focuses it when it mounts; focus_when focuses it each time the signal changes. caret_rect receives the caret rectangle, relative to the editor's box, each time the caret moves, and None while the editor is disabled, so a popup can follow the caret.
A numeric input. Text that parses updates value as you type; on Enter or blur, text that does not parse is replaced by the stored value, so the field never shows a number it did not store.
fn field<C: IntoNode>(label, control: C) -> FieldBuilder<C>; .error(impl Reactive<Option<String>>) when C: FieldControl; .required(impl Reactive<bool>)
A label above a control. .required marks the control required for screen readers and shows a marker after the label while it is true. .error shows the message under the control and paints the control invalid while it is Some. The control is marked invalid while an error shows and is described by the message.
One menu entry. activate runs when the entry is pressed.
menu_bar
fn menu_bar() -> MenuBarBuilder; .fill()
An in-window menu bar, as wide as its menus. fill makes it take the full width.
command_menu
fn command_menu() -> CommandMenuBuilder
A command palette. Typing in its query field filters and ranks items with fuzzy_score; Up and Down move, Enter or a click runs an item or opens a submenu, and Escape goes back one level.
Rows, columns, sort, and selection. identified keeps the selection on the same row ids across replace_rows. reset_columns restores the original column order and shows every column. row_eq tells the table when a replaced row is unchanged, so its cells are not rebuilt; without it every replace rebuilds the mounted rows. toggle_sort steps a sortable column through ascending, descending, and no sort; set sort_key to sort directly. cycle_sort moves the sort to the next sortable column in column order, ascending, wrapping to the first; with no sort it picks the first sortable column. When the sort or quick_filter hides a selected row, the row leaves the selection, so selected_row only returns a visible row. reverse_sort flips the direction of the current sort and does nothing without one. select_by moves the selection delta rows in visible order from the last selected row, clamped to the visible rows, and selects only that row; with no selected row, a negative delta selects the last visible row and any other the first. Text in quick_filter keeps the rows that a filterable column matches. visible holds the row indexes after filter and sort. Row numbers in the selection methods are indexes into rows. select_range_to selects from the last selected row to row in visible order. pin_column_width clamps to MIN_COL_WIDTH.
One table column. sort_by and sortable make the header sort the rows; filterable makes the column match the text in TableState::quick_filter; cell renders the cell, else the table shows nothing for it. numeric right-aligns the column and uses tabular digits.
ColWidth
enum ColWidth { Fixed(f32), Fraction(f32) }
Column width.
Density
enum Density { Grid, Compact, Default }
Row density of a table.
Identifiable
trait Identifiable { type Id; fn id(&self) -> Self::Id; }
Stable row identity.
virtual_list
fn virtual_list<T, R: Fn(usize, &T) -> N, N: IntoNode, I: IntoList<T, R>>(items: I, render: R) -> VirtualListBuilder<T, R>
A list that builds only the visible rows. render returns any IntoNode, such as text(..) or a widget builder.
SelectionMode
enum SelectionMode { None, Single, Multi, Extend }
Optional parts of a list row. title_width gives the title a fixed width so columns line up after it. leading places a node, such as an icon, before the title. marker_tone and status_tone color the marker and status text per row. badge: Option<(TextContent, Tone)> draws a count pill after the status. indent sets the columns per depth level (default 2).
Tabs. Each tab adds a label and its content component; the component builds once, so a tab keeps its state while another is shown. When tabs have content, the active tab's content fills the space left below the tab strip.
Syntax marks per line for rust, sh, toml, json, python, javascript, typescript, go, c/cpp, yaml, css, html, sql, markdown, and diff. Other languages get no marks. language_for_path(path) names the language of a file path; text_runs(marks, range) turns marks into TextRuns for a range of a line.
A rendered unified diff of text or a parsed Patch. A signal or closure source renders the rows again when it changes. Rows render through virtual_list, so a long patch builds only the visible rows. Code is colored by the language of the file path. With select, a click on a hunk header selects the hunk and a click or Shift+click selects changed lines, for staging.
A bordered card. selected gives it the accent border and background; activate handles click, Enter, and Space and makes the card a focusable button. Converts into NodeBuilder.
A tree view for explorers, outlines, and settings. Only rows under expanded nodes are built, and they are virtualized. Click toggles a folder and activates a leaf; arrows move, Left and Right collapse and expand, Home and End jump, Enter activates.
sheet
fn sheet(show: Signal<bool>) -> ModalBuilder
A panel that slides in from a side.
modal
fn modal(show: Signal<bool>) -> ModalBuilder
A modal dialog. While it is open and traps focus, it is marked modal and the rest of the page is hidden from assistive technology.
Builder of a modal or sheet. A titled dialog shows a close button that sets show to false; close_button(false) removes it. Children scroll in a body between the title and the footer, so the title and actions stay visible when the dialog reaches its maximum height. footer adds one node to the footer; actions(cancel, confirm) adds two. Escape closes the dialog by default. A click on the backdrop closes a sheet but not a modal, unless dismiss_on_backdrop changes it. trap(false) lets focus leave the dialog.
A bar, line, or candle chart. A line with more points than the plot has pixel columns keeps the low and high point of each column, so 100k points draw as one short path. candles takes (open, high, low, close) rows. x_range binds the visible range in point units: the wheel zooms around the pointer and a drag pans. crosshair draws rules and the value under the pointer. A signal or closure source draws the chart again when it changes, like sparkline. The chart fills its parent's width unless .width() is set; at small heights it thins x-axis labels and hides the axis row before the plot gets too small.
Custom drawing: the closure records scene commands for the node's rect when the node paints, clipped to that rect. It runs again on resize and each time the redraw_on signal changes. The terminal host paints the same commands to cells; a fill that covers part of a cell paints as a half or eighth block.
Builder of a vector path. fill_linear and fill_radial fill with a gradient. The host rasterizes the path at the laid-out size times the device scale. non_scaling_stroke keeps the stroke width in logical px under any fit, with round joins and caps.
Terminal host. Turn on xterm modifyOtherKeys level 2 when the terminal lacks the kitty keyboard protocol, so Shift+Enter and Ctrl+letter arrive as their own keys. Off by default; reset on exit, suspend, and panic. Needs a crossterm that decodes CSI 27 ; mod ; code ~.
Screen-reader options for the terminal host. The window host ignores them.
terminal::Access
struct Access { focus_cursor: FocusCursor, status: Duration }; Default is Follow and 5 s
Where the terminal cursor goes when no caret shows, and how long an announcement stays on the full-screen status row. Screen::set_access(access) applies it to a Screen.
terminal::FocusCursor
enum FocusCursor { Follow, Off }
Follow moves the hidden terminal cursor to the focused node's label when no text caret is visible, so screen readers read it. Off leaves it where it is. The cursor shows only at a text caret.
Mouse reports the terminal host asks for at start. Without it, the host keeps the last set_mouse_tracking value, Drags by default. The window host ignores it.
Terminal mouse reports, all in SGR form (1006). Clicks sends presses, releases, and the wheel (1000). Drags adds motion while a button is held (1002). Motion adds motion with no button held (1003), for hover. Every change and the exit first reset all four modes.
AppConfig::resizable
const fn resizable(self, yes: bool) -> Self
Let the user resize the window (feature desktop). false fixes the window at its configured size.
AppConfig::esc_exits
const fn esc_exits(self, yes: bool) -> Self
Exit the app on Escape. exits_on_esc(&self) -> bool reads the setting.
The key that suspends the terminal host (job control); the default is Ctrl+Z. The host restores the terminal and stops; fg resumes it and redraws the screen. None turns it off and delivers the key to the app. Unix only; the window host ignores it.
kernel::Cx::flush_announcements
fn flush_announcements(&mut self)
Move the text that kernel::announce queued into the live region. Host::frame calls it every frame.
kernel::announce
fn announce(text: impl Into<String>)
Queue a polite screen-reader announcement; the next frame posts it to the live region.
kernel::announce_assertive
fn announce_assertive(text: impl Into<String>)
Queue an assertive announcement that interrupts the screen reader.
kernel::Cx::dump_tree
fn dump_tree(&self, root: NodeId) -> String
Indented text of the node tree below root, for debugging.
kernel::Cx::describe
fn describe(&self, id: NodeId) -> String
A short label for one node: its role, then its accessible name, its text, or the nearest named ancestor. Profiler attributions use it.
reactive::debug::dump_owner_tree
fn dump_owner_tree() -> String
Indented text of every reactive owner with its name and source location, for debugging leaks.
Native menu accelerator for a Shortcut, so one key definition drives both the key binding and the menu hint. NativeMenuItem::with_id(id, label, enabled, accelerator) takes muda's code-based Accelerator, not this type: build the item with None, then call item.set_key_accelerator(accelerator(&shortcut)). Returns None for named keys other than Enter, Tab, Escape, Backspace, Delete, Insert, Home, End, PageUp, PageDown, the arrow keys, and F1–F12 (feature menu).
app::tray::set_tray
fn set_tray(builder: tray_icon::TrayIconBuilder)
Install a system tray icon. The window host builds it on the next frame (feature tray).
File picker (feature dialog). The result signal starts Pending and resolves without blocking the frame loop. The in-app picker runs on every host; native-dialog opens the OS dialog on the window host.
The text engine of a host. App code reaches the shared engine only through OwnedTextEngine::thread(), an Rc, so it cannot call register_font; use app::set_default_fonts to replace a face or text::add_fallback_font to add one.
layout::Dimension
enum Dimension
A length: px, percent, text length, or auto.
layout::LengthPercentage
enum LengthPercentage
A px or percent length.
style::Dimension
enum Dimension { Px(Px), Full, Fraction(u16), Auto }
Native menu types; an app needs no direct muda dependency. NativeMenuItem is muda's MenuItem, renamed to stay distinct from widgets::MenuItem. Build the menu passed to app::menu::set_menu_bar; clicks arrive as MenuId on app::menu::events.
Callbacks that an embedding host passes to Host::frame to feed input, act after layout, and paint. The input hook returns the viewport when input changed it (a resize), and the frame lays out at that size; None keeps the viewport passed to frame.
app::EngineGeometry
struct EngineGeometry; fn new() -> Self
TextGeometry implementation backed by the thread text engine. It gives hit tests and caret positions for text nodes.
app::DefaultTextMeasure
struct DefaultTextMeasure; fn new() -> Self
TextMeasure implementation backed by the thread text engine. Layout uses it to size text nodes.
app::is_grid
fn is_grid() -> bool
true on a cell grid (terminal) host.
app::viewport_size
fn viewport_size() -> Signal<LogicalSize>
The viewport size in logical px. A terminal cell is Host::CELL px.
app::display_scale
fn display_scale() -> Signal<f32>
Physical pixels per logical px of the window, user zoom included. It is 1.0 outside a host. Size raster work such as image decodes with it.
Open a file or URL with the OS handler (feature desktop).
app::dialog
mod dialog
File and message dialogs. No call blocks the frame loop. Feature dialog gives the API and an in-app modal that works on every host and needs no desktop dependencies. Feature native-dialog adds the OS dialog on the window host, run on the task runtime; the terminal host, or a Linux session without DISPLAY or WAYLAND_DISPLAY, still uses the in-app modal. The in-app modal shows the directory path, a list with .. and folders first, the extension filter applied, a name field in save mode, and Cancel and Open buttons. Arrows move, Enter opens a folder or picks a file, Backspace goes up, and Escape cancels. The caller code is the same on both hosts.
Now-playing information and media keys through the OS media controls: MPNowPlayingInfoCenter, SMTC, MPRIS, by the playwire crate (feature media). Shuffle and repeat changes from the OS arrive as MediaKey::SetShuffle and MediaKey::SetRepeat.
Audio player (feature audio). It keeps one output device for its life, so append and queue play tracks back to back with no gap. Setting volume changes the output level.
Open another window with its own tree on the same event loop. Events go to the window they come from. The app exits when its last window closes. Feature desktop.
Runs once on the UI thread when the window event loop exits: after the last window closes, on a macOS quit (Quit menu, Dock Quit, logout), and on a Windows session end (sign-out, shutdown, restart, or a Restart Manager close). A system quit or session end may not return from run, so work that must finish before the process ends goes here. On Windows the shell registers the StringKey::SavingOnExit text as the shutdown block reason while the hook runs, then ends the event loop.
app::ResizeDirection
enum ResizeDirection
Edge or corner for WindowCommand::DragResize. Feature desktop.
app::WindowOpts
struct WindowOpts
Window options that AppConfig collects. Feature desktop.
app::Anchor
enum Anchor { BottomCenter { margin: f32 } }
Screen anchor of an overlay window. Feature desktop.
app::DefaultFonts
struct DefaultFonts
Font bytes for the sans, mono, icon, and display faces.
app::set_default_fonts
fn set_default_fonts(fonts: DefaultFonts)
Replace the bundled fonts.
app::use_system_fonts
fn use_system_fonts()
Use the operating system fonts.
app::TextTuning
struct TextTuning
Text rasterization settings.
app::text_tuning
fn text_tuning() -> TextTuning
Read the text rasterization settings.
app::set_text_tuning
fn set_text_tuning(tuning: TextTuning)
Set the text rasterization settings.
Module `bidi`
Name
Signature
Purpose
bidi::visual_order
fn visual_order(levels: &[u8]) -> Vec<usize>
Returns the visual order of runs from their bidi embedding levels.
bidi::Step
enum Step { To(usize), Edge, Logical }
Result of a visual caret move: a new byte offset, the line edge, or a fall back to logical movement.
Module `clipboard`
Name
Signature
Purpose
clipboard::NoopClipboard
struct NoopClipboard;
Clipboard implementation used when no clipboard is installed. set returns an error.
A file drag over or onto the window. The host reports no drop point, so the event goes to the deepest file_drop handler under the last known pointer position, else on the focused node's path; with neither, every handler sees it.
Pasted text routed to the focused node, then to each ancestor until a handler stops it. NodeEventsExt::on_paste(f) receives it. Text fields insert it as one edit, the same as a clipboard paste.
events::PointerEventInit
struct PointerEventInit
Fields to build a PointerEvent. PointerEvent::with_contact(pointer_id, pressure, tilt) sets the contact data.
Queues a keyed reconcile of the children of parent. Children with a known key keep their node; new keys mount and missing keys unmount. Pass None for a key that is already mounted to keep it without building a node.
kernel::FocusScopeKind
enum FocusScopeKind { Modal, Popup, Inert }
Kind of focus scope on a node: a modal traps focus, a popup closes on focus loss, and inert content takes no focus.
Builder of a text node. wrap breaks lines at the width; ellipsize keeps one line and ends cut text with an ellipsis. runs styles ranges of the text. label replaces the text that screen readers read.
kernel::ImageBuilder
alt, fit, crop, mutate, plus WidgetLayoutExt
The one image builder. image, image_rgba, and image_bytes return it.
kernel::ImageCrop
struct ImageCrop { top: u32, height: u32 }
Vertical crop of an image: rows top..top + height, clamped to the image. A crop with no rows inside the image draws nothing. The fit applies to the cropped rows.
The layout pass. Host owns one. take_republished reports whether the last pass changed a size or bounds binding, and resets the flag. Host runs up to four passes per frame until no binding changes.
Lint a laid-out tree. Columns: in a block or non-wrapping flex column, each run of consecutive non-wrapping flex rows of one shape (the same row style and the same kinds of cells) must agree, cell by cell, on start, end, or center x within tolerance.exact; a header or footer of another shape splits the runs. Insets: a container that is its parent's only child, inset on both sides of an axis, is reported when the two insets differ by more than exact and at most near_miss. Text is not checked for insets. A node marked asymmetric(reason) is skipped by both rules.
Limits in layout points. cells() is exact 0 and near miss 3 cells (3 * Host::CELL); points() is exact 0.5 and near miss 4. for_mode picks one for the host mode.
One finding. Display reads like column 1 of <Container role=GenericContainer #4> in rows at y [0.0, 2.0, 4.0] starts at [44.0, 52.0, 58.0] ...; an inset names the node's position and size.
layout::align::NodeLabel
struct NodeLabel { id: NodeId, label: String }
The node a finding names, labelled the way Cx::dump_tree labels it, plus its id.
Names one timed stage of a frame. category() returns its Category. Gpu is GPU execution time from timestamp queries; GpuWait is time a headless host blocks on the GPU. The Render* phases split renderer CPU time into the damage plan, command encoding, the retained scene copy, and the queue submit.
Add n to subject under hotspot in the current frame. subject runs only while profiling is on. Past MAX_SUBJECTS distinct subjects per hotspot, new ones count under OTHER_SUBJECT.
profile::gpu_pass
fn gpu_pass(label: &'static str, ns: u64)
Add GPU execution time for one render pass to the current frame and to Phase::Gpu. The renderer calls it from timestamp queries.
Add one or n to a counter, or set it to a value, in the current frame.
profile::interact
fn interact(cause: Cause)
Marks the next frame as caused by cause so the report can measure input latency.
profile::note_input
fn note_input(event: &ShellEvent)
Marks the current frame with the cause that matches an input event: pointer press, hover, key, scroll, IME, or resize. Hosts and the test harness call it for each routed event. The summary breaks each cause down by phase.
The GPU renderer. It draws a CommandScene to a window surface or an offscreen texture and rebuilds the device after device loss.
renderer::WgpuRenderer::drain_gpu_timings
fn drain_gpu_timings(&mut self)
Report finished GPU timestamp results to the profiler. A headless caller calls it after a blocking device.poll to get GPU pass times in the same frame.
The pattern both renderers paint: period and cell clamped to 1..=1024 logical pixels (NaN becomes 1), line_width clamped to 0..=period (NaN becomes 0). Tiles are anchored at the top-left corner of the drawn rect, in logical pixels, independent of device scale. Colors are straight sRGB and each cell keeps its own alpha. tile_extent is one repeat: period for a slash, 2 * cell for a checker.
scene::LinearGradient::normalized
fn normalized(&self) -> LinearGradient
The gradient both renderers paint: stops sorted by offset, offsets clamped to 0..=1 with the color at each clamp point kept, and a zero-length line or no stops reduced to one solid stop (the last stop's color, or transparent).
An image command fitted into a destination rectangle, with optional crop. With a raster and no crop, both renderers draw pixels made at the physical destination size, snapped to the device pixel grid; source is the fallback.
The image and destination to paint at scale. With a raster and no crop, the pixels are made at the device size (each side at most 4096) and the rectangle snaps to the device pixel grid; otherwise source and destination. Embedders that paint DrawImage call this.
Resolved decoration shape that both renderers draw, in the band's local space before the transform. Ink stays inside the band: straight lines clamp line_width to the band height; wavy lines use a stroke of 0.8 x line_width and an amplitude of 0.75 x line_width, both shrunk to fit the band, with the period raised to at least 4 x (amplitude + stroke) and 1. The wave is a sine that starts at the band centre at the band's left edge. Returns None for a non-finite or empty band and for a non-finite, zero or negative line_width.
An outline on a rectangle, gradient, or pattern, with dash and alignment. A width that is not finite and positive draws nothing. Inside and Centered strokes reach at most half the shorter side inward. Dashed(gap) draws dashes of max(3 * width, 1) separated by gap; a gap below 1/16 or not finite draws a solid stroke.
Per-corner radii in the order top-left, top-right, bottom-right, bottom-left. normalized_for clamps negative and NaN radii to 0 and scales them down proportionally, as CSS does, so adjacent radii fit each side. Both renderers use it.
Describe a linear background gradient: its direction and its color stops. owned takes stops built at run time; equal stop lists share one copy for the life of the process.
Send handle of a reactive owner. run calls f inside the owner, so signals and effects it creates belong there, and returns false without calling f once the owner is disposed.
Terminal capabilities. detect reads environment variables; probe also queries the terminal. When the environment leaves the color depth below truecolor, probe asks the terminal (DECRQSS) and trusts a kitty keyboard reply. When the environment names no terminal, as behind ssh or a multiplexer, probe asks for its version (XTVERSION); any answer turns hyperlinks on and a known name sets notices. Inside tmux or screen, only TERM, COLORTERM, and the probe identify the terminal; variables inherited from the outer terminal are ignored. detect picks the key protocol from the terminal name; probe asks the current terminal for the kitty keyboard protocol (CSI ? u) and uses Legacy when it does not answer, whatever the name. probe skips its other queries while typed input is waiting. When raw mode cannot be entered, probe returns the environment result and sends no queries. erase is Erase::Default for TERM=screen*, which does not erase with the current background. SIGIL_COLOR=truecolor|256|16|none forces the color depth; SIGIL_ASCII=1 forces Glyphs::Ascii; SIGIL_AMBIGUOUS_WIDE=1 sets Ambiguous::Wide.
terminal::caps
fn caps() -> Option<Caps>
The capabilities the terminal host probed when it entered raw mode, for the current thread. None before the terminal host starts, after it exits, and in a window. Read Caps::backdrop here to pick a light or dark theme; Caps::probe called before sigil::run switches the terminal to raw mode for its queries and back, so replies are read, not echoed.
terminal::Erase
enum Erase { Background, Default }
How clearing to the end of a line fills the cleared cells. Default (GNU screen) makes the writer send spaces for tinted row tails.
Capability fields of Caps: color depth, key protocol, clipboard route, border glyph set, and caret shape.
terminal::Fills
enum Fills { Partial, Whole }; Caps::fills
How the terminal host fills a rectangle that covers part of a cell. Partial draws the edge with half and eighth block glyphs; Whole fills whole cells only. Caps::detect picks Whole for Terminal.app, by name or by __CFBundleIdentifier=com.apple.Terminal behind a multiplexer, because it draws block glyphs from the font with gaps between cells. Over ssh neither variable reaches the remote side, so set SIGIL_FILLS=whole there; SIGIL_FILLS=whole|partial overrides the detection anywhere.
Terminal background brightness. Caps::detect reads it from COLORFGBG; None means unknown. With no theme file set, the terminal host uses the dark theme on Dark.
Glyph set of the terminal and its one glyph map. Ascii for a non-UTF-8 locale, TERM=dumb, or TERM=vt100; Console for TERM=linux, which keeps box drawing and full and shade blocks and maps eighth blocks and braille to the nearest supported glyph; Unicode otherwise. The terminal host maps every painted cell through it. glyphs() reads the process environment, so apps pick glyphs through the same map.
terminal::install_clipboard
fn install_clipboard(caps: Caps)
Install the process clipboard for the terminal host, routed by caps.clipboard.
Send a desktop notification, or set the tab progress (Some(0..=100)) and clear it (None). Each writes only what Caps::notices says the terminal supports, and nothing when no terminal host is live.
Set the cell width rule from how the terminal renders wide glyphs: full-screen mode measures them in the startup exchange, inline mode measures them on the cursor's row. Returns TimedOut without asking again when the terminal answered nothing at startup.
The faces the web host fetches the first time text uses a script. Call before sigil::run; an empty list fetches nothing. Native targets ignore the list.
Builder of a tree. indent sets the columns per nesting level. Without expanded the tree keeps its own expansion; selected follows the keyboard cursor; without activate, Enter toggles folders. Takes the WidgetLayoutExt overrides and fills its viewport by default.
widgets::TreeKey
trait TreeKey: Clone + Eq + Hash + 'static
The key type of tree nodes; implemented for every such type.
What icon accepts: a bundled Icon or any text glyph.
widgets::layout_ext::LayoutOverrides
struct LayoutOverrides; const fn new() -> Self
Width, height, grow, padding, and full-style overrides that a widget builder applies to its root layout, plus the node hooks that WidgetLayoutExt::map_node queues.
Builder of a button. Tone and fill are independent, so call order does not matter. primary(), neutral(), and destructive() set only the tone (Primary, Neutral, Error), as does tone(Tone). solid(), soft(), ghost(), and outline() set only the fill: solid() is a filled background, soft() a framed tinted fill, ghost() no fill and no frame, outline() a framed ghost. With no fill set, the Primary and Error tones draw solid() and every other tone draws soft(). With no tone set, the tone is Neutral. icon_svg puts an SVG icon before the label (feature scene). A button below the default size, or with a height of 32 px or less, uses the text-xs label. pending disables the button and shows a spinner before the label while the signal is true. accessible sets the name that screen readers read. Width and height come from WidgetLayoutExt.
Builder of a switch. accessible names the switch for assistive tech without visible text. The off track is gray-6 with a gray-11 thumb; a disabled off track is gray-4.
widgets::SegmentedBuilder
struct SegmentedBuilder; label(name)
Builder of a segmented control. The default height is 32 px; set it with WidgetLayoutExt::height.
widgets::SidebarBuilder
struct SidebarBuilder; resizable(min: f32, max: f32), plus Paint and WidgetLayoutExt
Builder of a sidebar. Paint methods paint the whole column. resizable adds a drag handle on the inner edge; Left and Right resize it when the handle has focus, and Home and End jump to the limits.
Builder of a slider. marks draws one label per stop under a horizontal track, spaced evenly from the minimum to the maximum; the current stop is highlighted and a click on a label moves to it. glass() draws a translucent gradient track.
Builder of a text input. autofocus() focuses the field when it mounts. focus_when focuses it each time the signal changes after mount. submit runs with the value on Enter. blur runs when the field loses focus. password() masks the text; reveal shows it while the signal is true. caret_visible and scroll_offset return the signals of the caret blink and the horizontal scroll.
Builder of a text editor. Its default height is 160 px in a window and 5 rows in a terminal; set another with .height(..), such as .height(rows(3.0)). Enter inserts a new line and submit runs with the value on Ctrl+Enter; submit_on(SubmitKey::Enter) swaps them, so Enter submits and Shift+Enter inserts a new line, as a chat composer does. The placeholder shows whenever the value is empty, focused or not. state takes the value, caret, and undo state from a TextEditState. chrome(false) draws the editor without its frame and background.
widgets::TextEditState
TextEditState::new(value, caret: Signal<usize>)
Caret and undo state of a text editor.
widgets::FocusCaret
enum FocusCaret { Keep, End, SelectAll }
Where TextFieldBuilder::focus_caret puts the caret when autofocus or focus_when focuses the field.
Builder of a popup menu. Item actions run under the owner current when the menu was built, or under host. label names the menu for screen readers; the default is "Menu". anchor sets the position of the menu.
Builder of a command palette. disabled(label) adds an item that cannot run. submit runs with the label of each item that runs. cancel runs when the user leaves the top level.
Builder of a table. selectable_checkboxes() adds a leading selection box to each row. row_activate runs on a plain left click on a row, including its padding but not its selection box, and on Enter while the row has focus. It leaves the selection as the click set it. framed(false) drops the rounded outer border so the table runs edge to edge. The header fills with table-header; row dividers use border-subtle. Selected rows fill with accent-5, and accent-6 under hover or press. row_menu opens a context menu for a row. empty builds the content shown when no row is visible. viewport_fill() takes the height of the parent.
Builder of a virtual list. cursor shares the keyboard-focused row with a signal and keeps that row in view; arrow keys write it. identified() keys rows by Identifiable::id, so selection and row state follow a row when the list changes. follow_end(true) opens the list at the last row and keeps it pinned there while rows are added, until the user scrolls up. follow_row scrolls the minimum distance to keep the row in a read-only or derived signal visible, and wins over cursor for scrolling; while that row is the last row, it also pins the end like follow_end. initial_scroll and scroll_into_view set the start position only. measured() lays rows out at the list width and caches their heights. The two extent binds receive the content height and the largest scroll offset. item_height gives each row its own height. key_by keys rows by the value it returns. change runs with the first selected index each time the selection changes.
Builder of tabs. labels adds tabs without panels, for a strip that drives content elsewhere. active binds the selected index; without it the tabs keep their own. pill() draws pill tabs. justify_list aligns the tab row. closeable(true) shows a close button on each tab; it calls close with the tab index, and the app removes the tab. reorderable(true) lets the user drag tabs; order holds the tab order. disabled takes the indexes of the disabled tabs.
Builder of a diff view. change shows one button per DiffView and calls f with the one the user picks. path shows in the header; status shows as a line under the rows. wrap(true) wraps long lines inside the row instead of ending them with …; a wrapped line keeps its syntax colors but not the in-line change highlight.
Builder of a splitter. child_constrained is pane(node).initial(initial).min(min).max(max).commit(). sizes_bind writes the pane sizes to the signal. A dragged handle snaps to a snap point within snap_threshold; the default is 8.
widgets::ScrollBuilder
struct ScrollBuilder (converts into NodeBuilder); extent(f32 or Signal<f32>), fill(), fit(), follow_end(bool); scroll_bind(Signal<f32>)
Builder of a scroll area. fill() takes the parent's height. fit() takes the content height up to the parent's height, then scrolls. follow_end(true) opens the area scrolled to the bottom and keeps it pinned there while the content grows, until the user scrolls up.
Builder of a progress bar. tone colors the fill. WidgetLayoutExt::height sets the track height (default 8 px). In a terminal, a height under one cell draws the bar as a ─ line.
Builder of a sparkline. Without range, the scale runs from the lower of 0 and the minimum to the maximum. rows(n) draws a filled area graph n text rows tall, bottom-aligned. tones sets an optional tone per value that overrides tone for its column; a braille cell takes the tone of its right value, else its left.
widgets::SparkMark
enum SparkMark { Block, Braille }
Sparkline glyphs. Block (default): one column per value, 8 levels per row. Braille: two values per cell, 4 levels per row.
widgets::SparkFill
enum SparkFill { Solid, Shade }
Body of a multi-row sparkline. Solid (default): every cell in the tone. Shade: the body in a dim step of the tone and the top cell of each column solid, so a steady high value reads as a line.
Build the app, copy an optional regular, non-symlink profile unchanged to Contents/embedded.provisionprofile, then sign on macOS. A profile requires a nonempty identity other than -.
Build the Windows app directory. Rejects AppBundle::provisioning_profile.
sigil-pack macos --provisioning-profile PATH sets the profile. Other commands reject this flag. --identity or SIGIL_CODESIGN_IDENTITY supplies the identity. Profile embedding does not validate the profile's contents, expiration, application identifier, or entitlements.
Errors
Type
Returned by
Meaning
sigil::Error
sigil::run
Opaque application error. Error::kind returns an ErrorKind (Window, Gpu, Font, Io, Task, Config, Other). Error::new wraps any std::error::Error as Other; Error::with_kind sets the kind. Error::source_error returns the inner error.
tasks::ScheduleError
SignalWriter::set, SignalWriter::update
Closed: the dispatcher is closed. Full: the dispatcher queue is full.
The layout pass failed. It converts into sigil::Error.
sigil_sign::SignError
sign_file, verify_file
KeyFile, Key, Package, Envelope, TrustedComment, or PasswordRequired: the key, the package, the signature, or the signed file name or version failed, or an encrypted key had no password.
sigil_sign::PackError
macos_app, windows_dir
Missing, Io, Codesign, Escape, Symlink, Occupied, or NotFile.
Mounts a tree on a headless host with a task runtime installed. size uses the terminal cell host (default 80×24); pixels uses the window host and renders offscreen through wgpu. Each frame applies finished task results.
Paint every frame through the GPU renderer into an offscreen texture at scale and wait for the GPU, so profiles include emit, submit, and GPU time. Without a GPU adapter it falls back to pixels. Every harness frame is a profile frame.
Route events through Host::frame and run frames until no signal write or animation is pending (at most SETTLE_SAFETY_CAP frames). advance moves the virtual interval clock and runs 1/60 s frames across by.
Pointer actions at the centre of a labelled control, a Node, or a Point (layout points). A label waits up to EXPECT_TIMEOUT for its control. Each action settles.
Run the alignment lint with the tolerance for the harness host: cells on the terminal surface, points on pixel and GPU surfaces. assert_aligned panics with every finding and the text() dump.
The ShellEvent builders the harness sends. Coordinates are layout points.
Inspection
With the inspect cargo feature, an app exposes a local control socket when SIGIL_INSPECT is set. SIGIL_INSPECT=1 binds 127.0.0.1:5761; any other value is an address to bind. The socket speaks one JSON object per line, one reply per request.
op
Request
Reply
a11y::tree
–
nodes: id to {role, name, description, bounds, children, focused, selected, expanded, toggled, value, numeric} plus root and focus. Bounds are in points on the window host and cells on the terminal host.
a11y::snapshot
–
text: the accessibility text dump.
screenshot
–
Terminal: text with the painted grid. Window: png (base64) plus width/height in physical pixels.
layout::align
–
misalignments: a list of {kind: "column" or "inset", node, detail}, where detail is the Misalignment display text.
surfaces
–
surfaces: keyed surface holes and rects.
settle
–
ok after servicing; settled is false while the frame stays dirty or animations run.
terminal::click
col/row (terminal cells) or x/y (points), button
Moves, presses, and releases the pointer through the normal router.
move, down, up
same coordinates
One pointer phase.
widgets::scroll
coordinates plus dx/dy in lines
A scroll event.
key
key (a NamedKey name or one character), ctrl/shift/alt/meta
Key down and up.
type
text
Key events per character.
profile
last (frame count, default 30)
enabled, frames (index, cause, wall_ms, per-phase ms, counters, backend), and summary (the exit report text).
profile_dump
path (optional)
Writes the Chrome trace JSON now and replies with path. Defaults to SIGIL_PROFILE's value or sigil-profile.json.
profile_on, profile_off
–
Enable or stop frame collection without restarting.
hud
on (default true)
Draws the frame-HUD overlay: a sparkline, the active backend with any fallback cause, and last-frame phase readout top-right. Terminal host draws cells; the desktop host overlays scene commands at paint. Enabling turns profiling on.
Requests are serviced between frames on the UI thread, so replies reflect the tree as last laid out. The socket is loopback by convention; the feature is off without the environment variable.
Conventions
Make reactive writes on the thread that owns the runtime. From another thread, use signal_writer, or on_message for a channel.
sigil::run installs the OS clipboard on the window host. The terminal host installs an OSC 52 clipboard; on a local macOS terminal it writes with pbcopy and reads with pbpaste. Over OSC 52 the clipboard cannot be read, so a text input leaves Ctrl+V to the app and the terminal's own paste arrives as a paste event. An embed host calls install(OsClipboard) itself.
Public event, command, error, and config types are #[non_exhaustive]. Match them with a _ arm. Build AppConfig with its builder methods.
The renderer API takes wgpu types. sigil::wgpu re-exports the wgpu version that sigil-ui uses.
SIGIL_BACKEND accepts auto, wgpu, and cpu. See Troubleshooting.
sigil::profile keys are typed. span(Phase) times a phase and count(Counter), count_add(Counter, n), and gauge(Counter, v) record counters. Phase::category() returns a Category. name() and Display give the trace text. Frame::counter(Counter) reads a counter; Frame::phases and Frame::counts hold PhaseTime and CounterValue pairs.
profile::begin_frame(BackendStatus) opens a frame for one host. A BackendStatus is a BackendKind (Gpu, GpuSoftware, Cpu, Terminal) and a FallbackCause (None, NoAdapter, DeviceError, ForcedByEnv, UnknownEnv). BackendStatus::TERMINAL is the terminal host's status. Frame::backend holds the status of the host that drew that frame, so a window host and a terminal host in one process keep separate statuses.
profile::interact(Cause) marks the input that caused a frame. Cause is Idle, Pointer, Hover, Key, Scroll, Ime, Resize, A11y, Expose, or Input. When several inputs land in one frame, the highest Cause::rank() wins. Frame::cause holds it.
Parsers for markdown, HTML, SVG, and theme files run on the UI thread. See SECURITY.md for the input surfaces.