Make sure you have the latest CircuitPython firmware loaded for your board to use displayio. You can download it from the link below.

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:

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:

Download: file
import board
import displayio
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 tet label
text_area = label.Label(font, text="HELLO WORLD", color=0x00FF00)

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

# Show it
display.show(text_area)

Using Bitmap Fonts

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

Once you have the BDF font file, copy it to your CIRCUITPY folder somewhere. You then load it using load_font() as shown below. The rest is the same as the example above.

Download: file
import board
import displayio
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)

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 Origin

When setting text location, you are setting the origin point. It is located relative to the text as shown below.

This guide was first published on Apr 30, 2019. It was last updated on Apr 30, 2019. This page (Text) was last updated on Aug 24, 2019.