add Chinese comments.

git-svn-id: https://rt-thread.googlecode.com/svn/trunk@462 bbd45198-f89e-11dd-88c7-29a3b14d5316

examples/gui/demo_view.c

@@ -4,10 +4,14 @@
 #include <rtgui/widgets/workbench.h>
 #include <rtgui/widgets/staticline.h>
 
+/* 用于存放演示视图的数组，最多可创建32个演示视图 */
 static rtgui_view_t* demo_view_list[32];
-static rt_uint32_t demo_view_current = 0;
+/* 当前演示视图索引 */
-static rt_uint32_t demo_view_number = 0;
+static rt_uint16_t demo_view_current = 0;
+/* 总共包括的演示视图数目 */
+static rt_uint16_t demo_view_number = 0;
 
+/* 显示下一个演示视图 */
 void demo_view_next(struct rtgui_widget* widget, rtgui_event_t *event)
 {
 	if (demo_view_current + 1< demo_view_number)
@@ -17,6 +21,7 @@ void demo_view_next(struct rtgui_widget* widget, rtgui_event_t *event)
 	}
 }
 
+/* 显示前一个演示视图 */
 void demo_view_prev(struct rtgui_widget* widget, rtgui_event_t *event)
 {
 	if (demo_view_current != 0)
@@ -26,103 +31,122 @@ void demo_view_prev(struct rtgui_widget* widget, rtgui_event_t *event)
 	}
 }
 
+/* 创建一个演示视图，需提供父workbench和演示用的标题 */
 rtgui_view_t* demo_view(rtgui_workbench_t* workbench, const char* title)
 {
     char view_name[32];
     struct rtgui_view* view;
 
+    /* 设置视图的名称 */
     rt_sprintf(view_name, "view %d", demo_view_number + 1);
-
     view = rtgui_view_create(view_name);
+    if (view == RT_NULL) return RT_NULL;
 
-	/* add to the list */
+	/* 创建成功后，添加到数组中 */
 	demo_view_list[demo_view_number] = view;
 	demo_view_number ++;
 
+    /* 添加到父workbench中 */
 	rtgui_workbench_add_view(workbench, view);
 
-    /* add next and prev button */
+    /* 添加下一个视图和前一个视图按钮 */
     {
     	struct rtgui_rect rect;
         struct rtgui_button *next_btn, *prev_btn;
 		struct rtgui_label *label;
 		struct rtgui_staticline *line;
 
-		/* get view's rect */
+		/* 获得视图的位置信息(在加入到workbench中时，workbench会自动调整视图的大小) */
 		rtgui_widget_get_rect(RTGUI_WIDGET(view), &rect);
 		rect.x1 += 5; rect.y1 += 5;
 		rect.x2 -= 5; rect.y2 = rect.y1 + 20;
 
-		/* create view label */
+		/* 创建标题用的标签 */
 		label = rtgui_label_create(title);
+		/* 设置标签位置信息 */
 		rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+		/* 添加标签到视图中 */
 		rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 
 		rect.y1 += 20; rect.y2 += 20;
+		/* 创建一个水平的staticline线 */
 		line = rtgui_staticline_create(RTGUI_HORIZONTAL);
+		/* 设置静态线的位置信息 */
 		rtgui_widget_set_rect(RTGUI_WIDGET(line), &rect);
+		/* 添加静态线到视图中 */
 		rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(line));
 
-		/* get view's rect */
+		/* 获得视图的位置信息 */
 		rtgui_widget_get_rect(RTGUI_WIDGET(view), &rect);
 		rect.x2 -= 5; rect.y2 -= 5;
 		rect.x1 = rect.x2 - 50; rect.y1 = rect.y2 - 20;
 
-		/* create next button */
+		/* 创建"下一个"按钮 */
         next_btn = rtgui_button_create("Next");
+        /* 设置onbutton动作到demo_view_next函数 */
 		rtgui_button_set_onbutton(next_btn, demo_view_next);
+		/* 设置按钮的位置信息 */
 		rtgui_widget_set_rect(RTGUI_WIDGET(next_btn), &rect);
+		/* 添加按钮到视图中 */
 		rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(next_btn));
 
