# LVGL Python API

> LVGL (Light and Versatile Graphics Library) Python bindings for K230 平台
>
> 自动生成自 LVGL C 头文件，通过 libclang → IR → pybind11 流水线构建。
> 绑定方法/函数 902 个 (`.def()`)，枚举值 651 个，模块常量 65 个，枚举类 96 个，控件 26 个，类 8 个。

---

## 快速开始

![LVGL Benchmark Demo](https://www.kendryte.com/api/imagecdn/zh/sdk/k230_linux_sdk_docs/screenshot_20260728_141551.png)

| 示例          | 说明                           | 源码                                                                                                                                                              |
| ------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 仪表盘 Demo   | 头像/图表/动画弧形/列表        | [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         | 最小 LVGL 示例 (按钮)          | [quick_hello.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/quick_hello.py)                     |
| 摄像头 + OSD  | 摄像头画面叠加 LVGL 界面       | [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)           |
| 摄像头 + 旋转 | 竖屏适配                       | [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) |
| 中文字体      | FreeType 加载 TTF 字体         | [quick_chinese.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/quick/quick_chinese.py)                 |
| 基础控件      | 按钮/滑块/进度条/弧形/开关/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)                 |

---

## 初始化与驱动

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

K230 平台一键初始化，内部完成：

- `lv_init()` — 初始化 LVGL 库
- 注册驱动后端
- 初始化显示后端 (DRM 或 DRM_V4L2_K230)
- 初始化 EVDEV 输入后端

| 参数                | 类型                | 说明                                                                                                |
| ------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `v4l2_drm`          | `V4l2Drm` 或 `None` | 传入 V4l2Drm 对象使用 K230 v4l2-drm 后端 (OSD 与摄像头视频共享 DRM)；`None` 使用标准 Linux DRM 后端 |
| `v4l2_drm_run_flag` | `int`               | 保留参数，当前未使用，默认 0                                                                        |

### `lv.run()`

进入 LVGL 驱动运行循环 (阻塞)。支持 Ctrl+C 中断，中断后调用 os._exit(0) 退出。

---

## 模块级函数

### 核心

| 函数                     | 说明                                                 |
| ------------------------ | ---------------------------------------------------- |
| `lv.init()`              | 初始化 LVGL 库                                       |
| `lv.deinit()`            | 反初始化 LVGL 库                                     |
| `lv.is_initialized()`    | LVGL 是否已初始化                                    |
| `lv.timer_handler()`     | 调用 LVGL 定时器处理 (主循环核心)，返回空闲时间 (ms) |
| `lv.screen_active()`     | 获取当前活动屏幕对象                                 |
| `lv.screen_load(screen)` | 加载指定屏幕                                         |
| `lv.demo_benchmark()`    | 运行 LVGL 性能基准测试                               |
| `lv.pct(n)`              | 返回百分比宽度/高度值 (用于 `set_width` 等)          |

### 版本信息

| 函数                 | 说明                |
| -------------------- | ------------------- |
| `lv.version_major()` | LVGL 主版本号       |
| `lv.version_minor()` | LVGL 次版本号       |
| `lv.version_patch()` | LVGL 补丁版本号     |
| `lv.version_info()`  | LVGL 版本信息字符串 |

### 显示

| 函数                         | 说明                |
| ---------------------------- | ------------------- |
| `lv.display_create(w, h)`    | 创建显示对象        |
| `lv.display_get_default()`   | 获取默认显示对象    |
| `lv.evdev_create(type, dev)` | 创建 EVDEV 输入设备 |

### 定时器

| 函数                             | 说明                          |
| -------------------------------- | ----------------------------- |
| `lv.timer_create(cb, period_ms)` | 创建定时器，返回 timer_t 对象 |

### 动画

| 常量                      | 说明           |
| ------------------------- | -------------- |
| `lv.ANIM_REPEAT_INFINITE` | 动画无限循环值 |

### 分组

| 函数                           | 说明             |
| ------------------------------ | ---------------- |
| `lv.group_create()`            | 创建输入分组     |
| `lv.group_delete(group)`       | 删除分组         |
| `lv.group_set_default(group)`  | 设置默认分组     |
| `lv.group_get_default()`       | 获取默认分组     |
| `lv.group_add_obj(group, obj)` | 将对象加入分组   |
| `lv.group_remove_obj(obj)`     | 将对象从分组移除 |
| `lv.group_focus_obj(obj)`      | 聚焦指定对象     |
| `lv.group_focus_next(group)`   | 聚焦下一个对象   |
| `lv.group_focus_prev(group)`   | 聚焦上一个对象   |
| `lv.group_set_wrap(group, en)` | 设置是否循环聚焦 |

### 主题

| 函数                               | 说明           |
| ---------------------------------- | -------------- |
| `lv.theme_default_init(disp, ...)` | 初始化默认主题 |
| `lv.theme_get_color_primary()`     | 获取主题主色   |

### 调色板

| 函数                           | 说明           |
| ------------------------------ | -------------- |
| `lv.palette_main(palette)`     | 获取调色板主色 |
| `lv.palette_lighten(pal, lvl)` | 获取调色板亮色 |
| `lv.palette_darken(pal, lvl)`  | 获取调色板暗色 |

### 输入设备

| 函数                               | 说明               |
| ---------------------------------- | ------------------ |
| `lv.indev_create()`                | 创建输入设备       |
| `lv.indev_get_next(indev)`         | 获取下一个输入设备 |
| `lv.indev_get_type(indev)`         | 获取输入设备类型   |
| `lv.indev_set_group(indev, group)` | 设置输入设备的分组 |
| `lv.indev_set_type(indev, type)`   | 设置输入设备类型   |

### 驱动后端

| 函数                                     | 说明                                      |
| ---------------------------------------- | ----------------------------------------- |
| `lv.k230_driver_init(display_ptr, flag)` | K230 驱动初始化 (由 `lv.init()` 内部调用) |
| `lv.driver_backends_register()`          | 注册驱动后端                              |
| `lv.driver_backends_init_backend()`      | 初始化驱动后端                            |
| `lv.driver_backends_is_supported()`      | 查询后端是否支持                          |
| `lv.driver_backends_print_supported()`   | 打印支持的后端                            |
| `lv.driver_backends_run_loop()`          | 运行驱动循环                              |

### FreeType 字体

| 函数                                                 | 说明               |
| ---------------------------------------------------- | ------------------ |
| `lv.freetype_font_create(path, render, size, style)` | 创建 FreeType 字体 |
| `lv.freetype_font_delete(font)`                      | 删除 FreeType 字体 |

---

## 颜色 (color)

### 创建颜色

```python
c1 = lv.color_make(255, 0, 0)          # RGB (0-255)
c2 = lv.color.from_rgb(255, 0, 0)      # RGB (0-255)，color 静态方法
c3 = lv.color_hex(0xFF0000)            # 十六进制整数
c4 = lv.color.from_hex(0xFF0000)       # 十六进制整数，color 静态方法
c5 = lv.color(r, g, b)                 # _wrapper 别名，等同于 color_make
c6 = lv.color_from_hex_str("#FF0000")  # 十六进制字符串，_wrapper 别名
c7 = lv.color_black()                  # 纯黑
c8 = lv.color_white()                  # 纯白
```

### color 属性

```python
c = lv.color_make(255, 128, 0)
print(c.red, c.green, c.blue)       # 读取 RGB 分量 (只读, 0-255)
```

### 透明度常量

| 常量            | 值  | 说明        |
| --------------- | --- | ----------- |
| `lv.OPA_TRANSP` | 0   | 完全透明    |
| `lv.OPA_0`      | 0   | 0% 不透明   |
| `lv.OPA_10`     | 25  | 10% 不透明  |
| `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% 不透明 |
| `lv.OPA_COVER`  | 255 | 完全不透明  |

---

## 类 (Classes)

| 类        | Python 名称  | 说明                |
| --------- | ------------ | ------------------- |
| `obj`     | `lv.obj`     | 所有控件的基类      |
| `event`   | `lv.event`   | 事件对象            |
| `color`   | `lv.color`   | 颜色对象            |
| `display` | `lv.display` | 显示对象            |
| `indev`   | `lv.indev`   | 输入设备对象        |
| `timer_t` | `lv.timer_t` | 定时器对象          |
| `anim_t`  | `lv.anim_t`  | 动画对象            |
| `font`    | `lv.font`    | 字体对象 (FreeType) |

---

## 基础对象 obj

`obj` 是所有控件的基类。所有控件都继承 `obj` 的方法。

### 创建 (obj)

```python
obj = lv.obj()                      # 无参构造
child = parent.obj()                # 创建子对象 (在 parent 下创建新的 obj)
```

> **注意**: `lv.obj()` 无参构造创建基础对象，`parent.obj()` 在父对象下创建子对象。

### 位置与尺寸

| 方法                                           | 说明         |
| ---------------------------------------------- | ------------ |
| `set_pos(x, y)`                                | 设置位置     |
| `set_x(x)`                                     | 设置 X 坐标  |
| `set_y(y)`                                     | 设置 Y 坐标  |
| `set_size(w, h)`                               | 设置宽高     |
| `set_width(w)`                                 | 设置宽度     |
| `set_height(h)`                                | 设置高度     |
| `set_content_width(w)`                         | 设置内容宽度 |
| `set_content_height(h)`                        | 设置内容高度 |
| `get_x()` / `get_y()`                          | 获取坐标     |
| `get_width()` / `get_height()`                 | 获取宽高     |
| `get_content_width()` / `get_content_height()` | 获取内容宽高 |

### 对齐

| 方法                                  | 说明             |
| ------------------------------------- | ---------------- |
| `set_align(align)`                    | 设置对齐方式     |
| `align(align, x_ofs, y_ofs)`          | 相对父对象对齐   |
| `align_to(base, align, x_ofs, y_ofs)` | 相对另一对象对齐 |
| `center()`                            | 居中             |

对齐值使用 `lv.ALIGN` 枚举：

```python
lv.ALIGN.CENTER           # 居中
lv.ALIGN.TOP_LEFT         # 左上
lv.ALIGN.TOP_MID          # 上中
lv.ALIGN.TOP_RIGHT        # 右上
lv.ALIGN.BOTTOM_LEFT      # 左下
lv.ALIGN.BOTTOM_MID       # 下中
lv.ALIGN.BOTTOM_RIGHT     # 右下
lv.ALIGN.LEFT_MID         # 左中
lv.ALIGN.RIGHT_MID        # 右中
lv.ALIGN.OUT_TOP_LEFT     # 父对象外侧上方左对齐
lv.ALIGN.OUT_BOTTOM_MID   # 父对象外侧下方居中
# ... 更多 OUT_ 变体
```

### 层级与父子关系

| 方法                 | 说明               |
| -------------------- | ------------------ |
| `set_parent(parent)` | 设置父对象         |
| `get_parent()`       | 获取父对象         |
| `get_child(idx)`     | 获取子对象         |
| `get_child_count()`  | 获取子对象数量     |
| `get_index()`        | 获取在兄弟中的索引 |
| `move_to_index(idx)` | 移动到指定索引位置 |
| `move_foreground()`  | 移到最前           |
| `move_background()`  | 移到最后           |
| `swap(obj2)`         | 交换两个对象位置   |

### 删除

| 方法             | 说明           |
| ---------------- | -------------- |
| `delete_obj()`   | 删除对象       |
| `delete_async()` | 异步删除对象   |
| `clean()`        | 删除所有子对象 |

### 事件绑定 (简写)

```python
btn.add_event_cb(lv.EVENT.CLICKED, callback)        # 添加事件回调
btn.on(lv.EVENT.CLICKED, callback)                  # 简写，等同于 add_event_cb
btn.off(lv.EVENT.CLICKED, callback)                 # 移除事件回调 (LED 专用)
btn.remove_event(idx)                               # 按索引移除事件
btn.remove_event_cb_with_user_data(cb, data)        # 按回调移除事件
```

### 淡入淡出

```python
obj.fade_in(time_ms, delay_ms)   # 淡入
obj.fade_out(time_ms, delay_ms)  # 淡出
```

### 变换

```python
obj.set_transform(matrix)     # 设置变换矩阵
obj.reset_transform()         # 重置变换
obj.transform_point(point)    # 变换坐标点
```

### 坐标与可见性

| 方法                       | 说明                  |
| -------------------------- | --------------------- |
| `get_coords()`             | 获取绝对坐标区域      |
| `get_content_coords()`     | 获取内容区域坐标      |
| `invalidate()`             | 标记区域为无效 (重绘) |
| `invalidate_area(area)`    | 标记指定区域为无效    |
| `is_visible()`             | 对象是否可见          |
| `area_is_visible(area)`    | 区域是否在对象内可见  |
| `move_to(x, y)`            | 移动到绝对位置        |
| `move_children_by(dx, dy)` | 移动所有子对象        |

---

## 控件 (Widgets)

所有控件通过模块级工厂函数创建，传入 `parent` 参数 (可选，默认为当前屏幕)：

```python
btn = lv.button(parent)   # 创建按钮
```

> **统一命名**: 所有控件共享 `obj` 基类，但每个控件的方法都使用统一短名称（如 `set_text`、`set_value`、`close`），无需加控件前缀。同名方法在不同控件上自动调用对应实现（如 `arc.set_value()` 和 `slider.set_value()` 各自更新对应控件的值）。每个控件章节的"常用方法"表已列出该控件支持的完整方法。

### button

基础交互控件，用于触发操作。

创建

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

常用方法

| 方法                                  | 说明             |
| ------------------------------------- | ---------------- |
| `set_size(w, h)`                      | 设置宽高         |
| `set_pos(x, y)`                       | 设置位置         |
| `center()`                            | 居中             |
| `align(align, x_ofs, y_ofs)`          | 相对父对象对齐   |
| `align_to(base, align, x_ofs, y_ofs)` | 相对另一对象对齐 |
| `add_event_cb(event, cb)`             | 添加事件回调     |
| `add_flag(flag)`                      | 添加标志         |
| `remove_flag(flag)`                   | 移除标志         |
| `set_style_bg_color(color, selector)` | 设置背景颜色     |
| `set_style_bg_opa(opa, selector)`     | 设置背景透明度   |

事件

| 事件                    | 说明 |
| ----------------------- | ---- |
| `lv.EVENT.CLICKED`      | 点击 |
| `lv.EVENT.PRESSED`      | 按下 |
| `lv.EVENT.RELEASED`     | 释放 |
| `lv.EVENT.LONG_PRESSED` | 长按 |

完整示例

[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

文本显示控件，支持多行、滚动、重新着色等模式。

创建

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

常用方法

| 方法                    | 说明                  |
| ----------------------- | --------------------- |
| `set_text(text)`        | 设置文本              |
| `set_text_static(text)` | 设置静态文本 (不复制) |
| `set_long_mode(mode)`   | 设置长文本模式        |
| `set_recolor(True)`     | 启用重新着色          |
| `set_max_lines(n)`      | 最大行数              |
| `get_text()`            | 获取文本              |
| `ins_text(pos, text)`   | 在位置插入文本        |
| `cut_text(pos, count)`  | 从位置剪切文本        |

枚举

**长文本模式 (`lv.LABEL_LONG`)**：

| 枚举值            | 说明               |
| ----------------- | ------------------ |
| `WRAP`            | 自动换行 (默认)    |
| `DOTS`            | 超出部分显示省略号 |
| `SCROLL`          | 滚动显示           |
| `SCROLL_CIRCULAR` | 循环滚动           |
| `CLIP`            | 裁剪               |

事件

| 事件                     | 说明     |
| ------------------------ | -------- |
| `lv.EVENT.VALUE_CHANGED` | 文本改变 |

完整示例

[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

图片显示控件，支持缩放、旋转、偏移等变换。

创建

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

> **文件路径**: LVGL 使用 FS_STDIO 后端，驱动器盘符为 `A:`，所有文件路径必须以 `A:` 开头 (如 `"A:/root/image.png"`)。支持 PNG (推荐)、BMP、JPEG (仅 baseline) 格式。

常用方法

| 方法                     | 说明                        |
| ------------------------ | --------------------------- |
| `set_src(src)`           | 设置图片源                  |
| `set_offset_x(x)`        | X 偏移                      |
| `set_offset_y(y)`        | Y 偏移                      |
| `set_rotation(angle)`    | 旋转 (0.1度单位, 450=45.0°) |
| `set_pivot(x, y)`        | 设置旋转中心                |
| `set_scale(zoom)`        | 缩放 (256=1x, 512=2x)       |
| `set_scale_x(zoom)`      | X 方向缩放                  |
| `set_scale_y(zoom)`      | Y 方向缩放                  |
| `set_blend_mode(mode)`   | 混合模式                    |
| `set_antialias(True)`    | 抗锯齿                      |
| `set_inner_align(align)` | 内部对齐                    |
| `get_scale()`            | 获取缩放值                  |
| `get_rotation()`         | 获取旋转角度                |
| `get_src_width()`        | 获取源图宽度                |
| `get_src_height()`       | 获取源图高度                |
| `get_pivot()`            | 获取旋转中心                |

枚举

**图片对齐 (`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`

事件

| 事件                     | 说明     |
| ------------------------ | -------- |
| `lv.EVENT.VALUE_CHANGED` | 图片改变 |

完整示例

[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

弧形控件，用于显示角度范围或作为旋钮调节值。

创建

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

常用方法

| 方法                        | 说明           |
| --------------------------- | -------------- |
| `set_range(min, max)`       | 设置值范围     |
| `set_value(value)`          | 设置当前值     |
| `set_min_value(val)`        | 设置最小值     |
| `set_max_value(val)`        | 设置最大值     |
| `set_angles(start, end)`    | 设置前景弧角度 |
| `set_bg_angles(start, end)` | 设置背景弧角度 |
| `set_rotation(angle)`       | 旋转偏移       |
| `set_mode(mode)`            | 模式           |
| `set_change_rate(rate)`     | 值变化速率     |
| `set_knob_offset(offset)`   | 旋钮偏移       |
| `get_value()`               | 获取当前值     |
| `get_min_value()`           | 获取最小值     |
| `get_max_value()`           | 获取最大值     |
| `get_rotation()`            | 获取旋转偏移   |
| `get_angle_start()`         | 获取前景起始角 |
| `get_angle_end()`           | 获取前景结束角 |
| `get_mode()`                | 获取模式       |

枚举

**弧形模式 (`lv.ARC_MODE`)**：`NORMAL`, `SYMMETRICAL`, `REVERSE`

事件

| 事件                     | 说明   |
| ------------------------ | ------ |
| `lv.EVENT.VALUE_CHANGED` | 值改变 |

完整示例

[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

进度条控件，用于显示比例或进度。

创建

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

常用方法

| 方法                           | 说明                  |
| ------------------------------ | --------------------- |
| `set_range(min, max)`          | 设置范围              |
| `set_value(value, anim)`       | 设置值 (是否动画)     |
| `set_start_value(value, anim)` | 设置起始值 (范围模式) |
| `set_min_value(val)`           | 设置最小值            |
| `set_max_value(val)`           | 设置最大值            |
| `set_mode(mode)`               | 模式                  |
| `set_orientation(orient)`      | 方向                  |
| `get_value()`                  | 获取当前值            |
| `get_start_value()`            | 获取起始值            |
| `get_min_value()`              | 获取最小值            |
| `get_max_value()`              | 获取最大值            |
| `get_mode()`                   | 获取模式              |
| `get_orientation()`            | 获取方向              |
| `is_symmetrical()`             | 是否对称模式          |

枚举

**条形模式 (`lv.BAR_MODE`)**：`NORMAL`, `SYMMETRICAL`, `RANGE`

**方向 (`lv.BAR_ORIENTATION`)**：`AUTO`, `HORIZONTAL`, `VERTICAL`

事件

| 事件                     | 说明   |
| ------------------------ | ------ |
| `lv.EVENT.VALUE_CHANGED` | 值改变 |

完整示例

[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

滑块控件，用于拖拽调节值。

创建

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

常用方法

| 方法                           | 说明                            |
| ------------------------------ | ------------------------------- |
| `set_range(min, max)`          | 设置范围                        |
| `set_value(value, anim)`       | 设置值 (是否动画)               |
| `set_start_value(value, anim)` | 设置起始值 (范围模式，是否动画) |
| `set_min_value(val)`           | 设置最小值                      |
| `set_max_value(val)`           | 设置最大值                      |
| `set_mode(mode)`               | 模式                            |
| `set_orientation(orient)`      | 方向                            |
| `get_value()`                  | 获取当前值                      |
| `get_left_value()`             | 获取左值 (范围模式)             |
| `get_min_value()`              | 获取最小值                      |
| `get_max_value()`              | 获取最大值                      |
| `get_mode()`                   | 获取模式                        |
| `get_orientation()`            | 获取方向                        |
| `is_symmetrical()`             | 是否对称模式                    |
| `is_dragged()`                 | 是否正在拖拽                    |

枚举

**滑块模式 (`lv.SLIDER_MODE`)**：`NORMAL`, `SYMMETRICAL`, `RANGE`

事件

| 事件                     | 说明   |
| ------------------------ | ------ |
| `lv.EVENT.VALUE_CHANGED` | 值改变 |

完整示例

[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

开关控件，用于切换开/关状态。

创建

```python
sw = lv.switch(scr)
```

常用方法

| 方法                      | 说明     |
| ------------------------- | -------- |
| `set_orientation(orient)` | 方向     |
| `get_orientation()`       | 获取方向 |

枚举

**方向 (`lv.SWITCH_ORIENTATION`)**：`AUTO`, `HORIZONTAL`, `VERTICAL`

事件

| 事件                     | 说明   |
| ------------------------ | ------ |
| `lv.EVENT.VALUE_CHANGED` | 值改变 |

完整示例

[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

复选框控件，用于选择/取消选择选项。

创建

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

常用方法

| 方法                    | 说明         |
| ----------------------- | ------------ |
| `set_text(text)`        | 设置文本     |
| `set_text_static(text)` | 设置静态文本 |
| `get_text()`            | 获取文本     |

事件

| 事件                     | 说明   |
| ------------------------ | ------ |
| `lv.EVENT.VALUE_CHANGED` | 值改变 |

完整示例

[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

下拉列表控件，用于从选项中选择一项。

创建

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

常用方法

| 方法                     | 说明               |
| ------------------------ | ------------------ |
| `set_options(str)`       | 设置选项 (\n 分隔) |
| `add_option(str, pos)`   | 在位置添加选项     |
| `set_selected(idx)`      | 设置选中项         |
| `set_text(text)`         | 设置当前选中项文本 |
| `set_text_static(text)`  | 设置静态文本       |
| `set_dir(dir)`           | 设置展开方向       |
| `set_symbol(symbol)`     | 设置指示符号       |
| `clear_options()`        | 清除所有选项       |
| `get_selected()`         | 获取选中索引       |
| `get_text()`             | 获取当前选中项文本 |
| `get_options()`          | 获取选项字符串     |
| `get_option_count()`     | 获取选项数量       |
| `get_option_index(name)` | 按名称查找索引     |
| `open()`                 | 打开下拉列表       |
| `close()`                | 关闭下拉列表       |
| `is_open()`              | 是否打开           |

事件

| 事件                     | 说明       |
| ------------------------ | ---------- |
| `lv.EVENT.VALUE_CHANGED` | 选中项改变 |

完整示例

[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

滚轮控件，通过滚动选择选项。

创建

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

常用方法

| 方法                          | 说明                  |
| ----------------------------- | --------------------- |
| `set_options(str, mode)`      | 设置选项              |
| `set_selected(idx, anim)`     | 设置选中项 (是否动画) |
| `set_selected_str(str, anim)` | 按字符串选中          |
| `set_visible_row_count(n)`    | 设置可见行数          |
| `get_selected()`              | 获取选中索引          |
| `get_options()`               | 获取选项              |
| `get_option_count()`          | 获取选项数量          |

枚举

**滚轮模式 (`lv.ROLLER_MODE`)**：`NORMAL`, `INFINITE`

事件

| 事件                     | 说明       |
| ------------------------ | ---------- |
| `lv.EVENT.VALUE_CHANGED` | 选中项改变 |

完整示例

[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

文本输入框控件，支持单行/多行、密码模式、字符过滤等。

创建

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

常用方法

| 方法                         | 说明             |
| ---------------------------- | ---------------- |
| `set_text(text)`             | 设置文本         |
| `set_placeholder_text(text)` | 设置占位文本     |
| `set_one_line(True)`         | 单行模式         |
| `set_password_mode(True)`    | 密码模式         |
| `set_max_length(len)`        | 最大长度         |
| `set_accepted_chars(chars)`  | 限制可输入字符   |
| `set_cursor_pos(pos)`        | 设置光标位置     |
| `set_text_selection(True)`   | 启用文本选择     |
| `add_text(text)`             | 追加文本         |
| `add_char(code)`             | 追加字符 (ASCII) |
| `delete_char()`              | 删除光标前字符   |
| `delete_char_forward()`      | 删除光标后字符   |
| `clear_selection()`          | 清除选择         |
| `get_cursor_pos()`           | 获取光标位置     |
| `get_one_line()`             | 是否单行         |
| `get_password_mode()`        | 是否密码模式     |
| `get_max_length()`           | 获取最大长度     |

事件

| 事件                     | 说明         |
| ------------------------ | ------------ |
| `lv.EVENT.VALUE_CHANGED` | 文本内容改变 |
| `lv.EVENT.READY`         | 输入完成     |

完整示例

[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

虚拟键盘控件，用于配合 Textarea 输入文本。

创建

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

常用方法

| 方法                 | 说明             |
| -------------------- | ---------------- |
| `set_textarea(ta)`   | 关联文本输入框   |
| `set_mode(mode)`     | 设置键盘模式     |
| `set_popovers(True)` | 启用按键弹出     |
| `get_textarea()`     | 获取关联的文本框 |
| `get_mode()`         | 获取当前模式     |
| `get_button_text()`  | 获取按键文本     |

枚举

**键盘模式 (`lv.KEYBOARD_MODE`)**：`TEXT_LOWER`, `TEXT_UPPER`, `SPECIAL`, `NUMBER`, `USER_1`~`USER_4`

事件

| 事件                     | 说明              |
| ------------------------ | ----------------- |
| `lv.EVENT.VALUE_CHANGED` | 按键值改变        |
| `lv.EVENT.READY`         | 输入完成 (确认键) |

完整示例

[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

图表控件，支持折线、曲线、柱状等数据可视化。

创建

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

常用方法

| 方法                             | 说明              |
| -------------------------------- | ----------------- |
| `set_type(type)`                 | 图表类型          |
| `set_axis_range(axis, min, max)` | 设置轴范围        |
| `set_update_mode(mode)`          | 更新模式          |
| `set_div_line_count(h, v)`       | 水平/垂直分割线数 |
| `set_hor_div_line_count(n)`      | 水平分割线数      |
| `set_ver_div_line_count(n)`      | 垂直分割线数      |
| `set_axis_min_value(axis, val)`  | 设置轴最小值      |
| `set_axis_max_value(axis, val)`  | 设置轴最大值      |
| `set_point_count(n)`             | 设置数据点数      |
| `add_series(color, axis)`        | 添加数据系列      |
| `set_next_value(ser, val)`       | 追加一个数据点    |
| `set_all_values(ser, val)`       | 全部设为同一值    |
| `set_series_color(ser, color)`   | 设置系列颜色      |
| `refresh()`                      | 刷新显示          |
| `get_type()`                     | 获取类型          |
| `get_point_count()`              | 获取点数          |
| `get_update_mode()`              | 获取更新模式      |
| `get_hor_div_line_count()`       | 获取水平分割线数  |
| `get_ver_div_line_count()`       | 获取垂直分割线数  |
| `get_pressed_point()`            | 获取按下的数据点  |

枚举

**图表类型 (`lv.CHART_TYPE`)**：`NONE`, `LINE`, `CURVE`, `BAR`, `STACKED`, `SCATTER`

**更新模式 (`lv.CHART_UPDATE_MODE`)**：`SHIFT`, `CIRCULAR`

**轴 (`lv.CHART_AXIS`)**：`PRIMARY_Y`, `SECONDARY_Y`, `PRIMARY_X`, `SECONDARY_X`, `LAST`

事件

| 事件                     | 说明       |
| ------------------------ | ---------- |
| `lv.EVENT.VALUE_CHANGED` | 数据点改变 |
| `lv.EVENT.PRESSED`       | 按下数据点 |

完整示例

[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

表格控件，用于显示行列数据。

创建

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

常用方法

| 方法                             | 说明               |
| -------------------------------- | ------------------ |
| `set_row_count(n)`               | 设置行数           |
| `set_column_count(n)`            | 设置列数           |
| `set_column_width(col, w)`       | 设置列宽           |
| `set_cell_value(row, col, text)` | 设置单元格文本     |
| `set_cell_ctrl(row, col, ctrl)`  | 设置单元格控制标志 |
| `get_cell_value(row, col)`       | 获取单元格文本     |
| `get_row_count()`                | 获取行数           |
| `get_column_count()`             | 获取列数           |
| `set_selected_cell(row, col)`    | 设置选中单元格     |

枚举

**单元格控制 (`lv.TABLE_CELL_CTRL`)**：`NONE`, `MERGE_RIGHT`, `TEXT_CROP`, `CUSTOM_1`~`CUSTOM_4`

事件

| 事件                     | 说明           |
| ------------------------ | -------------- |
| `lv.EVENT.VALUE_CHANGED` | 选中单元格改变 |

完整示例

[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

标签页控件，用于多页面切换。

创建

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

常用方法

| 方法                        | 说明                  |
| --------------------------- | --------------------- |
| `add_tab(name)`             | 添加标签页            |
| `set_active(idx, anim)`     | 切换标签页 (是否动画) |
| `set_tab_bar_size(size)`    | 设置标签栏大小        |
| `set_tab_bar_position(dir)` | 设置标签栏位置        |
| `get_tab_count()`           | 获取标签页数量        |
| `get_tab_active()`          | 获取当前活动标签      |
| `get_content()`             | 获取内容区域          |
| `get_tab_bar()`             | 获取标签栏            |

事件

| 事件                     | 说明       |
| ------------------------ | ---------- |
| `lv.EVENT.VALUE_CHANGED` | 标签页切换 |

完整示例

[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

列表控件，用于显示带图标的条目列表。

创建

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

常用方法

| 方法                         | 说明         |
| ---------------------------- | ------------ |
| `add_text(text)`             | 添加文本标题 |
| `add_button(icon, text)`     | 添加按钮条目 |
| `get_button_text(btn)`       | 获取按钮文本 |
| `set_button_text(btn, text)` | 设置按钮文本 |

事件

| 事件                | 说明     |
| ------------------- | -------- |
| `lv.EVENT.CLICKED`  | 点击条目 |
| `lv.EVENT.SELECTED` | 选中条目 |

完整示例

[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

菜单控件，用于多级导航界面。

创建

```python
menu = lv.menu(scr)
```

常用方法

| 方法                                   | 说明               |
| -------------------------------------- | ------------------ |
| `set_mode_header(mode)`                | 设置头部模式       |
| `set_mode_root_back_button(mode)`      | 设置返回按钮模式   |
| `clear_history()`                      | 清除导航历史       |
| `set_page(page)`                       | 设置当前显示页面   |
| `set_sidebar_page(page)`               | 设置侧边栏页面     |
| `set_load_page_event(trigger, target)` | 设置点击跳转       |
| `get_cur_main_page()`                  | 获取当前主页面     |
| `get_cur_sidebar_page()`               | 获取当前侧边栏页面 |

枚举

**头部模式 (`lv.MENU_HEADER`)**：`TOP_FIXED`, `TOP_UNFIXED`, `BOTTOM_FIXED`

**返回按钮 (`lv.MENU_ROOT_BACK_BTN`)**：`MENU_ROOT_BACK_BUTTON_DISABLED`, `MENU_ROOT_BACK_BUTTON_ENABLED`

事件

| 事件               | 说明       |
| ------------------ | ---------- |
| `lv.EVENT.CLICKED` | 点击菜单项 |

完整示例

[demo_menu.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_menu.py)

注意事项

`menu_page`、`menu_cont`、`menu_section` 是模块级工厂函数，与 `menu` 一样通过 `lv.menu_page(menu, title)` 调用。

---

### msgbox

消息框控件，用于显示提示信息。无参构造时为模态 (带遮罩)。

创建

```python
msgbox = lv.msgbox()               # 模态 (推荐)
msgbox = lv.msgbox(parent)         # 非模态 (指定父对象)
```

常用方法

| 方法                      | 说明             |
| ------------------------- | ---------------- |
| `add_title(text)`         | 添加标题         |
| `add_text(text)`          | 添加文本内容     |
| `add_footer_button(text)` | 添加底部按钮     |
| `add_close_button()`      | 添加关闭按钮 (✕) |
| `get_header()`            | 获取头部区域     |
| `get_footer()`            | 获取底部区域     |
| `get_content()`           | 获取内容区域     |
| `close()`                 | 关闭消息框       |
| `close_async()`           | 异步关闭消息框   |

事件

| 事件                     | 说明       |
| ------------------------ | ---------- |
| `lv.EVENT.CLICKED`       | 点击按钮   |
| `lv.EVENT.CLOSED`        | 关闭消息框 |
| `lv.EVENT.VALUE_CHANGED` | 按钮值改变 |

完整示例

[demo_msgbox.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_msgbox.py)

注意事项

`lv.msgbox()` 不传 parent 时，内部传 `NULL` 给 `lv_msgbox_create`，LVGL 会自动在 `lv_layer_top()` 上创建半透明遮罩 (backdrop)，实现模态效果。如果传入 parent 对象，则不会创建遮罩。

---

### led

LED 指示灯控件，用于显示状态。

创建

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

常用方法

| 方法                  | 说明             |
| --------------------- | ---------------- |
| `set_color(color)`    | 设置 LED 颜色    |
| `set_brightness(val)` | 设置亮度 (0-255) |
| `on()`                | 开启 (最大亮度)  |
| `off()`               | 关闭 (最小亮度)  |
| `toggle()`            | 切换             |
| `get_brightness()`    | 获取亮度         |
| `get_color()`         | 获取颜色         |

完整示例

[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

折线控件，用于绘制多段折线。

创建

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

常用方法

| 方法                 | 说明                      |
| -------------------- | ------------------------- |
| `set_points(points)` | 设置坐标点 (列表 of 元组) |
| `set_y_invert(True)` | Y 轴反转                  |
| `get_y_invert()`     | 获取 Y 反转状态           |
| `get_point_count()`  | 获取坐标点数量            |

完整示例

[demo_line.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_line.py)

注意事项

`set_points()` 接受 Python 列表 of `(x, y)` 元组。Line 控件必须调用 `set_points()` 设置坐标点才能显示，否则为空白。

---

### canvas

画布控件，用于逐像素绘制图形。

创建

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

常用方法

| 方法                        | 说明           |
| --------------------------- | -------------- |
| `set_buffer(buf, w, h, cf)` | 设置绘制缓冲区 |
| `set_px(x, y, color, opa)`  | 设置像素       |
| `get_px(x, y)`              | 获取像素       |
| `fill_bg(color, opa)`       | 填充背景       |
| `set_palette(index, color)` | 设置调色板     |
| `get_draw_buf()`            | 获取绘制缓冲区 |

完整示例

[demo_canvas.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_canvas.py)

注意事项

`set_buffer(buf, w, h, cf)` 的 `buf` 参数为内存地址整数（`uintptr_t`），使用 numpy 数组时传 `buf.ctypes.data`，不要传 ctypes 指针对象。

---

### scale

刻度尺控件，用于显示刻度标记。

创建

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

常用方法

| 方法                          | 说明             |
| ----------------------------- | ---------------- |
| `set_mode(mode)`              | 模式             |
| `set_total_tick_count(n)`     | 总刻度数         |
| `set_major_tick_every(n)`     | 主刻度间隔       |
| `set_range(min, max)`         | 设置范围         |
| `set_min_value(val)`          | 设置最小值       |
| `set_max_value(val)`          | 设置最大值       |
| `set_angle_range(angle)`      | 圆形刻度角度范围 |
| `set_rotation(angle)`         | 旋转偏移         |
| `set_label_show(True)`        | 显示标签         |
| `set_draw_ticks_on_top(True)` | 刻度绘制在顶部   |
| `get_mode()`                  | 获取模式         |
| `get_total_tick_count()`      | 获取总刻度数     |
| `get_min_value()`             | 获取最小值       |
| `get_max_value()`             | 获取最大值       |
| `get_angle_range()`           | 获取角度范围     |
| `get_rotation()`              | 获取旋转偏移     |

枚举

**刻度模式 (`lv.SCALE_MODE`)**：`HORIZONTAL_TOP`, `HORIZONTAL_BOTTOM`, `VERTICAL_LEFT`, `VERTICAL_RIGHT`, `ROUND_INNER`, `ROUND_OUTER`, `LAST`

事件

| 事件                     | 说明   |
| ------------------------ | ------ |
| `lv.EVENT.VALUE_CHANGED` | 值改变 |

完整示例

[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

数字输入框控件，用于精确数值调节。

创建

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

常用方法

| 方法                                | 说明             |
| ----------------------------------- | ---------------- |
| `set_value(value)`                  | 设置值           |
| `set_digit_format(digits, sep_pos)` | 位数, 小数点位置 |
| `set_step(step)`                    | 步进值           |
| `set_range(min, max)`               | 设置范围         |
| `set_min_value(val)`                | 设置最小值       |
| `set_max_value(val)`                | 设置最大值       |
| `set_rollover(True)`                | 循环             |
| `set_cursor_pos(pos)`               | 光标位置         |
| `set_digit_step_direction(dir)`     | 数字步进方向     |
| `get_value()`                       | 获取值           |
| `get_min_value()`                   | 获取最小值       |
| `get_max_value()`                   | 获取最大值       |
| `increment()`                       | 增加一步         |
| `decrement()`                       | 减少一步         |
| `step_next()`                       | 光标移到下一位   |
| `step_prev()`                       | 光标移到上一位   |

事件

| 事件                     | 说明   |
| ------------------------ | ------ |
| `lv.EVENT.VALUE_CHANGED` | 值改变 |

完整示例

[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

加载动画控件，用于显示等待状态。

创建

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

常用方法

| 方法                             | 说明               |
| -------------------------------- | ------------------ |
| `set_anim_params(period, angle)` | 周期(ms), 扫过角度 |
| `set_anim_duration(ms)`          | 设置动画周期       |
| `set_arc_sweep(angle)`           | 设置弧扫角度       |
| `get_anim_duration()`            | 获取动画周期       |
| `get_arc_sweep()`                | 获取弧扫角度       |

完整示例

[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

平铺视图控件，用于左右/上下滑动切换页面。

创建

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

常用方法

| 方法                                | 说明                           |
| ----------------------------------- | ------------------------------ |
| `add_tile(col, row, dir)`           | 添加 tile (列, 行, 可滑动方向) |
| `set_tile(tile, anim)`              | 滑动到指定 tile (是否动画)     |
| `set_tile_by_index(col, row, anim)` | 按索引滑动                     |
| `get_tile_active()`                 | 获取当前活动 tile              |

完整示例

[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

窗口控件，带标题栏和内容区域。

创建

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

常用方法

| 方法                      | 说明         |
| ------------------------- | ------------ |
| `add_title(text)`         | 添加标题     |
| `add_button(icon, width)` | 添加按钮     |
| `get_header()`            | 获取头部     |
| `get_content()`           | 获取内容区域 |

完整示例

[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

动画图片控件，用于播放帧动画。

创建

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

常用方法

| 方法                  | 说明                      |
| --------------------- | ------------------------- |
| `set_src(paths)`      | 设置图片路径列表          |
| `set_duration(ms)`    | 一个完整循环时间 (ms)     |
| `set_repeat_count(n)` | 重复次数 (255 = 无限循环) |
| `start()`             | 开始播放                  |
| `get_duration()`      | 获取循环时间              |
| `get_repeat_count()`  | 获取重复次数              |

完整示例

[demo_animimg.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_animimg.py)

---

## 动画 (anim_t)

动画对象，用于驱动控件属性随时间变化。

### 创建 (anim_t)

```python
a = lv.anim_t()
a.set_var(obj)                                   # 设置动画目标对象
a.set_exec_cb(obj, lambda var, v: var.set_value(v))  # 设置执行回调 fn(var, value)
a.set_values(0, 100)                             # 起始值, 结束值
a.set_duration(1000)                             # 持续时间 (ms)
a.set_repeat_count(lv.ANIM_REPEAT_INFINITE)      # 无限循环
a.start()                                        # 启动动画
```

### 常用方法 (anim_t)                         |

| `set_exec_cb(obj, callback)`      | 设置执行回调 `fn(var, value)`            |
| `set_values(start, end)`          | 设置起始/结束值                          |
| `set_duration(ms)`                | 正向持续时间                             |
| `set_reverse_duration(ms)`        | 反向持续时间                             |
| `set_delay(ms)`                   | 延迟启动                                 |
| `set_repeat_count(n)`             | 重复次数 (`ANIM_REPEAT_INFINITE` = 无限) |
| `set_repeat_delay(ms)`            | 重复间隔                                 |
| `set_early_apply(True)`           | 立即应用起始值                           |
| `set_completed_cb(obj, callback)` | 设置完成回调                             |
| `set_start_cb(obj, callback)`     | 设置开始回调                             |
| `start()`                         | 启动动画                                 |
| `delete()`                        | 删除动画                                 |

### 运动路径

| 方法                     | 说明     |
| ------------------------ | -------- |
| `set_path_linear()`      | 线性     |
| `set_path_ease_in()`     | 缓入     |
| `set_path_ease_out()`    | 缓出     |
| `set_path_ease_in_out()` | 缓入缓出 |
| `set_path_overshoot()`   | 过冲     |
| `set_path_bounce()`      | 弹跳     |
| `set_path_step()`        | 阶梯     |

### 常量

| 常量                      | 说明         |
| ------------------------- | ------------ |
| `lv.ANIM_REPEAT_INFINITE` | 无限循环标志 |

---

## 定时器 (timer_t)

定时器对象，用于周期性执行回调。

### 创建 (timer_t)

```python
def on_timer(timer):
    # 周期性执行的代码
    pass

timer = lv.timer_create(on_timer, 100)  # 每 100ms 调用一次
```

### 常用方法 (timer_t)    |

| `ready()`        | 标记定时器为就绪 |
| `pause()`        | 暂停定时器       |
| `resume()`       | 恢复定时器       |
| `is_valid()`     | 定时器是否有效   |
| `delete()`       | 删除定时器       |

---

## 显示 (display)

显示对象，用于管理屏幕分辨率和旋转。

### 创建 (display)

```python
disp = lv.display_create(800, 480)       # 创建 800x480 显示
disp = lv.display_get_default()          # 获取默认显示对象
```

### 常用方法 (display)     |

| `set_rotation(rotation)`      | 设置旋转       |
| `get_horizontal_resolution()` | 获取水平分辨率 |
| `get_vertical_resolution()`   | 获取垂直分辨率 |
| `flush_ready()`               | 通知刷新完成   |

### 枚举 (display)

**显示旋转 (`lv.DISPLAY_ROTATION`)**：`_0`, `_90`, `_180`, `_270`

---

## 输入设备 (indev)

输入设备对象，用于管理触摸屏、键盘等输入。

### 创建 (indev)

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

### 常用方法 (indev)

| 方法                             | 说明           |
| -------------------------------- | -------------- |
| `lv.indev_get_next(indev)`       | 获取下一个设备 |
| `lv.indev_get_type(indev)`       | 获取设备类型   |
| `lv.indev_set_type(indev, type)` | 设置设备类型   |
| `lv.indev_set_group(indev, grp)` | 设置输入分组   |

### 枚举 (indev)：`NONE`, `POINTER`, `KEYPAD`, `BUTTON`, `ENCODER`

**EVDEV 类型 (`lv.EVDEV_TYPE`)**：`REL`, `ABS`, `KEY`

---

## 分组 (group)

分组用于键盘/编码器导航，将多个控件组织在一起，通过方向键在控件间切换焦点。

### 使用方式

```python
# 创建分组
g = lv.group_create()
lv.group_set_default(g)

# 将输入设备绑定到分组
indev = lv.indev_create()
indev.set_type(lv.INDEV_TYPE.KEYPAD)
lv.indev_set_group(indev, g)

# 将控件加入分组
lv.group_add_obj(g, btn1)
lv.group_add_obj(g, btn2)
```

### 分组函数

| 函数                           | 说明             |
| ------------------------------ | ---------------- |
| `lv.group_create()`            | 创建分组         |
| `lv.group_delete(group)`       | 删除分组         |
| `lv.group_set_default(group)`  | 设置默认分组     |
| `lv.group_get_default()`       | 获取默认分组     |
| `lv.group_add_obj(group, obj)` | 将对象加入分组   |
| `lv.group_remove_obj(obj)`     | 将对象从分组移除 |
| `lv.group_focus_obj(obj)`      | 聚焦指定对象     |
| `lv.group_focus_next(group)`   | 聚焦下一个对象   |
| `lv.group_focus_prev(group)`   | 聚焦上一个对象   |
| `lv.group_set_wrap(group, en)` | 设置是否循环聚焦 |

---

## 事件与回调

### 注册事件回调

```python
def on_clicked(event):
    if event.code == lv.EVENT.CLICKED:
        print("Button clicked!")
        print("Target:", event.target)  # 触发事件的对象

btn.add_event_cb(lv.EVENT.CLICKED, on_clicked)
btn.on(lv.EVENT.CLICKED, on_clicked)    # 简写，等同于 add_event_cb
```

### event 对象

回调函数接收 `event` 对象，提供以下属性和方法：

| 属性/方法                 | 说明                                      |
| ------------------------- | ----------------------------------------- |
| `event.code`              | 事件码 (int，可与 `lv.EVENT.XXX` 比较)    |
| `event.target`            | 触发事件的对象 (Obj)                      |
| `event.current_target`    | 当前处理事件的对象 (事件冒泡路径上的对象) |
| `event.stop_bubbling()`   | 停止事件冒泡                              |
| `event.stop_processing()` | 停止当前对象的事件处理                    |
| `event.stop_trickling()`  | 停止向子对象传递事件                      |

> **向后兼容**: `Event` 对象支持 `== int` 比较（`event == lv.EVENT.CLICKED` 等效于 `event.code == lv.EVENT.CLICKED`），旧代码无需修改即可运行。

### 完整事件码 (`lv.EVENT`, 76 个)

| 事件                  | 说明         |
| --------------------- | ------------ |
| `ALL`                 | 所有事件     |
| `PRESSED`             | 按下         |
| `PRESSING`            | 持续按压     |
| `PRESS_LOST`          | 按压丢失     |
| `SHORT_CLICKED`       | 短点击       |
| `SINGLE_CLICKED`      | 单击         |
| `DOUBLE_CLICKED`      | 双击         |
| `TRIPLE_CLICKED`      | 三击         |
| `LONG_PRESSED`        | 长按         |
| `LONG_PRESSED_REPEAT` | 长按重复     |
| `CLICKED`             | 点击         |
| `RELEASED`            | 释放         |
| `SCROLL_BEGIN`        | 滚动开始     |
| `SCROLL_THROW_BEGIN`  | 惯性滚动开始 |
| `SCROLL_END`          | 滚动结束     |
| `SCROLL`              | 滚动         |
| `GESTURE`             | 手势         |
| `KEY`                 | 按键         |
| `ROTARY`              | 旋钮         |
| `FOCUSED`             | 获得焦点     |
| `DEFOCUSED`           | 失去焦点     |
| `LEAVE`               | 离开         |
| `HIT_TEST`            | 命中测试     |
| `INDEV_RESET`         | 输入设备重置 |
| `HOVER_OVER`          | 悬停经过     |
| `HOVER_STILL`         | 悬停静止     |
| `HOVER_LEAVE`         | 悬停离开     |
| `VALUE_CHANGED`       | 值改变       |
| `INSERT`              | 插入         |
| `REFRESH`             | 刷新         |
| `READY`               | 就绪         |
| `CANCEL`              | 取消         |
| `SCREEN_LOADED`       | 屏幕加载完成 |
| `SCREEN_LOAD_START`   | 屏幕开始加载 |
| `SCREEN_UNLOADED`     | 屏幕卸载完成 |
| `SCREEN_UNLOAD_START` | 屏幕开始卸载 |
| `SIZE_CHANGED`        | 尺寸改变     |
| `DRAW_TASK_ADDED`     | 绘制任务添加 |
| `CHILD_CHANGED`       | 子对象改变   |
| `CHILD_CREATED`       | 子对象创建   |
| `CHILD_DELETED`       | 子对象删除   |
| `SELECTED`            | 选中         |
| `CHECKED`             | 勾选         |

---

## 样式系统

样式通过 `set_style_*(value, selector)` 方法设置。`selector` 参数指定样式应用的目标，推荐使用 `lv.SELECTOR.DEFAULT` (默认状态 `LV_PART_MAIN | LV_STATE_DEFAULT`)，避免使用裸数字 `0`。

### 常用 selector 值

| 值                     | 说明                            |
| ---------------------- | ------------------------------- |
| `lv.SELECTOR.DEFAULT`  | `LV_PART_MAIN` + 默认状态 (= 0) |
| `lv.PART.MAIN`         | 主部分                          |
| `lv.PART.INDICATOR`    | 指示器部分 (Slider/Bar 的填充)  |
| `lv.PART.KNOB`         | 旋钮部分                        |
| `lv.PART.ITEMS`        | 项目部分                        |
| `lv.PART.CURSOR`       | 光标部分                        |
| `lv.PART.SELECTED`     | 选中部分                        |
| `lv.PART.SCROLLBAR`    | 滚动条部分                      |
| `lv.PART.CUSTOM_FIRST` | 自定义部分起始                  |
| `lv.PART.ANY`          | 任意部分                        |

> **提示**: 组合 Part + State 使用位或运算：`lv.PART.KNOB | lv.STATE.FOCUSED`

### 背景样式

```python
obj.set_style_bg_color(lv.color_make(255, 0, 0), lv.SELECTOR.DEFAULT)       # 背景颜色
obj.set_style_bg_opa(lv.OPA_50, lv.SELECTOR.DEFAULT)                 # 背景透明度
obj.set_style_bg_grad_color(lv.color_make(0, 0, 255), lv.SELECTOR.DEFAULT)   # 渐变终止颜色
obj.set_style_bg_grad_dir(lv.GRAD_DIR.VER, lv.SELECTOR.DEFAULT)  # 渐变方向
obj.set_style_bg_main_stop(0, lv.SELECTOR.DEFAULT)                       # 渐变起始位置 (0-255)
obj.set_style_bg_grad_stop(255, lv.SELECTOR.DEFAULT)                     # 渐变结束位置
obj.set_style_bg_main_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # 渐变起始透明度
obj.set_style_bg_grad_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # 渐变终止透明度
obj.set_style_bg_image_src(src, lv.SELECTOR.DEFAULT)                     # 背景图片
obj.set_style_bg_image_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)              # 背景图片透明度
obj.set_style_bg_image_recolor(color, lv.SELECTOR.DEFAULT)               # 背景图片重新着色
obj.set_style_bg_image_tiled(True, lv.SELECTOR.DEFAULT)                  # 背景图片平铺
```

### 边框样式

```python
obj.set_style_border_width(2, lv.SELECTOR.DEFAULT)                       # 边框宽度
obj.set_style_border_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT)       # 边框颜色
obj.set_style_border_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)             # 边框透明度
obj.set_style_border_side(lv.BORDER_SIDE.FULL, lv.SELECTOR.DEFAULT)  # 边框边
obj.set_style_border_post(True, lv.SELECTOR.DEFAULT)                     # 边框后绘制
```

### 圆角与阴影

```python
obj.set_style_radius(10, lv.SELECTOR.DEFAULT)                            # 圆角半径
obj.set_style_shadow_width(10, lv.SELECTOR.DEFAULT)                      # 阴影宽度
obj.set_style_shadow_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT)       # 阴影颜色
obj.set_style_shadow_offset_x(3, lv.SELECTOR.DEFAULT)                    # 阴影 X 偏移
obj.set_style_shadow_offset_y(3, lv.SELECTOR.DEFAULT)                    # 阴影 Y 偏移
obj.set_style_shadow_spread(2, lv.SELECTOR.DEFAULT)                      # 阴影扩散
obj.set_style_shadow_opa(lv.OPA_50, lv.SELECTOR.DEFAULT)              # 阴影透明度
```

### 模糊样式

```python
obj.set_style_blur_radius(r, lv.SELECTOR.DEFAULT)                        # 模糊半径
obj.set_style_blur_quality(lv.BLUR_QUALITY.AUTO, lv.SELECTOR.DEFAULT)    # 模糊质量
obj.set_style_blur_backdrop(True, lv.SELECTOR.DEFAULT)                   # 模糊背景
```

### 轮廓样式

```python
obj.set_style_outline_width(2, lv.SELECTOR.DEFAULT)                      # 轮廓宽度
obj.set_style_outline_color(lv.color_make(0, 128, 255), lv.SELECTOR.DEFAULT)  # 轮廓颜色
obj.set_style_outline_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)            # 轮廓透明度
obj.set_style_outline_pad(3, lv.SELECTOR.DEFAULT)                        # 轮廓内边距
```

### 文本样式

```python
obj.set_style_text_color(lv.color_make(255, 255, 255), lv.SELECTOR.DEFAULT)   # 文本颜色
obj.set_style_text_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # 文本透明度
obj.set_style_text_font(font_ptr, lv.SELECTOR.DEFAULT)                    # 文本字体
obj.set_style_text_letter_space(2, lv.SELECTOR.DEFAULT)                   # 字间距
obj.set_style_text_line_space(4, lv.SELECTOR.DEFAULT)                     # 行间距
obj.set_style_text_align(lv.TEXT_ALIGN.CENTER, lv.SELECTOR.DEFAULT)  # 文本对齐
obj.set_style_text_decor(lv.TEXT_DECOR.UNDERLINE, lv.SELECTOR.DEFAULT)  # 文本装饰
obj.set_style_text_outline_stroke_width(1, lv.SELECTOR.DEFAULT)           # 文本描边宽度
obj.set_style_text_outline_stroke_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT) # 描边颜色
```

### 内边距与外边距

```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)       # 行间距 (Flex/Grid)
obj.set_style_pad_column(5, lv.SELECTOR.DEFAULT)    # 列间距

