Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for a specific release, use the drop-down menu on the left.

LVGL Python API

LVGL Python API#

LVGL (Light and Versatile Graphics Library) Python bindings for the K230 platform

Automatically generated from LVGL C headers and built through a libclang → IR → pybind11 pipeline. 902 binding methods/functions (.def()), 651 enum values, 65 module constants, 96 enum classes, 26 widgets, and 8 classes.

Quick Start#

LVGL Benchmark Demo

Example	Description	Source
Dashboard Demo	Avatar/chart/animated arc/list	lvgl_python_benchmark.py
Hello	Minimal LVGL example (button)	quick_hello.py
Camera + OSD	Camera feed with LVGL overlay	quick_camera_osd.py
Camera + Rotation	Portrait orientation support	quick_camera_rotation.py
Chinese Font	Load a TTF font with FreeType	quick_chinese.py
Basic Widgets	Button/slider/progress bar/arc/switch/LED	quick_widgets.py

Initialization and Drivers#

`lv.init(v4l2_drm=None, v4l2_drm_run_flag=0)`#

One-click initialization for the K230 platform, completing the following internally:

lv_init() — initialize the LVGL library
Register the driver backend
Initialize the display backend (DRM or DRM_V4L2_K230)
Initialize the EVDEV input backend

Parameter	Type	Description
`v4l2_drm`	`V4l2Drm` or `None`	Pass a V4l2Drm object to use the K230 v4l2-drm backend (OSD and camera video share DRM); `None` uses the standard Linux DRM backend
`v4l2_drm_run_flag`	`int`	Reserved parameter, currently unused, defaults to 0

`lv.settings`#

A module-level object that directly maps to the simulator global variable settings on the C side (defined in driver_backends.c); reads and writes directly affect the same global state.

Attribute	Type	Description
`rotation`	`lv.DISPLAY_ROTATION`	Display rotation angle; valid values are `lv.DISPLAY_ROTATION._0` / `_90` / `_180` / `_270`, corresponding to the `-R` option of the C simulator

Behavior differs between the two backend paths:

Standard Linux DRM backend (lv.init() with no arguments): rotation is consumed during initialization (DRM backend init_drm → sets the DRM plane rotation property while swapping the resolution), and must be set before lv.init(); changes made after initialization do not take effect.
K230 v4l2-drm backend (lv.init(v4l2drm)): rotation is controlled by v4l2drm.set_rotation(). After k230_driver_init completes initialization, the v4l2-drm rotation value is overwritten into settings.rotation (for evdev touch coordinate transformation). On this path, read lv.settings.rotation after initialization to obtain the effective angle instead of writing to it.

# 标准 DRM 后端：初始化前设置旋转
lv.settings.rotation = lv.DISPLAY_ROTATION._90
lv.init()                    # DRM plane 以 90° 初始化

# v4l2-drm 后端：初始化后读取生效旋转
v4l2drm.set_rotation(0, ROTATION_90)
lv.init(v4l2drm, v4l2_drm_run_flag=1)
print(lv.settings.rotation)  #DISPLAY_ROTATION._90 (由 v4l2-drm 发布)

Accompanying examples: lvgl_linux_drm_demo.py, lvgl_ai_change.py, and all examples under the basic/ and quick/ directories (all containing an lv.settings.rotation setting line).

`lv.run()`#

Enters the LVGL driver run loop (blocking). Supports interruption with Ctrl+C, calling os._exit(0) to exit after interruption.

Module-level Functions#

Core#

Function	Description
`lv.init()`	Initialize the LVGL library
`lv.deinit()`	Deinitialize the LVGL library
`lv.is_initialized()`	Whether LVGL has been initialized
`lv.timer_handler()`	Call the LVGL timer handler (main loop core), returning idle time (ms)
`lv.screen_active()`	Get the currently active screen object
`lv.screen_load(screen)`	Load the specified screen
`lv.demo_benchmark()`	Run the LVGL performance benchmark
`lv.pct(n)`	Return a percentage width/height value (for `set_width`, etc.)

Version Information#

Function	Description
`lv.version_major()`	LVGL major version number
`lv.version_minor()`	LVGL minor version number
`lv.version_patch()`	LVGL patch version number
`lv.version_info()`	LVGL version information string

Display#

Function	Description
`lv.display_create(w, h)`	Create a display object
`lv.display_get_default()`	Get the default display object
`lv.evdev_create(type, dev)`	Create an EVDEV input device

Timers#

Function	Description
`lv.timer_create(cb, period_ms)`	Create a timer and return a timer_t object

Animation#

Constant	Description
`lv.ANIM_REPEAT_INFINITE`	Infinite animation repeat value

Groups#

Function	Description
`lv.group_create()`	Create an input group
`lv.group_delete(group)`	Delete a group
`lv.group_set_default(group)`	Set the default group
`lv.group_get_default()`	Get the default group
`lv.group_add_obj(group, obj)`	Add an object to a group
`lv.group_remove_obj(obj)`	Remove an object from a group
`lv.group_focus_obj(obj)`	Focus a specified object
`lv.group_focus_next(group)`	Focus the next object
`lv.group_focus_prev(group)`	Focus the previous object
`lv.group_set_wrap(group, en)`	Set whether focus wraps around

Theme#

Function	Description
`lv.theme_default_init(disp, ...)`	Initialize the default theme
`lv.theme_get_color_primary()`	Get the theme primary color

Palette#

Function	Description
`lv.palette_main(palette)`	Get the palette main color
`lv.palette_lighten(pal, lvl)`	Get the palette light color
`lv.palette_darken(pal, lvl)`	Get the palette dark color

Input Devices#

Function	Description
`lv.indev_create()`	Create an input device
`lv.indev_get_next(indev)`	Get the next input device
`lv.indev_get_type(indev)`	Get the input device type
`lv.indev_set_group(indev, group)`	Set the input device group
`lv.indev_set_type(indev, type)`	Set the input device type

Driver Backends#

Function	Description
`lv.k230_driver_init(display_ptr, flag)`	Initialize the K230 driver (called internally by `lv.init()`)
`lv.driver_backends_register()`	Register driver backends
`lv.driver_backends_init_backend()`	Initialize driver backends
`lv.driver_backends_is_supported()`	Query whether a backend is supported
`lv.driver_backends_print_supported()`	Print supported backends
`lv.driver_backends_run_loop()`	Run the driver loop

FreeType Fonts#

Function	Description
`lv.freetype_font_create(path, render, size, style)`	Create a FreeType font
`lv.freetype_font_delete(font)`	Delete a FreeType font

Color (color)#

Create a color#

c1 = lv.color_make(255, 0, 0)          # RGB (0-255)
c2 = lv.color.from_rgb(255, 0, 0)      # RGB (0-255), color static method
c3 = lv.color_hex(0xFF0000)            # Hexadecimal integer
c4 = lv.color.from_hex(0xFF0000)       # Hexadecimal integer, color static method
c5 = lv.color(r, g, b)                 # _wrapper alias, equivalent to color_make
c6 = lv.color_from_hex_str("#FF0000")  # Hexadecimal string, _wrapper alias
c7 = lv.color_black()                  # Pure black
c8 = lv.color_white()                  # Pure white

color properties#

c = lv.color_make(255, 128, 0)
print(c.red, c.green, c.blue)       # Read RGB components (read-only, 0-255)

Opacity constants#

Constant	Value	Description
`lv.OPA_TRANSP`	0	Fully transparent
`lv.OPA_0`	0	0% opaque
`lv.OPA_10`	25	10% opaque
`lv.OPA_20`	51	20%
`lv.OPA_30`	76	30%
`lv.OPA_40`	102	40%
`lv.OPA_50`	127	50%
`lv.OPA_60`	153	60%
`lv.OPA_70`	178	70%
`lv.OPA_80`	204	80%
`lv.OPA_90`	229	90%
`lv.OPA_100`	255	100% opaque
`lv.OPA_COVER`	255	Fully opaque

Classes#

Class	Python Name	Description
`obj`	`lv.obj`	Base class of all widgets
`event`	`lv.event`	Event object
`color`	`lv.color`	Color object
`display`	`lv.display`	Display object
`indev`	`lv.indev`	Input device object
`timer_t`	`lv.timer_t`	Timer object
`anim_t`	`lv.anim_t`	Animation object
`font`	`lv.font`	Font object (FreeType)

Basic Object obj#

obj is the base class of all widgets. All widgets inherit the methods of obj.

Creation (obj)#

obj = lv.obj()                      # No-argument constructor
child = parent.obj()                # Create a child object (create a new obj under parent)

Note: The no-argument lv.obj() constructor creates a basic object, while parent.obj() creates a child object under the parent object.

Position and Size#

Method	Description
`set_pos(x, y)`	Set position
`set_x(x)`	Set X coordinate
`set_y(y)`	Set Y coordinate
`set_size(w, h)`	Set width and height
`set_width(w)`	Set width
`set_height(h)`	Set height
`set_content_width(w)`	Set content width
`set_content_height(h)`	Set content height
`get_x()` / `get_y()`	Get coordinates
`get_width()` / `get_height()`	Get width and height
`get_content_width()` / `get_content_height()`	Get content width and height

