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
29#[cfg(feature = "shaping")]
30pub use crate::layout::{
31    Alignment, LayoutError, LayoutScratch, Overflow, ParagraphLayout, WrapMode,
32};
33pub use crate::line::Line;
34
35#[cfg(feature = "shaping")]
36use crate::bidi::{BaseDirection, Direction};
37#[cfg(feature = "shaping")]
38use crate::layout::LayoutOptions;
39#[cfg(all(feature = "alloc", feature = "shaping"))]
40use crate::shaping::Typeface;
41#[cfg(feature = "shaping")]
42use crate::shaping::{FlowPoint, FontFeature};
43#[cfg(feature = "shaping")]
44use crate::unicode::LineBreakProvider;
45#[cfg(all(feature = "alloc", feature = "shaping"))]
46use crate::workspace::{LayoutOutput, TextWorkspace, WorkspaceError};
47
48#[cfg(feature = "bidi")]
49mod buffer;
50mod line;
51mod properties;
52
53#[cfg(feature = "bidi")]
54pub mod bidi;
55#[cfg(feature = "shaping")]
56pub mod layout;
57#[cfg(feature = "shaping")]
58pub mod shaping;
59#[cfg(any(
60    feature = "script-arabic",
61    feature = "script-thai",
62    feature = "script-devanagari"
63))]
64pub use crate::shaping::scripts;
65#[cfg(not(feature = "unicode"))]
66mod unicode;
67#[cfg(feature = "unicode")]
68pub mod unicode;
69#[cfg(all(feature = "alloc", feature = "shaping"))]
70pub mod workspace;
71
72pub struct TextFlow<'a> {
73    #[cfg(feature = "shaping")]
74    text: &'a str,
75    #[cfg(feature = "shaping")]
76    max_width: usize,
77    #[cfg(feature = "shaping")]
78    width: Option<usize>,
79    line_height: usize,
80    line_spacing: usize,
81    lines: Lines<'a>,
82    #[cfg(feature = "shaping")]
83    base_direction: BaseDirection,
84    #[cfg(feature = "shaping")]
85    features: &'a [FontFeature],
86    #[cfg(feature = "shaping")]
87    origin: FlowPoint,
88    #[cfg(feature = "shaping")]
89    wrap: WrapMode,
90    #[cfg(feature = "shaping")]
91    line_break_provider: Option<&'a dyn LineBreakProvider>,
92    #[cfg(feature = "shaping")]
93    letter_spacing: i32,
94    #[cfg(feature = "shaping")]
95    word_spacing: i32,
96    #[cfg(feature = "shaping")]
97    alignment: Alignment,
98    #[cfg(feature = "shaping")]
99    max_lines: usize,
100    #[cfg(feature = "shaping")]
101    overflow: Overflow,
102}
103
104impl<'a> TextFlow<'a> {
105    pub fn new(text: &'a str, max_width: usize) -> Self {
106        TextFlow {
107            #[cfg(feature = "shaping")]
108            text,
109            #[cfg(feature = "shaping")]
110            max_width,
111            #[cfg(feature = "shaping")]
112            width: Some(max_width),
113            line_height: 0,
114            line_spacing: 0,
115            lines: Lines::new(text, max_width, 4),
116            #[cfg(feature = "shaping")]
117            base_direction: BaseDirection::Auto,
118            #[cfg(feature = "shaping")]
119            features: &[],
120            #[cfg(feature = "shaping")]
121            origin: FlowPoint { x: 0, y: 0 },
122            #[cfg(feature = "shaping")]
123            wrap: WrapMode::Word,
124            #[cfg(feature = "shaping")]
125            line_break_provider: None,
126            #[cfg(feature = "shaping")]
127            letter_spacing: 0,
128            #[cfg(feature = "shaping")]
129            word_spacing: 0,
130            #[cfg(feature = "shaping")]
131            alignment: Alignment::Start,
132            #[cfg(feature = "shaping")]
133            max_lines: usize::MAX,
134            #[cfg(feature = "shaping")]
135            overflow: Overflow::Clip,
136        }
137    }
138
139    pub const fn with_line_height(mut self, line_height: usize) -> Self {
140        self.line_height = line_height;
141        self
142    }
143
144    pub const fn with_line_spacing(mut self, line_spacing: usize) -> Self {
145        self.line_spacing = line_spacing;
146        self
147    }
148
149    #[cfg(feature = "shaping")]
150    /// Sets the width used for alignment and overflow without changing line breaks.
151    pub const fn with_width(mut self, width: usize) -> Self {
152        self.width = Some(width);
153        self
154    }
155
156    #[cfg(feature = "shaping")]
157    /// Removes the width used for alignment and overflow without changing line breaks.
158    pub const fn without_width(mut self) -> Self {
159        self.width = None;
160        self
161    }
162
163    #[cfg(feature = "shaping")]
164    pub const fn with_direction(mut self, direction: BaseDirection) -> Self {
165        self.base_direction = direction;
166        self
167    }
168
169    #[cfg(feature = "shaping")]
170    pub fn with_features(mut self, features: &'a [FontFeature]) -> Self {
171        self.features = features;
172        self
173    }
174
175    #[cfg(feature = "shaping")]
176    pub const fn with_origin(mut self, origin: FlowPoint) -> Self {
177        self.origin = origin;
178        self
179    }
180
181    #[cfg(feature = "shaping")]
182    pub const fn with_wrap(mut self, wrap: WrapMode) -> Self {
183        self.wrap = wrap;
184        self
185    }
186
187    #[cfg(feature = "shaping")]
188    /// Adds application-defined line breaks without transferring ownership.
189    pub const fn with_line_break_provider(mut self, provider: &'a dyn LineBreakProvider) -> Self {
190        self.line_break_provider = Some(provider);
191        self
192    }
193
194    #[cfg(feature = "shaping")]
195    pub const fn with_letter_spacing(mut self, spacing: i32) -> Self {
196        self.letter_spacing = spacing;
197        self
198    }
199
200    #[cfg(feature = "shaping")]
201    pub const fn with_word_spacing(mut self, spacing: i32) -> Self {
202        self.word_spacing = spacing;
203        self
204    }
205
206    #[cfg(feature = "shaping")]
207    pub const fn with_alignment(mut self, alignment: Alignment) -> Self {
208        self.alignment = alignment;
209        self
210    }
211
212    #[cfg(feature = "shaping")]
213    pub const fn with_max_lines(mut self, max_lines: usize) -> Self {
214        self.max_lines = max_lines;
215        self
216    }
217
218    #[cfg(feature = "shaping")]
219    pub const fn with_overflow(mut self, overflow: Overflow) -> Self {
220        self.overflow = overflow;
221        self
222    }
223
224    #[cfg(feature = "shaping")]
225    /// Lays out a paragraph with fixed-capacity stack or static scratch storage.
226    pub fn layout_with_scratch<
227        'scratch,
228        const RUNS: usize,
229        const GLYPHS: usize,
230        const LINES: usize,
231        const CARETS: usize,
232    >(
233        &self,
234        typefaces: &[&dyn crate::shaping::Typeface],
235        scratch: &'scratch mut LayoutScratch<RUNS, GLYPHS, LINES, CARETS>,
236    ) -> Result<ParagraphLayout<'scratch>, LayoutError> {
237        scratch.layout(self, typefaces)
238    }
239
240    #[cfg(all(feature = "alloc", feature = "shaping"))]
241    /// Lays out a paragraph into caller-owned output using reusable private storage.
242    pub fn layout_into<'output>(
243        &self,
244        typefaces: &[&dyn Typeface],
245        workspace: &mut TextWorkspace,
246        output: &'output mut LayoutOutput<'_>,
247    ) -> Result<ParagraphLayout<'output>, WorkspaceError> {
248        let result = workspace.layout_into(self, typefaces, output)?;
249        Ok(output.layout(result))
250    }
251
252    #[cfg(feature = "shaping")]
253    fn layout_options(
254        &self,
255        line_advance: i32,
256        direction: Direction,
257        width: Option<i32>,
258    ) -> LayoutOptions {
259        let options = LayoutOptions::new(line_advance)
260            .with_origin(self.origin)
261            .with_spacing(layout::TextSpacing {
262                letter: self.letter_spacing,
263                word: self.word_spacing,
264            })
265            .with_alignment(self.alignment)
266            .with_direction(direction)
267            .with_max_lines(self.max_lines)
268            .with_overflow(self.overflow);
269        match width {
270            Some(width) => options.with_width(width),
271            None => options,
272        }
273    }
274}
275
276impl<'a> Iterator for TextFlow<'a> {
277    type Item = Line<'a>;
278
279    fn next(&mut self) -> Option<Self::Item> {
280        let mut line = self.lines.next()?;
281        line.set_metrics(self.line_height, self.line_spacing);
282        Some(line)
283    }
284}