# 简写 (padding)
obj.set_style_pad_all(10, lv.SELECTOR.DEFAULT)      # 四边相同
obj.set_style_pad_hor(10, lv.SELECTOR.DEFAULT)      # 左右相同
obj.set_style_pad_ver(10, lv.SELECTOR.DEFAULT)      # 上下相同
obj.set_style_pad_gap(5, lv.SELECTOR.DEFAULT)       # 行列间距相同

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)

# 简写 (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)
```

### 变换样式

```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 平移
```

### 其他样式

```python
obj.set_style_opa(lv.OPA_80, lv.SELECTOR.DEFAULT)              # 整体透明度
obj.set_style_opa_layered(lv.OPA_80, lv.SELECTOR.DEFAULT)      # 层叠透明度
obj.set_style_clip_corner(True, lv.SELECTOR.DEFAULT)               # 裁剪圆角
obj.set_style_blend_mode(lv.BLEND_MODE.NORMAL, lv.SELECTOR.DEFAULT)  # 混合模式
obj.set_style_anim_duration(300, lv.SELECTOR.DEFAULT)              # 动画持续时间
obj.set_style_base_dir(lv.BASE_DIR.LTR, lv.SELECTOR.DEFAULT)  # 文本方向
obj.set_style_bitmap_mask_src(src, lv.SELECTOR.DEFAULT)            # 位图遮罩
obj.set_style_color_filter_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)   # 颜色过滤透明度
obj.set_style_layout(lv.LAYOUT.FLEX, lv.SELECTOR.DEFAULT)         # 布局类型
obj.set_style_radial_offset(0, lv.SELECTOR.DEFAULT)               # 径向偏移
obj.set_style_recolor(color, lv.SELECTOR.DEFAULT)                 # 重新着色
obj.set_style_rotary_sensitivity(256, lv.SELECTOR.DEFAULT)        # 旋钮灵敏度
```

### 线与弧样式

```python
obj.set_style_line_width(2, lv.SELECTOR.DEFAULT)                   # 线宽
obj.set_style_line_color(lv.color_make(0, 0, 255), lv.SELECTOR.DEFAULT) # 线颜色
obj.set_style_line_rounded(True, lv.SELECTOR.DEFAULT)              # 线端圆角
obj.set_style_line_dash_width(10, lv.SELECTOR.DEFAULT)             # 虚线宽度
obj.set_style_line_dash_gap(5, lv.SELECTOR.DEFAULT)                # 虚线间隔