Alignment#

Method	Description
`set_align(align)`	Set alignment
`align(align, x_ofs, y_ofs)`	Align relative to the parent object
`align_to(base, align, x_ofs, y_ofs)`	Align relative to another object
`center()`	Center

Alignment values use the lv.ALIGN enumeration:

lv.ALIGN.CENTER           # Center
lv.ALIGN.TOP_LEFT         # Top left
lv.ALIGN.TOP_MID          # Top center
lv.ALIGN.TOP_RIGHT        # Top right
lv.ALIGN.BOTTOM_LEFT      # Bottom left
lv.ALIGN.BOTTOM_MID       # Bottom center
lv.ALIGN.BOTTOM_RIGHT     # Bottom right
lv.ALIGN.LEFT_MID         # Left center
lv.ALIGN.RIGHT_MID        # Right center
lv.ALIGN.OUT_TOP_LEFT     # Align to the upper left outside the parent object
lv.ALIGN.OUT_BOTTOM_MID   # Align to the bottom center outside the parent object
# ... More OUT_ variants

Hierarchy and Parent-Child Relationships#

Method	Description
`set_parent(parent)`	Set parent object
`get_parent()`	Get parent object
`get_child(idx)`	Get child object
`get_child_count()`	Get number of child objects
`get_index()`	Get index among siblings
`move_to_index(idx)`	Move to a specific index position
`move_foreground()`	Move to the front
`move_background()`	Move to the back
`swap(obj2)`	Swap the positions of two objects

Deletion#

Method	Description
`delete_obj()`	Delete object
`delete_async()`	Delete object asynchronously
`clean()`	Delete all child objects

Event Binding (Shorthand)#

btn.add_event_cb(lv.EVENT.CLICKED, callback)        # Add an event callback
btn.on(lv.EVENT.CLICKED, callback)                  # Shorthand, equivalent to add_event_cb
btn.off(lv.EVENT.CLICKED, callback)                 # Remove an event callback (LED only)
btn.remove_event(idx)                               # Remove an event by index
btn.remove_event_cb_with_user_data(cb, data)        # Remove an event by callback

Fade In and Fade Out#

obj.fade_in(time_ms, delay_ms)   # Fade in
obj.fade_out(time_ms, delay_ms)  # Fade out

Transformation#

obj.set_transform(matrix)     # Set the transformation matrix
obj.reset_transform()         # Reset the transformation
obj.transform_point(point)    # Transform a coordinate point

Coordinates and Visibility#

Method	Description
`get_coords()`	Get absolute coordinate area
`get_content_coords()`	Get content area coordinates
`invalidate()`	Mark an area as invalid (redraw)
`invalidate_area(area)`	Mark a specified area as invalid
`is_visible()`	Whether the object is visible
`area_is_visible(area)`	Whether the area is visible within the object
`move_to(x, y)`	Move to an absolute position
`move_children_by(dx, dy)`	Move all child objects

Widgets#

All widgets are created through module-level factory functions, passing the parent parameter (optional, defaults to the current screen):

btn = lv.button(parent)   # Create button

Unified naming: All widgets share the obj base class, but the methods of each widget use unified short names (such as set_text, set_value, close), with no widget prefix required. Methods with the same name automatically call the corresponding implementation on different widgets (for example, arc.set_value() and slider.set_value() each update the value of the corresponding widget). The “Common Methods” table in each widget section lists all the methods supported by that widget.

button#

Basic interactive widget used to trigger actions.

Creation

btn = lv.button(scr)
btn.set_size(120, 40)
btn.center()

Common Methods

Method	Description
`set_size(w, h)`	Set width and height
`set_pos(x, y)`	Set position
`center()`	Center
`align(align, x_ofs, y_ofs)`	Align relative to parent
`align_to(base, align, x_ofs, y_ofs)`	Align relative to another object
`add_event_cb(event, cb)`	Add event callback
`add_flag(flag)`	Add flag
`remove_flag(flag)`	Remove flag
`set_style_bg_color(color, selector)`	Set background color
`set_style_bg_opa(opa, selector)`	Set background opacity

Events

Event	Description
`lv.EVENT.CLICKED`	Clicked
`lv.EVENT.PRESSED`	Pressed
`lv.EVENT.RELEASED`	Released
`lv.EVENT.LONG_PRESSED`	Long pressed

Complete Example

demo_button.py

label#

Text display widget supporting multiline, scrolling, recoloring, and other modes.

Creation

label = lv.label(scr)
label.set_text("Hello World")

Common Methods

Method	Description
`set_text(text)`	Set text
`set_text_static(text)`	Set static text (not copied)
`set_long_mode(mode)`	Set long text mode
`set_recolor(True)`	Enable recoloring
`set_max_lines(n)`	Maximum number of lines
`get_text()`	Get text
`ins_text(pos, text)`	Insert text at position
`cut_text(pos, count)`	Cut text from position

Enumerations

Long text mode (lv.LABEL_LONG):

Enumeration Value	Description
`WRAP`	Automatic wrapping (default)
`DOTS`	Show ellipsis for excess text
`SCROLL`	Scroll display
`SCROLL_CIRCULAR`	Circular scrolling
`CLIP`	Clip

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Text changed

Complete Example

demo_label.py

image#

Image display widget supporting transformations such as scaling, rotation, and offset.

Creation

img = lv.image(scr)
img.set_src("A:/path/to/image.png")   # LVGL 文件系统需要 'A:' 前缀

File path: LVGL uses the FS_STDIO backend, with the drive letter A:. All file paths must begin with A: (for example, "A:/root/image.png"). PNG (recommended), BMP, and JPEG (baseline only) formats are supported.

Common Methods

Method	Description
`set_src(src)`	Set image source
`set_offset_x(x)`	X offset
`set_offset_y(y)`	Y offset
`set_rotation(angle)`	Rotate (0.1-degree units, 450=45.0°)
`set_pivot(x, y)`	Set rotation center
`set_scale(zoom)`	Scale (256=1x, 512=2x)
`set_scale_x(zoom)`	Scale in the X direction
`set_scale_y(zoom)`	Scale in the Y direction
`set_blend_mode(mode)`	Blend mode
`set_antialias(True)`	Antialiasing
`set_inner_align(align)`	Inner alignment
`get_scale()`	Get scale value
`get_rotation()`	Get rotation angle
`get_src_width()`	Get source image width
`get_src_height()`	Get source image height
`get_pivot()`	Get rotation center

Enumerations

Image alignment (lv.IMAGE_ALIGN): DEFAULT, TOP_LEFT, TOP_MID, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_MID, BOTTOM_RIGHT, LEFT_MID, RIGHT_MID, CENTER, STRETCH, TILE, CONTAIN, COVER

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Image changed

Complete Example

demo_image.py

arc#

Arc widget used to display an angular range or as a knob for adjusting a value.

Creation

arc = lv.arc(scr)
arc.set_range(0, 100)
arc.set_value(70)

Common Methods

Method	Description
`set_range(min, max)`	Set value range
`set_value(value)`	Set current value
`set_min_value(val)`	Set minimum value
`set_max_value(val)`	Set maximum value
`set_angles(start, end)`	Set foreground arc angles
`set_bg_angles(start, end)`	Set background arc angles
`set_rotation(angle)`	Rotation offset
`set_mode(mode)`	Mode
`set_change_rate(rate)`	Value change rate
`set_knob_offset(offset)`	Knob offset
`get_value()`	Get current value
`get_min_value()`	Get minimum value
`get_max_value()`	Get maximum value
`get_rotation()`	Get rotation offset
`get_angle_start()`	Get foreground start angle
`get_angle_end()`	Get foreground end angle
`get_mode()`	Get mode

Enumerations

Arc mode (lv.ARC_MODE): NORMAL, SYMMETRICAL, REVERSE

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Value changed

Complete Example

demo_arc.py

bar#

Progress bar widget used to display a ratio or progress.

Creation

bar = lv.bar(scr)
bar.set_range(0, 100)
bar.set_value(60, True)

Common Methods

Method	Description
`set_range(min, max)`	Set range
`set_value(value, anim)`	Set value (whether animated)
`set_start_value(value, anim)`	Set start value (range mode)
`set_min_value(val)`	Set minimum value
`set_max_value(val)`	Set maximum value
`set_mode(mode)`	Mode
`set_orientation(orient)`	Orientation
`get_value()`	Get current value
`get_start_value()`	Get start value
`get_min_value()`	Get minimum value
`get_max_value()`	Get maximum value
`get_mode()`	Get mode
`get_orientation()`	Get orientation
`is_symmetrical()`	Whether in symmetrical mode

Enumerations

Bar mode (lv.BAR_MODE): NORMAL, SYMMETRICAL, RANGE

