update docs

2024-12-01 19:49:11 +08:00 · 2020-08-20 11:21:16 +08:00 · 2020-08-20 11:21:16 +08:00 · 98be5e474f
commit 98be5e474f
parent 4e7d38d6fc
10 changed files with 199 additions and 1 deletions
--- a/docs/manual/button_t.md
+++ b/docs/manual/button_t.md
@ -55,6 +55,7 @@ default](https://github.com/zlgopen/awtk/blob/master/design/default/styles/defau
 | <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_enable_long_press">button\_set\_enable\_long\_press</a> | 设置是否启用长按事件。 |
+| <a href="#button_t_button_set_long_press_time">button\_set\_long\_press\_time</a> | 设置触发长按事件的时间。 |
 | <a href="#button_t_button_set_repeat">button\_set\_repeat</a> | 设置触发EVT\_CLICK事件的时间间隔。为0则不重复触发EVT\_CLICK事件。 |
 ### 属性
 <p id="button_t_properties">
@ -62,6 +63,7 @@ default](https://github.com/zlgopen/awtk/blob/master/design/default/styles/defau
 | 属性名称 | 类型 | 说明 | 
 | -------- | ----- | ------------ | 
 | <a href="#button_t_enable_long_press">enable\_long\_press</a> | bool\_t | 是否启用长按事件，为true时才触发长按事件。 |
+| <a href="#button_t_long_press_time">long\_press\_time</a> | uint32\_t | 触发长按事件的时间(ms) |
 | <a href="#button_t_repeat">repeat</a> | int32\_t | 重复触发EVT\_CLICK事件的时间间隔。 |
 ### 事件
 <p id="button_t_events">
@ -132,6 +134,26 @@ 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\_long\_press\_time 函数
+-----------------------
+
+* 函数功能：
+
+> <p id="button_t_button_set_long_press_time">设置触发长按事件的时间。
+
+* 函数原型：
+
+```
+ret_t button_set_long_press_time (widget_t* widget, uint32_t long_press_time);
+```
+
+* 参数说明：
+
+| 参数 | 类型 | 说明 |
+| -------- | ----- | --------- |
+| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
+| widget | widget\_t* | 控件对象。 |
+| long\_press\_time | uint32\_t | 触发长按事件的时间(毫秒)。 |
 #### button\_set\_repeat 函数
 -----------------------

@ -161,6 +183,22 @@ ret_t button_set_repeat (widget_t* widget, int32_t repeat);

 * 类型：bool\_t

+| 特性 | 是否支持 |
+| -------- | ----- |
+| 可直接读取 | 是 |
+| 可直接修改 | 否 |
+| 可持久化   | 是 |
+| 可脚本化   | 是 |
+| 可在IDE中设置 | 是 |
+| 可在XML中设置 | 是 |
+| 可通过widget\_get\_prop读取 | 是 |
+| 可通过widget\_set\_prop修改 | 是 |
+#### long\_press\_time 属性
+-----------------------
+> <p id="button_t_long_press_time">触发长按事件的时间(ms)
+
+* 类型：uint32\_t
+
 | 特性 | 是否支持 |
 | -------- | ----- |
 | 可直接读取 | 是 |
--- a/docs/manual/edit_t.md
+++ b/docs/manual/edit_t.md
@ -68,6 +68,7 @@ default](https://github.com/zlgopen/awtk/blob/master/design/default/styles/defau
 | <a href="#edit_t_edit_get_int">edit\_get\_int</a> | 获取int类型的值。 |
 | <a href="#edit_t_edit_set_action_text">edit\_set\_action\_text</a> | 设置软键盘上action按钮的文本。 |
 | <a href="#edit_t_edit_set_auto_fix">edit\_set\_auto\_fix</a> | 设置编辑器是否为自动改正。 |
+| <a href="#edit_t_edit_set_cancelable">edit\_set\_cancelable</a> | 设置编辑器是否为可撤销修改。 |
 | <a href="#edit_t_edit_set_cursor">edit\_set\_cursor</a> | 设置输入框的光标坐标。 |
 | <a href="#edit_t_edit_set_dec_value">edit\_set\_dec\_value</a> | 设置减少值的回调函数。 |
 | <a href="#edit_t_edit_set_double">edit\_set\_double</a> | 设置double类型的值。 |
@ -97,6 +98,7 @@ default](https://github.com/zlgopen/awtk/blob/master/design/default/styles/defau
 | <a href="#edit_t_action_text">action\_text</a> | char* | 软键盘上action按钮的文本。内置取值有： |
 | <a href="#edit_t_auto_fix">auto\_fix</a> | bool\_t | 输入无效时，是否自动改正。 |
 | <a href="#edit_t_bottom_margin">bottom\_margin</a> | uint8\_t | 下边距。 |
+| <a href="#edit_t_cancelable">cancelable</a> | bool\_t | 是否支持撤销编辑。如果为TRUE，在失去焦点之前可以撤销所有修改(恢复获得焦点之前的内容)。 |
 | <a href="#edit_t_input_type">input\_type</a> | input\_type\_t | 输入类型。 |
 | <a href="#edit_t_keyboard">keyboard</a> | char* | 自定义软键盘名称。AWTK优先查找keyboard属性设置的键盘文件名（该键盘的XML文件需要在default\raw\ui目录下存在），如果keyboard为空就找input_type设置的键盘类型 |
 | <a href="#edit_t_left_margin">left\_margin</a> | uint8\_t | 左边距。 |
@ -238,6 +240,26 @@ ret_t edit_set_auto_fix (widget_t* widget, bool_t auto_fix);
 | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
 | widget | widget\_t* | widget对象。 |
 | auto\_fix | bool\_t | 自动改正。 |
+#### edit\_set\_cancelable 函数
+-----------------------
+
+* 函数功能：
+
+> <p id="edit_t_edit_set_cancelable">设置编辑器是否为可撤销修改。
+
+* 函数原型：
+
+```
+ret_t edit_set_cancelable (widget_t* widget, bool_t cancelable);
+```
+
+* 参数说明：
+
+| 参数 | 类型 | 说明 |
+| -------- | ----- | --------- |
+| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
+| widget | widget\_t* | widget对象。 |
+| cancelable | bool\_t | 是否为可撤销修。 |
 #### edit\_set\_cursor 函数
 -----------------------

@ -712,6 +734,25 @@ ret_t edit_set_tr_tips (widget_t* widget, const char* tr_tips);

 * 类型：uint8\_t

+| 特性 | 是否支持 |
+| -------- | ----- |
+| 可直接读取 | 是 |
+| 可直接修改 | 否 |
+| 可持久化   | 是 |
+| 可脚本化   | 是 |
+| 可在IDE中设置 | 是 |
+| 可在XML中设置 | 是 |
+| 可通过widget\_get\_prop读取 | 是 |
+| 可通过widget\_set\_prop修改 | 是 |
+#### cancelable 属性
+-----------------------
+> <p id="edit_t_cancelable">是否支持撤销编辑。如果为TRUE，在失去焦点之前可以撤销所有修改(恢复获得焦点之前的内容)。
+
+> * 1.一般配合keyboard的"cancel"按钮使用。
+> * 2.为TRUE时，如果内容有变化，会设置编辑器的状态为changed，所以此时编辑器需要支持changed状态的style。
+
+* 类型：bool\_t
+
 | 特性 | 是否支持 |
 | -------- | ----- |
 | 可直接读取 | 是 |
--- a/docs/manual/encoding_name_t.md
+++ b/docs/manual/encoding_name_t.md
@ -0,0 +1,15 @@
+## encoding\_name\_t
+### 概述
+编码名称。
+### 常量
+<p id="encoding_name_t_consts">
+
+| 名称 | 说明 | 
+| -------- | ------- | 
+| ENCODING\_UTF8 | UTF-8。 |
+| ENCODING\_UTF16 | UTF-16。 |
+| ENCODING\_UTF32 | UTF-32。 |
+| ENCODING\_GBK | GBK。 |
+| ENCODING\_BIG | BIG5-2003。 |
+| ENCODING\_GB2312 | GB\_2312-80。 |
+| ENCODING\_GB18030 | GB18030。 |
--- a/docs/manual/encoding_t.md
+++ b/docs/manual/encoding_t.md
@ -0,0 +1,85 @@
+## encoding\_t
+### 概述
+encoding conversion
+
+示例：
+
+```c
+```
+----------------------------------
+### 函数
+<p id="encoding_t_methods">
+
+| 函数名称 | 说明 | 
+| -------- | ------------ | 
+| <a href="#encoding_t_encoding_convert">encoding\_convert</a> | 字符集转换。 |
+| <a href="#encoding_t_encoding_gbk_to_utf8">encoding\_gbk\_to\_utf8</a> | 将gbk转换成utf8编码。 |
+| <a href="#encoding_t_encoding_utf8_to_gbk">encoding\_utf8\_to\_gbk</a> | 将utf8转换成gbk编码。 |
+#### encoding\_convert 函数
+-----------------------
+
+* 函数功能：
+
+> <p id="encoding_t_encoding_convert">字符集转换。
+
+* 函数原型：
+
+```
+ret_t encoding_convert (encoding_name_t from, const char* from_str, uint32_t from_size, encoding_name_t to, const char* , uint32_t to_size);
+```
+
+* 参数说明：
+
+| 参数 | 类型 | 说明 |
+| -------- | ----- | --------- |
+| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
+| from | encoding\_name\_t | 源字符串的编码名称。 |
+| from\_str | const char* | 源字符串。 |
+| from\_size | uint32\_t | 源字符串的长度。 |
+| to | encoding\_name\_t | 目标字符串的编码名称。 |
+|  | const char* | 。 |
+| to\_size | uint32\_t | 目标字符串的最大长度。 |
+#### encoding\_gbk\_to\_utf8 函数
+-----------------------
+
+* 函数功能：
+
+> <p id="encoding_t_encoding_gbk_to_utf8">将gbk转换成utf8编码。
+
+* 函数原型：
+
+```
+ret_t encoding_gbk_to_utf8 (const char* from_str, uint32_t from_size, const char* , uint32_t to_size);
+```
+
+* 参数说明：
+
+| 参数 | 类型 | 说明 |
+| -------- | ----- | --------- |
+| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
+| from\_str | const char* | 源字符串(gbk)。 |
+| from\_size | uint32\_t | 源字符串的长度。 |
+|  | const char* | 。 |
+| to\_size | uint32\_t | 目标字符串的最大长度。 |
+#### encoding\_utf8\_to\_gbk 函数
+-----------------------
+
+* 函数功能：
+
+> <p id="encoding_t_encoding_utf8_to_gbk">将utf8转换成gbk编码。
+
+* 函数原型：
+
+```
+ret_t encoding_utf8_to_gbk (const char* from_str, uint32_t from_size, const char* to_str, uint32_t to_size);
+```
+
+* 参数说明：
+
+| 参数 | 类型 | 说明 |
+| -------- | ----- | --------- |
+| 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 |
+| from\_str | const char* | 源字符串(utf8)。 |
+| from\_size | uint32\_t | 源字符串的长度。 |
+| to\_str | const char* | 目标字符串(gbk)。 |
+| to\_size | uint32\_t | 目标字符串的最大长度。 |
--- a/docs/manual/event_type_t.md
+++ b/docs/manual/event_type_t.md
@ -56,6 +56,8 @@
 | EVT\_REQUEST\_CLOSE\_WINDOW | 请求关闭窗口的事件(event\_t)。 |
 | EVT\_TOP\_WINDOW\_CHANGED | 顶层窗口改变的事件(window\_event\_t)。 |
 | EVT\_IM\_COMMIT | 输入法提交输入的文本事件(im\_commit\_event\_t)。 |
+| EVT\_IM\_CLEAR | 清除编辑器内容(event\_t)。 |
+| EVT\_IM\_CANCEL | 取消编辑，恢复之前的内容(event\_t)。 |
 | EVT\_IM\_PREEDIT | 进入预编辑状态(event\_t)。 |
 | EVT\_IM\_PREEDIT\_CONFIRM | 确认预编辑内容，退出预编辑状态(event\_t)。 |
 | EVT\_IM\_PREEDIT\_ABORT | 删除预编辑内容，退出预编辑状态event\_t)。 |
