From 9273cbf5e52fad244203c4d727e841c7f69790e9 Mon Sep 17 00:00:00 2001 From: xianjimli Date: Wed, 20 Feb 2019 15:25:09 +0800 Subject: [PATCH] update user manual --- docs/manual/asset_type_t.md | 1 + docs/manual/button_t.md | 45 ++++ docs/manual/combo_box_t.md | 23 ++ docs/manual/darray_t.md | 71 ++++++ docs/manual/emitter_t.md | 24 ++ docs/manual/event_base_type_t.md | 1 + docs/manual/event_type_t.md | 1 + docs/manual/image_animation_t.md | 64 +++++ docs/manual/image_manager_t.md | 24 ++ docs/manual/object_default_t.md | 26 ++ docs/manual/object_t.md | 391 ++++++++++++++++++++++++++++++- docs/manual/ret_t.md | 1 + docs/manual/slide_menu_t.md | 2 +- docs/manual/str_t.md | 47 ++++ docs/manual/timer_t.md | 23 ++ docs/manual/tokenizer_t.md | 68 +++++- docs/manual/widget_prop_t.md | 2 +- docs/manual/widget_t.md | 80 ++++++- docs/manual/window_base_t.md | 17 -- docs/manual/wstr_t.md | 23 ++ tools/doc_gen/README.md | 14 +- 21 files changed, 920 insertions(+), 28 deletions(-) diff --git a/docs/manual/asset_type_t.md b/docs/manual/asset_type_t.md index 9d2d19e4b..ab501ecb7 100644 --- a/docs/manual/asset_type_t.md +++ b/docs/manual/asset_type_t.md @@ -14,4 +14,5 @@ | ASSET\_TYPE\_UI | UI数据资源。 | | ASSET\_TYPE\_XML | XML数据资源。 | | ASSET\_TYPE\_STRINGS | 字符串数据资源。 | +| ASSET\_TYPE\_SCRIPT | JS等脚本资源。 | | ASSET\_TYPE\_DATA | 其它数据资源。 | diff --git a/docs/manual/button_t.md b/docs/manual/button_t.md index ee834ae55..618efc39d 100644 --- a/docs/manual/button_t.md +++ b/docs/manual/button_t.md @@ -55,12 +55,14 @@ | -------- | ------------ | | button\_cast | 转换为button对象(供脚本语言使用)。 | | button\_create | 创建button对象 | +| button\_set\_enable\_long\_press | 设置是否启用长按事件。 | | button\_set\_repeat | 设置触发EVT\_CLICK事件的时间间隔。为0则不重复触发EVT\_CLICK事件。 | ### 属性

| 属性名称 | 类型 | 说明 | | -------- | ----- | ------------ | +| enable\_long\_press | bool\_t | | | repeat | int32\_t | 重复触发EVT\_CLICK事件的时间间隔。 | ### 事件

@@ -115,6 +117,28 @@ widget_t* button_create (widget_t* parent, xy_t x, xy_t y, wh_t w, wh_t h); | y | xy\_t | y坐标 | | w | wh\_t | 宽度 | | h | wh\_t | 高度 | +#### button\_set\_enable\_long\_press 函数 +----------------------- + +* 函数功能： + +>

设置是否启用长按事件。 + + + +* 函数原型： + +``` +ret_t button_set_enable_long_press (widget_t* widget, bool_t enable_long_press); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| widget | widget\_t* | 控件对象。 | +| enable\_long\_press | bool\_t | 是否启用长按事件。 | #### button\_set\_repeat 函数 ----------------------- @@ -137,6 +161,27 @@ ret_t button_set_repeat (widget_t* widget, int32_t repeat); | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | widget | widget\_t* | 控件对象。 | | repeat | int32\_t | 触发EVT\_CLICK事件的时间间隔(毫秒)。 | +#### enable\_long\_press 属性 +----------------------- +>

+ 是否启用长按事件，为true时才触发长按事件。 + 触发长按事件后不再触发点击事件。 + 缺省不启用。 + + + +* 类型：bool\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +| 可持久化 | 是 | +| 可脚本化 | 是 | +| 可在IDE中设置 | 是 | +| 可在XML中设置 | 是 | +| 可通过widget\_get\_prop读取 | 是 | +| 可通过widget\_set\_prop修改 | 是 | #### repeat 属性 ----------------------- >

重复触发EVT\_CLICK事件的时间间隔。 diff --git a/docs/manual/combo_box_t.md b/docs/manual/combo_box_t.md index a63a79e5b..6434a747f 100644 --- a/docs/manual/combo_box_t.md +++ b/docs/manual/combo_box_t.md @@ -92,6 +92,7 @@ default](https://github.com/zlgopen/awtk/blob/master/demos/assets/raw/styles/def | combo\_box\_set\_open\_window | 点击按钮时可以打开popup窗口，本函数可设置窗口的名称。 | | combo\_box\_set\_options | 设置选项。 | | combo\_box\_set\_selected\_index | 设置第index个选项为当前选中的选项。 | +| combo\_box\_set\_value | 设置值。 | ### 属性

@@ -349,6 +350,28 @@ ret_t combo_box_set_selected_index (widget_t* widget, uint32_t index); | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | widget | widget\_t* | combo\_box对象。 | | index | uint32\_t | 选项的索引。 | +#### combo\_box\_set\_value 函数 +----------------------- + +* 函数功能： + +>

设置值。 + + + +* 函数原型： + +``` +ret_t combo_box_set_value (widget_t* widget, int32_t value); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| widget | widget\_t* | combo\_box对象。 | +| value | int32\_t | 值。 | #### open\_window 属性 ----------------------- >