obj.set_style_arc_width(4, lv.SELECTOR.DEFAULT)                    # 弧宽
obj.set_style_arc_color(lv.color_make(255, 0, 0), lv.SELECTOR.DEFAULT)  # 弧颜色
obj.set_style_arc_rounded(True, lv.SELECTOR.DEFAULT)               # 弧端圆角
obj.set_style_arc_image_src(src, lv.SELECTOR.DEFAULT)              # 弧图片
```

### 尺寸约束样式

```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)           # 固定宽度
obj.set_style_height(50, lv.SELECTOR.DEFAULT)            # 固定高度
obj.set_style_size(100, lv.SELECTOR.DEFAULT)             # 固定尺寸 (宽=高)
```

---

## 布局 (Flex / Grid)

### Flex 布局

```python
# 父容器设置 Flex
container.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)  # 行 + 换行
container.set_flex_align(
    lv.FLEX_ALIGN.CENTER,       # 主轴对齐
    lv.FLEX_ALIGN.CENTER,       # 交叉轴对齐
    lv.FLEX_ALIGN.CENTER        # 行对齐
)

# 子项设置
child.set_flex_grow(1)  # 弹性增长
```

**Flex 流向 (`lv.FLEX_FLOW`)**：`ROW`, `COLUMN`, `ROW_WRAP`, `ROW_REVERSE`, `ROW_WRAP_REVERSE`, `COLUMN_WRAP`, `COLUMN_REVERSE`, `COLUMN_WRAP_REVERSE`

**Flex 对齐 (`lv.FLEX_ALIGN`)**：`START`, `END`, `CENTER`, `SPACE_EVENLY`, `SPACE_AROUND`, `SPACE_BETWEEN`

### Grid 布局

```python
container.set_grid_align(
    lv.GRID_ALIGN.CENTER,  # 列对齐
    lv.GRID_ALIGN.CENTER   # 行对齐
)

