Skip to main content

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