【重磅推出】自绘宫格列表框-TFT屏幕

小逸老师

宫格列表绘制模块API文档 v2.1
备注：本列表框所用颜色全为24位颜色(非RGB565色)
--使用备注：因为只能绘制在屏幕上，所以没有绘制到多个或者指定页面的功能，因为没有绘制到页面的选项，注意是绘制到屏幕而不是页面。
--如果需要在多个页面绘制列表框可以进行模拟操作：
--1.创建多个列表框并将列表框的vis设置为false
--2.在on_screen_change画面切换时或者其他合适时机进行隐藏或显示指定的列表框即可
--特别需要注意的是：
--1.列表框添加pic图片组件如果是图片路径时列表框将在删除表项、清空表、销毁列表框时自动释放图片资源，因为屏幕性能问题可能会导致图片无法释放。
--2.列表框添加pic图片组件如果是图片句柄时列表框在任何情况下都不会自动释放图片资源，需要手动释放图片资源便于你自己的关联
=== 列表框基础操作 ===
1. er_ini(x, y, w, h, cols, rows, spacing, border_color, bg_color, alpha,vis)
   - 功能：创建新宫格列表
   - 参数：
             x,y: 列表框的坐标
             w,h: 列表框的宽高
             cols:列表项的行数
             rows: 列表项的列数
             spacing: 列表项的间距
             border_color:边框颜色(填写false不显示边框)
             bg_color: 列表框背景颜色(填写false不显示边框)
             alpha: 列表框背景颜色透明度0~255,默认255不透明
             vis:是否可(false不可视,省略或者true可视)
    -返回值：列表id

2. er_vis(list_id,vis)
   - 功能：设置列表框是否可视
   - 参数：
             list_id:列表框id
             vis:是否可视(false不可视,省略或者true可视)
   - 返回：无

3. er_gvis(list_id)
   - 功能：获取列表框是否可视
   - 参数：
             list_id:列表框id
   - 返回：true/false

4. er_getwh(list_id)
   - 功能：获取列表项的尺寸,因为考虑在初始化时提供了列表框的宽度和高度和间距和行列数,系统自动进行计算合适的项尺寸
   - 参数：
             list_id:列表框id
   - 返回：w,h 两个参数

5. er_die(list_id)
   - 功能：销毁列表框【重要】如果不需要使用此列表框时调用此函数进行销毁,注意的是这个是销毁不是清空列表数据
   - 参数：
             list_id:列表框id
   - 返回：无

6. er_d(list_id)
   - 功能：【重要】重新绘制列表框,为了系统运行效率,请在以上的函数执行完毕后调用此函数进行重绘(切换页面、销毁列表框不需要调用此函数)
   - 参数：
             list_id:列表框id
   - 返回：无

7. er_page_c(list_id, screen_id, home_btn, prev_btn, next_btn, last_btn, page_display, goto_input, goto_btn, show_total)
   - 功能：注册自动页码控制器,此函数在er_ini初始化列表后优先调用(如果需要列表框自动处理页码功能的话),先在页面添加好这几个按
               钮和Text_Display输入框后提交给此函数即可，列表框将接管这几个控件的可视、使能(启禁用)、内容等。如果不需要使用列
               表框自动处理页码功能的话可以不使用此函数，或者可以使用列表框提供的其他页码控制函数进行自定义页码功能。
   - 参数：
             list_id:列表框id
             screen_id:页码控件所在画面id
             home_btn:切换到第一页按钮控件id
             prev_btn:上一页按钮控件id
             next_btn:下一页按钮控件id
             last_btn:切换到最后一页按钮控件id
             page_display:用于显示页码的Text_Display输入框控件id
             goto_input:用于快速切换指定页面的Text_Display输入框控件id
             show_total:用于快速切换指定页面的按钮控件id,需要和goto_input配合使用,用于输入框输入页码后点击此按钮进行跳转页面。
   - 返回：无

=== 列表项操作 ===
1. er_add(list_id, tag)
   - 功能：向列表框添加项目
   - 参数：
             list_id:列表框id
             tag:备注数据,会在事件回调中原样输出,可存储任何数据
   - 返回：表项索引

