Sometimes when you make labels, you will want to change the text that they are displaying at some point after they've been initialized. A common example of this would be showing the value being read from a sensor, then updating it as you make new readings from the sensor.

Basic Example

This example initializes a label before the main loop begins. Then inside the main loop it updates the text property on the label with the value it gets from time.monotonic(). This example can be run on any CircuitPython device with a built-in display. 

Updating the text property will change what appears in the label on the display.

In the example below, click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, open the directory CircuitPython_Display_Text/updating_text_example/ and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:

CIRCUITPY
# SPDX-FileCopyrightText: 2021 Tim C, written for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
This examples shows how to update your label with new text.
"""
import time
import board
import displayio
import terminalio
from adafruit_display_text import label

# built-in display
display = board.DISPLAY

# Make the display context
main_group = displayio.Group()
display.root_group = main_group

# create the label
updating_label = label.Label(
    font=terminalio.FONT, text="Time Is:\n{}".format(time.monotonic()), scale=2
)

# set label position on the display
updating_label.anchor_point = (0, 0)
updating_label.anchored_position = (20, 20)

# add label to group that is showing on display
main_group.append(updating_label)

# Main loop
while True:

    # update text property to change the text showing on the display
    updating_label.text = "Time Is:\n{}".format(time.monotonic())

    time.sleep(1)

What NOT To Do

Be careful not to create new labels infinitely in the main loop. It can lead to a Memory Error caused by making too many new labels.

Do NOT use code like below. The code presented here is an example of the type of code you should avoid. It is not indented for you to run this code.
# SPDX-FileCopyrightText: 2020 Tim C, written for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
This examples shows the wrong way change your displayed text in the main loop.
"""
import time
import board
import displayio
import terminalio
from adafruit_display_text import label

# built-in display
display = board.DISPLAY

# Make the display context
main_group = displayio.Group()
display.root_group = main_group


# Main loop
while True:
    
    # You should not create labels in an unrestriced manner like this.
    #
    # DONT DO THIS!!!
    #
    new_label = label.Label(
        font=terminalio.FONT, 
        text="Time Is:\n{}".format(time.monotonic()),
        scale=2,
        x=20, y=50
    )
    main_group.append(new_label)
    main_group.pop(0)
    
    time.sleep(1)

This guide was first published on Mar 09, 2021. It was last updated on Mar 20, 2024.

This page (Label Updating) was last updated on Mar 20, 2024.

Text editor powered by tinymce.