--- a/docs/manual/keyboard_t.md
+++ b/docs/manual/keyboard_t.md
@ -33,6 +33,8 @@ keyboard中按钮子控件的名称有些特殊要求：
 | tab            | tab键           |
 | space          | 空格键          |
 | close          | 关闭软键盘       |
+| clear          | 清除编辑器的内容 |
+| cancel         | 恢复编辑器的内容 |
 | back           | 关闭当前窗口     |
 | back_to_home   | 返回home窗口    |
 | 前缀key:        | 键值           |
--- a/docs/manual/widget_prop_t.md
+++ b/docs/manual/widget_prop_t.md
@ -66,6 +66,7 @@
 | WIDGET\_PROP\_KEYBOARD | 自定义软键盘资源名称。 |
 | WIDGET\_PROP\_DEFAULT\_FOCUSED\_CHILD | 缺省获得焦点的子控件(可用控件名或类型)。 |
 | WIDGET\_PROP\_READONLY | 只读模式。 |
+| WIDGET\_PROP\_CANCELABLE | 是否可取消。 |
 | WIDGET\_PROP\_PASSWORD\_VISIBLE | 密码是否可见。 |
 | WIDGET\_PROP\_ACTIVE | 是否处于active状态。 |
 | WIDGET\_PROP\_VERTICAL | 是否为垂直模式。 |
