# gui

**Repository Path**: oneos-ability/gui

## Basic Information

- **Project Name**: gui
- **Description**: 基于lvgl7.9和lvgl8.2开发的轻量级GUI框架，已适配OneOS，包括硬件加速功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-03-19
- **Last Updated**: 2024-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### 前言

轻量级`GUI`框架基于`LVGL`移植开发，针对图形化开发工具的设计，以模块化的方式，解决物联网操作系统在微控制器下图形界面资源占用过大、源码不可见、图形界面库不统一、使用难度较大的痛点。

主要功能如下：

1. 核心部件，如：按钮、图表、滑杆、图片、复选框、下拉列表、标签、滚轮、开关、线、文本框、弧、进度条等。
2. 对象类型的基本属性：位置、尺寸、家长、样式、事件处理程序等等
3. 触发事件机制：当被点击、滚动、数值改变、重新绘制等时，
4. 动态创建和删除对象
5. 颜色模块：处理所有与颜色相关的功能，如颜色深度、颜色深度之间的转换、混合颜色等
6. 图层用于多个对象之间的显示层级关系
7. 执行动画的创建、删除、播放、暂停、停止等，管理动画的轨迹、速度、时间等。
8. 具有抗锯齿、不透明度、平滑滚动的高级图形
9. 具有类似 `CSS` 样式的完全可定制的图形元素
10. 支持`bmp/png/jpg`图片格式
11. 支持使用点阵及`TTF`矢量字库
12. 支持多国语言，自带中英文
13. 多输入设备支持（如触摸板、鼠标、键盘、编码器等）
14. 支持本地模拟仿真

### 配置

此份说明文档主要阐明如何高效使用`menuconfig`对轻量级框架进行快速使用和配置。

```
(Top) → Components→ GUI
(lcd) GUI display dev name
(touch) GUI input dev name
[*] Enable LVGL  --->
```

`touch`和`lcd`是`GUI`的输入输出设备，选中`Enable LVGL`即可使能`LVGL`，目前支持的版本为`LVGL7.9`和`LVGL8.2`。

```
    LVGL (Enable lvgl 8.2)  --->
    LVGL basic menu  --->
    Widget usage  --->
    Extra Widgets  --->
    Themes  --->
    Layouts  --->
    Text Settings  --->
    Font usage  --->
    LVGL FileSystem  --->
    LVGL Log  --->
    LVGL Asserts  --->
    Third party Lib  --->
    Extra  --->
[ ] Enable LVGL examples  ----
[*] Enable LVGL Demo  --->
```

以上是适配支持的`LVGL`主要`menuconfig`配置。从上到下一一解释。

1. `LVGL basic menu`是`LVGL`最基本的配置，也是最重要的配置
2. `Widget usage`是对基础控件的支持与使能
3. `Extra Widgets`是对额外的高级控件的支持与使能
4. `Themes`是自带的一些主题
5. `Layouts`布局
6. `Text Settings`文本编码设置
7. `Font usage`字体选择
8. `LVGL FileSystem`文件系统支持
9. `LVGL Log`信息打印辅助开发
10. `LVGL Asserts`断言
11. `Third party Lib`第三方库
12. `Extra`其它功能
13. `Enable LVGL examples`一些简单的示例
14. `Enable LVGL Demo`一些复杂的示例



#### LVGL basic menu

```
(120) LVGL buff lines
(20) LVGL display refresh period(ms)
(30) Input device read period(ms)
(10) GUI task priority
(4096) GUI task stack size
(5) GUI task msleep
[ ] Enable LVGL two buff
[ ] Enable CPU usage and FPS count Show
[ ] Show the used memory and the memory fragmentation
[ ] LVGL minimal configuration.
[*] Enable graphics acceleration
[*] Enable complex draw engine
```

1. `LVGL`的单绘制缓冲区的行数
2. 默认显示刷新周期，`LVGL`将在此期间重新绘制更改的区域
3. 输入设备读取周期
4. `GUI`任务的优先级设置
5. `GUI`任务的栈大小设置
6. `GUI`任务的默认睡眠时间
7. 使能`LVGL`双绘制缓冲区
8. 显示`CPU`使用率和`FPS`计数显示
9. 显示已用内存和内存碎片
10. `LVGL`最小化配置，一般用于硬件资源很小的情况
11. 使能硬件加速
12. 使能复杂绘图引擎