为点击按钮时，要打开窗口的名称。 diff --git a/docs/manual/darray_t.md b/docs/manual/darray_t.md index 0a860bd7f..04c46b9f5 100644 --- a/docs/manual/darray_t.md +++ b/docs/manual/darray_t.md @@ -34,12 +34,15 @@ | darray\_destroy | 销毁darray对象。 | | darray\_find | 查找第一个满足条件的元素。 | | darray\_find\_index | 查找第一个满足条件的元素，并返回位置。 | +| darray\_foreach | 遍历元素。 | +| darray\_head | 返回第一个元素。 | | darray\_init | 初始化darray对象。 | | darray\_pop | 弹出最后一个元素。 | | darray\_push | 在尾巴追加一个元素。 | | darray\_remove | 删除第一个满足条件的元素。 | | darray\_remove\_all | 删除全部满足条件的元素。 | | darray\_remove\_index | 删除指定位置的元素。 | +| darray\_tail | 返回最后一个元素。 | ### 属性

@@ -210,6 +213,52 @@ int darray_find_index (darray_t* darray, void* ctx); | 返回值 | int | 如果找到，返回满足条件的对象的位置，否则返回-1。 | | darray | darray\_t* | 数组对象。 | | ctx | void* | 比较函数的上下文。 | +#### darray\_foreach 函数 +----------------------- + +* 函数功能： + +>

遍历元素。 + + + + +* 函数原型： + +``` +ret_t darray_foreach (darray_t* darray, tk_visit_t visit, void* ctx); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| darray | darray\_t* | 数组对象。 | +| visit | tk\_visit\_t | 遍历函数。 | +| ctx | void* | 遍历函数的上下文。 | +#### darray\_head 函数 +----------------------- + +* 函数功能： + +>

返回第一个元素。 + + + + +* 函数原型： + +``` +void* darray_head (darray_t* darray); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | void* | 成功返回最后一个元素，失败返回NULL。 | +| darray | darray\_t* | 数组对象。 | #### darray\_init 函数 ----------------------- @@ -350,6 +399,28 @@ ret_t darray_remove_index (darray_t* darray, uint32_t index); | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | darray | darray\_t* | 数组对象。 | | index | uint32\_t | 位置序数。 | +#### darray\_tail 函数 +----------------------- + +* 函数功能： + +>

返回最后一个元素。 + + + + +* 函数原型： + +``` +void* darray_tail (darray_t* darray); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | void* | 成功返回最后一个元素，失败返回NULL。 | +| darray | darray\_t* | 数组对象。 | #### capacity 属性 ----------------------- >

数组的容量大小。 diff --git a/docs/manual/emitter_t.md b/docs/manual/emitter_t.md index b3c7754be..7125722b2 100644 --- a/docs/manual/emitter_t.md +++ b/docs/manual/emitter_t.md @@ -20,6 +20,7 @@ | emitter\_find | 通过ID查找emitter_item_t，主要用于辅助测试。 | | emitter\_init | 初始化emitter对象。 | | emitter\_off | 注销指定事件的处理函数。 | +| emitter\_off\_by\_ctx | 注销指定事件的处理函数。 | | emitter\_off\_by\_func | 注销指定事件的处理函数。 | | emitter\_on | 注册指定事件的处理函数。 | | emitter\_set\_on\_destroy | 设置一个回调函数，在emitter被销毁时调用(方便脚本语言去释放回调函数)。 | @@ -260,6 +261,29 @@ ret_t emitter_off (emitter_t* emitter, uint32_t id); | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | emitter | emitter\_t* | emitter对象。 | | id | uint32\_t | emitter\_on返回的ID。 | +#### emitter\_off\_by\_ctx 函数 +----------------------- + +* 函数功能： + +>

注销指定事件的处理函数。 + + + + +* 函数原型： + +``` +ret_t emitter_off_by_ctx (emitter_t* emitter, void* ctx); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| emitter | emitter\_t* | emitter对象。 | +| ctx | void* | 事件处理函数上下文。 | #### emitter\_off\_by\_func 函数 ----------------------- diff --git a/docs/manual/event_base_type_t.md b/docs/manual/event_base_type_t.md index 2b53e7941..491990137 100644 --- a/docs/manual/event_base_type_t.md +++ b/docs/manual/event_base_type_t.md @@ -9,4 +9,5 @@ | -------- | ------- | | EVT\_PROP\_WILL\_CHANGE | 对象的属性即将改变的事件名(prop\_change\_event\_t)。 | | EVT\_PROP\_CHANGED | 对象的属性改变的事件名(prop\_change\_event\_t)。 | +| EVT\_PROPS\_CHANGED | 对象的属性改变的事件名(props\_event\_t)。 | | EVT\_DESTROY | 对象销毁事件名(event\_t)。 | diff --git a/docs/manual/event_type_t.md b/docs/manual/event_type_t.md index 61b280add..28bfb76f3 100644 --- a/docs/manual/event_type_t.md +++ b/docs/manual/event_type_t.md @@ -56,5 +56,6 @@ | EVT\_DRAG\_START | 开始拖动(event\_t)。 | | EVT\_DRAG | 拖动(event\_t)。 | | EVT\_DRAG\_END | 结束拖动(event\_t)。 | +| EVT\_SCREEN\_SAVER | 在指定的时间内(WITH\_SCREEN\_SAVER\_TIME)，没有用户输入事件，由窗口管理器触发。 | | EVT\_REQ\_START | event queue其它请求编号起始值。 | | EVT\_USER\_START | 用户定义事件起始值。 | diff --git a/docs/manual/image_animation_t.md b/docs/manual/image_animation_t.md index 57348ecb2..e97c49119 100644 --- a/docs/manual/image_animation_t.md +++ b/docs/manual/image_animation_t.md @@ -4,12 +4,16 @@ 图片动画控件，指定一个图片前缀，依次显示指定序列的图片，从而形成动画效果。 + 图片序列可以用sequence指定，也可以用start\_index和end\_index指定一个范围。 + image\_animation\_t是[widget\_t](widget_t.md)的子类控件，widget\_t的函数均适用于image\_animation\_t控件。 在xml中使用"image\_animation"标签创建图片动画控件。如： ```xml + ``` > 更多用法请参考： @@ -47,6 +51,7 @@ | image\_animation\_set\_image | 设置图片前缀。 | | image\_animation\_set\_interval | 设置播放间隔时间。 | | image\_animation\_set\_loop | 设置是否循环播放。 | +| image\_animation\_set\_range\_sequence | 设置播放序列。比如image为"fire"，max_nr为100, 将依次播放"fire0", ..., "fire99"。 | | image\_animation\_set\_sequence | 设置播放序列。比如image为"fire"，sequence为"123", 将依次播放"fire1", "fire2", "fire3"。 | | image\_animation\_stop | 停止(并重置index为0)。 | ### 属性 @@ -56,10 +61,12 @@ | -------- | ----- | ------------ | | auto\_play | bool\_t | 是否自动播放。 | | delay | uint32\_t | 自动播放时延迟播放的时间(毫秒)。 | +| end\_index | uint32\_t | 图片结束序数。 | | image | char* | 图片名称的前缀。 | | interval | uint32\_t | 每张图片播放的时间(毫秒)。 | | loop | bool\_t | 是否循环播放。 | | sequence | char* | 播放的序列，字符可选值为:0-9,a-z,A-Z。 | +| start\_index | uint32\_t | 图片起始序数。 | #### image\_animation\_cast 函数 ----------------------- @@ -258,6 +265,29 @@ ret_t image_animation_set_loop (widget_t* widget, bool_t loop); | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | widget | widget\_t* | image\_animation对象。 | | loop | bool\_t | 是否循环播放。 | +#### image\_animation\_set\_range\_sequence 函数 +----------------------- + +* 函数功能： + +>

