Module embedded_graphics::fonts

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 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)?;

Built-in fonts

Type	Screenshot
Font6x6
Font6x8
Font6x12
Font8x16
Font12x16
Font24x32	The 24x32 font is a pixel doubled version of the 12x16 font.

Structs

Font12x16	12x16 pixel monospace font.
Font24x32	24x32 pixel monospace font.
Font6x6	6x6 pixel variable width font.
Font6x8	6x8 pixel monospace font.
Font6x12	6x12 pixel monospace font.
Font8x16	8x16 pixel monospace font.
StyledTextIterator	Pixel iterator for styled text.
Text	A text object.

Traits

Font	Monospaced bitmap font.