From 853238f0e2cc567a7a0bf6bc975b62c7b86c7dba Mon Sep 17 00:00:00 2001 From: xianjimli Date: Thu, 3 Jan 2019 09:59:18 +0800 Subject: [PATCH] update docs --- docs/changes.md | 4 + docs/dots/idle_overview | 11 +++ docs/dots/timer_overview | 11 +++ docs/images/idle_overview.png | Bin 0 -> 2684 bytes docs/images/timer_overview.png | Bin 0 -> 2675 bytes docs/manual.md | 15 +++- docs/manual/idle_info_t.md | 76 +++++++++++++++++++ docs/manual/idle_t.md | 24 +++++- docs/manual/timer_info_t.md | 131 +++++++++++++++++++++++++++++++++ docs/manual/timer_t.md | 26 ++++++- docs/manual/widget_t.md | 22 +++++- src/base/idle.h | 18 +++++ src/base/timer.h | 15 ++++ tools/idl_gen/idl.json | 4 +- 14 files changed, 347 insertions(+), 10 deletions(-) create mode 100644 docs/dots/idle_overview create mode 100644 docs/dots/timer_overview create mode 100644 docs/images/idle_overview.png create mode 100644 docs/images/timer_overview.png create mode 100644 docs/manual/idle_info_t.md create mode 100644 docs/manual/timer_info_t.md diff --git a/docs/changes.md b/docs/changes.md index 867b2b411..f1245d56f 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -1,4 +1,8 @@ # 最新动态 +* 2019/01/03 + * 同步SDL代码。 + * 整理API文档：timer/idle + * 2019/01/02 * 整理API文档：input\_method/input\_method\_default/input\_method\_sdl/input\_method\_null * 整理API文档：input\_engine/input\_engine\_pinyin/input\_engine\_null diff --git a/docs/dots/idle_overview b/docs/dots/idle_overview new file mode 100644 index 000000000..e27150b19 --- /dev/null +++ b/docs/dots/idle_overview @@ -0,0 +1,11 @@ +digraph UML { + rankdir = LR + + fontname = "Courier New" + fontsize = 10 + + node [ fontname = "Courier New", fontsize = 10, shape = "record" ]; + edge [ fontname = "Courier New", fontsize = 10 ]; + + idle_t -> idle_info_t[arrowhead=vee] +} diff --git a/docs/dots/timer_overview b/docs/dots/timer_overview new file mode 100644 index 000000000..af0747c17 --- /dev/null +++ b/docs/dots/timer_overview @@ -0,0 +1,11 @@ +digraph UML { + rankdir = LR + + fontname = "Courier New" + fontsize = 10 + + node [ fontname = "Courier New", fontsize = 10, shape = "record" ]; + edge [ fontname = "Courier New", fontsize = 10 ]; + + timer_t -> timer_info_t[arrowhead=vee] +} diff --git a/docs/images/idle_overview.png b/docs/images/idle_overview.png new file mode 100644 index 0000000000000000000000000000000000000000..b3ca315e953772df56fef84cf07445f4aa03c7a1 GIT binary patch literal 2684 zcmcgu`8(9z8#ZI?V(i*&;E1P8?rQFB-@ne`+5I~?+@oZ*LCi5oo6}EIrmMrv$Z@TC@;vx#dQRWK{){SJ1~s+ zd4bs?hHnWlpfCqZBo}o6#^T}<)Wf38E=PgZ|8`22w1H~W%WCmKxYd@E^K@jjyzIra z2wY)3d^{4oXP*+H>^?Z(XC?^LCwrJ`d7#AXwJHw3`TdcLBzh9Pf>u0V460ovQYtFi zepOMaAMrub-6$j}4o*-3JEtwW>fWXJhVFGI>dYo10fhQoEE& z+?YEO@B~dOVOW zxAJ|F}UOqnV4EFXY|-B@C7FLbAF zvuBMgUrPQq0vs!-e>*(bcVvAk_gR~$+h%rhCs-<1S4e^EnGMRhpgE(E1&9;^cYmzf z**pi~LKQJw~$~iZt>pKD`#C-jzPiVIp39zn#AU5xOM#X`SqQ2rwdDix15-OgW=(dOV>q& zv(^vx_s-opjBPtMu>X^@dA##^kzrVm#@-f~^fGe2pxB1eex@ix;Dc+EKh{8BApGE0 z#OiQ`XwDheM>y&=Y_Z9$A4!Aj)6KnC=!zF_duuZLGLJ_VyLH44(URI{2O?;QlhN}x z+1;xipUSWegidhG_Sa0ju(?dh)s5(Ay`VW`%~A0eZ{A6w+alLLRY>2Jq6{BV%wl=x zpCV7SMpTu~q?1OgoDe43`jr$CYZE0L zyEasTZ40~Zdhf{dD^;+Kov%aYbtI#AI#wV>siMH@mi`^o`GgPfHcV)dRX#`j`(Bz6 zk^OO`(y?(mK1bMV;;y(l`|D6Ci#^+xecV!{Kz9^s1B;NMXBH4dhK`r*(f!U= z`0f@mZ23b8P`z(q5zd)A2;&lO&i8pdo;cFU%C4lWP1fIYZUAm)2q=yKt(L##*5U8` zM`v8o*0~zxJ!uNPjnBr~#`anxzJ>R3%RMoUcK8x>;mzJ;y_e7K+T_%yTvdBgD{G{<<<$#IWPLu2T zGB>9hd?aRDBT~;3+0}*XQ;mo;d0i{FHwp7R8Mcqlmv6W>`dXyQXi{Q-{$TB2{X?&U zo%4pe_tJe8c9hc9t~_VNj84~M(rm}Nn74S3)112#aC{;#JL3|`UTg|q=?t#jTRLjK zD=9^Wt2@iSxnC<~VPdd@82;6PS;6BO{zm<8HMVt*npDm`j5X|Sv5;{{Dq-Fk)U`VM z`i`5f&nMJu8}U-^7V1ipkj$=sd~~OMqu)3V7RlQC+#X%((i~WG)w%1}W~f8}yTrmq6#zRG*A^))?TF946Ke{&S?D zofT8ycj2Gi`=Lwk%InJvvSdT1tDWn&e=_h279=p@RNFWMJQRXI{QZ;Fl_Z2O{N8x% zOU)Uy+H0VB<$Ab-?^=T2!(!MvY%`ley;1zbVpF)Bq5s6$X$jwnTBRd$+Kez6Ow*Mb zmz)QR7pY6{QjJHeowJ$(rk7tH(Uh83l2p5laS9lx9t9yZ6FEntv&a&sRt@jFq2un6 zwT-QHe=Z|?<@@f5DmJ`VaH)veTyW1)-_D=boeA{MmsGW*-xhA}kSTS>8C7* zWmK(Ed=L)~Y-3l)Y7}_=jT52u?Y9r6sJw`zyuR?Rxu8;X+V(`;>D!ik5`Moqo7;l$_<4d`9?!V^uM4J4kn}arz>t8jk5HE=EHI$g$ zomTdHF-!Z3i>?k@3?THWBk^6LKl;I!^0h4xve}Y?DJqvr(vsWd#(j$Y%_EEmdMS@$66NrOFYK= zr-d{cqw4WNl`Y08uGw=O#!Yw`_@NGt_8eE^lJW(;1AOrr@&oU;r_jhyA%WAoTt$y# zR6BRY7gK7e_c53b+5$_II*c5X9o8n6o~Vnhr{kT(RGvL7A@K-_o4kdp|Ks`eg!Lon zjLjmL@X7&O8(iz@b7Ii|>U;Ata>lhI_Gj6Ib-ETWm5x<{F5PTNePx;Cc}(7KUX_Z-GP-1Oc-V5TiF+zapI=U_n5P-U5jv2m)p!AVzPtenmP#z=D7n zy#*3U5CqIdK#bmO{fcygfCT|DdJ80yAPAU^fEc~m`W5K}0Sf|R^cF}YK@cz-0Wo^B z^()c|0u}_s=q->)f*@cv0%G)L>sO=`1S|-M(OV#q1VO-T1jOjg)~`q>2v`shqqjgJ z34(yx2#C=err(DTAJWa6Hw}|Y#BmYs{#2}3F~WfG{{4HGIq+|O)22;y{``6W#2C86QfSSZ zHBoW&>C-3POctAqzIyd4sRWeapFX(TeogRqJ@JQo)yc~ zym@oNCsJC!em%jPDN&+Cq)ph?d-UiLVQY1#DQcrXc<><2pFf}O+_^(-+qPx?^5x6N z>qrl?aG&<<*+U;beBhDrzyJQ@tb6zF(V#(ts6vGbT)$eiYV_vK8-lRo$B*~!%=+TR z3&PUi?%lh*yC;HFbLPyU%$YNDJF8Z$qV3za)6k(q>F3X%+^O^C&C4CTc=6&MHiCY` zHS68GH=Q|i#>+nnE?TsRDpsr*v`(-@%%-PLpXQx}gXJez8g?@F^`^3C&rW^%^kIFV z1HtG$JEZR2yO(zD+C{Z%*G>|9;a~>0dBTJVtdFr{$MTr~o`-;+-@ktoCX0_BKeEw* z7wpl#a^*@c=BCa)eDv+xm)^d8%W;o|3m1Bl`5Vh4>P=#L1pdg^-%*<4JUHjQldn+>fXJ(`u_d9UpZ}DYSgGvoYtgC z6Q!2`N(Y@(t5&TzO?OhIXCkFLg~I;q$kPU|h7TX^*Uo_h2UO|OrPY`*W0W?0b^rc- z1-`;1eNaWXMT3^piinAQ&bZ<$aR+SrvocqUXa+kEf_Yy-)WHGQ-rPsffOxrsuB z3h``-Y3?$6M5*Idc?ID zFalNR+`gT;WXY0FJkpppv{%JTBrL&z6$pbV27>C({T8HEUMCv`B8WyUNuND5+7ShPR1uf=J%N zVO+pF!1^+0&YWD@DgMKFv@1oRkCrW4@|qI{5AO-au9r<5yldF7q4&9wo@V40X33>< zF90rF;9Ns^orn!#uz&{xFLme6onb#MTefU|=L1q&9WD_5>ig9Z&~_UzgG-V)JcFnr;{1?tkJ3r8do%z+WFTept#&AmB0?`OCgGP=V$-k9AKdo1<9tW^7 z0F*6Tmh;2;gXJm)5B$yn#(wqcRSud%w^5N+h#y4~$n!LSAjPd)x0H^|dXgOd)&qgk z>pj=nN09LP_3KJUr<2UL9%vM>OKH-tPL*~mIhdyhQ>EXfhYTJeaHczvN@^evvPOeh zI9R!@^Kf{Gri^|&pb!Mqr$I;D41&^n@Jw=jyFi{JGrecj!D|V8+#)yLh5GUe7Z{#I zJQH3MK?if^&SmciztD4&+{Vmpox6z*+J+a4Pc&pXYC4+6bX`Y{K1yC(sg8HSc57BF z1DuFExWagZjpDs9KB<{vUFX_6O7wpr5V*!t$1O72=&=sM`peGf0W8*aZqJ5pDNow9 zA`lNcU%GUu?aynq4^R3xC>#^BO6N?9(MAtr_WgyFGmuFuv5Y`G=o~@LlqC0jh?JB{ zo-GIn0=5W<(c3~J8G?YB2#C>}saKIo5U@o+jNTR+$q)q0L_mz*OudR!f`BaoV)VAq zNQNL_CIVvgX6jX>5(I1!5Tmz+Mlu8eGZ7G@H&d@7l^|e?fEc|kG?F0*n2CTGy_tFy zsRRLA1jOiVp^*$hz)S?h=*`rtNF@l^A`tYy?C|e>*xpDed<1}5yc4#KvimpWc$Y0T z^8e(?6F%%DPQ*EZ1cD+UMjsRwNfZRkML>++T-}Off + +| 名属性称 | 类型 | 说明 | +| -------- | ----- | ------------ | +| ctx | void* | idle回调函数上下文。 | +| id | uint32\_t | idle的ID | +| on\_destroy | tk\_destroy\_t | idle销毁时的回调函数。 | +| on\_destroy\_ctx | tk\_destroy\_t | idle销毁时的回调函数的上下文。 | +| on\_idle | idle\_func\_t | idle回调函数。 | +#### ctx 属性 +----------------------- +>