设置播放序列。比如image为"fire"，max_nr为100, 将依次播放"fire0", ..., "fire99"。 + + + +* 函数原型： + +``` +ret_t image_animation_set_range_sequence (widget_t* widget, uint32_t start_index, uint32_t end_index); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| widget | widget\_t* | image\_animation对象。 | +| start\_index | uint32\_t | 图片起始序数。 | +| end\_index | uint32\_t | 图片结束序数。 | #### image\_animation\_set\_sequence 函数 ----------------------- @@ -323,6 +353,23 @@ ret_t image_animation_stop (widget_t* widget); >

自动播放时延迟播放的时间(毫秒)。 +* 类型：uint32\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +| 可持久化 | 是 | +| 可脚本化 | 是 | +| 可在IDE中设置 | 是 | +| 可在XML中设置 | 是 | +| 可通过widget\_get\_prop读取 | 是 | +| 可通过widget\_set\_prop修改 | 是 | +#### end\_index 属性 +----------------------- +>

图片结束序数。 + + * 类型：uint32\_t | 特性 | 是否支持 | @@ -403,3 +450,20 @@ ret_t image_animation_stop (widget_t* widget); | 可在XML中设置 | 是 | | 可通过widget\_get\_prop读取 | 是 | | 可通过widget\_set\_prop修改 | 是 | +#### start\_index 属性 +----------------------- +>

图片起始序数。 + + +* 类型：uint32\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +| 可持久化 | 是 | +| 可脚本化 | 是 | +| 可在IDE中设置 | 是 | +| 可在XML中设置 | 是 | +| 可通过widget\_get\_prop读取 | 是 | +| 可通过widget\_set\_prop修改 | 是 | diff --git a/docs/manual/image_manager_t.md b/docs/manual/image_manager_t.md index e2bf3a9d8..7252090a8 100644 --- a/docs/manual/image_manager_t.md +++ b/docs/manual/image_manager_t.md @@ -17,6 +17,7 @@ | image\_manager\_init | 初始化图片管理器。 | | image\_manager\_set | 设置缺省的图片管理器。 | | image\_manager\_set\_assets\_manager | 设置资源管理器对象。 | +| image\_manager\_unload\_bitmap | 从图片管理器中卸载指定的图片。 | | image\_manager\_unload\_unused | 从图片管理器中卸载指定时间内没有使用的图片。 | | image\_manager\_update\_specific | 更新缓存中图片的specific信息。 | ### 属性 @@ -213,6 +214,29 @@ ret_t image_manager_set_assets_manager (image_manager_t* imm, assets_manager_t* | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | imm | image\_manager\_t* | 图片管理器对象。 | | assets\_manager | assets\_manager\_t* | 资源管理器。 | +#### image\_manager\_unload\_bitmap 函数 +----------------------- + +* 函数功能： + +>

从图片管理器中卸载指定的图片。 + + + + +* 函数原型： + +``` +ret_t image_manager_unload_bitmap (image_manager_t* imm, bitmap_t* image); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| imm | image\_manager\_t* | 图片管理器对象。 | +| image | bitmap\_t* | 图片。 | #### image\_manager\_unload\_unused 函数 ----------------------- diff --git a/docs/manual/object_default_t.md b/docs/manual/object_default_t.md index 68baf99e3..0c37dd95a 100644 --- a/docs/manual/object_default_t.md +++ b/docs/manual/object_default_t.md @@ -16,6 +16,7 @@ | 函数名称 | 说明 | | -------- | ------------ | | object\_default\_create | | +| object\_default\_unref | | ### 属性

