Skip to main content

Crate eternal_ui

Crate eternal_ui 

Source
Expand description

A small, dense, keyboard-first UI toolkit.

Eternal UI is built for tools: information-dense screens, strong hierarchy without decoration, keyboard and mouse as equals. The look is in the spirit of Aseprite and lives entirely in a stylesheet, so it is easy to change.

  • Declarative composition. The ui! macro describes a tree in HTML-like markup, inside Rust.
  • Imperative behaviour. Widgets are plain structs; reach them through Ui::widget_mut and call methods on them.
  • Explicit logic. Handlers produce messages of your own type; Ui::handle returns them and your code decides what happens.
  • Data-driven styling. Every colour, border, padding and font comes from CSS handled by eternal-styler, either the built-in theme, files you load, or inline style attributes built with Style.
  • Shortcuts first. Any button takes a shortcut="Ctrl+S" attribute; window-wide shortcuts are bound with Ui::bind; Tab moves focus; Enter and Space activate.
  • Pluggable rendering. The toolkit draws through the Renderer and Fonts traits. eternal-ui-skia implements them with Skia; a Vello or tiny-skia backend would implement the same two traits.

§Example

use eternal_ui::{ui, Element, Event, Key, Modifiers, MonospaceFonts, PointerButton, Size, Ui};
use eternal_ui::widgets::Label;

#[derive(Clone, Debug, PartialEq)]
enum Msg { Save, Rename(String) }

// Describe the tree.
let root: Element<Msg> = ui! {
    <column class="panel">
        <row class="toolbar">
            <button id="save" shortcut="Ctrl+S" on:click={|| Msg::Save}>"Save"</button>
            <spacer/>
            <label id="status" class="dim">"Ready"</label>
        </row>
        <input placeholder="File name" on:change={Msg::Rename}/>
    </column>
};

let mut ui = Ui::new();
ui.set_root(root);

// Each frame: events in, messages out, then layout and paint. The fonts
// and renderer come from a backend; this one only measures.
let fonts = MonospaceFonts::default();
ui.layout(Size::new(320.0, 200.0), &fonts);

let messages = ui.handle(&Event::KeyDown { key: Key::Char('s'), modifiers: Modifiers::CTRL }, &fonts);
assert_eq!(messages, vec![Msg::Save]);

// Behaviour is imperative: change what you like, when you like.
let status = ui.find("status").unwrap();
ui.widget_mut::<Label>(status).unwrap().set_text("Saved");

§The look

The default theme is dark, flat and dense. Replace it with Ui::set_theme, or add a stylesheet after it with Ui::add_stylesheet to change parts. Element tags (button, input, panel…), the id and class attributes, and the usual pseudo-classes (:hover, :active, :focus-visible, :disabled, :checked, :state(name)) are what selectors match on.

§Layout

Containers lay their children out along one axis. Sizes, spacing and borders come from the stylesheet; grow and align attributes on elements and align_items and justify on containers decide how spare room is used. See the layout module.

Re-exports§

pub use layout::Align;
pub use layout::Justify;
pub use eternal_styler as styler;

Modules§

elements
Constructors for the built-in elements, one per tag the ui! macro understands.
layout
Sizing and placing elements.
on
Constructors for handlers. In the ui! macro, on:click={|| Msg::Save} becomes .on(on::click(|| Msg::Save)).
widgets
The built-in widgets.

Macros§

impl_widget_any
Implements the two Any accessors of Widget for a type.
ui
Builds an Element tree from markup.

Structs§

Element
An element waiting to be mounted: a widget, its attributes, handlers and children.
EventCx
What a widget can do while handling an event.
FontSpec
The font a piece of text is set in, taken from a computed style.
Handlers
The handlers an element was declared with.
Modifiers
Modifier keys held during a key or pointer event.
MonospaceFonts
A font source that pretends every glyph is the same width.
NodeId
A handle to a mounted element. Stays valid until the element is removed.
PaintCx
What a widget can see while painting.
Point
RecordingRenderer
A renderer that records what it was asked to draw, for tests and for inspecting what a frame would contain.
Rect
Shortcut
A key with modifiers, such as Ctrl+Shift+S.
ShortcutParseError
The text was not a shortcut.
Size
Style
Builds inline CSS from Rust values, for style={...} attributes whose values are computed.
TextMetrics
How much room a run of text takes.
Ui
The element tree, the stylesheets that style it, and the focus.

Enums§

Axis
The direction a container lays its children out in.
Child
A child as the macro sees it: an element or a run of text.
DrawOp
One drawing call, as recorded by RecordingRenderer.
Event
Something the user did.
Handler
One handler, made by the functions in on and attached with Element::on.
Key
A key, independent of keyboard layout for the named ones and by produced character for the rest.
LoadError
A stylesheet file could not be read or parsed.
PointerButton

Constants§

DEFAULT_THEME_CSS
The stylesheet Ui::new starts with: dark, dense, flat, 1px borders, in the spirit of Aseprite. Read it to see which classes it understands (panel, toolbar, primary, title, dim).

Traits§

Fonts
Measures text. Implemented by a backend, since only it knows the fonts.
IntoChildren
Anything that can appear as a child in the ui! macro.
Renderer
Draws. Implemented by a backend for one frame’s drawing target.
Widget
What an element does: how it measures, reacts to input and paints.

Functions§

default_theme
The default theme, parsed.
load_stylesheet
Reads and parses a stylesheet from a file.