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::{Alignment, Overflow, WrapMode};
31pub use crate::line::Line;
32
33#[cfg(feature = "shaping")]
34use crate::bidi::BaseDirection;
35#[cfg(all(feature = "alloc", feature = "shaping"))]
36use crate::shaping::Typeface;
37#[cfg(feature = "shaping")]
38use crate::shaping::{FlowPoint, FontFeature};
39#[cfg(feature = "shaping")]
40use crate::unicode::LineBreakProvider;
41#[cfg(all(feature = "alloc", feature = "shaping"))]
42use crate::workspace::{TextWorkspace, WorkspaceError};
43
44#[cfg(feature = "bidi")]
45mod buffer;
46mod line;
47mod properties;
48
49#[cfg(feature = "bidi")]
50pub mod bidi;
51#[cfg(feature = "shaping")]
52pub mod layout;
53#[cfg(feature = "shaping")]
54pub mod shaping;
55#[cfg(any(feature = "script-arabic", feature = "script-thai"))]
56pub use crate::shaping::scripts;
57#[cfg(not(feature = "unicode"))]
58mod unicode;
59#[cfg(feature = "unicode")]
60pub mod unicode;
61#[cfg(all(feature = "alloc", feature = "shaping"))]
62pub mod workspace;
63
64pub struct TextFlow<'a> {
65    text: &'a str,
66    max_width: usize,
67    line_height: usize,
68    line_spacing: usize,
69    lines: Lines<'a>,
70    #[cfg(feature = "shaping")]
71    base_direction: BaseDirection,
72    #[cfg(feature = "shaping")]
73    features: &'a [FontFeature],
74    #[cfg(feature = "shaping")]
75    origin: FlowPoint,
76    #[cfg(feature = "shaping")]
77    wrap: WrapMode,
78    #[cfg(feature = "shaping")]
79    line_break_provider: Option<&'a dyn LineBreakProvider>,
80    #[cfg(feature = "shaping")]
81    letter_spacing: i32,
82    #[cfg(feature = "shaping")]
83    word_spacing: i32,
84    #[cfg(feature = "shaping")]
85    alignment: Alignment,
86    #[cfg(feature = "shaping")]
87    max_lines: usize,
88    #[cfg(feature = "shaping")]
89    overflow: Overflow,
90}
91
92impl<'a> TextFlow<'a> {
93    pub fn new(text: &'a str, max_width: usize) -> Self {
94        let mut flow = TextFlow {
95            text,
96            max_width,
97            line_height: 0,
98            line_spacing: 0,
99            lines: Lines::new("", 0, 4),
100            #[cfg(feature = "shaping")]
101            base_direction: BaseDirection::Auto,
102            #[cfg(feature = "shaping")]
103            features: &[],
104            #[cfg(feature = "shaping")]
105            origin: FlowPoint { x: 0, y: 0 },
106            #[cfg(feature = "shaping")]
107            wrap: WrapMode::Word,
108            #[cfg(feature = "shaping")]
109            line_break_provider: None,
110            #[cfg(feature = "shaping")]
111            letter_spacing: 0,
112            #[cfg(feature = "shaping")]
113            word_spacing: 0,
114            #[cfg(feature = "shaping")]
115            alignment: Alignment::Start,
116            #[cfg(feature = "shaping")]
117            max_lines: usize::MAX,
118            #[cfg(feature = "shaping")]
119            overflow: Overflow::Clip,
120        };
121
122        flow.lines = Lines::new(flow.text, flow.max_width, 4);
123
124        flow
125    }
126
127    pub const fn with_line_height(mut self, line_height: usize) -> Self {
128        self.line_height = line_height;
129        self
130    }
131
132    pub const fn with_line_spacing(mut self, line_spacing: usize) -> Self {
133        self.line_spacing = line_spacing;
134        self
135    }
136
137    #[cfg(feature = "shaping")]
138    pub const fn with_direction(mut self, direction: BaseDirection) -> Self {
139        self.base_direction = direction;
140        self
141    }
142
143    #[cfg(feature = "shaping")]
144    pub fn with_features(mut self, features: &'a [FontFeature]) -> Self {
145        self.features = features;
146        self
147    }
148
149    #[cfg(feature = "shaping")]
150    pub const fn with_origin(mut self, origin: FlowPoint) -> Self {
151        self.origin = origin;
152        self
153    }
154
155    #[cfg(feature = "shaping")]
156    pub const fn with_wrap(mut self, wrap: WrapMode) -> Self {
157        self.wrap = wrap;
158        self
159    }
160
161    #[cfg(feature = "shaping")]
162    /// Adds application-defined line breaks without transferring ownership.
163    pub const fn with_line_break_provider(mut self, provider: &'a dyn LineBreakProvider) -> Self {
164        self.line_break_provider = Some(provider);
165        self
166    }
167
168    #[cfg(feature = "shaping")]
169    pub const fn with_letter_spacing(mut self, spacing: i32) -> Self {
170        self.letter_spacing = spacing;
171        self
172    }
173
174    #[cfg(feature = "shaping")]
175    pub const fn with_word_spacing(mut self, spacing: i32) -> Self {
176        self.word_spacing = spacing;
177        self
178    }
179
180    #[cfg(feature = "shaping")]
181    pub const fn with_alignment(mut self, alignment: Alignment) -> Self {
182        self.alignment = alignment;
183        self
184    }
185
186    #[cfg(feature = "shaping")]
187    pub const fn with_max_lines(mut self, max_lines: usize) -> Self {
188        self.max_lines = max_lines;
189        self
190    }
191
192    #[cfg(feature = "shaping")]
193    pub const fn with_overflow(mut self, overflow: Overflow) -> Self {
194        self.overflow = overflow;
195        self
196    }
197
198    #[cfg(all(feature = "alloc", feature = "shaping"))]
199    pub fn layout<'workspace>(
200        &self,
201        typefaces: &[&dyn Typeface],
202        workspace: &'workspace mut TextWorkspace,
203    ) -> Result<layout::ParagraphLayout<'workspace>, WorkspaceError> {
204        workspace.layout(self, typefaces)
205    }
206}
207
208impl<'a> Iterator for TextFlow<'a> {
209    type Item = Line<'a>;
210
211    fn next(&mut self) -> Option<Self::Item> {
212        let mut line = self.lines.next()?;
213        line.set_metrics(self.line_height, self.line_spacing);
214        Some(line)
215    }
216}