Orientation (lv.BAR_ORIENTATION): AUTO, HORIZONTAL, VERTICAL

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Value changed

Complete Example

demo_bar.py

slider#

Slider widget used to drag and adjust a value.

Creation

slider = lv.slider(scr)
slider.set_range(0, 100)
slider.set_value(50, True)

Common Methods

Method	Description
`set_range(min, max)`	Set range
`set_value(value, anim)`	Set value (whether animated)
`set_start_value(value, anim)`	Set start value (range mode, whether animated)
`set_min_value(val)`	Set minimum value
`set_max_value(val)`	Set maximum value
`set_mode(mode)`	Mode
`set_orientation(orient)`	Orientation
`get_value()`	Get current value
`get_left_value()`	Get left value (range mode)
`get_min_value()`	Get minimum value
`get_max_value()`	Get maximum value
`get_mode()`	Get mode
`get_orientation()`	Get orientation
`is_symmetrical()`	Whether in symmetrical mode
`is_dragged()`	Whether currently being dragged

Enumerations

Slider mode (lv.SLIDER_MODE): NORMAL, SYMMETRICAL, RANGE

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Value changed

Complete Example

demo_slider.py

switch#

Switch widget used to toggle on/off states.

Creation

sw = lv.switch(scr)

Common Methods

Method	Description
`set_orientation(orient)`	Orientation
`get_orientation()`	Get orientation

Enumerations

Orientation (lv.SWITCH_ORIENTATION): AUTO, HORIZONTAL, VERTICAL

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Value changed

Complete Example

demo_switch.py

checkbox#

Checkbox widget used to select or deselect an option.

Creation

cb = lv.checkbox(scr)
cb.set_text("Option A")

Common Methods

Method	Description
`set_text(text)`	Set text
`set_text_static(text)`	Set static text
`get_text()`	Get text

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Value changed

Complete Example

demo_checkbox.py

dropdown#

Dropdown list widget used to select one item from a list of options.

Creation

dd = lv.dropdown(scr)
dd.set_options("Red\nGreen\nBlue")

Common Methods

Method	Description
`set_options(str)`	Set options (\n-separated)
`add_option(str, pos)`	Add option at position
`set_selected(idx)`	Set selected item
`set_text(text)`	Set current selected item text
`set_text_static(text)`	Set static text
`set_dir(dir)`	Set expansion direction
`set_symbol(symbol)`	Set indicator symbol
`clear_options()`	Clear all options
`get_selected()`	Get selected index
`get_text()`	Get current selected item text
`get_options()`	Get option string
`get_option_count()`	Get option count
`get_option_index(name)`	Find index by name
`open()`	Open dropdown list
`close()`	Close dropdown list
`is_open()`	Whether open

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Selected item changed

Complete Example

demo_dropdown.py

roller#

Roller widget for selecting options by scrolling.

Creation

roller = lv.roller(scr)
roller.set_options("A\nB\nC", lv.ROLLER_MODE.NORMAL)

Common Methods

Method	Description
`set_options(str, mode)`	Set options
`set_selected(idx, anim)`	Set selected item (whether animated)
`set_selected_str(str, anim)`	Select by string
`set_visible_row_count(n)`	Set visible row count
`get_selected()`	Get selected index
`get_options()`	Get options
`get_option_count()`	Get option count

Enumerations

Roller mode (lv.ROLLER_MODE): NORMAL, INFINITE

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Selected item changed

Complete Example

demo_roller.py

textarea#

Text input field widget supporting single-line/multiline, password mode, character filtering, and other features.

Creation

ta = lv.textarea(scr)
ta.set_text("Hello")

Common Methods

Method	Description
`set_text(text)`	Set text
`set_placeholder_text(text)`	Set placeholder text
`set_one_line(True)`	Single-line mode
`set_password_mode(True)`	Password mode
`set_max_length(len)`	Maximum length
`set_accepted_chars(chars)`	Restrict accepted chars
`set_cursor_pos(pos)`	Set cursor position
`set_text_selection(True)`	Enable text selection
`add_text(text)`	Append text
`add_char(code)`	Append character (ASCII)
`delete_char()`	Delete character before cursor
`delete_char_forward()`	Delete character after cursor
`clear_selection()`	Clear selection
`get_cursor_pos()`	Get cursor position
`get_one_line()`	Whether single-line
`get_password_mode()`	Whether password mode
`get_max_length()`	Get maximum length

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Text content changed
`lv.EVENT.READY`	Input completed

Complete Example

demo_textarea.py

keyboard#

Virtual keyboard widget used with Textarea to enter text.

Creation

kb = lv.keyboard(scr)
kb.set_textarea(textarea_obj)

Common Methods

Method	Description
`set_textarea(ta)`	Associate a text input field
`set_mode(mode)`	Set keyboard mode
`set_popovers(True)`	Enable key popovers
`get_textarea()`	Get associated text field
`get_mode()`	Get current mode
`get_button_text()`	Get key text

Enumerations

Keyboard mode (lv.KEYBOARD_MODE): TEXT_LOWER, TEXT_UPPER, SPECIAL, NUMBER, USER_1~USER_4

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Key value changed
`lv.EVENT.READY`	Input completed (confirm key)

Complete Example

demo_keyboard.py

chart#

Chart widget supporting data visualization such as line, curve, and bar charts.

Creation

chart = lv.chart(scr)
chart.set_type(lv.CHART_TYPE.LINE)

Common Methods

Method	Description
`set_type(type)`	Chart type
`set_axis_range(axis, min, max)`	Set axis range
`set_update_mode(mode)`	Update mode
`set_div_line_count(h, v)`	Horizontal/vertical division line count
`set_hor_div_line_count(n)`	Horizontal division line count
`set_ver_div_line_count(n)`	Vertical division line count
`set_axis_min_value(axis, val)`	Set axis minimum value
`set_axis_max_value(axis, val)`	Set axis maximum value
`set_point_count(n)`	Set number of data points
`add_series(color, axis)`	Add data series
`set_next_value(ser, val)`	Append a data point
`set_all_values(ser, val)`	Set all to the same value
`set_series_color(ser, color)`	Set series color
`refresh()`	Refresh display
`get_type()`	Get type
`get_point_count()`	Get number of points
`get_update_mode()`	Get update mode
`get_hor_div_line_count()`	Get horizontal division line count
`get_ver_div_line_count()`	Get vertical division line count
`get_pressed_point()`	Get pressed data point

Enumerations

Chart type (lv.CHART_TYPE): NONE, LINE, CURVE, BAR, STACKED, SCATTER

Update mode (lv.CHART_UPDATE_MODE): SHIFT, CIRCULAR

Axis (lv.CHART_AXIS): PRIMARY_Y, SECONDARY_Y, PRIMARY_X, SECONDARY_X, LAST

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Data point changed
`lv.EVENT.PRESSED`	Data point pressed

Complete Example

demo_chart.py

table#

Table widget used to display row and column data.

Creation

table = lv.table(scr)
table.set_row_count(5)
table.set_column_count(3)

Common Methods

Method	Description
`set_row_count(n)`	Set row count
`set_column_count(n)`	Set column count
`set_column_width(col, w)`	Set column width
`set_cell_value(row, col, text)`	Set cell text
`set_cell_ctrl(row, col, ctrl)`	Set cell control flags
`get_cell_value(row, col)`	Get cell text
`get_row_count()`	Get row count
`get_column_count()`	Get column count
`set_selected_cell(row, col)`	Set selected cell

Enumerations

Cell control (lv.TABLE_CELL_CTRL): NONE, MERGE_RIGHT, TEXT_CROP, CUSTOM_1~CUSTOM_4

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Selected cell changed

Complete Example

demo_table.py

tabview#

Tab view widget used to switch between multiple pages.

Creation

tv = lv.tabview(scr)
tab1 = tv.add_tab("Tab 1")
tab2 = tv.add_tab("Tab 2")

Common Methods

Method	Description
`add_tab(name)`	Add tab
`set_active(idx, anim)`	Switch tab (whether animated)
`set_tab_bar_size(size)`	Set tab bar size
`set_tab_bar_position(dir)`	Set tab bar position
`get_tab_count()`	Get number of tabs
`get_tab_active()`	Get current active tab
`get_content()`	Get content area
`get_tab_bar()`	Get tab bar

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Tab switched

Complete Example

demo_tabview.py

list#

List widget used to display a list of items with icons.

Creation

list = lv.list(scr)
list.add_text("Section Title")
btn = list.add_button(icon, "Item Text")

Common Methods

Method	Description
`add_text(text)`	Add text heading
`add_button(icon, text)`	Add button item
`get_button_text(btn)`	Get button text
`set_button_text(btn, text)`	Set button text

Events

Event	Description
`lv.EVENT.CLICKED`	Item clicked
`lv.EVENT.SELECTED`	Item selected

Complete Example

demo_list.py

menu#

Menu widget used for multi-level navigation interfaces.

Creation

menu = lv.menu(scr)

Common Methods

