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