child.set_grid_cell(
    lv.GRID_ALIGN.CENTER,  # 列对齐
    0, 1,                                 # 列位置, 列跨度
    lv.GRID_ALIGN.CENTER,  # 行对齐
    0, 1                                  # 行位置, 行跨度
)
```

**Grid 对齐 (`lv.GRID_ALIGN`)**：`START`, `CENTER`, `END`, `STRETCH`, `SPACE_EVENLY`, `SPACE_AROUND`, `SPACE_BETWEEN`

**布局类型 (`lv.LAYOUT`)**：`NONE`, `FLEX`, `GRID`, `LAST`

---

## 滚动

```python
obj.set_scrollbar_mode(lv.SCROLLBAR_MODE.AUTO)
obj.set_scroll_dir(lv.DIR.VER)        # 限制滚动方向
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)               # 滚动偏移
obj.scroll_to(x, y, anim_en)                 # 滚动到位置
obj.scroll_to_view(anim_en)                  # 滚动到可见
obj.is_scrolling()                           # 是否正在滚动
obj.stop_scroll_anim()                       # 停止滚动动画

obj.get_scroll_x()                           # 获取水平滚动位置
obj.get_scroll_y()                           # 获取垂直滚动位置
obj.get_scroll_bottom()                      # 获取底部滚动距离
obj.get_scroll_top()                         # 获取顶部滚动距离
obj.get_scroll_left()                        # 获取左侧滚动距离
obj.get_scroll_right()                       # 获取右侧滚动距离
```

---

## Flags-and-states

### 对象标志 (`lv.OBJ_FLAG`)

```python
obj.add_flag(lv.OBJ_FLAG.HIDDEN)        # 隐藏
obj.remove_flag(lv.OBJ_FLAG.HIDDEN)     # 取消隐藏
obj.has_flag(lv.OBJ_FLAG.CLICKABLE)     # 检查标志
obj.has_flag_any(lv.OBJ_FLAG.CLICKABLE) # 检查是否包含任一标志
obj.set_flag(lv.OBJ_FLAG.CLICKABLE, True) # 设置标志开/关
```

> **位运算支持**: `add_flag`/`remove_flag` 等方法已通过 `_wrapper.py` 补丁支持位或运算，如 `obj.add_flag(lv.OBJ_FLAG.CLICKABLE | lv.OBJ_FLAG.CHECKABLE)`。

| 常用标志                | 说明               |
| ----------------------- | ------------------ |
| `HIDDEN`                | 隐藏               |
| `CLICKABLE`             | 可点击             |
| `CLICK_FOCUSABLE`       | 点击可聚焦         |
| `CHECKABLE`             | 可选中             |
| `SCROLLABLE`            | 可滚动             |
| `SCROLL_ELASTIC`        | 弹性滚动           |
| `SCROLL_MOMENTUM`       | 惯性滚动           |
| `SCROLL_ONE`            | 一次只滚动一个子项 |
| `SCROLL_CHAIN_HOR`      | 水平滚动链         |
| `SCROLL_CHAIN_VER`      | 垂直滚动链         |
| `SCROLL_ON_FOCUS`       | 聚焦时滚动         |
| `SCROLL_WITH_ARROW`     | 方向键滚动         |
| `SNAPPABLE`             | 可对齐到滚动位置   |
| `PRESS_LOCK`            | 按压锁定           |
| `EVENT_BUBBLE`          | 事件冒泡           |
| `GESTURE_BUBBLE`        | 手势冒泡           |
| `ADV_HITTEST`           | 高级命中测试       |
| `IGNORE_LAYOUT`         | 忽略布局           |
| `FLOATING`              | 浮动 (不参与布局)  |
| `SEND_DRAW_TASK_EVENTS` | 发送绘制任务事件   |
| `OVERFLOW_VISIBLE`      | 溢出可见           |
| `EVENT_TRICKLE`         | 事件渗透           |
| `LAYOUT_1` ~ `LAYOUT_4` | 布局自定义标志     |
| `USER_1` ~ `USER_4`     | 用户自定义标志     |

### 对象状态 (`lv.STATE`)

```python
obj.add_state(lv.STATE.CHECKED)             # 添加状态
obj.remove_state(lv.STATE.CHECKED)          # 移除状态
obj.get_state()                             # 获取状态
obj.has_state(lv.STATE.CHECKED)             # 检查状态
```

| 常用状态            | 说明           |
| ------------------- | -------------- |
| `DEFAULT`           | 默认           |
| `ALT`               | 替代           |
| `CHECKED`           | 选中           |
| `FOCUSED`           | 聚焦           |
| `FOCUS_KEY`         | 按键聚焦       |
| `EDITED`            | 编辑           |
| `HOVERED`           | 悬停           |
| `PRESSED`           | 按压           |
| `SCROLLED`          | 滚动           |
| `DISABLED`          | 禁用           |
| `USER_1` ~ `USER_4` | 用户自定义状态 |
| `ANY`               | 任意状态       |

---

## 屏幕管理

```python
scr = lv.screen_active()          # 获取当前活动屏幕
lv.screen_load(scr)               # 加载屏幕 (无动画)

