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.1.0"

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.

Method	Description
`EguiUiCtx::new(ui)`	Wrap an egui `Ui` reference
`response()`	The egui `Response` of the most recently rendered widget
`clipboard_get()`	Read the most-recently-copied text from egui's output queue (intra-frame)
`clipboard_set(text)`	Queue a copy-to-clipboard command via egui

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

Function	Description
`palette_to_egui_visuals(&Palette) -> egui::Visuals`	Map an OxiUI palette to an egui colour scheme
`palette_to_egui_visuals_with_tokens(&Palette, &DesignTokens) -> egui::Style`	Palette visuals plus token-driven spacing and corner radius
`tokens_to_egui_style(&DesignTokens, &TypographyScale) -> egui::Style`	Full token + typography mapping to all five `egui::TextStyle` variants

Font loading

Function	Description
`load_font_into_egui(&egui::Context, Vec<u8>) -> Result<(), UiError>`	Validate and install a single font as the `"OxiFont"` family
`load_fonts_into_egui(&[(&str, Vec<u8>)], &egui::Context) -> Result<(), UiError>`	Install multiple named `"OxiFont-<name>"` families

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

Event forwarding

Function	Description
`forward_event_to_egui(&egui::Context, &UiEvent)`	Forward an OxiUI [`UiEvent`] (IME, keyboard, pointer, resize) into egui's input queue

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

Item	Description
`OxiWidget<'a>`	Wraps a `&mut dyn oxiui_core::Widget` so it can be placed in an egui layout via `ui.add(...)`; implements `egui::Widget`. `OxiWidget::new(widget)`

Adapters

Item	Description
`EguiAdapter`	Stateless builder: `new()`, `with_palette(p)`, `build() -> impl Fn(&egui::Context)`
`StatefulEguiAdapter`	Per-frame caching adapter (see below)

`StatefulEguiAdapter`

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

Method	Description
`new()`	Empty adapter
`with_palette(p)`	Set the palette (visuals recomputed only on change)
`with_design_tokens(tokens, typography)`	Apply a token-driven style once on the first frame
`with_font_bytes(bytes)`	Load fonts once on the first frame
`set_palette(p)`	Update the live palette (marks visuals stale)
`apply(&egui::Context)`	Apply state for one frame (fonts/tokens once, visuals on change)
`visuals_recompute_count` (field)	Number of times visuals were recomputed (instrumentation)
`fonts_load_count` (field)	Number of `set_fonts` calls (≤ 1 in normal use)

Feature Flags

This crate exposes no Cargo features; default is empty.

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.34'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.34'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.

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-render-wgpu — the wgpu render path eframe uses by default.
oxiui-iced — the alternative iced framework adapter.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)

oxiui-egui 0.1.0