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

21. Tables

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

Contents
API nameCore functionInput parametersReturn valueNotes (SDL environment behavior)
set_cell_valueSet the text content of the specified cellrow: row number (int),
col: column number (int),
txt: cell text (str)
No return value (NoneType)Numeric arguments accept only int; str triggers a type error
set_row_countSet the total number of rows of the tablecount: total number of rows (int)No return value (NoneType)Passing too few / too many arguments triggers an argument count error
set_column_countSet the total number of columns of the tablecount: total number of columns (int)No return value (NoneType)A float argument triggers a type error
set_column_widthSet the width of the specified columncol_id: column index (int), w: column width (int)No return value (NoneType)Width must be a positive integer
add_cell_ctrlSet control attributes for the specified cell (replaces set_cell_ctrl)row: row number (int),
col: column number (int),
ctrl: control attribute (int, e.g. CELL_CTRL.TEXT_CROP)
No return value (NoneType)ctrl must be a CELL_CTRL enum value (int type)
clear_cell_ctrlClear the control attributes of the specified cellrow: row number (int),
col: column number (int),
ctrl: control attribute (int)
No return value (NoneType)Passing extra arguments triggers an argument count error
set_cell_user_dataBind a custom user data object to the specified cellrow: row number (int),
col: column number (int),
obj: user data object (lv.obj)
No return value (NoneType)SDL allows passing str, but it has no effect
get_cell_valueGet the text content of the specified cellrow: row number (int),
col: column number (int)
cell_text: cell text (str)Returns an empty string if not set
get_row_countGet the total number of rows of the tableNonerow_count: total number of rows (int)Returns the default value (e.g. 0) if not set
get_column_countGet the total number of columns of the tableNonecol_count: total number of columns (int)Returns the default value (e.g. 0) if not set
get_column_widthGet the width of the specified columncol: column index (int)col_width: column width (int)Returns the default width if not set
has_cell_ctrlCheck whether the specified cell has the target control attributerow: row number (int),
col: column number (int),
ctrl: control attribute (int)
is_has: whether the cell has the attribute (bool)Returning False means the attribute is not set
get_selected_cellGet the currently selected cell position (the result is stored in the passed-in lists)row_list: list that receives the selected row number (list), col_list: list that receives the selected column number (list)No return value (NoneType); the result is stored in the passed-in listsSDL allows passing str, but it cannot receive the result
get_cell_user_dataGet the user data object bound to the specified cellrow: row number (int),
col: column number (int)
user_data: user data object (Blob/lv.obj)Displayed as Blob type in the SDL environment

21.1 Basic Table

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 table instance
table = lv.table(scr)
table.set_size(300, 200)  # Set table size
table.align(lv.ALIGN.CENTER, 0, 0)  # Center on screen
# Set number of table rows and columns
table.set_row_count(4)
table.set_column_count(3)
# Set column width
table.set_column_width(0, 80)
table.set_column_width(1, 100)

# Fill table data
table.set_cell_value(0, 0, "ID")
table.set_cell_value(0, 1, "NAME")
table.set_cell_value(0, 2, "STATE")

table.set_cell_value(1, 0, "001")
table.set_cell_value(1, 1, "Device A")
table.set_cell_value(1, 2, "ON")

table.set_cell_value(2, 0, "002")
table.set_cell_value(2, 1, "Device B")
table.set_cell_value(2, 2, "OFF")

table.set_cell_value(3, 0, "003")
table.set_cell_value(3, 1, "Device C")
table.set_cell_value(3, 2, "ON")

# Load the screen
lv.screen_load(scr)
ID001 ID002 ID003

21.2 Get the total number of rows in a table and the width of a specified column

# get_row_count: query total number of table rows
current_row_count = table.get_row_count()
print(f"get_row_count() → Current total rows: {current_row_count}, return value type: {type(current_row_count).__name__}")

# get_column_width: query width of specified column
query_col_width = 1
current_col_width = table.get_column_width(query_col_width)
print(f"get_column_width({query_col_width}) → Width of column {query_col_width}: {current_col_width}, return value type: {type(current_col_width).__name__}")
001 002 003 1 21.2

21.3 Adding Cell Control Properties

Cell control attributes (CELL_CTRL) are the display and behavior rules provided by LVGL for table cells, defined via enumeration values (such as text clipping, cell merging, custom markers, etc.), which are used to control the rendering logic and interaction behavior of cells.

In the following code, the following operations are performed:

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 table instance and initialize basic configuration
table = lv.table(scr)
table.set_size(400, 250)  # Enlarge table size to make merge/crop effects easier to show
table.align(lv.ALIGN.CENTER, 0, 0)
table.set_row_count(4)
table.set_column_count(3)
table.set_column_width(0, 80)
table.set_column_width(1, 100)
table.set_column_width(2, 80)

# Purpose: disable vertical scrolling of the table and let height adapt automatically, avoiding an initial scrollbar
table.set_scroll_dir(lv.DIR.NONE) 

# Fill test data (includes long text to demonstrate the TEXT_CROP effect)
table.set_cell_value(0, 0, "ID")
table.set_cell_value(0, 1, "NAME")
table.set_cell_value(0, 2, "STATE")
table.set_cell_value(1, 0, "001")
table.set_cell_value(1, 1, "Device A - Long Text For Crop Test")  # Very long text
table.set_cell_value(1, 2, "ON")
table.set_cell_value(2, 0, "002")
table.set_cell_value(2, 1, "Device B")
table.set_cell_value(2, 2, "OFF")

# Control attribute 1: TEXT_CROP - crop text when too long (the part beyond the column width is hidden)
# Purpose: prevent very long text from stretching the cell, showing only content within the column width
crop_row, crop_col = 1, 1
crop_ctrl = lv.table.CELL_CTRL.TEXT_CROP
# Add TEXT_CROP attribute
table.add_cell_ctrl(crop_row, crop_col, crop_ctrl)
print(f"add_cell_ctrl({crop_row},{crop_col},TEXT_CROP) → Add text crop attribute, return value: None")
# Check whether it was added successfully
is_has_crop = table.has_cell_ctrl(crop_row, crop_col, crop_ctrl)
print(f"has_cell_ctrl({crop_row},{crop_col},TEXT_CROP) → Attribute exists: {is_has_crop}, return type: {type(is_has_crop).__name__}")

# Control attribute 2: MERGE_RIGHT - merge cell to the right (the current cell merges with the column to its right)
# Purpose: merge adjacent cells to achieve a column-spanning display
merge_row, merge_col = 3, 0
merge_ctrl = lv.table.CELL_CTRL.MERGE_RIGHT
# First fill in the text of the merged cell
table.set_cell_value(merge_row, merge_col, "Merged Cell (003+Device C)")
# Add MERGE_RIGHT attribute (merge columns 0 and 1 of row 3)
table.add_cell_ctrl(merge_row, merge_col, merge_ctrl)
print(f"add_cell_ctrl({merge_row},{merge_col},MERGE_RIGHT) → Add cell merge right attribute, return value: None")
# Check whether it was added successfully
is_has_merge = table.has_cell_ctrl(merge_row, merge_col, merge_ctrl)
print(f"has_cell_ctrl({merge_row},{merge_col},MERGE_RIGHT) → Attribute exists: {is_has_merge}, return type: {type(is_has_merge).__name__}")

# Purpose: force LVGL to recalculate the table layout, avoiding an initial scrollbar/line-wrap anomalies
table.update_layout()

# Load screen (shows the effect of TEXT_CROP cropping long text and MERGE_RIGHT merging cells)
lv.screen_load(scr)
100px 3 0 1
001 002 003 003+Device 1 3 0

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.