Rxi's Microui Port to Idiomatic Rust

This project started as a C2Rust conversion of Rxi's MicroUI and has since grown into a Rust-first UI toolkit. It preserves the immediate-mode feel while using stateful widget structs with stable IDs, a row/column layout helper API, and backend-agnostic rendering hooks.

Compared to microui-rs, this crate embraces std types, closure-based window/panel/column scopes, and richer widgets such as custom rendering callbacks, dialogs, and a file dialog.

Demo

Clone and build the demo (enable exactly one backend feature):

$ cargo run --example demo-full --features example-vulkan   # Vulkan backend
# or
$ cargo run --example demo-full --features example-glow     # Glow backend

Key Concepts

• Context: owns the renderer handle, user input, and root windows. The atlas is provided by the renderer and accessed through the context. Each frame starts by feeding input into the context, then calling context.window(...) for every visible window or popup.
• Container: describes one layout surface. Every window, panel, popup or custom widget receives a mutable Container that exposes high-level widgets (buttons, sliders, etc.) and lower-level drawing helpers.
• Layout manager: controls how cells are sized. Container::with_row lets you scope a set of widgets to a row of SizePolicys, while nested columns can be created with container.column(|ui| { ... }).
• Widget: stateful UI element implementing the Widget trait (for example Button, Textbox, Slider). These structs hold interaction state and supply stable IDs.
• Renderer: any backend that implements the Renderer trait can be used. The included SDL2 + glow example demonstrates how to batch the commands produced by a container and upload them to the GPU.

let mut name = Textbox::new("");
ctx.window(&mut main_window, ContainerOption::NONE, WidgetBehaviourOption::NONE, |ui| {
    let widths = [SizePolicy::Fixed(120), SizePolicy::Remainder(0)];
    ui.with_row(&widths, SizePolicy::Auto, |ui| {
        ui.label("Name");
        ui.textbox_ex(&mut name);
    });
});

Window, dialog, and popup builders now accept a WidgetBehaviourOption to control scroll behavior. Use WidgetBehaviourOption::NO_SCROLL for popups that should not scroll, WidgetBehaviourOption::GRAB_SCROLL for widgets that want to consume scroll, and WidgetBehaviourOption::NONE for default behavior. Custom widgets receive consumed scroll in CustomRenderArgs::scroll_delta.

Images and textures

Some widgets can render an Image, which can reference either a slot or an uploaded texture at runtime:

let texture = ctx.load_image_from(ImageSource::Png { bytes: include_bytes!("assets/IMAGE.png") })?;
let mut image_button = Button::with_image(
    "External Image",
    Some(Image::Texture(texture)),
    WidgetOption::NONE,
    WidgetFillOption::ALL,
);
ui.button(&mut image_button);

• Image::Slot renders an entry from the atlas and benefits from batching.
• Image::Texture targets renderer-owned textures (the backend handles binding when drawing).
• WidgetFillOption controls which interaction states draw a filled background; use WidgetFillOption::ALL to keep the default normal/hover/click fills.
• Use Context::load_image_rgba/load_image_from and Context::free_image to manage the lifetime of external textures.

Cargo features

• builder (default) – enables the runtime atlas builder and PNG decoding helpers used by the examples.
• png_source – allows serialized atlases and ImageSource::Png { .. } uploads to stay compressed.
• save-to-rust – enables AtlasHandle::to_rust_files to emit the current atlas as Rust code for embedding.

Disabling default features leaves only the raw RGBA upload path (ImageSource::Raw { .. }): cargo build --no-default-features

The demos require builder, so run them with --no-default-features plus builder: cargo run --example demo-full --no-default-features --features "example-vulkan builder"

To export an atlas as Rust, enable save-to-rust (optionally png_source for PNG bytes) and call AtlasHandle::to_rust_files, or use the helper binary: cargo run --bin atlas_export --features "builder save-to-rust" -- --output path/to/atlas.rs

Text rendering and layout

• Container text widgets automatically center the font’s baseline inside each cell, and every line gets a small vertical pad so glyphs never touch the widget borders.
• Container::text_with_wrap supports explicit wrapping modes (TextWrap::None or TextWrap::Word) and renders wrapped lines back-to-back inside an internal column, so the block keeps the outer padding without adding extra spacing between lines.
• Custom drawing code can call Container::draw_text directly when precise placement is required, or use draw_control_text to get automatic alignment/clip handling.

Version 0.4

• Stateful widgets
  • Stateful widgets for core controls (button, list item, checkbox, textbox, slider, number, custom).
  • Pointer-based widget IDs; InputSnapshot threaded through widgets and cached per frame.
  • IdManager removed; widget IDs now derive from state pointers.
  • Widget API redesign requires stateful widget instances; trait/type renames applied.
  • Legacy button_ex* shims removed.
  • DrawCtx extracted into its own module and shared via WidgetCtx.
  • WidgetState/WidgetCtx pipeline with ControlState returned from update_control.
• File dialog UX fixes (close on OK/cancel, path-aware browsing).
• Expanded unit tests for scrollbars, sliders, and PNG decoding paths.
• Style shared via Rc<Style> across containers/panels; window chrome state moved into Window.
• Container::style now uses Rc<Style>.

Version 0.3

• Use std (Vec, parse, ...)
• Containers contain clip stack and command list
• Move begin_*, end_* functions to closures
• Move to AtlasRenderer Trait
• Remove/Refactor Pool
• Change layout code
• Treenode as tree
• Manage windows lifetime & ownership outside of context (use root windows)
• Manage containers lifetime & ownership outside of contaienrs
• Software based textured rectangle clipping
• Add Atlasser to the code
  • Runtime atlasser
    • Icon
    • Font (Hash Table)
  • Separate Atlas Builder from the Atlas
  • Builder feature
  • Save Atlas to rust
  • Atlas loader from const rust
• Image widget
• Png Atlas source
• Pass-Through rendering command (for 3D viewports)
• Custom Rendering widget
  • Mouse input event
  • Keyboard event
  • Text event
  • Drag outside of the region
  • Rendering
• Dialog support
• File dialog
• API/Examples loop/iterations
  • Simple example
  • Full api use example (3d/dialog/..)
• Documentation