Merge pull request #105 from kas-gui/push-zvszylowqqqo

Expose per-line data

Author: dhardy

Cargo.toml

@@ -15,7 +15,7 @@ rust-version = "1.88.0"
 
 [package.metadata.docs.rs]
 # To build locally:
-# RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features --no-deps --open
+# cargo +nightly doc --all-features --no-deps --open
 all-features = true
 
 [features]

src/data.rs

@@ -118,11 +118,6 @@ impl Range {
         to_usize(self.end) - to_usize(self.start)
     }
 
-    /// True if the given value is contained, inclusive of end points
-    pub fn includes(self, value: usize) -> bool {
-        to_usize(self.start) <= value && value <= to_usize(self.end)
-    }
-
     /// Convert to a standard range
     pub fn to_std(self) -> std::ops::Range<usize> {
         to_usize(self.start)..to_usize(self.end)

src/display/glyph_pos.rs

@@ -478,7 +478,7 @@ impl TextDisplay {
     /// Calls `f(top_left, bottom_right)` for each highlighting rectangle.
     pub fn highlight_range(&self, range: std::ops::Range<usize>, f: &mut dyn FnMut(Vec2, Vec2)) {
         for line in &self.lines {
-            let line_range: std::ops::Range<usize> = line.text_range.into();
+            let line_range = line.text_range();
             if line_range.end <= range.start {
                 continue;
             } else if range.end <= line_range.start {

src/display/mod.rs

@@ -17,7 +17,8 @@ mod text_runs;
 mod wrap_lines;
 pub use glyph_pos::{Effect, EffectFlags, GlyphRun, MarkerPos, MarkerPosIter};
 pub(crate) use text_runs::RunSpecial;
-use wrap_lines::{Line, RunPart};
+pub use wrap_lines::Line;
+use wrap_lines::RunPart;
 
 /// Error returned on operations if not ready
 ///
@@ -77,7 +78,7 @@ pub struct NotReady;
 /// direction in bi-directional text).
 ///
 /// Navigating to the start or end of a line can be done with
-/// [`TextDisplay::find_line`] and [`TextDisplay::line_range`].
+/// [`TextDisplay::find_line`], [`TextDisplay::get_line`] and [`Line::text_range`].
 ///
 /// Navigating forwards or backwards should be done via a library such as
 /// [`unicode-segmentation`](https://github.com/unicode-rs/unicode-segmentation)
@@ -151,10 +152,27 @@ impl TextDisplay {
     /// Get the number of lines (after wrapping)
     ///
     /// [Requires status][Self#status-of-preparation]: lines have been wrapped.
+    #[inline]
     pub fn num_lines(&self) -> usize {
         self.lines.len()
     }
 
+    /// Get line properties
+    ///
+    /// [Requires status][Self#status-of-preparation]: lines have been wrapped.
+    #[inline]
+    pub fn get_line(&self, index: usize) -> Option<&Line> {
+        self.lines.get(index)
+    }
+
+    /// Iterate over line properties
+    ///
+    /// [Requires status][Self#status-of-preparation]: lines have been wrapped.
+    #[inline]
+    pub fn lines(&self) -> impl Iterator<Item = &Line> {
+        self.lines.iter()
+    }
+
     /// Get the size of the required bounding box
     ///
     /// [Requires status][Self#status-of-preparation]: lines have been wrapped.
@@ -184,25 +202,19 @@ impl TextDisplay {
     pub fn find_line(&self, index: usize) -> Option<(usize, std::ops::Range<usize>)> {
         let mut first = None;
         for (n, line) in self.lines.iter().enumerate() {
-            if line.text_range.end() == index {
+            let text_range = line.text_range();
+            if text_range.end == index {
                 // When line wrapping, this also matches the start of the next
                 // line which is the preferred location. At the end of other
                 // lines it does not match any other location.
-                first = Some((n, line.text_range.to_std()));
-            } else if line.text_range.includes(index) {
-                return Some((n, line.text_range.to_std()));
+                first = Some((n, text_range));
+            } else if text_range.contains(&index) {
+                return Some((n, text_range));
             }
         }
         first
     }
 
-    /// Get the range of a line, by line number
-    ///
-    /// [Requires status][Self#status-of-preparation]: lines have been wrapped.
-    pub fn line_range(&self, line: usize) -> Option<std::ops::Range<usize>> {
-        self.lines.get(line).map(|line| line.text_range.to_std())
-    }
-
     /// Get the base directionality of the text
     ///
     /// [Requires status][Self#status-of-preparation]: none.
@@ -281,11 +293,11 @@ impl TextDisplay {
         let line = &self.lines[line];
         let run_range = line.run_range.to_std();
 
-        let mut best = line.text_range.start;
+        let mut best = line.text_range().start;
         let mut best_dist = f32::INFINITY;
-        let mut try_best = |dist, index| {
+        let mut try_best = |dist, index: u32| {
             if dist < best_dist {
-                best = index;
+                best = to_usize(index);
                 best_dist = dist;
             }
         };
@@ -319,6 +331,6 @@ impl TextDisplay {
             try_best((end_pos - rel_pos).abs(), end_index);
         }
 
-        Some(to_usize(best))
+        Some(best)
     }
 }

src/display/wrap_lines.rs

@@ -11,6 +11,7 @@ use crate::fonts::{self, FontLibrary};
 use crate::shaper::{GlyphRun, PartMetrics};
 use crate::{Align, Range, Vec2};
 use smallvec::SmallVec;
+use std::num::NonZeroUsize;
 use tinyvec::TinyVec;
 use unicode_bidi::{LTR_LEVEL, Level};
 
@@ -22,12 +23,33 @@ pub struct RunPart {
     pub offset: Vec2,
 }
 
+/// Per-line data (post wrapping)
 #[derive(Clone, Debug, Default)]
 pub struct Line {
-    pub text_range: Range, // range in text
-    pub run_range: Range,  // range in wrapped_runs
-    pub top: f32,
-    pub bottom: f32,
+    text_range: Range,           // range in text
+    pub(crate) run_range: Range, // range in wrapped_runs
+    pub(crate) top: f32,
+    pub(crate) bottom: f32,
+}
+
+impl Line {
+    /// Get the text range of line contents
+    #[inline]
+    pub fn text_range(&self) -> std::ops::Range<usize> {
+        self.text_range.to_std()
+    }
+
+    /// Get the upper bound of the line
+    #[inline]
+    pub fn top(&self) -> f32 {
+        self.top
+    }
+
+    /// Get the lower bound of the line
+    #[inline]
+    pub fn bottom(&self) -> f32 {
+        self.bottom
+    }
 }
 
 impl TextDisplay {
@@ -70,16 +92,15 @@ impl TextDisplay {
 
     /// Measure required vertical height, wrapping as configured
     ///
+    /// Stops after `max_lines`, if provided.
+    ///
     /// [Requires status][Self#status-of-preparation]: level runs have been
     /// prepared.
-    ///
-    /// This method performs most required preparation steps of the
-    /// [`TextDisplay`]. Remaining prepartion should be fast.
-    pub fn measure_height(&self, wrap_width: f32) -> f32 {
+    pub fn measure_height(&self, wrap_width: f32, max_lines: Option<NonZeroUsize>) -> f32 {
         #[derive(Default)]
         struct MeasureAdder {
             parts: Vec<usize>, // run index for each part
-            has_any_lines: bool,
+            lines: usize,
             line_gap: f32,
             vcaret: f32,
         }
@@ -89,6 +110,10 @@ impl TextDisplay {
                 self.parts.len()
             }
 
+            fn num_lines(&self) -> usize {
+                self.lines
+            }
+
             fn add_part(
                 &mut self,
                 _: &[GlyphRun],
@@ -134,7 +159,7 @@ impl TextDisplay {
                     line_gap = line_gap.max(scale_font.line_gap());
                 }
 
-                if self.has_any_lines {
+                if self.lines > 0 {
                     self.vcaret += line_gap.max(self.line_gap);
                 }
                 self.vcaret += ascent - descent;
@@ -143,13 +168,14 @@ impl TextDisplay {
                 // Vertically align lines to the nearest pixel (improves rendering):
                 self.vcaret = self.vcaret.round();
 
-                self.has_any_lines = true;
+                self.lines += 1;
                 self.parts.clear();
             }
         }
 
         let mut adder = MeasureAdder::default();
-        self.wrap_lines(&mut adder, wrap_width);
+        let max_lines = max_lines.map(|n| n.get()).unwrap_or(0);
+        self.wrap_lines(&mut adder, wrap_width, max_lines);
         adder.vcaret
     }
 
@@ -188,7 +214,7 @@ impl TextDisplay {
         debug_assert!(width_bound.is_finite());
         let mut adder = LineAdder::new(width_bound, h_align);
 
-        self.wrap_lines(&mut adder, wrap_width);
+        self.wrap_lines(&mut adder, wrap_width, 0);
 
         self.wrapped_runs = adder.wrapped_runs;
         self.lines = adder.lines;
@@ -201,7 +227,12 @@ impl TextDisplay {
         adder.vcaret
     }
 
-    fn wrap_lines(&self, accumulator: &mut impl PartAccumulator, wrap_width: f32) {
+    fn wrap_lines(
+        &self,
+        accumulator: &mut impl PartAccumulator,
+        wrap_width: f32,
+        max_lines: usize,
+    ) {
         let fonts = fonts::library();
 
         // Tuples: (index, part_index, num_parts)
@@ -244,6 +275,10 @@ impl TextDisplay {
                     // Add up to last valid break point then wrap and reset
                     accumulator.add_line(fonts, &self.runs, end.2, true);
 
+                    if accumulator.num_lines() == max_lines {
+                        return;
+                    }
+
                     end.2 = 0;
                     start = end;
                     caret = 0.0;
@@ -276,6 +311,10 @@ impl TextDisplay {
                     debug_assert_eq!(num_parts, end.2);
 
                     accumulator.add_line(fonts, &self.runs, num_parts, false);
+
+                    if accumulator.num_lines() == max_lines {
+                        return;
+                    }
                 }
 
                 start = (run_index, 0, 0);
@@ -332,6 +371,7 @@ impl TextDisplay {
 
 trait PartAccumulator {
     fn num_parts(&self) -> usize;
+    fn num_lines(&self) -> usize;
 
     fn add_part(
         &mut self,
@@ -386,6 +426,10 @@ impl PartAccumulator for LineAdder {
         self.parts.len()
     }
 
+    fn num_lines(&self) -> usize {
+        self.lines.len()
+    }
+
     fn add_part(
         &mut self,
         runs: &[GlyphRun],

src/lib.rs

@@ -13,16 +13,15 @@
 //!
 //! [`format`]: mod@format
 
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
-
 mod env;
 pub use env::*;
 
 mod conv;
 pub use conv::DPU;
 
 mod data;
-pub use data::{Range, Vec2};
+use data::Range;
+pub use data::Vec2;
 
 mod display;
 pub use display::*;

src/text.rs

@@ -8,7 +8,8 @@
 use crate::display::{Effect, MarkerPosIter, NotReady, TextDisplay};
 use crate::fonts::{FontSelector, NoFontMatch};
 use crate::format::FormattableText;
-use crate::{Align, Direction, GlyphRun, Status, Vec2};
+use crate::{Align, Direction, GlyphRun, Line, Status, Vec2};
+use std::num::NonZeroUsize;
 
 /// Text type-setting object (high-level API)
 ///
@@ -420,14 +421,16 @@ impl<T: FormattableText + ?Sized> Text<T> {
     }
 
     /// Measure required vertical height, wrapping as configured
-    pub fn measure_height(&mut self) -> Result<f32, NoFontMatch> {
+    ///
+    /// Stops after `max_lines`, if provided.
+    pub fn measure_height(&mut self, max_lines: Option<NonZeroUsize>) -> Result<f32, NoFontMatch> {
         if self.status >= Status::Wrapped {
             let (tl, br) = self.display.bounding_box();
             return Ok(br.1 - tl.1);
         }
 
         self.prepare_runs()?;
-        Ok(self.display.measure_height(self.wrap_width))
+        Ok(self.display.measure_height(self.wrap_width, max_lines))
     }
 
     /// Prepare text for display, as necessary
@@ -471,6 +474,7 @@ impl<T: FormattableText + ?Sized> Text<T> {
     pub fn bounding_box(&self) -> Result<(Vec2, Vec2), NotReady> {
         Ok(self.wrapped_display()?.bounding_box())
     }
+
     /// Get the number of lines (after wrapping)
     ///
     /// See [`TextDisplay::num_lines`].
@@ -479,6 +483,20 @@ impl<T: FormattableText + ?Sized> Text<T> {
         Ok(self.wrapped_display()?.num_lines())
     }
 
+    /// Get line properties
+    #[inline]
+    pub fn get_line(&self, index: usize) -> Result<Option<&Line>, NotReady> {
+        Ok(self.wrapped_display()?.get_line(index))
+    }
+
+    /// Iterate over line properties
+    ///
+    /// [Requires status][Self#status-of-preparation]: lines have been wrapped.
+    #[inline]
+    pub fn lines(&self) -> Result<impl Iterator<Item = &Line>, NotReady> {
+        Ok(self.wrapped_display()?.lines())
+    }
+
     /// Find the line containing text `index`
     ///
     /// See [`TextDisplay::find_line`].
@@ -490,14 +508,6 @@ impl<T: FormattableText + ?Sized> Text<T> {
         Ok(self.wrapped_display()?.find_line(index))
     }
 
-    /// Get the range of a line, by line number
-    ///
-    /// See [`TextDisplay::line_range`].
-    #[inline]
-    pub fn line_range(&self, line: usize) -> Result<Option<std::ops::Range<usize>>, NotReady> {
-        Ok(self.wrapped_display()?.line_range(line))
-    }
-
     /// Get the directionality of the current line
     ///
     /// See [`TextDisplay::line_is_rtl`].