Except for EPD (eink) displays, displayio by default automatically takes care of refreshing the display. This means you never need to call refresh() and things happen automagically. However, there are times when you may want to turn this feature off and instead manually refresh the display. One example might be if you are updating a lot graphical items and want to have the changes appear "all at once" on the display. Or maybe you want to be very exact about syncing the update with some other event.

Manually refreshing is pretty simple. The basic idea is to turn off the auto refresh behavior and then call refresh() as needed.

Turning Auto Refresh Off

There is an auto_refresh parameter you can use when creating your Display object. If you set this to False, the display will be created with auto refresh turned off. For example:

display = ST7789(display_bus, width=240, height=240, rowstart=80, auto_refresh=False)

The other way is to use the auto_refresh property after you've created the display. This not only returns the current state, but is also used to set the state. To check current state (if you wanted to), you could do something like:

if display.auto_refresh:
    print("Auto refresh is ON.")
else:
    print("Auto refresh is OFF.")

To turn auto refresh off, you simply set it False:

display.auto_refresh = False

Example Usage

Once you disable auto refresh, it is up to you to call refresh() as needed to show any updates. Exactly when and where you would do this is specific to your use case. But here's a simple boiler plate example:

# turn off auto refresh
display.auto_refresh = False

#
# your code here that changes the display
#

# when ready to show results, call refresh()
display.refresh()

Turning Auto Refresh On

If you ever want to revert back to the default behavior, simply re-enable auto refresh.

display.auto_refresh = True

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

This page (Manual Refresh) was last updated on Dec 16, 2020.

Text editor powered by tinymce.