idle回调函数上下文。 + + + +* 类型：void* + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### id 属性 +----------------------- +>

idle的ID + + > 为TK\_INVALID\_ID时表示无效idle。 + + + +* 类型：uint32\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### on\_destroy 属性 +----------------------- +>

idle销毁时的回调函数。 + + + +* 类型：tk\_destroy\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### on\_destroy\_ctx 属性 +----------------------- +>

idle销毁时的回调函数的上下文。 + + + +* 类型：tk\_destroy\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### on\_idle 属性 +----------------------- +>

idle回调函数。 + + + +* 类型：idle\_func\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | diff --git a/docs/manual/idle_t.md b/docs/manual/idle_t.md index f049310a8..6e152426c 100644 --- a/docs/manual/idle_t.md +++ b/docs/manual/idle_t.md @@ -1,6 +1,28 @@ ## idle\_t ### 概述 - idle函数在主循环中paint之后执行。 + + idle可以看作是duration为0的定时器，不同的是idle函数在主循环中paint之后执行。 + + > idle可以用来实现一些异步处理。 + + 示例： + + ```c + static ret_t something_on_idle(const idle_info_t* info) { + widget_t* widget = WIDGET(info->ctx); + edit_t* edit = EDIT(widget); + ... + return RET_REMOVE; + } + + ... + + idle_add(something_on_idle, edit); + + ``` + + > 在非GUI线程请用idle\_queue。 + ### 函数

