Module fonts

Expand description

Monospaced bitmap fonts.

This module contains support for drawing monospaced bitmap fonts and provides several built-in fonts.

Additional custom fonts can be added by the application or other crates. This is demonstrated in the text-custom-font example in the simulator crate.

§Examples

The examples below use the Font6x8 font, however any of the built-in fonts in this module or custom fonts can be substituted.

§Draw text without using `egtext` macro

Text can be drawn to a display by creating a Text object and attaching a text style to it by using a Styled object. By creating the text style manually, without using the egtext macro, it can be reused to style multiple text objects.

use embedded_graphics::{
    fonts::{Font6x8, Text},
    pixelcolor::Rgb565,
    prelude::*,
    style::{TextStyle, TextStyleBuilder},
};

// Create a new text style
let style = TextStyleBuilder::new(Font6x8)
    .text_color(Rgb565::YELLOW)
    .background_color(Rgb565::BLUE)
    .build();

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

§Draw text using the `egtext` macro

Creating styled text can be simplified by using the egtext and text_style macros. All style properties in TextStyle can be set by using assignments inside the text_style macro call.

The following example draws the same text as the previous example but uses the egtext macro to build the necessary styled text objects, and the text_style macro to style it.

use embedded_graphics::{egtext, fonts::Font6x8, pixelcolor::Rgb565, prelude::*, text_style};

egtext!(
    text = "Hello Rust!",
    top_left = (20, 30),
    style = text_style!(
        font = Font6x8,
        text_color = Rgb565::YELLOW,
        background_color = Rgb565::BLUE,
    )
)
.draw(&mut display)?;

It is also possible to provide a style created without using the text_style macro. In this example, [TextStyleBuilder] is used.

use embedded_graphics::{
    egtext,
    fonts::Font6x8,
    pixelcolor::Rgb565,
    prelude::*,
    style::{TextStyle, TextStyleBuilder},
};

egtext!(
    text = "Hello Rust!",
    top_left = (20, 30),
    style = TextStyleBuilder::new(Font6x8)
        .text_color(Rgb565::YELLOW)
        .background_color(Rgb565::BLUE)
        .build()
)
.draw(&mut display)?;

§Translate text by (20px, 30px)

use embedded_graphics::{
    fonts::{Font6x8, Text},
    pixelcolor::BinaryColor,
    prelude::*,
    style::TextStyle,
};

Text::new("Hello Rust!", Point::zero())
    .into_styled(TextStyle::new(Font6x8, BinaryColor::On))
    .translate(Point::new(20, 30))
    .draw(&mut display)?;

// this is equivalent to:

Text::new("Hello Rust!", Point::new(20, 30))
    .into_styled(TextStyle::new(Font6x8, BinaryColor::On))
    .draw(&mut display)?;

§Use `write!()` and arrayvec to render a formatted string

This example uses arrayvec’s ArrayString to render a floating point value using the write!() macro. These strings have a fixed maximum length, but allow the use of Rust’s builtin string formatting.

use arrayvec::ArrayString;
use core::fmt::Write;
use embedded_graphics::{egtext, fonts::Font6x8, pixelcolor::Rgb565, prelude::*, text_style};

let value = 12.34567;

// Create a fixed buffer of length 12
let mut buf = ArrayString::<[_; 12]>::new();

// Output `Value: 12.35`
write!(&mut buf, "Value: {:.2}", value).expect("Failed to write to buffer");

egtext!(
    text = &buf,
    top_left = Point::zero(),
    style = text_style!(
        font = Font6x8,
        text_color = Rgb565::YELLOW,
        background_color = Rgb565::BLUE,
    )
)
.draw(&mut display)?;