@ -101,6 +102,7 @@
 | WIDGET\_PROP\_XSLIDABLE | X方向是否可拖动。 |
 | WIDGET\_PROP\_YSLIDABLE | Y方向是否可拖动。 |
 | WIDGET\_PROP\_REPEAT | 重复次数。 |
+| WIDGET\_PROP\_LONG\_PRESS\_TIME | 触发长按事件的时间(ms)。 |
 | WIDGET\_PROP\_ENABLE\_LONG\_PRESS | 是否启用长按。 |
 | WIDGET\_PROP\_ANIMATABLE | 是否启用动画。 |
 | WIDGET\_PROP\_AUTO\_HIDE\_SCROLL\_BAR | 是否自动隐藏滚动条。 |
--- a/docs/manual/widget_state_t.md
+++ b/docs/manual/widget_state_t.md
@ -10,6 +10,7 @@
 | -------- | ------- | 
 | WIDGET\_STATE\_NONE | 无效状态。 |
 | WIDGET\_STATE\_NORMAL | 正常状态。 |
+| WIDGET\_STATE\_CHANGED | 内容被修改的状态。 |
 | WIDGET\_STATE\_PRESSED | 指针按下状态。 |
 | WIDGET\_STATE\_OVER | 指针悬浮状态。 |
 | WIDGET\_STATE\_DISABLE | 禁用状态。 |
