oxiui-egui — egui/eframe adapter for OxiUI

oxiui-egui is the egui/eframe adapter for OxiUI. It bridges OxiUI's backend-agnostic widget model to [egui] — the popular immediate-mode GUI library — and its [eframe] application shell. The adapter implements [oxiui_core::UiCtx] in terms of an egui::Ui, converts an OxiUI [Palette] / [oxiui_theme::DesignTokens] into egui::Visuals / egui::Style, loads OxiFont bytes into egui's font system, and forwards OxiUI [UiEvent]s into egui's input queue.

Both egui and eframe are Pure Rust GUI frameworks, so this adapter keeps the OxiUI stack C/C++-free. (eframe's default rendering goes through wgpu, the Rust graphics boundary, which dispatches to OS-provided GPU drivers at runtime.) Because egui is immediate-mode while OxiUI's UiCtx is also immediate-mode, the mapping is direct: each UiCtx call forwards straight to its egui equivalent. #![forbid(unsafe_code)] is enforced crate-wide.

Installation

[dependencies]
oxiui-egui = "0.2.1"

oxiui-egui depends only on [egui] itself (plus oxiui-core/oxiui-text/oxiui-theme) — bring your own [eframe] (or other windowing/event-loop shell) if you need a full native application; every function here takes an &egui::Context / &mut egui::Ui so it works the same whether that context comes from eframe or a hand-rolled egui-winit + wgpu loop.

Quick Start

Wrap an egui::Ui as an OxiUI [UiCtx] and render OxiUI widgets directly:

use oxiui_core::UiCtx;
use oxiui_egui::EguiUiCtx;

fn draw(ui: &mut egui::Ui) {
    let mut ctx = EguiUiCtx::new(ui);
    ctx.heading("OxiUI on egui");
    ctx.label("Backend-agnostic widgets, rendered by egui.");
    let response = ctx.button("Click me");
    if response.clicked {
        // handle click
    }
}

Applying an OxiUI palette to an egui context

use oxiui_core::{Color, Palette};
use oxiui_egui::palette_to_egui_visuals;

fn theme(ctx: &egui::Context, palette: &Palette) {
    ctx.set_visuals(palette_to_egui_visuals(palette));
}

Caching adapter for an eframe app

use oxiui_egui::StatefulEguiAdapter;

let mut adapter = StatefulEguiAdapter::new()
    .with_palette(my_palette)
    .with_design_tokens(my_tokens, my_typography)
    .with_font_bytes(font_data);

// In your eframe::App::update():
adapter.apply(ctx); // cheap after the first frame if the theme is unchanged

API Overview

EguiUiCtx<'a> — the UiCtx implementation

Wraps an &mut egui::Ui and implements [oxiui_core::UiCtx], forwarding each widget call to its egui equivalent.

Implemented UiCtx widgets (all forwarding to egui): heading, label, button, text_input, checkbox, slider, dropdown, image, separator, spacer, scroll_area, tooltip, popup, modal, horizontal, vertical, grid, menu_bar, rich_text, drag_source, drop_target.

Theme conversion functions

Font loading

Both validate font bytes via [oxiui_text::TextPipeline::from_bytes] and return [UiError::Render] on invalid input.

Event forwarding

Handled families: IME (ImePreedit, ImeCommit), keyboard (KeyDown, KeyUp, KeyPress), pointer (MouseMove, Mouse, MouseDown, MouseUp), and Resize (noted only — egui resize is driven by RawInput.screen_rect). Other variants are silently ignored.

Widget bridge

Adapters

StatefulEguiAdapter

Caches expensive operations across frames so repeated apply calls are cheap when the theme is stable.

Accessibility bridge (a11y feature)

Bridges oxiui-accessibility's A11yTree into accesskit::TreeUpdates, feeding egui's built-in AccessKit integration (forward the update to the platform adapter, e.g. accesskit_winit::Adapter::update_if_active).

Table bridge (table feature)

Convenience wrappers around oxiui-table's Table::render_egui / EguiTableState.

Feature Flags

default is empty — both features below are opt-in.

Errors

Functions that can fail return [oxiui_core::UiError]. Font-loading helpers use the UiError::Render variant for invalid font bytes; see the oxiui-core error table for all variants.

Adapter Notes and Deviations

The adapter is faithful to egui 0.35's API; a few mappings are approximate and documented inline:

• Key::Character / Key::Named are forwarded via egui::Key::from_name; unrecognised names fall back to egui::Key::F12.
• rich_text honours span colour, size, and italics; egui 0.35's TextFormat has no per-span bold field, so bold spans render at the default weight.
• Palette carries no error/warning/success colours (those live on oxiui_theme::ExtendedPalette), so egui's warn_fg_color / error_fg_color keep their defaults.
• IME preedit cursor. egui 0.35's ImeEvent::Preedit gained an active_range_chars: Option<Range<usize>> field. forward_event_to_egui converts UiEvent::ImePreedit's byte-offset cursor range into that char-offset range (the same conversion egui-winit applies to raw OS IME events), using str::get so a range landing off a UTF-8 char boundary degrades to None instead of panicking. On egui ≤ 0.34 there was nowhere to put this — ImeEvent::Preedit was a bare String — so the cursor position was always dropped; it is now forwarded.

Related Crates

• oxiui — the OxiUI facade crate.
• oxiui-core — UiCtx, Widget, Palette, UiEvent, UiError, response types.
• oxiui-theme — DesignTokens, TypographyScale, theming primitives.
• oxiui-text — font validation used by the font loaders.
• oxiui-iced — the alternative iced framework adapter.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)