Method	Description
`set_mode_header(mode)`	Set header mode
`set_mode_root_back_button(mode)`	Set back button mode
`clear_history()`	Clear navigation history
`set_page(page)`	Set current displayed page
`set_sidebar_page(page)`	Set sidebar page
`set_load_page_event(trigger, target)`	Set click navigation
`get_cur_main_page()`	Get current main page
`get_cur_sidebar_page()`	Get current sidebar page

Enumerations

Header mode (lv.MENU_HEADER): TOP_FIXED, TOP_UNFIXED, BOTTOM_FIXED

Back button (lv.MENU_ROOT_BACK_BTN): MENU_ROOT_BACK_BUTTON_DISABLED, MENU_ROOT_BACK_BUTTON_ENABLED

Events

Event	Description
`lv.EVENT.CLICKED`	Menu item clicked

Complete Example

demo_menu.py

Notes

menu_page, menu_cont, and menu_section are module-level factory functions. Like menu, they are called with lv.menu_page(menu, title).

msgbox#

Message box widget used to display prompts. When constructed without arguments, it is modal (with a backdrop).

Creation

msgbox = lv.msgbox()               # Modal (recommended)
msgbox = lv.msgbox(parent)         # Non-modal (specify parent object)

Common Methods

Method	Description
`add_title(text)`	Add title
`add_text(text)`	Add text content
`add_footer_button(text)`	Add footer button
`add_close_button()`	Add close button (✕)
`get_header()`	Get header area
`get_footer()`	Get footer area
`get_content()`	Get content area
`close()`	Close message box
`close_async()`	Close message box asynchronously

Events

Event	Description
`lv.EVENT.CLICKED`	Button clicked
`lv.EVENT.CLOSED`	Message box closed
`lv.EVENT.VALUE_CHANGED`	Button value changed

Complete Example

demo_msgbox.py

Notes

When lv.msgbox() is called without a parent, it internally passes NULL to lv_msgbox_create. LVGL automatically creates a semi-transparent backdrop on lv_layer_top(), producing a modal effect. If a parent object is passed, no backdrop is created.

led#

LED indicator widget used to display status.

Creation

led = lv.led(scr)
led.set_size(30, 30)

Common Methods

Method	Description
`set_color(color)`	Set LED color
`set_brightness(val)`	Set brightness (0-255)
`on()`	Turn on (maximum brightness)
`off()`	Turn off (minimum brightness)
`toggle()`	Toggle
`get_brightness()`	Get brightness
`get_color()`	Get color

Complete Example

demo_led.py

line#

Polyline widget used to draw a polyline with multiple segments.

Creation

line = lv.line(scr)
line.center()
line.set_points([(0, 0), (40, 30), (80, 0), (120, 30), (160, 0), (200, 30)])

Common Methods

Method	Description
`set_points(points)`	Set coordinate points (list of tuples)
`set_y_invert(True)`	Invert the Y axis
`get_y_invert()`	Get Y inversion state
`get_point_count()`	Get number of coordinate points

Complete Example

demo_line.py

Notes

set_points() accepts a Python list of (x, y) tuples. The Line widget must be given coordinate points with set_points() before it can be displayed; otherwise, it will remain blank.

canvas#

Canvas widget used to draw graphics pixel by pixel.

Creation

import numpy as np

canvas = lv.canvas(scr)
buf = np.zeros((H, W, 4), dtype=np.uint8)
canvas.set_buffer(buf.ctypes.data, W, H, lv.COLOR_FORMAT.ARGB8888)

Common Methods

Method	Description
`set_buffer(buf, w, h, cf)`	Set drawing buffer
`set_px(x, y, color, opa)`	Set pixel
`get_px(x, y)`	Get pixel
`fill_bg(color, opa)`	Fill background
`set_palette(index, color)`	Set palette
`get_draw_buf()`	Get drawing buffer

Complete Example

demo_canvas.py

Notes

The buf parameter of set_buffer(buf, w, h, cf) is a memory address integer (uintptr_t). When using a numpy array, pass buf.ctypes.data; do not pass a ctypes pointer object.

scale#

Scale widget used to display tick marks.

Creation

scale = lv.scale(scr)
scale.set_range(0, 100)

Common Methods

Method	Description
`set_mode(mode)`	Mode
`set_total_tick_count(n)`	Total tick count
`set_major_tick_every(n)`	Major tick interval
`set_range(min, max)`	Set range
`set_min_value(val)`	Set minimum value
`set_max_value(val)`	Set maximum value
`set_angle_range(angle)`	Circular scale angle range
`set_rotation(angle)`	Rotation offset
`set_label_show(True)`	Show labels
`set_draw_ticks_on_top(True)`	Draw ticks at the top
`get_mode()`	Get mode
`get_total_tick_count()`	Get total tick count
`get_min_value()`	Get minimum value
`get_max_value()`	Get maximum value
`get_angle_range()`	Get angle range
`get_rotation()`	Get rotation offset

Enumerations

Scale mode (lv.SCALE_MODE): HORIZONTAL_TOP, HORIZONTAL_BOTTOM, VERTICAL_LEFT, VERTICAL_RIGHT, ROUND_INNER, ROUND_OUTER, LAST

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Value changed

Complete Example

demo_scale.py

spinbox#

Numeric input field widget used for precise value adjustment.

Creation

sb = lv.spinbox(scr)
sb.set_value(50)

Common Methods

Method	Description
`set_value(value)`	Set value
`set_digit_format(digits, sep_pos)`	Digits, decimal point position
`set_step(step)`	Step value
`set_range(min, max)`	Set range
`set_min_value(val)`	Set minimum value
`set_max_value(val)`	Set maximum value
`set_rollover(True)`	Wrap around
`set_cursor_pos(pos)`	Cursor position
`set_digit_step_direction(dir)`	Digit step direction
`get_value()`	Get value
`get_min_value()`	Get minimum value
`get_max_value()`	Get maximum value
`increment()`	Increment by one step
`decrement()`	Decrement by one step
`step_next()`	Move cursor to next digit
`step_prev()`	Move cursor to previous digit

Events

Event	Description
`lv.EVENT.VALUE_CHANGED`	Value changed

Complete Example

demo_spinbox.py

spinner#

Loading animation widget used to display a waiting state.

Creation

sp = lv.spinner(scr)
sp.set_size(50, 50)

Common Methods

Method	Description
`set_anim_params(period, angle)`	Period (ms), sweep angle
`set_anim_duration(ms)`	Set animation period
`set_arc_sweep(angle)`	Set arc sweep angle
`get_anim_duration()`	Get animation period
`get_arc_sweep()`	Get arc sweep angle

Complete Example

demo_spinner.py

tileview#

Tile view widget used to switch pages by swiping left/right or up/down.

Creation

tv = lv.tileview(scr)
tile1 = tv.add_tile(0, 0, lv.DIR.RIGHT)
tile2 = tv.add_tile(1, 0, lv.DIR.LEFT)

Common Methods

Method	Description
`add_tile(col, row, dir)`	Add tile (column, row, swipe direction)
`set_tile(tile, anim)`	Swipe to specified tile (whether animated)
`set_tile_by_index(col, row, anim)`	Swipe by index
`get_tile_active()`	Get current active tile

Complete Example

demo_tileview.py

win#

Window widget with a title bar and content area.

Creation

win = lv.win(scr)
title = win.add_title("Window")

Common Methods

Method	Description
`add_title(text)`	Add title
`add_button(icon, width)`	Add button
`get_header()`	Get header
`get_content()`	Get content area

Complete Example

demo_win.py

animimg#

Animated image widget used to play frame animations.

Creation

anim = lv.animimg(scr)
anim.set_src(["A:/path/to/frame1.png", "A:/path/to/frame2.png"])

Common Methods

Method	Description
`set_src(paths)`	Set image path list
`set_duration(ms)`	Duration of one complete loop (ms)
`set_repeat_count(n)`	Repeat count (255 = infinite loop)
`start()`	Start playback
`get_duration()`	Get loop duration
`get_repeat_count()`	Get repeat count

Complete Example

demo_animimg.py

Animation (anim_t)#

An animation object used to drive widget property changes over time.

Creation (anim_t)#

a = lv.anim_t()
a.set_var(obj)                                   # Set the animation target object
a.set_exec_cb(obj, lambda var, v: var.set_value(v))  # Set the execution callback fn(var, value)
a.set_values(0, 100)                             # Start value, end value
a.set_duration(1000)                             # Duration (ms)
a.set_repeat_count(lv.ANIM_REPEAT_INFINITE)      # Infinite loop
a.start()                                        # Start the animation

Common Methods (anim_t) |#

Motion Path#

Method	Description
`set_path_linear()`	Linear
`set_path_ease_in()`	Ease in
`set_path_ease_out()`	Ease out
`set_path_ease_in_out()`	Ease in and ease out
`set_path_overshoot()`	Overshoot
`set_path_bounce()`	Bounce
`set_path_step()`	Step

Constants#

