embedded_graphics/text/renderer/
mod.rs

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}
embedded_graphics/text/renderer/mod.rs

embedded_graphics/text/renderer/
mod.rs
