Crate crabshell_ui

Expand description

Crabshell’s widgets, styles, layout, text layout, hit testing and invalidation.

A bar is described with widgets and turned into a live Window:

use crabshell_reactive::Runtime;
use crabshell_ui::prelude::*;

const BAR: Style = Style::new()
    .background(Color::rgb(0x1e, 0x1e, 0x2e))
    .color(Color::rgb(0xcd, 0xd6, 0xf4));

let runtime = Runtime::current();
let cx = Cx::new(runtime.new_owner());
let count = cx.signal(0);

let bar = PanelWindow::new(&Output::new("DP-1"))
    .anchors(Edge::Top | Edge::Left | Edge::Right)
    .height(30)
    .style(BAR)
    .child(
        Row::new().gap(8).padding(4, 8).child(
            Button::new(Text::new(move || format!("clicked {} times", count.get())))
                .on_click(move |_cx| count.update(|n| *n += 1)),
        ),
    );

// The platform does the rest once per event-loop iteration.
let window = Window::new(&cx, bar);
let mut text = TextSystem::new();
window.set_size(Size::new(1920.0, 30.0));
runtime.flush(); // bindings run
window.layout(&mut text);
let _damage = window.take_damage(); // what the renderer repaints

§How it fits together

Widgets are descriptions. Window::new turns them into a tree of nodes, each with its own reactive owner. A property given a closure becomes an effect that writes the node when a signal it read changes.
Each property is a layout property (text, font, padding, gap, size, children) or a paint property (colors, background, border, opacity, radius). A paint change records the widget’s area as damage. A layout change marks the window for Window::layout, which records the old and new area of every widget that moved or changed.
TextSystem loads only the fonts fontconfig matches for the families styles name, plus fallbacks for missing characters. Each Text keeps one cosmic-text buffer that layout measures and the renderer draws.
Pointer events go to Window::pointer_motion and friends. Hit testing finds the deepest Button under the pointer, and its handlers run with no borrow held, inside catch_unwind.
Dropping a Window disposes its owner, freeing every node, binding and handler it made.

Modules§

prelude: What a bar’s code needs, in one use.

Structs§

Anchors: The edges a window is anchored to. Combine edges with |: Edge::Top | Edge::Left | Edge::Right.
Border: A border drawn inside a widget’s edge. It takes no layout space.
Button: A clickable box around one child, which it centers.
Color: An sRGB color with straight (not premultiplied) alpha.
Column: Lays its children out top to bottom, like a CSS flexbox column.
Cx: The context widget code runs in.
Element: What a Widget turns into: plain data, with every child already turned into its element. Only this crate’s widgets create one.
Font: A font: family, size and weight.
Icon: An icon, drawn as a square.
IconPixels: Raw icon pixels: ARGB32 in network byte order (A, R, G, B bytes), row by row, as the StatusNotifierItem spec sends them.
IconView: An icon, ready to draw.
Menu: A vertical list of buttons, one per entry, as a popup menu shows them.
MenuEntry: One entry of a Menu.
NodeView: One node of a laid-out window: a widget, or the window itself at the root. Draw it, then its children in order, so later ones are on top.
Output: A monitor, as the compositor names it.
Padding: Space between a widget’s edge and its content, in logical pixels.
PanelWindow: A bar: a layer-shell surface on one output with one child.
Point: A point in logical pixels, measured from the window’s top-left corner.
PopupWindow: A popup: a window next to the widget that opened it, sized to fit its one child. Open one with Cx::open_popup.
Prop: A widget property: either a value set once, or a binding that reruns whenever a signal it read changes.
Rect: A rectangle in logical pixels: its top-left corner and its size.
Row: Lays its children out left to right, like a CSS flexbox row.
Size: A width and height in logical pixels.
Spacer: Takes the space left over in a Row or Column. Several spacers share it equally.
Stack: Draws its children on top of each other in one cell, each stretched to the size of the largest. Later children are on top.
Style: How a widget looks. Every field is optional, and an unset field falls back to the widget’s default: no background, black text in Font::DEFAULT, no padding, square corners, no border, fully opaque.
SurfaceConfig: What the platform needs to set up the window’s layer surface.
Text: A line of text.
TextSystem: The fonts every window measures and draws text with.
TextView: Laid-out text, ready to draw. Lines can stick out of the node’s rectangle when it is too small for them; draw them unclipped, as CSS does. The window’s damage covers them.
Window: A live window: the tree of nodes built from a PanelWindow.
WindowView: A window’s laid-out tree, borrowed for reading. Get one from Window::view.

Enums§

Align: How a Row or Column places children across its direction: up and down in a row, left and right in a column.
Content: What a node draws besides its background and border.
CursorShape: The cursor the platform should show.
Edge: An edge of the output.
IconSource: What an Icon shows.
Justify: How a Row or Column places children along its direction when they don’t fill it.
Layer: The layer-shell layer a window is drawn in, from bottom to top.
MenuToggle: What a toggling menu entry shows.
PointerButton: A pointer button.
ScrollDelta: One scroll event on the vertical axis, as wl_pointer reports it. Positive values scroll down.

Traits§

IntoProp: Anything a widget property accepts: a value of type T, or a closure that returns one.
Widget: Something that can be placed in a window: one of this crate’s widgets, or a type of your own that is made of them.

Crate crabshell_ui

Crate crabshell_ui Copy item path

§How it fits together

Modules§

Structs§

Enums§

Traits§

Crate crabshell_ui