update docs

Y-JESSE · Dec 21, 2018 · a267687 · a267687
1 parent 8d873ec
commit a267687
Show file tree

Hide file tree

Showing 120 changed files with 1,116 additions and 1,028 deletions.
diff --git a/docs/manual.md b/docs/manual.md
@@ -4,9 +4,11 @@
 
 ### 控件
 
-![](images/widget_overview.png)
+![widget_overview](images/widget_overview.png)
 
-1.[widget_t](manual/widget_t.md) 所有控件、窗口和窗口管理器的基类。
+* [widget_t](manual/widget_t.md) 所有控件、窗口和窗口管理器的基类。
+* [label_t](manual/widget_t.md) 文本控件。
+* [button_t](manual/widget_t.md) 按钮控件。
 
 ### 输入法
 

diff --git a/docs/manual/app_bar_t.md b/docs/manual/app_bar_t.md
@@ -9,8 +9,8 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#app_bar_t_app_bar_cast">app\_bar\_cast</a> |  转换为app_bar对象(供脚本语言使用)。 |
-| <a href="#app_bar_t_app_bar_create">app\_bar\_create</a> |  创建app_bar对象 |
+| <a href="#app_bar_t_app_bar_cast">app\_bar\_cast</a> | 转换为app_bar对象(供脚本语言使用)。 |
+| <a href="#app_bar_t_app_bar_create">app\_bar\_create</a> | 创建app_bar对象 |
 ### 属性
 <p id="app_bar_t_properties">
 

diff --git a/docs/manual/array_t.md b/docs/manual/array_t.md
@@ -7,24 +7,24 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#array_t_array_create">array\_create</a> |  创建array对象 |
-| <a href="#array_t_array_deinit">array\_deinit</a> |  清除数组中的元素。 |
-| <a href="#array_t_array_destroy">array\_destroy</a> |  清除数组中的元素，并释放数组对象。 |
-| <a href="#array_t_array_find">array\_find</a> |  查找第一个满足条件的元素。 |
-| <a href="#array_t_array_find_index">array\_find\_index</a> |  查找第一个满足条件的元素，并返回位置。 |
-| <a href="#array_t_array_init">array\_init</a> |  初始化array对象 |
-| <a href="#array_t_array_pop">array\_pop</a> |  弹出最后一个元素。 |
-| <a href="#array_t_array_push">array\_push</a> |  在尾巴追加一个元素。 |
-| <a href="#array_t_array_remove">array\_remove</a> |  删除第一个满足条件的元素。 |
-| <a href="#array_t_array_remove_all">array\_remove\_all</a> |  删除全部满足条件的元素。 |
+| <a href="#array_t_array_create">array\_create</a> | 创建array对象 |
+| <a href="#array_t_array_deinit">array\_deinit</a> | 清除数组中的元素。 |
+| <a href="#array_t_array_destroy">array\_destroy</a> | 清除数组中的元素，并释放数组对象。 |
+| <a href="#array_t_array_find">array\_find</a> | 查找第一个满足条件的元素。 |
+| <a href="#array_t_array_find_index">array\_find\_index</a> | 查找第一个满足条件的元素，并返回位置。 |
+| <a href="#array_t_array_init">array\_init</a> | 初始化array对象 |
+| <a href="#array_t_array_pop">array\_pop</a> | 弹出最后一个元素。 |
+| <a href="#array_t_array_push">array\_push</a> | 在尾巴追加一个元素。 |
+| <a href="#array_t_array_remove">array\_remove</a> | 删除第一个满足条件的元素。 |
+| <a href="#array_t_array_remove_all">array\_remove\_all</a> | 删除全部满足条件的元素。 |
 ### 属性
 <p id="array_t_properties">
 
 | 名属性称 | 类型 | 说明 | 
 | -------- | ----- | ------------ | 
