Expand description
Kova Native: a GPU-accelerated, Rust-first native GUI framework.
The facade connects the existing platform, retained element tree and GPU
renderer. Use prelude for element builders and Application to run
them in a native window.
Kova Native draws a retained UI through wgpu, solves layout with Taffy, and shapes Unicode text with cosmic-text. Applications use Rust elements, callbacks and signals. Windows and input are provided by the native platform layer; there is no browser runtime.
§Quick start
Add the facade package to your application’s manifest:
[dependencies]
kova-native = "0.3.1"The package name uses hyphens; the Rust import is kova_native.
This example opens a window with a reactive counter:
use kova_native::prelude::*;
fn main() -> KovaResult<()> {
let owner = Owner::new_root();
let count = owner.with(|| signal(0_u32));
let result = Application::new()
.title("Kova Native counter")
.size(640.0, 420.0)
.run(move || {
column().center().gap(16.0)
.child(text(move || format!("Count: {}", count.get())))
.child(button("Increment")
.on_click(move |_| count.update(|value| *value += 1)))
});
owner.dispose();
result.map(|_| ())
}Run native applications on the main thread. They need a windowing session and a supported GPU backend. Window dimensions and layout lengths are logical pixels; the platform’s scale factor controls glyph rasterization and GPU output.
§State and invalidation
The reactive runtime is owned by the UI thread. core::Owner scopes signals,
effects and cleanup. Keep application state outside the root builder when it
must survive a rebuild, as in the counter above.
Where a signal is read determines the work it invalidates:
| Read location | Result |
|---|---|
A text closure | Update that text node |
A bind style closure | Update the node’s style and invalidate affected layout or paint |
A dynamic builder | Rebuild that region’s children |
The builder passed to Application::run | Rebuild the root region |
Reads outside a tracked callback do not subscribe a UI node. Use
core::batch to coalesce changes, and core::memo for derived state.
Region-owned state is disposed when that region is rebuilt or removed.
§Elements, layout and events
Start with widgets::elements::row, widgets::elements::column,
widgets::elements::stack and widgets::elements::div. The
widgets::Styled trait adds sizing, spacing, fills, borders and shadows.
widgets::Interactive adds reactive bindings, callbacks, actions and transitions. The
widgets::widgets module provides buttons, checkboxes, switches, sliders
and progress bars. prelude imports this common vocabulary.
Application::key_bindings registers shortcuts in the existing action
system. Handle actions on elements with widgets::Interactive::on_action.
Keyboard dispatch follows the focus path; pointer dispatch uses hit testing,
capture and bubbling through the retained element tree.
Use Application::on_file_drop to receive paths dragged from the desktop
onto the window. The callback runs once for each dropped file:
use kova_native::prelude::*;
use std::path::PathBuf;
fn main() -> KovaResult<()> {
let owner = Owner::new_root();
let dropped_path = owner.with(|| signal(String::from("Drop a file here")));
let result = Application::new()
.on_file_drop({
let dropped_path = dropped_path.clone();
move |path: PathBuf| dropped_path.set(path.display().to_string())
})
.run(move || text(move || dropped_path.get()));
owner.dispose();
result.map(|_| ())
}widgets::elements::img_bind updates a mounted image when its signal changes,
preserving the image element. Use .on_pen(...) on an element to receive
pressure-aware pointer events, and .on_close_request(...) on the application
to accept or cancel an attempt to close its window.
§Subsystems
The facade re-exports the existing library crates. Use these modules when implementing custom elements or working directly with the frame pipeline:
| Module | Responsibility |
|---|---|
crate::core | Geometry, colors, identifiers, reactive state and dirty flags |
crate::widgets | Elements, styling, themes, retained tree and event dispatch |
crate::layout | Flexbox, grid, constraints and incremental layout |
crate::text | Unicode shaping, font fallback, wrapping and glyph rasterization |
crate::render | GPU context, scene commands, batching, atlases and effects |
crate::assets | Image and SVG loading, rasterization and caching |
crate::input | Events, keystrokes, actions and keymaps |
crate::animation | Tweens, easing, springs and property transitions |
crate::platform | Native windows, event loop, clipboard and IME hooks |
§Examples and current scope
The repository’s showcase exercises the same element tree, text system and renderer used by applications. It includes native smoke runs and GPU captures. See the README for launch commands.
The API is experimental. text_input provides single-line editing with
selection, clipboard, undo and IME composition; multi-line editing,
accessibility, arbitrary masks and custom shader registration are still
pending. The
repository audit
records the implemented subsystems and validation boundaries.
Re-exports§
pub use kova_native_animation as animation;pub use kova_native_assets as assets;pub use kova_native_core as core;pub use kova_native_input as input;pub use kova_native_layout as layout;pub use kova_native_platform as platform;pub use kova_native_render as render;pub use kova_native_text as text;pub use kova_native_widgets as widgets;
Modules§
- prelude
- Common application and element-building vocabulary.
Structs§
- Application
- Runs a retained UI in one native window. The event loop sleeps while idle; animations request redraws paced by the swapchain’s presentation mode.
- RunReport
- Measurements from frames actually presented to the native surface.
- Window
Options - Native window and presentation settings, using the platform/renderer options.