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