From bfcd714412425fa6b76c2638d809b952bd854df5 Mon Sep 17 00:00:00 2001 From: idea4good Date: Thu, 12 Sep 2019 11:25:07 +0800 Subject: [PATCH 1/2] add more function comment for HowToWork-cn.md --- core/surface.cpp | 1 - doc/HowToWork-cn.md | 27 ++++++++++++++++++++++----- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/core/surface.cpp b/core/surface.cpp index a130ffa..e3b5435 100644 --- a/core/surface.cpp +++ b/core/surface.cpp @@ -202,7 +202,6 @@ void c_surface::fill_rect_on_fb(int x0, int y0, int x1, int y1, unsigned int rgb } } } - } unsigned int c_surface::get_pixel(int x, int y, unsigned int z_order) diff --git a/doc/HowToWork-cn.md b/doc/HowToWork-cn.md index 98b575a..d0fbb83 100644 --- a/doc/HowToWork-cn.md +++ b/doc/HowToWork-cn.md @@ -103,11 +103,28 @@ widgets: ## 函数注释 | 函数名称 | display.cpp 函数接口注释 | | --- | --- | -| c_display | c_display构造函数，初始化显示参数。输入：物理framebuffer指针，物理显示器宽度，物理显示器高度，surface宽度，surface高度，颜色深度，surface个数/滑动页面的个数 | -| create_surface | 创建surface/滑动页面。输入： 用户ID，图层的个数| -| merge_surface | 横向组合surface，多用于滑动surface。输入：待组合的surface源1，待组合的surface源2，surface源1的起始点x坐标，surface源2的起始点x坐标，surface源1的起始点y坐标，surface源2的起始点y坐标，横向组合的偏移距离；输出：可能改变当前显示内容 | -| get_updated_fb | 获取该display的物理framebuffer指针 | -| snap_shot | 生成当前显示的快照，并输出到bmp文件 | +| c_display | c_display构造函数。phy_fb：物理framebuffer指针；display_width：物理显示器宽度；display_height：物理显示器高度；surface_width：surface宽度；surface_height：surface高度；color_bytes：颜色深度；surface_cnt：surface个数/滑动页面的个数；gfx_op：外部绘制接口，用以适配非framebuffer的渲染方式，如果该值不为空，surface在作底层渲染的时候，会调用该接口 | +| alloc_surface | 分配surface/滑动页面。usr： 用户ID；max_zorder：该surface所拥有的图层数量| +| merge_surface | 横向组合两个surface，多用于滑动surface。s0：源surface 0；s1：源surface 1，x0：源surface 0的起始点x坐标；x1：源surface 1的起始点x坐标；y0：源surface 0的起始点y坐标；y1：源surface 1的起始点y坐标；offset：横向组合的偏移距离 | +| get_updated_fb | 获取该display的framebuffer指针，常用来将GUI显示在任意需要的地方。widght：用来获取framebuffer的宽度；height：用来获取framebuffer的高度；force_update：是否需要强制更新framebuffer的内容，如果不需要强制更新，且framebuffer没法发生变化，将返回NULL | +| snap_shot | 生成当前显示的快照，并输出到bitmap文件。file_name：快照文件的名称 | +*** +| 函数名称 | surface.cpp 函数接口注释 | +| --- | --- | +| c_surface | c_surface构造函数。 display：surface所属于的display；width：surface的宽度；height：surface的高度；color_bytes：颜色深度| +| set_surface | 设置surface。wnd_root：使用者者ID，通常为root window，其子窗口自动获得该surface的使用权。 max_z_order：该surface拥有的图层数量 | +| draw_pixel | 渲染一个像素点。x：像素点坐标x；y：像素点坐标y；rgb：像素颜色；z_order：像素所在的图层 | +| draw_pixel_on_fb | 渲染一个像素点 - 底层渲染。x：像素点坐标x；y：像素点坐标y；rgb：像素颜色 | +| fill_rect | 填充一个矩形。 x0：矩形左上角的坐标x；y0：矩形左上角的坐标y；x1：矩形右下角的坐标x；y1：矩形右下角的坐标y；rgb：矩形的颜色；z_order：矩形所在的图层| +| fill_rect_on_fb | 填充一个矩形 - 底层渲染。 x0：矩形左上角的坐标x；y0：矩形左上角的坐标y；x1：矩形右下角的坐标x；y1：矩形右下角的坐标y；rgb：矩形的颜色 | +| get_pixel | 获取指定位置的像素点的颜色值。x：位置坐标x；y：位置坐标y；z_order：位置坐标z（图层坐标） | +| draw_hline | 渲染一条横线。x0：横线的左边起始坐标x；x1：横线的右边结尾坐标x；y：横线的纵向坐标y | +| draw_vline | 渲染一条竖线。x：竖线的横向坐标：x；y0：竖线的上起始坐标y；y1：竖线的下结尾坐标y | +| draw_line | 渲染普通直线。x1：直线左端点的坐标x；y1：直线左端点的坐标y；x2：直线右端点坐标x；y2：直线右端点坐标y | +| draw_rect | 渲染矩形。x0：矩形左上角的坐标x；y0：矩形左上角的坐标y；x1：矩形右下角的坐标x；y1：矩形右下角的坐标y | +| set_frame_layer_visible_rect | 设置指定图层的可视区域（矩形），可视区域会根据图层优先级，自动进行上下叠加。rect：可视矩形的位置信息；z_order：图层的z坐标（图层坐标） | +| flush_screen | 将当前surface的指定矩形区域一次性刷在显示屏上。left：surface指定区域的左边界坐标；top：surface指定区域的上边界坐标；right：surface指定区域的右边界坐标；bottom：surface指定区域的下边界坐标 | +| is_valid | 判断给定位置的矩形，是否合理（是否在surface的范围内）。rect：矩形区域的坐标信息 | ## 速成路线图 1. 精读源文件wnd.cpp中的connect, on_touch, on_key函数，理解界面元素的串联办法；理解响应触控操作的基本原理；理解响应硬按键的基本原理 From c14b2d3ac8fb6c8a44a31609406118eefe082b01 Mon Sep 17 00:00:00 2001 From: idea4good Date: Thu, 12 Sep 2019 16:54:16 +0800 Subject: [PATCH 2/2] add more function comment for HowToWork-cn.md --- doc/HowToBuild.md | 24 +++++++++++++----------- doc/HowToWork-cn.md | 21 +++++++++++++++++++++ 2 files changed, 34 insertions(+), 11 deletions(-) diff --git a/doc/HowToBuild.md b/doc/HowToBuild.md index c94196a..e64bcf3 100644 --- a/doc/HowToBuild.md +++ b/doc/HowToBuild.md @@ -45,15 +45,14 @@ FAQ: Error when open GuiLite project with Visual Studio, reconfigure the project - Output here: /GuiLite/Objects/GuiLite.lib ## How to port? -Here are 2 options for porting. For option 1: you should build GuiLite library, and move all headers files & library to your project; For option 2: You do not need to build GuiLite library, just merge all GuiLite code into 1 header(GuiLite.h) & 1 source(GuiLite.cpp), then move the 2 files to your project. +Here are 2 options for porting. -We recommend option 2, because of: -- Easy to port - no need to buid library -- Easy to move - just 2 files -- Easy to manage header files - just 1 header file -- Easy to debug - no library binary +### Option 1: 1 Header & 1 Source +1. Execute `1h-1cpp.sh` to merge the whole source code into: 1 header(GuiLite.h) & 1 source(GuiLite.cpp) +2. Move GuiLite.h/GuiLite.cpp to your project +3. Rebuild your project -### Option 1: Header & Library +### Option 2: Headers & 1 Library - Headers: core_include, widgets_include - Library: The GuiLite library 1. Move core_include/widgets_include to your project @@ -61,7 +60,10 @@ We recommend option 2, because of: 3. Link GuiLite library to your project 4. Rebuild your project -### Option 2: Header & Source -1. Execute `1h-1cpp.sh` to merge the whole source code into: 1 header(GuiLite.h) & 1 source(GuiLite.cpp) -2. Move GuiLite.h/GuiLite.cpp to your project -3. Rebuild your project +We recommend option 1, because of: +- Easy to port - no need to buid library +- Easy to move - just 2 files +- Easy to manage header files - just 1 header file +- Easy to debug - no library binary + +On the other hand, for option 2: you should build GuiLite library, and move all headers files & library to your project. diff --git a/doc/HowToWork-cn.md b/doc/HowToWork-cn.md index d0fbb83..c76468c 100644 --- a/doc/HowToWork-cn.md +++ b/doc/HowToWork-cn.md @@ -125,6 +125,27 @@ widgets: | set_frame_layer_visible_rect | 设置指定图层的可视区域（矩形），可视区域会根据图层优先级，自动进行上下叠加。rect：可视矩形的位置信息；z_order：图层的z坐标（图层坐标） | | flush_screen | 将当前surface的指定矩形区域一次性刷在显示屏上。left：surface指定区域的左边界坐标；top：surface指定区域的上边界坐标；right：surface指定区域的右边界坐标；bottom：surface指定区域的下边界坐标 | | is_valid | 判断给定位置的矩形，是否合理（是否在surface的范围内）。rect：矩形区域的坐标信息 | +*** +| 函数名称 | wnd.cpp 函数接口注释 | +| --- | --- | +| c_wnd | c_wnd构造函数，进行基本初始化 | +| connect | 把自己（this）、自己的子窗口系列及父窗口连接起来，形成完整的UI窗口链条；连接完成后，自己就可以响应用户输入及各种UI消息。parent：父窗口；resour_id：窗口ID；str：自己的窗口标题字符串；x：自己相对父窗口的坐标x；y：自己相对父窗口的坐标y；width：窗口宽度；height：窗口高度；p_child_tree：子窗口系列 | +| load_child_wnd | 把一系列子窗口连接起来，形成完整的UI窗口链条；连接完成后，所有子窗口都可以响应用户输入及各种UI消息。p_child_tree：子窗口系列 | +| disconnect | 把自己（this）跟父窗口、子窗口脱离连接，切断自己与UI的联系，不在响应用户输入及各种UI消息。 | +| get_wnd_ptr | 获得指定窗口ID的窗口指针。id：窗口ID | +| set_attr | 设置窗口属性，包括：普通、失效、可见。attr：属性值 | +| is_focus_wnd | 判断自己（this）是否可以获得焦点 | +| set_wnd_pos | 设置自己（this）相对于父窗口的窗口位置。x：窗口左上角坐标x；y：窗口左上角坐标y；width：窗口宽度；height：窗口高度 | +| get_wnd_rect | 获取自己（this）相对于父窗口的位置信息。rect：用于输出位置信息 | +| get_screen_rect | 获取自己（this）相对于UI系统的绝对位置信息。rect：用于输出位置信息 | +| set_child_focus | 将自己（this）的一个子窗口设置为获得讲点状态。 focus_child：获得焦点的子窗口| +| add_child_2_tail | 把一个子窗口添加到自己（this）的子窗口链表的尾部。child：被添加的子窗口 | +| get_last_child | 获得自己（this）子窗口链表尾部的子窗口指针。 | +| unlink_child | 将自己（this）的子窗口从子窗口链表中脱离出来。child：被脱链的子窗口 | +| show_window | 渲染自己（this）及自己的子窗口 | +| on_touch | 响应用户的触控消息。x：用户触控点的坐标x；y：用户触控点的坐标y；action：用户的触控类型，包括：按下，释放 | +| on_key | 响应用户的按键消息。key：用户点击的按键键值。 | +| notify_parent | 传递UI消息给自己（this）的父窗口，并调用父窗口对应的响应函数。msg_id：消息ID；ctrl_id：自己的资源ID，param：消息的参数 | ## 速成路线图 1. 精读源文件wnd.cpp中的connect, on_touch, on_key函数，理解界面元素的串联办法；理解响应触控操作的基本原理；理解响应硬按键的基本原理