Skip to main content

textflow/
lib.rs

1//! Bounded `no_std` Unicode text layout and shaping.
2//!
3//! [`TextFlow`] provides borrowed line layout with explicit width, height, and spacing metrics.
4//! The optional shaping pipeline adds bidirectional text, font fallback, safe line breaking,
5//! positioned glyphs, visual runs, and caret positions through caller-owned buffers.
6//!
7//! # Line layout
8//!
9//! ```
10//! use textflow::TextFlow;
11//!
12//! let text = "A small UI can still set type well.";
13//! let lines = TextFlow::new(text, 12)
14//!     .map(|line| line.text())
15//!     .collect::<Vec<_>>();
16//!
17//! assert_eq!(lines, ["A small UI", "can still", "set type", "well."]);
18//! ```
19
20#![no_std]
21
22#[cfg(feature = "alloc")]
23extern crate alloc;
24#[cfg(test)]
25extern crate std;
26
27use crate::line::Lines;
28
29pub use crate::line::Line;
30
31#[cfg(feature = "shaping")]
32use crate::bidi::BaseDirection;
33#[cfg(all(feature = "alloc", feature = "shaping"))]
34use crate::shaping::Typeface;
35#[cfg(feature = "shaping")]
36use crate::shaping::{FlowPoint, FontFeature};
37#[cfg(all(feature = "alloc", feature = "shaping"))]
38use crate::workspace::{TextWorkspace, WorkspaceError};
39
40#[cfg(feature = "shaping")]
41mod buffer;
42mod line;
43mod properties;
44
45#[cfg(feature = "bidi")]
46pub mod bidi;
47#[cfg(feature = "shaping")]
48pub mod layout;
49#[cfg(feature = "shaping")]
50pub mod shaping;
51#[cfg(not(feature = "unicode"))]
52mod unicode;
53#[cfg(feature = "unicode")]
54pub mod unicode;
55#[cfg(all(feature = "alloc", feature = "shaping"))]
56pub mod workspace;
57
58pub struct TextFlow<'a> {
59    text: &'a str,
60    max_width: usize,
61    line_height: usize,
62    line_spacing: usize,
63    lines: Lines<'a>,
64    #[cfg(feature = "shaping")]
65    base_direction: BaseDirection,
66    #[cfg(feature = "shaping")]
67    features: &'a [FontFeature],
68    #[cfg(feature = "shaping")]
69    origin: FlowPoint,
70}
71
72impl<'a> TextFlow<'a> {
73    pub fn new(text: &'a str, max_width: usize) -> Self {
74        let mut flow = TextFlow {
75            text,
76            max_width,
77            line_height: 0,
78            line_spacing: 0,
79            lines: Lines::new("", 0, 4),
80            #[cfg(feature = "shaping")]
81            base_direction: BaseDirection::Auto,
82            #[cfg(feature = "shaping")]
83            features: &[],
84            #[cfg(feature = "shaping")]
85            origin: FlowPoint { x: 0, y: 0 },
86        };
87
88        flow.lines = Lines::new(flow.text, flow.max_width, 4);
89
90        flow
91    }
92
93    pub const fn with_line_height(mut self, line_height: usize) -> Self {
94        self.line_height = line_height;
95        self
96    }
97
98    pub const fn with_line_spacing(mut self, line_spacing: usize) -> Self {
99        self.line_spacing = line_spacing;
100        self
101    }
102
103    #[cfg(feature = "shaping")]
104    pub const fn with_direction(mut self, direction: BaseDirection) -> Self {
105        self.base_direction = direction;
106        self
107    }
108
109    #[cfg(feature = "shaping")]
110    pub fn with_features(mut self, features: &'a [FontFeature]) -> Self {
111        self.features = features;
112        self
113    }
114
115    #[cfg(feature = "shaping")]
116    pub const fn with_origin(mut self, origin: FlowPoint) -> Self {
117        self.origin = origin;
118        self
119    }
120
121    #[cfg(all(feature = "alloc", feature = "shaping"))]
122    pub fn layout<'workspace>(
123        &self,
124        typefaces: &[&dyn Typeface],
125        workspace: &'workspace mut TextWorkspace,
126    ) -> Result<layout::ParagraphLayout<'workspace>, WorkspaceError> {
127        workspace.layout(self, typefaces)
128    }
129}
130
131impl<'a> Iterator for TextFlow<'a> {
132    type Item = Line<'a>;
133
134    fn next(&mut self) -> Option<Self::Item> {
135        let mut line = self.lines.next()?;
136        line.set_metrics(self.line_height, self.line_spacing);
137        Some(line)
138    }
139}