2. er_del(list_id, item_index)
   - 功能：删除项目
   - 参数：
             list_id:列表框id
             item_index:表项索引
   - 返回：无

3. er_delall(list_id)
   - 功能：清空项目
   - 参数：
             list_id:列表框id
   - 返回：无

=== 组件管理 - 这里是对列表项的功能===
1. er_text_add(list_id, item_idx, x, y, w, h, text, font, color, h_align, v_align, visible)
   - 功能：向列表项添加文字组件
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             x,y:添加在表项中的坐标
             w,h:文字框的尺寸(不能小于字体*字数的尺寸,如果大于列表项的尺寸系统会强制设置为列表项尺寸-文字组件位置)
             text:文字内容
             font:字号(直接填写字号就行,内部会转换成大彩默认字体编号,例如填写12)
             color:文字颜色
             h_align:水平对齐方式(0左,1中,2右)
             v_align:垂直对齐方式(0上,1中,2下)
             visible:是否可视
   - 返回：组件索引

2. er_text_g(list_id, item_idx, comp_idx)
   - 功能：获取文字框数据
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             comp_idx:组件索引
   - 返回：table{ x, y, w, h, text, font, color, h_align, v_align, visible}


3. er_text_u(list_id, item_idx, comp_idx, x, y, w, h, text, font, color, h_align, v_align, visible)
   - 功能：修改文字组件
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             comp_idx:组件索引
             x,y:修改在表项中的坐标
             w,h:文字框的尺寸(不能小于字体*字数的尺寸,如果大于列表项的尺寸系统会强制设置为列表项尺寸-文字组件位置)
             text:文字内容
             font:字号(直接填写字号就行,内部会转换成大彩默认字体编号,例如填写12)
             color:文字颜色
             h_align:水平对齐方式(0左,1中,2右)
             v_align:垂直对齐方式(0上,1中,2下)
             visible:是否可视
   - 返回：true/false

4. er_pic_add(list_id, item_idx, x, y, w, h, path, visible)
   - 功能：向列表项添加图片框组件
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             x,y:添加在表项中的坐标
             w,h:文字框的尺寸(不能小于字体*字数的尺寸,如果大于列表项的尺寸系统会强制设置为列表项尺寸-文字组件位置)
             path:图片路径或者图片surface句柄(建议使用图片句柄自行管理维护句柄,因为列表框释放图片句柄可能不干净)
             visible:是否可视
   - 返回：组件索引

5. er_pic_g(list_id, item_idx, comp_idx)
   - 功能：获取图片框数据
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             comp_idx:组件索引
   - 返回：table{x,y,w,h,path,visible}
6. er_pic_u(list_id, item_idx, comp_idx, x, y, w, h, path, visible)
   - 功能：更新图片框数据
   - 参数：(如果不需要更新哪一个参数填写false即可)
             list_id:列表框id
             item_idx:表项索引
             comp_idx:组件索引
             x,y:添加在表项中的坐标
             w,h:文字框的尺寸(不能小于字体*字数的尺寸,如果大于列表项的尺寸系统会强制设置为列表项尺寸-文字组件位置)
             path:图片路径或者图片surface句柄(建议使用图片句柄自行管理维护句柄,因为列表框释放图片句柄可能不干净)
             visible:是否可视
   - 返回：true/false

7. er_rgb_add(list_id, item_idx, x, y, w, h, color, alpha, visible)
   - 功能：向列表项添加颜色块组件
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             x,y:添加在表项中的坐标
             w,h:尺
             color:颜色
             alpha:透明度0~255
             visible:是否可视
   - 返回：组件索引


8. er_rgb_g(list_id, item_idx, comp_idx)
   - 功能：获取颜色块数据
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             comp_idx:组件索引
    - 返回：table{x,y,w,h,color,alpha}

9. er_rgb_u(list_id, item_idx, comp_idx, x, y, w, h, color, alpha, visible)
   - 功能：更新颜色块数据
   - 参数：(如果不需要更新哪一个参数填写false即可)
             list_id:列表框id
             item_idx:表项索引
             comp_idx:组件索引
             x,y:在表项中的坐标
             w,h:尺寸
             color:颜色
             alpha:透明度0~255
             visible:是否可视
   - 返回：true/false

