update docs

docs/changes.md

@@ -1,4 +1,7 @@
 # 最新动态
+* 2018/12/30
+  * 整理API文档：style/style\_const/style\_mutable/theme/style\_factory
+
 * 2018/12/29
   * 整理API文档：bitmap/image\_loader/image\_manager/image\_loader\_stb
   * 整理API文档：asset\_info/assets\_manager/locale\_info

docs/dots/style_overview

@@ -0,0 +1,22 @@
+digraph UML {
+  rankdir  = BT
+     
+  fontname = "Courier New"
+  fontsize = 10
+     
+  node [ fontname = "Courier New", fontsize = 10, shape = "record" ];
+  edge [ fontname = "Courier New", fontsize = 10 ];
+     
+   style_t->widget_t[arrowhead=none];
+   style_factory_t->widget_t[arrowhead=none];
+   subgraph cluster_0{
+     style_factory_t->style_t[constraint=false arrowhead=vee];
+   };
+   
+   subgraph cluster_1{
+     style_const_t -> style_mutable_t[constraint=false arrowhead=ediamond]
+   };
+   style_const_t -> style_t[arrowhead=empty style=dashed]
+   style_mutable_t -> style_t[arrowhead=empty style=dashed]
+   theme_t -> style_const_t[arrowhead=none]
+}

docs/manual.md

@@ -85,6 +85,14 @@
 
 #### 4.主题
 
+![style\_overview](images/style_overview.png)
+
+* [style](manual/style_t.md) style接口。
+* [theme](manual/theme_t.md) 常量主题数据。
+* [style\_factory](manual/style_factory_t.md) style工厂。
+* [style\_const](manual/style_const_t.md) 只读的style。
+* [style\_mutable](manual/style_mutable_t.md) 可修改的style。
+
 #### 5.UI描述数据
 
 

docs/manual/style_const_t.md

@@ -0,0 +1,39 @@
+## style\_const\_t
+### 概述
+![image](images/style_const_t_0.png)
+
+ 
+ 只读的style，从theme\_t中获取数据。
+
+ tools/theme_gen用于把XML的主题数据转换成常量数据。
+
+
+
+### 函数
+<p id="style_const_t_methods">
+
+| 函数名称 | 说明 | 
+| -------- | ------------ | 
+| <a href="#style_const_t_style_const">style\_const</a> |  |
+#### style\_const 函数
+-----------------------
+
+* 函数功能：
+
+> <p id="style_const_t_style_const">
+ 创建只读的style对象。
+
+
+
+
+* 函数原型：
+
+```
+style_t* style_const ();
+```
+
+* 参数说明：
+
+| 参数 | 类型 | 说明 |
+| -------- | ----- | --------- |
+| 返回值 | style\_t* | 返回style对象。 |

docs/manual/style_factory_t.md

@@ -1,6 +1,9 @@
 ## style\_factory\_t
 ### 概述
- style_factory接口。
+ style工厂接口，主要用于创建style。
+
+> 在特殊情况下，可以实现自己的style工厂，比如支持CSS和可实时修改的style。
+
 
 ### 函数
 <p id="style_factory_t_methods">

docs/manual/style_mutable_t.md

@@ -2,17 +2,21 @@
 ### 概述
 ![image](images/style_mutable_t_0.png)
 
- 控件风格(可实时修改并生效，用于在designer中被编辑的控件)。
+
+ 可变的style(可实时修改并生效，主要用于在designer中被编辑的控件，或者一些特殊控件)。
+
+ style\_mutable也对style\_const进行了包装，当用户没修改某个值时，便从style\_const中获取。
+
 
 ### 函数
 <p id="style_mutable_t_methods">
 
 | 函数名称 | 说明 | 
 | -------- | ------------ | 
-| <a href="#style_mutable_t_style_mutable_create">style\_mutable\_create</a> | 创建style_mutable对象。除了测试程序外不需要直接调用，widget会通过style_factory_create创建。 |
-| <a href="#style_mutable_t_style_mutable_foreach">style\_mutable\_foreach</a> | 遍历。对每项调用回调函数on_style_item。 |
+| <a href="#style_mutable_t_style_mutable_create">style\_mutable\_create</a> | 创建style\_mutable对象。 |
+| <a href="#style_mutable_t_style_mutable_foreach">style\_mutable\_foreach</a> | 遍历。对每项调用回调函数on\_style\_item。 |
 | <a href="#style_mutable_t_style_mutable_get_name">style\_mutable\_get\_name</a> | 获取style的名称。 |
-| <a href="#style_mutable_t_style_mutable_register">style\_mutable\_register</a> | 将自己注册到style_factory。 |
+| <a href="#style_mutable_t_style_mutable_register">style\_mutable\_register</a> | 将自己注册到style\_factory。 |
 | <a href="#style_mutable_t_style_mutable_set_color">style\_mutable\_set\_color</a> | 设置指定name的颜色值。 |
 | <a href="#style_mutable_t_style_mutable_set_int">style\_mutable\_set\_int</a> | 设置指定name整数格式的值。 |
 | <a href="#style_mutable_t_style_mutable_set_name">style\_mutable\_set\_name</a> | 设置style的名称。 |
@@ -28,7 +32,10 @@
 
 * 函数功能：
 
-> <p id="style_mutable_t_style_mutable_create"> 创建style_mutable对象。除了测试程序外不需要直接调用，widget会通过style_factory_create创建。
+> <p id="style_mutable_t_style_mutable_create"> 创建style\_mutable对象。
+
+ > 除了测试程序外不需要直接调用，widget会通过style\_factory\_create创建。
+
 
 
 
@@ -50,7 +57,7 @@ style_t* style_mutable_create (widget_t* widget);
 
 * 函数功能：
 