-| <a href="#array_t_capacity">capacity</a> | uint16_t |  数组的容量大小。 |
-| <a href="#array_t_elms">elms</a> | void** |  数组中的元素。 |
-| <a href="#array_t_size">size</a> | uint16_t |  数组中元素的个数。 |
+| <a href="#array_t_capacity">capacity</a> | uint16_t | 数组的容量大小。 |
+| <a href="#array_t_elms">elms</a> | void** | 数组中的元素。 |
+| <a href="#array_t_size">size</a> | uint16_t | 数组中元素的个数。 |
 ### 事件
 <p id="array_t_events">
 

diff --git a/docs/manual/asset_info_t.md b/docs/manual/asset_info_t.md
@@ -12,12 +12,12 @@
 
 | 名属性称 | 类型 | 说明 | 
 | -------- | ----- | ------------ | 
-| <a href="#asset_info_t_is_in_rom">is\_in\_rom</a> | uint8_t |  资源是否在ROM中。 |
-| <a href="#asset_info_t_name">name</a> | char* |  名称。 |
-| <a href="#asset_info_t_refcount">refcount</a> | uint32_t |  引用计数。is_in_rom == FALSE时才有效。 |
-| <a href="#asset_info_t_size">size</a> | uint32_t |  大小。 |
-| <a href="#asset_info_t_subtype">subtype</a> | uint8_t |  子类型。 |
-| <a href="#asset_info_t_type">type</a> | uint16_t |  类型。 |
+| <a href="#asset_info_t_is_in_rom">is\_in\_rom</a> | uint8_t | 资源是否在ROM中。 |
+| <a href="#asset_info_t_name">name</a> | char* | 名称。 |
+| <a href="#asset_info_t_refcount">refcount</a> | uint32_t | 引用计数。is_in_rom == FALSE时才有效。 |
+| <a href="#asset_info_t_size">size</a> | uint32_t | 大小。 |
+| <a href="#asset_info_t_subtype">subtype</a> | uint8_t | 子类型。 |
+| <a href="#asset_info_t_type">type</a> | uint16_t | 类型。 |
 ### 事件
 <p id="asset_info_t_events">
 

