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