crabshell_ui/
lib.rs

1//! Crabshell's widgets, styles, layout, text layout, hit testing and
2//! invalidation.
3//!
4//! A bar is described with widgets and turned into a live [`Window`]:
5//!
6//! ```
7//! use crabshell_reactive::Runtime;
8//! use crabshell_ui::prelude::*;
9//!
10//! const BAR: Style = Style::new()
11//!     .background(Color::rgb(0x1e, 0x1e, 0x2e))
12//!     .color(Color::rgb(0xcd, 0xd6, 0xf4));
13//!
14//! let runtime = Runtime::current();
15//! let cx = Cx::new(runtime.new_owner());
16//! let count = cx.signal(0);
17//!
18//! let bar = PanelWindow::new(&Output::new("DP-1"))
19//!     .anchors(Edge::Top | Edge::Left | Edge::Right)
20//!     .height(30)
21//!     .style(BAR)
22//!     .child(
23//!         Row::new().gap(8).padding(4, 8).child(
24//!             Button::new(Text::new(move || format!("clicked {} times", count.get())))
25//!                 .on_click(move |_cx| count.update(|n| *n += 1)),
26//!         ),
27//!     );
28//!
29//! // The platform does the rest once per event-loop iteration.
30//! let window = Window::new(&cx, bar);
31//! let mut text = TextSystem::new();
32//! window.set_size(Size::new(1920.0, 30.0));
33//! runtime.flush(); // bindings run
34//! window.layout(&mut text);
35//! let _damage = window.take_damage(); // what the renderer repaints
36//! ```
37//!
38//! # How it fits together
39//!
40//! - Widgets are descriptions. [`Window::new`] turns them into a tree of
41//!   nodes, each with its own reactive owner. A property given a closure
42//!   becomes an effect that writes the node when a signal it read changes.
43//! - Each property is a layout property (text, font, padding, gap, size,
44//!   children) or a paint property (colors, background, border, opacity,
45//!   radius). A paint change records the widget's area as damage. A layout
46//!   change marks the window for [`Window::layout`], which records the old
47//!   and new area of every widget that moved or changed.
48//! - [`TextSystem`] loads only the fonts fontconfig matches for the families
49//!   styles name, plus fallbacks for missing characters. Each `Text` keeps
50//!   one cosmic-text buffer that layout measures and the renderer draws.
51//! - Pointer events go to [`Window::pointer_motion`] and friends. Hit testing
52//!   finds the deepest [`Button`] under the pointer, and its handlers run
53//!   with no borrow held, inside `catch_unwind`.
54//! - Dropping a [`Window`] disposes its owner, freeing every node, binding
55//!   and handler it made.
56
57#![forbid(unsafe_code)]
58#![warn(missing_docs)]
59
60mod cx;
61mod geometry;
62mod input;
63mod keyed;
64mod layout;
65mod menu;
66mod popup;
67mod prop;
68mod style;
69mod text;
70mod tree;
71mod view;
72mod widgets;
73mod window;
74
75#[cfg(test)]
76mod tests;
77
78pub use cx::Cx;
79pub use geometry::{Point, Rect, Size};
80pub use input::{CursorShape, PointerButton, ScrollDelta};
81pub use menu::{Menu, MenuEntry, MenuToggle};
82pub use popup::PopupWindow;
83pub use prop::{IntoProp, Prop};
84pub use style::{Border, Color, Font, Padding, Style};
85pub use text::TextSystem;
86pub use view::{Content, IconView, NodeView, TextView, WindowView};
87pub use widgets::{
88  Align, Button, Column, Element, Icon, IconPixels, IconSource, Justify, Row, Spacer, Stack, Text,
89  Widget,
90};
91pub use window::{Anchors, Edge, Layer, Output, PanelWindow, SurfaceConfig, Window};
92
93/// What a bar's code needs, in one `use`.
94pub mod prelude {
95  pub use crate::{
96    Align, Button, Color, Column, Cx, Edge, Font, Icon, IconSource, Justify, Layer, Menu, Output,
97    PanelWindow, PopupWindow, Row, Size, Spacer, Stack, Style, Text, TextSystem, Widget, Window,
98  };
99}
crabshell_ui/lib.rs

crabshell_ui/
lib.rs