diff --git a/docs/manual/assets_manager_t.md b/docs/manual/assets_manager_t.md
@@ -7,19 +7,19 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#assets_manager_t_assets_manager">assets\_manager</a> |  获取缺省资源管理器。 |
-| <a href="#assets_manager_t_assets_manager_add">assets\_manager\_add</a> |  向资源管理器中增加一个资源。 |
-| <a href="#assets_manager_t_assets_manager_clear_cache">assets\_manager\_clear\_cache</a> |  清除指定类型的缓存。 |
-| <a href="#assets_manager_t_assets_manager_create">assets\_manager\_create</a> |  创建资源管理器。 |
-| <a href="#assets_manager_t_assets_manager_deinit">assets\_manager\_deinit</a> |  释放全部资源。 |
-| <a href="#assets_manager_t_assets_manager_destroy">assets\_manager\_destroy</a> |  释放全部资源并销毁asset manager对象。 |
-| <a href="#assets_manager_t_assets_manager_find_in_cache">assets\_manager\_find\_in\_cache</a> |  在资源管理器的缓存中查找指定的资源(不引用)。 |
-| <a href="#assets_manager_t_assets_manager_init">assets\_manager\_init</a> |  初始化资源管理器。 |
-| <a href="#assets_manager_t_assets_manager_load">assets\_manager\_load</a> |  从文件系统中加载指定的资源，并缓存到内存中。在定义了宏WITH_FS_RES时才生效。 |
-| <a href="#assets_manager_t_assets_manager_ref">assets\_manager\_ref</a> |  在资源管理器的缓存中查找指定的资源并引用它，如果缓存中不存在，尝试加载该资源。 |
-| <a href="#assets_manager_t_assets_manager_set">assets\_manager\_set</a> |  设置缺省资源管理器。 |
-| <a href="#assets_manager_t_assets_manager_set_res_root">assets\_manager\_set\_res\_root</a> |  设置资源所在的目录(其下目录结构请参考demos)。 |
-| <a href="#assets_manager_t_assets_manager_unref">assets\_manager\_unref</a> |  释放指定的资源。 |
+| <a href="#assets_manager_t_assets_manager">assets\_manager</a> | 获取缺省资源管理器。 |
+| <a href="#assets_manager_t_assets_manager_add">assets\_manager\_add</a> | 向资源管理器中增加一个资源。 |
+| <a href="#assets_manager_t_assets_manager_clear_cache">assets\_manager\_clear\_cache</a> | 清除指定类型的缓存。 |
+| <a href="#assets_manager_t_assets_manager_create">assets\_manager\_create</a> | 创建资源管理器。 |
+| <a href="#assets_manager_t_assets_manager_deinit">assets\_manager\_deinit</a> | 释放全部资源。 |
+| <a href="#assets_manager_t_assets_manager_destroy">assets\_manager\_destroy</a> | 释放全部资源并销毁asset manager对象。 |
+| <a href="#assets_manager_t_assets_manager_find_in_cache">assets\_manager\_find\_in\_cache</a> | 在资源管理器的缓存中查找指定的资源(不引用)。 |
+| <a href="#assets_manager_t_assets_manager_init">assets\_manager\_init</a> | 初始化资源管理器。 |
+| <a href="#assets_manager_t_assets_manager_load">assets\_manager\_load</a> | 从文件系统中加载指定的资源，并缓存到内存中。在定义了宏WITH_FS_RES时才生效。 |
+| <a href="#assets_manager_t_assets_manager_ref">assets\_manager\_ref</a> | 在资源管理器的缓存中查找指定的资源并引用它，如果缓存中不存在，尝试加载该资源。 |
+| <a href="#assets_manager_t_assets_manager_set">assets\_manager\_set</a> | 设置缺省资源管理器。 |
+| <a href="#assets_manager_t_assets_manager_set_res_root">assets\_manager\_set\_res\_root</a> | 设置资源所在的目录(其下目录结构请参考demos)。 |
+| <a href="#assets_manager_t_assets_manager_unref">assets\_manager\_unref</a> | 释放指定的资源。 |
 ### 属性
 <p id="assets_manager_t_properties">
 

diff --git a/docs/manual/bitmap_t.md b/docs/manual/bitmap_t.md
@@ -7,27 +7,27 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#bitmap_t_bitmap_create">bitmap\_create</a> |  创建图片对象(一般供脚本语言中使用)。 |
-| <a href="#bitmap_t_bitmap_create_ex">bitmap\_create\_ex</a> |  创建图片对象。 |
-| <a href="#bitmap_t_bitmap_destroy">bitmap\_destroy</a> |  销毁图片。 |
-| <a href="#bitmap_t_bitmap_get_bpp">bitmap\_get\_bpp</a> |  获取图片一个像素占用的字节数。 |
-| <a href="#bitmap_t_bitmap_get_line_length">bitmap\_get\_line\_length</a> |  获取每一行占用内存的字节数。 |
-| <a href="#bitmap_t_bitmap_get_pixel">bitmap\_get\_pixel</a> |  获取图片指定像素的rgba颜色值(主要用于测试程序)。 |
-| <a href="#bitmap_t_bitmap_init">bitmap\_init</a> |  初始化图片。 |
-| <a href="#bitmap_t_bitmap_init_from_rgba">bitmap\_init\_from\_rgba</a> |  初始化图片。 |
-| <a href="#bitmap_t_bitmap_set_line_length">bitmap\_set\_line\_length</a> |  设置line_length。 |
+| <a href="#bitmap_t_bitmap_create">bitmap\_create</a> | 创建图片对象(一般供脚本语言中使用)。 |
+| <a href="#bitmap_t_bitmap_create_ex">bitmap\_create\_ex</a> | 创建图片对象。 |
+| <a href="#bitmap_t_bitmap_destroy">bitmap\_destroy</a> | 销毁图片。 |
+| <a href="#bitmap_t_bitmap_get_bpp">bitmap\_get\_bpp</a> | 获取图片一个像素占用的字节数。 |
+| <a href="#bitmap_t_bitmap_get_line_length">bitmap\_get\_line\_length</a> | 获取每一行占用内存的字节数。 |
+| <a href="#bitmap_t_bitmap_get_pixel">bitmap\_get\_pixel</a> | 获取图片指定像素的rgba颜色值(主要用于测试程序)。 |
+| <a href="#bitmap_t_bitmap_init">bitmap\_init</a> | 初始化图片。 |
+| <a href="#bitmap_t_bitmap_init_from_rgba">bitmap\_init\_from\_rgba</a> | 初始化图片。 |
+| <a href="#bitmap_t_bitmap_set_line_length">bitmap\_set\_line\_length</a> | 设置line_length。 |
 ### 属性
 <p id="bitmap_t_properties">
 
 | 名属性称 | 类型 | 说明 | 
 | -------- | ----- | ------------ | 
