add Chinese Comments

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

examples/gui/demo_fnview.c

@@ -1,31 +1,43 @@
+/*
+ * 程序清单：文件列表视图演示
+ *
+ * 这个例子会先创建出一个演示用的view，当点击上面的按钮时会按照模式显示的形式显示
+ * 新的文件列表视图。
+ */
 #include "demo_view.h"
 #include <rtgui/widgets/label.h>
 #include <rtgui/widgets/button.h>
 #include <rtgui/widgets/filelist_view.h>
 
+/* 用于显示选择文件名的文本标签 */
 static rtgui_label_t* label;
+/* 触发文件列表视图的按钮回调函数 */
 static void open_btn_onbutton(rtgui_widget_t* widget, struct rtgui_event* event)
 {
-	/* create a file list view */
 	rtgui_filelist_view_t *view;
 	rtgui_workbench_t *workbench;
 	rtgui_rect_t rect;
 
+	/* 获得顶层的workbench对象 */
 	workbench = RTGUI_WORKBENCH(rtgui_widget_get_toplevel(widget));
 	rtgui_widget_get_rect(RTGUI_WIDGET(workbench), &rect);
 
+	/* 针对Win32平台和其他平台做的不同的其实目录位置 */
 #ifdef _WIN32
 	view = rtgui_filelist_view_create(workbench, "d:\\", "*.*", &rect);
 #else
 	view = rtgui_filelist_view_create(workbench, "/", "*.*", &rect);
 #endif
+
+	/* 采用模式形式显示文件列表视图 */
 	if (rtgui_view_show(RTGUI_VIEW(view), RT_TRUE) == RTGUI_MODAL_OK)
 	{
 		char path[32];
 
-		/* set label */
+		/* 在文件列表视图中成功选择文件，这里获得相应的路径名 */
 		rtgui_filelist_get_fullpath(view, path, sizeof(path));
 
+		/* 设置文件路径到文本标签 */
 		rtgui_label_set_text(label, path);
 	}
 
@@ -33,6 +45,7 @@ static void open_btn_onbutton(rtgui_widget_t* widget, struct rtgui_event* event)
 	rtgui_view_destroy(RTGUI_VIEW(view));
 }
 
+/* 创建用于演示文件列表视图的视图 */
 rtgui_view_t* demo_fn_view(rtgui_workbench_t* workbench)
 {
 	rtgui_rect_t rect;
@@ -40,25 +53,31 @@ rtgui_view_t* demo_fn_view(rtgui_workbench_t* workbench)
 	rtgui_button_t* open_btn;
 	rtgui_font_t* font;
 
+	/* 默认采用12字体的显示 */
 	font = rtgui_font_refer("asc", 12);
 
+	/* 创建演示用的视图 */
 	view = demo_view(workbench, "FileList View");
+	/* 获得演示视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 
 	rect.x1 += 5;
 	rect.x2 -= 5;
 	rect.y1 += 5;
 	rect.y2 = rect.y1 + 20;
+	/* 创建显示文件路径用的文本标签 */
 	label = rtgui_label_create("fn: ");
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(label));
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
 	RTGUI_WIDGET_FONT(RTGUI_WIDGET(label)) = font;
 
+	/* 获得演示视图的位置信息 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5;
 	rect.x2 = rect.x1 + 80;
 	rect.y1 += 30;
 	rect.y2 = rect.y1 + 20;
+	/* 创建按钮以触发一个新的文件列表视图 */
 	open_btn = rtgui_button_create("Open File");
 	rtgui_container_add_child(RTGUI_CONTAINER(view), RTGUI_WIDGET(open_btn));
 	rtgui_widget_set_rect(RTGUI_WIDGET(open_btn), &rect);

examples/gui/demo_listview.c

@@ -1,3 +1,9 @@
+/*
+ * 程序清单：列表视图演示
+ *
+ * 这个例子会先创建出一个演示用的view，当点击上面的按钮时会按照模式显示的形式显示
+ * 新的列表视图
+ */
 #include "demo_view.h"
 #include <rtgui/widgets/label.h>
 #include <rtgui/widgets/button.h>
@@ -8,6 +14,7 @@ static rtgui_workbench_t* workbench = RT_NULL;
 static rtgui_list_view_t* _view = RT_NULL;
 static rtgui_image_t* return_image = RT_NULL;
 