@@ -48,6 +49,31 @@ object_t* object_default_create (); | 参数 | 类型 | 说明 | | -------- | ----- | --------- | | 返回值 | object\_t* | 返回object对象。 | +#### object\_default\_unref 函数 +----------------------- + +* 函数功能： + +>

+ for script gc + + + + + + +* 函数原型： + +``` +ret_t object_default_unref (object_t* obj); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | 对象。 | #### props 属性 ----------------------- >

属性数组。 diff --git a/docs/manual/object_t.md b/docs/manual/object_t.md index 97314263d..63aaf5bb2 100644 --- a/docs/manual/object_t.md +++ b/docs/manual/object_t.md @@ -13,14 +13,29 @@ | 函数名称 | 说明 | | -------- | ------------ | +| object\_can\_exec | 检查是否可以执行指定的命令。 | | object\_compare | 比较两个对象。 | | object\_create | 创建对象。 | +| object\_eval | 计算一个表达式，表达式中引用的变量从prop中获取。 | +| object\_exec | 执行指定的命令。 | | object\_foreach\_prop | 遍历所有属性。 | | object\_get\_prop | 获取指定属性的值。 | +| object\_get\_prop\_float | 获取指定属性的浮点数类型的值。 | +| object\_get\_prop\_int | 获取指定属性的整数类型的值。 | +| object\_get\_prop\_object | 获取指定属性的object类型的值。 | +| object\_get\_prop\_pointer | 获取指定属性的指针类型的值。 | +| object\_get\_prop\_str | 获取指定属性的字符串类型的值。 | +| object\_has\_prop | 检查是否存在指定的属性。 | +| object\_notify\_changed | 触发EVT_PROPS_CHANGED事件。 | | object\_ref | 引用计数加1。 | | object\_remove\_prop | 删除指定属性。 | | object\_set\_name | 设置对象的名称。 | | object\_set\_prop | 设置指定属性的值。 | +| object\_set\_prop\_float | 设置指定属性的浮点数类型的值。 | +| object\_set\_prop\_int | 设置指定属性的整数类型的值。 | +| object\_set\_prop\_object | 设置指定属性的object类型的值。 | +| object\_set\_prop\_pointer | 设置指定属性的指针类型的值。 | +| object\_set\_prop\_str | 设置指定属性的字符串类型的值。 | | object\_unref | 引用计数减1。引用计数为0时，销毁对象。 | ### 属性

@@ -29,6 +44,31 @@ | -------- | ----- | ------------ | | name | char* | 对象的名称。 | | ref\_count | int32\_t | 引用计数。 | +#### object\_can\_exec 函数 +----------------------- + +* 函数功能： + +>

检查是否可以执行指定的命令。 + + + + + +* 函数原型： + +``` +bool_t object_can_exec (object_t* obj, const char* name, const char* args); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | bool\_t | 返回TRUE表示可以执行，否则表示不可以执行。 | +| obj | object\_t* | object对象。 | +| name | const char* | 命令的名称。 | +| args | const char* | 命令的参数。 | #### object\_compare 函数 ----------------------- @@ -43,14 +83,14 @@ * 函数原型： ``` -int32_t object_compare (object_t* obj, object_t* other); +int object_compare (object_t* obj, object_t* other); ``` * 参数说明： | 参数 | 类型 | 说明 | | -------- | ----- | --------- | -| 返回值 | int32\_t | 返回比较结果。 | +| 返回值 | int | 返回比较结果。 | | obj | object\_t* | object对象。 | | other | object\_t* | 比较的object对象。 | #### object\_create 函数 @@ -78,6 +118,55 @@ ret_t object_create (const object_vtable_t* vt); | -------- | ----- | --------- | | 返回值 | ret\_t | 返回object对象。 | | vt | const object\_vtable\_t* | 虚函数表。 | +#### object\_eval 函数 +----------------------- + +* 函数功能： + +>

计算一个表达式，表达式中引用的变量从prop中获取。 + + + + + +* 函数原型： + +``` +ret_t object_eval (object_t* obj, const char* expr, value_t* v); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | object对象。 | +| expr | const char* | 表达式。 | +| v | value\_t* | 返回计算结果。 | +#### object\_exec 函数 +----------------------- + +* 函数功能： + +>

执行指定的命令。 + + + + +* 函数原型： + +``` +ret_t object_exec (object_t* obj, const char* name, const char* args); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | object对象。 | +| name | const char* | 命令的名称。 | +| args | const char* | 命令的参数。 | #### object\_foreach\_prop 函数 ----------------------- @@ -128,6 +217,175 @@ ret_t object_get_prop (object_t* obj, const char* name, value_t* v); | obj | object\_t* | object对象。 | | name | const char* | 属性的名称。 | | v | value\_t* | 返回属性的值。 | +#### object\_get\_prop\_float 函数 +----------------------- + +* 函数功能： + +>

获取指定属性的浮点数类型的值。 + + + + + +* 函数原型： + +``` +float_t object_get_prop_float (object_t* obj, const char* name, float_t defval); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | float\_t | 返回指定属性的浮点数类型的值。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +| defval | float\_t | 缺省值。 | +#### object\_get\_prop\_int 函数 +----------------------- + +* 函数功能： + +>

获取指定属性的整数类型的值。 + + + + + +* 函数原型： + +``` +int32_t object_get_prop_int (object_t* obj, const char* name, int32_t defval); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | int32\_t | 返回指定属性的整数类型的值。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +| defval | int32\_t | 缺省值。 | +#### object\_get\_prop\_object 函数 +----------------------- + +* 函数功能： + +>

获取指定属性的object类型的值。 + + + + + +* 函数原型： + +``` +object_t* object_get_prop_object (object_t* obj, const char* name); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | object\_t* | 返回指定属性的object类型的值。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +#### object\_get\_prop\_pointer 函数 +----------------------- + +* 函数功能： + +>

获取指定属性的指针类型的值。 + + + + + +* 函数原型： + +``` +void* object_get_prop_pointer (object_t* obj, const char* name); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | void* | 返回指定属性的指针类型的值。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +#### object\_get\_prop\_str 函数 +----------------------- + +* 函数功能： + +>

获取指定属性的字符串类型的值。 + + + + + +* 函数原型： + +``` +const char* object_get_prop_str (object_t* obj, const char* name); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | const char* | 返回指定属性的字符串类型的值。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +#### object\_has\_prop 函数 +----------------------- + +* 函数功能： + +>

检查是否存在指定的属性。 + + + + + +* 函数原型： + +``` +bool_t object_has_prop (object_t* obj, const char* name); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | bool\_t | 返回TRUE表示存在，否则表示不存在。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +#### object\_notify\_changed 函数 +----------------------- + +* 函数功能： + +>

触发EVT_PROPS_CHANGED事件。 + + + + + +* 函数原型： + +``` +ret_t object_notify_changed (object_t* obj); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | object对象。 | #### object\_ref 函数 ----------------------- @@ -213,7 +471,7 @@ ret_t object_set_name (object_t* obj, const char* name); * 函数原型： ``` -ret_t object_set_prop (object_t* obj, const char* name, value_t* v); +ret_t object_set_prop (object_t* obj, const char* name, value_t* value); ``` * 参数说明： @@ -223,7 +481,132 @@ ret_t object_set_prop (object_t* obj, const char* name, value_t* v); | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | obj | object\_t* | object对象。 | | name | const char* | 属性的名称。 | -| v | value\_t* | 属性的值。 | +| value | value\_t* | 属性的值。 | +#### object\_set\_prop\_float 函数 +----------------------- + +* 函数功能： + +>

设置指定属性的浮点数类型的值。 + + + + + +* 函数原型： + +``` +ret_t object_set_prop_float (object_t* obj, const char* name, float_t value); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +| value | float\_t | 属性的值。 | +#### object\_set\_prop\_int 函数 +----------------------- + +* 函数功能： + +>

设置指定属性的整数类型的值。 + + + + + +* 函数原型： + +``` +ret_t object_set_prop_int (object_t* obj, const char* name, int32_t value); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +| value | int32\_t | 属性的值。 | +#### object\_set\_prop\_object 函数 +----------------------- + +* 函数功能： + +>

设置指定属性的object类型的值。 + + + + + +* 函数原型： + +``` +ret_t object_set_prop_object (object_t* obj, const char* name, object_t* value); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +| value | object\_t* | 属性的值。 | +#### object\_set\_prop\_pointer 函数 +----------------------- + +* 函数功能： + +>

设置指定属性的指针类型的值。 + + + + + +* 函数原型： + +``` +ret_t object_set_prop_pointer (object_t* obj, const char* name, void* value); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +| value | void* | 属性的值。 | +#### object\_set\_prop\_str 函数 +----------------------- + +* 函数功能： + +>

设置指定属性的字符串类型的值。 + + + + + +* 函数原型： + +``` +ret_t object_set_prop_str (object_t* obj, const char* name, const char* value); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| obj | object\_t* | object对象。 | +| name | const char* | 属性的名称。 | +| value | const char* | 属性的值。 | #### object\_unref 函数 ----------------------- diff --git a/docs/manual/ret_t.md b/docs/manual/ret_t.md index 1e81f7491..ef75a93f2 100644 --- a/docs/manual/ret_t.md +++ b/docs/manual/ret_t.md @@ -19,4 +19,5 @@ | RET\_DONE | 操作完成。 | | RET\_STOP | 停止后续操作。 | | RET\_CONTINUE | 继续后续操作。 | +| RET\_OBJECT\_CHANGED | 对象属性变化。 | | RET\_BAD\_PARAMS | 无效参数。 | diff --git a/docs/manual/slide_menu_t.md b/docs/manual/slide_menu_t.md index c7663b5dc..e106a392b 100644 --- a/docs/manual/slide_menu_t.md +++ b/docs/manual/slide_menu_t.md @@ -42,7 +42,7 @@ ```c widget_on(slide_menu, EVT_VALUE_CHANGED, on_current_changed, slide_menu); ``` - + 可按下面的方法关注当前按钮被点击的事件： ```c diff --git a/docs/manual/str_t.md b/docs/manual/str_t.md index 62aabe532..3632645c5 100644 --- a/docs/manual/str_t.md +++ b/docs/manual/str_t.md @@ -27,10 +27,12 @@ | str\_append | 追加字符串。 | | str\_append\_char | 追加一个字符。 | | str\_append\_with\_len | 追加字符串。 | +| str\_clear | 清除字符串内容。 | | str\_decode\_xml\_entity | 对XML基本的entity进行解码，目前仅支持<>"a;&。 | | str\_decode\_xml\_entity\_with\_len | 对XML基本的entity进行解码，目前仅支持<>"a;&。 | | str\_end\_with | 判断字符串是否以指定的子串结尾。 | | str\_eq | 判断两个字符串是否相等。 | +| str\_extend | 扩展字符串到指定的容量。 | | str\_from\_float | 用浮点数初始化字符串。 | | str\_from\_int | 用整数初始化字符串。 | | str\_from\_value | 用value初始化字符串。 | @@ -130,6 +132,28 @@ ret_t str_append_with_len (str_t* str, char* text, uint32_t len); | str | str\_t* | str对象。 | | text | char* | 要追加的字符串。 | | len | uint32\_t | 字符串长度。 | +#### str\_clear 函数 +----------------------- + +* 函数功能： + +>

清除字符串内容。 + + + + +* 函数原型： + +``` +ret_t str_clear (str_t* str); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| str | str\_t* | str对象。 | #### str\_decode\_xml\_entity 函数 ----------------------- @@ -223,6 +247,29 @@ bool_t str_eq (str_t* str, char* text); | 返回值 | bool\_t | 返回是否相等。 | | str | str\_t* | str对象。 | | text | char* | 待比较的字符串。 | +#### str\_extend 函数 +----------------------- + +* 函数功能： + +>

扩展字符串到指定的容量。 + + + + +* 函数原型： + +``` +ret_t str_extend (str_t* str, uint32_t capacity); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| str | str\_t* | str对象。 | +| capacity | uint32\_t | 初始容量。 | #### str\_from\_float 函数 ----------------------- diff --git a/docs/manual/timer_t.md b/docs/manual/timer_t.md index 022f76c9b..868707057 100644 --- a/docs/manual/timer_t.md +++ b/docs/manual/timer_t.md @@ -33,6 +33,7 @@ | timer\_now | 获取当前时间(ms)。 | | timer\_queue | 用于非GUI线程增加一个timer，本函数向主循环的事件队列中发送一个增加timer的请求。 | | timer\_remove | 删除指定的timer。 | +| timer\_reset | 重置指定的timer，重置之后定时器重新开始计时。 | | timer\_set\_on\_destroy | 设置一个回调函数，在timer被销毁时调用(方便脚本语言去释放回调函数)。 | #### timer\_add 函数 ----------------------- @@ -164,6 +165,28 @@ ret_t timer_remove (uint32_t timer_id); * 参数说明： +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| timer\_id | uint32\_t | timerID。 | +#### timer\_reset 函数 +----------------------- + +* 函数功能： + +>

重置指定的timer，重置之后定时器重新开始计时。 + + + + +* 函数原型： + +``` +ret_t timer_reset (uint32_t timer_id); +``` + +* 参数说明： + | 参数 | 类型 | 说明 | | -------- | ----- | --------- | | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | diff --git a/docs/manual/tokenizer_t.md b/docs/manual/tokenizer_t.md index 0cd242ac5..06796686c 100644 --- a/docs/manual/tokenizer_t.md +++ b/docs/manual/tokenizer_t.md @@ -12,16 +12,19 @@ | tokenizer\_deinit | 重置tokenizer。 | | tokenizer\_has\_more | 是否还有下一个token。 | | tokenizer\_init | 初始化tokenizer对象。 | +| tokenizer\_init\_ex | 初始化tokenizer对象。 | | tokenizer\_next | 获取下一个token。 | | tokenizer\_next\_float | 获取下一个token，并转换成float。 | | tokenizer\_next\_int | 获取下一个token，并转换成int。 | +| tokenizer\_next\_until | 获取下一个token，该token直到遇到指定的char。 | ### 属性

| 属性名称 | 类型 | 说明 | | -------- | ----- | ------------ | | cursor | uint32\_t | 当前位置。 | -| separtor | char* | 字符串。 | +| separtor | char* | 分隔字符串。 | +| single\_char\_token | char* | 单字符的token。 | | size | uint32\_t | 字符串的长度。 | | str | char* | 字符串。 | #### tokenizer\_deinit 函数 @@ -93,6 +96,32 @@ tokenizer_t* tokenizer_init (tokenizer_t* tokenizer, char* str, uint32_t size, c | str | char* | 要解析的字符串。 | | size | uint32\_t | 字符串长度。 | | separtor | char* | 分隔字符。 | +#### tokenizer\_init\_ex 函数 +----------------------- + +* 函数功能： + +>

