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