Module embedded_graphics::text

source ·
Expand description

Text drawing.

The Text drawable can be used to draw text on a draw target. To construct a Text object at least a text string, position and character style are required. For advanced formatting options an additional TextStyle object might be required.

Text rendering in embedded-graphics is designed to be extendable by text renderers for different font formats. To use a text renderer in an embedded-graphics project each renderer provides a character style object. This object is used to set the appearance of characters, like the text color or the used font. The available settings vary between different text renderer and are documented in the text renderer documentation.

See the renderer module docs for more information about implementing custom text renderers.

Embedded-graphics includes a text renderer for monospaced fonts in the mono_font module. Most examples will use this renderer and the associated MonoTextStyle character style. But they should be easily adaptable to any external renderer listed in the external crates list.

§Text style

In addition to styling the individual characters the Text drawable also contains a TextStyle setting. The text style is used to set the alignment and line spacing of text objects.

The alignment setting sets the horizontal alignment of the text. With the default value Left the text will be rendered to the right of the given text position. Analogously Right aligned text will be rendered to the left of the given position. Centered text will extend equally to the left and right of the text position.

The baseline setting defines the vertical alignment of the first line of text. With the default setting of Alphabetic the glyphs will be drawn with their descenders below the given position. This means that the bottom of glyphs without descender (like ‘A’) will be on the same Y coordinate as the given position. The other baseline settings will position the glyphs relative to the EM box, without considering the baseline.

If the text contains multiple lines only the first line will be vertically aligned based on the baseline setting. All following lines will be spaced relative to the first line, according to the line_height setting.

§Examples

§Draw basic text

use embedded_graphics::{
    mono_font::{ascii::FONT_6X10, MonoTextStyle},
    pixelcolor::Rgb565,
    prelude::*,
    text::Text,
};

// Create a new character style
let style = MonoTextStyle::new(&FONT_6X10, Rgb565::WHITE);

// Create a text at position (20, 30) and draw it using the previously defined style
Text::new("Hello Rust!", Point::new(20, 30), style).draw(&mut display)?;

§Draw centered text

Text provides the with_alignment and with_baseline constructors to easily set these commonly used settings without having to build a TextStyle object first.

use embedded_graphics::{
    mono_font::{ascii::FONT_6X10, MonoTextStyle},
    pixelcolor::Rgb565,
    prelude::*,
    text::{Text, Alignment},
};

// Create a new character style
let style = MonoTextStyle::new(&FONT_6X10, Rgb565::WHITE);

// Create a text at position (20, 30) and draw it using the previously defined style
Text::with_alignment(
    "First line\nSecond line",
    Point::new(20, 30),
    style,
    Alignment::Center,
)
.draw(&mut display)?;

§Draw text with TextStyle

For more advanced text styles a TextStyle object can be build using the TextStyleBuilder and then passed to the with_text_style constructor.

use embedded_graphics::{
    mono_font::{ascii::FONT_6X10, MonoTextStyle},
    pixelcolor::Rgb565,
    prelude::*,
    text::{Alignment, LineHeight, Text, TextStyleBuilder},
};

// Create a new character style.
let character_style = MonoTextStyle::new(&FONT_6X10, Rgb565::WHITE);

// Create a new text style.
let text_style = TextStyleBuilder::new()
    .alignment(Alignment::Center)
    .line_height(LineHeight::Percent(150))
    .build();

// Create a text at position (20, 30) and draw it using the previously defined style.
Text::with_text_style(
    "First line\nSecond line",
    Point::new(20, 30),
    character_style,
    text_style,
)
.draw(&mut display)?;

§Combine different character styles

The draw method for text drawables returns the position of the next character. This can be used to combine text with different character styles on a single line of text.

use embedded_graphics::{
    mono_font::{ascii::{FONT_6X10, FONT_10X20}, MonoTextStyle},
    pixelcolor::Rgb565,
    prelude::*,
    text::{Alignment, LineHeight, Text, TextStyleBuilder},
};

// Create a small and a large character style.
let small_style = MonoTextStyle::new(&FONT_6X10, Rgb565::WHITE);
let large_style = MonoTextStyle::new(&FONT_10X20, Rgb565::WHITE);

// Draw the first text at (20, 30) using the small character style.
let next = Text::new("small ", Point::new(20, 30), small_style).draw(&mut display)?;

// Draw the second text after the first text using the large character style.
let next = Text::new("large", next, large_style).draw(&mut display)?;

Modules§

Structs§

Enums§