-| <a href="#bitmap_t_data">data</a> | uint8_t* |  图片数据。 |
-| <a href="#bitmap_t_flags">flags</a> | uint16_t |  标志。请参考{bitmap_flag_t}。 |
-| <a href="#bitmap_t_format">format</a> | uint16_t |  格式。请参考{bitmap_format_t}。 |
-| <a href="#bitmap_t_h">h</a> | wh_t |  高度。 |
-| <a href="#bitmap_t_line_length">line\_length</a> | uint32_t |  每一行实际占用的内存(也称为stride或pitch)，一般情况下为w*bpp。 |
-| <a href="#bitmap_t_name">name</a> | char* |  名称。 |
-| <a href="#bitmap_t_w">w</a> | wh_t |  宽度。 |
+| <a href="#bitmap_t_data">data</a> | uint8_t* | 图片数据。 |
+| <a href="#bitmap_t_flags">flags</a> | uint16_t | 标志。请参考{bitmap_flag_t}。 |
+| <a href="#bitmap_t_format">format</a> | uint16_t | 格式。请参考{bitmap_format_t}。 |
+| <a href="#bitmap_t_h">h</a> | wh_t | 高度。 |
+| <a href="#bitmap_t_line_length">line\_length</a> | uint32_t | 每一行实际占用的内存(也称为stride或pitch)，一般情况下为w*bpp。 |
+| <a href="#bitmap_t_name">name</a> | char* | 名称。 |
+| <a href="#bitmap_t_w">w</a> | wh_t | 宽度。 |
 ### 事件
 <p id="bitmap_t_events">
 

diff --git a/docs/manual/button_group_t.md b/docs/manual/button_group_t.md
@@ -8,8 +8,8 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#button_group_t_button_group_cast">button\_group\_cast</a> |  转换为button_group对象(供脚本语言使用)。 |
-| <a href="#button_group_t_button_group_create">button\_group\_create</a> |  创建button_group对象 |
+| <a href="#button_group_t_button_group_cast">button\_group\_cast</a> | 转换为button_group对象(供脚本语言使用)。 |
+| <a href="#button_group_t_button_group_create">button\_group\_create</a> | 创建button_group对象 |
 ### 属性
 <p id="button_group_t_properties">
 

diff --git a/docs/manual/button_t.md b/docs/manual/button_t.md
@@ -3,20 +3,60 @@
 ![image](images/button_t_0.png)
 
  按钮控件。
