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