Sigil

Sigil API map

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.

Install gives the dependency line.

Application code imports the prelude:

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.

NameSignaturePurpose
geometrymod geometryPoints, rectangles, and sizes in logical and physical pixels, and the device scale factor.
preludemod preludeThe application import surface.
a11ymod a11yAccessibility tree construction.
animationmod animationEasing, springs, and keyframes.
animation_runtimemod animation_runtimeAnimators 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.
appmod appApplication host, configuration, and theme files.
bidimod bidiBidirectional text: paragraph levels, visual order, and ParagraphBidi::visual_step for caret motion. text::bidi re-exports it.
clipboardmod clipboardClipboard trait and the installed clipboard.
eventsmod eventsEvent routing, handlers, and focus.
halmod halInput events, keys, and geometry types.
iconsmod iconsBundled icon glyphs (feature scene).
kernelmod kernelNode tree, builders, and roles.
layoutmod layoutLayout styles and the layout engine.
profilemod profileFrame timing counters.
reactivemod reactiveSignals, effects, owners, and intervals.
renderermod rendererThe GPU and CPU renderers (feature scene).
scenemod sceneThe CommandScene display list.
shellmod shellThe window shell (feature desktop).
stylemod stylePaint, themes, tokens, and metrics.
tasksmod tasksAsync tasks and cross-thread dispatch.
terminalmod terminalThe 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.
textmod textFonts and text shaping (feature scene).
widgetsmod widgetsWidget builders.
wgpuextern crate wgpuThe wgpu version that the renderer uses (feature scene).
runfn run<C: Into<AppConfig>, N: IntoNode>(config: C, app: impl Fn() -> N + 'static) -> AppResultRun the app component on the host that config selects. app is called once, inside the root's reactive owner, and again after a hot patch.
request_exitfn request_exit()Ask the running host to exit after this frame.
dialog::FileDialogFileDialog::new(); filter(name, &[ext]), directory(path), file_name(name); open_file(), open_files(), pick_folder(), save_file()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::Pickedtype Picked<T> = Signal<Status<Option<T>, Infallible>>Result of a file dialog.
dialog::open_file, dialog::save_file, dialog::pick_folderfn() -> Picked<PathBuf>FileDialog::new() with one pick.
dialog::message, dialog::confirmfn(title, body) -> Signal<Status<bool, Infallible>>An alert with OK, or OK and Cancel. Resolves Ok(true) on OK.
dialog::mockpush_path, push_paths, push_alert, reset (cfg(test) or feature kittest)Queues the next dialog answers. A queued answer resolves the signal at once and opens no dialog.
AppConfigstruct AppConfig; From<&str>, From<String>; AppConfig::new(title); host: window() (feature desktop), terminal() (feature terminal), canvas(id) (feature desktop); window: size(w, h), window_size() -> (u32, u32), and with feature desktop min_size(w, h), user_zoom(f32), frameless(bool), overlay(bool), anchor(Anchor); theme_file(path), panic_policy(PanicPolicy), quit_on_ctrl_c(bool), frame_interval(Duration)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).
AppResulttype AppResult<T> = Result<T, Error>Result of the application functions.
Errorstruct ErrorOpaque application error.
Hoststruct HostEmbed host: build, route, lay out, and paint one tree. set_caps(HostCaps) tells widgets what the host can show.
Host::misalignmentsfn misalignments(&self, tolerance: Tolerance) -> Vec<Misalignment>Run layout::align::misalignments on the mounted tree as last laid out. Empty before mount.
Host::emit_since, Host::reset_emitfn emit_since(&mut self, viewport: (f32, f32), delta: &FrameDelta, prev: &CommandScene) -> (CommandScene, EmitDiff); fn reset_emit(&mut self)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::*;use std::time::Duration; fn app_tree() -> impl IntoNode {    text("Hello")} fn main() -> sigil::AppResult<()> {    let config: sigil::AppConfig = sigil::AppConfig::new("Demo").size(640, 400).terminal();    let _ = (sigil::request_exit, sigil::app::is_grid, sigil::app::viewport_size);    let _: sigil::AppResult<()> = Err(sigil::Error::with_kind(sigil::app::ErrorKind::Io, std::fmt::Error));    let _ = sigil::app::PanicPolicy::Isolate;    let _ = config.clone().frame_interval(Duration::from_millis(33));    if let Some(theme) = sigil::app::parse_theme("base = \"dark\"\n[tokens]\naccent = \"#3c59e7\"\n") {        sigil::app::set_theme(theme);    }    let _: fn(std::path::PathBuf) -> sigil::AppResult<sigil::app::ThemeWatcher> = sigil::app::watch_theme;    let _ = sigil::app::open("https://example.com");    let mut host = sigil::Host::new();    host.mount(app_tree);    let _: Option<sigil::app::AccessibilityTree> = None;    let _ = sigil::app::WindowCommand::DragResize(sigil::app::ResizeDirection::East);    let _ = sigil::app::WindowOpts::default();    let _ = sigil::app::Anchor::BottomCenter { margin: 16.0 };    sigil::app::set_default_fonts(sigil::app::DefaultFonts::default());    sigil::app::use_system_fonts();    let tuning: sigil::app::TextTuning = sigil::app::text_tuning();    sigil::app::set_text_tuning(tuning);    let _ = sigil::widgets::interaction::InteractionState::new(true);    let _ = sigil::style::Token::Accent;    let _ = sigil::scene::CommandScene::default();    let _: Option<sigil::wgpu::TextureFormat> = None;    let _ = sigil::terminal::focused();    let _ = (sigil::layout::cols(2.0), sigil::reactive::batch(|| 1));    let _ = sigil::animation::Easing::Linear;    let _ = sigil::animation_runtime::MotionPrefs::reduced();    let _ = sigil::tasks::ScheduleError::Closed;    let _ = sigil::widgets::spacer();    let _ = sigil::events::FocusIntent::Down;    let _ = sigil::events::KeyPhase::Down;    let _ = sigil::kernel::container();    let _ = sigil::clipboard::paste();    let _ = sigil::app::set_theme;    sigil::run(config, app_tree)}
use sigil::prelude::*;use std::time::Duration; fn app_tree() -> impl IntoNode {  text("Hello")} fn main() -> sigil::AppResult<()> {  let config: sigil::AppConfig =    sigil::AppConfig::new("Demo")      .size(640, 400)      .terminal();  let _ = (    sigil::request_exit,    sigil::app::is_grid,    sigil::app::viewport_size,  );  let _: sigil::AppResult<()> =    Err(sigil::Error::with_kind(      sigil::app::ErrorKind::Io,      std::fmt::Error,    ));  let _ =    sigil::app::PanicPolicy::Isolate;  let _ =    config.clone().frame_interval(      Duration::from_millis(33),    );  if let Some(theme) =    sigil::app::parse_theme(      "base = \"dark\"\n[tokens]\naccent = \"#3c59e7\"\n",    )  {    sigil::app::set_theme(theme);  }  let _: fn(    std::path::PathBuf,  ) -> sigil::AppResult<    sigil::app::ThemeWatcher,  > = sigil::app::watch_theme;  let _ = sigil::app::open(    "https://example.com",  );  let mut host = sigil::Host::new();  host.mount(app_tree);  let _: Option<    sigil::app::AccessibilityTree,  > = None;  let _ = sigil::app::WindowCommand::DragResize(sigil::app::ResizeDirection::East);  let _ =    sigil::app::WindowOpts::default();  let _ =    sigil::app::Anchor::BottomCenter {      margin: 16.0,    };  sigil::app::set_default_fonts(    sigil::app::DefaultFonts::default(),  );  sigil::app::use_system_fonts();  let tuning: sigil::app::TextTuning =    sigil::app::text_tuning();  sigil::app::set_text_tuning(tuning);  let _ = sigil::widgets::interaction::InteractionState::new(true);  let _ = sigil::style::Token::Accent;  let _ =    sigil::scene::CommandScene::default(    );  let _: Option<    sigil::wgpu::TextureFormat,  > = None;  let _ = sigil::terminal::focused();  let _ = (    sigil::layout::cols(2.0),    sigil::reactive::batch(|| 1),  );  let _ =    sigil::animation::Easing::Linear;  let _ = sigil::animation_runtime::MotionPrefs::reduced();  let _ =    sigil::tasks::ScheduleError::Closed;  let _ = sigil::widgets::spacer();  let _ =    sigil::events::FocusIntent::Down;  let _ = sigil::events::KeyPhase::Down;  let _ = sigil::kernel::container();  let _ = sigil::clipboard::paste();  let _ = sigil::app::set_theme;  sigil::run(config, app_tree)}

The modules bidi, icons, profile, renderer, shell, and text have no stable entry point in 0.1. Use them only through the functions above.

Feature-gated root items:

#[cfg(feature = "audio")]fn play(path: &std::path::Path) -> sigil::AppResult<()> {    sigil::app::Player::new().play_path(path)} #[cfg(feature = "pty")]fn shell() -> sigil::AppResult<sigil::app::Session> {    sigil::app::Session::spawn("sh")} #[cfg(feature = "dialog")]fn pick() -> sigil::app::dialog::Picked<std::path::PathBuf> {    sigil::app::dialog::FileDialog::new().filter("CSV", &["csv"]).open_file()} #[cfg(feature = "menu")]fn menu_events() -> sigil::reactive::EventChannel<sigil::app::menu::MenuId> {    sigil::app::menu::events()} #[cfg(feature = "tray")]fn tray_events() -> sigil::reactive::EventChannel<tray_icon::TrayIconEvent> {    sigil::app::tray::events()} #[cfg(feature = "terminal")]use sigil::terminal::render as _; #[cfg(feature = "kittest")]use sigil::testing as _; fn main() {}
#[cfg(feature = "audio")]fn play(  path: &std::path::Path,) -> sigil::AppResult<()> {  sigil::app::Player::new()    .play_path(path)} #[cfg(feature = "pty")]fn shell()-> sigil::AppResult<sigil::app::Session>{  sigil::app::Session::spawn("sh")} #[cfg(feature = "dialog")]fn pick() -> sigil::app::dialog::Picked<  std::path::PathBuf,> {  sigil::app::dialog::FileDialog::new()    .filter("CSV", &["csv"])    .open_file()} #[cfg(feature = "menu")]fn menu_events()-> sigil::reactive::EventChannel<  sigil::app::menu::MenuId,> {  sigil::app::menu::events()} #[cfg(feature = "tray")]fn tray_events()-> sigil::reactive::EventChannel<  tray_icon::TrayIconEvent,> {  sigil::app::tray::events()} #[cfg(feature = "terminal")]use sigil::terminal::render as _; #[cfg(feature = "kittest")]use sigil::testing as _; fn main() {}

Prelude

use sigil::prelude::*; imports every item in this section.

Application

NameSignaturePurpose
Host::mount_hotfn 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.
runfn run(config, app) -> AppResultSame as sigil::run.
AppConfigstruct AppConfigSame as sigil::AppConfig.
AppResulttype AppResult<T>Same as sigil::AppResult.
set_themefn set_theme(theme: Theme)Same as sigil::app::set_theme.
watch_themefn watch_theme(path) -> AppResult<ThemeWatcher>Same as sigil::app::watch_theme.
ThemeWatcherstruct ThemeWatcherSame as sigil::app::ThemeWatcher.
openfn open(target) -> AppResult<()>Same as sigil::app::open (feature desktop).
use sigil::Error;use sigil::app::is_grid;use sigil::app::parse_theme;use sigil::app::viewport_size;use sigil::prelude::*;use sigil::Host;use sigil::reactive::Runtime; fn tree() -> impl IntoNode {    let size = viewport_size();    text(derived(move || format!("{:?} grid={}", size.get(), is_grid())))} fn main() -> AppResult<()> {    let _: Option<(Host, ThemeWatcher, Error)> = None;    let _ = Runtime::scope("demo", || text("x"));    set_theme(parse_theme("base = \"light\"\n[tokens]\n").unwrap_or_else(Theme::light));    let _ = open("https://example.com");    let _ = watch_theme("theme.toml").map(drop);    run(AppConfig::new("Demo"), tree)} #[cfg(feature = "audio")]fn player() -> sigil::app::Player { sigil::app::Player::new() }#[cfg(feature = "pty")]fn session() -> AppResult<sigil::app::Session> { sigil::app::Session::spawn("sh") }
use sigil::Error;use sigil::Host;use sigil::app::is_grid;use sigil::app::parse_theme;use sigil::app::viewport_size;use sigil::prelude::*;use sigil::reactive::Runtime; fn tree() -> impl IntoNode {  let size = viewport_size();  text(derived(move || {    format!(      "{:?} grid={}",      size.get(),      is_grid()    )  }))} fn main() -> AppResult<()> {  let _: Option<(    Host,    ThemeWatcher,    Error,  )> = None;  let _ =    Runtime::scope("demo", || {      text("x")    });  set_theme(    parse_theme(      "base = \"light\"\n[tokens]\n",    )    .unwrap_or_else(Theme::light),  );  let _ = open("https://example.com");  let _ =    watch_theme("theme.toml").map(drop);  run(AppConfig::new("Demo"), tree)} #[cfg(feature = "audio")]fn player() -> sigil::app::Player {  sigil::app::Player::new()}#[cfg(feature = "pty")]fn session()-> AppResult<sigil::app::Session> {  sigil::app::Session::spawn("sh")}

Nodes and text

