iced_core/text/
paragraph.rs

1//! Draw paragraphs.
2use crate::alignment;
3use crate::text::{
4    Alignment, Difference, Ellipsis, Hit, LineHeight, Shaping, Span, Text, Wrapping,
5};
6use crate::{Font, Pixels, Point, Rectangle, Size};
7
8/// A text paragraph.
9pub trait Paragraph: Sized + Default {
10    /// Creates a new [`Paragraph`] laid out with the given [`Text`].
11    fn with_text(text: Text<&str>) -> Self;
12
13    /// Creates a new [`Paragraph`] laid out with the given [`Text`].
14    fn with_spans<Link>(text: Text<&[Span<'_, Link>]>) -> Self;
15
16    /// Lays out the [`Paragraph`] with some new boundaries.
17    fn resize(&mut self, new_bounds: Size);
18
19    /// Compares the [`Paragraph`] with some desired [`Text`] and returns the
20    /// [`Difference`].
21    fn compare(&self, text: Text<()>) -> Difference;
22
23    /// Returns the text size of the [`Paragraph`] in [`Pixels`].
24    fn size(&self) -> Pixels;
25
26    /// Returns the hint factor of the [`Paragraph`].
27    fn hint_factor(&self) -> Option<f32>;
28
29    /// Returns the [`Font`] of the [`Paragraph`].
30    fn font(&self) -> Font;
31
32    /// Returns the [`LineHeight`] of the [`Paragraph`].
33    fn line_height(&self) -> LineHeight;
34
35    /// Returns the horizontal alignment of the [`Paragraph`].
36    fn align_x(&self) -> Alignment;
37
38    /// Returns the vertical alignment of the [`Paragraph`].
39    fn align_y(&self) -> alignment::Vertical;
40
41    /// Returns the [`Wrapping`] strategy of the [`Paragraph`]>
42    fn wrapping(&self) -> Wrapping;
43
44    /// Returns the [`Ellipsis`] strategy of the [`Paragraph`]>
45    fn ellipsis(&self) -> Ellipsis;
46
47    /// Returns the [`Shaping`] strategy of the [`Paragraph`]>
48    fn shaping(&self) -> Shaping;
49
50    /// Returns the available bounds used to layout the [`Paragraph`].
51    fn bounds(&self) -> Size;
52
53    /// Returns the minimum boundaries that can fit the contents of the
54    /// [`Paragraph`].
55    fn min_bounds(&self) -> Size;
56
57    /// Tests whether the provided point is within the boundaries of the
58    /// [`Paragraph`], returning information about the nearest character.
59    fn hit_test(&self, point: Point) -> Option<Hit>;
60
61    /// Tests whether the provided point is within the boundaries of a
62    /// [`Span`] in the [`Paragraph`], returning the index of the [`Span`]
63    /// that was hit.
64    fn hit_span(&self, point: Point) -> Option<usize>;
65
66    /// Returns all bounds for the provided [`Span`] index of the [`Paragraph`].
67    /// A [`Span`] can have multiple bounds for each line it's on.
68    fn span_bounds(&self, index: usize) -> Vec<Rectangle>;
69
70    /// Returns the minimum width that can fit the contents of the [`Paragraph`].
71    fn min_width(&self) -> f32 {
72        self.min_bounds().width
73    }
74
75    /// Returns the minimum height that can fit the contents of the [`Paragraph`].
76    fn min_height(&self) -> f32 {
77        self.min_bounds().height
78    }
79}
80
81/// A [`Paragraph`] of plain text.
82#[derive(Debug, Clone, Default)]
83pub struct Plain<P: Paragraph> {
84    raw: P,
85    content: String,
86}
87
88impl<P: Paragraph> Plain<P> {
89    /// Creates a new [`Plain`] paragraph.
90    pub fn new(text: Text<String>) -> Self {
91        Self {
92            raw: P::with_text(text.as_ref()),
93            content: text.content,
94        }
95    }
96
97    /// Updates the plain [`Paragraph`] to match the given [`Text`], if needed.
98    ///
99    /// Returns true if the [`Paragraph`] changed.
100    pub fn update(&mut self, text: Text<&str>) -> bool {
101        if self.content != text.content {
102            text.content.clone_into(&mut self.content);
103            self.raw = P::with_text(text);
104            return true;
105        }
106
107        match self.raw.compare(text.with_content(())) {
108            Difference::None => false,
109            Difference::Bounds => {
110                self.raw.resize(text.bounds);
111                true
112            }
113            Difference::Shape => {
114                self.raw = P::with_text(text);
115                true
116            }
117        }
118    }
119
120    /// Returns the horizontal alignment of the [`Paragraph`].
121    pub fn align_x(&self) -> Alignment {
122        self.raw.align_x()
123    }
124
125    /// Returns the vertical alignment of the [`Paragraph`].
126    pub fn align_y(&self) -> alignment::Vertical {
127        self.raw.align_y()
128    }
129
130    /// Returns the minimum boundaries that can fit the contents of the
131    /// [`Paragraph`].
132    pub fn min_bounds(&self) -> Size {
133        self.raw.min_bounds()
134    }
135
136    /// Returns the minimum width that can fit the contents of the
137    /// [`Paragraph`].
138    pub fn min_width(&self) -> f32 {
139        self.raw.min_width()
140    }
141
142    /// Returns the minimum height that can fit the contents of the
143    /// [`Paragraph`].
144    pub fn min_height(&self) -> f32 {
145        self.raw.min_height()
146    }
147
148    /// Returns the cached [`Paragraph`].
149    pub fn raw(&self) -> &P {
150        &self.raw
151    }
152
153    /// Returns the current content of the plain [`Paragraph`].
154    pub fn content(&self) -> &str {
155        &self.content
156    }
157
158    /// Returns the [`Paragraph`] as a [`Text`] definition.
159    pub fn as_text(&self) -> Text<&str> {
160        Text {
161            content: &self.content,
162            bounds: self.raw.bounds(),
163            size: self.raw.size(),
164            line_height: self.raw.line_height(),
165            font: self.raw.font(),
166            align_x: self.raw.align_x(),
167            align_y: self.raw.align_y(),
168            shaping: self.raw.shaping(),
169            wrapping: self.raw.wrapping(),
170            ellipsis: self.raw.ellipsis(),
171            hint_factor: self.raw.hint_factor(),
172        }
173    }
174}
iced_core/text/paragraph.rs

iced_core/text/
paragraph.rs
