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