Constant	Description
`lv.ANIM_REPEAT_INFINITE`	Infinite loop flag

Timers (timer_t)#

Timer objects are used to periodically execute callbacks.

Creation (timer_t)#

def on_timer(timer):
    # Code executed periodically
    pass

timer = lv.timer_create(on_timer, 100)  # Called once every 100ms

Common Methods (timer_t) |#

Display (display)#

Displays objects, used to manage screen resolution and rotation.

Create (display)#

disp = lv.display_create(800, 480)       # Create an 800x480 display
disp = lv.display_get_default()          # Get the default display object

Common Methods (display) |#

Enumeration (display)#

Display rotation (lv.DISPLAY_ROTATION)：_0, _90, _180, _270

Input Devices (indev)#

An input device object used to manage input devices such as touchscreens and keyboards.

Creating (indev)#

indev = lv.indev_create()
indev.set_type(lv.INDEV_TYPE.POINTER)

Common Methods (indev)#

Method	Description
`lv.indev_get_next(indev)`	Gets the next device
`lv.indev_get_type(indev)`	Gets the device type
`lv.indev_set_type(indev, type)`	Sets the device type
`lv.indev_set_group(indev, grp)`	Sets the input group

Enumerations (indev): `NONE`, `POINTER`, `KEYPAD`, `BUTTON`, `ENCODER`#

EVDEV Types (lv.EVDEV_TYPE): REL, ABS, KEY

Groups (group)#

Groups are used for keyboard/encoder navigation. They organize multiple controls together, allowing focus to be switched between controls using the arrow keys.

Usage#

# Create a group
g = lv.group_create()
lv.group_set_default(g)

# Bind an input device to the group
indev = lv.indev_create()
indev.set_type(lv.INDEV_TYPE.KEYPAD)
lv.indev_set_group(indev, g)

# Add controls to the group
lv.group_add_obj(g, btn1)
lv.group_add_obj(g, btn2)

Group Functions#

Function	Description
`lv.group_create()`	Create a group
`lv.group_delete(group)`	Delete a group
`lv.group_set_default(group)`	Set the default group
`lv.group_get_default()`	Get the default group
`lv.group_add_obj(group, obj)`	Add an object to a group
`lv.group_remove_obj(obj)`	Remove an object from a group
`lv.group_focus_obj(obj)`	Focus the specified object
`lv.group_focus_next(group)`	Focus the next object
`lv.group_focus_prev(group)`	Focus the previous object
`lv.group_set_wrap(group, en)`	Set whether focus wraps

Events and Callbacks#

Registering Event Callbacks#

def on_clicked(event):
    if event.code == lv.EVENT.CLICKED:
        print("Button clicked!")
        print("Target:", event.target)  # The object that triggered the event

btn.add_event_cb(lv.EVENT.CLICKED, on_clicked)
btn.on(lv.EVENT.CLICKED, on_clicked)    # Shorthand, equivalent to add_event_cb

`event` Object#

The callback function receives an event object, which provides the following properties and methods:

Property/Method	Description
`event.code`	Event code (int, can be compared with `lv.EVENT.XXX`)
`event.target`	The object that triggered the event (Obj)
`event.current_target`	The object currently handling the event (object on the event bubbling path)
`event.stop_bubbling()`	Stops event bubbling
`event.stop_processing()`	Stops event processing for the current object
`event.stop_trickling()`	Stops propagating the event to child objects

Backward compatibility: The Event object supports == int comparisons (event == lv.EVENT.CLICKED is equivalent to event.code == lv.EVENT.CLICKED), so existing code will continue to run without modification.

Complete Event Codes (`lv.EVENT`, 76 total)#

Event	Description
`ALL`	All events
`PRESSED`	Pressed
`PRESSING`	Pressing
`PRESS_LOST`	Press lost
`SHORT_CLICKED`	Short click
`SINGLE_CLICKED`	Single click
`DOUBLE_CLICKED`	Double click
`TRIPLE_CLICKED`	Triple click
`LONG_PRESSED`	Long press
`LONG_PRESSED_REPEAT`	Long press repeat
`CLICKED`	Clicked
`RELEASED`	Released
`SCROLL_BEGIN`	Scrolling begins
`SCROLL_THROW_BEGIN`	Momentum scrolling begins
`SCROLL_END`	Scrolling ends
`SCROLL`	Scroll
`GESTURE`	Gesture
`KEY`	Key
`ROTARY`	Rotary
`FOCUSED`	Focused
`DEFOCUSED`	Defocused
`LEAVE`	Leave
`HIT_TEST`	Hit test
`INDEV_RESET`	Input device reset
`HOVER_OVER`	Hover over
`HOVER_STILL`	Hover still
`HOVER_LEAVE`	Hover leave
`VALUE_CHANGED`	Value changed
`INSERT`	Insert
`REFRESH`	Refresh
`READY`	Ready
`CANCEL`	Cancel
`SCREEN_LOADED`	Screen loading complete
`SCREEN_LOAD_START`	Screen loading starts
`SCREEN_UNLOADED`	Screen unloading complete
`SCREEN_UNLOAD_START`	Screen unloading starts
`SIZE_CHANGED`	Size changed
`DRAW_TASK_ADDED`	Draw task added
`CHILD_CHANGED`	Child changed
`CHILD_CREATED`	Child created
`CHILD_DELETED`	Child deleted
`SELECTED`	Selected
`CHECKED`	Checked

Style System#

Styles are set through the set_style_*(value, selector) method. The selector parameter specifies the target to which the style is applied. It is recommended to use lv.SELECTOR.DEFAULT (the default state LV_PART_MAIN | LV_STATE_DEFAULT) and avoid using the bare number 0.

Common selector values#

Value	Description
`lv.SELECTOR.DEFAULT`	`LV_PART_MAIN` + default state (= 0)
`lv.PART.MAIN`	Main part
`lv.PART.INDICATOR`	Indicator part (Slider/Bar fill)
`lv.PART.KNOB`	Knob part
`lv.PART.ITEMS`	Item part
`lv.PART.CURSOR`	Cursor part
`lv.PART.SELECTED`	Selected part
`lv.PART.SCROLLBAR`	Scrollbar part
`lv.PART.CUSTOM_FIRST`	Starting position for custom parts
`lv.PART.ANY`	Any part

Tip: Combine Part + State using bitwise OR: lv.PART.KNOB | lv.STATE.FOCUSED

Background styles#

obj.set_style_bg_color(lv.color_make(255, 0, 0), lv.SELECTOR.DEFAULT)       # Background color
obj.set_style_bg_opa(lv.OPA_50, lv.SELECTOR.DEFAULT)                 # Background opacity
obj.set_style_bg_grad_color(lv.color_make(0, 0, 255), lv.SELECTOR.DEFAULT)   # Gradient end color
obj.set_style_bg_grad_dir(lv.GRAD_DIR.VER, lv.SELECTOR.DEFAULT)  # Gradient direction
obj.set_style_bg_main_stop(0, lv.SELECTOR.DEFAULT)                       # Gradient start position (0-255)
obj.set_style_bg_grad_stop(255, lv.SELECTOR.DEFAULT)                     # Gradient end position
obj.set_style_bg_main_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # Gradient start opacity
obj.set_style_bg_grad_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # Gradient end opacity
obj.set_style_bg_image_src(src, lv.SELECTOR.DEFAULT)                     # Background image
obj.set_style_bg_image_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)              # Background image opacity
obj.set_style_bg_image_recolor(color, lv.SELECTOR.DEFAULT)               # Recolor background image
obj.set_style_bg_image_tiled(True, lv.SELECTOR.DEFAULT)                  # Tile background image

Border styles#

obj.set_style_border_width(2, lv.SELECTOR.DEFAULT)                       # Border width
obj.set_style_border_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT)       # Border color
obj.set_style_border_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)             # Border opacity
obj.set_style_border_side(lv.BORDER_SIDE.FULL, lv.SELECTOR.DEFAULT)  # Border side
obj.set_style_border_post(True, lv.SELECTOR.DEFAULT)                     # Draw border last

Rounded corners and shadows#

obj.set_style_radius(10, lv.SELECTOR.DEFAULT)                            # Corner radius
obj.set_style_shadow_width(10, lv.SELECTOR.DEFAULT)                      # Shadow width
obj.set_style_shadow_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT)       # Shadow color
obj.set_style_shadow_offset_x(3, lv.SELECTOR.DEFAULT)                    # Shadow X offset
obj.set_style_shadow_offset_y(3, lv.SELECTOR.DEFAULT)                    # Shadow Y offset
obj.set_style_shadow_spread(2, lv.SELECTOR.DEFAULT)                      # Shadow spread
obj.set_style_shadow_opa(lv.OPA_50, lv.SELECTOR.DEFAULT)              # Shadow opacity

Blur styles#