初始化tokenizer对象。 + + + + +* 函数原型： + +``` +tokenizer_t* tokenizer_init_ex (tokenizer_t* tokenizer, char* str, uint32_t size, char* separtor, char* single_char_token); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | tokenizer\_t* | tokenizer对象本身。 | +| tokenizer | tokenizer\_t* | tokenizer对象。 | +| str | char* | 要解析的字符串。 | +| size | uint32\_t | 字符串长度。 | +| separtor | char* | 分隔字符。 | +| single\_char\_token | char* | 单字符token。 | #### tokenizer\_next 函数 ----------------------- @@ -161,6 +190,29 @@ char* tokenizer_next_int (tokenizer_t* tokenizer, int defval); | 返回值 | char* | 成功返回token的int值，失败返回缺省值。 | | tokenizer | tokenizer\_t* | tokenizer对象。 | | defval | int | 缺省值。 | +#### tokenizer\_next\_until 函数 +----------------------- + +* 函数功能： + +>

获取下一个token，该token直到遇到指定的char。 + + + + +* 函数原型： + +``` +char* tokenizer_next_until (tokenizer_t* tokenizer, const char* str); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | char* | 成功返回token，失败返回NULL。 | +| tokenizer | tokenizer\_t* | tokenizer对象。 | +| str | const char* | 字符集。 | #### cursor 属性 ----------------------- >

当前位置。 @@ -175,7 +227,19 @@ char* tokenizer_next_int (tokenizer_t* tokenizer, int defval); | 可直接修改 | 否 | #### separtor 属性 ----------------------- ->

字符串。 +>

分隔字符串。 + + + +* 类型：char* + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### single\_char\_token 属性 +----------------------- +>

单字符的token。 diff --git a/docs/manual/widget_prop_t.md b/docs/manual/widget_prop_t.md index 08d412cfe..28951fb57 100644 --- a/docs/manual/widget_prop_t.md +++ b/docs/manual/widget_prop_t.md @@ -72,13 +72,13 @@ | WIDGET\_PROP\_FONT\_MANAGER | 字体管理器。 | | WIDGET\_PROP\_THEME\_OBJ | 窗口的主题对象。 | | WIDGET\_PROP\_DEFAULT\_THEME\_OBJ | 缺省的主题对象。 | -| WIDGET\_PROP\_SCRIPT | | | WIDGET\_PROP\_ITEM\_WIDTH | | | WIDGET\_PROP\_ITEM\_HEIGHT | | | WIDGET\_PROP\_DEFAULT\_ITEM\_HEIGHT | | | WIDGET\_PROP\_XSLIDABLE | | | WIDGET\_PROP\_YSLIDABLE | | | WIDGET\_PROP\_REPEAT | | +| WIDGET\_PROP\_ENABLE\_LONG\_PRESS | | | WIDGET\_PROP\_ANIMATABLE | | | WIDGET\_PROP\_AUTO\_HIDE\_SCROLL\_BAR | | | WIDGET\_PROP\_IMAGE | | diff --git a/docs/manual/widget_t.md b/docs/manual/widget_t.md index 099dfdbfc..b2e20df68 100644 --- a/docs/manual/widget_t.md +++ b/docs/manual/widget_t.md @@ -73,6 +73,7 @@ | widget\_get\_prop\_bool | 获取布尔格式的属性。 | | widget\_get\_prop\_default\_value | 获取控件指定属性的缺省值(在持久化控件时，无需保存缺省值)。 | | widget\_get\_prop\_int | 获取整数格式的属性。 | +| widget\_get\_prop\_pointer | 获取指针格式的属性。 | | widget\_get\_prop\_str | 获取字符串格式的属性。 | | widget\_get\_text | 获取控件的文本。 | | widget\_get\_type | 获取当前控件的类型名称。 | @@ -112,6 +113,7 @@ | widget\_set\_prop | 设置控件指定属性的值。 | | widget\_set\_prop\_bool | 设置布尔格式的属性。 | | widget\_set\_prop\_int | 设置整数格式的属性。 | +| widget\_set\_prop\_pointer | 设置指针格式的属性。 | | widget\_set\_prop\_str | 设置字符串格式的属性。 | | widget\_set\_self\_layout | 设置控件自己的布局参数。 | | widget\_set\_self\_layout\_params | 设置控件自己的布局(缺省布局器)参数(过时，请用widget\_set\_self\_layout)。 | @@ -129,6 +131,7 @@ | widget\_to\_screen | 将控件内的本地坐标转换成屏幕上的坐标。 | | widget\_ungrab | 让指定子控件放弃抓住事件。 | | widget\_unload\_asset | 卸载资源。 | +| widget\_unload\_image | 卸载图片。 | | widget\_use\_style | 启用指定的主题。 | ### 属性

