Crate densa_ui

Expand description

The widget layer of densa: a retained tree of widgets, laid out with flexbox, painted onto a densa_draw::Canvas, and driven by pointer, keyboard and input method events.

A Ui owns the widgets. The application adds them under the root with a Style, then a window layer (such as densa-window) calls Ui::paint each frame and hands it input with Ui::pointer, Ui::key and Ui::ime. Widgets report what the user did as Actions, read with Ui::actions. Nothing here depends on a window system or a GPU, so an interface runs, and is tested, headless.

Layout runs only when a style, a widget’s content or the viewport changes; painting, hit-testing and delivering events run every frame and do not allocate.

Popups (menus, completion lists) open above every other widget with Ui::open_popup, placed next to an Anchor and kept inside the viewport; a press outside closes them. A secondary press or the context menu key reports ActionKind::ContextMenu, where an application opens its context menu.

Widgets copy and paste through the Ui’s Clipboard (EventCx::clipboard): a MemoryClipboard until the window gives it the system’s.

Widgets also describe themselves to assistive technology (Widget::accessibility): Ui::access_tree is what a screen reader reads, and Ui::access_action does what it asks. Both are platform-neutral; densa-window connects them to the operating system.

use densa_core::{Point, Size};
use densa_paragraph::TextSystem;
use densa_ui::{
    ActionKind, Event, EventCx, Handled, PointerButton, PointerEvent, PointerKind, Style, Ui,
    Widget,
};

/// Reports a click when pressed.
struct Clickable;

impl Widget for Clickable {
    fn event(&mut self, cx: &mut EventCx<'_>, event: &Event<'_>) -> Handled {
        match event {
            Event::Pointer(p) if matches!(p.kind, PointerKind::Down(_)) => {
                cx.emit(ActionKind::Clicked);
                Handled::Yes
            }
            _ => Handled::No,
        }
    }
}

let mut ui = Ui::new(TextSystem::new()?);
ui.resize(Size::new(400.0, 300.0));
let button = ui.add(ui.root(), Clickable, Style::row().size(120.0, 32.0))?;

let press = PointerKind::Down(PointerButton::Primary);
ui.pointer(PointerEvent::new(press, Point::new(10.0, 10.0)));
let clicked: Vec<_> = ui.actions().map(|action| action.source).collect();
assert_eq!(clicked, [button]);

Structs§

AccessId: Identifies a node of the accessibility tree: a widget, or a part of one. A widget’s id is never given to another widget, even one in its slot after it is removed, so a request for a removed widget reaches nothing. Get one from Ui::access_id.
AccessNode: A node of the accessibility tree: a widget, or a part of one (such as a dock’s tab).
AccessRequest: A request from assistive technology, as a widget receives it in Widget::access_action.
AccessTree: The accessibility tree of a Ui: every shown widget (and the parts widgets add), parents before children.
Action: Something a widget reports to the application: a button was clicked, a text changed. Read them with Ui::actions after delivering events.
Anchor: Where a popup goes: next to a rectangle, kept inside the viewport.
Constraints: What layout asks a widget in Widget::measure.
Edges: One value per side of a box.
EventCx: What a widget gets while it handles an event (or is updated by the application through Ui::update): its state, and requests to the Ui.
KeyEvent: A key event.
LayoutCx: What a widget gets while it measures itself or learns its size.
MemoryClipboard: A clipboard in memory, seen by this process only: for tests and windowless interfaces.
Modifiers: Modifier keys held during an event.
PaintCx: What a widget gets while it paints.
PointerEvent: A pointer event.
Style: A widget’s layout style: its size, spacing, and how it lays out its children (flexbox). Lengths are in logical pixels.
Theme: Colors and sizes widgets share, so an application restyles every widget in one place. Sizes are in logical pixels.
Ui: A tree of widgets: their layout, painting and events.
WidgetId: Identifies a widget in a Ui.

Enums§

AccessAction: Something assistive technology can ask a widget to do.
ActionKind: What a widget reports. The details are on the widget: read them through Ui::widget.
Align: Where items sit across the main axis (or one item, as Style::align_self).
Available: Room along one axis.
ClipboardError: Why the clipboard gave no text, or took none.
Cursor: The mouse cursor a widget asks for.
Direction: The axis children are laid out along.
Event: What a widget receives.
Handled: Whether a widget handled an event; one it did not goes on to the widget’s parent.
Ime: Input method events: text being composed (preedit) and text committed.
Justify: How free space along the main axis is shared out.
Key: A key, after the keyboard layout.
Length: A length along one axis.
NamedKey: Keys with names.
Overflow: What happens to content larger than the widget.
PointerButton: A pointer button.
PointerKind: What a pointer did.
Position: How a widget takes part in its parent’s layout.
Role: What a widget is to assistive technology.
ScrollDelta: How far a scroll went.
UiError: Why a Ui refused a change.

Constants§

MAX_PART: The highest part number a widget can use (see AccessNode::push_part).

Traits§

Clipboard: Where copied text goes and pasted text comes from. A Ui starts with a MemoryClipboard, shared by its widgets only; a window gives it the system’s (Ui::set_clipboard).
Widget: A part of the interface: it can measure itself, paint, and handle events.

Crate densa_ui

Crate densa_ui Copy item path

Structs§

Enums§

Constants§

Traits§

Crate densa_ui