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

16. Drop-down List

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

Contents

API nameMeaningInput parametersReturn value
set_textSet the text displayed by the dropdown liststr (text to display)None
set_optionsSet the dropdown list options (dynamic string)str (options separated by newline character \n)None
set_options_staticSet the dropdown list options (static string)str (options separated by newline character \n)None
add_optionAdd a single option at the specified positionstr (option text), int (insertion position index)None
clear_optionsClear all options of the dropdown listNo parametersNone
set_selectedSet the default selected option of the dropdown listint (index of the selected item, starting from 0)None
set_dirSet the expansion direction of the dropdown listint (direction enum value, e.g., 0 = down, 1 = up)None
set_symbolSet the arrow symbol on the right side of the dropdown liststr (symbol identifier, e.g., "LV_SYMBOL_DOWN")None
set_selected_highlightSet whether the selected item is highlightedbool (True = highlighted, False = not highlighted)None
get_listGet the underlying list container object of the dropdown listNo parametersobj (list container object)
get_textGet the text currently displayed by the dropdown listNo parametersstr (display text)
get_optionsGet all options of the dropdown list (newline-separated)No parametersstr (text of all options)
get_selectedGet the index of the currently selected item (core method)No parametersint (index of the selected item)
get_option_countGet the total number of options in the dropdown listNo parametersint (number of options)
get_selected_strWrite the selected item's text to the specified bufferstr (buffer), int (buffer size)None
get_option_indexGet the corresponding index from the option textstr (option text to look up)int (corresponding index, returns -1 if no match)
get_symbolGet the text of the dropdown list's current arrow symbolNo parametersstr (symbol text)
get_selected_highlightGet whether the selected item is highlightedNo parametersbool (highlight state)
get_dirGet the current expansion direction of the dropdown listNo parametersint (direction enum value)
openManually expand the dropdown listNo parametersNone
closeManually collapse the dropdown listNo parametersNone
is_openCheck whether the dropdown list is expandedNo parametersbool (expanded state)
bind_valueBind an observer for value changes (advanced feature)NoneType (pass None for simplified testing)None

16.1 Simple Dropdown List

The following code implements an extremely minimalist drop-down list interaction function:

  1. First, initialize the LVGL environment and set the screen background to solid black, then create a drop-down list control and center it on the screen, and configure 4 selectable options for this drop-down list, namely "case 1" to "case 4"(separated by line breaks);
  2. Then an interactive callback function is defined. When the selected item of the drop-down list changes, this function will obtain the index value of the currently selected item and print it out (in the format of "choose ID: index value");
  3. Finally, bind this callback function to the "value change" event of the drop-down list, and refresh the screen to activate the entire drop-down list interface, so as to finally implement the core interaction logic of "select a drop-down list option → print the index of the selected item".
import display_driver
import lvgl as lv

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

# Create the dropdown widget
dropdown = lv.dropdown(scr)
#Center it
dropdown.center()
#A string separated by newline characters represents multiple options
dropdown.set_options("case 1\ncase 2\ncase 3\ncase 4")

#Interaction callback function
def dropdown_event_cd(e):
    #Get the index of the currently selected option
    selected_option = dropdown.get_selected()
    #Get the index of the currently selected option
    print(f"choose ID: {selected_option}")

#Register the interaction callback function. For more states see the "class EVENT" section of api.py
dropdown.add_event_cb(dropdown_event_cd, lv.EVENT.VALUE_CHANGED, None)

lv.screen_load(scr)
4 0 1 2 3 16.4

16.2 Get the Text of the Selected Item

In the following example, the basic interaction of the drop-down list is implemented, which not only obtains the index of the selected item, but also parses the corresponding text content:

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 dropdown widget and center it
dropdown = lv.dropdown(scr)
dropdown.center()
# Set the dropdown options (business scenario: select a device model)
options = "Model A\nModel B\nModel C\nModel D"
dropdown.set_options(options)

