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_mutand call methods on them. - Explicit logic. Handlers produce messages of your own type;
Ui::handlereturns 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
styleattributes built withStyle. - Shortcuts first. Any button takes a
shortcut="Ctrl+S"attribute; window-wide shortcuts are bound withUi::bind; Tab moves focus; Enter and Space activate. - Pluggable rendering. The toolkit draws through the
RendererandFontstraits.eternal-ui-skiaimplements 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
Anyaccessors ofWidgetfor a type. - ui
- Builds an
Elementtree 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.
- Font
Spec - 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.
- Monospace
Fonts - 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
- Recording
Renderer - 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. - Shortcut
Parse Error - The text was not a shortcut.
- Size
- Style
- Builds inline CSS from Rust values, for
style={...}attributes whose values are computed. - Text
Metrics - 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
onand attached withElement::on. - Key
- A key, independent of keyboard layout for the named ones and by produced character for the rest.
- Load
Error - A stylesheet file could not be read or parsed.
- Pointer
Button
Constants§
- DEFAULT_
THEME_ CSS - The stylesheet
Ui::newstarts 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.
- Into
Children - 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.