#### widget usage

支持了很多控件，可以自己选择是否需要，默认全部选中

#### extra widgets

支持了很多高级控件，可以自己选择是否需要，默认全部选中

#### theme

支持的主题，是对象的默认样式。创建对象时，将自动应用来自主题的样式。

#### layouts

```
[*] A layout similar to Flexbox in CSS.
[*] A layout similar to Grid in CSS
```

支持`flex`弹性布局和`grid`网格布局。

#### text settings

```
(X) UTF8
( ) ASCII
```

为字符串选择字符编码。`IDE`或编辑器应具有相同的字符编码。

#### font usage

选择支持的字体。

#### filesystem

```
-*- LVGL using filesystem
        Select mount device (SD/TF Card)  --->
```

通过此配置，关联组件中的文件系统。

#### log

```
( ) TRACE
( ) INFO
(X) WARNING
( ) ERROR
( ) USER LOG
( ) NO LOG
```

`LVGL`的`log`日志，支持以上6个级别，级别越高，打印信息更多。

#### asserts

```
[*] Check if the parameter is NULL. (fast)
[*] Checks if the memory is successfully allocated or no. (fast)
[ ] Check if the styles are properly initialized. (fast)
[ ] Check the integrity of `lv_mem` after critical operations. (Slow)
[ ] Check NULL, the object's type and existence. (Slow).
```

断言机制，分别在于：

1. 检查参数是否为`NULL`
2. 检查内存是否已成功分配
3. 检查样式是否正确初始化
4. 关键操作后检查`lv_mem`的完整性
5. 检查`NULL`，对象的类型和存在性

#### third party lib

```
[ ] Enable LVGL GIF
[ ] Enable LVGL PNG
[ ] Enable LVGL JPG
[ ] Enable LVGL BMP
[ ] Enable LVGL QRCODE
```

支持的第三方库

#### examples and demo

选中后，选择对应的示例，供开发者运行体验。

`demo`选中后，编译运行后将直接运行该`demo`。`example`选中后，将会添加到`shell`命令中去，需要开发者，自己在`shell`中调用该命令，`example`命令以`ex_`开头。



### 注意事项

使用`LV_CONF_MINIMAL`作为`LVGL`最小化配置时，需要注意首先取消使能`LVGL`，然后保存配置后，再次使能LVGL，然后再选中`LVGL minimal configuration`。

```
(lcd) GUI display dev name
(touch) GUI input dev name
[ ] Enable LVGL  --->
```

```
Components → GUI→ Enable LVGL→ LVGL basic menu
(20) LVGL display refresh period(ms)
(30) Input device read period(ms)
(10) GUI task priority
(4096) GUI task stack size
(5) GUI task msleep
[ ] Enable LVGL two buff
[ ] Enable CPU usage and FPS count Show
[ ] Show the used memory and the memory fragmentation
[*] LVGL minimal configuration.
```



在使用`stm32f469-st-disco`来测试`benchmark`测试帧率时，通过配置选中该`demo`：

```
Components → GU→ Enable LVGL→ Enable LVGL Demo
(1) Enable LVGL demo benchmark
(0) Enable LVGL demo music
(0) Enable LVGL demo keypad and encoder
(0) Enable LVGL demo stress
(0) Enable LVGL demo widgets
```

需要注意的是：

```
(120) LVGL buff lines
(20) LVGL display refresh period(ms)
(30) Input device read period(ms)
(10) GUI task priority
(4096) GUI task stack size
(5) GUI task msleep
[ ] Enable LVGL two buff
[ ] Enable CPU usage and FPS count Show
[ ] Show the used memory and the memory fragmentation
[ ] LVGL minimal configuration.
[*] Enable graphics acceleration
[*] Enable complex draw engine
```

1. 使能图形加速`Enable graphics acceleration`，该MCU具有专门处理图形图像的硬件，比如 stm32 的 DMA2D。
2. `LVGL display refresh period`，刷新周期选择`20ms`
3. 绘制缓冲区大小，选择`120`行，不选择双缓冲区，这是在有限条件下的折中
4. 不要选择`Enable CPU usage and FPS count Show`、`Show the used memory and the memory fragmentation`、`LVGL minimal configuration`
5. 优化级别选择`-O2`