diff --git a/docs/manual/timer_info_t.md b/docs/manual/timer_info_t.md new file mode 100644 index 000000000..522bfaf2c --- /dev/null +++ b/docs/manual/timer_info_t.md @@ -0,0 +1,131 @@ +## timer\_info\_t +### 概述 + 单个定时器的信息。 + +### 属性 +

+ +| 名属性称 | 类型 | 说明 | +| -------- | ----- | ------------ | +| ctx | void* | 定时器回调函数的上下文 | +| duration | uint32\_t | 时间间隔(单位为毫秒)。 | +| id | uint32\_t | 定时器的ID | +| now | uint32\_t | 当前时间(相对时间，单位为毫秒)。 | +| on\_destroy | tk\_destroy\_t | 定时器销毁时的回调函数。 | +| on\_destroy\_ctx | void* | 定时器销毁时的回调函数上下文。 | +| on\_timer | timer\_func\_t | 定时器回调函数。 | +| start | uint32\_t | 起始时间(相对时间，单位为毫秒)。 | +| user\_changed\_time | bool\_t | 用户是否修改了系统时间。 | +#### ctx 属性 +----------------------- +>

定时器回调函数的上下文 + + + +* 类型：void* + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### duration 属性 +----------------------- +>

时间间隔(单位为毫秒)。 + + + + +* 类型：uint32\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### id 属性 +----------------------- +>

定时器的ID + + > 为TK\_INVALID\_ID时表示无效定时器。 + + + +* 类型：uint32\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### now 属性 +----------------------- +>

当前时间(相对时间，单位为毫秒)。 + + + + +* 类型：uint32\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### on\_destroy 属性 +----------------------- +>

定时器销毁时的回调函数。 + + + +* 类型：tk\_destroy\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### on\_destroy\_ctx 属性 +----------------------- +>

定时器销毁时的回调函数上下文。 + + + +* 类型：void* + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### on\_timer 属性 +----------------------- +>

定时器回调函数。 + + + +* 类型：timer\_func\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### start 属性 +----------------------- +>

起始时间(相对时间，单位为毫秒)。 + + + + +* 类型：uint32\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | +#### user\_changed\_time 属性 +----------------------- +>

用户是否修改了系统时间。 + + + +* 类型：bool\_t + +| 特性 | 是否支持 | +| -------- | ----- | +| 可直接读取 | 是 | +| 可直接修改 | 否 | diff --git a/docs/manual/timer_t.md b/docs/manual/timer_t.md index d954b7b14..869b40bdf 100644 --- a/docs/manual/timer_t.md +++ b/docs/manual/timer_t.md @@ -2,6 +2,24 @@ ### 概述 定时器系统。 + > 本定时器精度较低，最高精度为1000/FPS，如果需要高精度的定时器，请用OS提供的定时器。 + + 示例： + + ```c + static ret_t my_on_timer(const timer_info_t* info) { + widget_t* widget = WIDGET(info->ctx); + ... + return RET_REPEAT; + } + + ... + + timer_add(my_on_timer, widget, 1000); + ``` + > 在非GUI线程请用timer\_queue。 + + ### 函数