@@ -141,7 +144,7 @@ | can\_not\_destroy | uint16\_t | 标识控件目前不能被销毁(比如正在分发事件)，如果此时调用widget\_destroy，自动异步处理。 | | children | darray\_t* | 全部子控件。 | | children\_layout | children\_layouter\_t* | 子控件布局器。请参考[控件布局参数](https://github.com/zlgopen/awtk/blob/master/docs/layout.md) | -| custom\_props | custom\_props\_t* | 自定义属性。 | +| custom\_props | object\_t* | 自定义属性。 | | destroying | bool\_t | 标识控件正在被销毁。 | | dirty | bool\_t | 标识控件是否需要重绘。 | | emitter | emitter\_t* | 事件发射器。 | @@ -713,6 +716,29 @@ int32_t widget_get_prop_int (widget_t* widget, const char* name, int32_t defval) | widget | widget\_t* | 控件对象。 | | name | const char* | 属性的名称。 | | defval | int32\_t | 缺省值。 | +#### widget\_get\_prop\_pointer 函数 +----------------------- + +* 函数功能： + +>

获取指针格式的属性。 + + + + +* 函数原型： + +``` +void* widget_get_prop_pointer (widget_t* widget, const char* name); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | void* | 返回属性的值。 | +| widget | widget\_t* | 控件对象。 | +| name | const char* | 属性的名称。 | #### widget\_get\_prop\_str 函数 ----------------------- @@ -1662,6 +1688,30 @@ ret_t widget_set_prop_int (widget_t* widget, const char* name, int32_t v); | widget | widget\_t* | 控件对象。 | | name | const char* | 属性的名称。 | | v | int32\_t | 属性的值。 | +#### widget\_set\_prop\_pointer 函数 +----------------------- + +* 函数功能： + +>

设置指针格式的属性。 + + + + +* 函数原型： + +``` +ret_t widget_set_prop_pointer (widget_t* widget, const char* name, void** v); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| widget | widget\_t* | 控件对象。 | +| name | const char* | 属性的名称。 | +| v | void** | 属性的值。 | #### widget\_set\_prop\_str 函数 ----------------------- @@ -2081,6 +2131,32 @@ ret_t widget_unload_asset (widget_t* widget, const asset_info_t* asset); | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | widget | widget\_t* | 控件对象。 | | asset | const asset\_info\_t* | 资源句柄。 | +#### widget\_unload\_image 函数 +----------------------- + +* 函数功能： + +>

卸载图片。 + +> 一般不需要调用，只有确认在图片不再需要时才调用本函数卸载。 + + + + + +* 函数原型： + +``` +ret_t widget_unload_image (widget_t* widget, bitmap_t* bitmap); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| widget | widget\_t* | 控件对象。 | +| bitmap | bitmap\_t* | 图片对象。 | #### widget\_use\_style 函数 ----------------------- @@ -2191,7 +2267,7 @@ ret_t widget_use_style (widget_t* widget, char* style); -* 类型：custom\_props\_t* +* 类型：object\_t* | 特性 | 是否支持 | | -------- | ----- | diff --git a/docs/manual/window_base_t.md b/docs/manual/window_base_t.md index 1fa9549cd..0de0e5bdf 100644 --- a/docs/manual/window_base_t.md +++ b/docs/manual/window_base_t.md @@ -24,7 +24,6 @@ | font\_manager | font\_manager\_t* | 获取字体管理器对象。 | | image\_manager | image\_manager\_t* | 获取图片管理器对象。 | | open\_anim\_hint | char* | 打开窗口动画的名称。 | -| script | char* | 脚本文件名称(暂时没用)。 | | stage | char* | 窗口当前处于的状态。 | | theme | char* | 主题资源的名称。 | | theme\_obj | theme\_t* | 窗口的常量主题数据。 | @@ -124,22 +123,6 @@ 请参考[窗口动画](https://github.com/zlgopen/awtk/blob/master/docs/window_animator.md) -* 类型：char* - -| 特性 | 是否支持 | -| -------- | ----- | -| 可直接读取 | 是 | -| 可直接修改 | 否 | -| 可持久化 | 是 | -| 可在IDE中设置 | 是 | -| 可在XML中设置 | 是 | -| 可通过widget\_get\_prop读取 | 是 | -| 可通过widget\_set\_prop修改 | 是 | -#### script 属性 ------------------------ ->

脚本文件名称(暂时没用)。 - - * 类型：char* | 特性 | 是否支持 | diff --git a/docs/manual/wstr_t.md b/docs/manual/wstr_t.md index 22fa99ec0..b3754a1d5 100644 --- a/docs/manual/wstr_t.md +++ b/docs/manual/wstr_t.md @@ -26,6 +26,7 @@ | wstr\_add\_float | 将字符串转成浮点数，加上delta，再转换回来。 | | wstr\_append | 追加字符串。 | | wstr\_append\_with\_len | 追加字符串。 | +| wstr\_clear | 清除字符串内容。 | | wstr\_equal | 判断两个字符是否相同。 | | wstr\_from\_float | 用浮点数初始化字符串。 | | wstr\_from\_int | 用整数初始化字符串。 | @@ -121,6 +122,28 @@ ret_t wstr_append_with_len (wstr_t* str, wchar_t* text, uint32_t len); | str | wstr\_t* | str对象。 | | text | wchar\_t* | 要追加的字符串。 | | len | uint32\_t | 字符串长度。 | +#### wstr\_clear 函数 +----------------------- + +* 函数功能： + +>

清除字符串内容。 + + + + +* 函数原型： + +``` +ret_t wstr_clear (wstr_t* str); +``` + +* 参数说明： + +| 参数 | 类型 | 说明 | +| -------- | ----- | --------- | +| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | +| str | wstr\_t* | str对象。 | #### wstr\_equal 函数 ----------------------- diff --git a/tools/doc_gen/README.md b/tools/doc_gen/README.md index 5068f7974..19e4ffbfc 100644 --- a/tools/doc_gen/README.md +++ b/tools/doc_gen/README.md @@ -1 +1,13 @@ -# 用户生成API文档(working) +# 生成用户手册的工具 + +## 生成文档 + +``` +./gen.sh +``` + +## 同步到/docs/manual + +``` +./sync.sh +```