# Interaction callback: get the index and text of the selected item
def dropdown_event_cb(e):
    # Get the index of the currently selected item
    selected_idx = dropdown.get_selected()
    # Get all options and split them by newline
    all_options = dropdown.get_options().split("\n")
    # Safely get the selected text (avoid index out of range)
    selected_text = all_options[selected_idx] if 0 <= selected_idx < len(all_options) else "Unknown"
    # Print the selected result (English output)
    print(f"Selected index: {selected_idx} | Selected text: {selected_text}")

# Bind the value-changed event: trigger the callback when the selected item changes
dropdown.add_event_cb(dropdown_event_cb, lv.EVENT.VALUE_CHANGED, None)

# Load the screen to make the interface take effect
lv.screen_load(scr)
1 2 3 16.2

16.3 Dynamically Add and Remove Options

The following code demonstrates dynamically adding/clearing dropdown list options at runtime, which adapts to the scenario of "updating selectable configurations based on device status"(e. g., updating communication methods based on device connection status):

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 dropdown widget, set a fixed size and position
dropdown = lv.dropdown(scr)
dropdown.set_pos(20, 20)
dropdown.set_size(200, 50)
# Initialize with empty options
dropdown.set_options("")

# Function: dynamically add options (simulate loading communication method configuration)
def add_options():
    # Add options at the specified index positions (WiFi/Bluetooth/Ethernet)
    dropdown.add_option("WiFi", 0)
    dropdown.add_option("Bluetooth", 1)
    dropdown.add_option("Ethernet", 2)
    # Print the current total number of options
    print(f"Current option count: {dropdown.get_option_count()}")

# Function: clear all options (simulate resetting the configuration)
def clear_all_options():
    dropdown.clear_options()
    # Print the total number of options after clearing
    print(f"Option count after clear: {dropdown.get_option_count()}")

# Call the function at initialization to add options
add_options()

# Interaction callback: clear all options when the last item (Ethernet) is selected
def dropdown_event_cb(e):
    if dropdown.get_selected() == 2:
        clear_all_options()

# Bind the value-changed event
dropdown.add_event_cb(dropdown_event_cb, lv.EVENT.VALUE_CHANGED, None)

# Load the screen
lv.screen_load(scr)
16. Drop-down List
4 0 16.3

16.4 Expand/Collapse Dropdown List via Button Control

In the following example, the expand/collapse state of the drop-down list is manually controlled via a button control:

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)

# 1. Create the dropdown widget, set its position and size
dropdown = lv.dropdown(scr)
dropdown.set_pos(lv.pct(10), lv.pct(20))
dropdown.set_size(200, 50)
# Set the dropdown options
dropdown.set_options("Option 1\nOption 2\nOption 3")

# 2. Create a control button: used to expand/collapse the dropdown
btn_open = lv.button(scr)
btn_open.set_pos(lv.pct(10), lv.pct(5))
btn_open.set_size(100, 40)
# Add a text label to the button
btn_label = lv.label(btn_open)
btn_label.set_text("Open List")
btn_label.center()

# Button callback: toggle the dropdown's expanded/collapsed state
def btn_event_cb(e):
    if dropdown.is_open():
        # Collapse the dropdown
        dropdown.close()
        btn_label.set_text("Open List")
    else:
        # Expand the dropdown
        dropdown.open()
        btn_label.set_text("Close List")

# Bind the button click event
btn_open.add_event_cb(btn_event_cb, lv.EVENT.CLICKED, None)

# Dropdown callback: print the index of the selected item
def dropdown_event_cb(e):
    print(f"Selected option index: {dropdown.get_selected()}")

# Bind the dropdown value-changed event
dropdown.add_event_cb(dropdown_event_cb, lv.EVENT.VALUE_CHANGED, None)

# Load the screen
lv.screen_load(scr)
1 2 3 16.4
1

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.