oxiui — The COOLJAPAN Pure-Rust GUI facade

oxiui is the top-level façade crate for OxiUI — the COOLJAPAN Pure-Rust UI layer with no GTK (C), no Qt (C++), no SDL (C), no system widgets, and no raw AppKit / Win32 / Cocoa bindings. It wraps the immediate-mode widget API from oxiui-core, selects a render + framework backend through Cargo features, and re-exports everything an application needs behind one builder: App. By default it boots an egui application rendered via wgpu; alternative backends (iced, Dioxus, software) are opt-in. The wasm32 / browser entry point is the separate unpublished oxiui-web copy-template, not a facade feature. (A Slint adapter exists as the standalone oxiui-slint crate — it is a KNOWN-NON-PURE, direct-opt-in dependency, not a facade feature; see 0.2.0 removal notice.)

The facade is the only crate most applications depend on. It owns the application life-cycle: window configuration (AppConfig), the event loop (App::run), headless rendering for CI (App::run_headless_once, App::screenshot), and cross-cutting features — plugins (Plugin), global hotkeys (HotkeyRegistry), a fuzzy-searchable command palette (CommandPalette), and a toast NotificationQueue. GPU drivers (Vulkan/Metal/DX12/WebGPU) are OS-provided at runtime and do not appear in cargo tree --edges normal, keeping the build Pure Rust.

Default-features note (GOVERNANCE §6): default = ["gpu", "egui"]. A zero-feature facade build must select at least one Pure adapter (ADAPTER_PATTERN §3 rule 4), mirroring precedents such as oxicrypto's default = ["pure"] and oxitls's default = ["pure", "webpki-roots"]. For a strictly minimal / ffi-audit build use --no-default-features --features software.

Installation

[dependencies]
# Default: egui + wgpu native app
oxiui = "0.2.1"

# Headless / ffi-audit: CPU softbuffer framebuffer, no GPU stack at build time
oxiui = { version = "0.2.1", default-features = false, features = ["software"] }

# iced retained-mode backend
oxiui = { version = "0.2.1", features = ["iced"] }

# Everything: tables, accessibility, plus the iced backend
oxiui = { version = "0.2.1", features = ["iced", "table", "a11y"] }

Quick Start

egui backend (default)

use oxiui::{App, AppConfig};

App::new(AppConfig::new().title("Hello OxiUI"))
    .theme(oxiui::theme::cooljapan_default())
    .content(|ui| {
        ui.heading("Hello, world!");
        if ui.button("Quit").clicked { /* exit logic */ }
    })
    .run()
    .expect("UI error");

iced backend

use oxiui::{App, AppConfig, Backend};

App::new(AppConfig::new().title("Hello OxiUI (iced)"))
    .theme(oxiui::theme::cooljapan_default())
    .backend(Backend::Iced)
    .content(|ui| {
        ui.heading("Hello from iced!");
        if ui.button("Quit").clicked { std::process::exit(0); }
    })
    .run()
    .expect("UI error");

Headless (CI-friendly, no display)

use oxiui::{App, AppConfig};

let exit = App::new(AppConfig::new().title("smoke"))
    .content(|ui| { ui.heading("h"); })
    .run_headless_once()?;
assert_eq!(exit, oxiui::AppExit::Ok);
# Ok::<(), oxiui::UiError>(())

Backend Selection

The active backend is chosen with App::backend and the Backend enum. The default is Backend::Egui. Each non-default variant is gated behind its own Cargo feature; the variant is only present when its feature is enabled.

There is no Backend::Slint variant — the slint feature was removed from the facade in 0.2.0 because oxiui-slint is a KNOWN-NON-PURE adapter (pulls in a C fontconfig binding on Linux via slint → parley/fontique). Use the standalone oxiui-slint crate directly instead.

The egui-on-wasm32 path is not driven through App::run (which returns UiError::Unsupported on wasm32); instead use oxiui_web::mount from the unpublished oxiui-web copy-template in a browser binary.

API Overview

Application builder

App builder methods

Cross-cutting feature types

Pluggable runner infrastructure (oxiui::runner)

EguiRunner / IcedRunner own the live event loops: App::run() moves its theme, hooks, and plugins into the matching runner and delegates via BackendRunner::run. A runner::LifecycleTracker deduplicates window size/focus/close snapshots so on_resize / on_focus fire only on real changes and on_close fires at most once.

Re-exported modules

Crate-root re-exports

From oxiui-core at the crate root: ButtonResponse, Color, FontSpec, Palette, Theme, UiCtx, UiError. From runner: BackendRunner, LifecycleConfig (always), plus EguiRunner (egui) and IcedRunner (iced). From theme_picker: theme_by_name, theme_picker, BUILTIN_THEMES. From multiwindow: SecondaryWindow. From dialog: DialogId, DialogKind, DialogQueue, DialogResponse. From menu: Menu, MenuBar, MenuBarBuilder, MenuItem. From native_dialog: DialogResult, MessageLevel.

Web (wasm32) entry point

The facade itself does not mount a browser canvas. On wasm32, App::run returns Err(UiError::Unsupported) directing you to oxiui_web::mount(canvas_id). That entry point lives in the unpublished oxiui-web crate (publish = false), which is provided as a copy-template for your own wasm app rather than a crates.io dependency. See its README for the browser API and build steps.

Feature Flags

Features fall into two groups: render backends (how pixels reach the screen) and framework backends (which widget framework drives the frame), plus optional capability modules.

Render backends

Framework backends

No slint feature. The facade's slint feature was removed in 0.2.0 — oxiui-slint pulls in a C fontconfig binding (yeslogic-fontconfig-sys) on Linux with no pure opt-out, so it can no longer be aggregated into the facade's Pure Rust closure. Use the standalone oxiui-slint crate directly instead.

Capability modules

Note: there is no web feature. The wasm32 browser entry point lives in the unpublished oxiui-web crate (publish = false), used as a copy-template — see Web (wasm32) entry point above.

Errors

App methods return Result<_, oxiui_core::UiError>. UiError is #[non_exhaustive].

A separate HotkeyConflict error (its own std::error::Error type) is returned by App::try_hotkey / HotkeyRegistry::register on a duplicate (Modifiers, Key) binding.

Examples

The crate ships runnable examples (see examples/):

cargo run --example hello                              # egui (default)
cargo run --example hello_iced   --features iced       # iced backend
cargo run --example hello_table  --features table      # table widget
cargo run --example hello_dioxus --features dioxus     # Dioxus adapter

Related Crates

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)