--- a/src/base/widget.h
+++ b/src/base/widget.h
@ -2287,6 +2287,10 @@ ret_t widget_set_self_layout_params(widget_t* widget, const char* x, const char*
 /**
 * @method widget_set_style_int
 * 设置整数类型的style。
+ *
+ * > * [state 的取值](https://github.com/zlgopen/awtk/blob/master/docs/manual/widget_state_t.md)
+ * > * [name 的取值](https://github.com/zlgopen/awtk/blob/master/docs/theme.md)
+ *
 * @annotation ["scriptable"]
 * @param {widget_t*} widget 控件对象。
 * @param {const char*} state_and_name 状态和名字，用英文的冒号分隔。
@ -2299,6 +2303,10 @@ ret_t widget_set_style_int(widget_t* widget, const char* state_and_name, int32_t
 /**
 * @method widget_set_style_str
 * 设置字符串类型的style。
+ *
+ * > * [state 的取值](https://github.com/zlgopen/awtk/blob/master/docs/manual/widget_state_t.md)
+ * > * [name 的取值](https://github.com/zlgopen/awtk/blob/master/docs/theme.md)
+ *
 * @annotation ["scriptable"]
 * @param {widget_t*} widget 控件对象。
 * @param {const char*} state_and_name 状态和名字，用英文的冒号分隔。
@ -2311,6 +2319,10 @@ ret_t widget_set_style_str(widget_t* widget, const char* state_and_name, const c
 /**
 * @method widget_set_style_color
 * 设置颜色类型的style。
+ *
+ * > * [state 的取值](https://github.com/zlgopen/awtk/blob/master/docs/manual/widget_state_t.md)
+ * > * [name 的取值](https://github.com/zlgopen/awtk/blob/master/docs/theme.md)
+ *
 * @annotation ["scriptable"]
 * @param {widget_t*} widget 控件对象。
 * @param {const char*} state_and_name 状态和名字，用英文的冒号分隔。