-> <p id="style_mutable_t_style_mutable_foreach"> 遍历。对每项调用回调函数on_style_item。
+> <p id="style_mutable_t_style_mutable_foreach"> 遍历。对每项调用回调函数on\_style\_item。
 
 
 
@@ -96,7 +103,7 @@ const char* style_mutable_get_name (style_t* s);
 
 * 函数功能：
 
-> <p id="style_mutable_t_style_mutable_register"> 将自己注册到style_factory。
+> <p id="style_mutable_t_style_mutable_register"> 将自己注册到style\_factory。
 
 
 

docs/manual/style_t.md

@@ -2,6 +2,18 @@
 ### 概述
  控件风格。
 
+ widget从style对象中，获取诸如字体、颜色和图片相关的参数，根据这些参数来绘制界面。
+
+ ```c
+ style_t* style = widget->astyle;
+ int32_t margin = style_get_int(style, STYLE_ID_MARGIN, 2);
+ int32_t icon_at = style_get_int(style, STYLE_ID_ICON_AT, ICON_AT_AUTO);
+ uint16_t font_size = style_get_int(style, STYLE_ID_FONT_SIZE, TK_DEFAULT_FONT_SIZE);
+ ```
+
+ 属性名称的请参考[style\_id](style_id_t.md)
+
+
 ### 函数
 <p id="style_t_methods">
 

docs/manual/theme_t.md

@@ -2,6 +2,9 @@
 ### 概述
  主题。
 
+ 负责管理缺省的主题数据，方便实现style\_const。
+
+
 ### 函数
 <p id="theme_t_methods">
 

src/base/style.h

@@ -207,6 +207,18 @@ typedef struct _style_vtable_t {
  * @class style_t
  * @annotation ["scriptable"]
  * 控件风格。
+ *
+ * widget从style对象中，获取诸如字体、颜色和图片相关的参数，根据这些参数来绘制界面。
+ *
+ * ```c
+ * style_t* style = widget->astyle;
+ * int32_t margin = style_get_int(style, STYLE_ID_MARGIN, 2);
+ * int32_t icon_at = style_get_int(style, STYLE_ID_ICON_AT, ICON_AT_AUTO);
+ * uint16_t font_size = style_get_int(style, STYLE_ID_FONT_SIZE, TK_DEFAULT_FONT_SIZE);
+ * ```
+ *
+ * 属性名称的请参考[style\_id](style_id_t.md)
+ *
  */
 struct _style_t {
   const style_vtable_t* vt;

src/base/style_const.h

@@ -26,6 +26,26 @@
 
 BEGIN_C_DECLS
 
+/**
+ * @class style_const_t
+ * @parent style_t
+ * 
+ * 只读的style，从theme\_t中获取数据。
+ *
+ * tools/theme_gen用于把XML的主题数据转换成常量数据。
+ *
+ * @annotation["fake"]
+ *
+ */
+
+/**
+ * @method style_const
+ * @annotation ["constructor"]
+ *
+ * 创建只读的style对象。
+ *
+ * @return {style_t*} 返回style对象。
+ */
 style_t* style_const_create(widget_t* widget);
 
 END_C_DECLS

src/base/style_factory.h

@@ -33,7 +33,10 @@ typedef style_t* (*style_factory_create_style_t)(style_factory_t* factory, widge
 
 /**
  * @class style_factory_t
- * style_factory接口。
+ * style工厂接口，主要用于创建style。
+ *
+ *> 在特殊情况下，可以实现自己的style工厂，比如支持CSS和可实时修改的style。
+ *
  */
 struct _style_factory_t {
   style_factory_create_style_t create_style;

src/base/theme.h

@@ -30,6 +30,9 @@ BEGIN_C_DECLS
 /**
  * @class theme_t
  * 主题。
+ *
+ * 负责管理缺省的主题数据，方便实现style\_const。
+ *
  */
 typedef struct _theme_t {
   const uint8_t* data;

src/designer_support/style_mutable.h

@@ -37,7 +37,11 @@ typedef struct _widget_state_style_t widget_state_style_t;
  * @class style_mutable_t
  * @parent style_t
  * @annotation ["scriptable"]
- * 控件风格(可实时修改并生效，用于在designer中被编辑的控件)。
+ *
+ * 可变的style(可实时修改并生效，主要用于在designer中被编辑的控件，或者一些特殊控件)。
+ *
+ * style\_mutable也对style\_const进行了包装，当用户没修改某个值时，便从style\_const中获取。
+ *
  */
 typedef struct _style_mutable_t {
   style_t style;
@@ -128,7 +132,7 @@ ret_t style_mutable_set_str(style_t* s, const char* state, const char* name, con
 
 /**
  * @method style_mutable_foreach
- * 遍历。对每项调用回调函数on_style_item。
+ * 遍历。对每项调用回调函数on\_style\_item。
  * @param {style_t*} s style对象。
  * @param {tk_on_style_item_t} on_style_item 回调函数。
  * @param {void*} ctx 回调函数的上下文。
@@ -139,7 +143,10 @@ ret_t style_mutable_foreach(style_t* s, tk_on_style_item_t on_style_item, void*
 
 /**
  * @method style_mutable_create
- * 创建style_mutable对象。除了测试程序外不需要直接调用，widget会通过style_factory_create创建。
+ * 创建style\_mutable对象。
+ *
+ * > 除了测试程序外不需要直接调用，widget会通过style\_factory\_create创建。
+ *
  * @annotation ["constructor", "scriptable"]
  * @param {widget_t*} widget 控件
  *
@@ -149,7 +156,7 @@ style_t* style_mutable_create(widget_t* widget);
 
 /**
  * @method style_mutable_register
- * 将自己注册到style_factory。
+ * 将自己注册到style\_factory。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */