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:
- CircuitPython Display Text - for displaying text
- CircuitPython Bitmap Font Library - for bitmap font support
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:
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 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 to prevent code from exiting while True: pass
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.
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 text 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 to prevent code from exiting while True: pass
To run the example above, you'll need this font file:
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:
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 you 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.