iced_core/
text.rs

1//! Draw and interact with text.
2pub mod editor;
3pub mod highlighter;
4pub mod paragraph;
5
6pub use editor::Editor;
7pub use highlighter::Highlighter;
8pub use paragraph::Paragraph;
9
10use crate::alignment;
11use crate::{
12    Background, Border, Color, Padding, Pixels, Point, Rectangle, Size,
13};
14
15use std::borrow::Cow;
16use std::hash::{Hash, Hasher};
17
18/// A paragraph.
19#[derive(Debug, Clone, Copy)]
20pub struct Text<Content = String, Font = crate::Font> {
21    /// The content of the paragraph.
22    pub content: Content,
23
24    /// The bounds of the paragraph.
25    pub bounds: Size,
26
27    /// The size of the [`Text`] in logical pixels.
28    pub size: Pixels,
29
30    /// The line height of the [`Text`].
31    pub line_height: LineHeight,
32
33    /// The font of the [`Text`].
34    pub font: Font,
35
36    /// The horizontal alignment of the [`Text`].
37    pub align_x: Alignment,
38
39    /// The vertical alignment of the [`Text`].
40    pub align_y: alignment::Vertical,
41
42    /// The [`Shaping`] strategy of the [`Text`].
43    pub shaping: Shaping,
44
45    /// The [`Wrapping`] strategy of the [`Text`].
46    pub wrapping: Wrapping,
47}
48
49impl<Content, Font> Text<Content, Font>
50where
51    Font: Copy,
52{
53    /// Returns a new [`Text`] replacing only the content with the
54    /// given value.
55    pub fn with_content<T>(&self, content: T) -> Text<T, Font> {
56        Text {
57            content,
58            bounds: self.bounds,
59            size: self.size,
60            line_height: self.line_height,
61            font: self.font,
62            align_x: self.align_x,
63            align_y: self.align_y,
64            shaping: self.shaping,
65            wrapping: self.wrapping,
66        }
67    }
68}
69
70impl<Content, Font> Text<Content, Font>
71where
72    Content: AsRef<str>,
73    Font: Copy,
74{
75    /// Returns a borrowed version of [`Text`].
76    pub fn as_ref(&self) -> Text<&str, Font> {
77        self.with_content(self.content.as_ref())
78    }
79}
80
81/// The alignment of some text.
82#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
83pub enum Alignment {
84    /// No specific alignment.
85    ///
86    /// Left-to-right text will be aligned to the left, while
87    /// right-to-left text will be aligned to the right.
88    #[default]
89    Default,
90    /// Align text to the left.
91    Left,
92    /// Center text.
93    Center,
94    /// Align text to the right.
95    Right,
96    /// Justify text.
97    Justified,
98}
99
100impl From<alignment::Horizontal> for Alignment {
101    fn from(alignment: alignment::Horizontal) -> Self {
102        match alignment {
103            alignment::Horizontal::Left => Self::Left,
104            alignment::Horizontal::Center => Self::Center,
105            alignment::Horizontal::Right => Self::Right,
106        }
107    }
108}
109
110impl From<crate::Alignment> for Alignment {
111    fn from(alignment: crate::Alignment) -> Self {
112        match alignment {
113            crate::Alignment::Start => Self::Left,
114            crate::Alignment::Center => Self::Center,
115            crate::Alignment::End => Self::Right,
116        }
117    }
118}
119
120impl From<Alignment> for alignment::Horizontal {
121    fn from(alignment: Alignment) -> Self {
122        match alignment {
123            Alignment::Default | Alignment::Left | Alignment::Justified => {
124                alignment::Horizontal::Left
125            }
126            Alignment::Center => alignment::Horizontal::Center,
127            Alignment::Right => alignment::Horizontal::Right,
128        }
129    }
130}
131
132/// The shaping strategy of some text.
133#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
134pub enum Shaping {
135    /// Auto-detect the best shaping strategy from the text.
136    ///
137    /// This strategy will use [`Basic`](Self::Basic) shaping if the
138    /// text consists of only ASCII characters; otherwise, it will
139    /// use [`Advanced`](Self::Advanced) shaping.
140    ///
141    /// This is the default, if neither the `basic-shaping` nor `advanced-shaping`
142    /// features are enabled.
143    Auto,
144    /// No shaping and no font fallback.
145    ///
146    /// This shaping strategy is very cheap, but it will not display complex
147    /// scripts properly nor try to find missing glyphs in your system fonts.
148    ///
149    /// You should use this strategy when you have complete control of the text
150    /// and the font you are displaying in your application.
151    ///
152    /// This will be the default if the `basic-shaping` feature is enabled and
153    /// the `advanced-shaping` feature is disabled.
154    Basic,
155    /// Advanced text shaping and font fallback.
156    ///
157    /// You will need to enable this flag if the text contains a complex
158    /// script, the font used needs it, and/or multiple fonts in your system
159    /// may be needed to display all of the glyphs.
160    ///
161    /// Advanced shaping is expensive! You should only enable it when necessary.
162    ///
163    /// This will be the default if the `advanced-shaping` feature is enabled.
164    Advanced,
165}
166
167impl Default for Shaping {
168    fn default() -> Self {
169        if cfg!(feature = "advanced-shaping") {
170            Self::Advanced
171        } else if cfg!(feature = "basic-shaping") {
172            Self::Basic
173        } else {
174            Self::Auto
175        }
176    }
177}
178
179/// The wrapping strategy of some text.
180#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
181pub enum Wrapping {
182    /// No wrapping.
183    None,
184    /// Wraps at the word level.
185    ///
186    /// This is the default.
187    #[default]
188    Word,
189    /// Wraps at the glyph level.
190    Glyph,
191    /// Wraps at the word level, or fallback to glyph level if a word can't fit on a line by itself.
192    WordOrGlyph,
193}
194
195/// The height of a line of text in a paragraph.
196#[derive(Debug, Clone, Copy, PartialEq)]
197pub enum LineHeight {
198    /// A factor of the size of the text.
199    Relative(f32),
200
201    /// An absolute height in logical pixels.
202    Absolute(Pixels),
203}
204
205impl LineHeight {
206    /// Returns the [`LineHeight`] in absolute logical pixels.
207    pub fn to_absolute(self, text_size: Pixels) -> Pixels {
208        match self {
209            Self::Relative(factor) => Pixels(factor * text_size.0),
210            Self::Absolute(pixels) => pixels,
211        }
212    }
213}
214
215impl Default for LineHeight {
216    fn default() -> Self {
217        Self::Relative(1.3)
218    }
219}
220
221impl From<f32> for LineHeight {
222    fn from(factor: f32) -> Self {
223        Self::Relative(factor)
224    }
225}
226
227impl From<Pixels> for LineHeight {
228    fn from(pixels: Pixels) -> Self {
229        Self::Absolute(pixels)
230    }
231}
232
233impl Hash for LineHeight {
234    fn hash<H: Hasher>(&self, state: &mut H) {
235        match self {
236            Self::Relative(factor) => {
237                state.write_u8(0);
238                factor.to_bits().hash(state);
239            }
240            Self::Absolute(pixels) => {
241                state.write_u8(1);
242                f32::from(*pixels).to_bits().hash(state);
243            }
244        }
245    }
246}
247
248/// The result of hit testing on text.
249#[derive(Debug, Clone, Copy, PartialEq)]
250pub enum Hit {
251    /// The point was within the bounds of the returned character index.
252    CharOffset(usize),
253}
254
255impl Hit {
256    /// Computes the cursor position of the [`Hit`] .
257    pub fn cursor(self) -> usize {
258        match self {
259            Self::CharOffset(i) => i,
260        }
261    }
262}
263
264/// The difference detected in some text.
265///
266/// You will obtain a [`Difference`] when you [`compare`] a [`Paragraph`] with some
267/// [`Text`].
268///
269/// [`compare`]: Paragraph::compare
270#[derive(Debug, Clone, Copy, PartialEq, Eq)]
271pub enum Difference {
272    /// No difference.
273    ///
274    /// The text can be reused as it is!
275    None,
276
277    /// A bounds difference.
278    ///
279    /// This normally means a relayout is necessary, but the shape of the text can
280    /// be reused.
281    Bounds,
282
283    /// A shape difference.
284    ///
285    /// The contents, alignment, sizes, fonts, or any other essential attributes
286    /// of the shape of the text have changed. A complete reshape and relayout of
287    /// the text is necessary.
288    Shape,
289}
290
291/// A renderer capable of measuring and drawing [`Text`].
292pub trait Renderer: crate::Renderer {
293    /// The font type used.
294    type Font: Copy + PartialEq;
295
296    /// The [`Paragraph`] of this [`Renderer`].
297    type Paragraph: Paragraph<Font = Self::Font> + 'static;
298
299    /// The [`Editor`] of this [`Renderer`].
300    type Editor: Editor<Font = Self::Font> + 'static;
301
302    /// The icon font of the backend.
303    const ICON_FONT: Self::Font;
304
305    /// The `char` representing a ✔ icon in the [`ICON_FONT`].
306    ///
307    /// [`ICON_FONT`]: Self::ICON_FONT
308    const CHECKMARK_ICON: char;
309
310    /// The `char` representing a ▼ icon in the built-in [`ICON_FONT`].
311    ///
312    /// [`ICON_FONT`]: Self::ICON_FONT
313    const ARROW_DOWN_ICON: char;
314
315    /// Returns the default [`Self::Font`].
316    fn default_font(&self) -> Self::Font;
317
318    /// Returns the default size of [`Text`].
319    fn default_size(&self) -> Pixels;
320
321    /// Draws the given [`Paragraph`] at the given position and with the given
322    /// [`Color`].
323    fn fill_paragraph(
324        &mut self,
325        text: &Self::Paragraph,
326        position: Point,
327        color: Color,
328        clip_bounds: Rectangle,
329    );
330
331    /// Draws the given [`Editor`] at the given position and with the given
332    /// [`Color`].
333    fn fill_editor(
334        &mut self,
335        editor: &Self::Editor,
336        position: Point,
337        color: Color,
338        clip_bounds: Rectangle,
339    );
340
341    /// Draws the given [`Text`] at the given position and with the given
342    /// [`Color`].
343    fn fill_text(
344        &mut self,
345        text: Text<String, Self::Font>,
346        position: Point,
347        color: Color,
348        clip_bounds: Rectangle,
349    );
350}
351
352/// A span of text.
353#[derive(Debug, Clone)]
354pub struct Span<'a, Link = (), Font = crate::Font> {
355    /// The [`Fragment`] of text.
356    pub text: Fragment<'a>,
357    /// The size of the [`Span`] in [`Pixels`].
358    pub size: Option<Pixels>,
359    /// The [`LineHeight`] of the [`Span`].
360    pub line_height: Option<LineHeight>,
361    /// The font of the [`Span`].
362    pub font: Option<Font>,
363    /// The [`Color`] of the [`Span`].
364    pub color: Option<Color>,
365    /// The link of the [`Span`].
366    pub link: Option<Link>,
367    /// The [`Highlight`] of the [`Span`].
368    pub highlight: Option<Highlight>,
369    /// The [`Padding`] of the [`Span`].
370    ///
371    /// Currently, it only affects the bounds of the [`Highlight`].
372    pub padding: Padding,
373    /// Whether the [`Span`] should be underlined or not.
374    pub underline: bool,
375    /// Whether the [`Span`] should be struck through or not.
376    pub strikethrough: bool,
377}
378
379/// A text highlight.
380#[derive(Debug, Clone, Copy, PartialEq)]
381pub struct Highlight {
382    /// The [`Background`] of the highlight.
383    pub background: Background,
384    /// The [`Border`] of the highlight.
385    pub border: Border,
386}
387
388impl<'a, Link, Font> Span<'a, Link, Font> {
389    /// Creates a new [`Span`] of text with the given text fragment.
390    pub fn new(fragment: impl IntoFragment<'a>) -> Self {
391        Self {
392            text: fragment.into_fragment(),
393            ..Self::default()
394        }
395    }
396
397    /// Sets the size of the [`Span`].
398    pub fn size(mut self, size: impl Into<Pixels>) -> Self {
399        self.size = Some(size.into());
400        self
401    }
402
403    /// Sets the [`LineHeight`] of the [`Span`].
404    pub fn line_height(mut self, line_height: impl Into<LineHeight>) -> Self {
405        self.line_height = Some(line_height.into());
406        self
407    }
408
409    /// Sets the font of the [`Span`].
410    pub fn font(mut self, font: impl Into<Font>) -> Self {
411        self.font = Some(font.into());
412        self
413    }
414
415    /// Sets the font of the [`Span`], if any.
416    pub fn font_maybe(mut self, font: Option<impl Into<Font>>) -> Self {
417        self.font = font.map(Into::into);
418        self
419    }
420
421    /// Sets the [`Color`] of the [`Span`].
422    pub fn color(mut self, color: impl Into<Color>) -> Self {
423        self.color = Some(color.into());
424        self
425    }
426
427    /// Sets the [`Color`] of the [`Span`], if any.
428    pub fn color_maybe(mut self, color: Option<impl Into<Color>>) -> Self {
429        self.color = color.map(Into::into);
430        self
431    }
432
433    /// Sets the link of the [`Span`].
434    pub fn link(mut self, link: impl Into<Link>) -> Self {
435        self.link = Some(link.into());
436        self
437    }
438
439    /// Sets the link of the [`Span`], if any.
440    pub fn link_maybe(mut self, link: Option<impl Into<Link>>) -> Self {
441        self.link = link.map(Into::into);
442        self
443    }
444
445    /// Sets the [`Background`] of the [`Span`].
446    pub fn background(self, background: impl Into<Background>) -> Self {
447        self.background_maybe(Some(background))
448    }
449
450    /// Sets the [`Background`] of the [`Span`], if any.
451    pub fn background_maybe(
452        mut self,
453        background: Option<impl Into<Background>>,
454    ) -> Self {
455        let Some(background) = background else {
456            return self;
457        };
458
459        match &mut self.highlight {
460            Some(highlight) => {
461                highlight.background = background.into();
462            }
463            None => {
464                self.highlight = Some(Highlight {
465                    background: background.into(),
466                    border: Border::default(),
467                });
468            }
469        }
470
471        self
472    }
473
474    /// Sets the [`Border`] of the [`Span`].
475    pub fn border(self, border: impl Into<Border>) -> Self {
476        self.border_maybe(Some(border))
477    }
478
479    /// Sets the [`Border`] of the [`Span`], if any.
480    pub fn border_maybe(mut self, border: Option<impl Into<Border>>) -> Self {
481        let Some(border) = border else {
482            return self;
483        };
484
485        match &mut self.highlight {
486            Some(highlight) => {
487                highlight.border = border.into();
488            }
489            None => {
490                self.highlight = Some(Highlight {
491                    border: border.into(),
492                    background: Background::Color(Color::TRANSPARENT),
493                });
494            }
495        }
496
497        self
498    }
499
500    /// Sets the [`Padding`] of the [`Span`].
501    ///
502    /// It only affects the [`background`] and [`border`] of the
503    /// [`Span`], currently.
504    ///
505    /// [`background`]: Self::background
506    /// [`border`]: Self::border
507    pub fn padding(mut self, padding: impl Into<Padding>) -> Self {
508        self.padding = padding.into();
509        self
510    }
511
512    /// Sets whether the [`Span`] should be underlined or not.
513    pub fn underline(mut self, underline: bool) -> Self {
514        self.underline = underline;
515        self
516    }
517
518    /// Sets whether the [`Span`] should be struck through or not.
519    pub fn strikethrough(mut self, strikethrough: bool) -> Self {
520        self.strikethrough = strikethrough;
521        self
522    }
523
524    /// Turns the [`Span`] into a static one.
525    pub fn to_static(self) -> Span<'static, Link, Font> {
526        Span {
527            text: Cow::Owned(self.text.into_owned()),
528            size: self.size,
529            line_height: self.line_height,
530            font: self.font,
531            color: self.color,
532            link: self.link,
533            highlight: self.highlight,
534            padding: self.padding,
535            underline: self.underline,
536            strikethrough: self.strikethrough,
537        }
538    }
539}
540
541impl<Link, Font> Default for Span<'_, Link, Font> {
542    fn default() -> Self {
543        Self {
544            text: Cow::default(),
545            size: None,
546            line_height: None,
547            font: None,
548            color: None,
549            link: None,
550            highlight: None,
551            padding: Padding::default(),
552            underline: false,
553            strikethrough: false,
554        }
555    }
556}
557
558impl<'a, Link, Font> From<&'a str> for Span<'a, Link, Font> {
559    fn from(value: &'a str) -> Self {
560        Span::new(value)
561    }
562}
563
564impl<Link, Font: PartialEq> PartialEq for Span<'_, Link, Font> {
565    fn eq(&self, other: &Self) -> bool {
566        self.text == other.text
567            && self.size == other.size
568            && self.line_height == other.line_height
569            && self.font == other.font
570            && self.color == other.color
571    }
572}
573
574/// A fragment of [`Text`].
575///
576/// This is just an alias to a string that may be either
577/// borrowed or owned.
578pub type Fragment<'a> = Cow<'a, str>;
579
580/// A trait for converting a value to some text [`Fragment`].
581pub trait IntoFragment<'a> {
582    /// Converts the value to some text [`Fragment`].
583    fn into_fragment(self) -> Fragment<'a>;
584}
585
586impl<'a> IntoFragment<'a> for Fragment<'a> {
587    fn into_fragment(self) -> Fragment<'a> {
588        self
589    }
590}
591
592impl<'a> IntoFragment<'a> for &'a Fragment<'_> {
593    fn into_fragment(self) -> Fragment<'a> {
594        Fragment::Borrowed(self)
595    }
596}
597
598impl<'a> IntoFragment<'a> for &'a str {
599    fn into_fragment(self) -> Fragment<'a> {
600        Fragment::Borrowed(self)
601    }
602}
603
604impl<'a> IntoFragment<'a> for &'a String {
605    fn into_fragment(self) -> Fragment<'a> {
606        Fragment::Borrowed(self.as_str())
607    }
608}
609
610impl<'a> IntoFragment<'a> for String {
611    fn into_fragment(self) -> Fragment<'a> {
612        Fragment::Owned(self)
613    }
614}
615
616macro_rules! into_fragment {
617    ($type:ty) => {
618        impl<'a> IntoFragment<'a> for $type {
619            fn into_fragment(self) -> Fragment<'a> {
620                Fragment::Owned(self.to_string())
621            }
622        }
623
624        impl<'a> IntoFragment<'a> for &$type {
625            fn into_fragment(self) -> Fragment<'a> {
626                Fragment::Owned(self.to_string())
627            }
628        }
629    };
630}
631
632into_fragment!(char);
633into_fragment!(bool);
634
635into_fragment!(u8);
636into_fragment!(u16);
637into_fragment!(u32);
638into_fragment!(u64);
639into_fragment!(u128);
640into_fragment!(usize);
641
642into_fragment!(i8);
643into_fragment!(i16);
644into_fragment!(i32);
645into_fragment!(i64);
646into_fragment!(i128);
647into_fragment!(isize);
648
649into_fragment!(f32);
650into_fragment!(f64);
iced_core/text.rs

iced_core/
text.rs