+/* 列表项的动作函数 */
 static void listitem_action(void* parameter)
 {
 	char label_text[32];
@@ -27,6 +34,7 @@ static void listitem_action(void* parameter)
 	rect.y1 += 5;
 	rect.y2 = rect.y1 + 20;
 
+	/* 添加相应的标签 */
 	rt_sprintf(label_text, "动作 %d", no);
 	label = rtgui_label_create(label_text);
 
@@ -37,15 +45,18 @@ static void listitem_action(void* parameter)
 	rtgui_win_show(win, RT_FALSE);
 }
 
+/* 返回功能的动作函数 */
 static void return_action(void* parameter)
 {
 	if (_view != RT_NULL)
 	{
+		/* 删除列表视图 */
 		rtgui_view_destroy(RTGUI_VIEW(_view));
 		_view = RT_NULL;
 	}
 }
 
+/* 各个列表项定义 */
 static struct rtgui_list_item items[] =
 {
 	{"列表项1", RT_NULL, listitem_action, (void*)1},
@@ -56,22 +67,26 @@ static struct rtgui_list_item items[] =
 	{"返回",    RT_NULL, return_action,    RT_NULL},
 };
 
+/* 打开列表视图用的按钮触发函数 */
 static void open_btn_onbutton(rtgui_widget_t* widget, struct rtgui_event* event)
 {
-	/* create a file list view */
 	rtgui_rect_t rect;
 
+	/* 获得顶层的workbench */
 	workbench = RTGUI_WORKBENCH(rtgui_widget_get_toplevel(widget));
 	rtgui_widget_get_rect(RTGUI_WIDGET(workbench), &rect);
 
+	/* 创建一个列表视图， 项指定为items */
 	_view = rtgui_list_view_create(items, sizeof(items)/sizeof(struct rtgui_list_item),
 		&rect);
+	/* 在workbench中添加相应的视图 */
 	rtgui_workbench_add_view(workbench, RTGUI_VIEW(_view));
 
 	/* 模式显示视图 */
 	rtgui_view_show(RTGUI_VIEW(_view), RT_FALSE);
 }
 
+/* 创建用于演示列表视图的视图 */
 rtgui_view_t* demo_listview_view(rtgui_workbench_t* workbench)
 {
 	rtgui_rect_t rect;
@@ -80,6 +95,7 @@ rtgui_view_t* demo_listview_view(rtgui_workbench_t* workbench)
 
 	view = demo_view(workbench, "列表视图演示");
 
+	/* 添加动作按钮 */
 	demo_view_get_rect(view, &rect);
 	rect.x1 += 5;
 	rect.x2 = rect.x1 + 80;

examples/gui/demo_view_dc.c

@@ -1,10 +1,20 @@
+/*
+ * 程序清单：DC操作演示
+ *
+ * 这个例子会在创建出的view上进行DC操作的演示
+ */
+
 #include "demo_view.h"
 #include <rtgui/rtgui_system.h>
 #include <rtgui/widgets/label.h>
 #include <rtgui/widgets/slider.h>
 
+/*
+ * view的事件处理函数
+ */
 rt_bool_t dc_event_handler(rtgui_widget_t* widget, rtgui_event_t *event)
 {
+	/* 仅对PAINT事件进行处理 */
 	if (event->type == RTGUI_EVENT_PAINT)
 	{
 		struct rtgui_dc* dc;
@@ -12,22 +22,27 @@ rt_bool_t dc_event_handler(rtgui_widget_t* widget, rtgui_event_t *event)
 		rt_uint32_t vx[] = {20, 50, 60, 45, 60, 20};
 		rt_uint32_t vy[] = {150, 50, 90, 60, 45, 50};
 
-		/* 因为用的是demo view，上面本身有一部分控件，所以在绘图时先要让demo view先绘图 */
+		/*
+		 * 因为用的是demo view，上面本身有一部分控件，所以在绘图时先要让demo view
+		 * 先绘图
+		 */
 		rtgui_view_event_handler(widget, event);
 
 		/************************************************************************/
-		/* 下面的是DC的处理                                             */
+		/* 下面的是DC的操作                                                     */
 		/************************************************************************/
 
 		/* 获得控件所属的DC */
 		dc = rtgui_dc_begin_drawing(widget);
-		if (dc == RT_NULL) /* 如果不能正常获得DC，返回（如果控件或父控件是隐藏状态，DC是获取不成功的） */
+		/* 如果不能正常获得DC，返回（如果控件或父控件是隐藏状态，DC是获取不成功的） */
+		if (dc == RT_NULL)
 			return RT_FALSE;
 
 		/* 获得demo view允许绘图的区域 */
 		demo_view_get_rect(RTGUI_VIEW(widget), &rect);
 
 		rtgui_dc_set_textalign(dc, RTGUI_ALIGN_BOTTOM | RTGUI_ALIGN_CENTER_HORIZONTAL);
+		/* 显示GUI的版本信息 */
 #ifdef RTGUI_USING_SMALL_SIZE
 		rtgui_dc_draw_text(dc, "RT-Thread/GUI小型版本", &rect);
 #else
@@ -109,24 +124,27 @@ rt_bool_t dc_event_handler(rtgui_widget_t* widget, rtgui_event_t *event)
 			rect.y1 += 20;
 			rect.y2 += 20;
 		}
+
 		/* 绘图完成 */
 		rtgui_dc_end_drawing(dc);
 	}
 	else
 	{
-		/* 调用默认的事件处理函数 */
+		/* 其他事件，调用默认的事件处理函数 */
 		return rtgui_view_event_handler(widget, event);
 	}
 
 	return RT_FALSE;
 }
 
