1//! Text renderer.
2//!
3//! For more complex text rendering cases that are not covered by the [`mono_font`] module, the
4//! `TextRenderer` trait can be implemented by external text renderers.
5//!
6//! Implementations of this trait can be found in the [bdf] and [eg-seven-segment] repositories,
7//! which may be useful as a reference of other implementations.
8//!
9//! [`mono_font`]: super::super::mono_font
10//! [bdf]: https://github.com/embedded-graphics/bdf
11//! [eg-seven-segment]: https://github.com/embedded-graphics/eg-seven-segment
12
13use crate::{
14 draw_target::DrawTarget, geometry::Point, pixelcolor::PixelColor, primitives::Rectangle,
15 text::Baseline,
16};
17
18mod character_style;
19
20pub use character_style::CharacterStyle;
21
22/// Text renderer.
23///
24/// The `TextRenderer` trait is used to integrate text renderers into embedded-graphics. Users should
25/// not call it directly and instead use the functions provided by the `Text` type.
26pub trait TextRenderer {
27 /// Color type.
28 type Color: PixelColor;
29
30 /// Draws a string.
31 ///
32 /// The method returns the start position of the next character to allow chaining of multiple
33 /// draw calls.
34 ///
35 /// # Implementation notes
36 ///
37 /// This method must not interpret any control characters and only render a single line of text.
38 /// Any control character in the `text` should be handled the same way as any other character
39 /// that isn't included in the font.
40 fn draw_string<D>(
41 &self,
42 text: &str,
43 position: Point,
44 baseline: Baseline,
45 target: &mut D,
46 ) -> Result<Point, D::Error>
47 where
48 D: DrawTarget<Color = Self::Color>;
49
50 /// Draws whitespace of the given width.
51 ///
52 /// The method returns the start position of the next character to allow chaining of multiple
53 /// draw calls.
54 fn draw_whitespace<D>(
55 &self,
56 width: u32,
57 position: Point,
58 baseline: Baseline,
59 target: &mut D,
60 ) -> Result<Point, D::Error>
61 where
62 D: DrawTarget<Color = Self::Color>;
63
64 /// Returns the text metrics for a string.
65 ///
66 /// # Implementation notes
67 ///
68 /// The returned bounding box must be independent of the text color. This is different to the
69 /// `Dimensions` trait, which should return a zero sized bounding box for completely transparent
70 /// drawables. But this behavior would make it impossible to correctly layout text which
71 /// contains a mixture of transparent and non transparent words.
72 ///
73 /// This method must not interpret any control characters and only render a single line of text.
74 /// Any control character in the `text` should be handled the same way as any other character
75 /// that isn't included in the font.
76 fn measure_string(&self, text: &str, position: Point, baseline: Baseline) -> TextMetrics;
77
78 /// Returns the default line height.
79 ///
80 /// The line height is defined as the vertical distance between the baseline of two adjacent
81 /// lines in pixels.
82 fn line_height(&self) -> u32;
83}
84
85/// Text metrics.
86///
87/// See [`TextRenderer::measure_string`] for more information.
88///
89#[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
90#[cfg_attr(feature = "defmt", derive(::defmt::Format))]
91pub struct TextMetrics {
92 /// Bounding box.
93 pub bounding_box: Rectangle,
94
95 /// The position of the next text.
96 pub next_position: Point,
97}
98