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§

Adjust: How a popup may move or shrink to stay on its output, combined with |, as xdg_positioner’s constraint adjustments. The compositor flips first, then slides, then resizes.
Affine: A 2D affine transform, in the order tiny-skia’s Transform::from_row takes: a point (x, y) goes to (sx·x + kx·y + tx, ky·x + sy·y + ty).
Anchors: The edges a window is anchored to. Combine edges with |: Edge::Top | Edge::Left | Edge::Right.
Animation: A value moving toward its target, from Cx::animation: a Copy handle to its value and to whether it moves.
Border: A border drawn inside a widget’s edge. It takes no layout space.
Button: A clickable box around one child, which it centers.
CaptureFrame: A captured frame, as a view keeps it.
CaptureRequest: One view the platform captures for, from Window::captures.
CaptureView: A screencopy view’s frame, ready to draw.
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.
FieldState: The focused text field, as an input method needs it.
FloatingConfig: What the platform needs to show a floating window.
FloatingWindow: A window like an application’s, which the compositor places, tiles or floats: a launcher, a settings panel, a picture viewer. Show one with cx.floating from the crabshell crate. Every property takes a value or a closure.
Font: A font: family, size and weight.
Gradient: Colors that blend into each other across a widget’s box, drawn over its background with the same corners.
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.
Image: A picture from a PNG, JPEG, GIF (its first frame), WebP or SVG file, drawn at a fixed size.
ImageView: An image, ready to draw.
InputView: A text field, ready to draw: the selection behind the text, then the text, then the caret.
KeyEvent: A key press, or a repeat of a key held down.
ListView: A scrolling list of rows of one height that builds only the rows in view, so a list of thousands costs what a screenful does. Offsets are f32, which stays exact to about 16 million pixels: some 700,000 rows of 24 pixels. It follows a list of items as children_keyed does: each row is kept while its item’s key stays in the list.
Lock: A SessionLock as the platform holds it: whether the config wants the session locked, what the compositor says, and each output’s lock surface. Dropping it disposes its owner, which frees everything it made.
Margins: Space between a window and the output edges it is anchored to, in logical pixels. Edges the window isn’t anchored to ignore theirs.
Menu: A vertical list of buttons, one per entry, as a popup menu shows them.
MenuEntry: One entry of a Menu.
Modifiers: The modifier keys held.
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, on each side.
PanelWindow: A bar: a layer-shell surface on one output with one child.
Placement: Where a popup goes next to the widget that opened it. Unset parts keep the defaults: below the widget from a horizontal bar, beside it from a vertical bar or another popup, flipped or slid to stay on the output.
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.
Preedit: Text an input method is composing, shown at the caret, underlined, until it commits or drops it.
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.
Region: An area of a window in logical pixels, built from rectangles, rounded rectangles and ellipses joined with union, subtract, intersect and xor, applied in the order they are called.
Row: Lays its children out left to right, like a CSS flexbox row.
ScreencopyView: Shows what an output or a window shows, captured by the compositor, in the box its style’s width and height give it, as an Image shows a picture. It draws nothing until the first frame arrives.
ScrollView: A box that shows part of its child, which may be taller, and scrolls it with the mouse wheel or touchpad. Children are cut to the box. Give it a height through its style, or let its parent size it.
SessionLock: A lock screen: while locked is true, the compositor shows only its surfaces, one covering each output, and nothing else gets input. Lock with cx.session_lock from the crabshell crate. Every property takes a value or a closure.
Shadow: A shadow cast by a widget’s box, as CSS’s box-shadow: the box’s shape moved by x and y, grown by spread and blurred over blur logical pixels. Unlike CSS’s, it is drawn under the box too, so a translucent background shows it through, unless it is cut_out.
Size: A width and height in logical pixels.
Spacer: Takes the space left over in a Row or Column. Several spacers share it equally.
Spring: The spring a Cx::spring value follows its target on, as Qt’s SpringAnimation. Time is in seconds and distance in the value’s own units. The target pulls the value with stiffness times the distance, per second squared, and friction slows it as damping says, as a ratio: 1 comes to rest as fast as it can without passing the target, less overshoots and bounces, more creeps in. The default, 700 and 0.9, is Material 3’s default spatial spring; its expressive one is 380 and 0.8.
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.
TextInput: A one-line text field. It takes the keyboard focus when clicked, when Tab reaches it, or when focus says so, and edits the text in a shared signal: typing writes it, and setting it changes what the field shows. Arrows, Home and End move the caret, Shift selects, Ctrl moves and deletes by word, and Ctrl+A selects everything. Keys it doesn’t use, such as Up, Down and Escape, go on to the window’s on_key.
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.
Timer: A timer made by Cx::after or Cx::interval. It is a Copy handle, like a signal, so closures capture it without cloning. Calls on a timer whose context is gone do nothing.
Transition: How long an animation takes, how it moves, and how long it waits first. Copy it into styles and constants like a color.
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.
CaptureSource: What a ScreencopyView shows.
Clipboard: What a key asks of the clipboard.
Content: What a node draws besides its background and border.
CursorShape: The cursor the platform should show.
Easing: How an animation moves from its start to its end: what fraction of the way it has gone at each fraction of its time.
Edge: An edge of the output.
Fit: How an Image fills its box when their shapes differ, as CSS’s object-fit.
GradientShape: Which way a Gradient’s colors run.
IconSource: What an Icon shows.
Justify: How a Row or Column places children along its direction when they don’t fill it.
Key: A key, as the keyboard layout names it.
KeyboardFocus: Whether and when a window takes the keyboard.
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.
WindowRequest: What a widget asked of the floating window it is in. Moving and resizing need a pointer button held, so ask from a button’s on_press; asked otherwise, they are ignored.

Traits§

Animate: A value an animation can move between two of: lerp gives the value t of the way from self to to, where t may stray a little past 0 or 1 for an easing that overshoots.
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.

Functions§

advance_animations: Advances every running animation to now, writing their values, and returns whether any still runs. Each one starts at the first call after it began, so now there is its time 0. One that panics is logged and dropped.
animating: Whether an animation is running, so the platform should advance the clock soon. false means nothing moves and nothing needs waking.
fire_timers: Runs every timer due at now, earliest first. A timer started while they run first fires at a later call. One whose callback panics is logged and stops; the others still fire.
next_timer: When the earliest running timer is due, for the platform to wake then. None means no timer runs and nothing needs waking. Timers whose context is gone are freed first, so they never wake the loop.

Crate crabshell_ui

Crate crabshell_ui Copy item path

§How it fits together

Modules§

Structs§

Enums§

Traits§

Functions§

Crate crabshell_ui