+/* 创建用于DC操作演示用的视图 */
 rtgui_view_t *demo_view_dc(rtgui_workbench_t* workbench)
 {
 	rtgui_view_t *view;
 
 	view = demo_view(workbench, "DC Demo");
 	if (view != RT_NULL)
+		/* 设置成自己的事件处理函数 */
 		rtgui_widget_set_event_handler(RTGUI_WIDGET(view), dc_event_handler);
 
 	return view;

examples/gui/demo_view_image.c

@@ -1,3 +1,9 @@
+/*
+ * 程序清单：DC上显示图像演示
+ *
+ * 这个例子会在创建出的view上显示图像
+ */
+
 #include "demo_view.h"
 #include <rtgui/widgets/button.h>
 #include <rtgui/widgets/filelist_view.h>
@@ -5,26 +11,29 @@
 static rtgui_image_t* image = RT_NULL;
 static rtgui_view_t* _view = RT_NULL;
 
+/* 打开按钮的回调函数 */
 static void open_btn_onbutton(rtgui_widget_t* widget, struct rtgui_event* event)
 {
-	/* create a file list view */
 	rtgui_filelist_view_t *view;
 	rtgui_workbench_t *workbench;
 	rtgui_rect_t rect;
 
+	/* 获得顶层的workbench */
 	workbench = RTGUI_WORKBENCH(rtgui_widget_get_toplevel(widget));
 	rtgui_widget_get_rect(RTGUI_WIDGET(workbench), &rect);
 
+	/* WIN32平台上和真实设备上的初始路径处理 */
 #ifdef _WIN32
 	view = rtgui_filelist_view_create(workbench, "d:\\", "*.*", &rect);
 #else
 	view = rtgui_filelist_view_create(workbench, "/", "*.*", &rect);
 #endif
+	/* 模态显示一个文件列表视图，以提供给用户选择图像文件 */
 	if (rtgui_view_show(RTGUI_VIEW(view), RT_TRUE) == RTGUI_MODAL_OK)
 	{
 		char path[32], image_type[8];
 
-		/* set label */
+		/* 设置文件路径的标签 */
 		rtgui_filelist_get_fullpath(view, path, sizeof(path));
 		if (image != RT_NULL) rtgui_image_destroy(image);
 
@@ -32,15 +41,16 @@ static void open_btn_onbutton(rtgui_widget_t* widget, struct rtgui_event* event)
 
 		/* 获得图像的类型 */
 		if (rt_strstr(path, ".png") != RT_NULL ||
-			rt_strstr(path, ".PNG") != RT_NULL) 
+			rt_strstr(path, ".PNG") != RT_NULL)
 			strcat(image_type, "png");
 		if (rt_strstr(path, ".jpg") != RT_NULL ||
-			rt_strstr(path, ".JPG") != RT_NULL) 
+			rt_strstr(path, ".JPG") != RT_NULL)
 			strcat(image_type, "jpeg");
 		if (rt_strstr(path, ".hdc") != RT_NULL ||
-			rt_strstr(path, ".HDC") != RT_NULL) 
+			rt_strstr(path, ".HDC") != RT_NULL)
 			strcat(image_type, "hdc");
 