# 创建新屏幕 (使用 obj 无参构造)
scr2 = lv.obj()
lv.screen_load(scr2)
```

**屏幕加载动画 (`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`

---

## 枚举参考

### 对齐 (`lv.ALIGN`)

`DEFAULT`, `TOP_LEFT`, `TOP_MID`, `TOP_RIGHT`, `BOTTOM_LEFT`, `BOTTOM_MID`, `BOTTOM_RIGHT`, `LEFT_MID`, `RIGHT_MID`, `CENTER`, 以及 `OUT_*` 外侧对齐变体 (`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 个。

### 方向 (`lv.DIR`)

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

### 文本对齐 (`lv.TEXT_ALIGN`)

`AUTO`, `LEFT`, `CENTER`, `RIGHT`

### 文本装饰 (`lv.TEXT_DECOR`)

`NONE`, `UNDERLINE`, `STRIKETHROUGH`

### 颜色格式 (`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` 等。共 45 个。

### 调色板 (`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`

### 混合模式 (`lv.BLEND_MODE`)

`NORMAL`, `ADDITIVE`, `SUBTRACTIVE`, `MULTIPLY`, `DIFFERENCE`

### 滚动条模式 (`lv.SCROLLBAR_MODE`)

`OFF`, `ON`, `ACTIVE`, `AUTO`