+
+ 点击按钮之后会触发EVT\_CLICK事件，注册EVT\_CLICK事件以执行特定操作。
+
+ 按钮控件也可以作为容器使用，使用图片和文本作为其子控件，可以实现很多有趣的效果。
+
+ button\_t是[widget\_t](widget_t.md)的子类控件，widget\_t的函数均适用于button\_t控件。
+
+ 在xml中使用"button"标签创建文本控件。如：
+
+ ```xml
+ <button x="c" y="m" w="80" h="30" text="OK"/>
+ ```
+
+ > 更多用法请参考：[button.xml](https://github.com/zlgopen/awtk/blob/master/demos/assets/raw/ui/button.xml)
+
+ 在c代码中使用函数button\_create创建文本控件。如：
+
+ ```c
+  widget_t* button = button_create(win, 10, 10, 128, 30);
+  widget_set_text(button, L"OK");
+  widget_on(button, EVT_CLICK, on_click, NULL);
+ ```
+
+ > 创建之后，需要用widget\_set\_text或widget\_set\_text\_utf8设置文本内容。
+
+ > 完整示例请参考：[button demo](https://github.com/zlgopen/awtk-c-demos/blob/master/demos/button.c)
+
+ 可用通过style来设置控件的显示风格，如字体的大小和颜色等等。如：
+
+ ```xml
+  <style name="default" border_color="#a0a0a0"  text_color="black">
+   <normal     bg_color="#f0f0f0" />
+   <pressed    bg_color="#c0c0c0" x_offset="1" y_offset="1"/>
+   <over       bg_color="#e0e0e0" />
+   <disable    bg_color="gray" text_color="#d0d0d0" />
+ </style>
+ ```
+
+ > 更多用法请参考：[theme default](https://github.com/zlgopen/awtk/blob/master/demos/assets/raw/styles/default.xml#L31)
+
 ### 函数
 <p id="button_t_methods">
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#button_t_button_cast">button\_cast</a> |  转换为button对象(供脚本语言使用)。 |
-| <a href="#button_t_button_create">button\_create</a> |  创建button对象 |
-| <a href="#button_t_button_set_repeat">button\_set\_repeat</a> |  设置释放EVT_CLICK事件的时间间隔。为0则不重复释放EVT_CLICK事件。 |
+| <a href="#button_t_button_cast">button\_cast</a> | 转换为button对象(供脚本语言使用)。 |
+| <a href="#button_t_button_create">button\_create</a> | 创建button对象 |
+| <a href="#button_t_button_set_repeat">button\_set\_repeat</a> | 设置触发EVT\_CLICK事件的时间间隔。为0则不重复触发EVT\_CLICK事件。 |
 ### 属性
 <p id="button_t_properties">
 
 | 名属性称 | 类型 | 说明 | 
 | -------- | ----- | ------------ | 
-| <a href="#button_t_repeat">repeat</a> | int32_t |  重复释放EVT_CLICK事件的时间间隔。为0则不重复释放EVT_CLICK事件。 |
+| <a href="#button_t_repeat">repeat</a> | int32_t | 重复触发EVT\_CLICK事件的时间间隔。 |
 ### 事件
 <p id="button_t_events">
 
@@ -85,16 +125,17 @@ ret_t button_set_repeat (widget_t* widget, int32_t repeat);
 | -------- | ----- | --------- |
 | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
 | widget | widget\_t* | 控件对象。 |
-| repeat | int32\_t | 释放EVT\_CLICK事件的时间间隔(毫秒)。 |
+| repeat | int32\_t | 触发EVT\_CLICK事件的时间间隔(毫秒)。 |
 * 函数功能：
 
-> <p id="button_t_button_set_repeat"> 设置释放EVT_CLICK事件的时间间隔。为0则不重复释放EVT_CLICK事件。
+> <p id="button_t_button_set_repeat"> 设置触发EVT\_CLICK事件的时间间隔。为0则不重复触发EVT\_CLICK事件。
 
 
 
 #### repeat 属性
 -----------------------
-> <p id="button_t_repeat"> 重复释放EVT_CLICK事件的时间间隔。为0则不重复释放EVT_CLICK事件。
+> <p id="button_t_repeat"> 重复触发EVT\_CLICK事件的时间间隔。
+ 为0则不重复触发EVT\_CLICK事件。
 
 
 * 类型：int32\_t

diff --git a/docs/manual/calibration_win_t.md b/docs/manual/calibration_win_t.md
@@ -8,9 +8,9 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#calibration_win_t_calibration_win_create">calibration\_win\_create</a> |  创建calibration_win对象 |
-| <a href="#calibration_win_t_calibration_win_set_on_click">calibration\_win\_set\_on\_click</a> |  设置校准点击事件的处理函数。 |
-| <a href="#calibration_win_t_calibration_win_set_on_done">calibration\_win\_set\_on\_done</a> |  设置校准完成的处理函数。 |
+| <a href="#calibration_win_t_calibration_win_create">calibration\_win\_create</a> | 创建calibration_win对象 |
+| <a href="#calibration_win_t_calibration_win_set_on_click">calibration\_win\_set\_on\_click</a> | 设置校准点击事件的处理函数。 |
+| <a href="#calibration_win_t_calibration_win_set_on_done">calibration\_win\_set\_on\_done</a> | 设置校准完成的处理函数。 |
 ### 属性
 <p id="calibration_win_t_properties">
 

diff --git a/docs/manual/candidates_t.md b/docs/manual/candidates_t.md
@@ -8,7 +8,7 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#candidates_t_candidates_create">candidates\_create</a> |  创建candidates对象 |
+| <a href="#candidates_t_candidates_create">candidates\_create</a> | 创建candidates对象 |
 ### 属性
 <p id="candidates_t_properties">
 

diff --git a/docs/manual/canvas_widget_t.md b/docs/manual/canvas_widget_t.md
@@ -8,8 +8,8 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#canvas_widget_t_canvas_widget_cast">canvas\_widget\_cast</a> |  转换为canvas_widget对象(供脚本语言使用)。 |
-| <a href="#canvas_widget_t_canvas_widget_create">canvas\_widget\_create</a> |  创建canvas_widget对象 |
+| <a href="#canvas_widget_t_canvas_widget_cast">canvas\_widget\_cast</a> | 转换为canvas_widget对象(供脚本语言使用)。 |
+| <a href="#canvas_widget_t_canvas_widget_create">canvas\_widget\_create</a> | 创建canvas_widget对象 |
 ### 属性
 <p id="canvas_widget_t_properties">
 

diff --git a/docs/manual/check_button_t.md b/docs/manual/check_button_t.md
@@ -8,16 +8,16 @@
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#check_button_t_check_button_cast">check\_button\_cast</a> |  转换check_button对象(供脚本语言使用)。 |
-| <a href="#check_button_t_check_button_create">check\_button\_create</a> |  创建check_button对象 |
-| <a href="#check_button_t_check_button_create_radio">check\_button\_create\_radio</a> |  创建check_button对象 |
-| <a href="#check_button_t_check_button_set_value">check\_button\_set\_value</a> |  设置控件的值。 |
+| <a href="#check_button_t_check_button_cast">check\_button\_cast</a> | 转换check_button对象(供脚本语言使用)。 |
+| <a href="#check_button_t_check_button_create">check\_button\_create</a> | 创建check_button对象 |
+| <a href="#check_button_t_check_button_create_radio">check\_button\_create\_radio</a> | 创建check_button对象 |
+| <a href="#check_button_t_check_button_set_value">check\_button\_set\_value</a> | 设置控件的值。 |
 ### 属性
 <p id="check_button_t_properties">
 
 | 名属性称 | 类型 | 说明 | 
 | -------- | ----- | ------------ | 
-| <a href="#check_button_t_value">value</a> | bool_t |  值。 |
+| <a href="#check_button_t_value">value</a> | bool_t | 值。 |
 ### 事件
 <p id="check_button_t_events">