Skip to main content

Crate kova_native

Crate kova_native 

Source
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 locationResult
A text closureUpdate that text node
A bind style closureUpdate the node’s style and invalidate affected layout or paint
A dynamic builderRebuild that region’s children
The builder passed to Application::runRebuild 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:

ModuleResponsibility
crate::coreGeometry, colors, identifiers, reactive state and dirty flags
crate::widgetsElements, styling, themes, retained tree and event dispatch
crate::layoutFlexbox, grid, constraints and incremental layout
crate::textUnicode shaping, font fallback, wrapping and glyph rasterization
crate::renderGPU context, scene commands, batching, atlases and effects
crate::assetsImage and SVG loading, rasterization and caching
crate::inputEvents, keystrokes, actions and keymaps
crate::animationTweens, easing, springs and property transitions
crate::platformNative 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.
WindowOptions
Native window and presentation settings, using the platform/renderer options.