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 animation;
61mod cx;
62mod edit;
63mod floating;
64mod geometry;
65mod input;
66mod keyboard;
67mod keyed;
68mod layout;
69mod lock;
70mod menu;
71mod popup;
72mod prop;
73mod region;
74mod screencopy;
75mod scroll;
76mod style;
77mod text;
78mod text_input;
79mod timer;
80mod tree;
81mod view;
82mod widgets;
83mod window;
84
85#[cfg(test)]
86mod tests;
87
88pub use animation::{
89  Animate, Animation, Easing, Spring, Transition, advance_animations, animating,
90};
91pub use cx::Cx;
92pub use floating::{FloatingConfig, FloatingWindow, WindowRequest};
93pub use geometry::{Affine, Point, Rect, Size};
94pub use input::{CursorShape, PointerButton, ScrollDelta};
95pub use keyboard::{Clipboard, Key, KeyEvent, Modifiers};
96pub use lock::{Lock, SessionLock};
97pub use menu::{Menu, MenuEntry, MenuToggle};
98pub use popup::{Adjust, Placement, PopupWindow};
99pub use prop::{IntoProp, Prop};
100pub use region::Region;
101pub use screencopy::{CaptureFrame, CaptureRequest, CaptureSource, ScreencopyView};
102pub use scroll::{ListView, ScrollView};
103pub use style::{Border, Color, Font, Gradient, GradientShape, Padding, Shadow, Style};
104pub use text::TextSystem;
105pub use text_input::{FieldState, Preedit, TextInput};
106pub use timer::{Timer, fire_timers, next_timer};
107pub use view::{
108  CaptureView, Content, IconView, ImageView, InputView, NodeView, TextView, WindowView,
109};
110pub use widgets::{
111  Align, Button, Column, Element, Fit, Icon, IconPixels, IconSource, Image, Justify, Row, Spacer,
112  Stack, Text, Widget,
113};
114pub use window::{
115  Anchors, Edge, KeyboardFocus, Layer, Margins, Output, PanelWindow, SurfaceConfig, Window,
116};
117
118/// What a bar's code needs, in one `use`.
119pub mod prelude {
120  pub use crate::{
121    Align, Button, Color, Column, Cx, Edge, Font, Icon, IconSource, Justify, Layer, Menu, Output,
122    PanelWindow, PopupWindow, Row, Size, Spacer, Stack, Style, Text, TextSystem, Timer, Widget,
123    Window,
124  };
125}
crabshell_ui/lib.rs

crabshell_ui/
lib.rs