-		/* get view's rect */
+		/* 获得视图的位置信息 */
 		rtgui_widget_get_rect(RTGUI_WIDGET(view), &rect);
 		rect.x1 += 5; rect.y2 -= 5;
 		rect.x2 = rect.x1 + 50; rect.y1 = rect.y2 - 20;
 
-		/* create previous button */
+		/* 创建"上一个"按钮 */
 		prev_btn = rtgui_button_create("Prev");
+		/* 设置onbutton动作到demo_view_prev函数 */
 		rtgui_button_set_onbutton(prev_btn, demo_view_prev);
+		/* 设置按钮的位置信息 */
 		rtgui_widget_set_rect(RTGUI_WIDGET(prev_btn), &rect);
+		/* 添加按钮到视图中 */
 		rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(prev_btn));
     }
 
+    /* 返回创建的视图 */
 	return view;
 }
 
+/* 这个函数用于返回演示视图的对外可用区域 */
 void demo_view_get_rect(rtgui_view_t* view, rtgui_rect_t *rect)
 {
 	RT_ASSERT(view != RT_NULL);
 	RT_ASSERT(rect != RT_NULL);
 
 	rtgui_widget_get_rect(RTGUI_WIDGET(view), rect);
-	/* remove the command button rect */
+	/* 去除演示标题和下方按钮的区域 */
 	rect->y1 += 45;
 	rect->y2 -= 25;
 }
 
