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