10. er_box_add(list_id, item_idx, x, y, w, h, color, visible)
   - 功能：向列表项添加颜色框组件
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             x,y:添加在表项中的坐标
             w,h:尺
             color:颜色
             visible:是否可视
   - 返回：组件索引


11. er_box_g(list_id, item_idx, comp_idx)
   - 功能：获取颜色框数据
   - 参数：
             list_id:列表框id
             item_idx:表项索引
             comp_idx:组件索引
    - 返回：table{x, y, w, h, color, visible}

12. er_box_u(list_id, item_idx, comp_idx, x, y, w, h, color, visible)
   - 功能：更新颜色框数据
   - 参数：(如果不需要更新哪一个参数填写false即可)
             list_id:列表框id
             item_idx:表项索引
             comp_idx:组件索引
             x,y:在表项中的坐标
             w,h:尺寸
             color:颜色
             visible:是否可视
   - 返回：true/false

=== 分页控制 ===
1. er_page_set(list_id,page)
   - 功能：用于切换页
   - 参数：
             list_id:列表框id
             page:需要切换到的列表页
   - 返回：无

2. er_page_get(list_id)
   - 功能：获取当前页
   - 参数：
             list_id:列表框id
   - 返回：int当前页数

3. er_page_all(list_id)
   - 功能：获取总页数
   - 参数：
             list_id:列表框id
   - 返回：int总页数

=== 事件挂接 ===
1. er_page_call(screen, control, value)
   - 功能：挂接页码控制器，需要配合列表框基础操作中的er_page_c函数使用,使用时先使用er_page_c注册并绑定控件
   - 使用备注：请将此函数原封不动的放到大彩屏幕的on_control_notify(screen, control, value)的回调函数内即可，例如：
               function on_control_notify(screen,control,value)
                       er_page_call(screen, control, value)
               end
   - 参数：
             list_id:列表框id
             control:控件id
             value:控件值
   - 返回：无

2. er_call(state, x, y, you_call)
   - 功能：挂接触摸回调函数,用于列表框的点击事件触发
   - 使用备注：请将此函数原封不动的放到大彩屏幕的on_press(state, x, y)的回调函数内即可，例如：
               function on_press(state, x, y)
                       er_call(state, x, y, you_call) --将you_call更换为你需要接收列表框点击事件的函数名称
               end
               function you_call(state, list_id, item_idx, comp_idx, tag, title)
                    print("点击", "state:",state,"  list_id:",list_id,"  item_idx:",item_idx,"  comp_idx:",comp_idx,"  tag:",tag,"  title:",title)
               end
   - 参数：
             state: 点击模式
             x/y:点击的屏幕位置
             you_call:将you_call更换为你需要接收列表框点击事件的函数名称
   - 返回：无

3. you_call(state, list_id, item_idx, comp_idx, tag, title)
   - 功能：用于列表框的点击事件回调在这个函数里,在你的代码里增加此函数,you_call函数名称换成你自己定义的,参数必须填写这几个
   - 使用备注：需要和er_call配合使用,参考er_call函数中的使用备注。
   - 参数：
             state:点击模式(1=点,0=放开,2=按住超过一定时间相当于持续按住,可以在本模块文件的touch_mod_deay变量调整精度)
             list_id:控件id
             item_idx:列表框id
             comp_idx:组件id
             tag:添加列表项的时候填写的tag
             title:如果是文字组件返回文字内容,如果是图片组件以图片路径提交的将返回图片路径,如果是图片组件以surface句柄提交的将返回句
                    柄,如果是颜色框或颜色外框将返回颜色值。
   - 返回：通用

4. er_draw()
   - 功能：挂接绘制函数
   - 使用备注：请将此函数原封不动的放到大彩屏幕的on_draw(screen)的回调函数内即可，例如：
               function on_draw(screen)
                       er_draw()
               end
   - 参数：
               无
   - 返回：无