+		/* 如果图像文件有效，创建相应的rtgui_image对象 */
 		if (image_type[0] != '\0')
 			image = rtgui_image_create_from_file(image_type, path, RT_TRUE);
 	}
@@ -50,11 +60,12 @@ static void open_btn_onbutton(rtgui_widget_t* widget, struct rtgui_event* event)
 	rtgui_view_show(_view, RT_FALSE);
 }
 
+/* 演示视图的事件处理函数 */
 static rt_bool_t demo_view_event_handler(rtgui_widget_t* widget, rtgui_event_t *event)
 {
 	rt_bool_t result;
 
-	/* 用默认的事件处理函数 */
+	/* 先调用默认的事件处理函数(这里只关心PAINT事件，但演示视图还有本身的一些控件) */
 	result = rtgui_view_event_handler(widget, event);
 
 	if (event->type == RTGUI_EVENT_PAINT)
@@ -64,7 +75,8 @@ static rt_bool_t demo_view_event_handler(rtgui_widget_t* widget, rtgui_event_t *
 
 		/* 获得控件所属的DC */
 		dc = rtgui_dc_begin_drawing(widget);
-		if (dc == RT_NULL) /* 如果不能正常获得DC，返回（如果控件或父控件是隐藏状态，DC是获取不成功的） */
+		if (dc == RT_NULL)
+			/* 如果不能正常获得DC，返回(如果控件或父控件是隐藏状态，DC是获取不成功的) */
 			return RT_FALSE;
 
 		/* 获得demo view允许绘图的区域 */
@@ -72,7 +84,7 @@ static rt_bool_t demo_view_event_handler(rtgui_widget_t* widget, rtgui_event_t *
 
 		/* 获得图像显示区域 */
 		rect.x1 += 5; rect.x2 -= 5;
-		rect.y1 += 30; 
+		rect.y1 += 30;
 
 		if (image != RT_NULL)
 			rtgui_image_blit(image, dc, &rect);
@@ -84,15 +96,19 @@ static rt_bool_t demo_view_event_handler(rtgui_widget_t* widget, rtgui_event_t *
 	return result;
 }
 
+/* 创建用于显示图像的演示视图 */
 rtgui_view_t* demo_view_image(rtgui_workbench_t* workbench)
 {
 	rtgui_rect_t rect;
 	rtgui_button_t* open_btn;
 
+	/* 先创建一个演示视图 */
 	_view = demo_view(workbench, "图像演示");
 	if (_view != RT_NULL)
+		/* 设置默认的事件处理函数到demo_view_event_handler函数 */
 		rtgui_widget_set_event_handler(RTGUI_WIDGET(_view), demo_view_event_handler);
 
+	/* 添加一个按钮 */
 	demo_view_get_rect(_view, &rect);
 	rect.x1 += 5; rect.x2 = rect.x1 + 120;
 	rect.y2 = rect.y1 + 20;

examples/gui/demo_view_window.c

@@ -1,3 +1,9 @@
+/*
+ * 程序清单：窗口演示
+ *
+ * 这个例子会先创建出一个演示用的view，当点击上面的按钮时会不同的模式创建窗口
+ */
+
 #include <rtgui/rtgui.h>
 #include <rtgui/rtgui_system.h>
 #include <rtgui/widgets/window.h>
@@ -79,6 +85,7 @@ static void demo_win_onbutton(struct rtgui_widget* widget, rtgui_event_t* event)
 	rect.y1 += 5;
 	rect.y2 = rect.y1 + 20;
 
+	/* 添加一个文本标签 */
 	label = rtgui_label_create("这是一个普通窗口");
 	rtgui_widget_set_rect(RTGUI_WIDGET(label), &rect);
 	rtgui_container_add_child(RTGUI_CONTAINER(win), RTGUI_WIDGET(label));
@@ -91,10 +98,7 @@ static void demo_win_onbutton(struct rtgui_widget* widget, rtgui_event_t* event)
 static void demo_autowin_onbutton(struct rtgui_widget* widget, rtgui_event_t* event)
 {
 	rtgui_toplevel_t *parent;
-	struct rtgui_rect rect =
-		{
-			50, 50, 200, 200
-		};
+	struct rtgui_rect rect ={50, 50, 200, 200};
 
 	parent = RTGUI_TOPLEVEL(rtgui_widget_get_toplevel(widget));
 	msgbox = rtgui_win_create(parent, "Information", &rect, RTGUI_WIN_STYLE_DEFAULT);