### 边框边 (`lv.BORDER_SIDE`)

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

### 按键 (`lv.KEY`)

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

### 渐变方向 (`lv.GRAD_DIR`)

`NONE`, `VER`, `HOR`, `LINEAR`, `RADIAL`, `CONICAL`

### 渐变扩展 (`lv.GRAD_EXTEND`)

`PAD`, `REPEAT`, `REFLECT`

### 模糊质量 (`lv.BLUR_QUALITY`)

`AUTO`, `SPEED`, `PRECISION`

### 文本方向 (`lv.BASE_DIR`)

`LTR`, `RTL`, `AUTO`, `NEUTRAL`, `WEAK`

### 输入设备类型 (`lv.INDEV_TYPE`)

`NONE`, `POINTER`, `KEYPAD`, `BUTTON`, `ENCODER`

### 输入设备模式 (`lv.INDEV_MODE`)

`NONE`, `TIMER`, `EVENT`

### 显示渲染模式 (`lv.DISPLAY_RENDER`)

`PARTIAL`, `DIRECT`, `FULL`

### 控件部分 (`lv.PART`)

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

### 覆盖结果 (`lv.COVER`)

`COVER`, `NOT_COVER`, `MASKED`

### 符号常量

| 常量                   | 说明     | 常量                      | 说明   |
| ---------------------- | -------- | ------------------------- | ------ |
| `lv.SYMBOL_BULLET`     | 项目符号 | `lv.SYMBOL_AUDIO`         | 音频   |
| `lv.SYMBOL_VIDEO`      | 视频     | `lv.SYMBOL_LIST`          | 列表   |
| `lv.SYMBOL_OK`         | 确认     | `lv.SYMBOL_CLOSE`         | 关闭   |
| `lv.SYMBOL_POWER`      | 电源     | `lv.SYMBOL_SETTINGS`      | 设置   |
| `lv.SYMBOL_HOME`       | 主页     | `lv.SYMBOL_DOWNLOAD`      | 下载   |
| `lv.SYMBOL_DRIVE`      | 驱动器   | `lv.SYMBOL_REFRESH`       | 刷新   |
| `lv.SYMBOL_MUTE`       | 静音     | `lv.SYMBOL_VOLUME_MID`    | 音量中 |
| `lv.SYMBOL_VOLUME_MAX` | 音量最大 | `lv.SYMBOL_IMAGE`         | 图片   |
| `lv.SYMBOL_TINT`       | 色调     | `lv.SYMBOL_PREV`          | 上一曲 |
| `lv.SYMBOL_PLAY`       | 播放     | `lv.SYMBOL_PAUSE`         | 暂停   |
| `lv.SYMBOL_STOP`       | 停止     | `lv.SYMBOL_NEXT`          | 下一曲 |
| `lv.SYMBOL_EJECT`      | 弹出     | `lv.SYMBOL_LEFT`          | 左     |
| `lv.SYMBOL_RIGHT`      | 右       | `lv.SYMBOL_PLUS`          | 加     |
| `lv.SYMBOL_MINUS`      | 减       | `lv.SYMBOL_EYE_OPEN`      | 睁眼   |
| `lv.SYMBOL_EYE_CLOSE`  | 闭眼     | `lv.SYMBOL_WARNING`       | 警告   |
| `lv.SYMBOL_SHUFFLE`    | 随机     | `lv.SYMBOL_UP`            | 上     |
| `lv.SYMBOL_DOWN`       | 下       | `lv.SYMBOL_LOOP`          | 循环   |
| `lv.SYMBOL_DIRECTORY`  | 目录     | `lv.SYMBOL_UPLOAD`        | 上传   |
| `lv.SYMBOL_CALL`       | 呼叫     | `lv.SYMBOL_CUT`           | 剪切   |
| `lv.SYMBOL_COPY`       | 复制     | `lv.SYMBOL_SAVE`          | 保存   |
| `lv.SYMBOL_BARS`       | 柱状图   | `lv.SYMBOL_ENVELOPE`      | 信封   |
| `lv.SYMBOL_CHARGE`     | 充电     | `lv.SYMBOL_PASTE`         | 粘贴   |
| `lv.SYMBOL_BELL`       | 铃铛     | `lv.SYMBOL_KEYBOARD`      | 键盘   |
| `lv.SYMBOL_GPS`        | GPS      | `lv.SYMBOL_FILE`          | 文件   |
| `lv.SYMBOL_WIFI`       | WiFi     | `lv.SYMBOL_BATTERY_FULL`  | 满电   |
| `lv.SYMBOL_BATTERY_3`  | 电量3    | `lv.SYMBOL_BATTERY_2`     | 电量2  |
| `lv.SYMBOL_BATTERY_1`  | 电量1    | `lv.SYMBOL_BATTERY_EMPTY` | 空电   |
| `lv.SYMBOL_USB`        | USB      | `lv.SYMBOL_BLUETOOTH`     | 蓝牙   |
| `lv.SYMBOL_TRASH`      | 回收站   | `lv.SYMBOL_EDIT`          | 编辑   |
| `lv.SYMBOL_BACKSPACE`  | 退格     | `lv.SYMBOL_SD_CARD`       | SD 卡  |

