eternal_ui/lib.rs
1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
5//! A small, dense, keyboard-first UI toolkit.
6//!
7//! Eternal UI is built for tools: information-dense screens, strong
8//! hierarchy without decoration, keyboard and mouse as equals. The look is
9//! in the spirit of Aseprite and lives entirely in a stylesheet, so it is
10//! easy to change.
11//!
12//! - **Declarative composition.** The [`ui!`] macro describes a tree in
13//! HTML-like markup, inside Rust.
14//! - **Imperative behaviour.** Widgets are plain structs; reach them
15//! through [`Ui::widget_mut`] and call methods on them.
16//! - **Explicit logic.** Handlers produce messages of your own type;
17//! [`Ui::handle`] returns them and your code decides what happens.
18//! - **Data-driven styling.** Every colour, border, padding and font comes
19//! from CSS handled by [eternal-styler](eternal_styler), either the
20//! built-in theme, files you load, or inline `style` attributes built
21//! with [`Style`].
22//! - **Shortcuts first.** Any button takes a `shortcut="Ctrl+S"`
23//! attribute; window-wide shortcuts are bound with [`Ui::bind`]; Tab
24//! moves focus; Enter and Space activate.
25//! - **Pluggable rendering.** The toolkit draws through the [`Renderer`]
26//! and [`Fonts`] traits. `eternal-ui-skia` implements them with Skia;
27//! a Vello or tiny-skia backend would implement the same two traits.
28//!
29//! # Example
30//!
31//! ```
32//! use eternal_ui::{ui, Element, Event, Key, Modifiers, MonospaceFonts, PointerButton, Size, Ui};
33//! use eternal_ui::widgets::Label;
34//!
35//! #[derive(Clone, Debug, PartialEq)]
36//! enum Msg { Save, Rename(String) }
37//!
38//! // Describe the tree.
39//! let root: Element<Msg> = ui! {
40//! <column class="panel">
41//! <row class="toolbar">
42//! <button id="save" shortcut="Ctrl+S" on:click={|| Msg::Save}>"Save"</button>
43//! <spacer/>
44//! <label id="status" class="dim">"Ready"</label>
45//! </row>
46//! <input placeholder="File name" on:change={Msg::Rename}/>
47//! </column>
48//! };
49//!
50//! let mut ui = Ui::new();
51//! ui.set_root(root);
52//!
53//! // Each frame: events in, messages out, then layout and paint. The fonts
54//! // and renderer come from a backend; this one only measures.
55//! let fonts = MonospaceFonts::default();
56//! ui.layout(Size::new(320.0, 200.0), &fonts);
57//!
58//! let messages = ui.handle(&Event::KeyDown { key: Key::Char('s'), modifiers: Modifiers::CTRL }, &fonts);
59//! assert_eq!(messages, vec![Msg::Save]);
60//!
61//! // Behaviour is imperative: change what you like, when you like.
62//! let status = ui.find("status").unwrap();
63//! ui.widget_mut::<Label>(status).unwrap().set_text("Saved");
64//! ```
65//!
66//! # The look
67//!
68//! The [default theme](default_theme) is dark, flat and dense. Replace it
69//! with [`Ui::set_theme`], or add a stylesheet after it with
70//! [`Ui::add_stylesheet`] to change parts. Element tags (`button`,
71//! `input`, `panel`...), the `id` and `class` attributes, and the usual
72//! pseudo-classes (`:hover`, `:active`, `:focus-visible`, `:disabled`,
73//! `:checked`, `:state(name)`) are what selectors match on.
74//!
75//! # Layout
76//!
77//! Containers lay their children out along one axis. Sizes, spacing and
78//! borders come from the stylesheet; `grow` and `align` attributes on
79//! elements and `align_items` and `justify` on containers decide how spare
80//! room is used. See the [`layout`] module.
81
82mod element;
83mod event;
84mod geometry;
85pub mod layout;
86mod macros;
87mod paint;
88mod render;
89mod shortcut;
90mod style;
91mod ui;
92mod widget;
93pub mod widgets;
94
95/// The style engine, re-exported for convenience.
96pub use eternal_styler as styler;
97
98pub use element::{Child, Element, IntoChildren, elements, tags};
99pub use event::{Event, Key, Modifiers, PointerButton};
100pub use geometry::{Axis, Point, Rect, Size};
101pub use layout::{Align, Justify};
102pub use render::{
103 DrawOp, FontSpec, Fonts, MonospaceFonts, RecordingRenderer, Renderer, TextMetrics,
104};
105pub use shortcut::{Shortcut, ShortcutParseError};
106pub use style::{DEFAULT_THEME_CSS, LoadError, Style, default_theme, load_stylesheet};
107pub use ui::{NodeId, Ui};
108pub use widget::{EventCx, Handler, Handlers, PaintCx, Widget, on};