Labs / LVGL / 03 Quick Start Example - Control Section (Based on Web Simulator and LVGL v9.0)

18. Lists

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

Contents
API nameMeaningInput parametersReturn value
add_textAdd a plain text item to the list (commonly used for group titles, description text, etc.)txt: str (text content; a string must be passed)obj (the created text item object)
add_buttonAdd a button item to the list (pass None as the first argument for no icon; pass an icon object to display that icon)icon: Any (NoneType passed in tests, no-icon case); txt: str (button display text, string type)obj (the created button item object)
get_button_textGet the current display text of the specified button item in the listbtn: obj (the button item object returned by add_button must be passed)str (the button's display text string)
set_button_textDynamically change the display text of the specified button item in the listbtn: obj (the target button item object);
txt: str (new button display text, string type)
None (no return value)

18.1 Creating Simple Grouped Headings and Button Lists

The following code performs the following operations:

import display_driver
import lvgl as lv

# Initialize the LVGL environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#Create the list object
list_obj = lv.list(scr)
list_obj.set_size(300, 200)
list_obj.center()
#Add a text item
list_obj.add_text("button A")
#Add a button item
btnA1 = list_obj.add_button(None, "A1")
btnA2 = list_obj.add_button(None, "A2")
btnA3 = list_obj.add_button(None, "A3")
#Add a text item
list_obj.add_text("button B")
#Add a button item
btnB1 = list_obj.add_button(None, "B1")
btnB2 = list_obj.add_button(None, "B2")
btnB3 = list_obj.add_button(None, "B3")

# Load the screen
lv.screen_load(scr)

18.2 Reading and Dynamically Modifying Button List Text

In the following code, we have completed the following tasks:

  1. First, initialize the LVGL environment, set the screen background to solid black, and create a list object that is 300×200 pixels in size and displayed centered on the screen;
  2. Next, write dedicated click callback functions respectively for the six buttons A1/A2/A3 and B1/B2/B3. In each callback, first use get_button_text to read and print the original display text of the button, then use set_button_text to dynamically modify the button text to a new text with the suffix "(Clicked)", and finally read the modified text again and print it to verify the effect;
  3. Then add the group titles "button A" and "button B" to the list, create six buttons corresponding to the respective groups, and bind a dedicated callback to each button.
  4. The final loading screen applies the configuration changes.

After running the program, click any button, and the Console will output the English text information of the button before and after modification, while the button text on the interface will also be updated synchronously.

import display_driver
import lvgl as lv

# Initialize the LVGL environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

# Create the list object (global, for use by callbacks)
list_obj = lv.list(scr)
list_obj.set_size(300, 200)
list_obj.center()

# ===================== Dedicated callback for each button (demonstrates get/set_button_text) =====================
# Dedicated callback for button A1: full demonstration of get/set_button_text usage
def on_btnA1_click(e):
    # 1. Demonstrate get_button_text: read the text currently displayed on the button
    original_text = list_obj.get_button_text(btnA1)
    print(f"[A1] Original text: {original_text}")
    
    # 2. Demonstrate set_button_text: dynamically change the button text
    list_obj.set_button_text(btnA1, "A1 (Clicked)")
    
    # 3. Verify the change: read the button text again
    updated_text = list_obj.get_button_text(btnA1)
    print(f"[A1] Updated text: {updated_text}\n")

# Dedicated callback for button A2
def on_btnA2_click(e):
    original_text = list_obj.get_button_text(btnA2)
    print(f"[A2] Original text: {original_text}")
    list_obj.set_button_text(btnA2, "A2 (Clicked)")
    updated_text = list_obj.get_button_text(btnA2)
    print(f"[A2] Updated text: {updated_text}\n")

# Dedicated callback for button A3
def on_btnA3_click(e):
    original_text = list_obj.get_button_text(btnA3)
    print(f"[A3] Original text: {original_text}")
    list_obj.set_button_text(btnA3, "A3 (Clicked)")
    updated_text = list_obj.get_button_text(btnA3)
    print(f"[A3] Updated text: {updated_text}\n")

# Dedicated callback for button B1
def on_btnB1_click(e):
    original_text = list_obj.get_button_text(btnB1)
    print(f"[B1] Original text: {original_text}")
    list_obj.set_button_text(btnB1, "B1 (Clicked)")
    updated_text = list_obj.get_button_text(btnB1)
    print(f"[B1] Updated text: {updated_text}\n")

# Dedicated callback for button B2
def on_btnB2_click(e):
    original_text = list_obj.get_button_text(btnB2)
    print(f"[B2] Original text: {original_text}")
    list_obj.set_button_text(btnB2, "B2 (Clicked)")
    updated_text = list_obj.get_button_text(btnB2)
    print(f"[B2] Updated text: {updated_text}\n")

# Dedicated callback for button B3
def on_btnB3_click(e):
    original_text = list_obj.get_button_text(btnB3)
    print(f"[B3] Original text: {original_text}")
    list_obj.set_button_text(btnB3, "B3 (Clicked)")
    updated_text = list_obj.get_button_text(btnB3)
    print(f"[B3] Updated text: {updated_text}\n")

# ===================== Create the list content and bind the dedicated callbacks =====================
# Add a text item (group title)
list_obj.add_text("button A")
# Create the group A buttons and bind the callbacks
btnA1 = list_obj.add_button(None, "A1")
btnA1.add_event_cb(on_btnA1_click, lv.EVENT.CLICKED, None)

btnA2 = list_obj.add_button(None, "A2")
btnA2.add_event_cb(on_btnA2_click, lv.EVENT.CLICKED, None)

btnA3 = list_obj.add_button(None, "A3")
btnA3.add_event_cb(on_btnA3_click, lv.EVENT.CLICKED, None)

# Add a text item (group title)
list_obj.add_text("button B")
# Create the group B buttons and bind the callbacks
btnB1 = list_obj.add_button(None, "B1")
btnB1.add_event_cb(on_btnB1_click, lv.EVENT.CLICKED, None)

btnB2 = list_obj.add_button(None, "B2")
btnB2.add_event_cb(on_btnB2_click, lv.EVENT.CLICKED, None)

btnB3 = list_obj.add_button(None, "B3")
btnB3.add_event_cb(on_btnB3_click, lv.EVENT.CLICKED, None)

# Load the screen
lv.screen_load(scr)

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.