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