obj.set_style_blur_radius(r, lv.SELECTOR.DEFAULT)                        # Blur radius
obj.set_style_blur_quality(lv.BLUR_QUALITY.AUTO, lv.SELECTOR.DEFAULT)    # Blur quality
obj.set_style_blur_backdrop(True, lv.SELECTOR.DEFAULT)                   # Blur backdrop

Outline styles#

obj.set_style_outline_width(2, lv.SELECTOR.DEFAULT)                      # Outline width
obj.set_style_outline_color(lv.color_make(0, 128, 255), lv.SELECTOR.DEFAULT)  # Outline color
obj.set_style_outline_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)            # Outline opacity
obj.set_style_outline_pad(3, lv.SELECTOR.DEFAULT)                        # Outline padding

Text styles#

obj.set_style_text_color(lv.color_make(255, 255, 255), lv.SELECTOR.DEFAULT)   # Text color
obj.set_style_text_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # Text opacity
obj.set_style_text_font(font_ptr, lv.SELECTOR.DEFAULT)                    # Text font
obj.set_style_text_letter_space(2, lv.SELECTOR.DEFAULT)                   # Letter spacing
obj.set_style_text_line_space(4, lv.SELECTOR.DEFAULT)                     # Line spacing
obj.set_style_text_align(lv.TEXT_ALIGN.CENTER, lv.SELECTOR.DEFAULT)  # Text alignment
obj.set_style_text_decor(lv.TEXT_DECOR.UNDERLINE, lv.SELECTOR.DEFAULT)  # Text decoration
obj.set_style_text_outline_stroke_width(1, lv.SELECTOR.DEFAULT)           # Text outline stroke width
obj.set_style_text_outline_stroke_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT) # Stroke color

Padding and margin#

obj.set_style_pad_top(10, lv.SELECTOR.DEFAULT)
obj.set_style_pad_bottom(10, lv.SELECTOR.DEFAULT)
obj.set_style_pad_left(10, lv.SELECTOR.DEFAULT)
obj.set_style_pad_right(10, lv.SELECTOR.DEFAULT)
obj.set_style_pad_row(5, lv.SELECTOR.DEFAULT)       # Row spacing (Flex/Grid)
obj.set_style_pad_column(5, lv.SELECTOR.DEFAULT)    # Column spacing

# Shorthand (padding)
obj.set_style_pad_all(10, lv.SELECTOR.DEFAULT)      # Same on all sides
obj.set_style_pad_hor(10, lv.SELECTOR.DEFAULT)      # Same on left and right
obj.set_style_pad_ver(10, lv.SELECTOR.DEFAULT)      # Same on top and bottom
obj.set_style_pad_gap(5, lv.SELECTOR.DEFAULT)       # Same row and column spacing