@@ -27,7 +45,7 @@ * 函数原型： ``` -uint32_t timer_add (timer_func_t on_timer, void* ctx, uint32_t duration_ms); +uint32_t timer_add (timer_func_t on_timer, void* ctx, uint32_t duration); ``` * 参数说明： @@ -37,7 +55,7 @@ uint32_t timer_add (timer_func_t on_timer, void* ctx, uint32_t duration_ms); | 返回值 | uint32\_t | 返回timer的ID，TK\_INVALID\_ID表示失败。 | | on\_timer | timer\_func\_t | timer回调函数。 | | ctx | void* | timer回调函数的上下文。 | -| duration\_ms | uint32\_t | 时间。 | +| duration | uint32\_t | 时间。 | #### timer\_count 函数 ----------------------- @@ -115,7 +133,7 @@ uint32_t timer_now (); * 函数原型： ``` -ret_t timer_queue (timer_func_t , void* ctx, uint32_t duration_ms); +ret_t timer_queue (timer_func_t , void* ctx, uint32_t duration); ``` * 参数说明： @@ -125,7 +143,7 @@ ret_t timer_queue (timer_func_t , void* ctx, uint32_t duration_ms); | 返回值 | ret\_t | 返回RET\_OK表示成功，否则表示失败。 | | | timer\_func\_t | r | | ctx | void* | timer回调函数的上下文。 | -| duration\_ms | uint32\_t | 时间。 | +| duration | uint32\_t | 时间。 | #### timer\_remove 函数 ----------------------- diff --git a/docs/manual/widget_t.md b/docs/manual/widget_t.md index 32133733d..9e8d66407 100644 --- a/docs/manual/widget_t.md +++ b/docs/manual/widget_t.md @@ -10,8 +10,6 @@ 它负责控件的生命周期、通用状态、事件分发和Style的管理。 本类提供的接口(函数和属性)除非特别说明，一般都适用于子类控件。 - > **widget_t**是抽象类，不要直接创建**widget_t**的实例。 - 为了便于解释，这里特别说明一下几个术语： * **父控件与子控件**：父控件与子控件指的两个控件的组合关系(这是在运行时决定的)。 @@ -26,6 +24,26 @@ ![image](images/widget_t_2.png) + widget相关的函数都只能在GUI线程中执行，如果需在非GUI线程中想调用widget相关函数， + 请用idle\_queue或timer\_queue进行串行化。 + 请参考[demo thread](https://github.com/zlgopen/awtk/blob/master/demos/demo_thread_app.c) + + **widget\_t**是抽象类，不要直接创建**widget\_t**的实例。控件支持两种创建方式： + + * 通过XML创建。如： + + ```xml +