+/* 当是标准版本时，这个函数用于返回自动布局引擎box控件 */
 #ifndef RTGUI_USING_SMALL_SIZE
 rtgui_box_t* demo_view_create_box(rtgui_view_t* view, int orient)
 {
 	rtgui_rect_t rect;
 	rtgui_box_t* box;
 
-	/* get rect of view */
+	/* 获得视图的位置信息 */
 	rtgui_widget_get_rect(RTGUI_WIDGET(view), &rect);
 	rect.y1 += 45;
 	rect.y2 -= 25;
 
+    /* 创建一个自动布局引擎 */
 	box = rtgui_box_create(orient, &rect);
+	/* 添加box控件到视图中 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(box));
 
 	return box;
 }
 #endif
 
+/* 这个函数用于显示当前的视图 */
 void demo_view_show()
 {
 	if (demo_view_number != 0)
 	{
-		rtgui_view_show(demo_view_list[demo_view_current], RT_FALSE);		
+		rtgui_view_show(demo_view_list[demo_view_current], RT_FALSE);
 	}
 }
-

examples/gui/demo_view.h

@@ -1,3 +1,16 @@
+/*
+ * 程序清单：view演示
+ *
+ * 这是一个视图的演示，也是为了配合整个GUI演示而制作的视图，或者说，其他大多数控件的演示
+ * 都是采用，先创建一个demo_view（演示视图），然后再在这个演示视图上添加相应的控件。
+ *
+ * 这个演示视图默认上方带一个演示标题，下方带两个按钮，点击它切换到前一个视图或后一个视图。
+ * 针对控件演示而言，这个演示视图最重要的是提供了一个可显示的区域，只需要在这块区域上添加
+ * 控件即可达到演示的目的。
+ *
+ * 获得这个显示区域的函数是：
+ * demo_view_get_rect函数。
+ */
 #ifndef __DEMO_VIEW_H__
 #define __DEMO_VIEW_H__
 
@@ -5,14 +18,18 @@
 #include <rtgui/widgets/view.h>
 #include <rtgui/widgets/workbench.h>
 
+/* 如果是标准版本，可以启用box自动布局引擎 */
 #ifndef RTGUI_USING_SMALL_SIZE
 #include <rtgui/widgets/box.h>
 #endif
 
+/* 创建一个演示视图，需要给出这个视图所在的workbench和演示标题 */
 rtgui_view_t* demo_view(rtgui_workbench_t* workbench, const char* title);
+/* 获得演示视图提供给演示控件用的区域信息 */
 void demo_view_get_rect(rtgui_view_t* view, rtgui_rect_t *rect);
 void demo_view_show(void);
 
+/* 如果是标准版，可以调用这个函数获得一个自动布局引擎 */
 #ifndef RTGUI_USING_SMALL_SIZE
 rtgui_box_t* demo_view_create_box(rtgui_view_t* view, int orient);
 #endif

examples/gui/demo_view_button.c

@@ -1,6 +1,13 @@
+/*
+ * 程序清单：button控件演示
+ *
+ * 这个例子会在创建出的view上添加几个不同类型的button控件
+ */
+
 #include "demo_view.h"
 #include <rtgui/widgets/button.h>
 
+/* 创建用于演示button控件的视图 */
 rtgui_view_t* demo_view_button(rtgui_workbench_t* workbench)
 {
 	rtgui_rect_t rect;
@@ -8,43 +15,62 @@ rtgui_view_t* demo_view_button(rtgui_workbench_t* workbench)
 	rtgui_button_t* button;
 	rtgui_font_t* font;
 
-	/* create a demo view */
+	/* 先创建一个演示用的视图 */
 	view = demo_view(workbench, "Button View");
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 100;
 	rect.y1 += 5; rect.y2 = rect.y1 + 20;
+	/* 创建一个button控件 */
 	button = rtgui_button_create("Red");
+	/* 设置label控件的前景色为红色 */
 	RTGUI_WIDGET_FOREGROUND(RTGUI_WIDGET(button)) = red;
+	/* 设置button的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(button), &rect);
+	/* view是一个container控件，调用add_child方法添加这个button控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(button));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 100;
 	rect.y1 += 5 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个button控件 */
 	button = rtgui_button_create("Blue");
+	/* 设置label控件的前景色为蓝色 */
 	RTGUI_WIDGET_FOREGROUND(RTGUI_WIDGET(button)) = blue;
+	/* 设置button的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(button), &rect);
+	/* view是一个container控件，调用add_child方法添加这个button控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(button));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 100;
 	rect.y1 += 5 + 25 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个button控件 */
 	button = rtgui_button_create("12 font");
+	/* 设置字体为12点阵的asc字体 */
 	font = rtgui_font_refer("asc", 12);
 	RTGUI_WIDGET_FONT(RTGUI_WIDGET(button)) = font;
+	/* 设置button的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(button), &rect);
+	/* view是一个container控件，调用add_child方法添加这个button控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(button));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 100;
 	rect.y1 += 5 + 25 + 25 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个button控件 */
 	button = rtgui_button_create("16 font");
+	/* 设置字体为16点阵的asc字体 */
 	font = rtgui_font_refer("asc", 16);
 	RTGUI_WIDGET_FONT(RTGUI_WIDGET(button)) = font;
+	/* 设置button的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(button), &rect);
+	/* view是一个container控件，调用add_child方法添加这个button控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(button));
 
 	return view;
 }
-

examples/gui/demo_view_checkbox.c

@@ -1,6 +1,13 @@
+/*
+ * 程序清单：checkbox控件演示
+ *
+ * 这个例子会在创建出的view上添加几个checkbox控件
+ */
+
 #include "demo_view.h"
 #include <rtgui/widgets/checkbox.h>
 
+/* 创建用于演示checkbox控件的视图 */
 rtgui_view_t* demo_view_checkbox(rtgui_workbench_t* workbench)
 {
 	rtgui_rect_t rect;
@@ -8,44 +15,62 @@ rtgui_view_t* demo_view_checkbox(rtgui_workbench_t* workbench)
 	rtgui_checkbox_t* checkbox;
 	rtgui_font_t* font;
 
-	/* create a demo view */
+	/* 先创建一个演示用的视图 */
 	view = demo_view(workbench, "CheckBox View");
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 100;
 	rect.y1 += 5; rect.y2 = rect.y1 + 20;
+	/* 创建一个checkbox控件 */
 	checkbox = rtgui_checkbox_create("Red");
+	/* 设置前景色为红色 */
 	RTGUI_WIDGET_FOREGROUND(RTGUI_WIDGET(checkbox)) = red;
+	/* 设置checkbox的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(checkbox), &rect);
+	/* view是一个container控件，调用add_child方法添加这个checkbox控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(checkbox));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 100;
 	rect.y1 += 5 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个checkbox控件 */
 	checkbox = rtgui_checkbox_create("Blue");
+	/* 设置前景色为蓝色 */
 	RTGUI_WIDGET_FOREGROUND(RTGUI_WIDGET(checkbox)) = blue;
+	/* 设置checkbox的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(checkbox), &rect);
+	/* view是一个container控件，调用add_child方法添加这个checkbox控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(checkbox));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 100;
 	rect.y1 += 5 + 25 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个checkbox控件 */
 	checkbox = rtgui_checkbox_create("12 font");
+	/* 设置字体为12点阵 */
 	font = rtgui_font_refer("asc", 12);
 	RTGUI_WIDGET_FONT(RTGUI_WIDGET(checkbox)) = font;
+	/* 设置checkbox的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(checkbox), &rect);
+	/* view是一个container控件，调用add_child方法添加这个checkbox控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(checkbox));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 100;
 	rect.y1 += 5 + 25 + 25 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个checkbox控件 */
 	checkbox = rtgui_checkbox_create("16 font");
+	/* 设置字体为16点阵 */
 	font = rtgui_font_refer("asc", 16);
 	RTGUI_WIDGET_FONT(RTGUI_WIDGET(checkbox)) = font;
+	/* 设置checkbox的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(checkbox), &rect);
+	/* view是一个container控件，调用add_child方法添加这个checkbox控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(checkbox));
 
 	return view;
 }
-
-

examples/gui/demo_view_label.c

@@ -1,6 +1,12 @@
+/*
+ * 程序清单：label控件演示
+ *
+ * 这个例子会在创建出的view上添加几个不同类型的label控件
+ */
 #include "demo_view.h"
 #include <rtgui/widgets/label.h>
 
+/* 创建用于演示label控件的视图 */
 rtgui_view_t* demo_view_label(rtgui_workbench_t* workbench)
 {
 	rtgui_rect_t rect;
@@ -8,52 +14,80 @@ rtgui_view_t* demo_view_label(rtgui_workbench_t* workbench)
 	rtgui_label_t* label;
 	rtgui_font_t* font;
 
-	/* create a demo view */
+	/* 先创建一个演示用的视图 */
 	view = demo_view(workbench, "Label View");
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 -= 5;
 	rect.y1 += 5; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("Red Left");
+	/* 设置label控件上的文本对齐方式为：左对齐 */
 	RTGUI_WIDGET_TEXTALIGN(RTGUI_WIDGET(label)) = RTGUI_ALIGN_LEFT;
+	/* 设置label控件的前景色为红色 */
 	RTGUI_WIDGET_FOREGROUND(RTGUI_WIDGET(label)) = red;
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+	/* view是一个container控件，调用add_child方法添加这个label控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 -= 5;
 	rect.y1 += 5 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("Blue Right");
+	/* 设置label控件上的文本对齐方式为：右对齐 */
 	RTGUI_WIDGET_TEXTALIGN(RTGUI_WIDGET(label)) = RTGUI_ALIGN_RIGHT;
+	/* 设置label控件的前景色为蓝色 */
 	RTGUI_WIDGET_FOREGROUND(RTGUI_WIDGET(label)) = blue;
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+	/* view是一个container控件，调用add_child方法添加这个label控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 -= 5;
 	rect.y1 += 5 + 25 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("Green Center");
+	/* 设置label控件的前景色为绿色 */
 	RTGUI_WIDGET_FOREGROUND(RTGUI_WIDGET(label)) = green;
+	/* 设置label控件上的文本对齐方式为：右对齐 */
 	RTGUI_WIDGET_TEXTALIGN(RTGUI_WIDGET(label)) = RTGUI_ALIGN_CENTER_HORIZONTAL;
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+	/* view是一个container控件，调用add_child方法添加这个label控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 -= 5;
 	rect.y1 += 5 + 25 + 25 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("12 font");
+	/* 设置字体为12点阵的asc字体 */
 	font = rtgui_font_refer("asc", 12);
 	RTGUI_WIDGET_FONT(RTGUI_WIDGET(label)) = font;
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+	/* view是一个container控件，调用add_child方法添加这个label控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
-	rect.x1 += 5; 
+	rect.x1 += 5;
 	rect.y1 += 5 + 25 + 25 + 25 + 25; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("16 font");
+	/* 设置字体为16点阵的asc字体 */
 	font = rtgui_font_refer("asc", 16);
 	RTGUI_WIDGET_FONT(RTGUI_WIDGET(label)) = font;
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+	/* view是一个container控件，调用add_child方法添加这个label控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 
 	return view;

examples/gui/demo_view_mywidget.c

@@ -1,27 +1,37 @@
+/*
+ * 程序清单：自定义控件演示
+ *
+ * 这个例子会在创建出的view上添加两个自定义控件
+ */
 #include "demo_view.h"
 #include "mywidget.h"
 
+/* 创建用于演示自定义控件的视图 */
 rtgui_view_t *demo_view_mywidget(rtgui_workbench_t* workbench)
 {
 	rtgui_view_t *view;
 	rtgui_rect_t rect;
 	rtgui_mywidget_t *mywidget;
 
-	/* create a demo view */
+	/* 先创建一个演示用的视图 */
 	view = demo_view(workbench, "MyWidget View");
 
-	/* get demo view rect */
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.y1 + 80;
 	rect.y1 += 5; rect.y2 = rect.y1 + 80;
+	/* 创建一个自定义控件 */
 	mywidget = rtgui_mywidget_create(&rect);
+	/* view是一个container控件，调用add_child方法添加这个自控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(mywidget));
 
-	/* get demo view rect */
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 25; rect.x2 = rect.y1 + 40;
 	rect.y1 += 5 + 100; rect.y2 = rect.y1 + 40;
+	/* 创建一个自定义控件 */
 	mywidget = rtgui_mywidget_create(&rect);
+	/* view是一个container控件，调用add_child方法添加这个自控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(mywidget));
 
 	return view;

examples/gui/demo_view_radiobox.c

@@ -1,7 +1,14 @@
+/*
+ * 程序清单：radiobox控件演示
+ *
+ * 这个例子会在创建出的view上添加两个不同方向的radiobox控件
+ */
+
 #include "demo_view.h"
 #include <rtgui/widgets/radiobox.h>
 
-static char* radio_item[5] =
+/* 用于显示垂直方向的radio文本项数组 */
+static char* radio_item_v[5] =
 {
     "one",
     "two",
@@ -10,39 +17,49 @@ static char* radio_item[5] =
     "item 2"
 };
 
+/* 用于显示水平方向的radio文本项数组 */
 static char* radio_item_h[3] =
 {
 	"one", "two", "three"
 };
 
+/* 创建用于演示radiobox控件的视图 */
 rtgui_view_t* demo_view_radiobox(rtgui_workbench_t* workbench)
 {
     rtgui_rect_t rect;
     rtgui_view_t* view;
     rtgui_radiobox_t* radiobox;
 
+	/* 先创建一个演示用的视图 */
     view = demo_view(workbench, "RadioBox View");
-    demo_view_get_rect(view, &rect);
 
+    /* 获得视图的位置信息 */
+    demo_view_get_rect(view, &rect);
     rect.x1 += 5; rect.x2 -= 5;
     rect.y1 += 5; rect.y2 = rect.y1 + 5 * 25;
 
-    radiobox = rtgui_radiobox_create("Radio Box", RTGUI_VERTICAL, radio_item, 5);
+    /* 创建一个垂直方向显示的radiobox控件，文本项是radio_item_v数组，共5个项 */
+    radiobox = rtgui_radiobox_create("Radio Box", RTGUI_VERTICAL, radio_item_v, 5);
+    /* 设置当前选择的数组是第0项 */
 	rtgui_radiobox_set_selection(radiobox, 0);
-
+    /* 添加radiobox控件到视图中 */
     rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(radiobox));
+    /* 设置radiobox控件的位置信息 */
     rtgui_widget_set_rect(RTGUI_WIDGET(radiobox), &rect);
 
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
     rect.x1 += 5; rect.x2 -= 5;
     rect.y1 += 5 + 5 * 25; rect.y2 = rect.y1 + 60;
 
+    /* 创建一个水平方向显示的radiobox控件，文本项是radio_item_h数组，共3个项 */
     radiobox = rtgui_radiobox_create("Radio Box", RTGUI_HORIZONTAL, radio_item_h, 3);
+    /* 设置当前选择的数组是第0项 */
 	rtgui_radiobox_set_selection(radiobox, 0);
-
+    /* 添加radiobox控件到视图中 */
     rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(radiobox));
+    /* 设置radiobox控件的位置信息 */
     rtgui_widget_set_rect(RTGUI_WIDGET(radiobox), &rect);
 
     return view;
 }
-

examples/gui/demo_view_textbox.c

@@ -1,7 +1,13 @@
+/*
+ * 程序清单：texbox控件演示
+ *
+ * 这个例子会在创建出的view上添加几个不同类型的textbox控件
+ */
 #include "demo_view.h"
 #include <rtgui/widgets/label.h>
 #include <rtgui/widgets/textbox.h>
 
+/* 创建用于演示textbox控件的视图 */
 rtgui_view_t* demo_view_textbox(rtgui_workbench_t* workbench)
 {
 	rtgui_rect_t rect, textbox_rect;
@@ -9,52 +15,79 @@ rtgui_view_t* demo_view_textbox(rtgui_workbench_t* workbench)
 	rtgui_label_t* label;
 	rtgui_textbox_t* text;
 
-	/* create a demo view */
+	/* 先创建一个演示用的视图 */
 	view = demo_view(workbench, "TextBox View");
 
-	/* add label */
+    /* 获得视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 30;
 	rect.y1 += 5; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("Ãû×Ö: ");
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+	/* view是一个container控件，调用add_child方法添加这个label控件 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 
+    /* 让textbox_rect赋值到rect，以计算textbox控件的位置 */
 	textbox_rect = rect;
 	textbox_rect.x1 = textbox_rect.x2 + 5; textbox_rect.x2 = textbox_rect.x1 + 160;
+    /* 创建一个textbox控件 */
 	text = rtgui_textbox_create("bernard");
+    /* 设置textbox控件的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(text), &textbox_rect);
+    /* 添加textbox控件到视图中 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(text));
 
+    /* 计算下一个label控件的位置 */
 	rect.y1 += 23; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("Óʼþ: ");
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+    /* 添加label控件到视图中 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 	textbox_rect = rect;
 	textbox_rect.x1 = textbox_rect.x2 + 5; textbox_rect.x2 = textbox_rect.x1 + 160;
+    /* 创建一个textbox控件 */
 	text = rtgui_textbox_create("bernard.xiong@gmail.com");
+    /* 设置textbox控件的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(text), &textbox_rect);
+    /* 添加textbox控件到视图中 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(text));
 
 	rect.y1 += 23; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("ÃÜÂë: ");
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+    /* 添加label控件到视图中 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 	textbox_rect = rect;
 	textbox_rect.x1 = textbox_rect.x2 + 5; textbox_rect.x2 = textbox_rect.x1 + 160;
+    /* 创建一个textbox控件 */
 	text = rtgui_textbox_create("rt-thread");
+    /* 设置textbox显示文本为掩码形式(即显示为*号，适合于显示密码的情况) */
 	text->flag |= RTGUI_TEXTBOX_MASK;
+    /* 设置textbox控件的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(text), &textbox_rect);
+    /* 添加textbox控件到视图中 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(text));
 
 	rect.y1 += 23; rect.y2 = rect.y1 + 20;
+	/* 创建一个label控件 */
 	label = rtgui_label_create("Ö÷Ò³: ");
+	/* 设置label的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
+    /* 添加label控件到视图中 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 	textbox_rect = rect;
 	textbox_rect.x1 = textbox_rect.x2 + 5; textbox_rect.x2 = textbox_rect.x1 + 160;
+    /* 创建一个textbox控件 */
 	text = rtgui_textbox_create("http://www.rt-thread.org");
+    /* 设置textbox控件的位置 */
 	rtgui_widget_set_rect(RTGUI_WIDGET(text), &textbox_rect);
+    /* 添加textbox控件到视图中 */
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(text));
 
 	return view;

examples/gui/mywidget.c

@@ -68,9 +68,11 @@ static void rtgui_mywidget_onmouse(struct rtgui_mywidget* me, struct rtgui_event
 	}
 }
 
-static rt_bool_t rtgui_mywidget_event_handler(struct rtgui_widget* widget, struct rtgui_event* event)
+/* mywidget控件的事件处理函数 */
+rt_bool_t rtgui_mywidget_event_handler(struct rtgui_widget* widget, struct rtgui_event* event)
 {
-	struct rtgui_mywidget* me = (struct rtgui_mywidget*)widget;
+    /* 调用事件处理函数时，widget指针指向控件本身，所以先获得相应控件对象的指针 */
+	struct rtgui_mywidget* me = RTGUI_MYWIDGET(widget);
 
 	switch (event->type)
 	{
@@ -86,44 +88,47 @@ static rt_bool_t rtgui_mywidget_event_handler(struct rtgui_widget* widget, struc
 
 	/* 其他事件调用父类的事件处理函数 */
 	default:
-		rtgui_widget_event_handler(widget, event);
+		return rtgui_widget_event_handler(widget, event);
 	}
 
 	return RT_FALSE;
 }
 
+/* 自定义控件的构造函数 */
 static void _rtgui_mywidget_constructor(rtgui_mywidget_t *mywidget)
 {
-	/* 初始化控件并设置事件处理函数 */
+    /* 默认这个控件接收聚焦 */
 	RTGUI_WIDGET(mywidget)->flag |= RTGUI_WIDGET_FLAG_FOCUSABLE;
+	/* 初始化控件并设置事件处理函数 */
 	rtgui_widget_set_event_handler(RTGUI_WIDGET(mywidget), rtgui_mywidget_event_handler);
 
+    /* 初始状态时OFF */
 	mywidget->status = MYWIDGET_STATUS_OFF;
 }
 
-static void _rtgui_mywidget_destructor(rtgui_mywidget_t *mywidget)
+/* 获得控件的类型 */
-{
-}
-
 rtgui_type_t *rtgui_mywidget_type_get(void)
 {
+    /* 控件的类型是一个静态变量，默认是NULL */
 	static rtgui_type_t *mywidget_type = RT_NULL;
 
 	if (!mywidget_type)
 	{
+	    /* 当控件类型不存在时，创建它，并指定这种类型数据的大小及指定相应的构造函数和析构函数 */
 		mywidget_type = rtgui_type_create("mywidget", RTGUI_WIDGET_TYPE,
 			sizeof(rtgui_mywidget_t),
-			RTGUI_CONSTRUCTOR(_rtgui_mywidget_constructor),
+			RTGUI_CONSTRUCTOR(_rtgui_mywidget_constructor), RT_NULL);
-			RTGUI_DESTRUCTOR(_rtgui_mywidget_destructor));
 	}
 
 	return mywidget_type;
 }
 
+/* 创建一个自定义控件 */
 struct rtgui_mywidget* rtgui_mywidget_create(rtgui_rect_t* r)
 {
     struct rtgui_mywidget* me;
 
+    /* 让rtgui_widget创建出一个指定类型：RTGUI_MYWIDGET_TYPE类型的控件 */
     me = (struct rtgui_mywidget*) rtgui_widget_create (RTGUI_MYWIDGET_TYPE);
     if (me != RT_NULL)
     {
@@ -133,6 +138,7 @@ struct rtgui_mywidget* rtgui_mywidget_create(rtgui_rect_t* r)
 	return me;
 }
 
+/* 删除一个自定义控件 */
 void rtgui_mywidget_destroy(struct rtgui_mywidget* me)
 {
 	rtgui_widget_destroy(RTGUI_WIDGET(me));

examples/gui/mywidget.h

@@ -1,22 +1,34 @@
+/*
+ * 程序清单：自定义控件
+ *
+ * 这个例子是要实现一个自定义控件，外观大致如
+ *   |
+ * --o--
+ *   |
+ * 的形状，中间的o色彩表示了当前的状态，ON状态时是绿色，OFF状态时是红色。
+ * 并且，这个o位置接受鼠标点击，点击下切换下相应的状态。
+ */
 #ifndef __MY_WIDGET_H__
 #define __MY_WIDGET_H__
 
 #include <rtgui/rtgui.h>
 #include <rtgui/widgets/widget.h>
 
+/* 自定义控件的状态值定义 */
 #define MYWIDGET_STATUS_ON	1
 #define MYWIDGET_STATUS_OFF	0
 
-/** Gets the type of a button */
+/** 每个控件会有一个类型，通过如下的宏获得控件相应的类型信息 */
 #define RTGUI_MYWIDGET_TYPE       (rtgui_mywidget_type_get())
-/** Casts the object to an rtgui_button */
+/** 对一个对象实例，可以通过下面的宏实现类型转换 */
 #define RTGUI_MYWIDGET(obj)       (RTGUI_OBJECT_CAST((obj), RTGUI_MYWIDGET_TYPE, rtgui_mywidget_t))
-/** Checks if the object is an rtgui_button */
+/** 可以通过下面的宏以决定一个具体实例是否是自定义控件类型 */
 #define RTGUI_IS_MYWIDGET(obj)    (RTGUI_OBJECT_CHECK_TYPE((obj), RTGUI_MYWIDGET_TYPE))
 
-/* 个性化控件 */
+/* 个性化控件类定义 */
 struct rtgui_mywidget
 {
+    /* 这个控件是继承自rtgui_widget控件 */
 	struct rtgui_widget parent;
 
 	/* 状态：ON、OFF */
@@ -24,7 +36,17 @@ struct rtgui_mywidget
 };
 typedef struct rtgui_mywidget rtgui_mywidget_t;
 
+/* 这个函数用于获得自定义控件的类型 */
+rtgui_type_t *rtgui_mywidget_type_get(void);
+
+/* 控件的创建和删除 */
 struct rtgui_mywidget* rtgui_mywidget_create(rtgui_rect_t* r);
 void rtgui_mywidget_destroy(struct rtgui_mywidget* me);
 
+/* 控件的默认事件处理函数。
+ * 对一个控件而言，如果派生自它的子控件很可能会调用父控件的事件处理函数，
+ * 所以这里采用公开声明的方式。
+ */
+rt_bool_t rtgui_mywidget_event_handler(struct rtgui_widget* widget, struct rtgui_event* event);
+
 #endif