Contents
| API name | Meaning | Input parameters | Return value |
|---|---|---|---|
| add_text | Add 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_button | Add 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_text | Get the current display text of the specified button item in the list | btn: obj (the button item object returned by add_button must be passed) | str (the button's display text string) |
| set_button_text | Dynamically change the display text of the specified button item in the list | btn: 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:
- First, initialize the LVGL environment and set the screen background to solid black, then create a list control with a size of 300×200 pixels that is displayed centered;
- Then add content to the list according to the grouping logic: first add the text item "button A" as the group title, then add the three button items "A1", "A2" and "A3" in sequence, then add the text item "button B" as the second group title, and continue to add the three button items "B1", "B2" and "B3";
- The final loading screen applies all configurations, and finally presents a list control containing two groups of buttons, A and B, in the center of a pure black background screen, with corresponding text titles in front of each group of buttons for grouping and distinction.
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:
- 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;
- 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_textto read and print the original display text of the button, then useset_button_textto 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; - 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.
- 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. |