obj.set_style_margin_top(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_bottom(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_left(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_right(5, lv.SELECTOR.DEFAULT)

# Shorthand (margin)
obj.set_style_margin_all(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_hor(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_ver(5, lv.SELECTOR.DEFAULT)

Transform styles#

obj.set_style_transform_scale_x(256, lv.SELECTOR.DEFAULT)        # X 缩放 (256=1x)
obj.set_style_transform_scale_y(256, lv.SELECTOR.DEFAULT)        # Y 缩放
obj.set_style_transform_scale(256, lv.SELECTOR.DEFAULT)          # XY 同时缩放
obj.set_style_transform_rotation(0, lv.SELECTOR.DEFAULT)          # 旋转 (0.1° 单位)
obj.set_style_transform_pivot_x(0, lv.SELECTOR.DEFAULT)           # 旋转中心 X
obj.set_style_transform_pivot_y(0, lv.SELECTOR.DEFAULT)           # 旋转中心 Y
obj.set_style_transform_skew_x(0, lv.SELECTOR.DEFAULT)            # X 倾斜
obj.set_style_transform_skew_y(0, lv.SELECTOR.DEFAULT)            # Y 倾斜
obj.set_style_translate_x(10, lv.SELECTOR.DEFAULT)                # X 平移
obj.set_style_translate_y(10, lv.SELECTOR.DEFAULT)                # Y 平移

Other styles#

obj.set_style_opa(lv.OPA_80, lv.SELECTOR.DEFAULT)              # Overall opacity
obj.set_style_opa_layered(lv.OPA_80, lv.SELECTOR.DEFAULT)      # Layered opacity
obj.set_style_clip_corner(True, lv.SELECTOR.DEFAULT)               # Clip rounded corners
obj.set_style_blend_mode(lv.BLEND_MODE.NORMAL, lv.SELECTOR.DEFAULT)  # Blend mode
obj.set_style_anim_duration(300, lv.SELECTOR.DEFAULT)              # Animation duration
obj.set_style_base_dir(lv.BASE_DIR.LTR, lv.SELECTOR.DEFAULT)  # Text direction
obj.set_style_bitmap_mask_src(src, lv.SELECTOR.DEFAULT)            # Bitmap mask
obj.set_style_color_filter_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)   # Color filter opacity
obj.set_style_layout(lv.LAYOUT.FLEX, lv.SELECTOR.DEFAULT)         # Layout type
obj.set_style_radial_offset(0, lv.SELECTOR.DEFAULT)               # Radial offset
obj.set_style_recolor(color, lv.SELECTOR.DEFAULT)                 # Recolor
obj.set_style_rotary_sensitivity(256, lv.SELECTOR.DEFAULT)        # Rotary sensitivity

Line and arc styles#

obj.set_style_line_width(2, lv.SELECTOR.DEFAULT)                   # Line width
obj.set_style_line_color(lv.color_make(0, 0, 255), lv.SELECTOR.DEFAULT) # Line color
obj.set_style_line_rounded(True, lv.SELECTOR.DEFAULT)              # Rounded line caps
obj.set_style_line_dash_width(10, lv.SELECTOR.DEFAULT)             # Dash width
obj.set_style_line_dash_gap(5, lv.SELECTOR.DEFAULT)                # Dash gap

obj.set_style_arc_width(4, lv.SELECTOR.DEFAULT)                    # Arc width
obj.set_style_arc_color(lv.color_make(255, 0, 0), lv.SELECTOR.DEFAULT)  # Arc color
obj.set_style_arc_rounded(True, lv.SELECTOR.DEFAULT)               # Rounded arc caps
obj.set_style_arc_image_src(src, lv.SELECTOR.DEFAULT)              # Arc image

Size constraint styles#

obj.set_style_min_width(50, lv.SELECTOR.DEFAULT)
obj.set_style_max_width(200, lv.SELECTOR.DEFAULT)
obj.set_style_min_height(30, lv.SELECTOR.DEFAULT)
obj.set_style_max_height(100, lv.SELECTOR.DEFAULT)
obj.set_style_width(100, lv.SELECTOR.DEFAULT)           # Fixed width
obj.set_style_height(50, lv.SELECTOR.DEFAULT)            # Fixed height
obj.set_style_size(100, lv.SELECTOR.DEFAULT)             # Fixed size (width=height)

Layouts (Flex / Grid)#

Flex Layout#

# Set Flex on the parent container
container.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)  # Row + wrapping
container.set_flex_align(
    lv.FLEX_ALIGN.CENTER,       # Main-axis alignment
    lv.FLEX_ALIGN.CENTER,       # Cross-axis alignment
    lv.FLEX_ALIGN.CENTER        # Row alignment
)

# Child item settings
child.set_flex_grow(1)  # Flexible growth

Flex Flow (lv.FLEX_FLOW)：ROW, COLUMN, ROW_WRAP, ROW_REVERSE, ROW_WRAP_REVERSE, COLUMN_WRAP, COLUMN_REVERSE, COLUMN_WRAP_REVERSE

Flex Alignment (lv.FLEX_ALIGN)：START, END, CENTER, SPACE_EVENLY, SPACE_AROUND, SPACE_BETWEEN

Grid Layout#

container.set_grid_align(
    lv.GRID_ALIGN.CENTER,  # Column alignment
    lv.GRID_ALIGN.CENTER   # Row alignment
)

child.set_grid_cell(
    lv.GRID_ALIGN.CENTER,  # Column alignment
    0, 1,                                 # Column position, column span
    lv.GRID_ALIGN.CENTER,  # Row alignment
    0, 1                                  # Row position, row span
)

Grid Alignment (lv.GRID_ALIGN)：START, CENTER, END, STRETCH, SPACE_EVENLY, SPACE_AROUND, SPACE_BETWEEN

Layout Type (lv.LAYOUT)：NONE, FLEX, GRID, LAST

Scrolling#

obj.set_scrollbar_mode(lv.SCROLLBAR_MODE.AUTO)
obj.set_scroll_dir(lv.DIR.VER)        # Restrict scroll direction
obj.set_scroll_snap_x(lv.SCROLL_SNAP.CENTER)
obj.set_scroll_snap_y(lv.SCROLL_SNAP.CENTER)

obj.scroll_by(dx, dy, anim_en)               # Scroll offset
obj.scroll_to(x, y, anim_en)                 # Scroll to position
obj.scroll_to_view(anim_en)                  # Scroll into view
obj.is_scrolling()                           # Whether scrolling is in progress
obj.stop_scroll_anim()                       # Stop scroll animation

obj.get_scroll_x()                           # Get horizontal scroll position
obj.get_scroll_y()                           # Get vertical scroll position
obj.get_scroll_bottom()                      # Get bottom scroll distance
obj.get_scroll_top()                         # Get top scroll distance
obj.get_scroll_left()                        # Get left scroll distance
obj.get_scroll_right()                       # Get right scroll distance

Flags-and-states#

Object flags (`lv.OBJ_FLAG`)#

obj.add_flag(lv.OBJ_FLAG.HIDDEN)        # Hide
obj.remove_flag(lv.OBJ_FLAG.HIDDEN)     # Unhide
obj.has_flag(lv.OBJ_FLAG.CLICKABLE)     # Check flag
obj.has_flag_any(lv.OBJ_FLAG.CLICKABLE) # Check whether any flag is included
obj.set_flag(lv.OBJ_FLAG.CLICKABLE, True) # Set flag on/off

Bitwise operation support: Methods such as add_flag/remove_flag support bitwise OR operations through the _wrapper.py patch, such as obj.add_flag(lv.OBJ_FLAG.CLICKABLE | lv.OBJ_FLAG.CHECKABLE).

Common flags	Description
`HIDDEN`	Hidden
`CLICKABLE`	Clickable
`CLICK_FOCUSABLE`	Click focusable
`CHECKABLE`	Checkable
`SCROLLABLE`	Scrollable
`SCROLL_ELASTIC`	Elastic scrolling
`SCROLL_MOMENTUM`	Momentum scrolling
`SCROLL_ONE`	Scroll only one child at a time
`SCROLL_CHAIN_HOR`	Horizontal scroll chain
`SCROLL_CHAIN_VER`	Vertical scroll chain
`SCROLL_ON_FOCUS`	Scroll on focus
`SCROLL_WITH_ARROW`	Arrow key scrolling
`SNAPPABLE`	Snap to scroll position
`PRESS_LOCK`	Press lock
`EVENT_BUBBLE`	Event bubbling
`GESTURE_BUBBLE`	Gesture bubbling
`ADV_HITTEST`	Advanced hit testing
`IGNORE_LAYOUT`	Ignore layout
`FLOATING`	Floating (not included in layout)
`SEND_DRAW_TASK_EVENTS`	Send draw task events
`OVERFLOW_VISIBLE`	Overflow visible
`EVENT_TRICKLE`	Event trickle
`LAYOUT_1` ~ `LAYOUT_4`	Custom layout flags
`USER_1` ~ `USER_4`	User-defined flags

Object states (`lv.STATE`)#

obj.add_state(lv.STATE.CHECKED)             # Add state
obj.remove_state(lv.STATE.CHECKED)          # Remove state
obj.get_state()                             # Get state
obj.has_state(lv.STATE.CHECKED)             # Check state

Common states	Description
`DEFAULT`	Default
`ALT`	Alternative
`CHECKED`	Checked
`FOCUSED`	Focused
`FOCUS_KEY`	Key focus
`EDITED`	Edited
`HOVERED`	Hovered
`PRESSED`	Pressed
`SCROLLED`	Scrolled
`DISABLED`	Disabled
`USER_1` ~ `USER_4`	User-defined state
`ANY`	Any state

Screen Management#

scr = lv.screen_active()          # Get the current active screen
lv.screen_load(scr)               # Load the screen (no animation)

# Create a new screen (using obj with no arguments)
scr2 = lv.obj()
lv.screen_load(scr2)

Screen load animation (lv.SCREEN_LOAD)：NONE, OVER_LEFT, OVER_RIGHT, OVER_TOP, OVER_BOTTOM, MOVE_LEFT, MOVE_RIGHT, MOVE_TOP, MOVE_BOTTOM, FADE_IN, FADE_ON, FADE_OUT, OUT_LEFT, OUT_RIGHT, OUT_TOP, OUT_BOTTOM

Enum Reference#

Alignment (`lv.ALIGN`)#

DEFAULT, TOP_LEFT, TOP_MID, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_MID, BOTTOM_RIGHT, LEFT_MID, RIGHT_MID, CENTER, and OUT_* outside alignment variants (OUT_TOP_LEFT, OUT_TOP_MID, OUT_TOP_RIGHT, OUT_BOTTOM_LEFT, OUT_BOTTOM_MID, OUT_BOTTOM_RIGHT, OUT_LEFT_TOP, OUT_LEFT_MID, OUT_LEFT_BOTTOM, OUT_RIGHT_TOP, OUT_RIGHT_MID, OUT_RIGHT_BOTTOM). 22 in total.

Direction (`lv.DIR`)#

NONE, LEFT, RIGHT, TOP, BOTTOM, HOR, VER, ALL

Text alignment (`lv.TEXT_ALIGN`)#

AUTO, LEFT, CENTER, RIGHT

Text decoration (`lv.TEXT_DECOR`)#

NONE, UNDERLINE, STRIKETHROUGH

Color format (`lv.COLOR_FORMAT`)#

UNKNOWN, RAW, RAW_ALPHA, L8, I1, I2, I4, I8, A8, RGB565, ARGB8565, RGB565A8, AL88, RGB565_SWAPPED, RGB888, ARGB8888, XRGB8888, ARGB8888_PREMULTIPLIED, A1, A2, A4, ARGB1555, ARGB4444, ARGB2222, YUV_START, I420, NV12, NV21, YUY2, UYVY, etc. 45 in total.

Palette (`lv.PALETTE`)#

RED, PINK, PURPLE, DEEP_PURPLE, INDIGO, BLUE, LIGHT_BLUE, CYAN, TEAL, GREEN, LIGHT_GREEN, LIME, YELLOW, AMBER, ORANGE, DEEP_ORANGE, BROWN, BLUE_GREY, GREY, LAST, NONE

Blend mode (`lv.BLEND_MODE`)#

NORMAL, ADDITIVE, SUBTRACTIVE, MULTIPLY, DIFFERENCE

Scrollbar mode (`lv.SCROLLBAR_MODE`)#

OFF, ON, ACTIVE, AUTO

Border side (`lv.BORDER_SIDE`)#

NONE, BOTTOM, TOP, LEFT, RIGHT, FULL, INTERNAL

Keys (`lv.KEY`)#

UP, DOWN, RIGHT, LEFT, ESC, DEL, BACKSPACE, ENTER, NEXT, PREV, HOME, END

Gradient direction (`lv.GRAD_DIR`)#

NONE, VER, HOR, LINEAR, RADIAL, CONICAL

Gradient extension (`lv.GRAD_EXTEND`)#

PAD, REPEAT, REFLECT

Blur quality (`lv.BLUR_QUALITY`)#

AUTO, SPEED, PRECISION

Text direction (`lv.BASE_DIR`)#

LTR, RTL, AUTO, NEUTRAL, WEAK

Input device type (`lv.INDEV_TYPE`)#

NONE, POINTER, KEYPAD, BUTTON, ENCODER

Input device mode (`lv.INDEV_MODE`)#

NONE, TIMER, EVENT

Display render mode (`lv.DISPLAY_RENDER`)#

PARTIAL, DIRECT, FULL

Cover result (`lv.COVER`)#

COVER, NOT_COVER, MASKED

Symbol constants#

Constant	Description	Constant	Description
`lv.SYMBOL_BULLET`	Bullet	`lv.SYMBOL_AUDIO`	Audio
`lv.SYMBOL_VIDEO`	Video	`lv.SYMBOL_LIST`	List
`lv.SYMBOL_OK`	Confirm	`lv.SYMBOL_CLOSE`	Close
`lv.SYMBOL_POWER`	Power	`lv.SYMBOL_SETTINGS`	Settings
`lv.SYMBOL_HOME`	Home	`lv.SYMBOL_DOWNLOAD`	Download
`lv.SYMBOL_DRIVE`	Drive	`lv.SYMBOL_REFRESH`	Refresh
`lv.SYMBOL_MUTE`	Mute	`lv.SYMBOL_VOLUME_MID`	Medium volume
`lv.SYMBOL_VOLUME_MAX`	Max volume	`lv.SYMBOL_IMAGE`	Image
`lv.SYMBOL_TINT`	Tint	`lv.SYMBOL_PREV`	Previous track
`lv.SYMBOL_PLAY`	Play	`lv.SYMBOL_PAUSE`	Pause
`lv.SYMBOL_STOP`	Stop	`lv.SYMBOL_NEXT`	Next track
`lv.SYMBOL_EJECT`	Eject	`lv.SYMBOL_LEFT`	Left
`lv.SYMBOL_RIGHT`	Right	`lv.SYMBOL_PLUS`	Add
`lv.SYMBOL_MINUS`	Subtract	`lv.SYMBOL_EYE_OPEN`	Open eye
`lv.SYMBOL_EYE_CLOSE`	Closed eye	`lv.SYMBOL_WARNING`	Warning
`lv.SYMBOL_SHUFFLE`	Shuffle	`lv.SYMBOL_UP`	Up
`lv.SYMBOL_DOWN`	Down	`lv.SYMBOL_LOOP`	Loop
`lv.SYMBOL_DIRECTORY`	Directory	`lv.SYMBOL_UPLOAD`	Upload
`lv.SYMBOL_CALL`	Call	`lv.SYMBOL_CUT`	Cut
`lv.SYMBOL_COPY`	Copy	`lv.SYMBOL_SAVE`	Save
`lv.SYMBOL_BARS`	Bar chart	`lv.SYMBOL_ENVELOPE`	Envelope
`lv.SYMBOL_CHARGE`	Charging	`lv.SYMBOL_PASTE`	Paste
`lv.SYMBOL_BELL`	Bell	`lv.SYMBOL_KEYBOARD`	Keyboard
`lv.SYMBOL_GPS`	GPS	`lv.SYMBOL_FILE`	File
`lv.SYMBOL_WIFI`	WiFi	`lv.SYMBOL_BATTERY_FULL`	Full battery
`lv.SYMBOL_BATTERY_3`	Battery 3	`lv.SYMBOL_BATTERY_2`	Battery 2
`lv.SYMBOL_BATTERY_1`	Battery 1	`lv.SYMBOL_BATTERY_EMPTY`	Empty battery
`lv.SYMBOL_USB`	USB	`lv.SYMBOL_BLUETOOTH`	Bluetooth
`lv.SYMBOL_TRASH`	Trash	`lv.SYMBOL_EDIT`	Edit
`lv.SYMBOL_BACKSPACE`	Backspace	`lv.SYMBOL_SD_CARD`	SD card

Complete Example#

Example	Description	Source Code
Basic Widgets	Buttons/Checkboxes/Sliders/Progress Bars/Arcs/Switches/LEDs	quick_widgets.py
Image Loading	PNG/BMP loading, rotation, scaling	demo_image.py
Style Customization	Colors/rounded corners/shadows/gradients/blur	demo_style.py
Flex Layout	Rows/columns/wrapping/alignment	demo_flex.py
FreeType Chinese	Loading TTF fonts to display Chinese	demo_chinese.py
Animated Image	animimg frame animation	demo_animimg.py
Dashboard	anim_t-driven arc animation / timer-based periodic refresh	lvgl_python_benchmark.py

FreeType Font Support#

The built-in Montserrat font in LVGL contains only Latin characters. To display Chinese, Japanese, Korean, and other CJK characters, TTF/OTF fonts must be loaded via FreeType.

Loading a Font#

# Create a FreeType font (returns an lv.font object)
font = lv.freetype_font_create(
    "/usr/lib/fonts/SourceHanSansSC-Normal-Min.ttf",  # Font file path
    lv.FREETYPE_RENDER.BITMAP,                     # Rendering mode
    24,                                                  # Font size (px)
    lv.FREETYPE_STYLE.NORMAL,                      # Style
)

Using the Font#

label = lv.label(scr)
label.set_style_text_font(font, lv.SELECTOR.DEFAULT)   # Set the font (SELECTOR.DEFAULT = default state)
label.set_text("Hello, world!")

Releasing the Font#

The font object is automatically released when the Python GC collects it, but it can also be released manually:

lv.freetype_font_delete(font)

Rendering Modes (`lv.FREETYPE_RENDER`)#

Mode	Description
`BITMAP`	Bitmap rendering (recommended, good performance)
`OUTLINE`	Vector outline rendering (supports arbitrary scaling, lower performance)

Font Styles (`lv.FREETYPE_STYLE`)#

Style	Description
`NORMAL`	Normal
`ITALIC`	Italic
`BOLD`	Bold

font Class#

font = lv.freetype_font_create(...)
font.is_valid()   # Check whether the font is valid

Complete Example

Complete source code: quick_chinese.py | demo_chinese.py

Notes#

Font file: The K230 device comes preinstalled with SourceHanSansSC-Normal-Min.ttf (the slimmed-down version of Source Han Sans) in /usr/lib/fonts/. The slimmed-down version contains only common Chinese characters, so some special symbols (such as ° and ℃) may be missing and can be replaced with Chinese alternatives (such as “degree”).
Performance: FreeType fonts need to be rasterized when a character is first rendered, after which the result is cached. BITMAP mode performs better than OUTLINE mode.
Font size: Each font size requires a separate font object. For 16px and 24px, freetype_font_create must be called twice.
Lifecycle: Font objects are managed by the Python GC. Ensure that font objects are not collected while they are in use by labels.

Known Limitations#

The following features are not exposed in the Python bindings due to C API parameter/return type limitations:

Category	Unbound Functionality	Reason
Style objects	`lv_style_*`	Involves `lv_style_t*` struct operations
Event dispatching	`lv_event_send`, `lv_event_get_*`	Involves `lv_event_t*` parameters
Memory/strings	`lv_malloc`, `lv_memcpy`, `lv_strdup`, etc.	Manually skipped rules
Logging	`lv_log`, `lv_log_register_print_cb`	Manually skipped rules
Button/widget matrix	`lv_buttonmatrix_*`	Involves complex C array/callback parameters

Note: Animations (anim_t), timers (timer_t), groups (group_*), input devices (indev_*), and displays (display_*) have been exposed as bindings in this update.

Statistics:

Statistic	Count
`.def()` bindings (methods + functions, including overloads)	902
└ Standalone module-level functions `m.def()`	78
└ Obj class methods `obj_cls.def()` (including 99 `_widget_method` dispatches)	786+
Unique method names after deduplication	881
Enum classes `py::enum_`	96
Enum member values `.value()`	651
Module constants `m.attr()` (SYMBOL/OPA/ANIM)	651+
Classes `py::class_`	8
Widget factory functions	26

Documentation generated: 2026-07-28

Automatically generated through analysis of lvgl_pybind_generated.cpp + manual supplementation from _wrapper.py

LVGL Python API

Contents

LVGL Python API#

Quick Start#

Initialization and Drivers#

lv.init(v4l2_drm=None, v4l2_drm_run_flag=0)#

lv.settings#

lv.run()#

Module-level Functions#

Core#

Version Information#

Display#

Timers#

Animation#

Groups#

Theme#

Palette#

Input Devices#

Driver Backends#

FreeType Fonts#

Color (color)#

Create a color#

color properties#

Opacity constants#

Classes#

Basic Object obj#

Creation (obj)#

Position and Size#

Alignment#

Hierarchy and Parent-Child Relationships#

Deletion#

Event Binding (Shorthand)#

Fade In and Fade Out#

Transformation#

Coordinates and Visibility#

Widgets#

button#

label#

image#

arc#

bar#

slider#

switch#

checkbox#

dropdown#

roller#

textarea#

keyboard#

chart#

table#

tabview#

list#

menu#

msgbox#

led#

line#

canvas#

scale#

spinbox#

spinner#

tileview#

win#

animimg#

Animation (anim_t)#

Creation (anim_t)#

Common Methods (anim_t) |#

Motion Path#

Constants#

Timers (timer_t)#

Creation (timer_t)#

Common Methods (timer_t) |#

Display (display)#

Create (display)#

Common Methods (display) |#

Enumeration (display)#

Input Devices (indev)#

Creating (indev)#

Common Methods (indev)#

Enumerations (indev): NONE, POINTER, KEYPAD, BUTTON, ENCODER#

Groups (group)#

`lv.init(v4l2_drm=None, v4l2_drm_run_flag=0)`#

`lv.settings`#

`lv.run()`#

Enumerations (indev): `NONE`, `POINTER`, `KEYPAD`, `BUTTON`, `ENCODER`#

`event` Object#

Complete Event Codes (`lv.EVENT`, 76 total)#

Object flags (`lv.OBJ_FLAG`)#

Object states (`lv.STATE`)#

Alignment (`lv.ALIGN`)#

Direction (`lv.DIR`)#

Text alignment (`lv.TEXT_ALIGN`)#

Text decoration (`lv.TEXT_DECOR`)#

Color format (`lv.COLOR_FORMAT`)#

Palette (`lv.PALETTE`)#

Blend mode (`lv.BLEND_MODE`)#

Scrollbar mode (`lv.SCROLLBAR_MODE`)#

Border side (`lv.BORDER_SIDE`)#

Keys (`lv.KEY`)#

Gradient direction (`lv.GRAD_DIR`)#

Gradient extension (`lv.GRAD_EXTEND`)#

Blur quality (`lv.BLUR_QUALITY`)#

Text direction (`lv.BASE_DIR`)#

Input device type (`lv.INDEV_TYPE`)#

Input device mode (`lv.INDEV_MODE`)#

Display render mode (`lv.DISPLAY_RENDER`)#

Widget part (`lv.PART`)#

Cover result (`lv.COVER`)#

Rendering Modes (`lv.FREETYPE_RENDER`)#

Font Styles (`lv.FREETYPE_STYLE`)#