点阵屏UI开发工具及应用说明
点阵屏UI开发工具及应用说明
珠海市杰理科技股份有限公司
Zhuhai Jieli Technologyco.,LTD
版权所有，未经许可，禁止外传
版权所有，侵权必究 1
地址：珠海市香洲区南屏镇科兴路333号 邮编：519015
电话：0756-6313088 传真：0756-6313081
网站：www.zh-jieli.com
修改记录
| 版本 | 更新日期 | 描述 |
|---|---|---|
| V1.0 | 2021/03/7 | 撰写工具以应用说明文档 |
版权所有，侵权必究 2
目录
1.引 言..............................................................................................................................................................................4
1.1.编写目的............................................................................................................................................................ 4
1.2.参考资料............................................................................................................................................................ 4
1.3.术语和缩写词.....................................................................................................................................................4
2. UI编辑工具简介及使用................................................................................................................................................ 4
2.1. UI编辑工具介绍.................................................................................................................................................4
2.2. UI编辑工具使用.................................................................................................................................................6
3. UI资源生成工具............................................................................................................................................................ 9
4. UI资源升级工具.......................................................................................................................................................... 10
4.1.工具界面.......................................................................................................................................................... 10
4.2.使用说明.......................................................................................................................................................... 10
5. UI框架..........................................................................................................................................................................11
5.1. UI 工具链......................................................................................................................................................... 11
5.2. UI 绘制过程..................................................................................................................................................... 11
6.应用程序...................................................................................................................................................................... 12
6.1.添加屏驱动....................................................................................................................................................... 12
6.2.注册回调函数模板........................................................................................................................................... 13
6.3.消息传递流程................................................................................................................................................... 16
6.3.1.按键消息的传递过程......................................................................................................................... 16
6.3.2.触摸消息的传递过程......................................................................................................................... 18
6.3.3. APP事件消息的传递过程.................................................................................................................. 18
7. UI API接口.................................................................................................................................................................. 19
7.1. UI API控件接口............................................................................................................................................... 19
7.2.文本控件接口...................................................................................................................................................20
7.3.图片控件接口...................................................................................................................................................21
7.4.时间控件接口...................................................................................................................................................22
7.5.电池控件接口...................................................................................................................................................22
7.6.表格控件接口...................................................................................................................................................22
7.7.滑动条控件接口............................................................................................................................................... 23
7.8.数字控件接口...................................................................................................................................................23
7.9.圆环控件接口...................................................................................................................................................24
7.10.多圆环进度条控件接口（最多三个）.......................................................................................................... 24
版权所有，侵权必究 3
1. 引 言
1.1.编写目的
该文档主要介绍了点阵屏UI开发过程中使用到的工具以及整体的UI框架、应用代码流程。
1.2.参考资料
[ 1]
1.3.术语和缩写词
| 缩写和术语 | 解 释 |
|---|---|
2. UI编辑工具简介及使用
2.1. UI编辑工具介绍
该工具位于 “XXX\SDK\cpu\br23\tools\UI 工程\UITools”中，也可以通过UITools 同级目录中的“ui_ 128_ 64JL02\模式界面\step1-打开UI绘图工具.bat”批处理打开编辑工具。
UI开发界面框架如图： （目前的芯片只支持单图层，所以每个页面只能建立一个图层。 ）
版权所有，侵权必究 4
地址：珠海市香洲区南屏镇科兴路333号 邮编：519015
电话：0756-6313088 传真：0756-6313081
网站：www.zh-jieli.com
UI编辑工具的主编辑界面如下图，主编辑界面的相关参数以及具体各个控件的详细介绍请看“UI布局工具使用说明”文档。
版权所有，侵权必究 5
2.2. UI编辑工具使用
以下简单介绍几种常用控件元素的添加以及应用。
（1）文字控件：添加不存在的文本。
版权所有，侵权必究 6
对于在垂直列表中的文字控件，当高亮颜色设置为aaa555，选项被选中的话就会形成高亮反显的效果，清显示是555aaa；例如在点阵屏中，EQ模式按键选中“自然”的时候，就会形成白色高亮背景的效果。而对于普通文字控件来说，可以不设置背景色。
版权所有，侵权必究 7
（2）图片控件：添加不存在的图片时，注意添加的图片必须是BMP格式的，并且位深度为 1；单色图片背景色选择555aaa是清显示，其他值表示显示；另外在编辑界面拉小图片控件时，虽然在编辑界面上显示图标变小了，不过实际显示还是按照图片的分辨率大小来显示。
例如：拉小“播放”图标后，实际上是按照图片的分辨率来显示的。
以下是图片控件调用的相关接口。
版权所有，侵权必究 8
（3）电量控件：电量图标需递增添加进去。
主要界面编辑好后点击保存，UI信息会默认保存在资源文件“SmallColorTFT.json”中。
3. UI资源生成工具
功能根据所需设置，然后点击生成资源文件即可。如有新添加的控件，资源文件生成后，需要把相应的控件ID号（在ename.h可查看）添加进头文件style_jl02 .h（以点阵屏为例）中。
版权所有，侵权必究 9
4. UI资源升级工具
4.1.工具界面
4.2.使用说明
（1）关闭UI工程，备份源文件。
若UI编辑工具处于打开状态下，首先保存工程、关闭UI编辑工具，然后将UI工程的源文件*.json 备份一下。
例如：将工程源文件dial.json改名为dial_bak.json。
（2）设置好相应的文件路径
由于提前备份了工程源文件，源工程文件可以直接选择备份文件dial_bak.json，另存为工程则选择原来的工程文件dial.json，然后控件路径选择控件模板所在的路径，默认在“UI工程/UITools/control”，如下图所示：
（3）转换升级
路径参数设置好后，点击转换升级就可以了。
版权所有，侵权必究 10
5. UI框架
5.1. UI 工具链
5.2. UI 绘制过程
ui 内核会解析上述UI工具链所生成的sty文件，生成控件树，并依次根据控件的属性将控件显示出来。
版权所有，侵权必究 11
6.应用程序
6.1.添加屏驱动
（1）在板卡里面添加宏用于控制是否使用该驱动代码（以点阵屏驱动为例），并将驱动工程放在目录 cpu/br23/ui_driver/lcd_spi 中。
版权所有，侵权必究 12
（2）注册显示屏驱动信息，根据显示屏的规格参数修改相关参数即可。
（3）程序一开始运行的时候会调用UI_INIT(&ui_cfg_data)去创建ui线程，在线程中ui_framework_init()去调用已注册的驱动函数进行初始化。
6.2.注册回调函数模板
该模板适用于所有控件，包括页面、 图层、布局。
（1）页面、 图层、布局注册回调函数模板：
当切换/显示某一页面/图层/布局时，xxx_onchange会收到ON_CHANGE_INIT消息进行控件创建，可在此处初始化相关变量。 当一个从图层切换到另一个图层时，会进行控件的销毁。
版权所有，侵权必究 13
相关事件类型枚举：
//onchange事件
enum element_change_event {
ON_CHANGE_INIT_PROBE,
ON_CHANGE_INIT, //创建
ON_CHANGE_TRY_OPEN_DC,
ON_CHANGE_FIRST_SHOW, //自创建以来首次显示
ON_CHANGE_SHOW_PROBE, //显示前
ON_CHANGE_SHOW, //显示、重绘
ON_CHANGE_SHOW_POST, //显示后
ON_CHANGE_HIDE, //隐藏
ON_CHANGE_HIGHLIGHT, //高亮显示
ON_CHANGE_RELEASE_PROBE, //销毁前
ON_CHANGE_RELEASE, //销毁
ON_CHANGE_ANIMATION_END, //动画播放完毕（暂时不用）
ON_CHANGE_SHOW_COMPLETED, //显示完成};
（2）按键注册回调函数模板：
注意：在点阵屏SDK 中按键没有双击类型。
版权所有，侵权必究 14
（3）触摸事件注册回调函数模板：
版权所有，侵权必究 15
6.3.消息传递流程
按键驱动或触摸驱动将消息传递给ui 内核，ui 内核对消息进行分发，具体的消息传递过程如下：
6.3.1.按键消息的传递过程
若不存在焦点控件或者焦点控件被隐藏，则遍历该页面的所有可见控件，消息按照父控件到子控件的顺序递归传递，直到某个控件的onkey 响应函数返回true，此时消息终止传递，该控件被标记为焦点控件。若存在焦点控件,则消息直接传递给焦点控件。
如上图所示，ui 内核按照图层->布局->控件 1- >控件1子控件->控件2- >控件2子控件的顺序依次遍历所有控件的onkey响应函数，onkey响应函数返回true 时终止传递。下面是具体的消息传递流程：
版权所有，侵权必究 16
版权所有，侵权必究 17
6.3.2.触摸消息的传递过程
当点击触摸屏时，ui收到触摸消息，按照父控件到子控件的顺序依次遍历坐标所落在区域内的可见控件，直到某个控件的ontouch 响应函数返回true，此时消息终止传递，控件被重新标记为焦点控件。确定焦点控件后，在触摸屏上滑动所产生的ELM_EVENT_TOUCH_MOVE事件只会传递给焦点控件。
如上图所示，触摸按下时的坐标落在图层、布局、控件1、 控件1子控件的区域，则ui 内核按照"图层->布局->控件1- >控件 1子控件"的顺序来传递ELM_EVENT_TOUCH_DOWN 的事件。
6.3.3. APP事件消息的传递过程
窗口APP与ui消息交互需先调用接口注册回调，通过UI_MSG_POST( ...)/ui_server_msg_post发送消息到ui线程，在线程中回调相关函数。
版权所有，侵权必究 18
7. UI API接口
7.1. UI API控件接口
| 接口 | 参数说明 |
|---|---|
| int ui_show_main(int id) | @ brief 显示指定页面 @param id 页面id：显示指定页面（如：PAGE_0,PAGE_ 1...) -7~0:该函数内部有历史记忆，可以显示最近的8个页面，0表示当前页面，-1表示上一个页面，依此类推 * @return 0:成功 其他：失败 |
| int ui_hide_main(int id) | @brief 隐藏指定页面 @ param id 页面id：显示指定页面（如：PAGE_0,PAGE_ 1...)*@ return 0:成功 其他：失败 |
| int ui_hide_curr_main() | @brief 隐藏当前页面 @return 0:成功 其他：失败 |
版权所有，侵权必究 19
| int ui_show(int id) | @brief 显示指定的控件及其所有子控件 @param id:控件宏名称 *@ return 0:成功 其他：失败 |
|---|---|
| int ui_hide(int id) | @brief 隐藏指定的控件及其所有子控件 @ param id:控件宏名称 *@ return 0:成功 其他：失败 |
| int ui_get_current_window_id() | *@brief 获取当前页面id *@ return-1:失败 其他：成功 |
| void ui_ontouch_lock(void *elm) | @brief 锁住触摸焦点控件 @ param 控件句柄 * @return void |
| void ui_ontouch_unlock(void *elm) | @brief 解锁触摸焦点控件 @param 控件句柄 *@ return void |
7.2.文本控件接口
| 接口 | 参数说明 |
|---|---|
| int ui_text_show_index_by_id(int id, int index) | * @brief 在文字列表里切换显示（strpic编码格式） * @param id：控件id * @param index:文字索引 * @return 0：成功 其他：失败 |
| int ui_text_set_index(struct ui_text *text, int index) | * @brief 在文字列表里切换显示（strpic编码格式） * @param text：文本控件句柄 * @param index:文字索引 * @return 0：成功 其他：失败 * @note 一般在onchange里调用，用于控件的初始化 |
| int ui_text_set_str(struct ui_text *text, const char *format, const char *str,int strlen, u32 flags) | * @brief ascii编码的初始化函数 * @param text：文本控件句柄 * @param format:格式，默认“ascii” * @param str：ascii编码 * @param strlen：编码长度 * @param flags：标志位 * @return 0：成功 其他：失败 |
| int ui_text_set_str_by_id(int id, const char *format, const char *str) | * @brief 显示ascii码（ascii编码格式，ascii字库默认已添加） * @param id：控件id * @param format:文本控件格式，默认填“ascii” * @param str：ascii编码 * @return 0：成功 其他：失败 |
| void ui_text_set_text_attrs(struct ui_text *text, const char *str, int | * @brief text编码的初始化函数 * @param text：文本控件句柄 |
版权所有，侵权必究 20
| strlen,u8 encode, u8 endian, u32 flags) | * @param str：编码 * @param strlen：编码长度*@param encode：编码类型， FONT_ENCODE_ANSI/FONT_ENCODE_UNICODE/FONT_ENCODE_UTF8 * @param endian：大小端（对FONT_ENCODE_UNICODE编码有效） * @param flags：标志位 * @return 0：成功 其他：失败 |
|---|---|
| int ui_text_set_text_by_id(int id, const char *str, int strlen, u32 flags) | * @brief 显示内码（text编码格式，需要在download.bat脚本添加对应的字库文件） * @param id：控件id * @param str： 内码 * @param strlen：编码长度 * @param flags：标志位 * @return 0：成功 其他：失败 |
| int ui_text_set_textw_by_id(int id, const char *str, int strlen, intendian, u32 flags) | * @brief 显示unicode编码（text编码格式，需要在download.bat脚本添加对应的字库文件） * @param id：控件id * @param str：unicode码缓存 * @param strlen：编码长度 * @param endian:大小端 * @param flags:标志位 * @return 0：成功 其他：失败 |
| int ui_text_set_textu_by_id(int id, const char *str, int strlen, u32 flags | * @brief 显示utf8编码（text编码格式，需要download.bat添加对应的字库文件） * @param id：控件id * @param str：utf8码缓存 * @param strlen：编码长度 * @param flags：标志位 * @return 0：成功 其他：失败 |
7.3.图片控件接口
| 接口 | 参数说明 |
|---|---|
| int ui_pic_show_image_by_id(int id, int index) | * @brief 在图片列表里切换显示 * @param id：控件id * @param index： 图片索引 * @return void |
| int ui_pic_set_image_index(struct ui_pic *pic, int index) | * @brief 在图片列表里切换显示 * @param pic： 图片控件句柄 * @param index： 图片索引 |
版权所有，侵权必究 21
| * @return void * @note 一般在onchange里调用，用于设置图片控件的初始值 |
|---|
7.4.时间控件接口
| 接口 | 参数说明 |
|---|---|
| int ui_time_update_by_id(int id, struct utime *time) | * @brief 设置时间 * @param id：控件id * @param time：时间 * @return 0：成功 其他：失败 |
| int ui_watch_set_time_by_id(int id, int hour, int min, int sec) | * @brief 设置时间 * @param id：控件id * @param hour：时 * @param min：分 * @param sec：秒 * @return 0：成功 其他：失败 |
7.5.电池控件接口
| 接口 | 参数说明 |
|---|---|
| void ui_battery_level_change(int persent, int incharge) | * @brief 改变所有电池控件的状态 * @param persent：百分比 * @param incharge:是否充电 * @return 0：成功 其他：失败 |
| int ui_battery_set_level_by_id(int id, int persent, int incharge) | * @brief 改变指定id 的电池控件的状态 * @param persent：百分比 * @param incharge:是否充电 * @return 0：成功 其他：失败 |
| int ui_battery_set_level(struct ui_battery *battery, int persent, int incharge); | * @brief 改变指定句柄的电池控件的状态 * @param persent：百分比 * @param incharge:是否充电 * @return 0：成功 其他：失败 |
7.6.表格控件接口
| 接口 | 参数说明 |
|---|---|
| void ui_grid_set_item(struct ui_grid *grid,int index) | * @brief 设置表格活动项 * @param grid：表格控件句柄 |
版权所有，侵权必究 22
| * @param index：活动项索引 * @return void * @note 一般在onchange里调用，用于设置控件的初始值 | |
|---|---|
| int ui_grid_cur_item(struct ui_grid *grid) | * @brief 获取当前表格活动项 * @param grid：表格控件句柄 * @return 高亮索引或者触摸索引 |
| int ui_grid_highlight_item(struct ui_grid *grid, int item, bool yes) | * @brief 高亮指定子项 * @param grid：表格控件句柄 * @param item：子项序号 * @param yes：是否高亮（高亮时使用控件的css属性_ 1） |
| int ui_grid_highlight_item_by_id (int id,int item, bool yes) | * @brief 高亮指定id 的表格控件的指定子项 * @param id：表格控件id * @param item：子项序号 * @param yes：是否高亮（高亮时使用控件的css属性_ 1） |
| void ui_grid_on_focus(struct ui_grid *grid) | * @brief 设置表格控件为焦点控件，按键触摸消息直接发给焦点控件 * @param grid：表格控件句柄 |
| void ui_grid_lose_focus(struct ui_grid *grid) | * @brief 设置表格控件为非焦点控件 * @param grid：表格控件句柄 * @return |
7.7.滑动条控件接口
| 接口 | 参数说明 |
|---|---|
| int ui_slider_set_persent_by_id(int id, int persent) | * @brief 设置滑动块进度 * @param id：控件id * @param persent：百分比（0~ 100%） * @return 0：成功 其他：失败 |
7.8.数字控件接口
| 接口 | 参数说明 |
|---|---|
| int ui_number_update_by_id(int id, struct unumber *n) | * @brief 设置滑动块进度 * @param id：控件id * @param n：数字句柄 @return 0：成功 其他：失败 |
版权所有，侵权必究 23
7.9.圆环控件接口
| 接口 | 参数说明 |
|---|---|
| int ui_progress_set_persent_by_id (int id, int persent) | * @brief 设置圆环进度 * @param id：控件id * @param persent：百分比（0~ 100%） * @return 0：成功 其他：失败 |
7.10.多圆环进度条控件接口（最多三个）
| 接口 | 参数说明 |
|---|---|
| int ui_multiprogress_set_persent_by_id(int id, int persent) | * @brief 设置第一个圆环进度 * @param id：控件id * @param persent：百分比（0~ 100%） * @return 0：成功 其他：失败 |
| int ui_multiprogress_set_second_ persent_by_id(int id, int percent) | * @brief 设置第二个圆环进度 * @param id：控件id * @param persent：百分比（0~ 100%） * @return 0：成功 其他：失败 |
| int ui_multiprogress_set_third_ persent_by_id(int id, int percent) | * @brief 设置第三个圆环进度 * @param id：控件id * @param persent：百分比（0~ 100%） * @return 0：成功 其他：失败 |
版权所有，侵权必究 24