---

## 完整示例

| 示例          | 说明                                  | 源码                                                                                                                                                        |
| ------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 基础控件      | 按钮/复选框/滑块/进度条/弧形/开关/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)           |
| 图片加载      | PNG/BMP 加载、旋转、缩放              | [demo_image.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_image.py)                 |
| 样式定制      | 颜色/圆角/阴影/渐变/模糊              | [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 布局     | 行/列/换行/对齐                       | [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 中文 | 加载 TTF 字体显示中文                 | [demo_chinese.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_chinese.py)             |
| 动画图片      | animimg 帧动画                        | [demo_animimg.py](https://github.com/kendryte/k230_linux_sdk/tree/dev/buildroot-overlay/package/python-k230/py_demo/lvgl/basic/demo_animimg.py)             |
| 仪表盘        | anim_t 驱动弧形动画 / timer 定时刷新  | [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 字体支持

LVGL 内置的 Montserrat 字体仅包含拉丁字符。要显示中文、日文、韩文等 CJK 字符，需通过 FreeType 加载 TTF/OTF 字体。

### 加载字体

```python
# 创建 FreeType 字体 (返回 lv.font 对象)
font = lv.freetype_font_create(
    "/usr/lib/fonts/SourceHanSansSC-Normal-Min.ttf",  # 字体文件路径
    lv.FREETYPE_RENDER.BITMAP,                     # 渲染模式
    24,                                                  # 字号 (px)
    lv.FREETYPE_STYLE.NORMAL,                      # 样式
)
```

### 使用字体

```python
label = lv.label(scr)
label.set_style_text_font(font, lv.SELECTOR.DEFAULT)   # 设置字体 (SELECTOR.DEFAULT = 默认状态)
label.set_text("你好，世界！")
```

### 释放字体

字体对象在 Python GC 回收时自动释放，也可手动释放：

```python
lv.freetype_font_delete(font)
```

### 渲染模式 (`lv.FREETYPE_RENDER`)

| 模式      | 说明                                  |
| --------- | ------------------------------------- |
| `BITMAP`  | 位图渲染 (推荐，性能好)               |
| `OUTLINE` | 矢量轮廓渲染 (支持任意缩放，性能较低) |

### 字体样式 (`lv.FREETYPE_STYLE`)

| 样式     | 说明 |
| -------- | ---- |
| `NORMAL` | 正常 |
| `ITALIC` | 斜体 |
| `BOLD`   | 粗体 |

### font 类

```python
font = lv.freetype_font_create(...)
font.is_valid()   # 检查字体是否有效
```

完整示例

> 完整源码: [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)

### 注意事项

- **字体文件**: K230 设备预装 `SourceHanSansSC-Normal-Min.ttf`（思源黑体精简版）于 `/usr/lib/fonts/`。精简版仅包含常用汉字，部分特殊符号（如 `°`、`℃`）可能缺失，可用中文替代（如"度"）。
- **性能**: FreeType 字体首次渲染某个字符时需要光栅化，后续使用缓存。`BITMAP` 模式比 `OUTLINE` 模式性能更好。
- **字号**: 每个字号需创建独立的字体对象。如需 16px 和 24px，需调用两次 `freetype_font_create`。
- **生命周期**: 字体对象由 Python GC 管理。确保字体对象在 label 使用期间不被回收。

---

## 已知限制

以下功能因 C API 参数/返回类型限制，**未在 Python 绑定中暴露**：

| 类别          | 未绑定功能                               | 原因                          |
| ------------- | ---------------------------------------- | ----------------------------- |
| 样式对象      | `lv_style_*`                             | 涉及 `lv_style_t*` 结构体操作 |
| 事件发送      | `lv_event_send`, `lv_event_get_*`        | 涉及 `lv_event_t*` 参数       |
| 内存/字符串   | `lv_malloc`, `lv_memcpy`, `lv_strdup` 等 | 手动跳过规则                  |
| 日志          | `lv_log`, `lv_log_register_print_cb`     | 手动跳过规则                  |
| 按钮/控件矩阵 | `lv_buttonmatrix_*`                      | 涉及复杂 C 数组/回调参数      |

> **注意**: 动画 (`anim_t`)、定时器 (`timer_t`)、分组 (`group_*`)、输入设备 (`indev_*`)、显示 (`display_*`) 已在本次更新中绑定暴露。

**统计**：

| 统计项                                                        | 数量 |
| ------------------------------------------------------------- | ---- |
| `.def()` 绑定 (方法+函数，含重载)                             | 902  |
| └ 模块级独立函数 `m.def()`                                    | 78   |
| └ Obj 类方法 `obj_cls.def()` (含 99 个 `_widget_method` 分派) | 786+ |
| 去重后唯一方法名                                              | 881  |
| 枚举类 `py::enum_`                                            | 96   |
| 枚举成员值 `.value()`                                         | 651  |
| 模块常量 `m.attr()` (SYMBOL/OPA/ANIM)                         | 651+ |
| 类 `py::class_`                                               | 8    |
| 控件工厂函数                                                  | 26   |

---

> 文档生成时间: 2026-07-28
>
> 基于 `lvgl_pybind_generated.cpp` 自动分析 + `_wrapper.py` 手动补充生成