NameSignaturePurpose
kernel::Cxstruct Cx; cx.add(node) -> NodeIdThe node tree. App code does not name it; a component is a function that returns impl IntoNode. Embedders and on_added hooks use it.
kernel::NodeIdstruct NodeIdHandle of a node in the tree.
kernel::FrameDelta, kernel::Cx::take_delta#[non_exhaustive] struct FrameDelta { paint: AHashSet<NodeId>, layout: AHashSet<NodeId>, structure: bool }, is_empty(); fn take_delta(&mut self) -> FrameDeltaThe 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.
kernel::NodeTag, kernel::DeltaKind, kernel::Node::tagstruct NodeTag, id(), record(DeltaKind); enum DeltaKind { Paint, Layout }, layout_if(bool); fn tag(&self) -> Option<NodeTag>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.
NodeBuilderstruct NodeBuilder; child(impl IntoNode), children_reactive(Fn() -> IntoIterator<Item = N>), children_keyed(Fn() -> IntoIterator<Item = (K, N)>), with<T>(value), mutate(FnOnce(&mut Node)), add(&mut Cx) -> NodeId; accessibility: role(Role), label(name), description(text), placeholder(text), labelled_by(NodeId), owns(NodeId), action(Action), keyboard_shortcut(shortcut), focusable(bool), tab_index(i32), traps_tab(bool), hittable(bool), checked(Signal<bool>), selected(Signal<bool>), expanded(Signal<bool>), value(Signal<f32>, min, max), value_step(f32), text_value(Signal<String>), text_cursor(caret, anchor), row_count(Signal<usize>), row_index(usize), column_count(usize), column_index(usize), sort_direction(Signal<Option<SortDirection>>), on_added; From every widget builderBuilder 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.
IntoNodetrait IntoNodeA value that builds into a node.
nodefn node(child: impl IntoNode + 'static) -> Box<dyn IntoNode>Box a child of any builder type.
containerfn container() -> NodeBuilderA box that holds children.
fragmentfn fragment() -> NodeBuilderChildren without a box of their own.
showfn show<A: IntoNode, B: IntoNode>(cond: impl Reactive<bool>, then: impl Fn() -> A, otherwise: impl Fn() -> B) -> NodeBuilderMounts 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.
for_eachfn for_each<T, K: Clone + Eq + Hash, N: IntoNode>(items: Signal<Vec<T>>, key: impl Fn(&T) -> K, render: impl Fn(&T) -> N) -> NodeBuilderOne 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<>.
switchfn switch<K: Clone + PartialEq>(key: impl Reactive<K>) -> SwitchBuilder<K>; .case(key: K, view: impl Fn() -> N), .otherwise(view: impl Fn() -> N), .keep_alive(bool)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.
match_statusfn match_status<T, E: From<String>>(status: impl Reactive<Status<T, E>>) -> StatusView<T, E>; .idle(view), .pending(view), .ok(impl Fn(&T) -> N), .error(impl Fn(&E) -> N)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.
textfn text(source: impl Into<TextContent>) -> TextBuilderThe 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.
TextContentenum TextContent; From<&str>, From<String>, From<Signal<T: Display>>, From<F: Fn() -> String>Static, signal, or computed text. Every text-taking builder accepts it.
imagefn image(source: ImageSource) -> sigil::kernel::ImageBuilderAn image node from an ImageSource.
ImageSourceImageSource::from_rgba8(w, h, rgba) -> Option<ImageSource>Decoded RGBA pixels.
ImageRaster::atfn at(&self, width: u32, height: u32, scale: f32) -> Option<ImageSource>Pixels for a physical size in device pixels at scale. None when the source cannot draw at that size.
Roleaccesskit::RoleAccessibility role.
Actionaccesskit::ActionAccessibility action.
use sigil::kernel::A11yProps;use sigil::kernel::AccessibleName;use sigil::kernel::ImageCrop;use sigil::kernel::Node;use sigil::kernel::NodeExtensions;use sigil::kernel::NodeType;use sigil::kernel::ObjectFit;use sigil::kernel::TextBuilder;use sigil::kernel::TopLayer;use sigil::prelude::*;use sigil::kernel::Surface; fn tree() -> impl IntoNode {    let pixels = ImageSource::from_rgba8(1, 1, vec![255, 0, 0, 255]);    let picture = pixels.map(image).map(|i| i.fit(ObjectFit::Contain));    let heading: TextBuilder = text("Title").role(Role::Heading);    let body = container().label(AccessibleName::Static("Body".into())).action(Action::Click);    let marked = container().mutate(|n: &mut Node| drop((&n.kind as &NodeType, &n.a11y as &A11yProps)));    let items = signal(vec![1_u32, 2, 3]);    let open = signal(true);    let rows = for_each(items, |n: &u32| *n, |n: &u32| text(n.to_string()));    let panel = show(open, || text("Open"), || text("Closed"));    let children: Vec<Box<dyn IntoNode>> = vec![node(heading), node(text(|| "live".into())), node(rows), node(panel)];    let _: Option<(ImageCrop, Surface, TopLayer, &NodeExtensions)> = None;    let mut root: NodeBuilder = fragment().child(body).child(marked);    for child in children { root = root.child(child); }    if let Some(picture) = picture { root = root.child(picture); }    container().child(root)} fn main() {    let _ = tree;}
use sigil::kernel::A11yProps;use sigil::kernel::AccessibleName;use sigil::kernel::ImageCrop;use sigil::kernel::Node;use sigil::kernel::NodeExtensions;use sigil::kernel::NodeType;use sigil::kernel::ObjectFit;use sigil::kernel::Surface;use sigil::kernel::TextBuilder;use sigil::kernel::TopLayer;use sigil::prelude::*; fn tree() -> impl IntoNode {  let pixels = ImageSource::from_rgba8(    1,    1,    vec![255, 0, 0, 255],  );  let picture = pixels    .map(image)    .map(|i| i.fit(ObjectFit::Contain));  let heading: TextBuilder =    text("Title").role(Role::Heading);  let body = container()    .label(AccessibleName::Static(      "Body".into(),    ))    .action(Action::Click);  let marked = container().mutate(    |n: &mut Node| {      drop((        &n.kind as &NodeType,        &n.a11y as &A11yProps,      ))    },  );  let items = signal(vec![1_u32, 2, 3]);  let open = signal(true);  let rows = for_each(    items,    |n: &u32| *n,    |n: &u32| text(n.to_string()),  );  let panel = show(    open,    || text("Open"),    || text("Closed"),  );  let children: Vec<Box<dyn IntoNode>> = vec![    node(heading),    node(text(|| "live".into())),    node(rows),    node(panel),  ];  let _: Option<(    ImageCrop,    Surface,    TopLayer,    &NodeExtensions,  )> = None;  let mut root: NodeBuilder =    fragment()      .child(body)      .child(marked);  for child in children {    root = root.child(child);  }  if let Some(picture) = picture {    root = root.child(picture);  }  container().child(root)} fn main() {  let _ = tree;}

Layout

NameSignaturePurpose
rowfn row() -> NodeBuilderA container that places its children left to right with the theme gap: 8 px in a window, one cell in a terminal.
columnfn column() -> NodeBuilderA container that places its children top to bottom with the theme gap.
LayoutStyleLayoutStyle::flex_column(), flex_row(), grid(cols), block(); LayoutStyle::pane(w, h), with_layout(FnOnce(&mut StyleData)), data() -> &StyleData; size: width(d), height(d), fixed_size(w, h), fill(), fill_width(), fill_height(), min_width(d), min_height(d), min_size(w, h), max_width(d), max_height(d), max_size(w, h), box_sizing(BoxSizing); flex: flex_direction(FlexDirection), flex_wrap(FlexWrap), flex_basis(d), grow(f32), shrink(f32); align: align_items(AlignItems), align_self(AlignSelf), align_content(AlignContent), justify_content(JustifyContent); grid: grid_columns(Vec<TrackSize>), grid_rows(Vec<TrackSize>), grid_area(col, row), grid_column_span(n), grid_row_span(n), grid_dense(); position: display(Display), position(Position), inset(v), inset_top/right/bottom/left(v); overflow(Overflow), overflow_x(Overflow), overflow_y(Overflow)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.
LayoutStyle spacingpadding(v), padding_x/y(v), padding_top/right/bottom/left(v), margin(v), margin_x(v), margin_y(v), margin_top(v), margin_right(v), margin_bottom(v), margin_left(v), gap(v), gap_x(v), gap_y(v)Padding, margin, and gap in px or text units. margin_* take the same type as margin; gap_x and gap_y take the same type as gap.
LayoutBuilderExtfn layout(self, style: LayoutStyle) -> SelfSet the layout of a node or text.
WidgetLayoutExtfn layout, width, height, grow, map_node(FnOnce(NodeBuilder) -> NodeBuilder)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.
LayoutReactiveExtfn position_reactive, size_reactive, bounds_reactiveWrite the laid-out position or size to a signal.
Displayenum Display { Block, Flex, Grid, None }Display mode.
FlexWrapenum FlexWrap { NoWrap, Wrap, WrapReverse }Wrap mode of a flex box.
AlignItemsenum AlignItems { Start, End, Center, Baseline, Stretch }Cross-axis alignment of children.
JustifyContentenum JustifyContentMain-axis distribution of children.
rowsconst fn rows(count: f32) -> TextLengthHeight of count text lines.
colsconst fn cols(count: f32) -> TextLengthWidth of count character cells.
emconst fn em(count: f32) -> TextLengthcount times the font size.
IntoPxtrait IntoPx { fn into_px(self) -> f32; }A pixel count or a TextLength, for widget sizes such as width and row_height.
use sigil::layout::AlignSelf;use sigil::layout::BoundsReactive;use sigil::layout::FlexDirection;use sigil::layout::LayoutEngine;use sigil::layout::LayoutResult;use sigil::layout::LengthPercentageAuto;use sigil::layout::Overflow;use sigil::layout::Position;use sigil::layout::ReactivePosition;use sigil::layout::TextLength;use sigil::layout::TrackSize;use sigil::prelude::*;use sigil::layout::LayoutError;use sigil::layout::TextMeasure; fn tree() -> impl IntoNode {    let size = signal((0.0_f32, 0.0_f32));    let grid = LayoutStyle::grid(vec![TrackSize::Px(120.0), TrackSize::Fr(1.0), TrackSize::Auto]);    let column = LayoutStyle::flex_column().gap(rows(1.0)).padding(cols(2.0)).min_width(em(20.0));    let row = LayoutStyle::flex_row().flex_wrap(FlexWrap::Wrap).align_items(AlignItems::Center);    let row = row.justify_content(JustifyContent::SpaceBetween).align_self(AlignSelf::Stretch);    let abs = LayoutStyle::block().position(Position::Absolute).inset(LengthPercentageAuto::Px(0.0));    let abs = abs.overflow(Overflow::Hidden).display(Display::Flex).flex_direction(FlexDirection::Row);    let _ = (sigil::layout::Dimension::from(rows(2.0)), sigil::layout::LengthPercentage::from(cols(1.0)), TextLength::Em(1.0));    let _: Option<(&LayoutEngine, LayoutResult, LayoutError, ReactivePosition, BoundsReactive)> = None;    let _: Option<&dyn TextMeasure> = None;    let button = button("OK").width(80.0).grow(1.0);    container()        .layout(column)        .child(container().layout(grid).size_reactive(size))        .child(container().layout(row).child(button))        .child(container().layout(abs))} fn main() {    let _ = tree;    fn _ext<T: WidgetLayoutExt + LayoutBuilderExt + LayoutReactiveExt>(_: T) {}}
use sigil::layout::AlignSelf;use sigil::layout::BoundsReactive;use sigil::layout::FlexDirection;use sigil::layout::LayoutEngine;use sigil::layout::LayoutError;use sigil::layout::LayoutResult;use sigil::layout::LengthPercentageAuto;use sigil::layout::Overflow;use sigil::layout::Position;use sigil::layout::ReactivePosition;use sigil::layout::TextLength;use sigil::layout::TextMeasure;use sigil::layout::TrackSize;use sigil::prelude::*; fn tree() -> impl IntoNode {  let size = signal((0.0_f32, 0.0_f32));  let grid = LayoutStyle::grid(vec![    TrackSize::Px(120.0),    TrackSize::Fr(1.0),    TrackSize::Auto,  ]);  let column =    LayoutStyle::flex_column()      .gap(rows(1.0))      .padding(cols(2.0))      .min_width(em(20.0));  let row = LayoutStyle::flex_row()    .flex_wrap(FlexWrap::Wrap)    .align_items(AlignItems::Center);  let row = row    .justify_content(      JustifyContent::SpaceBetween,    )    .align_self(AlignSelf::Stretch);  let abs = LayoutStyle::block()    .position(Position::Absolute)    .inset(LengthPercentageAuto::Px(      0.0,    ));  let abs = abs    .overflow(Overflow::Hidden)    .display(Display::Flex)    .flex_direction(FlexDirection::Row);  let _ = (sigil::layout::Dimension::from(rows(2.0)), sigil::layout::LengthPercentage::from(cols(1.0)), TextLength::Em(1.0));  let _: Option<(    &LayoutEngine,    LayoutResult,    LayoutError,    ReactivePosition,    BoundsReactive,  )> = None;  let _: Option<&dyn TextMeasure> =    None;  let button =    button("OK").width(80.0).grow(1.0);  container()    .layout(column)    .child(      container()        .layout(grid)        .size_reactive(size),    )    .child(      container()        .layout(row)        .child(button),    )    .child(container().layout(abs))} fn main() {  let _ = tree;  fn _ext<    T: WidgetLayoutExt      + LayoutBuilderExt      + LayoutReactiveExt,  >(    _: T,  ) {  }}

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.

State

NameSignaturePurpose
Signalstruct Signal<T>; get, peek, set, update, with; PartialEq, Eq, Hash by identityReactive 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.
signalfn signal<T: 'static>(initial: T) -> Signal<T>Create a signal.
derivedfn derived<T: Clone + PartialEq, F: FnMut() -> T>(f: F) -> Signal<T>A signal that f recomputes. Notifies readers only when the new value differs from the old one.
effectfn effect<F: FnMut() + 'static>(f: F)Run f now and after each change it reads.
Reactivetrait Reactive<T>; fn read(&self) -> T; fn into_signal(self) -> Signal<T>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.
intervalfn interval(period: Duration, callback: impl Fn() + 'static) -> IntervalIdRun callback on a fixed period.
IntervalIdstruct IntervalIdHandle for sigil::reactive::cancel_interval.
use sigil::reactive::EventChannel;use sigil::reactive::batch;use sigil::reactive::defer;use sigil::reactive::on_cleanup;use sigil::reactive::untrack;use sigil::prelude::*;use std::time::Duration; fn tree() -> impl IntoNode {    let count: Signal<i32> = signal(0);    let double = derived(move || count.get() * 2);    let even = derived(move || count.get() % 2 == 0);    effect(move || println!("{} {}", double.get(), even.get()));    on_cleanup(|| println!("disposed"));    batch(|| { count.set(1); count.update(|n| *n += 1); });    effect(move || untrack(|| count.update(|n| *n += 1)));    let inbox: Signal<Option<String>> = signal(None);    effect(move || {        if let Some(line) = inbox.get() {            println!("{line}");            defer(move || inbox.set(None));        }    });    let len = count.with(|n| n.to_string().len());    let source: Box<dyn Reactive<i32>> = Box::new(move || count.get() + len as i32);    let channel: EventChannel<String> = EventChannel::new();    drop(channel.subscribe(|msg| println!("{msg}")));    let id: IntervalId = interval(Duration::from_secs(1), move || count.update(|n| *n += 1));    sigil::reactive::cancel_interval(id);    channel.emit(source.read().to_string());    text(derived(move || count.get().to_string()))} fn main() {    let _ = tree;}
use sigil::prelude::*;use sigil::reactive::EventChannel;use sigil::reactive::batch;use sigil::reactive::defer;use sigil::reactive::on_cleanup;use sigil::reactive::untrack;use std::time::Duration; fn tree() -> impl IntoNode {  let count: Signal<i32> = signal(0);  let double =    derived(move || count.get() * 2);  let even = derived(move || {    count.get() % 2 == 0  });  effect(move || {    println!(      "{} {}",      double.get(),      even.get()    )  });  on_cleanup(|| println!("disposed"));  batch(|| {    count.set(1);    count.update(|n| *n += 1);  });  effect(move || {    untrack(|| {      count.update(|n| *n += 1)    })  });  let inbox: Signal<Option<String>> =    signal(None);  effect(move || {    if let Some(line) = inbox.get() {      println!("{line}");      defer(move || inbox.set(None));    }  });  let len =    count.with(|n| n.to_string().len());  let source: Box<dyn Reactive<i32>> =    Box::new(move || {      count.get() + len as i32    });  let channel: EventChannel<String> =    EventChannel::new();  drop(channel.subscribe(|msg| {    println!("{msg}")  }));  let id: IntervalId = interval(    Duration::from_secs(1),    move || count.update(|n| *n += 1),  );  sigil::reactive::cancel_interval(id);  channel    .emit(source.read().to_string());  text(derived(move || {    count.get().to_string()  }))} fn main() {  let _ = tree;}

Tasks

NameSignaturePurpose
taskfn task<T: Send, E: Send, F: Fn() -> Fut, Fut: Future<Output = Result<T, E>> + Send>(make: F) -> Task<T, E>Async work that runs on demand. Each run calls make for a new future.
task_withfn task_with<A, T: Send, E: Send, F: Fn(A) -> Fut, Fut: Future<Output = Result<T, E>> + Send>(make: F) -> Task<T, E, A>A task whose runs take an argument: run_with(arg) calls make(arg), so one task serves many targets, such as staging one path.
Taskstruct 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.
spawnfn spawn<T, E, F: Future<Output = Result<T, E>> + Send>(future: F) -> Signal<Status<T, E>>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::sleepasync 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::blockingasync fn blocking<T: Send + 'static, F: FnOnce() -> T + Send + 'static>(f: F) -> TRun 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 AutoWorker threads of the native task runtime. Auto uses one per CPU.
tasks::AsyncRuntime::with_workersfn with_workers(workers: TaskWorkers) -> io::Result<AsyncRuntime>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::TaskHandleabort(), is_finished() -> boolA 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.
Statusenum Status<T, E> { Idle, Pending, Ok(T), Err(E), Panicked(String) }; is_pending(), is_ok(), is_err(), is_panicked()State of a task. A Task is Idle until its first run; spawn starts Pending.
signal_writerfn signal_writer<T: Send>(signal: Signal<T>) -> SignalWriter<T>A Send handle that writes a signal. Panics outside a reactive scope, or when no runtime is installed with AsyncRuntime::install_current.
SignalWriterset(value) -> Result<(), ScheduleError>, update(f) -> Result<(), ScheduleError>; CloneWrite a signal from another thread. Clone one writer into each task run to stream tokens into a signal; no channel is needed.
ScheduleErrorenum ScheduleError { Closed, Full }A cross-thread write was not queued.
use sigil::tasks::on_message;use sigil::tasks::on_message_or_close;use sigil::prelude::*; fn tree() -> impl IntoNode {    let log = signal(String::new());    let writer: SignalWriter<String> = signal_writer(log);    std::thread::spawn(move || {        let _: Result<(), ScheduleError> = writer.update(|s| s.push_str("line\n"));    });    let fetched: Signal<Status<u32, String>> = spawn(async { Ok::<u32, String>(42) });    let reload: Task<u32, String> = task(|| async { Ok(7) });    reload.run();    let (tx, rx) = tokio::sync::mpsc::unbounded_channel::<String>();    on_message(rx, move |line| log.update(|s| s.push_str(&line)));    let (done_tx, done_rx) = tokio::sync::mpsc::channel::<String>(16);    on_message_or_close(done_rx, move |line| log.set(line), || println!("worker closed"));    drop(done_tx);    drop(tx.send("hello\n".into()));    text(derived(move || match (fetched.get(), reload.status()) {        (Status::Ok(n), Status::Ok(m)) => format!("{n} {m}"),        _ => log.get(),    }))} fn main() {    let _ = tree;}
use sigil::prelude::*;use sigil::tasks::on_message;use sigil::tasks::on_message_or_close; fn tree() -> impl IntoNode {  let log = signal(String::new());  let writer: SignalWriter<String> =    signal_writer(log);  std::thread::spawn(move || {    let _: Result<(), ScheduleError> =      writer.update(|s| {        s.push_str("line\n")      });  });  let fetched: Signal<    Status<u32, String>,  > = spawn(async {    Ok::<u32, String>(42)  });  let reload: Task<u32, String> =    task(|| async { Ok(7) });  reload.run();  let (tx, rx) = tokio::sync::mpsc::unbounded_channel::<String>();  on_message(rx, move |line| {    log.update(|s| s.push_str(&line))  });  let (done_tx, done_rx) =    tokio::sync::mpsc::channel::<String>(      16,    );  on_message_or_close(    done_rx,    move |line| log.set(line),    || println!("worker closed"),  );  drop(done_tx);  drop(tx.send("hello\n".into()));  text(derived(move || {    match (      fetched.get(),      reload.status(),    ) {      (        Status::Ok(n),        Status::Ok(m),      ) => format!("{n} {m}"),      _ => log.get(),    }  }))} fn main() {  let _ = tree;}

Events and input

NameSignaturePurpose
NodeEventsExtkey, key_any, key_capture, key_capture_any, shortcut, pointer_down, on_scroll, on_gesture, on_paste, focus_in, link, on_selection_copy, autofocus, focus_when(Signal<u64>), ...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.
request_focusfn request_focus(id: NodeId)Move keyboard focus to a node.
ShortcutShortcut::new(key, mods), plain(key), ctrl(key), primary(key), label(), label_for(mac: bool); FromStr ("ctrl+shift+k".parse::<Shortcut>())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::PRIMARYconst PRIMARY: ModifiersStateThe platform's primary shortcut modifier: Command (META) on macOS, Control elsewhere, including wasm32.
Keykeyboard_types::NamedKeyA named key such as Key::Enter.
LogicalKeyLogicalKey::named(key), LogicalKey::character(s)A named key or a character.
ModifiersStatekeyboard_types::ModifiersModifier flags such as CONTROL.
KeyEventstruct KeyEvent { key, physical, modifiers, repeat, phase, text }A key press or release.
KeyPhaseenum KeyPhase { Down, Up }Press or release.
PointerEventstruct PointerEventA 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.
PointerKindenum PointerKind { Mouse, Touch, Pen }Pointer device.
PointerPhaseenum PointerPhase { Down, Move, Up, Enter, Leave, Cancel }Pointer event phase.
MouseButtonenum MouseButton { Left, Right, Middle, Back, Forward, Other(u16) }One mouse button.
MouseButtonsstruct MouseButtons; MouseButtons::LEFTSet of pressed buttons.
Pointstruct Point { x: f32, y: f32 }A position in logical px.
Sizestruct Size { width: Dim, height: Dim }; Size::max_content(), Size::min_content()A size constraint. The two constructors ask for the max-content or min-content size on both axes.
use sigil::app::ResizeDirection;use sigil::app::WindowCommand;use sigil::events::EventHandlers;use sigil::events::FileDropEvent;use sigil::events::FileDropPhase;use sigil::events::FocusIntent;use sigil::events::ImeEvent;use sigil::events::PhysicalKey;use sigil::events::ScrollDelta;use sigil::events::ScrollEvent;use sigil::events::ScrollPhase;use sigil::events::WindowEvent;use sigil::events::request_window_command;use sigil::geometry::Dim;use sigil::geometry::LogicalSize;use sigil::prelude::*;use sigil::events::EventRouter;use sigil::events::PointerEventInit;use sigil::events::ShellEvent; fn tree() -> impl IntoNode {    let save = Shortcut::ctrl(LogicalKey::character("s"));    let quit = Shortcut::new(LogicalKey::character("q"), ModifiersState::empty());    let root = container()        .focusable(true)        .key(save, |event: &mut KeyEvent| event.stop_propagation())        .key(Shortcut::plain(Key::Escape), |_| sigil::request_exit())        .key_capture(quit, |_| sigil::request_exit())        .shortcut(Shortcut::ctrl(LogicalKey::character("o")), |_| drop(()))        .key_any(|event| drop(event.phase == KeyPhase::Down && event.text.is_some()))        .key_capture_any(|event| drop(matches!(event.key, LogicalKey::Named(Key::Enter))))        .pointer_down(|event: &mut PointerEvent| drop(event))        .on_scroll(|event: &mut ScrollEvent| drop(event))        .file_drop(|event: &FileDropEvent| drop(event))        .on_ime(|event: &ImeEvent| drop(matches!(event, ImeEvent::Commit(_))))        .on_added(|_, id| request_focus(id));    request_window_command(WindowCommand::DragResize(ResizeDirection::South));    root} fn main() {    let _ = tree;    let _ = (PointerKind::Mouse, PointerPhase::Down, MouseButton::Left, MouseButtons::LEFT);    let _ = (ScrollDelta::Lines(Point { x: 0.0, y: 1.0 }), ScrollPhase::Moved, FileDropPhase::Dropped);    let _ = (FocusIntent::Down, PhysicalKey::KeyA, Size { width: Dim::MinContent, height: Dim::Fixed(1.0) });    let _ = LogicalSize { width: 80.0, height: 24.0 };    let _: Option<(ShellEvent, WindowEvent, PointerEventInit, EventHandlers)> = None;    let _ = EventRouter::new();}
use sigil::app::ResizeDirection;use sigil::app::WindowCommand;use sigil::events::EventHandlers;use sigil::events::EventRouter;use sigil::events::FileDropEvent;use sigil::events::FileDropPhase;use sigil::events::FocusIntent;use sigil::events::ImeEvent;use sigil::events::PhysicalKey;use sigil::events::PointerEventInit;use sigil::events::ScrollDelta;use sigil::events::ScrollEvent;use sigil::events::ScrollPhase;use sigil::events::ShellEvent;use sigil::events::WindowEvent;use sigil::events::request_window_command;use sigil::geometry::Dim;use sigil::geometry::LogicalSize;use sigil::prelude::*; fn tree() -> impl IntoNode {  let save = Shortcut::ctrl(    LogicalKey::character("s"),  );  let quit = Shortcut::new(    LogicalKey::character("q"),    ModifiersState::empty(),  );  let root = container()    .focusable(true)    .key(      save,      |event: &mut KeyEvent| {        event.stop_propagation()      },    )    .key(      Shortcut::plain(Key::Escape),      |_| sigil::request_exit(),    )    .key_capture(quit, |_| {      sigil::request_exit()    })    .shortcut(      Shortcut::ctrl(        LogicalKey::character("o"),      ),      |_| drop(()),    )    .key_any(|event| {      drop(        event.phase == KeyPhase::Down          && event.text.is_some(),      )    })    .key_capture_any(|event| {      drop(matches!(        event.key,        LogicalKey::Named(Key::Enter)      ))    })    .pointer_down(      |event: &mut PointerEvent| {        drop(event)      },    )    .on_scroll(      |event: &mut ScrollEvent| {        drop(event)      },    )    .file_drop(      |event: &FileDropEvent| {        drop(event)      },    )    .on_ime(|event: &ImeEvent| {      drop(matches!(        event,        ImeEvent::Commit(_)      ))    })    .on_added(|_, id| {      request_focus(id)    });  request_window_command(    WindowCommand::DragResize(      ResizeDirection::South,    ),  );  root} fn main() {  let _ = tree;  let _ = (    PointerKind::Mouse,    PointerPhase::Down,    MouseButton::Left,    MouseButtons::LEFT,  );  let _ = (    ScrollDelta::Lines(Point {      x: 0.0,      y: 1.0,    }),    ScrollPhase::Moved,    FileDropPhase::Dropped,  );  let _ = (    FocusIntent::Down,    PhysicalKey::KeyA,    Size {      width: Dim::MinContent,      height: Dim::Fixed(1.0),    },  );  let _ = LogicalSize {    width: 80.0,    height: 24.0,  };  let _: Option<(    ShellEvent,    WindowEvent,    PointerEventInit,    EventHandlers,  )> = None;  let _ = EventRouter::new();}

Style

NameSignaturePurpose
NodeStyleExttheme, tone, focus_ring, presence(Signal<bool>, AnimationConfig), animate, visible_when(impl Reactive<bool>), paint_when(impl Reactive<bool>, |s| ..)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.
Paintbg(c), background_gradient(g), text_color(c), border_color(c), border_w(px), border_top/right/bottom/left(px), rounded(Radius), shadow(Elevation), opacity(f32), font_size(f32), font_weight(u16), font_italic(bool), font_family(FontFamily), line_height_px(px), letter_spacing_em(em), tabular_nums(bool), underline(), line_through(), transition(id), duration(ms)Typed paint on nodes, text, widget builders, and state closures. c is impl Into<ColorOrToken>. Sealed.
StateVariantsfn rest(f), hover(f), focus(f), pressed(f), disabled_style(f); f: FnOnce(StateStyleBuilder) -> StateStyleBuilderPaint per interaction state. Works on a plain node, a text node, and a widget. Sealed.
Tokenenum Token { Accent, Surface, OnSurface, Border, .. }A theme color. Pass it to bg, text_color, or border_color.
Radiusenum Radius { None, Sm, Base, Md, Lg, Full }Corner radius from the theme: 2, 4, 6, 8, and 9999 px. 0 on a character grid.
Elevationenum Elevation { Sm, Base, Md, Lg, Xl }Shadow depth from the theme.
ControlSizeenum ControlSize { Compact, Default, Wide, Grow }Size step of a control, as in button(..).size(ControlSize::Compact).
FontFamilyenum FontFamily { Sans, Mono, Serif, Icon, Display }Font family for font_family.
Rgba8struct Rgba8 { r, g, b, a: u8 }An 8-bit RGBA color.
ColorAtomenum ColorAtom { Rgba8(Rgba8), ThemeRef(ColorKey) }A color or a theme color key.
Token::scale / Token::scale_stepfn scale(ScaleRole, u8) -> Option<Token>, fn scale_step(self) -> Option<(ScaleRole, u8)>Map a scale role and step 1..=12 to its token and back.
ThemeTheme::light(), Theme::dark(), Theme::console_dark(); with_direction(Direction), with_locale(Locale), with_strings(Strings)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::Directionenum 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.
style::Locale, style::DateOrderstruct Locale { decimal, group, group_size, zero, date_order, date_separator }; Locale::en(), de(), ar(), new(decimal, group), with_date(order, sep), with_zero(char), with_group_size(u8); parse_number, format_number, parse_date, format_date; `Locale::from_name("en""de""ar"); enum DateOrder { Ymd, Dmy, Mdy }, DateOrder::from_name`Number and date rules as data. Locale::default() is . decimals, no grouping, and year-month-day with -.
style::Strings, style::StringKeystruct 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_colorfn resolve_color(&self, key: ColorKey) -> Rgba8Resolve 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.
Theme::colorfn color(&self, token: Token) -> Rgba8resolve_color for a built-in token.
Theme::register_token / with_tokenfn register_token(&mut self, name: &str, value: ThemeValue) -> Option<ThemeValue>Set a runtime override. A built-in token name also updates the matching base color field.
Theme::with_theme_tokensfn with_theme_tokens(self, tokens: &phf::Map<&'static str, ThemeValue>) -> SelfFill the theme table layer from static data.
Toneenum Tone { Neutral, Primary, Info, Success, Warn, Error }; token(step: u8) -> Token, shade(), fill(), solid()Semantic color family. token returns the tone's color-scale step (1–12); shade is step 4 (tinted background), fill step 9 (solid fill), solid step 11 (text and strokes).
FocusRingFocusRing::static_visible(bool); theme_color(Token)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.

use sigil::style::ColorOrToken;use sigil::style::NumericAtomKind;use sigil::style::StyleState;use sigil::style::ThemeValue;use sigil::prelude::*; fn tree() -> impl IntoNode {    let card = container()        .layout(LayoutStyle::default().padding(8.0).margin_x(16.0).gap_y(4.0))        .bg(Rgba8 { r: 20, g: 20, b: 30, a: 255 })        .rounded(Radius::Base)        .shadow(Elevation::Md)        .border_w(1)        .border_color(Token::Border)        .hover(|s| s.bg(Token::SurfaceHover))        .disabled_style(|s| s.opacity(0.5))        .child(text("Title").font_size(14.0).font_weight(600).text_color(Token::OnSurface))        .child(text("42").font_family(FontFamily::Mono).tabular_nums(true));    let _ = (ColorOrToken::from(Token::Accent), Token::Accent.color(), ThemeValue::Ms(150));    let _ = (StyleState { disabled: false, hovered: true, pressed: false, focused: false }, NumericAtomKind::Opacity);    let theme = Theme::dark();    let node = container().tone(Tone::Primary).focus_ring(FocusRing::static_visible(true));    fragment().child(node.theme(theme)).child(card)} fn main() {    let _ = tree;    fn _traits<T: Paint + StateVariants>(_: T) {}    fn _node<T: NodeStyleExt>(_: T) {}}
use sigil::prelude::*;use sigil::style::ColorOrToken;use sigil::style::NumericAtomKind;use sigil::style::StyleState;use sigil::style::ThemeValue; fn tree() -> impl IntoNode {  let card = container()    .layout(      LayoutStyle::default()        .padding(8.0)        .margin_x(16.0)        .gap_y(4.0),    )    .bg(Rgba8 {      r: 20,      g: 20,      b: 30,      a: 255,    })    .rounded(Radius::Base)    .shadow(Elevation::Md)    .border_w(1)    .border_color(Token::Border)    .hover(|s| {      s.bg(Token::SurfaceHover)    })    .disabled_style(|s| s.opacity(0.5))    .child(      text("Title")        .font_size(14.0)        .font_weight(600)        .text_color(Token::OnSurface),    )    .child(      text("42")        .font_family(FontFamily::Mono)        .tabular_nums(true),    );  let _ = (    ColorOrToken::from(Token::Accent),    Token::Accent.color(),    ThemeValue::Ms(150),  );  let _ = (    StyleState {      disabled: false,      hovered: true,      pressed: false,      focused: false,    },    NumericAtomKind::Opacity,  );  let theme = Theme::dark();  let node = container()    .tone(Tone::Primary)    .focus_ring(      FocusRing::static_visible(true),    );  fragment()    .child(node.theme(theme))    .child(card)} fn main() {  let _ = tree;  fn _traits<    T: Paint + StateVariants,  >(    _: T,  ) {  }  fn _node<T: NodeStyleExt>(_: T) {}}

Animation

NameSignaturePurpose
use sigil::animation::AnimationDirection;use sigil::animation::AnimationFill;use sigil::animation::CubicBezier;use sigil::animation::Easing;use sigil::animation::Keyframe;use sigil::animation::Keyframes;use sigil::animation::SpringPreset;use sigil::animation_runtime::AnimationConfig;use sigil::animation_runtime::Animator;use sigil::animation_runtime::MotionPrefs;use sigil::animation_runtime::Playback;use sigil::animation_runtime::clock;use sigil::style::NumericAtomKind;use sigil::prelude::*;use std::time::Duration; fn tree() -> impl IntoNode {    let opacity = signal(0.0_f32);    let _ = Animator::new(opacity, AnimationConfig::Spring { preset: SpringPreset::Snappy });    let easing = Easing::Bezier(CubicBezier::new(0.4, 0.0, 0.2, 1.0));    let _ = AnimationConfig::Tween { ms: 200, easing };    let frames = Keyframes::new([Keyframe::new(0.0, 0.0), Keyframe::new(1.0, 1.0)], Duration::from_millis(300));    let _ = (AnimationDirection::Alternate, AnimationFill::Forwards, MotionPrefs::reduced());    let _ = Playback::new(opacity, frames);    let _seconds: Signal<f64> = clock();    container().animate(NumericAtomKind::Opacity, opacity)} fn main() {    let _ = tree;}
use sigil::animation::AnimationDirection;use sigil::animation::AnimationFill;use sigil::animation::CubicBezier;use sigil::animation::Easing;use sigil::animation::Keyframe;use sigil::animation::Keyframes;use sigil::animation::SpringPreset;use sigil::animation_runtime::AnimationConfig;use sigil::animation_runtime::Animator;use sigil::animation_runtime::MotionPrefs;use sigil::animation_runtime::Playback;use sigil::animation_runtime::clock;use sigil::prelude::*;use sigil::style::NumericAtomKind;use std::time::Duration; fn tree() -> impl IntoNode {  let opacity = signal(0.0_f32);  let _ = Animator::new(    opacity,    AnimationConfig::Spring {      preset: SpringPreset::Snappy,    },  );  let easing =    Easing::Bezier(CubicBezier::new(      0.4, 0.0, 0.2, 1.0,    ));  let _ = AnimationConfig::Tween {    ms: 200,    easing,  };  let frames = Keyframes::new(    [      Keyframe::new(0.0, 0.0),      Keyframe::new(1.0, 1.0),    ],    Duration::from_millis(300),  );  let _ = (    AnimationDirection::Alternate,    AnimationFill::Forwards,    MotionPrefs::reduced(),  );  let _ =    Playback::new(opacity, frames);  let _seconds: Signal<f64> = clock();  container().animate(    NumericAtomKind::Opacity,    opacity,  )} fn main() {  let _ = tree;}

Widgets: controls and fields

NameSignaturePurpose
buttonfn button(label: impl Into<TextContent>) -> ButtonBuilderA push button.
icon_buttonfn icon_button(glyph: impl Into<ButtonGlyph>, activate: impl Fn() + 'static) -> ButtonBuilderA button that shows one glyph: text or an Icon. An icon's name is the accessible name.
checkboxfn checkbox(checked: Signal<bool>) -> CheckboxBuilderA checkbox.
toggleconst fn toggle(on: Signal<bool>) -> ToggleBuilderAn on/off switch.
radio_groupfn radio_group(selected: Signal<String>) -> RadioGroupBuilderA set of radio options; .label() and .labelled_by() name the group.
segmentedfn segmented(active: Signal<usize>, labels: Vec<String>) -> SegmentedBuilderA framed row of options where one is active; .label() names the group and .height() (WidgetLayoutExt) sets its height.
sliderfn slider(value: Signal<f32>, range: RangeInclusive<f32>) -> SliderBuilder; .label(text)A value slider. .label shows the text before the track and names the slider.
Orientationenum Orientation { Horizontal, Vertical }Axis of a slider or splitter.
text_fieldfn text_field(value: Signal<String>) -> TextFieldBuilder; .leading(node), .trailing(node), .clearable()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.
text_editfn text_edit(value: Signal<String>) -> TextEditBuilder; .autofocus(), .focus_when(Signal<u64>), .caret_rect(Signal<Option<Rect>>)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.
number_fieldfn number_field<T: NumericKind>(value: Signal<T>, range: RangeInclusive<T>) -> NumberFieldBuilder<T>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.
NumericKindtrait NumericKindNumber types that number_field accepts.
date_fieldfn date_field(value: Signal<Date>) -> DateFieldBuilderA date input.
Datestruct Date { year: i32, month: u8, day: u8 }; parse_in(&str, &Locale), render_in(&Locale)A calendar date. parse and render use Locale::default().
color_fieldfn color_field(value: Signal<Rgba8>) -> ColorFieldBuilderA color input.
fieldfn 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.
chipfn chip(label, tone: Tone) -> ChipBuilder; .dot(), .leading(node)A small tag. dot puts a dot in the chip's tone before the label, for status pills; leading puts any node, such as an icon, before it.
interactivefn interactive(inner: NodeBuilder) -> InteractiveBuilderMake any node hoverable, pressable, and focusable.
use sigil::kernel::TextBuilder;use sigil::widgets::ButtonBuilder;use sigil::widgets::CheckboxBuilder;use sigil::widgets::ChipBuilder;use sigil::widgets::DateFieldBuilder;use sigil::widgets::InteractiveBuilder;use sigil::widgets::NumberFieldBuilder;use sigil::widgets::RadioGroupBuilder;use sigil::widgets::SliderBuilder;use sigil::widgets::TextEditBuilder;use sigil::widgets::TextEditState;use sigil::widgets::TextFieldBuilder;use sigil::widgets::ToggleBuilder;use sigil::widgets::interaction::InteractionState;use sigil::prelude::*; fn tree() -> impl IntoNode {    let name = signal(String::new());    let on = signal(false);    let save: ButtonBuilder = button("Save").primary().activate(|| println!("saved"));    let close: ButtonBuilder = icon_button("x", || sigil::request_exit());    let _: (CheckboxBuilder, ToggleBuilder) = (checkbox(on), toggle(on));    let _: RadioGroupBuilder = radio_group(signal("a".to_string()));    let _: SliderBuilder = slider(signal(0.5), 0.0..=1.0);    let _ = Orientation::Vertical;    let _: TextEditBuilder = text_edit(signal(String::new()));    let _ = TextEditState::new(name, signal(0));    let _: NumberFieldBuilder<i32> = number_field(signal(3_i32), 0..=10);    let _: DateFieldBuilder = date_field(signal(Date { year: 2026, month: 1, day: 1 }));    let _ = (color_field(signal(Rgba8 { r: 0, g: 0, b: 0, a: 255 })), field("Name", text_field(name)));    let checked = field("Name", text_field(name)).error(move || name.with(|n| n.is_empty().then(|| "Required".to_string())));    let _: ChipBuilder = chip("beta", Tone::Info);    let _: (ChipBuilder, TextBuilder) = (chip("3", Tone::Error), text("Label").nowrap());    let _: InteractiveBuilder = interactive(container());    let _ = InteractionState::new(true);    let _: Option<TextFieldBuilder> = None;    fn _numeric<T: NumericKind>() {}    container().child(checked).child(save).child(close)} fn main() {    let _ = tree;}
use sigil::kernel::TextBuilder;use sigil::prelude::*;use sigil::widgets::ButtonBuilder;use sigil::widgets::CheckboxBuilder;use sigil::widgets::ChipBuilder;use sigil::widgets::DateFieldBuilder;use sigil::widgets::InteractiveBuilder;use sigil::widgets::NumberFieldBuilder;use sigil::widgets::RadioGroupBuilder;use sigil::widgets::SliderBuilder;use sigil::widgets::TextEditBuilder;use sigil::widgets::TextEditState;use sigil::widgets::TextFieldBuilder;use sigil::widgets::ToggleBuilder;use sigil::widgets::interaction::InteractionState; fn tree() -> impl IntoNode {  let name = signal(String::new());  let on = signal(false);  let save: ButtonBuilder =    button("Save")      .primary()      .activate(|| println!("saved"));  let close: ButtonBuilder =    icon_button("x", || {      sigil::request_exit()    });  let _: (    CheckboxBuilder,    ToggleBuilder,  ) = (checkbox(on), toggle(on));  let _: RadioGroupBuilder =    radio_group(signal(      "a".to_string(),    ));  let _: SliderBuilder =    slider(signal(0.5), 0.0..=1.0);  let _ = Orientation::Vertical;  let _: TextEditBuilder =    text_edit(signal(String::new()));  let _ =    TextEditState::new(name, signal(0));  let _: NumberFieldBuilder<i32> =    number_field(signal(3_i32), 0..=10);  let _: DateFieldBuilder =    date_field(signal(Date {      year: 2026,      month: 1,      day: 1,    }));  let _ = (    color_field(signal(Rgba8 {      r: 0,      g: 0,      b: 0,      a: 255,    })),    field("Name", text_field(name)),  );  let checked =    field("Name", text_field(name))      .error(move || {        name.with(|n| {          n.is_empty().then(|| {            "Required".to_string()          })        })      });  let _: ChipBuilder =    chip("beta", Tone::Info);  let _: (ChipBuilder, TextBuilder) = (    chip("3", Tone::Error),    text("Label").nowrap(),  );  let _: InteractiveBuilder =    interactive(container());  let _ = InteractionState::new(true);  let _: Option<TextFieldBuilder> =    None;  fn _numeric<T: NumericKind>() {}  container()    .child(checked)    .child(save)    .child(close)} fn main() {  let _ = tree;}

Widgets: choice, collections, and documents

NameSignaturePurpose
dropdownfn dropdown(selected: Signal<usize>, options: Vec<String>) -> DropdownBuilderA select box. The trigger fills the width of its parent, like a form field; in a toolbar row give it .width(..).
comboboxfn combobox(state: Combobox) -> NodeBuilderA text input with a filtered list.
ComboboxCombobox::new(options: Vec<String>); selected_option() -> Option<String>, edit_query(text: &str), move_cursor(delta: i32)State of a combobox.
menufn menu(open: Signal<bool>) -> MenuBuilderA popup menu.
context_menufn context_menu(target, items: impl Fn() -> Vec<MenuItem>) -> NodeBuilderWraps target; a right click opens a menu of items() at the pointer.
MenuItemstruct MenuItem { label, shortcut, disabled, submenu_indicator }; MenuItem::new(label), shortcut(hint), disabled(bool), submenu(bool), activate(Fn())One menu entry. activate runs when the entry is pressed.
menu_barfn menu_bar() -> MenuBarBuilder; .fill()An in-window menu bar, as wide as its menus. fill makes it take the full width.
command_menufn command_menu() -> CommandMenuBuilderA 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.
fuzzy_scorefn fuzzy_score(query: &str, text: &str) -> Option<FuzzyMatch>Rank text against a query. A lower score is a better match.
tablefn table<Row>(state: TableState<Row>) -> TableBuilder<Row>A sortable, filterable table.
TableStateTableState::new(rows: Vec<Row>, columns: Vec<TableColumn<Row>>); TableState::identified(rows, columns) for Row: Identifiable; replace_rows(impl Into<Arc<Vec<Row>>>), row_eq(self, impl Fn(&Row, &Row) -> bool) -> Self, selected_row() -> Option<Row>, clear_selection(), show_column(id: &'static str), reset_columns(); sort: sort(id, SortDir), toggle_sort(id), cycle_sort(), reverse_sort(), sort_key() -> Signal<Option<SortKey>>; search: quick_filter() -> Signal<String>; view: visible() -> Signal<Rc<Vec<u32>>>, rows() -> Signal<Arc<Vec<Row>>>; selection: selection() -> Signal<Rc<HashSet<u32>>>, selected_index() -> Option<u32>, select_only(row), select_by(delta: i32), toggle_selected(row), select_range_to(row); columns: columns(), visible_columns(), hide_column(id), show_all_columns(), move_column(from, to), column_layout() -> Signal<Rc<ColumnLayout>>, column_width(id) -> Option<f32>, pin_column_width(id, px), clear_column_width(id)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.
TableColumnTableColumn::new(id: &'static str, title); sort_by(Fn(&Row) -> K) with K: Ord, sortable(Fn(&Row, &Row) -> Ordering), filterable(Fn(&Row, &str) -> bool), cell(Fn(&Row) -> N) with N: IntoNode, numeric(), align(ColAlign), width(ColWidth), min_width(px)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.
ColWidthenum ColWidth { Fixed(f32), Fraction(f32) }Column width.
Densityenum Density { Grid, Compact, Default }Row density of a table.
Identifiabletrait Identifiable { type Id; fn id(&self) -> Self::Id; }Stable row identity.
virtual_listfn 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.
SelectionModeenum SelectionMode { None, Single, Multi, Extend }Selection mode of a list.
list_rowfn list_row(selected: bool, title, detail) -> NodeBuilderOne row of a list.
list_row_withfn list_row_with(selected: bool, title, slots: ListRowSlots) -> NodeBuilderA list row with a marker, status, and columns. With slots.activate set, the row takes keyboard focus and runs it on Enter, Space, or a click.
ListRowSlotsstruct ListRowSlots { depth, disclosure, marker, marker_tone, leading, status, status_tone, badge, columns, shrink, title_width, indent, tone, activate: Option<Rc<dyn Fn()>> }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).
Disclosureenum Disclosure { None, Leaf, Collapsed, Expanded }The tree chevron slot of a list row.
kv_gridfn kv_grid(rows: impl IntoIterator<Item = (impl Into<TextContent>, impl Into<TextContent>)>) -> NodeBuilderA two-column key/value grid. Keys and values can be reactive.
kv_rowfn kv_row(label, value: impl IntoNode + 'static) -> NodeBuilderOne key/value row.
tabsfn tabs() -> TabsBuilder; .tab(label, component), .active(Signal<usize>)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.
code_editfn code_edit(lines: Signal<Vec<String>>, caret: Signal<(usize, usize)>) -> CodeEditBuilderA code editor with built-in text_edit editing.
highlightfn highlight(language: &str, source: &str) -> Vec<Vec<Highlight>>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.
hl_spansfn hl_spans(language: &str, source: &str) -> Vec<Vec<HlSpan>>highlight as column spans for code_edit(..).highlights(..).
markdownfn markdown(source: Signal<String>) -> NodeBuilderRendered markdown. Each link is exposed as a Link node with its URL and on-screen area, and a click on it reaches the nearest link handler.
markdown_inlinefn markdown_inline(source: &str) -> TextBuilderOne wrapped paragraph with inline markdown spans.
markdown_editfn markdown_edit(source: Signal<String>) -> MarkdownEditBuilderA markdown editor with preview.
htmlfn html(source: Signal<String>) -> NodeBuilderRendered HTML subset.
mermaidfn mermaid(source: impl Reactive<String>) -> NodeBuilderA rendered mermaid diagram. A signal or closure source draws the diagram again when it changes.
difffn diff(patch: impl DiffSource + 'static) -> DiffBuilder; .select(Signal<Selection>)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.
Patch, Hunk, Line, LineKind, LineIdPatch::parse(&str) -> Patch; struct Patch { hunks, trailer }, line(LineId), changes(), hunk_changes(usize); struct Hunk { meta, path, header, old_start, new_start, lines }; struct Line { kind, text, old, new }; enum LineKind { Context, Removed, Added, Note }The parsed unified diff that diff renders.
Selection, DiffSourcestruct Selection { hunks: BTreeSet<usize>, lines: BTreeSet<LineId>, .. }, contains, select_hunk, select_line; trait DiffSource for text, Patch, and Signal<Patch>What the user selected in a diff, and the sources diff accepts.
DiffViewenum DiffView { Split, Unified }Diff view: side-by-side or unified rows.
terminalfn terminal(lines: Signal<Vec<String>>, on_input: impl Fn(String) + 'static) -> NodeBuilderA terminal transcript with an input line.
use sigil::widgets::CodeEditBuilder;use sigil::widgets::ColAlign;use sigil::widgets::CommandMenuBuilder;use sigil::widgets::DiffBuilder;use sigil::widgets::DropdownBuilder;use sigil::widgets::FuzzyMatch;use sigil::widgets::Highlight;use sigil::widgets::HlSpan;use sigil::widgets::MenuBarBuilder;use sigil::widgets::MenuBuilder;use sigil::widgets::ScrollAnchor;use sigil::widgets::SelectionState;use sigil::widgets::SubmenuBuilder;use sigil::widgets::TableBuilder;use sigil::widgets::TabsBuilder;use sigil::widgets::VirtualListBuilder;use sigil::prelude::*; #[derive(Clone)]struct File { name: String, size: u64 } fn tree() -> impl IntoNode {    let _: DropdownBuilder = dropdown(signal(0), vec!["One".into(), "Two".into()]);    let _ = combobox(Combobox::new(vec!["red".into(), "blue".into()]));    let _: MenuBuilder = menu(signal(false));    let _: Option<(MenuItem, SubmenuBuilder)> = None;    let _: (MenuBarBuilder, CommandMenuBuilder) = (menu_bar(), command_menu());    let _: Option<FuzzyMatch> = fuzzy_score("sv", "save file");    let size = TableColumn::new("size", "Size").numeric().width(ColWidth::Fixed(80.0)).align(ColAlign::End);    let columns = vec![TableColumn::new("name", "Name").cell(|f: &File| text(f.name.clone()).nowrap()), size];    let files: TableBuilder<File> = table(TableState::new(vec![File { name: "a".into(), size: 1 }], columns));    let _ = (Density::Compact, ScrollAnchor::Bottom, SelectionState::new(SelectionMode::Single));    let list: VirtualListBuilder<String, _> = virtual_list(vec!["a".to_string()], |_, s: &String| list_row(false, s.clone(), ""));    let (scroll, max_scroll) = (signal(0.0_f32), signal(0.0_f32));    let list = list.measured().estimate(rows(2.0)).scroll_bind(scroll).max_scroll_bind(max_scroll);    let list = list.content_height_bind(signal(0.0)).follow_row(signal(0));    let _ = list_row_with(true, "Inbox", ListRowSlots { marker: Some("*".into()), ..ListRowSlots::default() });    let _ = (kv_grid([("Name", "Sigil")]), kv_row("Size", text("1 KB")));    let _: TabsBuilder = tabs().tab("A", || text("a")).tab("B", || text("b"));    let _: CodeEditBuilder = code_edit(signal(vec!["fn main() {}".into()]), signal((0, 0)));    let _ = HlSpan { start: 0, end: 2, token: "keyword" };    let _: Vec<Vec<Highlight>> = highlight("rust", "fn main() {}");    let _ = code_edit(signal(vec!["let x = 1;".into()]), signal((0, 0))).highlights(signal(hl_spans("rust", "let x = 1;")));    let doc = signal("# Title".to_string());    let _ = (markdown(doc), markdown_edit(doc), html(signal("<b>x</b>".into())), mermaid("graph TD; A-->B"));    let _: DiffBuilder = diff("--- a\n+++ b\n").view(DiffView::Unified);    let _ = terminal(signal(Vec::new()), |line| println!("{line}"));    fn _id<T: Identifiable>() {}    container().child(files).child(list)} fn main() {    let _ = tree;}
use sigil::prelude::*;use sigil::widgets::CodeEditBuilder;use sigil::widgets::ColAlign;use sigil::widgets::CommandMenuBuilder;use sigil::widgets::DiffBuilder;use sigil::widgets::DropdownBuilder;use sigil::widgets::FuzzyMatch;use sigil::widgets::Highlight;use sigil::widgets::HlSpan;use sigil::widgets::MenuBarBuilder;use sigil::widgets::MenuBuilder;use sigil::widgets::ScrollAnchor;use sigil::widgets::SelectionState;use sigil::widgets::SubmenuBuilder;use sigil::widgets::TableBuilder;use sigil::widgets::TabsBuilder;use sigil::widgets::VirtualListBuilder; #[derive(Clone)]struct File {  name: String,  size: u64,} fn tree() -> impl IntoNode {  let _: DropdownBuilder = dropdown(    signal(0),    vec!["One".into(), "Two".into()],  );  let _ =    combobox(Combobox::new(vec![      "red".into(),      "blue".into(),    ]));  let _: MenuBuilder =    menu(signal(false));  let _: Option<(    MenuItem,    SubmenuBuilder,  )> = None;  let _: (    MenuBarBuilder,    CommandMenuBuilder,  ) = (menu_bar(), command_menu());  let _: Option<FuzzyMatch> =    fuzzy_score("sv", "save file");  let size =    TableColumn::new("size", "Size")      .numeric()      .width(ColWidth::Fixed(80.0))      .align(ColAlign::End);  let columns = vec![    TableColumn::new("name", "Name")      .cell(|f: &File| {        text(f.name.clone()).nowrap()      }),    size,  ];  let files: TableBuilder<File> =    table(TableState::new(      vec![File {        name: "a".into(),        size: 1,      }],      columns,    ));  let _ = (    Density::Compact,    ScrollAnchor::Bottom,    SelectionState::new(      SelectionMode::Single,    ),  );  let list: VirtualListBuilder<    String,    _,  > = virtual_list(    vec!["a".to_string()],    |_, s: &String| {      list_row(false, s.clone(), "")    },  );  let (scroll, max_scroll) =    (signal(0.0_f32), signal(0.0_f32));  let list = list    .measured()    .estimate(rows(2.0))    .scroll_bind(scroll)    .max_scroll_bind(max_scroll);  let list = list    .content_height_bind(signal(0.0))    .follow_row(signal(0));  let _ = list_row_with(    true,    "Inbox",    ListRowSlots {      marker: Some("*".into()),      ..ListRowSlots::default()    },  );  let _ = (    kv_grid([("Name", "Sigil")]),    kv_row("Size", text("1 KB")),  );  let _: TabsBuilder = tabs()    .tab("A", || text("a"))    .tab("B", || text("b"));  let _: CodeEditBuilder = code_edit(    signal(vec!["fn main() {}".into()]),    signal((0, 0)),  );  let _ = HlSpan {    start: 0,    end: 2,    token: "keyword",  };  let _: Vec<Vec<Highlight>> =    highlight("rust", "fn main() {}");  let _ = code_edit(    signal(vec!["let x = 1;".into()]),    signal((0, 0)),  )  .highlights(signal(hl_spans(    "rust",    "let x = 1;",  )));  let doc =    signal("# Title".to_string());  let _ = (    markdown(doc),    markdown_edit(doc),    html(signal("<b>x</b>".into())),    mermaid("graph TD; A-->B"),  );  let _: DiffBuilder =    diff("--- a\n+++ b\n")      .view(DiffView::Unified);  let _ = terminal(    signal(Vec::new()),    |line| println!("{line}"),  );  fn _id<T: Identifiable>() {}  container().child(files).child(list)} fn main() {  let _ = tree;}

Widgets: frame, overlays, and display

NameSignaturePurpose
app_shellfn app_shell(top, work, status, modal: Option<impl IntoNode>) -> NodeBuilderTop bar, work area, status bar, and modal slot.
sidebarfn sidebar(child: impl IntoNode + 'static) -> SidebarBuilderA side column. Set its width with .width(..).
status_barfn status_bar<I: IntoIterator>(children: I) -> NodeBuilderA status line.
panelfn panel() -> PanelBuilderA titled panel.
cardfn card(child: impl IntoNode + 'static) -> CardBuilder; .selected(impl Reactive<bool>), .activate(f)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.
statfn stat(label, value) -> StatBuilder; .delta(text, Tone), .caption(text), .trend(values), .range(low, high), .tone(Tone)A KPI tile in card chrome: a label, a large value, and an optional toned change line, caption, and sparkline trend. Label and value can be reactive.
treefn tree<K: TreeKey>(nodes: impl Reactive<Vec<TreeNode<K>>>) -> TreeBuilder<K>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.
sheetfn sheet(show: Signal<bool>) -> ModalBuilderA panel that slides in from a side.
modalfn modal(show: Signal<bool>) -> ModalBuilderA modal dialog. While it is open and traps focus, it is marked modal and the rest of the page is hidden from assistive technology.
ModalBuilderstruct ModalBuilder; close_button(bool); ModalBuilder::new(Signal<bool>), title(text), child(impl IntoNode), footer(impl IntoNode), actions(cancel, confirm), side(Side), escape_closes(bool), dismiss_on_backdrop(bool), trap(bool); width with WidgetLayoutExt::widthBuilder 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.
SortDirenum SortDir { Ascending, Descending }Direction of a table sort.
SortKeystruct SortKey { column: &'static str, dir: SortDir }Table sort column and direction.
SubmitKeyenum SubmitKey { CtrlEnter, Enter }; Default is CtrlEnterThe key that runs TextEditBuilder::submit. With Enter, Shift+Enter inserts a new line.
Sideenum Side { Left, Right, Bottom }Edge of a sheet.
splitterfn splitter(orientation: Orientation) -> SplitterBuilderResizable panes.
scrollfn scroll(content: NodeBuilder) -> ScrollBuilderA scroll area. It measures its content; .extent(f32 or Signal<f32>) sets a known content height instead.
section_labelfn section_label(title) -> NodeBuilderA section heading row.
hint_barfn hint_bar(keys, right) -> NodeBuilderA key hint row.
hint_overlayfn hint_overlay(hints: &[(&str, &str)]) -> HintOverlayBuilderAn overlay that lists key bindings.
notice_bandfn notice_band(body, tone: Tone) -> NodeBuilderA full-width notice.
empty_statefn empty_state(title, body) -> NodeBuilderA placeholder for empty content.
spacerfn spacer() -> NodeBuilderFlexible empty space.
divider_horizontalfn divider_horizontal() -> NodeBuilderA horizontal divider.
divider_verticalfn divider_vertical() -> VerticalDivider; .height(px)A vertical divider that fills the height. height gives a fixed tick, such as between toolbar items.
surfacefn surface(key: u64) -> NodeBuilderA rectangle that the embed host draws.
tooltipfn tooltip(label: impl Into<String>) -> TooltipBuilderA hover tooltip.
toastfn toast(message: Signal<Option<String>>) -> NodeBuilderOne transient message.
toast_queuefn toast_queue(queue: ToastQueue) -> NodeBuilderA stack of transient messages.
ToastQueueToastQueue::new(); info, success, warning, errorQueue of toast messages.
progressfn progress(value: Signal<f32>, max: f32) -> ProgressBuilder; .label(text)A progress bar. .label shows the text beside the bar and names it; without a label it is named "Progress".
gaugefn gauge(value: Signal<f32>) -> GaugeBuilderA labelled meter bar that shows a value against a maximum.
chartfn chart(values: impl Reactive<Vec<f32>>) -> ChartBuilder; ChartBuilder::candles(rows: impl Reactive<Vec<(f32, f32, f32, f32)>>), .x_range(Signal<Range<f32>>), .crosshair()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.
sparklinefn sparkline(values: impl Reactive<Vec<f32>>) -> SparklineBuilderA sparkline. By default, one block glyph per value on one text row. A signal or closure source draws the graph again when it changes.
heatmapfn heatmap<F: Fn(usize, usize) -> Rgba8>(grid_w, grid_h, color: F) -> NodeBuilderA grid of colored cells, drawn as one image that fills its box.
dotfn dot(tone: Tone) -> DotBuilderA status dot.
avatarfn avatar(initials) -> NodeBuilderInitials in a circle.
spinnerfn spinner() -> NodeBuilderA busy indicator named "Loading".
iconfn icon(glyph: impl IntoIconSource) -> IconBuilderAn icon: a bundled Icon, such as icon(Icon::Folder), or a text glyph.
Iconenum Icon (105 variants); Icon::ALL, name(), svg()The bundled Lucide icon set (ISC). name is the kebab-case file name and svg the SVG source (feature scene).
pathconst fn path(width: u32, height: u32) -> PathNodeA vector path.
widgets::canvas, widgets::CanvasBuilderfn canvas(record: impl Fn(&mut SceneBuilder, Rect) + 'static) -> CanvasBuilder; redraw_on(Signal<u64>), layout(LayoutStyle)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.
widgets::PathNode::drawfn draw(self, scene: &mut SceneBuilder, destination: Rect, theme: &Theme)Record a vector path into a canvas scene. It rasterizes again at the drawn size.
PathNodemove_to, line_to, quad_to, cubic_to, close, fill, fill_linear(start, end, stops: Vec<(f32, Rgba8)>), fill_radial(center, radius, stops), stroke, non_scaling_strokeBuilder 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.
image_rgbafn image_rgba(width: u32, height: u32, rgba: Vec<u8>) -> Option<ImageBuilder>An image from RGBA bytes.
image_bytesfn image_bytes(encoded: &[u8]) -> Option<ImageBuilder>An image from PNG or JPEG bytes (feature image-decode).
use sigil::kernel::ImageBuilder;use sigil::widgets::ChartBuilder;use sigil::widgets::ChartMark;use sigil::widgets::DotBuilder;use sigil::widgets::GaugeBuilder;use sigil::widgets::HintOverlayBuilder;use sigil::widgets::IconBuilder;use sigil::widgets::icon_svg;use sigil::widgets::spinner_frame;use sigil::widgets::ModalBuilder;use sigil::widgets::PanelBuilder;use sigil::widgets::PathCmd;use sigil::widgets::PathColor;use sigil::widgets::PathFill;use sigil::widgets::ProgressBuilder;use sigil::widgets::ScrollBuilder;use sigil::widgets::SparkMark;use sigil::widgets::SparklineBuilder;use sigil::widgets::SplitterBuilder;use sigil::widgets::ToastEntry;use sigil::widgets::ToastLevel;use sigil::widgets::TooltipBuilder;use sigil::prelude::*; fn tree() -> impl IntoNode {    let open = signal(false);    let queue = ToastQueue::new();    queue.info("Saved");    let _: Option<ToastEntry> = None;    let dialog: ModalBuilder = modal(open);    let _: ModalBuilder = sheet(open);    let _ = Side::Right;    let _: SplitterBuilder = splitter(Orientation::Horizontal);    let _: ScrollBuilder = scroll(container()).extent(400.0_f32);    let _: PanelBuilder = panel();    let _: HintOverlayBuilder = hint_overlay(&[("q", "quit")]);    let _ = (section_label("Files"), hint_bar("q quit", "v0.1"), notice_band("Offline", Tone::Warn));    let _ = (empty_state("No files", "Add one"), divider_horizontal(), divider_vertical());    let _ = (surface(1), toast(signal(None)), toast_queue(queue), ToastLevel::Error);    let _: TooltipBuilder = tooltip("Help");    let _: (ProgressBuilder, GaugeBuilder) = (progress(signal(0.3), 1.0).tone(Tone::Warn), gauge(signal(0.5)));    let _: ChartBuilder = chart([1.0, 2.0, 3.0]).line();    let _: SparklineBuilder = sparkline([1.0, 4.0, 2.0]).range(0.0, 5.0).tone(Tone::Warn);    let _: SparklineBuilder = sparkline([1.0, 4.0]).mark(SparkMark::Braille).rows(3).tones([None, Some(Tone::Error)]);    let _ = (ChartMark::Bar, PathCmd::Close, PathFill::Solid(Rgba8 { r: 0, g: 0, b: 0, a: 255 }));    let _ = heatmap(4, 4, |x, y| Rgba8 { r: (x * 60) as u8, g: (y * 60) as u8, b: 0, a: 255 });    let _: DotBuilder = dot(Tone::Success);    let _ = (avatar("TG"), spinner(), spinner_frame(3));    let _: IconBuilder = icon("*");    let _: IconBuilder = icon_svg(sigil::icons::builtin::GEAR_SVG).tone(Tone::Primary);    let _: PathNode = path(16, 16).move_to(0.0, 0.0).line_to(16.0, 16.0).stroke(PathColor::Token(sigil::style::Token::Gray11), 1.5);    let _: PathNode = path(16, 16).move_to(0.0, 0.0).line_to(16.0, 16.0).close().fill(Rgba8 { r: 0, g: 0, b: 0, a: 255 });    let _: Option<ImageBuilder> = image_rgba(1, 1, vec![0, 0, 0, 255]);    let _ = spacer();    let work = sidebar(card(text("Card"))).width(200.0);    app_shell(text("Top"), work, status_bar([text("Ready")]), Some(dialog))} #[cfg(feature = "image-decode")]fn decoded(bytes: &[u8]) -> Option<ImageBuilder> { image_bytes(bytes) } fn main() {    let _ = tree;}
use sigil::kernel::ImageBuilder;use sigil::prelude::*;use sigil::widgets::ChartBuilder;use sigil::widgets::ChartMark;use sigil::widgets::DotBuilder;use sigil::widgets::GaugeBuilder;use sigil::widgets::HintOverlayBuilder;use sigil::widgets::IconBuilder;use sigil::widgets::ModalBuilder;use sigil::widgets::PanelBuilder;use sigil::widgets::PathCmd;use sigil::widgets::PathColor;use sigil::widgets::PathFill;use sigil::widgets::ProgressBuilder;use sigil::widgets::ScrollBuilder;use sigil::widgets::SparkMark;use sigil::widgets::SparklineBuilder;use sigil::widgets::SplitterBuilder;use sigil::widgets::ToastEntry;use sigil::widgets::ToastLevel;use sigil::widgets::TooltipBuilder;use sigil::widgets::icon_svg;use sigil::widgets::spinner_frame; fn tree() -> impl IntoNode {  let open = signal(false);  let queue = ToastQueue::new();  queue.info("Saved");  let _: Option<ToastEntry> = None;  let dialog: ModalBuilder =    modal(open);  let _: ModalBuilder = sheet(open);  let _ = Side::Right;  let _: SplitterBuilder =    splitter(Orientation::Horizontal);  let _: ScrollBuilder =    scroll(container())      .extent(400.0_f32);  let _: PanelBuilder = panel();  let _: HintOverlayBuilder =    hint_overlay(&[("q", "quit")]);  let _ = (    section_label("Files"),    hint_bar("q quit", "v0.1"),    notice_band("Offline", Tone::Warn),  );  let _ = (    empty_state("No files", "Add one"),    divider_horizontal(),    divider_vertical(),  );  let _ = (    surface(1),    toast(signal(None)),    toast_queue(queue),    ToastLevel::Error,  );  let _: TooltipBuilder =    tooltip("Help");  let _: (    ProgressBuilder,    GaugeBuilder,  ) = (    progress(signal(0.3), 1.0)      .tone(Tone::Warn),    gauge(signal(0.5)),  );  let _: ChartBuilder =    chart([1.0, 2.0, 3.0]).line();  let _: SparklineBuilder =    sparkline([1.0, 4.0, 2.0])      .range(0.0, 5.0)      .tone(Tone::Warn);  let _: SparklineBuilder =    sparkline([1.0, 4.0])      .mark(SparkMark::Braille)      .rows(3)      .tones([None, Some(Tone::Error)]);  let _ = (    ChartMark::Bar,    PathCmd::Close,    PathFill::Solid(Rgba8 {      r: 0,      g: 0,      b: 0,      a: 255,    }),  );  let _ = heatmap(4, 4, |x, y| Rgba8 {    r: (x * 60) as u8,    g: (y * 60) as u8,    b: 0,    a: 255,  });  let _: DotBuilder =    dot(Tone::Success);  let _ = (    avatar("TG"),    spinner(),    spinner_frame(3),  );  let _: IconBuilder = icon("*");  let _: IconBuilder = icon_svg(    sigil::icons::builtin::GEAR_SVG,  )  .tone(Tone::Primary);  let _: PathNode = path(16, 16)    .move_to(0.0, 0.0)    .line_to(16.0, 16.0)    .stroke(      PathColor::Token(        sigil::style::Token::Gray11,      ),      1.5,    );  let _: PathNode = path(16, 16)    .move_to(0.0, 0.0)    .line_to(16.0, 16.0)    .close()    .fill(Rgba8 {      r: 0,      g: 0,      b: 0,      a: 255,    });  let _: Option<ImageBuilder> =    image_rgba(      1,      1,      vec![0, 0, 0, 255],    );  let _ = spacer();  let work =    sidebar(card(text("Card")))      .width(200.0);  app_shell(    text("Top"),    work,    status_bar([text("Ready")]),    Some(dialog),  )} #[cfg(feature = "image-decode")]fn decoded(  bytes: &[u8],) -> Option<ImageBuilder> {  image_bytes(bytes)} fn main() {  let _ = tree;}

Drag and drop

NameSignaturePurpose
DragDropExtfn drag_source(self, state, payload), fn drop_target(self, state, accepts, on_drop)Make a node a drag source or a drop target.
DragStateDragState::new()Shared state of one drag interaction.
drag_ghostfn drag_ghost<T, N>(state: DragState<T>, render: impl Fn(&T) -> N + 'static) -> NodeBuilderThe node that follows the pointer.
axis_dragfn axis_drag<S>(node, axis: Axis, snapshot, on_delta, on_end) -> NodeBuilderDrag along one axis.
use sigil::widgets::DRAG_THRESHOLD_PX;use sigil::widgets::DROP_TARGET_CLASS;use sigil::prelude::*;use sigil::widgets::Axis; fn tree() -> impl IntoNode {    let drag: DragState<u32> = DragState::new();    let source = container().drag_source(drag.clone(), 7);    let target = container().drop_target(drag.clone(), |n: &u32| *n > 0, |n| println!("{n}"));    let ghost = drag_ghost(drag, |n: &u32| text(n.to_string()));    let width = signal(200.0_f32);    let handle = axis_drag(container(), Axis::X, move || width.peek(), move |start, dx| width.set(start + dx), || {});    let _ = (DRAG_THRESHOLD_PX, DROP_TARGET_CLASS);    container().child(source).child(target).child(ghost).child(handle)} fn main() {    let _ = tree;}
use sigil::prelude::*;use sigil::widgets::Axis;use sigil::widgets::DRAG_THRESHOLD_PX;use sigil::widgets::DROP_TARGET_CLASS; fn tree() -> impl IntoNode {  let drag: DragState<u32> =    DragState::new();  let source = container()    .drag_source(drag.clone(), 7);  let target = container().drop_target(    drag.clone(),    |n: &u32| *n > 0,    |n| println!("{n}"),  );  let ghost =    drag_ghost(drag, |n: &u32| {      text(n.to_string())    });  let width = signal(200.0_f32);  let handle = axis_drag(    container(),    Axis::X,    move || width.peek(),    move |start, dx| {      width.set(start + dx)    },    || {},  );  let _ = (    DRAG_THRESHOLD_PX,    DROP_TARGET_CLASS,  );  container()    .child(source)    .child(target)    .child(ghost)    .child(handle)} fn main() {  let _ = tree;}

Module items

Public items outside the prelude. Import them by path.

NameSignaturePurpose
tasks::panic_messagefn panic_message(payload: &(dyn Any + Send)) -> &strText of a panic payload; "<non-string panic payload>" when it is not a string.
animation_runtime::install_animators_themedfn install_animators_themed(atoms: &[StyleAtom], state_style: StateStyle, component_id: ComponentId, theme: &Theme) -> AttachedAnimatorsLike install_animators, with token colors resolved against theme.
animation_runtime::AttachedColorAnimatorstruct AttachedColorAnimator { kind: ColorAtomKind, channels: [Signal<f32>; 4], animators: [Animator; 4] }One animated color atom: one signal and animator per RGBA channel.
animation_runtime::lerp_rgba8fn lerp_rgba8(a: Rgba8, b: Rgba8, t: f32) -> Rgba8Mix two sRGB colors in linear light. t is clamped to 0..=1.
animation_runtime::linear_channel_to_srgbfn linear_channel_to_srgb(v: f32) -> u8Encode a linear channel in 0..=1 as an sRGB byte.
a11y::RecordingBridgestruct RecordingBridge { pending_actions: VecDeque<(NodeId, ActionRequest)> }; new(), action(target, request), last_published(), published_count()An A11yBridge that records published trees and queues actions, for tests.
a11y::BoundsLookuptype BoundsLookup<'a> = &'a dyn Fn(NodeId) -> Option<Rect>Node bounds source for a11y::tree.
reactive::timeoutfn timeout(delay: Duration, callback: impl FnOnce() + 'static) -> IntervalIdRun callback once after delay. Cancelled with its owner or by sigil::reactive::cancel_interval.
reactive::next_interval_deadlinefn next_interval_deadline() -> Option<Instant>Earliest next fire time of the registered intervals and timeouts. An embed host loop sleeps until it.
AppConfig::inlineconst fn inline(self, yes: bool) -> SelfRun the terminal host in the normal screen below the prompt instead of the alternate screen.
AppConfig::modify_other_keysconst fn modify_other_keys(self, yes: bool) -> SelfTerminal 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 ~.
AppConfig::reduced_motionconst fn reduced_motion(self, reduced: bool) -> SelfOverride the OS reduced-motion setting for MotionPrefs.
AppConfig::clickconst fn click(self, click: hal::ClickConfig) -> SelfOverride the double-click interval and distance.
AppConfig::task_workersconst fn task_workers(self, workers: tasks::TaskWorkers) -> SelfSet the worker threads of the task runtime. Default Auto on every host.
events::ClickConfigstruct ClickConfig { interval: Duration, distance: f32 }; current(), set(config), is_repeat(&self, elapsed, from, to) -> boolDouble-click limits. Default 450 ms and 8 px; sigil::run takes the OS interval on macOS and GNOME.
AppConfig::terminal_hooksfn terminal_hooks(self, hooks: terminal::Hooks<'static>) -> SelfTerminal host hooks for sigil::run: external_events, after_frame, region_rows. The window host ignores them.
terminal::Hooks::region_rowsregion_rows: Option<Box<dyn FnMut() -> u16>>Height of the inline live region each frame, clamped to 1..=terminal rows. Used only with inline(true).
terminal::print_abovefn print_above(text: &str) -> io::Result<()>Write lines above the inline live region, into scrollback. Returns PrintAboveError in an io::Error when no inline host is live on this thread.
AppConfig::terminal_accessconst fn terminal_access(self, access: terminal::Access) -> SelfScreen-reader options for the terminal host. The window host ignores them.
terminal::Accessstruct Access { focus_cursor: FocusCursor, status: Duration }; Default is Follow and 5 sWhere 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::FocusCursorenum 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.
AppConfig::mouse_trackingconst fn mouse_tracking(self, tracking: terminal::MouseTracking) -> SelfMouse 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::MouseTrackingenum MouseTracking { Off, Clicks, Drags, Motion }; Default is DragsTerminal 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::resizableconst fn resizable(self, yes: bool) -> SelfLet the user resize the window (feature desktop). false fixes the window at its configured size.
AppConfig::esc_exitsconst fn esc_exits(self, yes: bool) -> SelfExit the app on Escape. exits_on_esc(&self) -> bool reads the setting.
AppConfig::on_panicconst fn on_panic(&self) -> PanicPolicyThe configured panic policy.
AppConfig::suspend_onfn suspend_on(self, shortcut: impl Into<Option<Shortcut>>) -> SelfThe 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_announcementsfn flush_announcements(&mut self)Move the text that kernel::announce queued into the live region. Host::frame calls it every frame.
kernel::announcefn announce(text: impl Into<String>)Queue a polite screen-reader announcement; the next frame posts it to the live region.
kernel::announce_assertivefn announce_assertive(text: impl Into<String>)Queue an assertive announcement that interrupts the screen reader.
kernel::Cx::dump_treefn dump_tree(&self, root: NodeId) -> StringIndented text of the node tree below root, for debugging.
kernel::Cx::describefn describe(&self, id: NodeId) -> StringA 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_treefn dump_owner_tree() -> StringIndented text of every reactive owner with its name and source location, for debugging leaks.
reactive::debug::dump_subtreefn dump_subtree(owner: OwnerId) -> Stringdump_owner_tree for one owner and its children.
animation::Spring::with_epsilonsfn with_epsilons(self, value: f32, velocity: f32) -> SelfRest thresholds of a spring. Both must be positive; it panics otherwise.
animation::Tween::restartconst fn restart(&mut self)Set the elapsed time back to zero.
bidi::paragraph_levelsfn paragraph_levels(input: &str) -> SmallVec<[u8; 64]>Unicode bidi embedding level of each byte of input.
app::menu::set_menu_barfn set_menu_bar(menu: app::menu::Menu)Install the native menu bar. The window host installs it on the next frame (feature menu).
app::menu::acceleratorfn accelerator(shortcut: &Shortcut) -> Option<app::menu::KeyAccelerator>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_trayfn set_tray(builder: tray_icon::TrayIconBuilder)Install a system tray icon. The window host builds it on the next frame (feature tray).
scene::SceneBuilder::with_layerfn with_layer(&mut self, opacity: f32, body: impl FnOnce(&mut Self))Draw body into a layer composited at opacity.
scene::SceneBuilder::with_transformfn with_transform(&mut self, transform: Transform, body: impl FnOnce(&mut Self))Draw body under transform.
app::dialog::FileDialogFileDialog::new(); filter(name, extensions), directory(dir), file_name(name); open_file(), save_file(), pick_folder() -> Picked<PathBuf>, open_files() -> Picked<Vec<PathBuf>>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.
style::palette::Palettestruct Palette { background, text, primary, success, warning, danger: Rgba8 }; obsidian(), terminal(), aetherlight(), voltglyph(), mythril(), frostkeep(), vellum(), embergrove(), verdigris(), faewine(), crystalline(), spellforge(accent: Rgba8)Named six-color palettes. spellforge derives a palette from one accent color.
style::scaleconst fn {slate, blue, green, amber, ruby, cyan, iris}_{light, dark}() -> ColorScaleTwelve-step color scales for Theme.
style::Theme::with_gray_scalewith_gray_scale, with_accent_scale, with_success_scale, with_warn_scale, with_error_scale, with_info_scale (each const fn(self, scale: ColorScale) -> Self)Replace one color scale of a theme.
style::font_family_hintconst fn font_family_hint(variant: Variant) -> FontFamilyHintThe font family a theme variant asks for.
layout::LayoutStylegrid_columns(Vec<TrackSize>), grid_rows(Vec<TrackSize>), grid_area(col, row), grid_dense(), max_height(impl Into<Dimension>), with_layout(f: impl FnOnce(&mut StyleData))Grid tracks and placement, and direct access to the layout data.
style::Metrics::icon_sizefn icon_size(self) -> f32Icon size in points, or one cell on the terminal host.
style::LengthPercentage::px_or_zeroconst fn px_or_zero(self) -> f32The pixel value, or 0 for a non-pixel size. Dimension has the same method.
style::StyleBinding::set_animator_overlayfn set_animator_overlay(&mut self, overlay: Option<Box<dyn AnimatorOverlay>>)Replace the animated values that override the resolved style.
text::add_fallback_fontfn add_fallback_font(bytes: Vec<u8>, face_index: u32) -> Result<(), TextError>Add a fallback face to every text engine. Shaping uses it for characters the primary faces lack. Layout measures text again on the next frame.
text::load_font_urlfn load_font_url(url: &str, face_index: u32) -> Signal<Status<(), FontLoadError>> (wasm32 only)Fetch a font file and add it with add_fallback_font. The signal turns Ok(()) when the face is in use.
text::FontLoadErrorenum FontLoadError { Fetch(String), Http(u16), InvalidFont } (wasm32 only)Why load_font_url failed.
text::OwnedTextEngineregister_font(bytes: Vec<u8>, face_index: u32) -> Result<(), TextError>, clear_cache()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::Dimensionenum DimensionA length: px, percent, text length, or auto.
layout::LengthPercentageenum LengthPercentageA px or percent length.
style::Dimensionenum Dimension { Px(Px), Full, Fraction(u16), Auto }A size in a style atom.
clipboard::pastefn paste() -> AppResult<String>Read text from the installed clipboard.

Module `a11y`

NameSignaturePurpose
a11y::AccessKitBridgestruct AccessKitBridge<F: FnMut(TreeUpdate)>; const fn new(action_rx: crossbeam_channel::Receiver<ActionRequest>, publish_sink: F) -> SelfImplements A11yBridge over AccessKit. It passes each tree update to the sink and reads action requests from the channel.
a11y::BridgeErrorstruct BridgeError;Error type of AccessKitBridge. It reports that the bridge rejected an update.

Module `animation`

NameSignaturePurpose
animation::SpringPresetenum SpringPreset { Gentle, Smooth, Snappy, Bouncy, Stiff }Spring constants.
animation::Easingenum EasingTween easing curve.
animation::CubicBezierCubicBezier::new(x1, y1, x2, y2)Custom easing curve.
animation::KeyframeKeyframe::new(offset: f32, value: f32)One keyframe.
animation::KeyframesKeyframes::new(frames, duration: Duration); repeat_forever()A keyframe animation. repeat_forever() loops it with no iteration limit.
animation::AnimationDirectionenum AnimationDirectionPlay direction of keyframes.
animation::AnimationFillenum AnimationFill { None, Forwards, Backwards, Both }Value before and after keyframes.

Module `animation_runtime`

NameSignaturePurpose
animation_runtime::AnimatorStatusenum AnimatorStatus { Running, Settled }Tells whether an Animator still moves or has reached its target.
animation_runtime::AttachedAnimatorstruct AttachedAnimator { kind: NumericAtomKind, signal: Signal<f32>, animator: Animator, .. }One numeric style atom that a component animates: the atom kind, the signal that holds the current value, and its animator.
animation_runtime::srgb_channel_to_linearfn srgb_channel_to_linear(c: u8) -> f32Converts one sRGB 8-bit channel to a linear value in 0.0 to 1.0.
animation_runtime::presetsmod presets { const SMOOTH, GENTLE, SNAPPY, BOUNCY, STIFF, FAST, DEFAULT, SLOW: TransitionId }Named TransitionId values that animation_runtime::config maps to spring and tween configs.
animation_runtime::active_countfn active_count() -> usizeReturns the number of animators on this thread that are not paused and not settled.
animation_runtime::AnimatorAnimator::new(signal: Signal<f32>, config: AnimationConfig); pause(), resume()Animate a signal toward targets.
animation_runtime::AnimationConfigenum AnimationConfig { Spring { preset }, Tween { ms, easing } }Spring or tween settings.
animation_runtime::PlaybackPlayback::new(value: Signal<f32>, frames: Keyframes); pause(), resume(), restart()Play keyframes into a signal. restart() seeks to the start.
animation_runtime::MotionPrefsMotionPrefs::reduced() -> bool, MotionPrefs::set(bool)Reduced-motion preference. sigil::run sets it from AppConfig::reduced_motion, else from the OS (macOS accessibility setting, GNOME enable-animations).

Module `app`

NameSignaturePurpose
app::menu::AboutMetadata, app::menu::CheckMenuItem, app::menu::ContextMenu, app::menu::IconMenuItem, app::menu::KeyAccelerator, app::menu::Menu, app::menu::MenuEvent, app::menu::MenuId, app::menu::NativeMenuItem, app::menu::PredefinedMenuItem, app::menu::Submenure-exports of muda typesNative 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.
app::tray::Icon, app::tray::TrayIcon, app::tray::TrayIconEventre-exports of tray_icon typesTray types from the tray-icon crate. Icon is the tray image, TrayIcon is the installed tray, and TrayIconEvent arrives on app::tray::events.
app::CellWidthenum CellWidth { Unicode, Scalar { joiner: usize, nonjoiner: usize, keycap: usize } }Selects how the terminal host counts cell width: Unicode East Asian width, or fixed widths for joiners, non-joiners, and keycaps. Default is Unicode.
app::set_cell_width, app::cell_widthfn set_cell_width(width: CellWidth); fn cell_width(text: &str) -> usizeSet the cell width rule for this thread, and return the number of terminal cells that a string occupies under that rule.
app::Ambiguous, app::set_ambiguousenum Ambiguous { Narrow, Wide }; fn set_ambiguous(width: Ambiguous)Width of East Asian ambiguous characters for this thread. Wide counts them as two cells, as CJK terminals do. Default is Narrow.
app::cell_text_linesfn cell_text_lines(text: &str, max_cells: usize) -> Vec<(usize, usize)>Wraps text to max_cells terminal cells and returns the byte range of each line. 0 means no wrap.
app::FrameInfo#[non_exhaustive] pub struct FrameInfo { dirty: bool, animating: bool, layout_ok: bool, delta: FrameDelta }State of the current frame that Host::frame passes to the paint hook, with the frame's FrameDelta for Host::emit_since.
app::FrameOutputstruct FrameOutput { exit: bool, intervals: usize, animating: bool, layout: Result<(), LayoutError> }Result of Host::frame: exit request, number of intervals fired, whether animations still run, and the layout result.
app::FrameHooks, app::FrameInputHook, app::FrameLayoutHook, app::FramePaintHookstruct FrameHooks<'a> { input: Option<FrameInputHook<'a>>, after_layout: Option<FrameLayoutHook<'a>>, paint: Option<FramePaintHook<'a>> }; type FrameInputHook<'a> = Box<dyn FnOnce(&mut Host, &mut EventRouter) -> Option<(f32, f32)> + 'a>; type FrameLayoutHook<'a> = Box<dyn FnOnce(&mut Host, &mut EventRouter) + 'a>; pub type FramePaintHook<'a> = Box<dyn FnOnce(&mut Host, &mut EventRouter, &FrameInfo) + 'a>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::EngineGeometrystruct EngineGeometry; fn new() -> SelfTextGeometry implementation backed by the thread text engine. It gives hit tests and caret positions for text nodes.
app::DefaultTextMeasurestruct DefaultTextMeasure; fn new() -> SelfTextMeasure implementation backed by the thread text engine. Layout uses it to size text nodes.
app::is_gridfn is_grid() -> booltrue on a cell grid (terminal) host.
app::viewport_sizefn viewport_size() -> Signal<LogicalSize>The viewport size in logical px. A terminal cell is Host::CELL px.
app::display_scalefn 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.
app::set_themefn set_theme(theme: Theme)Replace the active theme at the next frame.
app::parse_themefn parse_theme(input: &str) -> Option<Theme>Parse a theme TOML document.
app::watch_themefn watch_theme(path: impl Into<PathBuf>) -> AppResult<ThemeWatcher>Reload a theme file when it changes.
app::ThemeWatcherstruct ThemeWatcherGuard of watch_theme. Drop it to stop the watch.
app::openfn open(target: impl AsRef<OsStr>) -> AppResult<()>Open a file or URL with the OS handler (feature desktop).
app::dialogmod dialogFile 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.
app::traymod traySystem tray icon (feature tray).
app::tray::updatefn update<R>(edit: impl FnOnce(&TrayIcon) -> R) -> Option<R>Change the installed tray's icon, tooltip, or menu; None before it is installed.
app::notify, app::notify::Notification, app::notify::sendstruct Notification { title, body, app_name }, Notification::new(title, body), .app_name(..); fn send(&Notification) -> AppResult<()>Desktop notification on macOS, Windows, and freedesktop systems. Other targets return an unsupported error (feature notify).
app::media, app::media::now_playing, app::media::eventsfn now_playing(Track) -> AppResult<()>; fn events() -> EventChannel<MediaKey>; struct Track (title, artist, album, cover, duration, position, state, shuffle, repeat), enum PlaybackState, enum Repeat { Off, One, All }, enum MediaKeyNow-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.
app::hotkey, app::hotkey::register, app::hotkey::unregisterfn register(&Shortcut) -> AppResult<EventChannel<KeyPhase>>; fn unregister(&Shortcut) -> AppResult<bool>A system-wide hotkey that fires while the app is in the background. Register from the UI thread (feature hotkey).
app::menumod menuNative menu bar (feature menu).
app::Playerstruct Player; play_path, play_bytes(Vec<u8>), queue(paths), append(path), stop(), toggle(), seek; volume: Signal<f32>, duration: Signal<Option<Duration>>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.
app::Sessionstruct SessionChild process in a pseudo-terminal (feature pty).
app::ErrorKindenum ErrorKindClass of an Error.
app::PanicPolicyenum PanicPolicy { Isolate, Abort }What a panic in a handler does.
app::HostCapsstruct HostCaps { hyperlinks: bool }; HostCaps::current(), HostCaps::window()What the running host can show. The terminal host fills it from the detected terminal.
app::AccessibilityTreetype AccessibilityTree = accesskit::TreeUpdateAccessibility tree of an embedded tree.
app::WindowCommandenum WindowCommand { Close, Minimize, ToggleMaximize, Drag, DragResize, SetZoom, Show, Hide, Focus, SetTitle(String), SetPosition(Point), SetLevel(WindowLevel) }Commands for the window whose frame runs, or for a WindowId through WindowId::command. Feature desktop.
app::WindowLevelenum WindowLevel { AlwaysOnBottom, Normal, AlwaysOnTop }Window stacking level.
app::open_window, app::WindowIdfn open_window(config: impl Into<AppConfig>, view: impl Fn() -> N + 'static) -> WindowId; WindowId::close(), command(WindowCommand), focused() -> Option<Signal<bool>>, occluded() -> Option<Signal<bool>>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.
app::current_window, app::window_focused, app::window_occludedfn current_window() -> Option<WindowId>; fn window_focused() -> Signal<bool>; fn window_occluded() -> Signal<bool>The window whose frame runs, and its focus and occlusion as signals.
app::CloseAction, AppConfig::on_closeenum CloseAction { Close, Hide, Keep }; fn on_close(self, decide: impl Fn() -> CloseAction + 'static) -> SelfWhat a close request does: close the window (the default), hide it and keep the app running (for tray apps), or ignore it.
AppConfig::on_exitfn on_exit(self, run: impl Fn() + 'static) -> Self (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::ResizeDirectionenum ResizeDirectionEdge or corner for WindowCommand::DragResize. Feature desktop.
app::WindowOptsstruct WindowOptsWindow options that AppConfig collects. Feature desktop.
app::Anchorenum Anchor { BottomCenter { margin: f32 } }Screen anchor of an overlay window. Feature desktop.
app::DefaultFontsstruct DefaultFontsFont bytes for the sans, mono, icon, and display faces.
app::set_default_fontsfn set_default_fonts(fonts: DefaultFonts)Replace the bundled fonts.
app::use_system_fontsfn use_system_fonts()Use the operating system fonts.
app::TextTuningstruct TextTuningText rasterization settings.
app::text_tuningfn text_tuning() -> TextTuningRead the text rasterization settings.
app::set_text_tuningfn set_text_tuning(tuning: TextTuning)Set the text rasterization settings.

Module `bidi`

NameSignaturePurpose
bidi::visual_orderfn visual_order(levels: &[u8]) -> Vec<usize>Returns the visual order of runs from their bidi embedding levels.
bidi::Stepenum 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`

NameSignaturePurpose
clipboard::NoopClipboardstruct NoopClipboard;Clipboard implementation used when no clipboard is installed. set returns an error.
clipboard::copyfn copy(text: &str) -> AppResult<Delivery>Write text to the installed clipboard.
clipboard::image, clipboard::copy_imagefn image() -> AppResult<Option<ImageSource>>; fn copy_image(image: &ImageSource) -> Result<Delivery, ClipError>; Clipboard::set_image (feature clipboard-image)Read an image from the clipboard, None when it holds no image, or write one. The web clipboard has no image write and returns a ClipError.
clipboard::ClipErrorClipError::new(msg)A clipboard back end failed.
clipboard::OsClipboardstruct OsClipboardThe OS clipboard (feature clipboard).
clipboard::installfn install(clip: impl Clipboard + 'static)Replace the installed clipboard.
clipboard::Clipboardtrait Clipboard { fn set(&self, &str) -> Result<Delivery, ClipError>; fn get(&self) -> Option<String>; }A clipboard back end.
clipboard::Deliveryenum Delivery { Confirmed, Requested }Whether the OS took the text.
use sigil::clipboard::ClipError;use sigil::clipboard::OsClipboard;use sigil::clipboard::copy;use sigil::prelude::*;use sigil::clipboard::Clipboard;use sigil::clipboard::Delivery;use sigil::clipboard::install; struct Memory; impl Clipboard for Memory {    fn set(&self, _text: &str) -> Result<Delivery, ClipError> { Err(ClipError::new("read-only")) }    fn get(&self) -> Option<String> { Some("text".into()) }} fn main() -> AppResult<()> {    install(Memory);    let _: Delivery = copy("hello")?;    let _: String = sigil::clipboard::paste()?;    let _: Option<OsClipboard> = None;    Ok(())}
use sigil::clipboard::ClipError;use sigil::clipboard::Clipboard;use sigil::clipboard::Delivery;use sigil::clipboard::OsClipboard;use sigil::clipboard::copy;use sigil::clipboard::install;use sigil::prelude::*; struct Memory; impl Clipboard for Memory {  fn set(    &self,    _text: &str,  ) -> Result<Delivery, ClipError> {    Err(ClipError::new("read-only"))  }  fn get(&self) -> Option<String> {    Some("text".into())  }} fn main() -> AppResult<()> {  install(Memory);  let _: Delivery = copy("hello")?;  let _: String =    sigil::clipboard::paste()?;  let _: Option<OsClipboard> = None;  Ok(())}

Module `events`

NameSignaturePurpose
events::focus_from_keyboardfn focus_from_keyboard() -> boolWhether the last focus change came from the keyboard, which decides whether a focus ring shows.
events::EventHandlersstruct EventHandlersThe handler set of a node.
events::request_revealfn request_reveal(id: NodeId)Scroll each enclosing scroll so a node is in view after the next layout.
events::FocusIntentenum FocusIntent { Up, Down, Left, Right }Directional focus move.
events::SelectableTextstruct SelectableTextNode extension that marks a text region as selectable. NodeEventsExt::selectable_text(true) attaches it.
events::request_window_commandfn request_window_command(command: WindowCommand)Send a command to the window. Feature desktop.
events::PhysicalKeykeyboard_types::CodeA key position on the keyboard.
events::ImeEventenum ImeEvent { Enabled, Preedit, Commit, Disabled }Input method event.
events::ScrollEventstruct ScrollEventA wheel or trackpad scroll. Each on_scroll handler sees position relative to its own node, as pointer handlers do.
events::ScrollDeltaenum ScrollDelta { Pixels(Point), Lines(Point) }Scroll amount.
events::ScrollPhaseenum ScrollPhase { Started, Moved, Ended, Cancelled }Scroll gesture phase.
events::FileDropEventstruct FileDropEventA 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.
events::FileDropPhaseenum FileDropPhase { Hovered, Dropped, Cancelled }File drop phase.
events::WindowEventenum WindowEventResize, focus, and close events of the window.
events::KeyEventInitstruct KeyEventInit { key: LogicalKey, physical: PhysicalKey, modifiers: ModifiersState, repeat: bool, phase: KeyPhase, text: Option<SmolStr> }Fields for KeyEvent::new.
events::ScrollEventInitstruct ScrollEventInit { position: Point, delta: ScrollDelta, modifiers: ModifiersState, phase: ScrollPhase }Fields for ScrollEvent::new.
events::EventRouterEventRouter::new()Routes shell events to an embedded tree.
events::ShellEventenum ShellEvent { Pointer, Key, Ime, Scroll, Gesture(GestureEvent), FileDrop, Paste(String), Window }An input event from the host. The terminal host sends a bracketed paste as one Paste.
events::PasteEventstruct PasteEvent { pub text: String, .. }; PasteEvent::new(text), stop_propagation(), propagation_stopped() -> boolPasted 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::PointerEventInitstruct PointerEventInitFields to build a PointerEvent. PointerEvent::with_contact(pointer_id, pressure, tilt) sets the contact data.
events::PointerTiltstruct PointerTilt { x: f32, y: f32 }Pen tilt in degrees.
events::GestureEvent, events::GestureEventInit, events::GestureKindstruct GestureEvent { kind, phase: ScrollPhase, position, modifiers, .. }; enum GestureKind { Pinch(f64), Rotate(f32), Pan(Point), DoubleTap }; stop_propagation()A trackpad or touch gesture. It goes to the node under its position and bubbles like a scroll; NodeEventsExt::on_gesture(f) receives it.
events::ShortcutParseErrorenum ShortcutParseError { Empty, UnknownModifier(String), UnknownKey(String) }Why a shortcut string did not parse.

Module `geometry`

NameSignaturePurpose
geometry::Dimenum Dim { Fixed(f32), MinContent, MaxContent }One axis of a size constraint.
geometry::LogicalSizestruct LogicalSize { width: f32, height: f32 }A size in logical px or cells.
geometry::PhysicalSizestruct PhysicalSize { width: u32, height: u32 }; const fn new(width: u32, height: u32) -> SelfSize in device pixels.
geometry::Scalestruct Scale(f32); const ONE; fn new(scale: f32) -> Self; const fn factor(self) -> f32; fn to_physical(self, logical: LogicalSize) -> PhysicalSizeDevice scale factor. new replaces a non-finite or non-positive value with ONE.

Module `hal`

NameSignaturePurpose
hal::Renderertrait Renderer { type Error; type Surface; type WindowHandle; fn create_surface(..); fn resize(..); fn clear(..); }Contract for a render backend: create a surface for a window, resize it, and clear it to a color.
hal::Shelltrait Shell: Sized { type Error; type Waker; type Window; fn waker(&self); fn wake(waker: &Self::Waker); fn create_window(..); fn create_window_logical(..); fn create_window_with(..); fn drain_events(&mut self); fn run<F>(self, frame: F); }Contract for a windowing backend: create windows, wake the loop from other threads, drain events, and run the frame loop.
hal::RenderedGlyph#[non_exhaustive] pub struct RenderedGlyph { font_id: u64, font_index: u32, glyph_id: u32, x: f32, y: f32, size: f32, color: Color, variation_coords: Box<[i16]>, skew: f32 }One positioned glyph that the text engine gives to the renderer.
hal::TextAffinity, hal::HitPositionenum TextAffinity { Downstream, Upstream }; struct HitPosition { byte_index: usize, affinity: TextAffinity }Result of a text hit test: the byte index and the side of a line break or bidi boundary that the caret belongs to.
hal::ParagraphMetrics, hal::TextEnginetrait ParagraphMetrics { fn width; fn height; fn line_count; fn min_content_width; fn max_content_width }; trait TextEngine { type Error; type Paragraph: ParagraphMetrics; fn layout_paragraph(&self, text: &str, max_width: Option<f32>) -> Result<Self::Paragraph, Self::Error>; fn clear_cache(&self) }Contract for a text shaper: lay out a paragraph at a width and report its size and line count.
hal::ParagraphMetricstrait ParagraphMetrics { fn width(&self) -> f32; fn height(&self) -> f32; fn line_count(&self) -> usize; fn min_content_width(&self) -> f32; ... }Reports the measured size of a laid-out paragraph.
hal::TextEnginetrait TextEngine { type Error; type Paragraph: ParagraphMetrics; fn layout_paragraph(&self, text: &str, max_width: Option<f32>, ..) -> Result<Self::Paragraph, Self::Error>; ... }Shapes and lays out text into paragraphs.

Module `icons`

NameSignaturePurpose
icons::IconBakerstruct IconBaker; const fn new() -> Self; fn bake(&self, svg_source: &str, width: u32, height: u32) -> Result<BakedIcon, BakeError>Rasterizes an SVG icon into an alpha mask of the given size.
icons::BakedIconstruct BakedIcon { width: u32, height: u32, alpha: Vec<u8> }Holds a baked icon as one alpha byte per pixel.
icons::BakeErrorenum BakeError { SvgParseError(String), PathOverflow, TooManySegments(u32), ViewBoxMissing }Reports why IconBaker::bake failed.
icons::builtin::HEART_SVG, icons::builtin::GEAR_SVG, icons::builtin::SEARCH_SVG, icons::builtin::ARROW_RIGHT_SVG, icons::builtin::X_SVG, icons::builtin::ARROW_UP_SVG, icons::builtin::ARROW_DOWN_SVG, icons::builtin::CHEVRONS_UP_DOWN_SVG, icons::builtin::CHECK_SVGconst *_SVG: &strHold the SVG source of each bundled icon.
icons::builtin::ALLconst ALL: [(&str, &str); 8]Lists every bundled icon as a (name, svg) pair.

Module `kernel`

NameSignaturePurpose
kernel::Live, kernel::SortDirectionre-exports of accesskit::Live, accesskit::SortDirectionAccessKit values for live-region politeness and column sort state in accessibility props.
kernel::HostModeenum HostMode { Pixel, Cell }Tells widgets whether the host lays out in pixels (window) or in terminal cells. Default is Pixel.
kernel::schedule_keyed_rebuildfn schedule_keyed_rebuild<K: Clone + Eq + Hash + 'static, N: IntoNode + 'static>(parent: NodeId, prior: Rc<RefCell<Vec<(K, NodeId)>>>, incoming: Vec<(K, Option<N>)>)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::FocusScopeKindenum 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.
kernel::TextCursorstruct TextCursor { caret: Signal<usize>, anchor: Signal<Option<usize>> }Caret and selection anchor of an editable text node, exported to accessibility.
kernel::Nodestruct NodeA node in the tree, as NodeBuilder::mutate sees it.
kernel::NodeTypeenum NodeTypeContainer, text, image, or fragment.
kernel::NodeExtensionsstruct NodeExtensionsTyped data attached to a node.
kernel::TextBuilderstruct TextBuilder; wrap(), ellipsize(), nowrap(), runs(Vec<TextRun>), label(name), description(text), role(Role), keyboard_shortcut(shortcut), focusable(bool), tab_index(i32), hittable(bool), mutate(FnOnce(&mut Node)), add(&mut Cx) -> NodeIdBuilder 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::ImageBuilderalt, fit, crop, mutate, plus WidgetLayoutExtThe one image builder. image, image_rgba, and image_bytes return it.
kernel::ImageCropstruct 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.
kernel::ImageRasterstruct ImageRaster (opaque, Clone + PartialEq + Debug)Resolution-independent source of an image. Paths and SVG icons carry one; the renderer asks it for pixels at the physical destination size.
kernel::ObjectFitenum ObjectFit { Fill, Contain, Cover }How an image fills its box.
kernel::TopLayerstruct TopLayerMarker of a node that paints above the tree.
kernel::A11yPropsstruct A11yProps; required: Option<Signal<bool>>, position_in_set: Option<usize>, size_of_set: Option<usize>, ..Accessibility properties of a node. virtual_list sets each row's position and the item count, so a screen reader reads "5 of 200".
kernel::AccessibleNameenum AccessibleNameNone, static, or signal name.
kernel::Surfacestruct Surface { key: u64 }Marker of a host-drawn surface.

Module `layout`

NameSignaturePurpose
layout::Display, layout::Position, layout::FlexDirection, layout::BoxSizingenum Display { Block, Flex, Grid, None }; enum Position { Relative, Absolute }; enum FlexDirection { Row, Column, RowReverse, ColumnReverse }; enum BoxSizing { ContentBox, BorderBox }Set the display mode, positioning, flex direction, and box sizing of a StyleData node.
layout::JustifyContent, layout::AlignContent, layout::AlignItems, layout::AlignSelfenum JustifyContent and enum AlignContent { Start, End, Center, Stretch, SpaceBetween, SpaceAround, SpaceEvenly }; enum AlignItems { Start, End, Center, Baseline, Stretch }; type AlignSelf = AlignItemsSet main-axis and cross-axis alignment of a StyleData node and its children.
layout::LengthPercentage, layout::LengthPercentageAutoenum LengthPercentage { Px(f32), Percent(f32), Text(TextLength) }; enum LengthPercentageAuto { Px(f32), Percent(f32), Auto }Padding, margin, gap, and inset values of a StyleData node.
layout::TextGeometrytrait TextGeometry { fn hit(..) -> HitPosition; fn caret(..) -> CaretGeometry; fn selection_rects(..) -> Vec<Rect> }Maps between points and text positions for hit testing, carets, and selection.
layout::CaretGeometrystruct CaretGeometry { x: f32, top: f32, height: f32 }Holds the position and height of a text caret.
layout::ReactivePositionstruct ReactivePositionExtension that position_reactive attaches.
layout::BoundsReactivestruct BoundsReactiveExtension that bounds_reactive attaches.
layout::FlexDirectionenum FlexDirection { Row, Column, RowReverse, ColumnReverse }Main axis of a flex box.
layout::AlignSelftype AlignSelf = AlignItemsCross-axis alignment of one child.
layout::Positionenum Position { Relative, Absolute }Positioning mode.
layout::Overflowenum Overflow { Visible, Hidden, Scroll }Overflow mode.
layout::LengthPercentageAutoenum LengthPercentageAuto { Px, Percent, Auto }A px, percent, or auto length.
layout::TrackSizeenum TrackSize { Px(f32), Fr(f32), Auto, MinMax(f32, f32) }Size of a grid track.
layout::TextLengthenum TextLength { Rows(f32), Cols(f32), Em(f32) }A length relative to the text metrics.
layout::LayoutEnginestruct LayoutEngine; take_republished(&mut self) -> boolThe 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.
layout::LayoutResultstruct LayoutResultThe laid-out rectangle of a node.
layout::LayoutErrorenum LayoutErrorThe layout pass failed.
layout::align::misalignmentsfn misalignments(cx: &Cx, layout: &LayoutEngine, root: NodeId, tolerance: Tolerance) -> Vec<Misalignment>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.
layout::align::Tolerancestruct Tolerance { exact: f32, near_miss: f32 }; Tolerance::cells(), Tolerance::points(), Tolerance::for_mode(HostMode)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.
layout::align::Misalignment, layout::align::MisalignmentKindenum Misalignment { Column { parent: NodeLabel, column: usize, tops: Vec<f32>, starts: Vec<f32>, ends: Vec<f32> }, Inset { node: NodeLabel, rect: Rect, axis: Axis, start: f32, end: f32 } }; kind() -> MisalignmentKind, node() -> &NodeLabel; enum MisalignmentKind { Column, Inset }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::NodeLabelstruct NodeLabel { id: NodeId, label: String }The node a finding names, labelled the way Cx::dump_tree labels it, plus its id.
layout::align::Asymmetric, LayoutBuilderExt::asymmetricstruct Asymmetric(&'static str); fn asymmetric(self, reason: &'static str) -> SelfWaiver: the alignment lint skips this node and its column check. The reason stays on the node as the Asymmetric extension.
layout::TextMeasuretrait TextMeasureText measurement that the layout pass calls. font_generation changes when the loaded fonts change; layout drops cached text sizes when it does.

Module `profile`

NameSignaturePurpose
profile::Categoryenum Category { Layout, Paint, Render, A11y, Reactive, App } (name())Groups profile phases by subsystem for reports and the frame HUD.
profile::Phaseenum Phase { Effect, Layout, LayoutSolve, ..., Paint, RenderCpu, A11y, TuiPaint, TuiRaster, TuiWrite, TuiPresent, Gpu, GpuWait, RenderPlan, RenderEncode, RenderRetain, RenderSubmit } (name(), category())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.
profile::Counter, profile::Cause, profile::BackendKind, profile::FallbackCause#[non_exhaustive] enum with name() -> &'static strName a per-frame counter, the event that caused a frame, the active renderer backend, and why the host fell back from the GPU backend.
profile::BackendStatusstruct BackendStatus { kind: BackendKind, fallback: FallbackCause }; const TERMINALRecords which backend renders the frame and the fallback cause, if any.
profile::PhaseTime, profile::CounterValuetype PhaseTime = (Phase, u64); type CounterValue = (Counter, u64)Pair a phase with its time in nanoseconds, and a counter with its value.
profile::Spanstruct Span (drop guard)Measures one phase from creation until drop. Create it with profile::span.
profile::Framestruct Frame { index: u32, cause: Cause, wall_ns: u64, end_us: u64, phases: Vec<PhaseTime>, counts: Vec<CounterValue>, hot: Vec<Attribution>, gpu_passes: Vec<(&'static str, u64)>, backend: Option<BackendStatus> }; counter, total_ns, hottestHolds the recorded timings, counters, attributions, and GPU pass times of one frame.
profile::FRAME_BUDGET_NS, profile::INTERACT_BUDGET_NSconst FRAME_BUDGET_NS: u64 = 16_670_000; const INTERACT_BUDGET_NS: u64 = 200_000_000The 60 Hz frame budget and the input-to-frame latency budget. Reports compare frames against frame_budget_ns.
profile::frame_budget_ns, profile::BUDGET_ENV, profile::DEFAULT_BUDGET_MSfn frame_budget_ns() -> u64; const BUDGET_ENV: &str = "SIGIL_PROFILE_BUDGET_MS"; const DEFAULT_BUDGET_MS: f64 = 8.33The frame budget that reports use: SIGIL_PROFILE_BUDGET_MS in milliseconds, or 8.33 ms (120 Hz). It is read once.
profile::Hotspot, profile::Attribution#[non_exhaustive] enum Hotspot { LayoutDirtyKernel, LayoutDirtySeed, LayoutResized, LayoutRoot, EmitResolved, GpuLayer, GpuFullRepaint, RowRebuild } (name()); struct Attribution { hotspot: Hotspot, subject: String, count: u64 }Name what caused a cost and who caused it. The summary's why section lists the top subjects per hotspot.
profile::attribute, profile::MAX_SUBJECTS, profile::OTHER_SUBJECTfn attribute(hotspot: Hotspot, n: u64, subject: impl FnOnce() -> String); const MAX_SUBJECTS: usize = 64; const OTHER_SUBJECT: &str = "(other)"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_passfn 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.
profile::enable, profile::disable, profile::enabled, profile::resetfn enable(); fn disable(); fn enabled() -> bool; fn reset()Turn frame recording on or off, query it, and clear recorded frames.
profile::begin_frame, profile::tick_framefn begin_frame(backend: BackendStatus); fn tick_frame()Open a new recorded frame with its backend status, and close the current frame. Hosts call these once per frame.
profile::spanfn span(phase: Phase) -> SpanStarts timing phase in the current frame.
profile::count, profile::count_add, profile::gaugefn count(counter: Counter); fn count_add(counter: Counter, n: u64); fn gauge(counter: Counter, value: u64)Add one or n to a counter, or set it to a value, in the current frame.
profile::interactfn interact(cause: Cause)Marks the next frame as caused by cause so the report can measure input latency.
profile::note_inputfn 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.
profile::dump, profile::dump_if_enabledfn dump(path: impl AsRef<Path>) -> io::Result<()>; fn dump_if_enabled()Write recorded frames as a Chrome trace file and print a summary. dump_if_enabled writes to the path set by the environment, if any.
profile::frames, profile::summaryfn frames() -> Vec<Frame>; fn summary() -> StringReturn the recorded frames, and a text summary of them.

Module `reactive`

NameSignaturePurpose
reactive::Subscription#[must_use] pub struct SubscriptionHandle returned by EventChannel::subscribe. Dropping it removes the subscriber.
reactive::effect_namedfn effect_named<F: FnMut() + 'static>(name: &'static str, f: F)Same as effect, with a name that shows in diagnostics.
reactive::Ownerstruct Owner; fn new(name: &'static str, parent: Option<OwnerId>) -> SelfReactive scope that owns effects, signals, and cleanups. Disposing it disposes its children.
reactive::DrawPhaseenum DrawPhase { Idle, Effect, Layout, Paint }Phase of the frame that the runtime is in. Signal writes during paint are rejected.
reactive::on_cleanupfn on_cleanup(f: impl FnOnce() + 'static)Run f when the current owner is disposed.
reactive::batchfn batch<R>(f: impl FnOnce() -> R) -> RGroup writes into one update.
reactive::untrackfn untrack<R>(f: impl FnOnce() -> R) -> RRun f without subscribing the current effect to its reads.
reactive::deferfn defer(f: impl FnOnce() + 'static)Run f after the current effect returns, or now outside an effect. An effect uses it to consume the signal that triggers it.
reactive::EventChannelstruct EventChannel<T>; emit, subscribeSend events between parts of the app.
reactive::Runtimestruct Runtime; Runtime::scope(name, f) -> RRun code inside a reactive runtime.

Module `renderer`

NameSignaturePurpose
renderer::WgpuRendererstruct WgpuRenderer; fn new() -> Result<Self, RendererError>; fn render_command_scene(&mut self, surface: &mut WgpuSurface, scene: &CommandScene, clear_color: Color, viewport: (f32, f32)) -> Result<(), RendererError>; fn render_command_scene_offscreen(&mut self, target: OffscreenTarget<'_>, scene: &CommandScene, clear_color: Color) -> Result<(), RendererError>; fn device/queue/instanceThe 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_timingsfn 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.
renderer::WgpuSurfacestruct WgpuSurface; const fn size(&self) -> PhysicalSize; const fn format(&self) -> wgpu::TextureFormatA configured GPU window surface that WgpuRenderer presents to.
renderer::CpuRenderer, renderer::CpuSurfacestruct CpuRenderer; fn new() -> Self; fn render(&mut self, scene: &CommandScene, clear: Color, viewport: (f32, f32), size: PhysicalSize) -> Result<Pixmap, RendererError>; fn render_command_scene(&mut self, surface: &mut CpuSurface, scene, clear, viewport) -> Result<(), RendererError>; CpuSurface::size(&self) -> PhysicalSizeThe software renderer (feature cpu, selected by SIGIL_BACKEND=cpu). It draws the same CommandScene to a pixmap or a window buffer.
renderer::OffscreenTargetstruct OffscreenTarget<'a> { device: &wgpu::Device, queue: &wgpu::Queue, view: &wgpu::TextureView, format: wgpu::TextureFormat, viewport: (f32, f32), scale: f32 }A caller-owned texture target for WgpuRenderer::render_command_scene_offscreen.
renderer::ScreenSubmissionstruct ScreenSubmission<'a> { device, queue, view, format, viewport: (f32, f32), scale: f32, clear: Option<Color> }Target for drawing a scene in screen space into an embedder's render pass.
renderer::RendererError#[non_exhaustive] enum RendererError { NoAdapter, DeviceRequest(..), SurfaceCreate(..), NoSupportedFormat, SurfaceValidation, NotInitialized, InvalidViewport, Layer(LayerError), Software(String) }Errors from device setup, surface creation, frame validation, offscreen layers, and the software renderer.
renderer::LayerErrorenum LayerError { Empty, TooLarge { requested: u32, max: u32 } }Why the renderer could not allocate an offscreen layer: the extent is empty or larger than the device limit. RendererError::Layer carries it.
renderer::WindowHandle, renderer::into_window_handlestruct WindowHandle; fn into_window_handle<W>(window: W) -> WindowHandle where W: HasWindowHandle + HasDisplayHandle + Send + Sync + 'staticWrap a platform window so the renderer can create a surface for it.

`renderer::capture`

NameSignaturePurpose
renderer::capture::FORMAT, renderer::capture::CaptureExtentconst FORMAT: wgpu::TextureFormat = Rgba8UnormSrgb; struct CaptureExtent { width: u32, height: u32 }The texture format and size of a capture target (feature scene).
renderer::capture::render_to_image, renderer::capture::ImageRenderer, renderer::capture::ImageTargetfn render_to_image(renderer: ImageRenderer<'_>, scene: &CommandScene, target: ImageTarget) -> Result<RgbaImage, RendererError>; enum ImageRenderer { Gpu(&mut WgpuRenderer), Cpu(&mut CpuRenderer) }; struct ImageTarget { size: PhysicalSize, viewport: (f32, f32), clear: Color }Render a scene to an image on the GPU or the CPU. The inspector screenshot, app::snapshot, and the kittest harness all render through it.
app::snapshotfn snapshot(view: impl IntoNode, size: PhysicalSize) -> AppResult<RgbaImage>Lay out and render a view off screen to an image of size pixels, on the GPU when an adapter exists, else on the CPU renderer (feature desktop).
renderer::capture::capture_texture, renderer::capture::read_texturefn capture_texture(device: &wgpu::Device, extent: CaptureExtent) -> wgpu::Texture; fn read_texture(device: &wgpu::Device, queue: &wgpu::Queue, texture: &wgpu::Texture, extent: CaptureExtent) -> Result<Vec<u8>, Box<dyn Error>>Create a render target texture that supports copy-out, and read it back as tightly packed RGBA8 rows.

Module `scene`

NameSignaturePurpose
scene::SceneCommandenum SceneCommand { PushClip(Rect), PopClip, PushTransform(Transform), PopTransform, SaveLayer { opacity }, RestoreLayer, PushLayer(LayerScope), PopLayer, Rect(DrawRect), Gradient(DrawGradient), Pattern(DrawPattern), DrawShadow { rect, radii, shadow }, GlyphRun(DrawGlyphRun), Sprite(DrawSprite), Image(DrawImage), Decoration(DrawDecoration) }One draw or state command in a CommandScene. Both hosts consume the same command list.
scene::emit_scene, scene::emit_scene_clippedfn emit_scene(cx: &Cx, root: NodeId) -> CommandScene; fn emit_scene_clipped(cx: &Cx, root: NodeId, clip: Option<Rect>) -> CommandSceneWalk the laid-out tree from root and return its draw commands. The clipped form skips nodes outside clip.
scene::EmitDiffstruct EmitDiff { changed: Vec<(Range<usize>, Range<usize>)> }, unchanged()What Host::emit_since changed: pairs of old and new command ranges that differ. unchanged() is true when the new scene equals prev.
scene::paint_backdropfn paint_backdrop(scene: &mut CommandScene, theme: &Theme, viewport: (f32, f32))Put a rectangle of the theme's Token::Surface color under every command in scene, as an opaque window paints behind its tree.
scene::DrawRect, scene::CellRectstruct DrawRect { node, rect, color, border_radius, opacity, stroke, tone, leaf, border, outline }; struct CellRect { tone, leaf, border, outline }A filled rectangle command. CellRect holds the cell-grid hints (tone, leaf, border, outline) that the terminal host reads.
scene::DrawGradient, scene::LinearGradient, scene::GradientStopstruct DrawGradient { node, rect, gradient, border_radius, opacity, stroke, .. }; LinearGradient::new(start: Point, end: Point, stops); GradientStop::new(offset: f32, color: Rgba8)A rectangle filled with a linear gradient between two points through ordered color stops.
scene::DrawPattern, scene::PatternKindstruct DrawPattern { node, rect, pattern, border_radius, opacity, stroke }; enum PatternKind { Slash { color, period, line_width }, Checker { color_a, color_b, cell } }A rectangle filled with a repeating slash or checker pattern.
scene::PatternKind::normalized, scene::PatternKind::tile_extentfn normalized(self) -> PatternKind; fn tile_extent(self) -> f32The 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::normalizedfn normalized(&self) -> LinearGradientThe 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).
scene::PaintFillenum PaintFill { Solid(Rgba8), LinearGradient(LinearGradient), Pattern(PatternKind) }The fill of a painted area: solid color, gradient, or pattern.
scene::DrawImagestruct DrawImage { node, source: ImageSource, fit: ObjectFit, destination: Rect, opacity: u16, crop: Option<ImageCrop>, raster: Option<ImageRaster> }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.
scene::DrawImage::source_atfn source_at(&self, scale: f32) -> (ImageSource, Rect)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.
scene::DrawSprite, scene::SpriteSource, scene::SpriteKindDrawSprite::new(style: &SceneSpriteStyle); struct SpriteSource { atlas: u32, region: Rect, phase: f32 }; enum SpriteKind { Mono, Subpixel, Poly }A region of a glyph or icon atlas drawn into a destination rectangle.
scene::DrawDecoration, scene::DecorationKindstruct DrawDecoration { node, kind, band, color, opacity, period, line_width }; enum DecorationKind { Underline, Strikethrough, WavyUnderline }A text decoration line drawn across a band.
scene::DecorationGeometry, scene::DrawDecoration::geometrystruct DecorationGeometry { band, center, thickness, amplitude, period }; fn geometry(&self) -> Option<DecorationGeometry>; fn wave_y(&self, x) -> f32, fn line(&self) -> Rect, fn reach(&self) -> f32Resolved 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.
scene::DrawGlyphRun, scene::shape_glyph_runfn shape_glyph_run(rect: Rect, text: String, color: Rgba8, style: TextStyle, opacity: u16) -> GlyphRun (feature scene)DrawGlyphRun is a shaped text command. shape_glyph_run shapes text into a GlyphRun ready for SceneBuilder::draw_glyph_run.
scene::SceneRectStyle, scene::SceneGradientStyle, scene::ScenePatternStyleSceneRectStyle::new(color, border_radius, opacity), ::solid(color), ::rounded(color, radius), .with_stroke(stroke); SceneGradientStyle::new(gradient, border_radius, opacity); ScenePatternStyle::new(pattern, border_radius, opacity)Style arguments for SceneBuilder::draw_rect, draw_gradient, and draw_pattern.
scene::SceneSpriteStyle, scene::SceneDecorationStylestruct SceneSpriteStyle { source, kind, destination, color, opacity }; struct SceneDecorationStyle { kind, band, color, opacity, period, line_width }Style arguments for SceneBuilder::draw_sprite and draw_decoration.
scene::Stroke, scene::StrokeStyle, scene::StrokeAlignstruct Stroke { color: Rgba8, width: f32, style: StrokeStyle, align: StrokeAlign }; enum StrokeStyle { Solid, Dashed(f32) }; enum StrokeAlign { Centered, Inside, Outside }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.
scene::LayerScope, scene::LayerEffectstruct LayerScope { clip: Rect, clip_radii: CornerRadii, effect: LayerEffect, opacity: f32 }; enum LayerEffect { Identity, Transform(Transform), LayerBlur { sigma } }A composited layer: its clip, opacity, and a transform or blur effect. Used with SceneBuilder::push_layer.
scene::CornerRadiistruct CornerRadii(pub [f32; 4]); ZERO, new(tl, tr, br, bl), uniform(r), top(r), bottom(r), left(r), right(r), normalized_for(w, h) -> [f32; 4]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.
scene::Shadow, scene::ShadowKindShadow::new(offset: [f32; 2], blur: f32, spread: f32, color: [f32; 4]), Shadow::glow(color: Rgba8, spread, blur), .with_kind(kind); enum ShadowKind { Outer, Inner, Glow }A box shadow with linear color, offset, blur, and spread. glow builds a centred glow from an sRGB color.

Module `shell`

NameSignaturePurpose
shell::WinitShellstruct WinitShell (implements hal::Shell)Window host backed by winit.
shell::WinitWaker, shell::WakeEventstruct WinitWaker; fn wake(&self) -> Result<(), ShellError>; struct WakeEvent;Wakes the winit event loop from any thread. Repeated wakes before the loop runs merge into one WakeEvent.
shell::WinitWindowHandlestruct WinitWindowHandle(u64); const fn id(self) -> u64Id of a window that WinitShell created.
shell::ShellErrorenum ShellError { EventLoop(EventLoopError), EventLoopClosed, WakerPoisoned, AlreadyRun, Window(String) }Errors from WinitShell and WinitWaker.

Module `style`

NameSignaturePurpose
style::Transform2Dstruct Transform2D; translate(x, y), scale(x, y), rotate(radians), origin(x, y), IDENTITYHolds a 2D translation, scale, and rotation for a node. The renderer applies it around the transform origin.
style::SELECTION_FILLconst SELECTION_FILL: Rgba8Gives the fill color for selected text.
style::SPACING_STEPconst SPACING_STEP: f32 = 4.0Sets the pixel size of one spacing step in style atoms.
style::GradientAxis, style::GradientStopKey, style::BgGradientenum GradientAxis { TopToBottom, BottomToTop, LeftToRight, .. }; struct GradientStopKey { offset: u16, color: ColorAtom }; struct BgGradient { axis: GradientAxis, stops: &'static [GradientStopKey] }; BgGradient::owned(axis, Vec<GradientStopKey>)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.
style::DisplayKind, style::FlexDir, style::AlignKind, style::JustifyKind, style::FlexWrapKind, style::OverflowKindenum DisplayKind { Flex, Block, Grid, .. }; enum FlexDir { Row, Column, RowReverse, .. }; enum AlignKind; enum JustifyKind; enum FlexWrapKind { NoWrap, Wrap }; enum OverflowKind { Visible, Hidden, Scroll, .. }Typed layout values that style atoms carry for display, flex direction, alignment, justification, wrap, and overflow.
style::TransitionId, style::MillisU16struct TransitionId(pub u16); struct MillisU16(pub u16)Identify a style transition and give its duration in milliseconds.
style::Elevationenum Elevation { Sm, Base, Md, .. }Selects a shadow depth from the theme.
style::RenderStylestruct RenderStyle { background_color, background_gradient, text_color, border_radius, border_width, border_top, .., border_color, shadow, opacity: u16, transform: Transform2D }Holds the resolved paint properties of one node. Opacity is in units of 1/10000.
style::TextDecorationenum TextDecoration { None, Underline, .. }Selects the line drawn with text.
style::ReactiveStateSlot, style::ReactiveStyleAtomstype ReactiveStateSlot = Rc<Cell<StateSlot>>; type ReactiveStyleAtoms = Rc<Cell<&'static [StyleAtom]>>Shared cells that let code change a node's state slot or style atoms without rebuilding the tree.
style::StyleEnginestruct StyleEngine<'theme>; apply(&self, &[StyleAtom], &mut RenderStyle), apply_text(&self, &[StyleAtom], &mut TextStyle), resolve_color(&self, ColorAtom) -> Rgba8Applies style atoms to paint and text styles against a theme and tone.
style::StyleReactiveEffectstruct StyleReactiveEffect; new()Holds a reactive atom channel that updates a node's style when its value changes.
style::unknown_class_warning_countfn unknown_class_warning_count() -> usizeNumber of unknown class names seen.
style::BORDER_WIDTH, style::DISABLED_OPACITY, style::ICON_SIZE, style::OVERLAY_SHADOWconst BORDER_WIDTH: Px = Px(1); const DISABLED_OPACITY: u16 = 5_000; const ICON_SIZE: Px = Px(20); const OVERLAY_SHADOW: Elevation = Elevation::MdDefault border width, disabled opacity, icon size, and overlay shadow for widgets.
style::spaceconst fn space(steps: u8) -> f32Converts a number of spacing steps to pixels.
style::StyleOverlaystruct StyleOverlay; new(), is_empty(), rest(), hover(), focus(), pressed(), disabled(), atoms_for(StateSlot) -> &[StyleAtom]Holds extra style atoms for each interaction state.
style::render_style_forfn render_style_for(id: NodeId, node: &Node, inherited: &Theme, inherited_text: Option<Rgba8>) -> RenderStyleResolves the paint style of a node from its style binding and theme.
style::text_style_forfn text_style_for(node: &Node, inherited: &Theme, base: &TextStyle) -> TextStyleResolves the text style of a node on top of a base text style.
style::scale::slate_light, style::scale::iris_light, style::scale::blue_light, style::scale::green_light, style::scale::amber_light, style::scale::ruby_light, style::scale::cyan_light, style::scale::slate_dark, style::scale::iris_dark, style::scale::blue_dark, style::scale::green_dark, style::scale::amber_dark, style::scale::ruby_dark, style::scale::cyan_darkconst fn slate_light() -> ColorScale (same shape for each)Return the built-in 12-step color scales for light and dark themes.
style::StateSlotenum StateSlot { Rest, Focused, Hovered, Pressed, Disabled }Names the interaction state that selects state style atoms.
style::StateStyleBuilderstruct StateStyleBuilderBuilds the paint for one interaction state. Implements Paint.
style::TextLineHeightenum TextLineHeight { FontSizeRelative(f32), Absolute(f32) }Gives line height as a multiple of font size or in pixels.
style::TextStylestruct TextStyle { font_family: String, font_size: f32, font_weight: u16, italic: bool, line_height: TextLineHeight, letter_spacing_em: f32, tabular_nums: bool, decoration: TextDecoration, runs: Option<TextRuns> }Holds the resolved typography of a text node.
style::TextFace, style::TextRun, style::TextRunsstruct TextFace { bold, italic, mono, .. }; struct TextRun { start: usize, end: usize, face: TextFace, .. }; struct TextRuns(pub Arc<[TextRun]>)Mark byte ranges of a text with bold, italic, or monospace faces.
style::is_typography_atomconst fn is_typography_atom(atom: StyleAtom) -> boolReturns true when a style atom changes text layout.
style::StyledTextEnginetrait StyledTextEngine: TextEngine { fn layout_paragraph_styled(&self, text: &str, max_width: Option<f32>, style: &TextStyle) -> Result<Self::Paragraph, Self::Error>; }Lays out a paragraph with a text style.
style::ThemeBuilderstruct ThemeBuilder; new(), tokens(&phf::Map<&str, ThemeValue>), token(&str, ThemeValue), build() -> ThemeBuilds a theme from named token values.
style::ToneContextstruct ToneContext { tone: Tone }; new(Tone)Carries the tone that descendants resolve tone colors against.
style::variant::VariantTokensstruct VariantTokens { radius: u16, shadows: bool, hover_lift: bool, font: FontFamilyHint }Holds the radius, shadow, hover, and font settings of a theme variant.
style::SOLID_VARIANT, style::SOFT_VARIANT, style::GHOST_VARIANTconst SOLID_VARIANT: StyleVariant (same for soft and ghost)Built-in solid, soft, and ghost style variants with their per-state atoms.
style::Pxstruct Px(pub i16)A pixel length in a style atom.
style::ColorOrTokenenum ColorOrToken { Rgba(Rgba8), Token(ColorKey), Atom(ColorAtom) }Color argument of the Paint methods. Converts from Token, Rgba8, and ColorAtom.
style::ColorKeyenum ColorKey { Token(Token), Custom(&'static str) }, ColorKey::parse(name)Typed key of a theme color. parse maps a built-in name to Token and any other name to Custom.
style::TokenTablestruct TokenTable { overrides: TokenLayer, theme: TokenLayer }The runtime override and theme layers of Theme::tokens.
style::TokenLayercolor(ColorKey), value(&str), insert(&str, ThemeValue), names()One layer: a fixed array per Token plus a map for custom names.
style::ThemeValueenum ThemeValue { Color(Rgba8), Px(f32), Ms(u16) }One theme token value.
style::StyleStatestruct StyleState { disabled, hovered, pressed, focused: bool }Interaction state for a style variant.
style::StateStyleStateStyle::new(rest, focused, hovered, pressed, disabled); with_rest(atoms), with_focused(atoms), with_hovered(atoms), with_pressed(atoms), with_disabled(atoms)Atoms per interaction state. Each with_* replaces the atoms of one state.
style::StyleVariantStyleVariant::new(base, states)Base atoms plus StateStyle.
style::NumericAtomKindenum NumericAtomKindA numeric style property that animate drives.

Module `tasks`

NameSignaturePurpose
tasks::installedfn installed() -> boolTells whether a task dispatcher is installed on this thread.
tasks::on_messagefn on_message<T: Send + 'static, F: Fn(T) + 'static>(rx: impl MessageReceiver<T>, f: F)Run f on the UI thread for each message, in the current owner. rx is a tokio UnboundedReceiver<T> or a bounded Receiver<T>.
tasks::on_message_or_closefn on_message_or_close<T: Send + 'static, F: Fn(T) + 'static, C: FnOnce() + 'static>(rx: impl MessageReceiver<T>, f: F, on_close: C)Like on_message. Runs on_close on the UI thread after the last message, when every sender is dropped.
tasks::OwnerHandleOwnerHandle::current() -> Option<OwnerHandle>, OwnerHandle::from_id(OwnerId), .is_alive() -> bool, .run(f) -> boolSend 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.

Module `terminal`

NameSignaturePurpose
terminal::Capsstruct Caps { color, graphics: Option<Protocol>, mux: Option<Mux>, keyboard, hyperlinks, underline_styles, borders, glyphs: Glyphs, ambiguous: Ambiguous, erase: Erase, cursor, sync, clipboard, backdrop, notices: Notices, fills: Fills }; Caps::detect(env), Caps::probe(), .host() -> HostCapsTerminal 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::capsfn 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::Eraseenum 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.
terminal::ColorDepth, terminal::Keyboard, terminal::ClipRoute, terminal::Borders, terminal::Cursorenum ColorDepth { Truecolor, Ansi256, Ansi16, Monochrome }; enum Keyboard { Legacy, Kitty }; enum ClipRoute { Pbcopy, Osc52 }; enum Borders { Rounded, Light, Ascii }; enum Cursor { Bar, Block }Capability fields of Caps: color depth, key protocol, clipboard route, border glyph set, and caret shape.
terminal::Fillsenum Fills { Partial, Whole }; Caps::fillsHow 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::Backdropenum Backdrop { Dark, Light }; Caps::backdrop: Option<Backdrop>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.
terminal::Glyphs, terminal::glyphsenum Glyphs { Unicode, Console, Ascii }; fn glyphs() -> Glyphs; Glyphs::glyph(self, char) -> char; Glyphs::text(self, &str) -> Cow<'_, str>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_clipboardfn install_clipboard(caps: Caps)Install the process clipboard for the terminal host, routed by caps.clipboard.
terminal::notify, terminal::progressfn notify(title: &str, body: &str) -> io::Result<()>; fn progress(value: Option<u8>) -> io::Result<()>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.
terminal::Notices, terminal::Notifystruct Notices { pub notify: Option<Notify>, pub progress: bool }; enum Notify { Osc9, Osc777 }The notification sequence and the tab-progress sequence (OSC 9;4) a terminal supports.
terminal::Mux, terminal::detect_muxenum Mux { Tmux, Screen }; fn detect_mux(env: impl Fn(&str) -> Option<String>) -> Option<Mux>Detect a terminal multiplexer from TMUX or STY, so graphics output can be wrapped for it.
terminal::Placementstruct Placement { col: u16, row: u16, cols: u16, rows: u16, source: ImageSource, crop: Option<(u32, u32)> }; .same(&other) -> boolAn image placed on the cell grid. same compares position and source.
terminal::blocks, terminal::blocks_window, terminal::sextants, terminal::sextants_windowfn blocks(source: &ImageSource, cols: usize, rows: usize) -> Vec<Vec<(Rgba8, Rgba8)>>; fn sextants(..) -> Vec<Vec<(char, Rgba8, Rgba8)>>; *_window(source, window: (u32, u32), cols, rows)Downsample an image to half-block or sextant cells for terminals without a graphics protocol. The window forms sample only a vertical pixel range.
terminal::png_window, terminal::base64fn png_window(source: &ImageSource, top: u32, height: u32) -> Vec<u8>; fn base64(bytes: &[u8]) -> StringEncode a vertical slice of an image as PNG, and encode bytes as base64 for graphics escape sequences.
terminal::key_down, terminal::map_keyfn key_down(key: impl Into<LogicalKey>) -> ShellEvent; fn map_key(event: &crossterm::event::KeyEvent) -> Option<ShellEvent>Build a key-press event, or translate a crossterm key event to a shell event.
terminal::cell_point, terminal::pointer, terminal::wheel, terminal::map_mousefn cell_point(col: u16, row: u16) -> Point; fn pointer(phase: PointerPhase, col: u16, row: u16) -> ShellEvent; fn wheel(col: u16, row: u16, lines: f32) -> ShellEvent; fn map_mouse(event: &MouseEvent, cell: f32, last: &mut Point) -> Option<ShellEvent>Convert cell coordinates to layout points and build pointer and wheel events, or translate a crossterm mouse event.
terminal::Cell, terminal::CONTINUESstruct Cell { text, fg: Ink, bg: Ink, bold, italic, dim, lines: Lines, underline_ink: Ink, link: Option<SmolStr> }; Cell::blank(); const CONTINUES: &str = ""One grid cell. A cell whose text is CONTINUES is the trailing half of a wide glyph.
terminal::Ink, terminal::Underlineenum Ink { Bare, Of(Tone), Exact(Rgba8) }; enum Underline { None, Straight, Curly }Cell color (unset, theme tone, or exact RGBA) and underline shape.
terminal::MarksMarks::collect(cx: &Cx, focus: Option<NodeId>, scene: &CommandScene, cell: f32) -> MarksCollect link targets and the caret node from a frame so the rasterizer can mark those cells.
terminal::Paint, terminal::raster_into, terminal::raster_withstruct Paint<'a> { theme: &Theme, cell: f32, caps: Caps, marks: &Marks }; fn raster_into(grid: &mut Grid, scene: &CommandScene, theme: &Theme, cell: f32); fn raster_with(grid: &mut Grid, scene: &CommandScene, paint: &Paint<'_>)Draw a scene into an existing grid. raster_with takes capabilities and marks as well as the theme.
terminal::EventPump, terminal::AfterFrametype EventPump<'a> = Box<dyn FnMut(&mut Vec<ShellEvent>) + 'a>; type AfterFrame<'a> = Box<dyn FnMut(&mut Host, &mut EventRouter, &Screen) + 'a>Callback types for Hooks: inject extra events before a frame, and run code after a frame is drawn.
terminal::calibratefn calibrate(out: &mut impl Write) -> io::Result<()>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.
terminal::renderfn render(out: &mut impl Write, prev: &Grid, next: &Grid, depth: ColorDepth) -> io::Result<()>Write the escape sequences that turn the prev grid into next at the given color depth.

Module `testing`

Feature kittest. For tests that drive the kernel by hand; app tests use sigil_kittest::Harness.

NameSignaturePurpose
testing::with_cx, testing::with_runtimefn with_cx(name: &'static str, f: impl FnOnce(&mut Cx)); fn with_runtime(name: &'static str, f: impl FnOnce(&Runtime))Run f inside a fresh reactive runtime, with a root Cx for with_cx.
testing::tree_sizefn tree_size(name: &'static str, root: impl IntoNode) -> usizeCount the nodes a tree mounts.
testing::tick_intervalsfn tick_intervals() -> usizeFire every due interval and return how many fired. A hand-driven frame loop calls it where Host::frame would.

Module `text`

NameSignaturePurpose
text::WebFont, text::WebFontScriptstruct WebFont { script: WebFontScript, url: String, face_index: u32 }, WebFont::new(script, url, face_index), WebFont::noto_defaults(); enum WebFontScript { Cjk, Arabic, Hebrew, Devanagari, Khmer, Thai, Lao }One web fallback face and the script it covers. The Noto defaults pin exact commits on jsDelivr.
text::set_web_fallbacks, text::web_fallbacksfn set_web_fallbacks(fonts: impl IntoIterator<Item = WebFont>); fn web_fallbacks() -> Vec<WebFont>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.
text::TextConfigstruct TextConfig { font_family: String, font_size: f32, font_weight: u16, line_height: f32 }; fn text_style(&self) -> TextStyleHolds basic font settings and converts them to a TextStyle.
text::prefer_system_fontsfn prefer_system_fonts()Switches the default fonts to system fonts unless the app already set them.
text::Paragraphstruct Paragraph (Clone)Holds a shaped, line-broken text block. Implements ParagraphMetrics.

Module `widgets`

NameSignaturePurpose
widgets::ButtonGlyphenum ButtonGlyph { Text(TextContent), Icon(Icon) }; From text and From<Icon>What icon_button shows.
widgets::spinner_framefn spinner_frame(tick: u64) -> &'static strThe spinner glyph for a tick count.
widgets::icon_svgfn icon_svg(svg: impl Into<Rc<str>>) -> IconBuilderAn SVG icon. Its color comes from the tone and the active theme at paint time.
widgets::TreeNodestruct TreeNode<K>; new(id, label), .leading(icon), .status(text, Tone), .detail(text), .tone(RowTone), .children(iter), .child(node)One node of a tree. leading takes an Icon or a text glyph.
widgets::TreeBuilderstruct TreeBuilder<K>; .expanded(Signal<Vec<K>>), .selected(Signal<Option<K>>), .activate(impl Fn(&K)), .indent(cols), .label(name)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::TreeKeytrait TreeKey: Clone + Eq + Hash + 'staticThe key type of tree nodes; implemented for every such type.
widgets::TreeRowstruct TreeRow<K> { id, depth, disclosure, selected, parent, .. }; has_children()One visible row of a flattened tree.
widgets::IconSourcestruct IconSource; trait IntoIconSourceWhat icon accepts: a bundled Icon or any text glyph.
widgets::layout_ext::LayoutOverridesstruct LayoutOverrides; const fn new() -> SelfWidth, 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.
widgets::HintEntrytype HintEntry<'a> = (&'a str, &'a str)One key and label pair for the hint overlay.
widgets::ChangeKindenum ChangeKind { Added, Modified, Deleted }Line change mark in the code_edit gutter.
widgets::DiagSeverity, widgets::DiagSpanenum DiagSeverity { Hint, Info, Warning, Error }; struct DiagSpan { line: usize, start: usize, end: usize, severity: DiagSeverity }Diagnostic range that code_edit underlines, with its severity.
widgets::parse_hex, widgets::to_hexfn parse_hex(input: &str) -> Option<Rgba8>; fn to_hex(color: Rgba8) -> StringParse #rgb or #rrggbb to an opaque color, and format a color as #rrggbb.
widgets::PaneBuilderstruct PaneBuilder; const fn initial(self, px: f32) -> Self; const fn min(self, px: f32) -> Self; max(px), grow(factor), pane(node) -> PaneBuilder, commit() -> SplitterBuilderConfigures one pane of a splitter before it is committed. pane commits this pane and starts the next.
widgets::ColumnLayoutstruct ColumnLayout { order: Vec<usize>, hidden: HashSet<&'static str>, widths: HashMap<&'static str, f32> }Column order, hidden columns, and column widths of a TableState.
widgets::MIN_COL_WIDTHconst MIN_COL_WIDTH: f32 = 48.0Smallest width a table column can be resized to.
widgets::MAX_VISIBLE, widgets::TOAST_TTLconst MAX_VISIBLE: usize = 4; const TOAST_TTL: Duration = Duration::from_secs(4)Maximum toasts shown at once and how long a toast stays before it expires.
widgets::IntoList, widgets::virtual_list_bindtrait IntoList<T, R: RowRender<T>> { fn into_list(self, render: R) -> VirtualListBuilder<T, R>; }; fn virtual_list_bind<S, T, R: Fn(usize, &T) -> N, N: IntoNode>(items: Signal<S>, render: R) -> VirtualListBuilder<T, R>IntoList lets virtual_list take a Vec<T> or a signal of a slice. virtual_list_bind builds a list bound to a signal.
widgets::interactionmod interactionHover, press, and focus state of a widget.
widgets::ButtonBuilderprimary(), outline(), ghost(), soft(), neutral(), destructive(), icon_svg(svg), activate(f), size(ControlSize), disabled(impl Reactive<bool>); ButtonBuilder::new(label), solid(), tone(Tone), theme(Theme), accessible(name), pending(Signal<bool>)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.
widgets::CheckboxBuilderstruct CheckboxBuilder; indeterminate(Signal<bool>); CheckboxBuilder::new(Signal<bool>), label(text), change(Fn(bool)), disabled(impl Reactive<bool>), tone(Tone), theme(Theme)Builder of a checkbox. A 16 px box with an on-accent mark. indeterminate draws a dash while the signal is true. Table selection uses the same box.
widgets::ToggleBuilderstruct ToggleBuilder; label(text), accessible(name); ToggleBuilder::new(Signal<bool>), change(Fn(bool)), disabled(impl Reactive<bool>), theme(Theme)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::SegmentedBuilderstruct SegmentedBuilder; label(name)Builder of a segmented control. The default height is 32 px; set it with WidgetLayoutExt::height.
widgets::SidebarBuilderstruct SidebarBuilder; resizable(min: f32, max: f32), plus Paint and WidgetLayoutExtBuilder 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.
widgets::RadioGroupBuilderstruct RadioGroupBuilder; RadioGroupBuilder::new(Signal<String>), option(key, label), disabled(impl Reactive<bool>), tone(Tone)Builder of a radio group. Each option adds one radio button. The selected signal holds the key of the selected option.
widgets::SliderBuilderstruct SliderBuilder; step(f32), length(f32), label(text), marks(labels), change(fn); SliderBuilder::new(Signal<f32>, RangeInclusive<f32>), orientation(Orientation), disabled(impl Reactive<bool>), glass(), theme(Theme)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.
widgets::TextFieldBuilderstruct TextFieldBuilder; autofocus(), focus_when(Signal<u64>), focus_caret(FocusCaret); TextFieldBuilder::new(Signal<String>), placeholder(text), change(Fn(&str)), submit(Fn(&str)), blur(Fn()), disabled(impl Reactive<bool>), invalid_when(impl Reactive<bool>), password(), reveal(Signal<bool>), clipboard(impl Clipboard), caret_visible(&mut self) -> Signal<bool>, scroll_offset(&mut self) -> Signal<f32>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.
widgets::TextEditBuilderstruct TextEditBuilder; TextEditBuilder::new(Signal<String>), placeholder(text), change(Fn(&str)), submit(Fn(&str)), submit_on(SubmitKey), disabled(impl Reactive<bool>), state(TextEditState), caret_position(Signal<usize>), caret_visible(&mut self) -> Signal<bool>, chrome(bool), content_padding(horizontal, vertical), clipboard(impl Clipboard)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::TextEditStateTextEditState::new(value, caret: Signal<usize>)Caret and undo state of a text editor.
widgets::FocusCaretenum FocusCaret { Keep, End, SelectAll }Where TextFieldBuilder::focus_caret puts the caret when autofocus or focus_when focuses the field.
widgets::NumberFieldBuilderstruct NumberFieldBuilder<T>; disabled(impl Reactive<bool>), invalid_when(impl Reactive<bool>), text_field() -> TextFieldBuilderBuilder of a numeric input. text_field() returns the inner text field, invalid while the text is out of range, for further text field options.
widgets::DateFieldBuilderstruct DateFieldBuilder; disabled(impl Reactive<bool>), invalid_when(impl Reactive<bool>), text_field() -> TextFieldBuilderBuilder of a date input. text_field() returns the inner text field, invalid while the text is not a date.
widgets::ColorFieldBuilderstruct ColorFieldBuilder; disabled(impl Reactive<bool>), invalid_when(impl Reactive<bool>)Builder of a color input.
widgets::ChipBuilderstruct ChipBuilder; tone(impl Reactive<Tone>), activate(f); into_node_builder() -> NodeBuilder, layout(LayoutStyle) -> NodeBuilderBuilder of a chip. A signal or closure passed to tone retints the chip when it changes. layout returns a NodeBuilder, so it comes last.
widgets::InteractiveBuilderstruct InteractiveBuilder; focusable(bool), disabled(impl Reactive<bool>), into_node_builder() -> NodeBuilderBuilder of an interactive node.
widgets::interaction::InteractionStateInteractionState::new(enabled: bool)Hover, press, and focus signals.
widgets::DropdownBuilderstruct DropdownBuilder; DropdownBuilder::new(Signal<usize>, Vec<String>), change(Fn(usize)), label(text), disabled(impl Reactive<bool>)Builder of a select box.
widgets::MenuBuilderstruct MenuBuilder; host(owner); MenuBuilder::new(Signal<bool>), item(MenuItem), separator(), label(text), anchor(x, y)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.
widgets::MenuBarBuilderstruct MenuBarBuilder; menu(label, IntoIterator<Item = MenuItem>)Builder of a menu bar.
widgets::CommandMenuBuilderstruct CommandMenuBuilder; placeholder(text), item(label, Fn()), disabled(label), submenu(label, FnOnce(SubmenuBuilder) -> SubmenuBuilder), submit(Fn(&str)), cancel(Fn())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.
widgets::SubmenuBuilderstruct SubmenuBuilder; item(label, Fn()), disabled(label), submenu(label, FnOnce(Self) -> Self)Builder of a command palette submenu.
widgets::FuzzyMatchstruct FuzzyMatch { score: usize, positions: Vec<usize> }Result of fuzzy_score.
widgets::TableBuilderstruct TableBuilder<Row>; framed(bool), row_activate(impl Fn(&Row) + 'static), selectable_checkboxes(); density(Density), striped(), row_height(len), header_height(px), viewport_height(len), viewport_width(px), viewport_fill(), scroll_bind(Signal<f32>), row_menu(Fn(&Row) -> Vec<MenuItem>), empty(Fn() -> NodeBuilder), disabled(impl Reactive<bool>)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.
widgets::ColAlignenum ColAlign { Start, End }Column alignment.
widgets::VirtualListBuilderstruct VirtualListBuilder<T, R>; measured(), estimate(len), scroll_bind(Signal<f32>), follow_row(Signal<usize>), content_height_bind(Signal<f32>), max_scroll_bind(Signal<f32>), cursor(Signal<usize>), identified(), follow_end(bool), initial_scroll(ScrollAnchor), scroll_into_view(index); row_height(len), item_height(Fn(usize, &T) -> f32), overscan(pages), key_by(Fn(usize, &T) -> u64), viewport_height(len), viewport_width(px), viewport_fill(), shrink_to_content(), scrollbar(bool), scroll_x_bind(scroll_x, max, width), keyboard(bool), selection(SelectionMode), selection_state(&mut self) -> Signal<SelectionState>, change(Fn(usize))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.
widgets::RowRendertrait RowRender<T> { type Row: IntoNode; fn row(&self, index: usize, item: &T) -> Self::Row; }Row renderer of a virtual list. Every Fn(usize, &T) -> N with N: IntoNode implements it.
widgets::ScrollAnchorenum ScrollAnchor { Top, Bottom, Index(usize) }Where a virtual list stays scrolled.
widgets::SelectionStateSelectionState::new(mode: SelectionMode); click(index), ctrl_click(index), shift_click(index); contains(index) -> bool, selected_indices() -> impl Iterator<Item = usize>, mode() -> SelectionModeSelected indexes of a list.
widgets::ListColumnListColumn::new(text, width); start(); From<(TextContent, f32)>One fixed-width column of a list row. Columns align to the end unless start() is set.
widgets::RowToneenum RowTone { Normal, Muted, Header }Text tone of a list row. Muted dims an unavailable row. Header labels columns and takes no hover or selection.
widgets::TabsBuilderstruct TabsBuilder; tab(label, component), labels(impl Reactive<Vec<S>>), active(Signal<usize>), pill(), justify_list(JustifyContent), into_container() -> NodeBuilder; line(), theme(Theme), disabled(&[usize]), closeable(bool), close(Fn(usize)), reorderable(bool), order(Signal<Vec<usize>>)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.
widgets::FieldBuilderstruct FieldBuilder<C>; error(impl Reactive<Option<String>>)Builder that field returns.
widgets::FieldControltrait FieldControl { fn invalid_when(self, impl Reactive<bool>) -> Self; }A control that can paint an invalid state: text_field, number_field, color_field. field(..).error(..) needs one.
widgets::CodeEditBuilderstruct CodeEditBuilder; highlights(Signal<Vec<Vec<HlSpan>>>), diagnostics(Signal<Vec<DiagSpan>>), gutter(Signal<Vec<Option<ChangeKind>>>), selection(Signal<Option<(usize, usize)>>), key(Fn(&mut KeyEvent)), row_height(f32), disabled(impl Reactive<bool>)Builder of a code editor. selection holds the selection anchor as (line, column). key runs for key events in the editor and makes Tab stay in it.
widgets::HlSpanstruct HlSpan { start: usize, end: usize, token: &'static str }A highlight span in a code line.
widgets::Highlightstruct Highlight { start: usize, end: usize, token: Token }One syntax mark: a byte range and its theme token.
widgets::MarkdownEditBuilderstruct MarkdownEditBuilder; disabled(impl Reactive<bool>)Builder of a markdown editor.
widgets::DiffBuilderstruct DiffBuilder; change(f: impl Fn(DiffView)); view(DiffView), path(text), status(text), max_rows(n), wrap(bool)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.
widgets::PanelBuilderstruct PanelBuilder; PanelBuilder::new(), title(text), child(impl IntoNode), padding(px), elevation(tier)Builder of a panel. elevation takes 0 to 3.
widgets::SplitterBuilderstruct SplitterBuilder; child(node, initial), pane(node), child_constrained(node, initial, min, max); min_size(index, px), max_size(index, px), snap_points(handle, &[f32]), snap_threshold(px), sizes_bind(Signal<Vec<f32>>)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::ScrollBuilderstruct 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.
widgets::HintOverlayBuilderstruct HintOverlayBuilder; HintOverlayBuilder::new(&[HintEntry]), entry(chord, description)Builder of a key hint overlay.
widgets::TooltipBuilderstruct TooltipBuilder; TooltipBuilder::new(label), child(target), shortcut(Option<text>), delay(ms), clamp_top(), theme(Theme)Builder of a tooltip. child is the node that shows the tooltip on hover. clamp_top() shows the tooltip below the target instead of above.
widgets::ToastEntrystruct ToastEntry { level: ToastLevel, message: String }One queued toast.
widgets::ToastLevelenum ToastLevel { Info, Success, Warning, Error }Toast severity.
widgets::ProgressBuilderstruct ProgressBuilder; tone(t), label(name), indeterminate(); ProgressBuilder::new(Signal<f32>, max)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.
widgets::GaugeBuilderstruct GaugeBuilder; GaugeBuilder::new(Signal<f32>), max(f32), label(text), warn(ratio)Builder of a gauge. warn paints the fill in the warning color while value / max is below the ratio.
widgets::ChartBuilderbar(), line(), labels(impl IntoIterator<Item = impl Into<String>>), series(name, values: impl Reactive<Vec<f32>>, tone); tone(Tone)Builder of a chart. WidgetLayoutExt::width and height set its size (default 280×180, minimum 80×48).
style::ControlSizeenum ControlSize { Compact, Default, Wide, Grow }Size step of a control. Metrics and Theme map it to height, width, padding, gap, and radius.
widgets::ChartMarkenum ChartMark { Bar, Line, Candle }Chart mark.
widgets::SparklineBuilderrange(low, high), tone(t), tones(impl IntoIterator<Item = Option<Tone>>), mark(SparkMark), fill(SparkFill), rows(n: usize)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::SparkMarkenum 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::SparkFillenum 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.
widgets::DotBuilderstruct DotBuilder; DotBuilder::new(Tone), size(ControlSize)Builder of a status dot.
widgets::IconBuildertone(t), size(s), px(px), strong(); IconBuilder::new(glyph), label(text)Builder of an icon. px sets an exact icon size. strong uses the high-contrast step of the tone scale.
widgets::PathCmdenum PathCmd { MoveTo, LineTo, QuadTo, CubicTo, Close }One path command.
widgets::PathFillenum PathFill { Solid, Theme, Linear, Radial }Path fill paint. Theme(Token) resolves at paint time.
widgets::PathColorenum PathColor { Rgba(Rgba8), Token(Token) }Color of fill and stroke. A Token follows the active theme.
widgets::DRAG_THRESHOLD_PXconst DRAG_THRESHOLD_PX: f32 = 4.0Pointer travel before a drag starts.
widgets::DROP_TARGET_CLASSconst DROP_TARGET_CLASS: &strClass on a drop target under the pointer.

Jobs to symbols

JobSymbol
Import the application surfaceuse sigil::prelude::*;
Open a window and run the frame loopsigil::run(config, tree) (feature desktop)
Run the tree in a terminalsigil::run(AppConfig::new(title).terminal(), tree) (feature terminal)
Run the terminal host inline instead of on the alternate screenAppConfig::terminal().inline(true); Hooks::region_rows through AppConfig::terminal_hooks sizes the live region
Run the tree in a browsersigil::run(config, tree) built for wasm32-unknown-unknown (Web host)
<canvas>AppConfig::canvas(id) (browser host; native hosts ignore it)
Open a file or URL with the operating system handlersigil::app::open(target) (feature desktop)
Stop the applicationsigil::request_exit(); in the terminal host it also works from a terminal::Hooks callback
Send a window commandrequest_window_command, WindowCommand (feature desktop)
Embed the tree in another engineRuntime::scope, Host::new, Host::mount
Patch the running app when the code changesfeature hot, dx serve --hot-patch (Hot reload)
Route an input event to an embedded treeHost::route(&mut EventRouter, ShellEvent)
Run an accessibility action on an embedded treeHost::perform(&mut EventRouter, NodeId, &accesskit::ActionRequest)
Lay out and paint an embedded treeHost::layout, then Host::emit(viewport) for the CommandScene; Host::scene(viewport) does both
Draw a scene onto a cell gridsigil::terminal::raster(&scene, host.theme(), cols, rows, cell) (feature terminal)
Get the rectangles of host-drawn surfacessurface(key) in the tree, then Host::surfaces
Get the accessibility tree of an embedded treeHost::accessibility_tree
Pump external events into the terminal loop, or run code after each framesigil::run(config.terminal().terminal_hooks(Hooks { .. }), tree)
$EDITORsigil::terminal::suspend(f) -> io::Result<R>
Commit lines above the inline live region into scrollbacksigil::terminal::print_above(text) -> io::Result<()>
terminal::print_above, NotLive, FullScreen, io::ErrorKind::Unsupported, err.get_ref()?.downcast_ref()sigil::terminal::PrintAboveError
Set the terminal window titlesigil::terminal::set_title(title) -> io::Result<()>
Ring the terminal bell, with an optional desktop notificationsigil::terminal::bell(note: Option<&str>) -> io::Result<()>
Send a terminal desktop notificationsigil::terminal::notify(title, body) -> io::Result<()>
Show progress in the terminal tabsigil::terminal::progress(Some(percent)) -> io::Result<()>
Handle pasted text on a node.on_paste(f) from NodeEventsExt
Check whether the terminal window has focussigil::terminal::focused() -> bool
Send Ctrl+C to the tree instead of exitingAppConfig::quit_on_ctrl_c(false)
Set the terminal frame interval (default 1/60 s, 60 Hz)AppConfig::frame_interval(Duration)
Drags, Offsigil::terminal::set_mouse_capture(yes) -> io::Result<()>
Pick which terminal mouse reports the app receivessigil::terminal::set_mouse_tracking(tracking: MouseTracking) -> io::Result<()>
Render one terminal frame to a stringsigil::terminal::present(tree, cols, rows, events)
Drive the terminal host one step at a timesigil::terminal::step, Host::cells
Detect the terminal graphics protocolsigil::terminal::detect, sigil::terminal::Protocol
Bind a key on a node.key(shortcut, handler) from NodeEventsExt
Bind a key that fires from anywhere.shortcut(shortcut, handler) from NodeEventsExt
See every key before the focused descendant.key_capture_any(handler); call event.stop_propagation() to keep the key from the target
Run a callback on a fixed periodinterval(Duration, f) -> IntervalId, sigil::reactive::cancel_interval
Run a callback once after a delaysigil::reactive::timeout(Duration, f) -> IntervalId
Load data on demand and show loading and errorstask(make), Task::run, Task::cancel, Task::status, kernel::match_status
Stream results from a backend threadsignal_writer(signal), SignalWriter::update
Apply a themeparse_theme, set_theme, watch_theme, AppConfig::theme_file
Name a theme color in codesigil::style::Token (Token::Surface.bg(), Token::Ring.color())
Theme a table header or row dividerToken::TableHeader (table-header), Token::BorderSubtle (border-subtle)

Terminal rasterizer

The terminal host draws the same CommandScene as the window. Widgets do not branch on the host. The rasterizer maps each command to cells:

Scene commandCells
RectCell background. A leaf rect fills with a full block. A rect thinner than one cell draws ─ or │.
Rect, scene::CellBorderBox-drawing glyphs on each side whose width is above zero. A rounded border uses rounded corners.
scene::GlyphRunText cells with bold and italic. TextFlow selects one line, wrap, or ellipsis.
ImageThe detected graphics protocol, or sextant glyphs. The crop and the clip apply.
PushClip, PushLayerClip the commands inside.
SaveLayer, PushLayerBlend fills, borders, and text against the cell below, with the active theme.
Shadow, gradient, pattern, sprite, decorationNot drawn.

TopLayer content comes last in the scene, so it draws above clipped content.

App bundles

Package sigil-sign, library sigil_sign. Guide: Signing.

NameSignaturePurpose
sigil_sign::AppBundleFields: name, identifier, version, executable, exe_name, icon, provisioning_profile: Option<&Path>, min_systemBundle metadata and inputs. Set provisioning_profile to None when no macOS profile is required.
sigil_sign::CodeSignFields: identity: Option<&str>, entitlements: Option<&Path>; .sign(path: &Path) -> Result<(), PackError>Native macOS signing for an executable or a completed .app. None selects ad-hoc signing. Profiles belong to AppBundle.
sigil_sign::macos_appfn macos_app(app: &AppBundle<'_>, resources: &[ResourceCopy<'_>], dest: &Path, sign: &CodeSign<'_>) -> Result<(), PackError>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 -.
sigil_sign::windows_dirfn windows_dir(app: &AppBundle<'_>, resources: &[ResourceCopy<'_>], dest: &Path) -> Result<(), PackError>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

TypeReturned byMeaning
sigil::Errorsigil::runOpaque 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::ScheduleErrorSignalWriter::set, SignalWriter::updateClosed: the dispatcher is closed. Full: the dispatcher queue is full.
layout::LayoutErrorHost::layout, Host::scene, sigil::terminal::present, sigil::terminal::stepThe layout pass failed. It converts into sigil::Error.
sigil_sign::SignErrorsign_file, verify_fileKeyFile, 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::PackErrormacos_app, windows_dirMissing, Io, Codesign, Escape, Symlink, Occupied, or NotFile.

Test harness

Package sigil-kittest, library sigil_kittest. Guide: Testing.

NameSignaturePurpose
sigil_kittest::HarnessHarness::new(app: impl IntoNode + 'static) -> Harness; .size(cols: u16, rows: u16); .pixels(width: u32, height: u32)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.
Harness::gpufn gpu(self, width: u32, height: u32, scale: f32) -> SelfPaint 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.
Harness::send, Harness::settle, Harness::advancefn send(&mut self, events: impl IntoIterator<Item = ShellEvent>) -> &mut Self; fn settle(&mut self) -> &mut Self; fn advance(&mut self, by: Duration) -> &mut SelfRoute 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.
Harness::click, hover, scroll, dragfn click(&mut self, target: &(impl Target + ?Sized)) -> &mut Self; fn scroll(&mut self, target: &(impl Target + ?Sized), lines: f32); fn drag(&mut self, from: &(impl Target + ?Sized), to: &(impl Target + ?Sized))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.
Harness::press, press_with, type_text, type_into, focus_next, focus_previousfn press(&mut self, key: impl Into<LogicalKey>) -> &mut Self; fn press_with(&mut self, key, modifiers: ModifiersState); fn type_text(&mut self, text: &str); fn type_into(&mut self, label: &str, text: &str)Key down and up, one key per character, or Tab and Shift+Tab. type_into clicks the control with that label, then types. Each action settles.
Harness::expect_textfn expect_text(&mut self, text: &str) -> &mut SelfWait until a node's name or value is text, running frames that apply finished tasks, up to EXPECT_TIMEOUT; then fail with the tree dump.
Harness::get, get_by_role, get_by_text, query, find_all, focused, refreshfn get_by_role(&mut self, role: Role, name: &str) -> Node; fn get_by_text(&mut self, text: &str) -> Node; fn find_all(&mut self, query: &Query) -> Vec<Node>; fn refresh(&mut self, node: &Node) -> Option<Node>Query the accessibility tree. get* fails the test with the tree dump unless exactly one node matches. Text runs and hidden nodes are skipped.
Harness::misalignments, Harness::assert_alignedfn misalignments(&mut self) -> Vec<Misalignment>; fn assert_aligned(&mut self)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.
Harness::text, accessibility_snapshot, accessibility_tree, image, hostfn text(&mut self) -> String; fn image(&mut self) -> Rendered; fn host(&mut self) -> (&mut Host, &mut EventRouter)The terminal grid text (the accessibility dump on a pixel harness), the tree, the offscreen image, or the host for anything else.
Harness::snapshot, snapshot_with, sigil_kittest::SNAPSHOT_MAX_DELTA_PCTfn snapshot(&mut self, name: &str); fn snapshot_with(&mut self, name: &str, max_delta_pct: f32); const SNAPSHOT_MAX_DELTA_PCT: f32 = 0.5Compare with tests/goldens/<name>.txt (cells) or <name>.png (pixels). SIGIL_REGEN_GOLDENS=1 rewrites them.
sigil_kittest::Noderole(), name(), value(), numeric(), bounds(), center(), is_focused(), is_checked(), is_selected(), is_expanded(), is_disabled()A snapshot of one accessibility node at query time. The name follows labelled_by when the node has no label.
sigil_kittest::QueryQuery::role(role), Query::text(text), .name(name)Match by role, accessible name, or text (name or value).
sigil_kittest::Targettrait Target { fn point(&self, ui: &mut Harness) -> Point } for str, Node, and PointWhere a pointer action lands. A str is a label: the one control whose name or value it is, else the one node. A label on two controls fails.
sigil_kittest::EXPECT_TIMEOUTconst EXPECT_TIMEOUT: Duration (5 s)How long expect_text and a label target wait.
sigil_kittest::assert_text_matches_goldenfn assert_text_matches_golden(actual: &str, golden: &Path)Text golden compare with the same regen switch as PNG goldens.
sigil_kittest::inputpointer_move, pointer_drag, pointer_down, pointer_up, click, key_event, key_down, chord, press, type_char, type_text, tab, scroll_lines, window_blur, ime_eventThe 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.

opRequestReply
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::clickcol/row (terminal cells) or x/y (points), buttonMoves, presses, and releases the pointer through the normal router.
move, down, upsame coordinatesOne pointer phase.
widgets::scrollcoordinates plus dx/dy in linesA scroll event.
keykey (a NamedKey name or one character), ctrl/shift/alt/metaKey down and up.
typetextKey events per character.
profilelast (frame count, default 30)enabled, frames (index, cause, wall_ms, per-phase ms, counters, backend), and summary (the exit report text).
profile_dumppath (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.
hudon (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.