# 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](https://www.kendryte.com/api/imagecdn/zh/sdk/k230_linux_sdk_docs/screenshot_20260728_141551.png)

| Example           | Description                                      | Source                                                                                                                                                           |
| ----------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dashboard Demo    | Avatar/chart/animated arc/list                   | [lvgl_python_benchmark.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/lvgl_python_benchmark.py)       |
| Hello             | Minimal LVGL example (button)                    | [quick_hello.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/quick_hello.py)                     |
| Camera + OSD      | Camera feed with LVGL overlay                    | [quick_camera_osd.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/quick_camera_osd.py)           |
| Camera + Rotation | Portrait orientation support                     | [quick_camera_rotation.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/quick_camera_rotation.py) |
| Chinese Font      | Load a TTF font with FreeType                    | [quick_chinese.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/quick_chinese.py)                 |
| Basic Widgets     | Button/slider/progress bar/arc/switch/LED        | [quick_widgets.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/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.

```python
# 标准 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

```python
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

```python
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)

```python
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:

```python
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)

```python
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

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

### Transformation

```python
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):

```python
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

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_button.py)

---

### label

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

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_label.py)

---

### image

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

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_image.py)

---

### arc

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

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_arc.py)

---

### bar

Progress bar widget used to display a ratio or progress.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_bar.py)

---

### slider

Slider widget used to drag and adjust a value.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_slider.py)

---

### switch

Switch widget used to toggle on/off states.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_switch.py)

---

### checkbox

Checkbox widget used to select or deselect an option.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_checkbox.py)

---

### dropdown

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

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_dropdown.py)

---

### roller

Roller widget for selecting options by scrolling.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_roller.py)

---

### textarea

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

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_textarea.py)

---

### keyboard

Virtual keyboard widget used with Textarea to enter text.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_keyboard.py)

---

### chart

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

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_chart.py)

---

### table

Table widget used to display row and column data.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_table.py)

---

### tabview

Tab view widget used to switch between multiple pages.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_tabview.py)

---

### list

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

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_list.py)

---

### menu

Menu widget used for multi-level navigation interfaces.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/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

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/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

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_led.py)

---

### line

Polyline widget used to draw a polyline with multiple segments.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/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

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/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

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_scale.py)

---

### spinbox

Numeric input field widget used for precise value adjustment.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_spinbox.py)

---

### spinner

Loading animation widget used to display a waiting state.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_spinner.py)

---

### tileview

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

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_tileview.py)

---

### win

Window widget with a title bar and content area.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_win.py)

---

### animimg

Animated image widget used to play frame animations.

Creation

```python
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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_animimg.py)

---

## Animation (anim_t)

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

### Creation (anim_t)

```python
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)                         |

| `set_exec_cb(obj, callback)`      | Set the execution callback `fn(var, value)`            |
| `set_values(start, end)`          | Set the start/end values                          |
| `set_duration(ms)`                | Forward duration                             |
| `set_reverse_duration(ms)`        | Reverse duration                             |
| `set_delay(ms)`                   | Delayed start                                 |
| `set_repeat_count(n)`             | Number of repeats (`ANIM_REPEAT_INFINITE` = infinite) |
| `set_repeat_delay(ms)`            | Repeat interval                                 |
| `set_early_apply(True)`           | Apply the start value immediately                           |
| `set_completed_cb(obj, callback)` | Set the completion callback                             |
| `set_start_cb(obj, callback)`     | Set the start callback                             |
| `start()`                         | Start the animation                                 |
| `delete()`                        | Delete the animation                                 |

### 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)

```python
def on_timer(timer):
    # Code executed periodically
    pass

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

### Common Methods (timer_t)    |

| `ready()`        | Mark the timer as ready |
| `pause()`        | Pause the timer          |
| `resume()`       | Resume the timer         |
| `is_valid()`     | Whether the timer is valid |
| `delete()`       | Delete the timer         |

---

## Display (display)

Displays objects, used to manage screen resolution and rotation.

### Create (display)

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

### Common Methods (display)     |

| `set_rotation(rotation)`      | Set rotation       |
| `get_horizontal_resolution()` | Get horizontal resolution |
| `get_vertical_resolution()`   | Get vertical resolution |
| `flush_ready()`               | Notify that flushing is complete |

### 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)

```python
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

```python
# 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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
# 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

```python
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

```python
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`)

```python
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`)

```python
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

```python
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`

### Widget part (`lv.PART`)

`MAIN`, `SCROLLBAR`, `INDICATOR`, `KNOB`, `SELECTED`, `ITEMS`, `CURSOR`, `CUSTOM_FIRST`, `ANY`

### 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](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/quick_widgets.py)                                           |
| Image Loading  | PNG/BMP loading, rotation, scaling                          | [demo_image.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_image.py)                                                 |
| Style Customization | Colors/rounded corners/shadows/gradients/blur              | [demo_style.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_style.py)                                                 |
| Flex Layout    | Rows/columns/wrapping/alignment                             | [demo_flex.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_flex.py)                                                   |
| FreeType Chinese | Loading TTF fonts to display Chinese                    | [demo_chinese.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_chinese.py)                                             |
| Animated Image | animimg frame animation                                     | [demo_animimg.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_animimg.py)                                             |
| Dashboard      | anim_t-driven arc animation / timer-based periodic refresh | [lvgl_python_benchmark.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/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

```python
# 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

```python
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:

```python
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

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

Complete Example

> Complete source code: [quick_chinese.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/quick_chinese.py) | [demo_chinese.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/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`