What about text? How do you print "Hello World" to the display? Where is text support in displayio?!?!

It's not actually in the core library. Instead, it is provided by a set of external libraries, each which takes care of a certain aspect.

Display Text

The CircuitPython Display Text Library is used to create text elements you can then display. We cover the basics here, but checkout this guide for more info:

Bitmap Fonts

The CircuitPython Bitmap Font Library provides support for using custom fonts. We show a simple example here, but checkout this guide for more info:

Basic Text with Built in Font

The workhorse item is the Label, which is essentially a Group containing all the characters of the text. So once it's created, you use it like you would a Group.

Creating a Label is pretty straight forward - you give it the text, font, and color to use. You specify the text location using x and y.

In general, you always need to specify a font to use for the text. The next section shows how to load custom font files. However, a simple built in font is provided so that you can display text without needing a font file. It is available from terminalio.FONT.

Here's a basic Hello World example:

Example assumes board with a built in display.
# SPDX-FileCopyrightText: 2019 Carter Nelson for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import board
import terminalio
from adafruit_display_text import label

display = board.DISPLAY

# Set text, font, and color
text = "HELLO WORLD"
font = terminalio.FONT
color = 0x0000FF

# Create the text label
text_area = label.Label(font, text=text, color=color)

# Set the location
text_area.x = 100
text_area.y = 80

# Show it
display.show(text_area)

# Loop forever so you can enjoy your image
while True:
    pass

Using Bitmap Fonts

You can also load fonts from external files in Bitmap Distribution Format (.bdf) or the binary Portable Compiled Format (.pcf) . Check out the Custom Fonts for CircuitPython Displays guide for more information about how to create your own font files.

Here we show a basic BDF example. First, copy the font file to your CIRCUITPY folder somewhere. You then load it using load_font() as shown below. The rest is the same as the example above.

# SPDX-FileCopyrightText: 2019 Carter Nelson for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import board
from adafruit_bitmap_font import bitmap_font
from adafruit_display_text import label

display = board.DISPLAY

# Set text, font, and color
text = "HELLO WORLD"
font = bitmap_font.load_font("/Helvetica-Bold-16.bdf")
color = 0xFF00FF

# Create the tet label
text_area = label.Label(font, text=text, color=color)

# Set the location
text_area.x = 20
text_area.y = 20

# Show it
display.show(text_area)

# Loop forever so you can enjoy your text
while True:
    pass

To run the example above, you'll need this font file:

Note: the font file should be on the board's CIRCUITPY flash drive. In the example above, the main (root) directory / is used, but in some tutorials, a new subdirectory /font is created for font files. Just be sure your load_font has the correct directory to the font file in your project.

Text Positioning

When setting text location using the x and y properties, you are setting the origin point. It is located relative to the text as shown below.

Alternatively, thanks to more recent updates to the CircuitPython Display Text library, you can now change the anchor point used to locate the text label. You do so by using the anchor_point property of the label and giving it an (x, y) tuple, like this:

label.anchor_point = (0.1, 0.8)

The values range from 0 to 1 with x being the horizontal and y being the vertical. The origin is in the upper left corner. A value of 0 is at the origin. A value of 1 is all the way to the right/down.

Here are some example locations:

You can then set the position of the label on the display using the anchored_position property and also specifying an (x, y) tuple. But this time, the values are actual screen coordinates in pixels, like this:

label.anchored_position = (120, 85)

See the example program linked below for lots of common example use cases:

Changing Text

If you ever want to change the text of a label, you can do this:

text_area.text = "NEW TEXT"

However, the new text length can not be longer than what was originally specified when the label was created. So you have to know the expected max number of characters ahead of time. One easy way to do this when creating the label is with something like:

text_area = label.Label(font, text=" "*20)

where 20 is the character count, i.e. the maximum number of characters the label can display.

This guide was first published on Apr 30, 2019. It was last updated on Feb 27, 2021.

This page (Text) was last updated on Sep 29, 2023.

Text editor powered by tinymce.