4. 控件

本章导读：

AWTK框架为开发者提供了丰富的基础控件，开发者通过组合这些基础控件可以快速开发、创建复杂的GUI界面。控件是视图层的基本组成元素，是构建GUI界面的重要元素。熟练的使用控件是高效开发AWTK应用程序的必备技能。

4.1 简介

本章将阐述AWTK四大基本控件：窗口、基本控件、通用容器和扩展控件，内容包括各个控件提供的函数、属性、事件以及相关用法的示例。AWTK包括的控件及其继承关系详见awtk/docs/images/widget_overview.png。

4.2 widget

widget_t是所有控件、窗口和窗口管理器的基类。widget_t也是一个容器，可放其它widget_t到它的内部，形成一个树形结构。通常widget_t通过一个矩形区域向用户呈现一些信息，接受用户的输入，并据此做出适当反应。它负责控件的生命周期、通用状态、事件分发和Style的管理。

本类提供的接口（函数和属性）除非特别说明，一般都适用于子类控件。例如，list_view_t是widget_t的子类控件，在list_view控件中没有提供专门的API用于添加、删除list_item控件，但可以调用widget控件提供的widget_add_child和widget_remove_child函数完成。

4.2.1 函数

widget提供的函数详见下表，具体请查看AWTK_API手册，这里不累赘了。

函数名称	说明
widget_count_children	获取子控件的个数。
widget_get_child	获取指定索引的子控件。
widget_find_parent_by_name	通过名称查找父控件。
widget_find_parent_by_type	通过类型查找父控件。
widget_get_focused_widget	获取当前窗口中的焦点控件。
widget_get_native_window	获取原生窗口对象。
widget_index_of	获取控件在父控件中的索引编号。
widget_close_window	关闭控件所在的窗口。
widget_close_window_force	关闭控件所在的窗口。
widget_back	请求返回到前一个窗口。
widget_back_to_home	请求返回到home窗口。
widget_move	移动控件。
widget_move_to_center	移动控件到父控件中间。
widget_resize	调整控件的大小。
widget_move_resize	移动控件并调整控件的大小。
widget_move_resize_ex	移动控件并调整控件的大小。
widget_get_value	获取控件的值。只是对widget_get_prop的包装，值的意义由子类控件决定。
widget_set_value	设置控件的值。
widget_add_value	增加控件的值。
widget_get_value_int	获取控件的值。只是对widget_get_prop的包装，值的意义由子类控件决定。
widget_set_value_int	设置控件的值。
widget_add_value_int	增加控件的值。
widget_animate_value_to	设置控件的值(以动画形式变化到指定的值)。
widget_set_text	设置控件的文本。（如果字符串相同，则不会重复设置以及触发事件）
widget_set_text_ex	设置控件的文本。
widget_get_window_theme	获取控件的窗体样式。
widget_is_style_exist	查询指定的style是否存在。
widget_is_support_highlighter	判断widget是否支持高亮。
widget_use_style	启用指定的style。
widget_set_text_utf8	设置控件的文本。（如果字符串相同，则不会重复设置以及触发事件）
widget_set_text_utf8_ex	设置控件的文本。
widget_get_text_utf8	获取控件的文本。
widget_set_child_text_utf8	设置子控件的文本。
widget_get_child_text_utf8	获取子控件的文本。
widget_set_child_text_with_double	用一个浮点数去设置子控件的文本。
widget_set_child_text_with_int	用一个整数去设置子控件的文本。
widget_set_tr_text	获取翻译之后的文本，然后调用widget_set_text。
widget_get_enable	获取控件enable属性值。
widget_get_floating	获取控件floating属性值。
widget_get_auto_adjust_size	获取控件auto_adjust_size属性值。
widget_get_with_focus_state	获取控件with_focus_state属性值。
widget_get_focusable	获取控件focusable属性值。
widget_get_sensitive	获取控件sensitive属性值。
widget_get_visible	获取控件visible属性值。
widget_get_feedback	获取控件feedback属性值。
widget_get_text	获取控件的文本。
widget_to_local	将屏幕坐标转换成控件内的本地坐标，即相对于控件左上角的坐标。
widget_to_global	将控件内的本地坐标转换成全局坐标。
widget_to_screen_ex	将控件内的本地坐标根据祖父级控件转换成相对于祖父级控件的屏幕相对坐标。
widget_to_screen	将控件内的本地坐标转换成屏幕上的坐标。
widget_set_name	设置控件的名称。
widget_set_theme	设置theme的名称，用于动态切换主题。名称与当前主题名称相同，则重新加载全部资源。
widget_get_theme_name	获取 theme 的名称
widget_set_pointer_cursor	设置鼠标指针的图片名。
widget_set_animation	设置控件的动画参数(仅用于在UI文件使用)。
widget_create_animator	创建动画。
widget_start_animator	播放动画。
widget_set_animator_time_scale	设置动画的时间倍率，<0: 时间倒退，<1: 时间变慢，>1 时间变快。
widget_pause_animator	暂停动画。
widget_find_animator	查找指定名称的动画。
widget_stop_animator	停止动画(控件的相应属性回归原位)。
widget_destroy_animator	销毁动画。
widget_set_enable	设置控件的可用性。
widget_set_feedback	设置控件是否启用反馈。
widget_set_auto_adjust_size	设置控件是否根据子控件和文本自动调整控件自身大小。
widget_set_floating	设置控件的floating标志。
widget_set_focused	设置控件是否获得焦点。
widget_set_focusable	设置控件是否可获得焦点。
widget_set_state	设置控件的状态。
widget_set_opacity	设置控件的不透明度。
widget_set_dirty_rect_tolerance	设置控件脏矩形超出控件本身大小的最大范围(一般不用指定)。
widget_destroy_children	销毁全部子控件。
widget_add_child	加入一个子控件。
widget_remove_child	移出指定的子控件(并不销毁)。
widget_insert_child	插入子控件到指定的位置。
widget_restack	调整控件在父控件中的位置序数。
widget_child	查找指定名称的子控件(同widget_lookup(widget, name, FALSE))。
widget_lookup	查找指定名称的子控件(返回第一个)。
widget_lookup_by_type	查找指定类型的子控件(返回第一个)。
widget_set_visible	设置控件的可见性。
widget_set_visible_only	设置控件的可见性(不触发repaint和relayout)。
widget_set_sensitive	设置控件是否接受用户事件。
widget_on	注册指定事件的处理函数。
widget_on_with_tag	注册指定tag的事件处理函数。
widget_off	注销指定事件的处理函数。
widget_child_on	为指定名称的子控件注册指定事件的处理函数。
widget_off_by_func	注销指定函数的事件处理函数。
widget_off_by_ctx	注销指定ctx的事件处理函数。
widget_off_by_tag	注销指定tag的事件处理函数。
widget_invalidate	请求重绘指定的区域
widget_invalidate_force	请求强制重绘控件。
widget_paint	绘制控件到一个canvas上。
widget_draw_text_in_rect	在canvas绘制一行文本。
widget_dispatch	分发一个事件。
widget_dispatch_async	异步分发一个事件。
widget_dispatch_simple_event	分发一个简单事件。
widget_dispatch_model_event	分发model事件(分发到各个窗口)。
widget_dispatch_recursive	分发一个事件控件本身及所有子控件。
widget_get_prop	获取控件指定属性的值。
widget_get_prop_default_value	获取控件指定属性的缺省值(在持久化控件时，无需保存缺省值)。
widget_set_prop	设置控件指定属性的值。
widget_set_props	设置多个参数。
widget_set_prop_str	设置字符串格式的属性。
widget_get_prop_str	获取字符串格式的属性。
widget_set_prop_pointer	设置指针格式的属性。
widget_set_prop_pointer_ex	设置指针格式的属性。
widget_get_prop_pointer	获取指针格式的属性。
widget_set_prop_float	设置浮点数格式的属性。
widget_get_prop_float	获取浮点数格式的属性。
widget_set_prop_int	设置整数格式的属性。
widget_get_prop_int	获取整数格式的属性。
widget_set_prop_bool	设置布尔格式的属性。
widget_get_prop_bool	获取布尔格式的属性。
widget_is_window_opened	判断当前控件所在的窗口是否已经打开。
widget_is_window_created	判断窗口及子控件创建或加载是否完成。
widget_is_parent_of	判断当前控件是否是指定控件的父控件(包括非直系)。
widget_is_direct_parent_of	判断当前控件是否是指定控件的直系父控件。
widget_is_window	判断当前控件是否是窗口。
widget_is_system_bar	检查控件是否是system bar类型。
widget_is_normal_window	检查控件是否是普通窗口类型。
widget_is_fullscreen_window	检查控件是否是全屏窗口。
widget_is_dialog	检查控件是否是对话框类型。
widget_is_popup	检查控件是否是弹出窗口类型。
widget_is_overlay	检查控件是否是overlay窗口类型。
widget_is_always_on_top	检查控件是否总在最上层。
widget_is_opened_dialog	检查控件弹出对话框控件是否已经打开了（而非挂起状态）。
widget_is_opened_popup	检查控件弹出窗口控件是否已经打开了（而非挂起状态）。
widget_is_keyboard	判断当前控件是否是keyboard。
widget_is_designing_window	判断当前控件是否是设计窗口。
widget_is_window_manager	判断当前控件是否是窗口管理器。
widget_grab	让指定子控件抓住事件。
widget_ungrab	让指定子控件放弃抓住事件。
widget_foreach	遍历当前控件及子控件。
widget_get_window	获取当前控件所在的窗口。
widget_get_window_manager	获取当前的窗口管理器。
widget_get_type	获取当前控件的类型名称。
widget_clone	clone。
widget_equal	判断两个widget是否相同。
widget_add_timer	创建定时器。
widget_remove_timer	删除指定的timer。
widget_add_idle	创建idle。
widget_remove_idle	删除指定的idle。
widget_load_image	加载图片。
widget_unload_image	卸载图片。
widget_load_asset	加载资源。
widget_load_asset_ex	加载资源。
widget_unload_asset	卸载资源。
widget_cast	转换为widget对象(供脚本语言使用)。
widget_destroy	从父控件中移除控件，并调用unref函数销毁控件。
widget_destroy_async	从父控件中移除控件，并调用unref函数销毁控件。
widget_ref	增加控件的引用计数。
widget_unref	减少控件的引用计数。引用计数为0时销毁控件。
widget_paint_helper	帮助子控件实现自己的绘制函数。
widget_draw_background	根据控件的style绘制背景矩形。
widget_stroke_border_rect	根据控件的style绘制边框矩形。
widget_fill_bg_rect	根据控件的style绘制背景矩形。
widget_fill_fg_rect	根据控件的style绘制前景矩形。
widget_prepare_text_style	从widget的style中取出字体名称、大小和颜色数据，设置到canvas中。
widget_prepare_text_style_ex	从widget的style中取出字体名称、大小和颜色数据，设置到canvas中。
widget_measure_text	计算文本的宽度。
widget_dispatch_event_to_target_recursive	递归分发事件到targe控件。
widget_is_point_in	判断一个点是否在控件内。
widget_dispatch_to_target	递归的分发一个事件到所有target子控件。
widget_dispatch_to_key_target	递归的分发一个事件到所有key_target子控件。
widget_find_target	查找x/y坐标对应的子控件。
widget_re_translate_text	语言改变后，重新翻译控件上的文本(包括子控件)。
widget_init	初始化控件。仅在子类控件构造函数中使用。
widget_create	创建控件。仅在子类控件构造函数中使用。
widget_get_style_type	获取 widget 对应风格类型
widget_update_style	让控件根据自己当前状态更新style。
widget_update_style_recursive	让控件及子控件根据自己当前状态更新style。
widget_set_as_key_target	递归的把父控件的key_target设置为自己。
widget_focus_next	把焦点移动下一个控件。
widget_focus_prev	把焦点移动前一个控件。
widget_get_state_for_style	把控件的状态转成获取style选要的状态，一般只在子类中使用。
widget_layout	布局当前控件及子控件。
widget_layout_children	layout子控件。
widget_set_self_layout	设置控件自己的布局参数。
widget_set_children_layout	设置子控件的布局参数。
widget_set_self_layout_params	设置控件自己的布局(缺省布局器)参数(过时，请用widget_set_self_layout)。
widget_set_style_int	设置整数类型的style。
widget_set_style_str	设置字符串类型的style。
widget_set_style_color	设置颜色类型的style。
widget_take_snapshot	创建一个bitmap对象，将控件绘制到bitmap上，并返回bitmap对象。
widget_take_snapshot_rect	创建一个bitmap对象，将控件绘制到bitmap上并且可以设置该控件的截屏区域，返回bitmap对象。
widget_get_canvas	获取canvas对象。
widget_reset_canvas	重置canvas对象。for designer only,调用者需要unload全部图片
widget_on_paint_background	绘制背景。
widget_on_paint_self	绘制自身。
widget_on_paint_children	绘制子控件。
widget_on_paint_border	绘制边框。
widget_is_instance_of	检查控件是否是指定的类型。
widget_set_need_relayout_children	设置控件需要relayout标识。
widget_set_need_relayout	设置控件需要relayout标识。
widget_ensure_visible_in_viewport	使控件滚动到可见区域。
widget_focus_first	置焦点于第一个控件。
widget_get_locale_info	获取locale_info对象。
widget_get_image_manager	获取image_manager对象。
widget_get_assets_manager	获取assets_manager对象。
widget_get_font_manager	获取font_manager对象。
widget_update_pointer_cursor	更新鼠标指针。
widget_begin_wait_pointer_cursor	开始等待鼠标指针。
widget_end_wait_pointer_cursor	结束等待鼠标指针。
widget_set_style	设置widget私有样式。
widget_get_style	获取widget样式。
widget_get_content_area	获取widget去掉margin之外的区域。
widget_calc_icon_text_rect	计算icon text的位置。
widget_auto_scale_children	根据缩放子控件的位置和大小。
widget_set_need_update_style	设置需要更新Style。
widget_set_need_update_style_recursive	让控件及子控件设置需要更新Style。
widget_on_pointer_down_children	处理子控件的pointer down事件。
widget_on_pointer_move_children	处理子控件的pointer move事件。
widget_on_pointer_up_children	处理子控件的pointer up事件。
widget_is_change_focus_key	是否是切换焦点的键。
widget_add_child_default	加入一个子控件默认实现(供子类调用)。
widget_on_keydown	处理key down事件。
widget_on_keyup	处理key up事件。
widget_get_widget_vtable	获取 widget 虚表。
widget_to_xml	将widget转换成xml。

4.2.2 属性

1. 属性列表

widget提供了下面属性，widget的属性均适用于widget的子类控件，详见下表：

属性名称	类型	说明
x	xy_t	x坐标(相对于父控件的x坐标)。
y	xy_t	y坐标(相对于父控件的y坐标)。
w	wh_t	宽度。
h	wh_t	高度。
name	char*	控件名字。
pointer_cursor	char*	鼠标光标图片名称。
tr_text	char*	保存用于翻译的字符串。
style	char*	style的名称。
animation	char*	动画参数。请参考控件动画 (opens new window)
enable	bool_t	启用/禁用状态。
feedback	bool_t	是否启用按键音、触屏音和震动等反馈。
visible	bool_t	是否可见。
sensitive	bool_t	是否接受用户事件。
focusable	bool_t	是否支持焦点停留。
with_focus_state	bool_t	是否支持焦点状态。
auto_adjust_size	bool_t	是否根据子控件和文本自动调整控件自身大小。
focused	bool_t	是否得到焦点。
auto_created	bool_t	是否由父控件自动创建。
dirty	bool_t	标识控件是否需要重绘。
floating	bool_t	标识控件是否启用浮动布局，不受父控件的children_layout的控制。
need_update_style	bool_t	标识控件是否需要update style。
ref_count	int32_t	引用计数，计数为0时销毁。
initializing	bool_t	标识控件正在初始化。
loading	bool_t	标识控件正在加载。
destroying	bool_t	标识控件正在被销毁。
state	char*	控件的状态(取值参考widget_state_t)。
opacity	uint8_t	不透明度(0-255)，0完全透明，255完全不透明。
dirty_rect_tolerance	uint16_t	脏矩形超出控件本身大小的最大范围(一般不用指定)。
text	wstr_t	文本。用途视具体情况而定。
parent	widget_t*	父控件
target	widget_t*	接收事件的子控件。
grab_widget	widget_t*	grab事件的子控件。
grab_widget_count	int32_t	有时子控件和控件自己都会grab widget，所需要grab的计数。
key_target	widget_t*	接收按键事件的子控件。
children	darray_t*	全部子控件。
emitter	emitter_t*	事件发射器。
astyle	style_t*	Style对象。
children_layout	children_layouter_t*	子控件布局器。请参考控件布局参数 (opens new window)
self_layout	self_layouter_t*	控件布局器。请参考控件布局参数 (opens new window)
custom_props	tk_object_t*	自定义属性。
vt	const widget_vtable_t*	虚函数表。

2. 设置属性

上个小节表格中的属性，可以在编写UI界面的XML文件通过控件的属性指定，比如，设置label控件的name、x、y等属性，代码如下：

<window name="home_page">
    <label name="label" x="79" y="192" w="160" h="28" text="Label"/>
</window>

因为label控件是widget的子类控件，所以widget的属性均适用于label控件。

3. 获取属性

在以上代码中，设置了label控件的x属性，如果想要获取x属性对应的属性值"79"。可以通过widget_lookup()函数获取label控件的指针对象，然后通过箭头运算符（->）获取该属性值，代码如下：

widget_t* label = widget_lookup(win, "label", TRUE);
int32_t x = label->x;

4. 使用widget_get_prop和widget_set_prop函数获取或设置控件属性

除了上面提到的可以通过箭头运算符获取控件的属性外，AWTK还提供widget_get_prop和widget_set_prop函数用于获取和设置控件的属性，这两个函数的函数原型如下：

ret_t widget_get_prop(widget_t* widget, const char* name, value_t* v);
ret_t widget_set_prop(widget_t* widget, const char* name, const value_t* v);

其中，上面两个函数中name的取值详见下表，由于prop属性很多该表没有列出全部，具体请看AWTK_API手册根据关键字"widget_prop_t"查找，示例请看下文章节。

名称	说明
WIDGET_PROP_X	X坐标
WIDGET_PROP_Y	Y坐标
WIDGET_PROP_W	宽度
WIDGET_PROP_H	高度
WIDGET_PROP_CANVAS	Canvas
WIDGET_PROP_NATIVE_WINDOW	Native Window
WIDGET_PROP_HIGHLIGHT	dialog highlight
WIDGET_PROP_BAR_SIZE	slider中的bar的的宽度或高度
WIDGET_PROP_OPACITY	不透明度
WIDGET_PROP_MIN_W	最小宽度
WIDGET_PROP_MAX_W	最大宽度
WIDGET_PROP_CHILDREN_LAYOUT	子控件布局参数
WIDGET_PROP_LAYOUT	子控件布局参数(过时)
WIDGET_PROP_SELF_LAYOUT	控件布局参数
WIDGET_PROP_LAYOUT_W	layout宽度
WIDGET_PROP_LAYOUT_H	layout高度
...	...

4.2.3 事件

widget还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_WILL_MOVE	event_t	控件移动前触发。
EVT_MOVE	event_t	控件移动后触发。
EVT_WILL_RESIZE	event_t	控件调整大小前触发。
EVT_RESIZE	event_t	控件调整大小后触发。
EVT_WILL_MOVE_RESIZE	event_t	控件移动并调整大小前触发。
EVT_MOVE_RESIZE	event_t	控件移动并调整大小后触发。
EVT_THEME_CHANGED	event_t	主题变化事件。
EVT_FOCUS	event_t	控件得到焦点时触发。
EVT_BLUR	event_t	控件失去焦点时触发。
EVT_WIDGET_ADD_CHILD	event_t	控件加载新的子控件。
EVT_WIDGET_REMOVE_CHILD	event_t	控件移除子控件。
EVT_WIDGET_WILL_RESTACK_CHILD	event_t	控件即将调整子控件位置序数。
EVT_WIDGET_RESTACK_CHILD	event_t	控件调整子控件位置序数。
EVT_PROP_WILL_CHANGE	prop_change_event_t	控件属性改变前触发(通过set_prop设置属性，才会触发)。
EVT_PROP_CHANGED	prop_change_event_t	控件属性改变后触发(通过set_prop设置属性，才会触发)。
EVT_PAINT	paint_event_t	控件绘制时触发。
EVT_BEFORE_PAINT	paint_event_t	控件绘制前触发。
EVT_AFTER_PAINT	paint_event_t	控件绘制完成时触发。
EVT_PAINT_DONE	paint_event_t	控件绘制完成时(canvas状态已经恢复)触发。
EVT_WHEEL_BEFORE_CHILDREN	wheel_event_t	鼠标滚轮事件，在子控件处理之前触发。
EVT_WHEEL	wheel_event_t	鼠标滚轮事件。
EVT_POINTER_LEAVE	pointer_event_t	鼠标指针离开控件时触发。
EVT_POINTER_ENTER	pointer_event_t	鼠标指针进入控件时触发。
EVT_KEY_DOWN_BEFORE_CHILDREN	key_event_t	键按下事件，在子控件处理之前触发。
EVT_KEY_DOWN	key_event_t	键按下事件。
EVT_KEY_LONG_PRESS	key_event_t	键长按事件。
EVT_KEY_UP_BEFORE_CHILDREN	key_event_t	键释放事件，在子控件处理之前触发。
EVT_KEY_UP	key_event_t	键释放事件。
EVT_POINTER_DOWN_BEFORE_CHILDREN	pointer_event_t	指针设备按下事件，在子控件处理之前触发。
EVT_POINTER_DOWN	pointer_event_t	指针设备按下事件。
EVT_POINTER_DOWN_ABORT	pointer_event_t	取消指针设备按下事件。
EVT_POINTER_MOVE	pointer_event_t	指针设备移动事件。
EVT_POINTER_MOVE_BEFORE_CHILDREN	pointer_event_t	指针设备移动事件，在子控件处理之前触发。
EVT_POINTER_UP	pointer_event_t	指针设备释放事件。
EVT_POINTER_UP_BEFORE_CHILDREN	pointer_event_t	指针设备释放事件，在子控件处理之前触发。
EVT_DESTROY	event_t	控件销毁时触发。

4.2.4 示例

上面介绍了有关widget的函数、属性以及事件等，下面以一些简单的示例来说明一下，如何调用这些函数。

1. 查找控件widget_lookup

例如，要查找awtk/bin/demoui.exe中下图所示的"n/a"文本框，步骤如下：

首先，需要在XML中设置文本框的name属性，详见以下代码：

<!-- awtk\demos\assets\default\raw\ui\memtest.xml -->
<window anim_hint="htranslate" x="0" y="0" w="320" h="480">
    <button name="memtest" x="center" y="bottom:100" w="50%" h="30" text="Start"/>
    <button name="close" x="center" y="bottom:50" w="50%" h="30" text="Close"/>
    <label name="cost" x="center" y="10" w="100%" h="30" text="n/a"/>
    <label name="memset" x="center" y="50" w="100%" h="30" text="n/a"/>
    <label name="memcpy" x="center" y="90" w="100%" h="30" text="n/a"/>
</window>

图4.1 widget_lookup

然后，在C代码中调用widget_lookup函数查找该控件，代码如下：

/* awtk/demos/demo_ui_app.c */
static ret_t on_mem_test(void* ctx, event_t* e) {
  ...
  widget_t* win = WIDGET(ctx);
  widget_t* label_cost = widget_lookup(win, "cost", TRUE);
  ...
  return RET_OK;
}

2. 设置文本内容widget_set_text_utf8

例如，要设置上一小节示例图中"n/a"文本框的内容，通过widget_lookup查找到控件后，再调用widget_set_text_utf8设置文本框的内容，代码如下：

/* awtk/demos/demo_ui_app.c */
static ret_t on_mem_test(void* ctx, event_t* e) {
  char text[32];
  uint32_t size = 100 * 1024;
  uint32_t memset_speed = 0;
  uint32_t memcpy_speed = 0;
  widget_t* win = WIDGET(ctx);
  widget_t* label_cost = widget_lookup(win, "cost", TRUE);

  void* buff = TKMEM_ALLOC(size);
  uint32_t cost = tk_mem_speed_test(buff, size, &memcpy_speed, &memset_speed);
  TKMEM_FREE(buff);

  tk_snprintf(text, sizeof(text), "%ums", cost);
  widget_set_text_utf8(label_cost, text);
  ...
  return RET_OK;
}

3. 获取控件指定属性的值widget_get_prop

在4.2.1章节的表格中有多个以widget_get_prop开头的函数，其中widget_get_prop_xx是对widget_get_prop进一步封装，如：widget_get_prop_int用于获取整数格式的属性；而widget_get_prop_bool则用于获取布尔格式的属性。至于使用widget_get_prop_int还是widget_get_prop_bool要看获取属性值类型。

例如，要获取label控件的宽和高，因为宽和高是int类型，所以使用widget_get_prop_int，代码如下：

widget_t* label = widget_lookup(win, "label", TRUE);
int32_t w = widget_get_prop_int(label, WIDGET_PROP_W, 0);
int32_t h = widget_get_prop_int(label, WIDGET_PROP_H, 0);

4. 更新样式widget_use_style

例如，要更新label控件的样式，可以使用widget_use_style函数，代码如下：

widget_t* label = widget_lookup(win, "label", TRUE);
widget_use_style(label, "green"); 

上述代码中的"green"为样式名称，该样式的代码如下，当然也可以设置为其他样式：

<!-- awtk/demos/assets/default/raw/styles/default.xml -->
<label>
  <style name="default">
    <normal text_color="black" />
  </style>
  <style name="green">
    <normal text_color="green" />
  </style>
  ...
</label>

4.2.5 控件的可见性

在AWTK中，控件的visible属性决定了控件是否可见，默认为可见的。例如，设置button按钮控件不可见，代码如下：

<window name="home_page">
  <button name="button" x="33" y="26" w="100" h="36" visible="false" text="Button"/>
</window>

在C代码中，可以通过widget_set_visible函数设置控件是否可见。

需要注意的是，控件是否可见并不影响其是否接收用户事件（比如：鼠标事件）。假设不可见的button控件注册了EVT_CLICK点击事件，则该事件的回调函数还是会执行。

在AWTK中，窗口内的控件是否接收用户事件由控件的enable（是否使能）和sensitive（是否接受用户事件）属性决定。只要enable和sensitive属性有一个值为false，就不会接收用户事件。

因此，如果不想button控件的事件回调函数被执行，可以设置button控件的enable或者sensitive属性为false，代码如下：

<window name="home_page">
  <button name="button" x="33" y="26" w="100" h="36" visible="false" text="Button" enable="false"/>
</window>

也可以在C代码的程序中调用widget_set_enable或widget_set_sensitive函数完成。

设置enable和sensitive属性的差异主要表现在外观上：设置enable属性为false，则使用disable状态的样式；而设置sensitive属性，不管其值是true还是false，都使用normal状态的样式。

4.3 window_manager

4.3.1 窗口管理器

window_manager_t继承widget_t，负责对AWTK应用程序的各个窗口进行集中管理。例如，通过window_manager_t类提供的函数可以回到指定的窗口、获取最上面的窗口、获取鼠标指针的坐标、设置鼠标指针等，以上功能请参考下文示例。

4.3.2 函数

window_manager提供的函数详见下表，具体请查看AWTK_API手册，这里不累赘了。在下表中，函数的第一个形参传递的值通常是window_manager()。

函数名称	说明
window_manager	获取全局window_manager对象
window_manager_cast	转换为window_manager对象(供脚本语言使用)。
window_manager_set	设置缺省的窗口管理器。
window_manager_get_top_main_window	获取最上面的主窗口。
window_manager_get_top_window	获取最上面的窗口。
window_manager_get_prev_window	获取前一个的窗口。
window_manager_get_pointer_x	获取指针当前的X坐标。
window_manager_get_pointer_y	获取指针当前的Y坐标。
window_manager_get_pointer_pressed	获取指针当前是否按下。
window_manager_is_animating	获取当前窗口动画是否正在播放。
window_manager_open_window	打开窗口。
window_manager_close_window_force	强制立即关闭窗口。
window_manager_paint	绘制。
window_manager_dispatch_input_event	分发输入事件。
window_manager_set_show_fps	设置是否显示FPS。
window_manager_set_max_fps	限制最大帧率。
window_manager_set_ignore_input_events	设置是否忽略用户输入事件。
window_manager_set_screen_saver_time	设置屏保时间。
window_manager_set_cursor	设置鼠标指针。
window_manager_back	请求关闭顶层窗口。
window_manager_back_to_home	回到主窗口，关闭之上的全部窗口。
window_manager_back_to	回到指定的窗口，关闭之上的全部窗口。
window_manager_switch_to	切换到指定窗口。
window_manager_dispatch_native_window_event	处理native window事件。
window_manager_begin_wait_pointer_cursor	开始等待鼠标指针。
window_manager_end_wait_pointer_cursor	结束等待鼠标指针。
window_manager_resize	调整原生窗口的大小。
window_manager_close_all	关闭全部窗口。
window_manager_destroy	销毁window_manager。
window_manager_init	初始化window_manager。

4.3.3 属性

window_manager还提供了下面属性，详见下表：

属性名称	类型	说明
global_emitter	emitter_t*	全局事情分发器。

4.3.4 事件

window_manager还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_TOP_WINDOW_CHANGED	window_event_t	顶层窗口改变的事件。
EVT_SCREEN_SAVER	window_event_t	在指定的时间内，没有用户输入事件，由窗口管理器触发。
EVT_ORIENTATION_CHANGED	event_t	屏幕旋转事件。
EVT_SYSTEM	system_event_t	SDL系统事件。

4.3.5 示例

1. 回到指定的窗口window_manager_back_to

如果要回到指定的窗口，并关闭之上的全部窗口，比如main窗口，代码如下：

window_manager_back_to(window_manager(), "main");

2. 获取最上面的窗口window_manager_get_top_window

如果要获取最上面的窗口，代码如下：

widget_t* top_win = window_manager_get_top_window(window_manager());

3. 获取指针当前的X坐标window_manager_get_pointer_x

如果要获取指针当前的X坐标，代码如下：

int32_t x = window_manager_get_pointer_x(window_manager());

4. 设置鼠标指针window_manager_set_cursor

请参考 HowTo 中的如何设置鼠标指针 (opens new window)。

4.4 窗口

常用的窗口详见下表：

窗口	说明
window_base	窗口基类（一般不直接使用）
dialog	对话框
popup	弹出窗口（一般不直接使用）
window	普通窗口
system_bar	系统状态窗口
calibration_win	电阻屏校准窗口
overlay	悬浮窗口

4.4.1 window_base

window_base_t继承widget_t，是所有窗口的基类。window_base_t是一个抽象类，不能进行实例化。请在应用程序中使用中具体的窗口类，例如window_t、dialog_t、system_bar_t、calibration_win_t、overlay_t、popup_t。

1. 函数

window_base提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
window_base_on_destroy	窗口on_destroy函数的缺省实现。
window_base_on_event	窗口on_event函数的缺省实现。
window_base_invalidate	窗口on_invalidate函数的缺省实现。
window_base_on_paint_begin	窗口on_paint_begin函数的缺省实现。
window_base_on_paint_end	窗口on_paint_end函数的缺省实现。
window_base_on_paint_self	窗口on_paint_self函数的缺省实现。
window_base_get_prop	窗口get_prop函数的缺省实现。
window_base_set_prop	窗口set_prop函数的缺省实现。
window_base_create	创建window base对象。
window_base_cast	转换为window_base对象(供脚本语言使用)。
window_base_set_need_relayout	设置是否需要relayout
window_base_on_copy	默认拷贝函数。
window_base_auto_scale_children	根据参数自动缩放子控件。
window_base_get_widget_vtable	获取 window_base 虚表。

2. 属性

window_base还提供了下面属性，详见下表：

属性名称	类型	说明
theme	char*	窗体样式资源的名称。
design_w	uint16_t	设计时宽度。
design_h	uint16_t	设计时高度。
auto_scale_children_x	bool_t	窗口大小与设计时大小不同时，是否自动调整子控件的x坐标。
auto_scale_children_y	bool_t	窗口大小与设计时大小不同时，是否自动调整子控件的y坐标。
auto_scale_children_w	bool_t	窗口大小与设计时大小不同时，是否自动调整子控件的宽度。
auto_scale_children_h	bool_t	窗口大小与设计时大小不同时，是否自动调整子控件的高度。
disable_anim	bool_t	禁用窗口动画。
closable	window_closable_t	收到EVT_REQUEST_CLOSE_WINDOW是否自动关闭窗口。
open_anim_hint	char*	打开窗口动画的名称。
close_anim_hint	char*	关闭窗口动画的名称。
stage	window_stage_t	窗口当前处于的状态。
theme_obj	theme_t*	窗口的常量窗体样式数据。
image_manager	image_manager_t*	获取图片管理器对象。
font_manager	font_manager_t*	获取字体管理器对象。
assets_manager	assets_manager_t*	获取资源管理器对象。
locale_info	locale_info_t*	获取多国语言字符串管理器对象。
move_focus_prev_key	char*	向前移动焦点的键值。
move_focus_next_key	char*	向后移动焦点的键值。
move_focus_up_key	char*	向上移动焦点的键值。
move_focus_down_key	char*	向下移动焦点的键值。
move_focus_left_key	char*	向左移动焦点的键值。
move_focus_right_key	char*	向右移动焦点的键值。
applet_name	char*	小应用程序(applet)的名称。
single_instance	bool_t	单例。如果窗口存在，先关闭再打开。
strongly_focus	bool_t	点击非focusable控件时，是否让当前焦点控件失去焦点。比如点击窗口空白区域，是否让编辑器失去焦点。

3. 样式

window_base可设置的样式在所有窗口中均可设置，样式列表详见下表：

样式属性	说明
bg_color	背景颜色
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

4. 状态

window_base在样式文件中可以设置的状态同样适用于所有窗口，状态列表详见下表：

状态	说明
normal	正常状态
disable	禁用状态
focused	聚焦状态

5. 事件

window_base提供的事件在所有窗口中均可使用，事件列表详见下表，窗口事件分发的时间点在窗口生命周期中的位置如下图所示。

事件名称	类型	说明
EVT_WINDOW_WILL_OPEN	event_t	窗口即将打开事件。 如果有窗口动画，在窗口动画开始前触发。如果没有窗口动画，在窗口被加载后的下一次循环中触发。
EVT_WINDOW_OPEN	event_t	窗口打开事件。 如果有窗口动画，在窗口动画完成时触发。如果没有窗口动画，在窗口被加载后的下一次循环中触发。
EVT_WINDOW_TO_BACKGROUND	event_t	窗口被切换到后台事件。 打开新窗口时，当前窗口被切换到后台时，对当前窗口触发本事件。
EVT_WINDOW_TO_FOREGROUND	event_t	窗口被切换到前台事件。 关闭当前窗口时，前一个窗口被切换到前台时，对前一个窗口触发本事件。
EVT_WINDOW_CLOSE	event_t	窗口关闭事件。
EVT_WINDOW_LOAD	event_t	窗口加载完成事件。
EVT_REQUEST_CLOSE_WINDOW	event_t	请求关闭窗口的事件。
EVT_LOCALE_CHANGED	event_t	locale改变的事件。

图4.2 常用窗口生命生命周期

4.4.2 window

缺省的应用程序窗口，占用除system_bar_t之外的整个区域。window_t是window_base_t的子类控件，window_base_t的函数均适用于window_t控件。

1. 函数

window提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
window_create	创建window对象
window_create_default	以缺省的方式创建window对象。
window_set_fullscreen	设置为全屏窗口。
window_set_auto_scale_children	当设计分辨率和实际分辨率不一致时，自动调整子控件的位置和大小。
window_open	从资源文件中加载并创建window_base对象。本函数在ui_loader/ui_builder_default里实现。
window_open_and_close	从资源文件中加载并创建window对象。本函数在ui_loader/ui_builder_default里实现。
window_close	关闭窗口。
window_close_force	立即无条件关闭窗口(无动画)。
window_cast	转换为window对象(供脚本语言使用)。
window_get_widget_vtable	获取 window 虚表。

2. 属性

window还提供了下面属性，详见下表：

属性名称	类型	说明
fullscreen	bool_t	是否全屏。

3. 示例

(1) 创建窗口

• 在xml中，使用"window"标签创建窗口。无需指定坐标和大小，可以指定窗体样式和动画名称，代码如下：

<!-- awtk/demos/assets/default/raw/ui/main.xml -->
<window closable="no" text="Desktop" anim_hint="htranslate">
	...
</window>

• 在C代码中，使用函数window_create创建窗口，无需指定父控件、坐标和大小，使用0即可，代码如下：

/* awtk/demos/demo1_app.c */
ret_t application_init() {
  ...
  widget_t* win = window_create(NULL, 0, 0, 0, 0);
  ...
}

(2) 打开窗口window_open

通常，在assets/default/raw/ui目录下的XML文件中使用"window"标签创建好窗口，然后调用window_open函数打开窗口，需要传递给该函数的字符串为XML的文件名，代码如下：

/* awtk-examples/HelloWorld.Xml-Demo/src/window_main.c */
ret_t application_init() {
  widget_t* win = window_open("main");
  if (win) {
    init_children_widget(win);
  }
  return RET_OK;
}

(3) 关闭窗口window_close

例如，点击下图中右侧的"close"按钮关闭当前窗口，需要调用window_close，代码如下：

图4.3 关闭窗口

/* awtk/demos/demo_ui_app.c */
static ret_t on_close(void* ctx, event_t* e) {
  widget_t* win = WIDGET(ctx);
  (void)e;
  return window_close(win);
}

static ret_t install_one(void* ctx, const void* iter) {
  widget_t* widget = WIDGET(iter);
  widget_t* win = widget_get_window(widget);

  if (widget->name != NULL) {
    const char* name = widget->name;
    if (strstr(name, "open:") != NULL) {
      widget_on(widget, EVT_CLICK, on_open_window, (void*)(name + 5));
      widget_on(widget, EVT_LONG_PRESS, on_open_window, (void*)(name + 5));
    } else if (tk_str_eq(name, "close")) {
      widget_on(widget, EVT_CLICK, on_close, win);
    }
	...
  return RET_OK;
}

4.4.3 dialog

对话框是一种特殊的窗口，大小和位置可以自由设置。AWTK中的对话框可以是模态的，也可以是非模态的。

对话框通常由对话框标题和对话框客户区两部分组成详见下图。dialog是window_base_t的子类控件，window_base_t的函数均适用于dialog_t控件。

图4.4 对话框的组成

由于浏览器中无法实现主循环嵌套，因此无法实现模态对话框。如果希望自己写的AWTK应用程序可以在浏览器（包括各种小程序）中运行或演示，请避免使用模态对话框。

1. 函数

dialog提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
dialog_create	创建dialog对象。
dialog_create_simple	创建dialog对象，同时创建title/client。
dialog_cast	转换dialog对象(供脚本语言使用)。
dialog_get_title	获取title控件。
dialog_get_client	获取client控件。
dialog_open	从资源文件中加载并创建Dialog对象。
dialog_set_title	设置对话框的标题文本。
dialog_modal	模态显示对话框。
dialog_quit	退出模态显示，关闭对话框。
dialog_is_quited	检查对话框是否已经退出模态。
dialog_is_modal	检查对话框是否为模态对话框。
dialog_toast	显示『短暂提示信息』对话框。
dialog_info	显示『提示信息』对话框。
dialog_warn	显示『警告』对话框。
dialog_confirm	显示『确认』对话框。
dialog_create_with_ok_cancel	创建一个带有OK/Cancel按钮的对话框。
dialog_simple_show	根据所选标题，内容与主题等创建一个对话框。
dialog_get_widget_vtable	获取 dialog 虚表。

2. 属性

dialog还提供了下面属性，详见下表：

属性名称	类型	说明
highlight	char*	对话框高亮策略。

3. 示例

(1) 创建对话框

• 在xml中，使用"dialog"标签创建对话框，代码如下：

<dialog theme="dialog" style="custom" highlight="default(alpha=40)" 
  x="c" y="m" w="80%" h="160">
  <dialog_title style="custom" x="0" y="0" w="100%" h="30" text="Hello AWTK" />
  <dialog_client style="custom" x="0" y="bottom" w="100%" h="-30">
    <label x="center" y="middle:-20" w="200" h="30" text="AWTK is cool!"/>
    <button style="green_btn" name="quit" x="10" y="bottom:10" w="40%" h="30" text="确定"/>
    <button style="red_btn" name="quit" x="right:10" y="bottom:10" w="40%" h="30" text="取消"/>
  </dialog_client>
</dialog>

• 在C代码中，使用函数dialog_create_simple创建对话框，代码如下：

/* awtk/demos/demo1_app.c */
static ret_t on_show_dialog(void* ctx, event_t* e) {
  ...
  widget_t* win = dialog_create_simple(NULL, 0, 0, 240, 160);
  dialog_t* dialog = DIALOG(win);

  code = dialog_modal(win);
  ...
}

创建之后，再创建子控件，最后调用dialog_modal显示对话框。对话框关闭之后dialog_modal才会返回。

另外，关于非模态和模态对话框在使用上的区别请看：

• 非模态对话框 (opens new window)
• 模态对话框 (opens new window)

(2) 打开对话框dialog_open

通常，在assets/default/raw/ui目录下的XML文件中使用"dialog"标签创建好窗口，然后调用dialog_open函数打开窗口，需要传递给该函数的字符串为XML的文件名，打开之后还要调用dialog_modal模态显示对话框，代码如下：

/* awtk-examples/MusicPlayer-Demo/src/dialog_advanced.c */
ret_t open_play_list_window(widget_t* s_parent) {
  widget_t* dialog = dialog_open("play_list");

  if (dialog) {
    widget_on(dialog, EVT_POINTER_DOWN, on_dialog_state, dialog);
    m_win = s_parent;
    init_children_widget(dialog);
    return dialog_modal(dialog);
  }

  return RET_FAIL;

}

(3) 关闭对话框dialog_quit

要关闭对话框只需要调用dialog_quit就可以了，代码如下：

/* awtk-examples/MusicPlayer-Demo/src/dialog_advanced.c */
static ret_t on_close(void* ctx, event_t* e) {
  widget_t* dialog = (widget_t*)ctx;
  (void)e;

  return dialog_quit(dialog, RET_QUIT);
}

static ret_t init_widget(void* ctx, const void* iter) {
  widget_t* widget = WIDGET(iter);
  (void)ctx;
  if (widget->name != NULL) {
    const char* name = widget->name;
    if (tk_str_eq(name, "close")) {
      widget_t* dialog = widget_get_window(widget);
      widget_on(widget, EVT_CLICK, on_close, dialog);
    } 
	...
  }
  return RET_OK;
}

4.4.4 system_bar

system_bar窗口是一种特殊的窗口，独占LCD顶部区域，用来显示当前窗口的标题和关闭按钮等内容。system_bar窗口需要在打开第一个应用程序窗口之前打开。system_bar_t是window_base_t的子类控件，window_base_t的函数均适用于system_bar_t控件。system_bar对两个子控件会做特殊处理：

• 名为"title"的label控件，自动显示当前主窗口的name或text
• 名为"close"的button控件，向当前主窗口发送EVT_REQUEST_CLOSE_WINDOW消息，如果点击该控件的话

1. 函数

system_bar提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
system_bar_create	创建system_bar对象。
system_bar_cast	转换为system_bar对象(供脚本语言使用)。
system_bar_get_widget_vtable	获取 system_bar 虚表。

2. 示例

• 在xml中，使用"system_bar"标签创建system_bar窗口，代码如下：

<!-- awtk/demos/assets/default/raw/ui/system_bar.xml -->
<system_bar h="30">
  <column x="0" y="0" w="-40" h="100%">
    <label style="title" x="10" y="m" w="55%" h="100%" name="title"/>
    <digit_clock style="time" x="r" y="m" w="40%" h="100%" format="hh:mm"/>
  </column>
  <button style="close" x="r:5" y="m" w="26" h="26" name="close" text="x"/>
</system_bar>

• 在C代码中，使用函数system_bar_create创建system_bar窗口，代码如下：

widget_t* win = system_bar_create(NULL, 0, 0, 320, 30);

创建之后，就和使用普通窗口一样了。

4.4.5 calibration_win

电阻屏校准窗口。calibration_win_t是window_base_t的子类控件，window_base_t的函数均适用于calibration_win_t控件。

1. 函数

calibration_win提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
calibration_win_create	创建calibration_win对象
calibration_win_set_on_done	设置校准完成的处理函数。
calibration_win_set_on_click	设置校准点击事件的处理函数。
calibration_win_cast	转换为calibration_win对象(供脚本语言使用)。
calibration_win_get_widget_vtable	获取 calibration_win 虚表。

2. 示例

• 在xml中，使用"calibration_win"标签创建电阻屏校准窗口，代码如下：

<!--awtk/demos/assets/default/raw/ui/calibration_win.xml -->
<calibration_win name="cali" w="100%" h="100%" text="Please click the center of cross">
</calibration_win>

• 在C代码中，使用calibration_win_create创建电阻屏校准窗口，代码如下：

widget_t* win = calibration_win_create(NULL, 0, 0, 320, 480);

4.4.6 overlay

overlay窗口。overlay窗口有点类似于非模态的dialog，但是它位置和大小是完全自由的，窗口管理器不会对它做任何限制。如果overlay窗口有透明或半透效果，则不支持窗口动画，但可以通过移动窗口位置来实现类似动画的效果。overlay_t是window_base_t的子类控件，window_base_t的函数均适用于overlay_t控件。

1. 函数

overlay提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
overlay_create	创建overlay对象
overlay_set_click_through	设置是否启用点击穿透。
overlay_set_always_on_top	设置是否总是在最上面。
overlay_set_modeless	设置是否非模态窗口模式。
overlay_cast	转换为overlay对象(供脚本语言使用)。
overlay_get_widget_vtable	获取 overlay 虚表。

2. 属性

overlay还提供了下面属性，详见下表：

属性名称	类型	说明
click_through	bool_t	点击穿透。点击没有子控件的位置，是否穿透到底层窗口。
always_on_top	bool_t	是否总在最上面。
modeless	bool_t	非模态窗口。

3. 示例

• 在xml中，使用"overlay"标签创建overlay控件，代码如下：

<!-- awtk/demos/assets/default/raw/ui/overlay.xml -->
<overlay text="overlay" x="0" y="0" w="100%" h="100%">
  <svg image="ball" x="c" y="m" w="200" h="200"/>
  <button name="close" image="ball" x="c" y="m:150" w="80" h="30" text="Close"/>
</overlay>

4.4.7 popup

popup弹出窗口。弹出窗口是一种特殊的窗口，大小和位置可以自由设置，主要用来实现右键菜单和combo_box的下列列表等功能。popup_t是window_base_t的子类控件，window_base_t的函数均适用于popup_t控件。

1. 函数

popup提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
popup_create	创建popup对象。
popup_cast	转换为popup对象(供脚本语言使用)。
popup_set_close_when_click	设置点击时是否关闭窗口。
popup_set_close_when_click_outside	设置点击窗口外部时是否关闭窗口。
popup_set_close_when_timeout	设置超时关闭时间(ms)。
popup_get_widget_vtable	获取 popup 虚表。

2. 属性

popup还提供了下面属性，详见下表：

属性名称	类型	说明
close_when_click	bool_t	点击时是否关闭窗口。
close_when_click_outside	bool_t	点击到窗口外时是否关闭窗口。
close_when_timeout	uint32_t	超时后自动关闭窗口(ms)。

3. 示例

• 在xml中，使用"popup"标签创建popup控件，代码如下：

<popup close_when_click_outside="true" x="c" y="m" w="80%" h="80" >
  <list_view x="0"  y="0" w="100%" h="100%" item_height="30">
    <scroll_view name="view" x="0"  y="0" w="-12" h="100%">
      <combo_box_item tr_text="english"/>
      <combo_box_item tr_text="chinese" />
    </scroll_view>
    <scroll_bar_d name="bar" x="right" y="0" w="12" h="100%" value="0"/>
  </list_view>
</popup>

4.4.8 component

可复用的 UI 组件。Component 严格意义上来说并不是一个窗口，而是一段通用的 UI 片段，可以在不同的窗口上使用，或者在一个窗口上复用多次，主要用来解决 UI 复用的问题。

Component 是一个独立的 xml 文件，通常用 view 控件作为根节点容器控件，可以往这个 view 控件中添加各种类型子控件组合成组件。

1. 示例

• 在 xml 中，使用"view"标签创建 Component，代码如下：

<!-- component_name.xml -->
<view name="view" x="0" y="0" w="100" h="100">
  <button name="button" x="0" y="36" w="100" h="36" text="Button"/>
</view>

使用 AWTK Designer 可以在"新建窗口"页面中直接创建 Component 类型的界面。

• 在窗口 UI 中，可以通过 Component 界面的文件名直接加载，代码如下：

<!-- home_page.xml -->
<window name="home_page">
  <?include filename="component_name.xml" ?>
</window>

• 在 C 代码中动态加载 Component

在 C 代码中调用 ui_loader_load_widget_with_parent() 函数即可动态加载 Component，接口声明如下：

/**
 * @method ui_loader_load_widget_with_parent
 *
 * 从指定的资源加载widget对象，并为widget对象指定父控件对象，通常用于加载非窗口的widget。
 *
 * @param {const char*} name 资源名。
 * @param {widget_t*} parent 父控件对象。
 *
 * @return {widget_t*} 返回widget对象。
 *
 */
widget_t* ui_loader_load_widget_with_parent(const char* name, widget_t* parent);

动态加载 Component 时，需要传入资源文件名和父控件，比如此处将上文中创建的 Component 加载到某个窗口对象中，代码如下：

ret_t home_page_init(widget_t* win, void* ctx) {
  /* 将 win 窗口作为父控件加载组件，并获取组件对象 component */
  widget_t* component = ui_loader_load_widget_with_parent("component_name", win);

  /* 初始化 component 对象 */
  ...

  return RET_OK;
}

无论是在窗口 UI 中加载 Component，还是在代码中加载 Component，加载完毕后都需要对其进行初始化操作。

4.5 控件的属性

在使用XML编写UI界面的时候，控件包含的属性一般包括两方面：父控件的属性和本身的属性。例如，button_t是widget_t的子类控件，widget_t的属性列表详见widget一节的属性小节，button_t的属性列表详见button一节的属性小节。

在以下代码中button控件的name、style、x、y等属性来自于其父控件widget_t，而enable_long_press属性则来自于自身。

<!-- awtk/demos/assets/default/raw/ui/button.xml -->
<window anim_hint="htranslate">
  <button name="open:dialog1" style="round" enable_long_press="true" 
    x="c" y="10" w="128" h="30" text="Long Press"/>
  <button style="red_btn" x="c" y="50" w="128" h="30" text="Text"/>
  <button style="icon" x="c" y="90" w="128" h="30" text="Fullscreen" name="fullscreen"/>
  <button x="c" y="130" w="128" h="30">
    <label y="0" x="0" w="100%" h="100%" text="Text"/>
    <image image="earth" draw_type="icon" y="0" x="right" w="30" h="100%"/>
  </button>
  
  <button style="icon" x="c" y="170" w="60" h="60" text="Text"/>
  <button style="icon" x="c" y="240" w="60" h="60"/>
  <button style="image" x="c" y="310" w="30" h="30"/>
  
  <button name="close" x="center" y="bottom:10" w="25%" h="30" text="Close"/>
</window>

在XML中设置了控件的name属性，在C代码中就可以通过调用widget_lookup函数获取该控件的对象指针，进一步就可以获取控件对应的属性值了。如，获取name="open:dialog1"按钮的x坐标：

widget_t* btn = widget_lookup(win, "open:dialog1", TRUE);
int32_t x = btn->x;

在上面的代码中，由于widget_lookup的返回类型是widget_t*，且button_t是widget_t的子类控件，所以可以直接通过btn->x的方式获取x坐标。如果要获取button_t中的enable_long_press属性值，则需要将widget_t的类型转换为button_t，如：

button_t* button = BUTTON(btn);
bool_t enable_long_press = button->enable_long_press;

在上面的代码中BUTTON是AWTK中定义的宏，对于其他的控件也有类似的宏，如：check_button_t对应的宏为CHECK_BUTTON，在代码中直接使用即可。

4.6 基本控件

常见的基本控件详见下表：

控件名称	说明
button	按钮控件
label	文本控件
edit	单行编辑器控件
image	图片控件
image_base	图片控件基类（一般不直接使用）
spin_box	数值编辑器控件
combo_box	下拉列表控件
combo_box_item	下拉列表项控件（一般不直接使用）
color_tile	色块控件
dialog_title	对话框标题控件
dialog_client	对话框客户区控件
slider	滑块控件
progress_bar	进度条控件
tab_control	标签控件
tab_button	标签按钮控件
check_button	勾选控件
radio_button	单选控件
dragger	dragger控件，可在指定范围内拖拽
digit_clock	数字时钟控件

4.6.1 button

按钮控件。点击按钮之后会触发EVT_CLICK事件，注册EVT_CLICK事件执行特定操作。按钮控件也可以作为容器使用，使用图片和文本作为其子控件，可以实现很多有趣的效果。button_t是widget_t的子类控件，widget_t的函数均适用于button_t控件。

1. 函数

button提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
button_create	创建button对象
button_cast	转换为button对象(供脚本语言使用)。
button_set_repeat	设置触发EVT_CLICK事件的时间间隔。为0则不重复触发EVT_CLICK事件。
button_set_long_press_time	设置触发长按事件的时间。
button_set_enable_long_press	设置是否启用长按事件。
button_set_enable_preview	设置是否启用预览。
button_get_widget_vtable	获取 button 虚表。

2. 属性

button还提供了下面属性，详见下表：

属性名称	类型	说明
repeat	int32_t	重复触发EVT_CLICK事件的时间间隔。
enable_long_press	bool_t	是否启用长按事件，为true时才触发长按事件。
enable_preview	bool_t	是否启用预览(主要用于软键盘)。
long_press_time	uint32_t	触发长按事件的时间(ms)
pressed	bool_t	当前是否按下。

3. 样式

button可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
icon	图标的名称
spacer	间距
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
icon_at	图标的位置（取值：top|bottom|left|right）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

例如，使用以下代码中的"default"样式，效果详见下图。

<!-- res/assets/default/raw/styles/default.xml -->
<button>
  <style name="default" border_color="#a0a0a0"  text_color="black" font_size="36" >
    <normal     bg_color="green" />
    <pressed     bg_color="red" x_offset="1" y_offset="1"/>
    <over       bg_color="yellow" />
    <disable    bg_color="gray" text_color="#d0d0d0" />
  </style>
  <style name="round" border_color="#a0a0a0"  text_color="black" round_radius="8">
    <normal     bg_color="#f0f0f0" />
    <pressed    bg_color="#c0c0c0" x_offset="1" y_offset="1"/>
    <over       bg_color="#e0e0e0" />
    <disable    bg_color="gray" text_color="#d0d0d0" />
  </style>
  <style name="icon" icon="earth" border_color="#a0a0a0"  text_color="black">
    <normal     bg_color="#f0f0f0" />
    <pressed    bg_color="#c0c0c0" x_offset="3" y_offset="3" />
    <over       bg_color="#e0e0e0" />
    <disable    bg_color="gray" text_color="#d0d0d0" />
  </style>
  <style name="red_btn" bg_image_draw_type="patch3_x" text_color="blue">
    <normal   bg_image="red_btn_n" />
    <pressed  bg_image="red_btn_p" x_offset="3" y_offset="3"/>
    <over     bg_image="red_btn_o" />
  </style>
</button>

图4.5 button样式示例

4. 状态

button在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
pressed	指针按下状态
over	指针悬浮状态
disable	禁用状态
focused	聚焦状态

5. 事件

button还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_CLICK	pointer_event_t	点击事件。
EVT_LONG_PRESS	pointer_event_t	长按事件。

6. 示例

• 在xml中，使用"button"标签创建按钮控件，代码如下，其中的样式详见上文样式一节。

<window anim_hint="htranslate">
  <button style="round" x="c" y="10" w="128" h="30" text="Text"/>
  <button style="red_btn" x="c" y="50" w="128" h="30" text="Text"/>
  <button style="icon" x="c" y="90" w="128" h="30" text="Text"/>
</window>

运行效果如下图所示：

图4.6 在xml中创建button的效果

• 在C代码中，使用函数button_create创建按钮控件，代码如下，其中的样式详见上文样式一节。

ret_t application_init() {
  widget_t* ok;
  widget_t* cancel;
  widget_t* win = window_create(NULL, 0, 0, 0, 0);

  ok = button_create(win, 10, 5, 80, 30);
  widget_set_text(ok, L"Inc");

  cancel = button_create(win, 100, 5, 80, 30);
  widget_set_text(cancel, L"Dec");
  
  return RET_OK;
}

创建之后，需要用widget_set_text或widget_set_text_utf8设置文本内容。运行效果如下图所示：

图4.7 在C代码中创建button的效果

4.6.2 label

文本控件。用于显示一行或多行文本。文本控件设置line_wrap属性为true后，可根据文本的长度自动换行，当文本内容包含换行符时也会换行。label_t是widget_t的子类控件，widget_t的函数均适用于label_t控件。

1. 函数

label提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
label_create	创建label对象
label_set_length	设置显示字符的个数(小余0时全部显示)。
label_set_max_w	设置max_w。
label_set_line_wrap	设置是否自动换行。
label_set_word_wrap	设置是否允许整个单词换行。(需要开启自动换行才有效果)
label_resize_to_content	根据文本内容调节控件大小。
label_cast	转换为label对象(供脚本语言使用)。
label_get_widget_vtable	获取 label 虚表。

2. 属性

label还提供了下面属性，详见下表：

属性名称	类型	说明
length	int32_t	显示字符的个数(小余0时全部显示)。
line_wrap	bool_t	是否自动换行(默认FALSE)。
word_wrap	bool_t	是否允许整个单词换行(默认FALSE)。
max_w	int32_t	当auto_adjust_size为TRUE时，用于控制控件的最大宽度，超出该宽度后才自动换行。

3. 样式

label可设置的样式，详见button一节的样式小节，示例中使用到的样式，代码如下：

<!-- res/assets/default/raw/styles/default.xml -->
<label>
  <style name="default">
    <normal text_color="black" />
  </style>

  <style name="left">
    <normal text_color="red" text_align_h="left" border_color="#a0a0a0" margin="4" font_size="24"/>
  </style>

  <style name="center">
    <normal text_color="green" text_align_h="center" border_color="#a0a0a0" font_size="24"/>
  </style>
  
  <style name="right">
    <normal text_color="blue" text_align_h="right" border_color="#a0a0a0" margin="4" font_size="24"/>
  </style>
</label>

4. 状态

label在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
disable	禁用状态
focused	聚焦状态

5. 示例

• 在xml中，使用"label"标签创建文本控件，代码如下，其中的样式详见上文样式一节。

<window anim_hint="htranslate">
  <row x="0" y="80" w="100%" h="30" children_layout="default(r=1,c=3,xm=2,s=10)">
    <label style="left" name="left" text="Left"/>
    <label style="center" name="center" text="Center"/>
    <label style="right" name="right" text="Right"/>
  </row>
</window>

运行效果如下图所示：

图4.8 在xml创建label的效果

• 在C代码中，使用函数label_create创建文本控件，代码如下，其中的样式详见上文样式一节。

ret_t application_init() {
    widget_t* label;
    widget_t* win = window_create(NULL, 0, 0, 0, 0);
    label = label_create(win, 190, 40, 80, 30);
    widget_set_text(label, L"Right");
    widget_use_style(label, "right");
    return RET_OK;  
}

创建之后，需要用widget_set_text或widget_set_text_utf8设置文本内容。运行效果如下图所示。

图4.9 在C代码中创建label的效果

4.6.3 edit

单行编辑器控件。在基于SDL的平台，单行编辑器控件使用平台原生的输入法，对于嵌入式平台使用内置的输入法。在使用内置的输入法时，软键盘由输入类型决定，开发者可以自定义软键盘的界面。edit_t是widget_t的子类控件，widget_t的函数均适用于edit_t控件。

edit_t控件中光标的颜色取的是样式文件中该控件的text_color；如果没有设置text_color，则默认是黑色。

edit_t本身可以做为容器，放入按钮等控件。有几个特殊的子控件：

• 名为"clear"的按钮。点击时清除编辑器中的内容
• 名为"inc"的按钮。点击时增加编辑器的值，用于实现类似于spinbox的功能
• 名为"dec"的按钮。点击时减少编辑器的值，用于实现类似于spinbox的功能
• 名为"visible"的复选框。勾选时显示密码，反之不显示密码

例如，在以下代码中edit控件包含了inc和dec按钮，效果如下图所示。其中edit使用的样式详见下文样式一节。

<window anim_hint="htranslate" >
  <list_view x="0"  y="0" w="100%" h="-50" item_height="36" auto_hide_scroll_bar="true">
    <scroll_view name="view" x="0"  y="0" w="-12" h="100%">
     <list_item style="empty" children_layout="default(r=1,c=0,ym=1)">
      <label w="30%" text="Age"/>
      <edit w="70%" right_margin="16" tips="uint(0-150)" input_type="uint" min="0" max="150" step="1">
        <button name="inc" repeat="300" style="spinbox_up" x="right" y="0" w="15" h="50%" />
        <button name="dec" repeat="300" style="spinbox_down" x="right" y="bottom" w="15" h="50%" />
      </edit>
     </list_item>
    </scroll_view>
    <scroll_bar_d name="bar" x="right" y="0" w="12" h="100%" value="0"/>
  </list_view>
  <button name="close" x="center" y="bottom:10" w="25%" h="30" text="Close"/>
</window>

图4.10 edit包含inc和dec按钮

1. 函数

edit提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
edit_create	创建edit对象
edit_cast	转换为edit对象(供脚本语言使用)。
edit_get_int	获取int类型的值。
edit_get_double	获取double类型的值。
edit_set_int	设置int类型的值。
edit_set_double	设置double类型的值。
edit_set_double_ex	设置double类型的值。
edit_set_text_limit	设置为文本输入及其长度限制，不允许输入超过max个字符，少于min个字符时进入error状态。
edit_set_int_limit	设置为整数输入及取值范围。
edit_set_float_limit	设置为浮点数输入及取值范围。
edit_set_readonly	设置编辑器是否为只读。
edit_set_cancelable	设置编辑器是否为可撤销修改。
edit_set_auto_fix	设置编辑器是否为自动改正。
edit_set_select_none_when_focused	设置编辑器是否在获得焦点时不选中文本。
edit_set_open_im_when_focused	设置编辑器是否在获得焦点时打开输入法。
edit_set_close_im_when_blured	设置编辑器是否在失去焦点时关闭输入法。
edit_set_input_type	设置编辑器的输入类型。
edit_set_action_text	设置软键盘上action按钮的文本。
edit_set_tips	设置编辑器的输入提示。
edit_set_tr_tips	获取翻译之后的文本，然后调用edit_set_tips。
edit_set_keyboard	设置自定义软键盘名称。
edit_set_password_visible	当编辑器输入类型为密码时，设置密码是否可见。
edit_set_focus	设置为焦点。
edit_set_cursor	设置输入框的光标位置。
edit_get_cursor	获取输入框的光标位置。
edit_set_is_valid_char	设置输入字符检查函数。
edit_set_is_valid_value	设置输入内容检查函数。
edit_set_fix_value	设置修正输入内容的回调函数。
edit_set_inc_value	设置增加值的回调函数。
edit_set_dec_value	设置减少值的回调函数。
edit_set_pre_input	设置预输入处理的回调函数。
edit_set_pre_delete	设置预删除处理的回调函数。
edit_set_select	选择指定范围的文本。
edit_get_selected_text	获取选中的文本。
edit_get_widget_vtable	获取 edit 虚表。

2. 属性

edit还提供了下面属性，详见下表：

属性名称	类型	说明
tips	char*	输入提示。
tr_tips	char*	保存用于翻译的提示信息。
action_text	char*	软键盘上action按钮的文本。内置取值有：
keyboard	char*	自定义软键盘名称。AWTK优先查找keyboard属性设置的键盘文件名（该键盘的XML文件需要在default\raw\ui目录下存在），如果没有指定keyboard，就找input_type设置的键盘类型。如果指定为空字符串，则表示不需要软键盘。
min	double	最小值或最小长度。
max	double	最大值或最大长度。
step	double	步长。
input_type	input_type_t	输入类型。
readonly	bool_t	编辑器是否为只读。
password_visible	bool_t	密码是否可见。
auto_fix	bool_t	输入无效时，是否自动改正。
select_none_when_focused	bool_t	获得焦点时不选中文本。
open_im_when_focused	bool_t	获得焦点时打开输入法。
close_im_when_blured	bool_t	是否在失去焦点时关闭输入法(默认是)。
cancelable	bool_t	是否支持撤销编辑。如果为TRUE，在失去焦点之前可以撤销所有修改(恢复获得焦点之前的内容)。

3. 样式

edit可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
fg_color	前景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
tips_text_color	提示文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
fg_image	前景图片的名称
fg_image_draw_type	前景图片的显示方式（取值：详见image 控件一节）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
selected_bg_color	编辑器（包括edit和mledit控件）中选中区域的背景颜色
selected_fg_color	编辑器（包括edit和mledit控件）中选中区域的前景颜色
selected_text_color	编辑器（包括edit和mledit控件）中选中区域的文本颜色
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

例如，使用以下代码设置的样式，效果如下图所示。

<!-- res/assets/default/raw/styles/default.xml -->
<edit selected_fg_color="red" selected_text_color="blue" selected_bg_color="yellow">
  <style name="default" border_color="#a0a0a0"  text_color="black" text_align_h="center" font_size="40">
    <normal     bg_color="#f0f0f0" />
    <focused    bg_color="orange" border_color="black"/>
    <disable    bg_color="gray" text_color="#d0d0d0" />
    <error      bg_color="#f0f0f0" text_color="red" />
    <empty      bg_color="green" text_color="#a0a0a0" />
    <empty_focus bg_color="black" text_color="#a0a0a0" border_color="black"/>
  </style>
  <style name="number" border_color="#a0a0a0"  text_color="black" text_align_h="right">
    <normal     bg_color="#f0f0f0" />
    <focused    bg_color="#f0f0f0" border_color="black"/>
    <disable    bg_color="gray" text_color="#d0d0d0" />
    <error      bg_color="#f0f0f0" text_color="red" />
    <empty      bg_color="#f0f0f0" text_color="#a0a0a0" />
  </style>
</edit>

图4.11 edit样式示例

4. 状态

edit在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
pressed	指针按下状态
error	编辑器错误
empty	编辑器无内容状态
over	指针悬浮状态
empty_focus	编辑器无内容同时聚焦的状态
empty_over	编辑器无内容同时指针悬浮状态
disable	禁用状态
focused	聚焦状态

5. 事件

edit还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_CHANGING	value_change_event_t	文本正在改变事件(编辑中)。
EVT_VALUE_CHANGED	value_change_event_t	文本改变事件(编辑完成或设置文本时触发)。
EVT_IM_ACTION	event_t	软键盘Action点击事件。

6. 示例

• 在xml中，使用"edit"标签创建单行编辑器控件，代码如下，其中edit使用的样式详见上文样式一节。

<window anim_hint="htranslate" >
  <list_view x="0"  y="0" w="100%" h="-50" item_height="36" auto_hide_scroll_bar="true">
    <scroll_view name="view" x="0"  y="0" w="-12" h="100%">
     <list_item style="empty" children_layout="default(r=1,c=0,ym=1)">
      <label w="30%" text="Age"/>
      <edit w="70%" right_margin="16" tips="uint(0-150) auto_fix" input_type="uint" min="0" max="150" 
	  step="1" auto_fix="true" style="number">
        <button name="inc" repeat="300" style="spinbox_up" x="right" y="0" w="15" h="50%" />
        <button name="dec" repeat="300" style="spinbox_down" x="right" y="bottom" w="15" h="50%" />
      </edit>
     </list_item>
  </list_view>
  <button name="close" x="center" y="bottom:10" w="25%" h="30" text="Close"/>
</window>

运行效果如下图所示：

图4.12 在xml中创建edit的效果

• 在C代码中，使用函数edit_create创建单行编辑器控件，代码如下，其中edit使用的样式详见上文样式一节。

ret_t application_init(void) {
  widget_t* win = window_create(NULL, 0, 0, 0, 0);
  widget_t* label = label_create(win, 0, 0, 0, 0);
  widget_t* edit = edit_create(win, 0, 0, 0, 0);
  widget_set_text(label, L"hello awtk!");
  widget_set_self_layout_params(label, "0", "middle", "30%", "30");
  widget_set_self_layout_params(edit, "30%", "middle", "60%", "30");
  widget_layout(win);
  return RET_OK;
}

创建之后，需要用widget_set_text或widget_set_text_utf8设置文本内容。运行效果如下图所示：

图4.13 在C代码中创建edit的效果

4.6.4 image

图片控件，用来显示一张静态图片，目前支持bmp/png/jpg等格式，其中：

• 如果要显示gif文件，请用gif_image
• 如果要显示svg文件，请用svg_image
• 如果需要支持勾选效果，请设置selectable属性
• 如果需要支持点击效果，请设置clickable属性

image_t是image_base_t的子类控件，image_base_t的函数均适用于image_t控件。关于selectable属性的示例，请看下图。

图4.14 selectable属性

1. 函数

image提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
image_create	创建image对象
icon_create	创建icon对象
image_set_draw_type	设置图片的绘制方式。
image_cast	转换为image对象(供脚本语言使用)。
image_get_widget_vtable	获取 image 虚表。

2. 属性

image还提供了下面属性，详见下表：

属性名称	类型	说明
draw_type	image_draw_type_t	图片的绘制方式(仅在没有旋转和缩放时生效)。

draw_type可取的值，详见下表：

draw_type取值	说明
default	缺省显示。将图片按原大小显示在目标矩形的左上角
icon	图标显示。同居中显示，但会根据屏幕密度调整大小
center	居中显示。将图片按原大小显示在目标矩形的中央
scale	缩放显示。将图片缩放至目标矩形的大小（不保证宽高成比例）
scale_auto	自动缩放显示。将图片缩放至目标矩形宽度或高度（选取最小的比例），并居中显示
scale_w	宽度缩放显示。将图片缩放至目标矩形的宽度，高度按此比例进行缩放，超出部分不显示
scale_h	高度缩放显示。将图片缩放至目标矩形的高度，宽度按此比例进行缩放，超出部分不显示
repeat	平铺显示
repeat_x	水平方向平铺显示，垂直方向缩放
repeat_y	垂直方向平铺显示，水平方向缩放
repeat_y_inverse	垂直方向平铺显示，水平方向缩放(从底部到顶部)。
patch9	9宫格显示
patch3_x	水平方向3宫格显示，垂直方向居中显示
patch3_y	垂直方向3宫格显示，水平方向居中显示
patch3_x_scale_y	水平方向3宫格显示，垂直方向缩放显示
patch3_y_scale_x	垂直方向3宫格显示，水平方向缩放显示

3. 样式

image可设置的样式，详见button一节的样式小节。示例中使用的样式，代码如下：

<!-- res/assets/default/raw/styles/default.xml -->
<image>
  <style name="border">
    <normal border_color="#000000" bg_color="#e0e0e0" text_color="black"/>
  </style>
</image>

4. 状态

image在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
pressed	指针按下状态
selected	选中状态
disable	禁用状态
focused	聚焦状态

5. 示例

• 在xml中，使用"image"标签创建图片控件，代码如下，其中image="1"中的1是图片名，即1.jpg。程序中image使用的样式，详见上文样式一节。

<window anim_hint="htranslate" >
  <list_view x="0"  y="0" w="100%" h="-50" item_height="128" auto_hide_scroll_bar="true">
    <scroll_view name="view" x="0"  y="0" w="-12" h="100%">
     <list_item style="empty" children_layout="default(r=1,c=3,s=2,m=2)">
      <image style="border" image="1" draw_type="scale_auto"><label w="100%" h="100%" text="auto"/>
	  </image>
      <image style="border" image="2" draw_type="scale_auto"><label w="100%" h="100%" text="auto"/>
	  </image>
      <image style="border" image="3" draw_type="scale_auto"><label w="100%" h="100%" text="auto"/>
	  </image>
     </list_item>
</window>

运行效果如下图所示：

图4.15 在xml中创建image的效果

• 在C代码中，使用函数image_create创建图片控件，代码如下：

ret_t application_init() {
  image = image_create(win, 10, 230, 100, 100);
  image_set_image(image, "earth");
  image_set_draw_type(image, IMAGE_DRAW_ICON);
}

创建之后，需要用image_set_image设置图片名称，用image_set_draw_type设置图片的绘制方式。运行效果如下图所示：

图4.16 在C代码中创建image的效果

4.6.5 spin_box

spinbox控件。一个特殊的数值编辑器，将edit_t和button_t进行组合，方便编辑数值。点击向上的按钮将数值增加一个step，点击向下的按钮将数值减小一个step。step的值可以通过step属性进行设置。spin_box_t是edit_t的子类控件，edit_t的函数均适用于spin_box_t控件。

使用该控件的时候需要将awtk/demos/assets/default/raw/images/x1目录下：arrow_*.png共12张图片复制到自己的应用目录下（如：res/assets/default/raw/images/xx），否则将不能正常显示。

1. 函数

spin_box提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
spin_box_create	创建spin_box对象
spin_box_cast	转换为spin_box对象(供脚本语言使用)。
spin_box_set_easy_touch_mode	设置是否启用易点击模式。
spin_box_set_button_position	设置按钮位置样式。
spin_set_repeat	设置连击的时间间隔。
spin_box_get_widget_vtable	获取 spin_box 虚表。

2. 属性

spin_box还提供了下面属性，详见下表：

属性名称	类型	说明
easy_touch_mode	bool_t	是否启用易点击模式(在电容屏设备上建议启用)。
button_position	char*	按钮位置样式选择，优先级高于easy_touch_mode，各模式对应样式如下,默认为none。
repeat	int32_t	重复触发EVT_CLICK事件的时间间隔。

3. 样式

spin_box可设置的样式，详见edit一节的样式小节。spin_box的"default"样式代码如下：

<!-- res/assets/default/raw/styles/default.xml -->
<spin_box>
  <style name="default" border_color="#a0a0a0"  text_color="black" text_align_h="left">
    <normal     bg_color="#f0f0f0" />
    <focused    bg_color="#f0f0f0" border_color="black"/>
    <disable    bg_color="gray" text_color="#d0d0d0" />
    <error      bg_color="#f0f0f0" text_color="red" />
    <empty      bg_color="#f0f0f0" text_color="#a0a0a0" />
  </style>
</spin_box>

4. 示例

• 在xml中，使用"spin_box"标签创建spinbox控件，代码如下，其中使用的样式，详见上文第二小节。

<window anim_hint="htranslate" children_layout="default(h=30,c=1,m=2,s=2)">
  <view children_layout="default(r=1,c=0)">
    <spin_box w="70%" tips="uint(0-150) auto_fix" input_type="uint" min="0" max="150" step="1" 
	 auto_fix="true">
    </spin_box>
  </view>
</window>

运行效果如下图所示：

图4.17 在xml中创建spin_box的效果

• 在C代码中，使用函数spin_box_create创建spinbox控件，代码如下：

ret_t application_init() {
  widget_t* spin_box;
  widget_t* win = window_create(NULL, 0, 0, 0, 0);

  spin_box = spin_box_create(win, 10, 10, 128, 30);
  edit_set_input_type(spin_box, INPUT_INT);

  return RET_OK;
}

创建之后，可以用edit相关函数去设置它的各种属性。运行效果如下图所示：

图4.18 在C代码中创建spin_box的效果

4.6.6 combo_box

下拉列表控件。点击右边的按钮，可弹出一个下拉列表，从中选择一项作为当前的值。combo_box_t是edit_t的子类控件，edit_t的函数均适用于combo_box_t控件。另外，如果需要使用带滚动条的下拉列表控件请用combo_box_ex_t，该控件的用法、函数、属性等都与combo_box_t一样。

使用该控件的时候需要将awtk/demos/assets/default/raw/images/x1目录下：arrow_down_*.png共3张图片复制到自己的应用目录下（如：res/assets/default/raw/images/xx），否则将不能正常显示。

1. 函数

combo_box提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
combo_box_create	创建combo_box对象
combo_box_cast	转换combo_box对象(供脚本语言使用)。
combo_box_set_open_window	点击按钮时可以打开popup窗口，本函数可设置窗口的名称。
combo_box_set_theme_of_popup	设置弹出窗口的主题。
combo_box_reset_options	重置所有选项。
combo_box_count_options	获取选项个数。
combo_box_set_selected_index	设置第index个选项为当前选中的选项。
combo_box_set_selected_index_by_text	根据文本设置当前选中的选项。
combo_box_set_localize_options	设置是否本地化(翻译)选项。
combo_box_set_value	设置值。
combo_box_set_item_height	设置item高度。
combo_box_append_option	追加一个选项。
combo_box_remove_option	删除选项。
combo_box_set_options	设置选项。
combo_box_set_custom_open_popup	设置自定义的打开弹出窗口的函数。
combo_box_set_on_item_click	设置弹出窗口的item被点击的回调函数，回调函数返回非RET_OK，继续默认处理。
combo_box_get_option	获取第index个选项。
combo_box_get_value	获取combo_box的值。
combo_box_has_option_text	检查选项中是否存在指定的文本。
combo_box_get_text	获取combo_box的文本(可能是翻译后的文本)。
combo_box_get_text_of_selected	获取combo_box当前选中项目的文本(原生非翻译的文本)。
combo_box_get_widget_vtable	获取 combo_box 虚表。

2. 属性

combo_box还提供了下面属性，详见下表：

属性名称	类型	说明
open_window	char*	为点击按钮时，要打开窗口的名称。
theme_of_popup	char*	弹出窗口的主题(对应的style文件必须存在)，方便为不同combo box的弹出窗口指定不同的样式。
selected_index	int32_t	当前选中的选项。
value	int32_t	值。
localize_options	bool_t	是否本地化(翻译)选项(缺省为TRUE)。
options	char*	设置可选项(冒号分隔值和文本，分号分隔选项，如:1:red;2:green;3:blue)。
item_height	int32_t	下拉选项的高度。如果open_window为空，则使用缺省高度。

3. 样式

combo_box可设置的样式，详见button一节的样式小节。combo_box的"default"样式，代码如下：

<!-- res/assets/default/raw/styles/default.xml -->
<combo_box>
  <style name="default" border_color="#a0a0a0"  text_color="black" text_align_h="left">
    <normal     bg_color="#f0f0f0" />
    <focused    bg_color="#f0f0f0" border_color="black"/>
    <disable    bg_color="gray" text_color="#d0d0d0" />
    <error      bg_color="#f0f0f0" text_color="red" />
    <empty      bg_color="#f0f0f0" text_color="#a0a0a0" />
  </style>
</combo_box>

4. 状态

combo_box在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
error	指针按下状态
empty	编辑器无内容状态
empty_focus	编辑器无内容同时聚焦的状态
disable	禁用状态
focused	聚焦状态

5. 事件

combo_box还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值改变事件。

6. 示例

• 在xml中，使用"combo_box"标签创建下拉列表控件，代码如下，其中使用到的样式详见上文样式一节。

<window anim_hint="htranslate">
    <combo_box left_margin="6" readonly="true" x="10" y="5" w="200" h="30" text="left" options="left;center;right;"/>
    <combo_box open_window="color" readonly="true" x="10" y="50" w="200" h="30" text="red"/>
    <combo_box readonly="true" x="10" y="bottom:5" w="200" h="30" tr_text="ok" options="1:ok;2:cancel;"/>
    <combo_box open_window="langauge" readonly="true" x="10" y="bottom:50" w="200" h="30" tr_text="english"/>
</window>

运行效果如下图所示：

图4.19 在xml中创建combo_box的效果

• 在C代码中，使用combo_box_create创建下拉列表控件，代码如下：

ret_t application_init() {
  widget_t* combo_box;
  widget_t* win = window_create(NULL, 0, 0, 0, 0);
  combo_box = combo_box_create(win, 10, 10, 128, 30);
  combo_box_set_options(combo_box, "left;center;right;");
  combo_box_set_selected_index(combo_box, 1);
  return RET_OK;
}

创建之后，用combo_box_set_options设置可选项目，用combo_box_set_selected_index设置缺省项。运行效果如下图所示：

图4.20 在C代码中创建combo_box的效果

4.6.7 combo_box_item

combo_box_item控件，本控件仅供combo_box控件内部使用。combo_box_item_t是widget_t的子类控件，widget_t的函数均适用于combo_box_item_t控件。

1. 函数

combo_box_item提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
combo_box_item_create	创建combo_box_item对象
combo_box_item_cast	转换combo_box_item对象(供脚本语言使用)。
combo_box_item_set_checked	设置控件是否被选中。
combo_box_item_set_value	设置控件的值。
combo_box_item_get_widget_vtable	获取 combo_box_item 虚表。

2. 属性

combo_box_item还提供了下面属性，详见下表：

属性名称	类型	说明
value	int32_t	值。
checked	bool_t	是否被选中。

3. 事件

combo_box_item还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_CLICK	pointer_event_t	点击事件。
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(勾选状态)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(勾选状态)改变事件。

4. 示例

• 在xml中，使用"combo_box_item"标签创建色块控件，代码如下：

<!-- awtk/design/deafault/ui/language.xml -->
<popup close_when_click_outside="true" h="80" >
  <list_view x="0"  y="0" w="100%" h="100%" item_height="30">
    <scroll_view name="view" x="0"  y="0" w="-12" h="100%">
      <combo_box_item tr_text="english"/>
      <combo_box_item tr_text="chinese" />
    </scroll_view>
    <scroll_bar_d name="bar" x="right" y="0" w="12" h="100%" value="0"/>
  </list_view>
</popup>

4.6.8 color_tile

色块控件。用来显示一个颜色块，它通过属性而不是窗体样式来设置颜色，方便在运行时动态改变颜色。可以使用value属性访问背景颜色的颜色值。color_tile_t是widget_t的子类控件，widget_t的函数均适用于color_tile_t控件。

1. 函数

color_tile提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
color_tile_create	创建color_tile对象
color_tile_cast	转换为color_tile对象(供脚本语言使用)。
color_tile_set_bg_color	设置背景颜色。
color_tile_set_border_color	设置边框颜色。
color_tile_set_value	设置背景颜色。
color_tile_get_bg_color	获取背景颜色。
color_tile_get_border_color	获取边框颜色。
color_tile_get_widget_vtable	获取 color_tile 虚表。

2. 属性

color_tile还提供了下面属性，详见下表。

属性名称	类型	说明
bg_color	char*	背景颜色。
border_color	char*	边框颜色。

3. 事件

color_tile还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(颜色)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(颜色)改变事件。

4. 示例

• 在xml中，使用"color_tile"标签创建色块控件，代码如下：

<window>
  <color_picker x="0" y="0" w="100%" h="100%" value="orange">
    <color_component x="0" y="0" w="200" h="200" name="sv"/>
    <color_component x="210" y="0" w="20" h="200" name="h"/>
    <color_tile x="0" y="210" w="50%" h="20" name="new" bg_color="green"/>
    <color_tile x="right" y="210" w="50%" h="20" name="old" bg_color="blue"/>
  </color_picker>
</window>

运行效果如下图所示：

图4.21 在xml中创建color_tile的效果

• 在C代码中，使用函数color_tile_create创建色块控件，代码如下：

ret_t application_init() {
  widget_t* color_tile;
  widget_t* win = window_create(NULL, 0, 0, 0, 0);

  color_tile = color_tile_create(win, 10, 10, 128, 30);
  color_tile_set_bg_color(color_tile, "red");

  return RET_OK;
}

创建之后，用color_tile_set_bg_color设置背景颜色。运行效果如下图所示：

图4.22 在C代码中创建color_tile的效果

4.6.9 dialog_title

对话框标题控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。dialog_title_t是widget_t的子类控件，widget_t的函数均适用于dialog_title_t控件。

1. 函数

dialog_title提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
dialog_title_create	创建dialog对象。
dialog_title_cast	转换为dialog_title对象(供脚本语言使用)。
dialog_title_get_widget_vtable	获取 dialog_title 虚表。

2. 示例

• 在xml中，使用"dialog_title"标签创建对话框标题控件，代码如下：

<dialog anim_hint="center_scale(duration=300)" x="c" y="m" w="80%" h="160" text="Dialog">
  <dialog_title x="0" y="0" w="100%" h="30" text="Hello AWTK" />
  <dialog_client x="0" y="bottom" w="100%" h="-30">
    <label name="" x="center" y="middle:-20" w="200" h="30" text="Are you ready?"/>
    <button name="quit" x="10" y="bottom:10" w="40%" h="30" text="确定"/>
    <button name="quit" x="right:10" y="bottom:10" w="40%" h="30" text="取消"/>
  </dialog_client>
</dialog>

运行效果如下图所示：

图4.23 在xml中创建dialog_title的效果

• 在C代码中，使用dialog_create_simple()创建对话框标题控件时，会自动创建dialog标题对象，通过"dialog->tile"，可以对dialog标题进行操作，代码如下：

static ret_t on_show_dialog(void* ctx, event_t* e) {
  (void)ctx;
  (void)e;

  widget_t* win = dialog_create_simple(NULL, 0, 0, 240, 160);
  dialog_t* dialog = DIALOG(win);
   
  code = dialog_modal(win);
  
  return RET_OK;
}

运行效果如下图所示：

图4.24 在C代码中创建dialog_title的效果

4.6.10 dialog_client

对话框客户区控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。dialog_client_t是widget_t的子类控件，widget_t的函数均适用于dialog_client_t控件。

1. 函数

dialog_client提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
dialog_client_create	创建dialog客户区对象。
dialog_client_cast	转换为dialog_client对象(供脚本语言使用)。
dialog_client_get_widget_vtable	获取 dialog_client 虚表。

2. 示例

• 在xml中，使用"dialog_client"标签创建对话框客户区控件，代码如下：

<dialog anim_hint="center_scale(duration=300)" x="c" y="m" w="80%" h="160" text="Dialog">
  <dialog_title x="0" y="0" w="100%" h="30" text="Hello AWTK" />
  <dialog_client x="0" y="bottom" w="100%" h="-30">
    <label name="" x="center" y="middle:-20" w="200" h="30" text="Are you ready?"/>
    <button name="quit" x="10" y="bottom:10" w="40%" h="30" text="确定"/>
    <button name="quit" x="right:10" y="bottom:10" w="40%" h="30" text="取消"/>
  </dialog_client>
</dialog>

运行效果如下图所示：

图4.25 在xml中创建dialog_client的效果

• 在C代码中，使用dialog_create_simple()创建对话框控件时，会自动创建dialog客户区对象，通过"dialog->client"，可以对dialog客户区进行操作。代码如下：

static ret_t on_show_dialog(void* ctx, event_t* e) {
  (void)ctx;
  (void)e;

  widget_t* win = dialog_create_simple(NULL, 0, 0, 240, 160);
  dialog_t* dialog = DIALOG(win);
   
  code = dialog_modal(win);
  
  return RET_OK;
}

运行效果如下图所示：

图4.26 在C代码中创建dialog_client的效果

4.6.11 slider

滑块控件。slider_t是widget_t的子类控件，widget_t的函数均适用于slider_t控件。slider_t控件可以拖拉的小方块背景色使用的是"border_color"的颜色。

1. 函数

slider提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
slider_create	创建slider对象
slider_cast	转换为slider对象(供脚本语言使用)。
slider_set_value	设置滑块的值。
slider_set_min	设置滑块的最小值。
slider_set_max	设置滑块的最大值。
slider_set_line_cap	设置前景色的线帽形状。（默认为跟随风格的圆角设置，但是在没有设置圆角的时候无法使用 "round" 来设置圆角）
slider_set_step	设置滑块的拖动的最小单位。
slider_set_bar_size	设置bar的宽度或高度。
slider_set_vertical	设置滑块的方向。
slider_set_value_internal	设置滑块的值(public for test)。
slider_get_widget_vtable	获取 slider 虚表。

2. 属性

slider还提供了下面属性，详见下表：

属性名称	类型	说明
value	double	值。
min	double	最小值。
max	double	最大值。
step	double	拖动的最小单位。
bar_size	uint32_t	轴的宽度或高度（单位：像素），为0表示为控件的宽度或高度的一半，缺省为0。
dragger_size	uint32_t	滑块的宽度或高度（单位：像素），缺省为 bar_size * 1.5。
line_cap	char*	前景色的线帽形状。（取值：butt
vertical	bool_t	滑块的是否为垂直方向。
dragger_adapt_to_icon	bool_t	滑块的宽度或高度是否与icon适应，缺省为true。
slide_with_bar	bool_t	是否允许在轴上滑动来改变滑块位置，缺省为FALSE。

3. 样式

slider可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
fg_color	前景颜色
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
icon	图标的名称
fg_image	前景图片的名称
fg_image_draw_type	前景图片的显示方式（取值：详见image 控件一节）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果

例如，使用以下代码设置的样式，效果详见下图。

<!-- res/assets/default/raw/styles/default.xml -->
<slider>
  <style name="default">
    <normal bg_color="red" fg_color="blue" border_color="green"/>
    <pressed bg_color="red" fg_color="blue" border_color="green"/>
    <over bg_color="red" fg_color="blue" border_color="green"/>
    <focused bg_color="red" fg_color="blue" border_color="green"/>
  </style>
</slider>

图4.27 slider样式示例

4. 状态

slider在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
pressed	指针按下状态
over	指针悬浮状态
disable	禁用状态
focused	聚焦状态

5. 事件

slider还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值即将改变事件。
EVT_VALUE_CHANGING	value_change_event_t	值正在改变事件(拖动中)。
EVT_VALUE_CHANGED	value_change_event_t	值改变事件。

6. 示例

• 在xml中，使用"slider"标签创建滑块控件，代码如下：

<window>
     <slider x="98" y="middle" w="-100" h="10%" name="g" />
</window>

运行效果如下图所示：

图4.28 在xml中创建slider的效果

• 在C代码中，使用函数slider_create创建滑块控件，代码如下：

ret_t application_init() {
  widget_t* slider;
  widget_t* win = window_create(NULL, 0, 0, 0, 0);
  slider = slider_create(win, 10, 10, 200, 30);
  return RET_OK;
}

运行效果如下图所示：

图4.29 在C代码中创建slider的效果

4.6.12 progress_bar

进度条控件。进度条控件可以水平显示也可以垂直显示，由vertical属性决定。progress_bar_t是widget_t的子类控件，widget_t的函数均适用于progress_bar_t控件。

1. 函数

progress_bar提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
progress_bar_create	创建progress_bar对象
progress_bar_cast	转换为progress_bar对象(供脚本语言使用)。
progress_bar_set_value	设置进度条的进度。
progress_bar_set_max	设置最大值。
progress_bar_set_format	设置格式。
progress_bar_set_vertical	设置进度条的方向。
progress_bar_set_show_text	设置进度条的是否显示文本。
progress_bar_set_reverse	设置进度条是否反向。
progress_bar_get_percent	获取进度百分比。
progress_bar_get_widget_vtable	获取 progress_bar 虚表。

2. 属性

progress_bar还提供了下面属性，详见下表：

属性名称	类型	说明
value	double	进度条的值[0-max]。
max	double	最大值(缺省为100)。
format	char*	数值到字符串转换时的格式，缺省为"%d"。
vertical	bool_t	进度条的是否为垂直方向。
show_text	bool_t	是否显示文本。
reverse	bool_t	是否反向显示。如果为TRUE，水平方向从右向左表示增加，垂直方向从上到下表示增加。

3. 样式

progress_bar可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
fg_color	前景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
icon	图标的名称
fg_image	前景图片的名称
fg_image_draw_type	前景图片的显示方式（取值：详见image 控件一节）
spacer	间距
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
icon_at	图标的位置（取值：top|bottom|left|right）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果

例如，使用以下代码设置的样式，效果如下图所示。

<!-- res/assets/default/raw/styles/default.xml -->
<progress_bar>
  <style name="default">
    <normal bg_color="red" fg_color="green" border_color="#333333"/>
  </style>
</progress_bar>

图4.30 progress_bar样式示例

4. 事件

progress_bar还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值改变事件。

5. 示例

• 在xml中，使用"progress_bar"标签创建进度条控件，代码如下：

<window anim_hint="htranslate">
  <progress_bar name="bar1" x="10" y="142" w="240" h="16" value="40"/>
  <progress_bar name="bar2" x="280" y="128" w="30" h="118" value="20" vertical="true"/>
</window>

运行效果如下图所示：

图4.31 在xml中创建progress_bar的效果

• 在C代码中，使用函数progress_bar_create创建进度条控件，代码如下：

ret_t application_init() {
  widget_t* progress_bar;
  widget_t* win = window_create(NULL, 0, 0, 0, 0);

  progress_bar = progress_bar_create(win, 260, 80, 20, 118);
  widget_set_value(progress_bar, 40);
  progress_bar_set_vertical(progress_bar, TRUE);
  return RET_OK;
}

运行效果如下图所示：

图4.32 在C代码中创建progress_bar的效果

4.6.13 tab_control

标签控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。标签控件通常会包含一个pages控件和一个tab_button_group控件，它们之间的关系如下图所示。tab_control_t是widget_t的子类控件，widget_t的函数均适用于tab_control_t控件。

图4.33 tab_control

1. 函数

tab_control提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
tab_control_create	创建tab_control对象
tab_control_cast	转换tab_control对象(供脚本语言使用)。
tab_control_get_widget_vtable	获取 tab_control 虚表。

2. 样式

tab_control可设置的样式，详见button一节的样式小节。tab_control的样式示例，代码如下：

<!-- res/assets/default/raw/styles/default.xml -->
<tab_button>
  <style name="default" border_color="#a0a0a0"  text_color="black">
    <normal     bg_color="#d0d0d0" />
    <pressed    bg_color="#f0f0f0" />
    <over       bg_color="#e0e0e0" />
    <normal_of_active     bg_color="#f0f0f0" />
    <pressed_of_active    bg_color="#f0f0f0" />
    <over_of_active       bg_color="#f0f0f0" />
  </style>
</tab_button>

<tab_button_group>
  <style name="default">
    <normal/>
  </style>
</tab_button_group>

3. 示例

• 在xml中，使用"tab_control"标签创建标签控件，代码如下，其中使用的样式，详见上文样式小节。

<window anim_hint="htranslate" theme="tab_bottom">
  <tab_control x="0" y="0" w="100%" h="100%" >
    <pages x="0" y="0" w="100%" h="-60" style="at_top">
      <?include filename="tab_views.inc" ?>
    </pages>
    <tab_button_group x="0" y="bottom" w="100%" h="60" >
      <tab_button icon="msg" active_icon="msg_active" text="Message"/>
      <tab_button icon="contact" active_icon="contact_active" text="Contact" value="true" />
      <tab_button icon="discovery" active_icon="discovery_active" text="Discovery" />
      <tab_button icon="me" active_icon="me_active" text="Me" />
    </tab_button_group>
  </tab_control>
</window>

运行效果如下图所示：

图4.34 在xml中创建tab_control的效果

4.6.14 tab_button

标签按钮控件。标签按钮有点类似单选按钮，但点击标签按钮之后会自动切换当前的标签页。tab_button_t是widget_t的子类控件，widget_t的函数均适用于tab_button_t控件。

1. 函数

tab_button提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
tab_button_create	创建tab_button对象
tab_button_cast	转换tab_button对象(供脚本语言使用)。
tab_button_set_value	设置为当前标签。
tab_button_set_icon	设置控件的图标。
tab_button_set_active_icon	设置控件的active图标。
tab_button_set_load_ui	设置控件动态加载显示UI。
tab_button_get_widget_vtable	获取 tab_button 虚表。

2. 属性

tab_button还提供了下面属性，详见下表：

属性名称	类型	说明
value	bool_t	值。
load_ui	char*	激活后加载的UI名字。
active_icon	char*	当前项的图标的名称。
icon	char*	非当前项的图标的名称。

3. 样式

tab_button可设置的样式，详见button一节的样式小节。tab_button的样式示例，代码如下：

<!-- res/assets/default/raw/styles/default.xml -->
<tab_button>
  <style name="default" border_color="#a0a0a0"  text_color="black">
    <normal     bg_color="#d0d0d0" />
    <pressed    bg_color="#f0f0f0" />
    <over       bg_color="#e0e0e0" />
    <normal_of_active     bg_color="#f0f0f0" />
    <pressed_of_active    bg_color="#f0f0f0" />
    <over_of_active       bg_color="#f0f0f0" />
  </style>
</tab_button>

<tab_button_group>
  <style name="default">
    <normal/>
  </style>
</tab_button_group>

4. 状态

tab_button在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
pressed	指针按下状态
over	指针悬浮状态
normal_of_active	正常状态(当前项)
pressed_of_active	指针按下状态(当前项)
over_of_active	指针悬浮状态(当前项)
disable	禁用状态
focused	聚焦状态

5. 事件

tab_button还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(激活状态)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(激活状态)改变事件。
EVT_CLICK	pointer_event_t	点击事件。

6. 示例

• 在xml中，使用"tab_button"标签创建标签控件，代码如下，其中使用的样式，详见上文样式一节。

<window anim_hint="htranslate" theme="tab_bottom_compact">
  <tab_control x="0" y="0" w="100%" h="100%" >
    <pages x="c" y="20" w="90%" h="-60" value="1">
      <view w="100%" h="100%">
        <label x="c" y="m" w="100%" h="60" text="General" />
        <button name="close" x="c" y="bottom:100" w="80" h="40" text="Close" />
      </view>
      <view w="100%" h="100%">
        <label x="c" y="m" w="100%" h="60" text="Network" />
        <button name="close" x="c" y="bottom:100" w="80" h="40" text="Close" />
      </view>
      <view w="100%" h="100%">
        <label x="c" y="m" w="100%" h="60" text="Security" />
        <button name="close" x="c" y="bottom:100" w="80" h="40" text="Close" />
      </view>
    </pages>
    <tab_button_group x="c" y="bottom:10" w="90%" h="30" compact="true" >
      <tab_button text="General"/>
      <tab_button text="Network" value="true" />
      <tab_button text="Security"/>
    </tab_button_group>
  </tab_control>
</window>

运行效果如下图所示：

图4.35 在xml中创建tab_button的效果

4.6.15 check_button

勾选控件。check_button_t是widget_t的子类控件，widget_t的函数均适用check_button_t控件。

使用该控件的时候需要将awtk/demos/assets/default/raw/images/x1目录下：unchecked.png和checked.png复制到自己的应用目录下（如：res/assets/default/raw/images/xx），否则将不能正常显示。

1. 函数

check_button提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
check_button_cast	转换check_button对象(供脚本语言使用)
check_button_create	创建多选按钮对象
check_button_set_value	设置控件的值

2. 属性

check_button还提供了下面属性，详见下表：

属性名称	类型	说明
value	bool_t	值

3. 样式

check_button可设置的样式，详见button一节的样式小节。check_button的样式示例，代码如下：

<!-- res/assets/default/raw/styles/default.xml -->
<check_button bg_color="#f0f0f0" text_color="black">
  <style name="default">
    <normal  icon="unchecked" />
    <pressed icon="unchecked" />
    <over    icon="unchecked" text_color="green"/>
    <normal_of_checked icon="checked" text_color="blue"/>
    <pressed_of_checked icon="checked" text_color="blue"/>
    <over_of_checked icon="checked" text_color="green"/>
  </style>
</check_button>

4. 状态

check_button在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
pressed	指针按下状态
over	指针悬浮状态
disable	禁用状态
normal_of_checked	正常状态(选中项)
pressed_of_checked	指针按下状态(选中项)
over_of_checked	指针悬浮状态(选中项)
focused	聚焦状态
focused_of_checked	焦点状态(选中项)

5. 事件

check_button还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	event_t	值（勾选状态）即将改变事件
EVT_VALUE_CHANGED	event_t	值（勾选状态）改变事件
EVT_CLICK	pointer_event_t	点击事件

6. 示例

• 在xml中，使用"check_button"标签创建勾选控件，代码如下，其中使用的样式，详见上文样式一节。

<window anim_hint="htranslate">
  <column x="20" y="160" w="50%" h="60" children_layout="default(r=2,c=1,ym=2,s=10)" >
    <check_button name="c1" text="Book"/>
    <check_button name="c2" text="Food"/>
  </column>
</window>

运行效果如下图所示：

图4.36 在xml中创建check_button的效果

• 在C代码中，使用函数check_button_create创建勾选控件，代码如下，其中使用的样式，详见上文样式一节。

ret_t application_init() {
  widget_t* check_button = NULL;
  widget_t* win = window_create(NULL, 0, 0, 0, 0);

  check_button = check_button_create(win, 10, 150, 80, 30);
  widget_set_text(check_button, L"Book");

  check_button = check_button_create(win, 100, 150, 80, 30);
  widget_set_text(check_button, L"Food");
  
  return RET_OK;
} 

运行效果如下图所示：

图4.37 在C代码中创建check_button的效果

4.6.16 radio_button

单选控件。radio_button_t是widget_t的子类控件，widget_t的函数均适用于radio_button_t控件。

使用该控件的时候需要将awtk/demos/assets/default/raw/images/x1目录下：radio_checked.png和radio_unchecked.png复制到自己的应用目录下（如：res/assets/default/raw/images/xx），否则将不能正常显示。

1. 函数

radio_button提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
check_button_cast	转换check_button对象(供脚本语言使用)
check_button_create_radio	创建单选按钮对象
check_button_get_checked_button	用于radio button获取同组中勾选的radio button
check_button_set_value	设置控件的值

2. 属性

radio_button还提供了下面属性，详见下表：

属性名称	类型	说明
value	bool_t	值

3. 样式

radio_button可设置的样式，详见button一节的样式小节。radio_button的样式示例，代码如下：

<!-- res/assets/default/raw/styles/default.xml -->
<radio_button>
  <style name="default" bg_color="#f0f0f0" text_color="black">
    <normal  icon="radio_unchecked" />
    <pressed icon="radio_unchecked" />
    <over    icon="radio_unchecked" text_color="green"/>
    <normal_of_checked icon="radio_checked" text_color="red"/>
    <pressed_of_checked icon="radio_checked" text_color="red"/>
    <over_of_checked icon="radio_checked" text_color="green"/>
  </style>
  <style name="left">
    <normal  icon="left_off" />
    <pressed icon="left_off" />
    <over    icon="left_off" />
    <normal_of_checked icon="left_on" />
    <pressed_of_checked icon="left_on" />
    <over_of_checked icon="left_on" />
  </style>
  <style name="middle">
    <normal  icon="middle_off" />
    <pressed icon="middle_off" />
    <over    icon="middle_off" />
    <normal_of_checked icon="middle_on" />
    <pressed_of_checked icon="middle_on" />
    <over_of_checked icon="middle_on" />
  </style>
  <style name="right">
    <normal  icon="right_off" />
    <pressed icon="right_off" />
    <over    icon="right_off" />
    <normal_of_checked icon="right_on" />
    <pressed_of_checked icon="right_on" />
    <over_of_checked icon="right_on" />
  </style>
</radio_button>

4. 事件

radio_button还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	event_t	值（勾选状态）即将改变事件
EVT_VALUE_CHANGED	event_t	值（勾选状态）改变事件
EVT_CLICK	pointer_event_t	点击事件

5. 示例

• 在xml中，使用"radio_button"标签创建单选控件，代码如下，其中使用的样式详见上文样式一节。

<window anim_hint="htranslate">
  <row x="c" y="m" w="100" h="30" children_layout="default(r=1,c=3)">
    <radio_button style="left"/>
    <radio_button style="middle"/>
    <radio_button style="right"/>
  </grid>
</window>

运行效果如下图所示：

图4.38 在xml中创建radio_button的效果

• 在C代码中，使用函数check_button_create_radio创建单选控件，代码如下：

ret_t application_init() {
  radio_button = check_button_create_radio(win, 10, 200, 80, 30);
  widget_set_tr_text(radio_button, "English");
  widget_set_value(radio_button, 1);

  radio_button = check_button_create_radio(win, 100, 200, 80, 30);
  widget_set_tr_text(radio_button, "Chinese");

  return RET_OK;
} 

运行效果如下所示：

图4.39 在C代码中创建radio_button的效果

4.6.17 dragger

dragger控件。dragger_t是widget_t的子类控件，widget_t的函数均适用于dragger_t控件。

1. 函数

dragger提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
dragger_create	创建dragger对象。
dragger_cast	转换为dragger对象(供脚本语言使用)。
dragger_set_range	设置拖动的范围。
dragger_get_widget_vtable	获取 dragger 虚表。

2. 属性

dragger还提供了下面属性，详见下表：

属性名称	类型	说明
x_min	xy_t	x坐标的最小值。
y_min	xy_t	y坐标的最小值。
x_max	xy_t	x坐标的最大值。
y_max	xy_t	y坐标的最大值。

3. 样式

dragger可设置的样式，详见button一节的样式小节。其实dragger的样式使用示例，代码如下：

<!-- res\assets\default\raw\styles\default.xml -->
<dragger>
  <style name="scroll_bar" >
    <normal     bg_color="#d0d0d0" />
    <pressed    bg_color="#c0c0c0" />
    <over       bg_color="#c0c0c0" />
  </style>
</dragger>

4. 状态

dragger在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
pressed	指针按下状态
over	指针悬浮状态
disable	禁用状态
focused	聚焦状态

5. 事件

dragger还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_DRAG_START	event_t	开始拖动事件。
EVT_DRAG	event_t	拖动事件。
EVT_DRAG_END	event_t	结束拖动事件。

6. 示例

• 在xml中使用"dragger"标签创建dragger控件，代码如下，其中使用的样式，

<window anim_hint="htranslate">
    <dragger style="scroll_bar" x="50" y="50" w="20" h="20" x_min="0" 
             x_max="200" y_min="0" y_max="200" />
  </window>

运行效果如下图所示，"dragger"控件可在指定范围内拖拽：

图4.40 在xml中创建dragger的效果

• 在C代码中使用"dragger_create"创建dragger控件，代码如下，使用的样式详见上文样式一节。

ret_t application_init() {
  widget_t* dragger = NULL;
  widget_t* win = window_create(NULL, 0, 0, 0, 0);
  dragger = dragger_create(win, 10, 200, 80, 30);
  dragger_set_range(dragger, 20, 20, 100, 100);
  widget_use_style(dragger, "scroll_bar");
  return RET_OK;
} 

运行效果如下图所示：

图4.41 在C代码中创建dragger的效果

4.6.18 digit_clock

数字时钟控件。digit_clock_t是widget_t的子类控件，widget_t的函数均适用于digit_clock_t控件。

1. 函数

digit_clock提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
digit_clock_create	创建digit_clock对象
digit_clock_cast	转换为digit_clock对象(供脚本语言使用)。
digit_clock_set_format	设置显示格式。
digit_clock_get_widget_vtable	获取 digit_clock 虚表。

2. 属性

digit_clock还提供了下面属性，详见下表：

属性名称	类型	说明
format	char*	显示格式。

format 属性的取值详见下表：

Format取值	说明
Y	代表年（完整显示）
M	代表月（1-12）
D	代表日（1-31）
h	代表时（0-23）
m	代表分（0-59）
s	代表秒（0-59）
w	代表星期（0-6）
W	代表星期的英文缩写（支持翻译）
YY	代表年（只显示末两位）
MM	代表月（01-12）
DD	代表日（01-31）
hh	代表时（00-23）
mm	代表分（00-59）
ss	代表秒（00-59）
MMM	代表月的英文缩写（支持翻译）

3. 样式

digit_clock可设置的样式，详见button一节的样式小节。样式设置代码如下：

<digit_clock>
  <style name="default" bg_color="gray" font_size="30" border_color="black">
    <normal text_color="green" />
  </style>
</digit_clock>

4. 星期和月份中英文互译

digit_clock控件中的星期和月份默认是英文显示的，如果要显示中文，如："2019/10/12 星期六18:30"，步骤如下：

(1) 在UI文件中创建digit_clock控件，代码如下：

<digit_clock  x="c" y="3.3%" w="100%" h="3.5%" format="YYYY/MM/DD W h:mm" />

(2) 然后，参考8.3章节的内容，在strings.xml中添加星期或者月份的中英文互译，代码如下：

<!-- assets/default/raw/strings/strings.xml -->
...
<string name="Mon">
    <language name="en_US">Mon</language>
    <language name="zh_CN">星期一</language>
</string>
<string name="Tues">
    <language name="en_US">Tues</language>
    <language name="zh_CN">星期二</language>
</string>
<string name="Wed">
    <language name="en_US">Wed</language>
    <language name="zh_CN">星期三</language>
</string>
<string name="Thur">
    <language name="en_US">Thur</language>
    <language name="zh_CN">星期四</language>
</string>
<string name="Fri">
    <language name="en_US">Fri</language>
    <language name="zh_CN">星期五</language>
</string>
<string name="Sat">
    <language name="en_US">Sat</language>
    <language name="zh_CN">星期六</language>
</string>
<string name="Sun">
    <language name="en_US">Sun</language>
    <language name="zh_CN">星期日</language>
</string>
<string name="Jan">
    <language name="en_US">Jan</language>
    <language name="zh_CN">1月</language>
</string>
<string name="Feb">
    <language name="en_US">Feb</language>
    <language name="zh_CN">2月</language>
</string>
<string name="Mar">
    <language name="en_US">Mar</language>
    <language name="zh_CN">3月</language>
</string>
<string name="Apr">
    <language name="en_US">Apr</language>
    <language name="zh_CN">4月</language>
</string>
...
<string name="Sept">
    <language name="en_US">Sept</language>
    <language name="zh_CN">9月</language>
</string>
<string name="Oct">
    <language name="en_US">Oct</language>
    <language name="zh_CN">10月</language>
</string>
<string name="Nov">
    <language name="en_US">Nov</language>
    <language name="zh_CN">11月</language>
</string>
<string name="Dec">
    <language name="en_US">Dec</language>
    <language name="zh_CN">12月</language>
</string>

5. 示例

• 在xml中，使用"digit_clock"标签创建数字时钟控件，代码如下，样式设置见上文第三小节。

<!-- awtk/demos/assets/default/raw/ui/digit_clock.xml -->
<window anim_hint="htranslate" children_layout="default(c=1,h=30,s=10)">
  <digit_clock format="h:m" />
  <digit_clock format="hh:mm" />
  <digit_clock format="h:m:s"/>
  <digit_clock format="hh:mm:ss"/>
  <digit_clock format="Y/M/D"/>
  <digit_clock format="YY-MM-DD"/>
  <digit_clock format="Y/M/D h:mm:ss"/>
  <digit_clock format="YY/MM/DD h:mm:ss"/>
</window>

运行效果如下图所示：

图4.42 在xml中创建digit_clock的效果

• 在C代码中，使用函数digit_clock_create创建数字时钟控件，代码如下，样式设置见上文第三小节。

widget_t* tc = digit_clock_create(win, 10, 10, 240, 30);
digit_clock_set_format(tc, "YY/MM/DD h:mm:ss"); 

图4.43 在C中创建digit_clock的效果

4.7 通用容器控件

常用的通用容器控件详见下表：

控件名称	说明
row	行控件
column	列控件
grid	网格控件
view	通用容器控件
clip_view	裁剪子控件的容器控件
grid_item	网格项控件
group_box	通用分组控件
app_bar	app_bar控件
pages	页面管理控件
button_group	按钮分组控件
tab_button_group	标签按钮分组控件

容器可以设置的样式详见下表：

样式属性	说明
bg_color	背景颜色
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

其中group_box和button_group可以设置的样式详见下表：

样式属性	说明
bg_color	背景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
icon	图标的名称
spacer	间距
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
icon_at	图标的位置（取值：top|bottom|left|right）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

通用容器控件在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
disable	禁用状态
focused	聚焦状态

4.7.1 row

row。一个简单的容器控件，用于水平排列其子控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。row_t是widget_t的子类控件，widget_t的函数均适用于row_t控件。

1. 函数

row提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
row_create	创建row对象
row_cast	转换为row对象(供脚本语言使用)。
row_get_widget_vtable	获取 row 虚表。

2. 示例

• 在xml中，使用"row"标签创建行容器，代码如下：

<!-- awtk/demos/assets/default/raw/ui/basic.xml -->
<window anim_hint="htranslate">
  ...
  <row x="0" y="40" w="100%" h="30" children_layout="default(r=1,c=3,xm=2,s=10)">
    <button name="inc_value" text="Inc"/>
    <button name="close" text="Close"/>
    <button name="dec_value" text="Dec"/>
  </row>
  ...
</window>

4.7.2 column

column。一个简单的容器控件，垂直排列其子控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。column_t是widget_t的子类控件，widget_t的函数均适用于column_t控件。

1. 函数

column提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
column_create	创建column对象
column_cast	转换为column对象(供脚本语言使用)。
column_get_widget_vtable	获取 column 虚表。

2. 示例

• 在xml中，使用"column"标签创建列容器，代码如下：

<!-- awtk/demos/assets/default/raw/ui/basic.xml -->
<window anim_hint="htranslate">
  ...
  <column x="20" y="230" w="50%" h="90" children_layout="default(r=3,c=1,ym=2,s=10)" >
    <radio_button name="r1" text="Book"/>
    <radio_button name="r2" text="Food"/>
    <radio_button name="r3" text="Pencil" value="true"/>
  </column>
  ...
</window>

4.7.3 grid

grid控件。一个简单的容器控件，用于网格排列一组控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。grid_t是widget_t的子类控件，widget_t的函数均适用于grid_t控件。

1. 函数

grid提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
grid_create	创建grid对象
grid_cast	转换为grid对象(供脚本语言使用)。
grid_set_rows	设置 行数。
grid_set_columns_definition	设置 各列的参数。
grid_set_show_grid	设置 是否显示网格。
grid_get_widget_vtable	获取 grid 虚表。

2. 属性

grid还提供了下面属性，详见下表：

属性名称	类型	说明
rows	uint32_t	行数。
columns_definition	char*	各列的参数。
show_grid	bool_t	是否显示网格。

3. 示例

• 在xml中，使用"grid"标签创建网格容器，代码如下：

<!-- awtk/demos/assets/default/raw/ui/basic.xml -->
<window anim_hint="htranslate">
  ...
  <grid x="20" y="bottom:10" w="80%" h="40" children_layout="default(r=1,c=5,x=2,s=10)">
    <image draw_type="icon" image="earth"/>
    <image draw_type="icon" image="rgba" />
    <image draw_type="icon" image="rgb" />
    <image draw_type="icon" image="message"/>
    <image draw_type="icon" image="red_btn_n"/>
  </grid>
</window>

4.7.4 view

一个通用的容器控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。view_t是widget_t的子类控件，widget_t的函数均适用于view_t控件。

1. 函数

view提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
view_create	创建view对象
view_set_default_focused_child	设置缺省获得焦点的子控件(可用控件名或类型)。
view_cast	转换为view对象(供脚本语言使用)。

2. 属性

view还提供了下面属性，详见下表：

属性名称	类型	说明
default_focused_child	char*	缺省获得焦点的子控件(可用控件名或类型)。

3.示例

• 在xml中，使用"view"标签创建view容器，代码如下：

<!-- awtk/demos/assets/default/raw/ui/basic.xml -->
<window anim_hint="htranslate">
  ...
  <view x="0" y="40" w="100%" h="30" children_layout="default(r=1,c=3,xm=2,s=10)">
    <button name="inc_value" text="Inc"/>
    <button name="close" text="Close"/>
    <button name="dec_value" text="Dec"/>
  </view>
  ...
</window>

4.7.5 clip_view

一个裁剪子控件的容器控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。在clip_view控件下的所有子控件都会被裁剪，无法画超出clip_view控件所在范围。clip_view_t是widget_t的子类控件，widget_t的函数均适用于clip_view_t控件。

1. 函数

clip_view提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
clip_view_create	创建clip_view对象
clip_view_cast	转换为clip_view对象(供脚本语言使用)。

2. 示例

• 在xml中，使用"clip_view"标签创建clip_view容器，代码如下：

<window anim_hint="htranslate">
  ...
  <clip_view x="0" y="0" w="100" h="100">
    <button x="50" y="10" w="100" h="50" />  
  </clip_view>
  ...
</window>

4.7.6 grid_item

grid_item。一个简单的容器控件，一般作为grid的子控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。grid_item_t是widget_t的子类控件，widget_t的函数均适用于grid_item_t控件。

1. 函数

grid_item提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
grid_item_create	创建grid_item对象
grid_item_cast	转换为grid_item对象(供脚本语言使用)。
grid_item_get_widget_vtable	获取 grid_item 虚表。

2. 示例

• 在xml中，使用"grid_item"标签创建grid_item容器，代码如下：

<grid x="0" y="0" w="100%" h="100%" children_layout="default(c=2,r=2,m=5,s=5)">
    <grid_item>
        <button x="c" y="m" w="80%" h="30" name="0" text="0"/>
    </grid_item>
    <grid_item>
        <button x="c" y="m" w="80%" h="30" name="1" text="1"/>
    </grid_item>
    <grid_item>
        <button x="c" y="m" w="80%" h="30" name="2" text="2"/>
    </grid_item>
    <grid_item>
        <button x="c" y="m" w="80%" h="30" name="3" text="3"/>
    </grid_item>
</grid>

4.7.7 group_box

分组控件。单选按钮在同一个父控件中是互斥的，所以通常将相关的单选按钮放在一个group_box中。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。group_box_t是widget_t的子类控件，widget_t的函数均适用于group_box_t控件。

1. 函数

group_box提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
group_box_create	创建group_box对象
group_box_cast	转换为group_box对象(供脚本语言使用)。
group_box_get_widget_vtable	获取 group_box 虚表。

2. 示例

• 在xml中，使用"group_box"标签创建分组容器，代码如下：

<group_box x="20" y="230" w="50%" h="90" children_layout="default(r=3,c=1,ym=2,s=10)">
    <radio_button name="r1" text="Book"/>
    <radio_button name="r2" text="Food"/>
    <radio_button name="r3" text="Pencil" value="true"/>
</group_box>

4.7.8 app_bar

app_bar控件。一个简单的容器控件，一般在窗口的顶部，用于显示本窗口的状态和信息。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。app_bar_t是widget_t的子类控件，widget_t的函数均适用于app_bar_t控件。

1. 函数

app_bar提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
app_bar_create	创建app_bar对象
app_bar_cast	转换为app_bar对象(供脚本语言使用)。
app_bar_get_widget_vtable	获取 app_bar 虚表。

2. 示例

• 在xml中，使用"app_bar"标签创建app_bar容器，代码如下：

<!-- awtk/demos/assets/default/raw/ui/basic.xml -->
<window anim_hint="htranslate">
  <app_bar x="0" y="0" w="100%" h="30" >
    <label x="0" y="0" w="100%" h="100%" text="Basic Controls" />
  </app_bar>
  ...
</window>

4.7.9 pages

页面管理控件。只有一个Page处于active状态，处于active状态的Page才能显示并接收事件。常用于实现标签控件中的页面管理。pages_t是widget_t的子类控件，widget_t的函数均适用于pages_t控件。

1. 函数

pages提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
pages_create	创建pages对象
pages_cast	转换为pages对象(供脚本语言使用)。
pages_set_active	设置当前的Page。
pages_set_auto_focused	设置切换界面时是否自动聚焦。
pages_set_active_by_name	通过页面的名字设置当前的Page。
pages_get_widget_vtable	获取 pages 虚表。

2. 属性

pages还提供了下面属性，详见下表：

属性名称	类型	说明
active	uint32_t	当前活跃的page。(需要用到 MVVM 数据绑定请设置 value 属性)
auto_focused	bool_t	选择切换界面时是否自动聚焦上一次保存的焦点。（默认为TRUE）
value	uint32_t	当前活跃的page。

3. 事件

pages还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(当前页)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(当前页)改变事件。

4. 示例

• 在xml中，使用"pages"标签创建pages容器，代码如下：

<!-- awtk/design/default/ui/tab_top_compact.xml -->
<window anim_hint="htranslate">
  ...
  <pages x="c" y="41" w="90%" h="-60" value="1">
    <view w="100%" h="100%">
      <label x="c" y="m" w="100%" h="60" text="General" /> 
      <button name="close" x="c" y="bottom:100" w="80" h="40" text="Close" />
    </view>
    <view w="100%" h="100%">
      <label x="c" y="m" w="100%" h="60" text="Network" /> 
      <button name="close" x="c" y="bottom:100" w="80" h="40" text="Close" />
    </view>
    <view w="100%" h="100%">
      <label x="c" y="m" w="100%" h="60" text="Security" /> 
      <button name="close" x="c" y="bottom:100" w="80" h="40" text="Close" />
    </view>
  </pages>
  ...
</window>

4.7.10 button_group

button group控件。一个简单的容器控件，用于容纳一组按钮控件。它本身不提供布局功能，仅提供具有语义的标签，让xml更具有可读性。button_group_t是widget_t的子类控件，widget_t的函数均适用于button_group_t控件。

1. 函数

button_group提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
button_group_create	创建button_group对象
button_group_cast	转换为button_group对象(供脚本语言使用)。
button_group_get_widget_vtable	获取 button_group 虚表。

2. 示例

• 在xml中，使用"button_group"标签创建button_group容器，代码如下：

<button_group x="0" y="m" w="100%" h="40" children_layout="default(c=4,r=1,s=5,m=5)">
    <button name="open:basic" text="Basic"/>
    <button name="open:button" text="Buttons"/>
    <button name="open:edit" text="Edits"/>
    <button name="open:keyboard" text="KeyBoard"/>
</button_group>

4.7.11 tab_button_group

标签按钮分组控件。一个简单的容器，主要用于对标签按钮进行布局和管理。tab_button_group_t是widget_t的子类控件，widget_t的函数均适用于tab_button_group_t控件。

在下图中右侧表示当前标签页的颜色取的是fg_color，非当前标签页取的是border_color，样式代码如下：

图4.44 tab_top

<!-- awtk/demos/assets/default/raw/styles/tab_top.xml -->
<tab_button_group>
  <style name="highlight" border_color="#a0a0a0" fg_color="#1296db">
    <normal/>
  </style>
</tab_button_group>

<tab_button>
  <style name="default" margin="4" bg_color="#eeeeee">
    <normal     text_color="black"/>
    <pressed    text_color="black"/>
    <over       text_color="black"/>
    <normal_of_active     text_color="#1296db"/>
    <pressed_of_active    text_color="#1296db"/>
    <over_of_active       text_color="#1296db"/>
  </style>
</tab_button>

<pages>
  <style name="at_top" border_color="#a0a0a0" border="bottom">
    <normal />
  </style>
</pages>

1. 函数

tab_button_group提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
tab_button_group_create	创建tab_button_group对象
tab_button_group_set_compact	设置compact。
tab_button_group_set_scrollable	设置scrollable。
tab_button_group_cast	转换tab_button_group对象(供脚本语言使用)。
tab_button_group_get_widget_vtable	获取 tab_button_group 虚表。

2. 属性

tab_button_group还提供了下面属性，详见下表：

属性名称	类型	说明
compact	bool_t	紧凑型排版子控件(缺省FALSE)。
scrollable	bool_t	是否支持滚动(缺省FALSE)。
enable_hscroll_animator	bool_t	是否开启 tab_button 的左右滚动动画(缺省TRUE)。

3. 示例

• 在xml中，使用"tab_button_group"标签创建tab_button_group容器，代码如下：

<tab_button_group x="c" y="bottom:10" w="90%" h="30" compact="true" >
  <tab_button text="General"/>
  <tab_button text="Network" value="true" />
  <tab_button text="Security"/>
</tab_button_group>

4.8 扩展控件

在AWTK中提供了两种类型的控件：内置控件和扩展控件，其中内置控件包括窗口、基本控件和通用容器。AWTK默认加入扩展控件，如果不需要则可以定义宏 WITHOUT_EXT_WIDGETS。

常见的扩展控件详见下表：

控件名称	说明
canvas_widget	画布控件
color_picker	颜色选择器控件
color_component	颜色选择器的颜色分量
combo_box_ex	扩展combo_box控件
draggable	draggable控件
gif_image	gif_image控件
gauge	仪表控件
gauge_pointer	仪表指针控件
image_animation	图片动画控件
image_value	图片值控件
keyboard	软键盘控件
candidates	输入法候选者字词控件
lang_indicator	输入法语言指示器
progress_circle	进度圆环控件
rich_text	图文混排控件
slide_menu	左右滑动菜单控件
slide_view	滑动视图控件
svg_image	SVG图片控件
switch	开关控件
text_selector	文本选择器控件
time_clock	模拟时钟控件
digit_clock	数字时钟控件
list_view	列表视图控件
list_view_h	水平列表视图控件
list_item	列表项控件
list_item_seperator	属性页分组控件
scroll_bar	滚动条控件
scroll_view	滚动视图控件
mutable_image	mutable图片控件（用于辅助实现camera/video）
mledit	多行编辑器控件
line_number	多行编辑器的行号控件
slide_indicator	滑动视图的指示器控件
hscroll_label	可水平滚动的文本
serial_widget	用于串口通信的控件
timer_widget	定时器控件
vpage	虚拟页面

4.8.1 canvas_widget

画布控件。画布控件让开发者可以自己在控件上绘制需要的内容。canvas_widget_t是widget_t的子类控件，widget_t的函数均适用于canvas_widget_t控件。

1. 函数

canvas_widget提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
canvas_widget_create	创建canvas_widget对象
canvas_widget_cast	转换为canvas_widget对象(供脚本语言使用)。
canvas_widget_get_widget_vtable	获取 canvas_widget 虚表。

2. 样式

canvas_widget可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

• canvas样式应用示例见以下代码，效果如下图所示：

<canvas>
<style name="default" border_color="black" border_width="3" border="all" >
<normal  bg_color="gray" />
<disable  bg_color="gray" round_radius="6" x_offset="3" y_offset="3"/>
<focused  bg_color="gray" bg_image_draw_type="center" bg_image="1"/>
</style>
</canvas>

图4.45 canvas样式效果

3. 状态

canvas_widget在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
disable	禁用状态
focused	聚焦状态

4. 示例

• 在xml中，使用"canvas_widget"标签创建画布控件，代码如下，控件样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/vgcanvas.xml -->
<window anim_hint="htranslate">
  <canvas name="paint_vgcanvas" x="0" y="0" w="100%" h="100%" />
</window>

运行效果如下图所示：

图4.46 在xml中创建canvas的效果

• 在C代码中，使用函数canvas_widget_create创建画布控件，代码如下，控件样式设置见上文样式一节。

/* awtk/demos/demo_vg_app.c */
ret_t application_init() {
  widget_t* win = window_create(NULL, 0, 0, 0, 0);
  widget_t* canvas = canvas_widget_create(win, 0, 0, win->w, win->h);

  // widget_on(canvas, EVT_PAINT, on_paint_vg_simple, NULL);
  widget_on(canvas, EVT_PAINT, on_paint_vg, NULL);

  timer_add(on_timer, win, 500);

  return RET_OK;
}

创建之后，需要用widget_on注册EVT_PAINT事件，并在EVT_PAINT事件处理函数中绘制，运行效果如下图所示：

图4.47 在C中创建canvas的效果

4.8.2 color_picker

颜色选择器。color_picker_t是widget_t的子类控件，widget_t函数均适用于color_picker_t控件。

1. 函数

color_picker提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
color_picker_create	创建color_picker对象
color_picker_set_color	设置颜色。
color_picker_cast	转换为color_picker对象(供脚本语言使用)。
color_picker_get_widget_vtable	获取 color_picker 虚表。

2. 属性

color_picker还提供了下面属性，详见下表：

属性名称	类型	说明
value	char*	颜色。

3. 样式

color_picker可设置的样式，详见canvas_widget一节的样式小节。color_picker控件样式设置示例代码如下：

<style name="default" border_color="black" border_width="3" border="all" >
  <normal  bg_color="gray" />
  <disable  bg_color="gray" round_radius="6" x_offset="3" y_offset="3"/>
  <focused  bg_color="gray" bg_image_draw_type="center" bg_image="1"/>
</style>

运行效果如下图所示：

图4.48 color_picker样式效果

4. 事件

color_picker还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(颜色)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(颜色)改变事件。

5. 示例

• 在xml中，使用"color_picker"标签创建颜色选择器控件，代码如下，样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/color_picker_full.xml -->
<window>
  <color_picker x="0" y="0" w="100%" h="100%" value="orange">
   <color_component x="0" y="0" w="200" h="200" name="sv"/>
   <color_component x="210" y="0" w="20" h="200" name="h"/>
   <color_tile x="0" y="210" w="50%" h="20" name="new" bg_color="green"/>
   <color_tile x="right" y="210" w="50%" h="20" name="old" bg_color="blue"/>
  </color_picker>
  <button name="close" x="center" y="bottom:5" w="25%" h="50" text="Close"/>
</window>

运行效果如下图所示：

图4.49 在xml中创建color_picker及子控件的效果

其中的子控件的name必须按规则命名，详见下表：

取值	说明
r	红色分量可以是spin_box、edit和slider
g	绿色分量可以是spin_box、edit和slider
b	蓝色分量可以是spin_box、edit和slider
h	Hue分量可以是spin_box、edit、slider和color_component
s	Saturation分量可以是spin_box、edit和slider
v	Value/Brightness分量可以是spin_box、edit和slider
sv	Saturation和Value/Brightness分量可以是color_component
old	旧的值可以是spin_box、edit和color_tile
new	新的值可以是spin_box、edit和color_tile

以上面取值"r"为例，表示name="r"可以在spin_box、edit和slider这几个控件上使用，代码如下，控件样式设置见上文样式一节。

<color_picker name="c" x="0" y="0" w="100%" h="100%" value="orange">
	<color_tile name="new" x="0"  y="210" w="50%" h="20"/>
	<color_tile name="old" x="right" y="210" w="50%" h="20"/>
	<edit name="new" x="0"     y="240" w="50%" h="30"  input_type="hex"/>
	<edit name="old" x="right" y="240" w="50%" h="30"  readonly="true"/>
	<color_component name="sv" x="0"  y="0" w="200" h="200" />
	<color_component name="h" x="210" y="0" w="20"  h="200" />
	
	<view x="0" y="300" w="100%" h="90" children_layout="default( r=3,c=3,s=2)">
		<label    name="r" x="0" y="middle" w="100%" h="100%" text="r"/>
		<spin_box name="r" x="0" y="middle" w="100%" h="100%" min="0" input_type="int" max="255"
         step="1" auto_fix="true"  />
		<slider   name="r" x="0" y="middle" w="100%" h="20"  />
		
		<label    name="g" x="0" y="middle" w="100%" h="100%" text="g"/>
		<spin_box name="g" x="0" y="middle" w="100%" h="100%" min="0" input_type="int" max="255"
         step="1" auto_fix="true"  />
		<slider   name="g" x="0" y="middle" w="100%" h="20"/>
		
		<label    name="b" x="0" y="middle" w="100%" h="100%" text="b"/>
		<spin_box name="b" x="0" y="middle" w="100%" h="100%" min="0" input_type="int" max="255"
         step="1" auto_fix="true"  />
		<slider   name="b" x="0" y="middle" w="100%" h="20"  />
	</view>
</color_picker>

运行效果如下图所示：

图4.50 color_picker_rgb运行效果

4.8.3 color_component

颜色选择器的颜色分量。控件名称的命名规则可以查看color_picker控件中的示例。color_component_t是widget_t的子类控件，widget_t函数均适用于color_component_t控件。

1. 函数

color_component提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
color_component_create	创建color_component对象
color_component_set_color	设置颜色。
color_component_set_hsv	设置颜色。
color_component_get_h	获取h分量。
color_component_get_s	获取s分量。
color_component_get_v	获取v分量。
color_component_cast	转换为color_component对象(供脚本语言使用)。
color_component_get_widget_vtable	获取 color_component 虚表。

2. 事件

color_component还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_CHANGING	value_change_event_t	颜色正在改变事件。

3. 示例

• 在xml中，使用"color_component"标签创建color_component控件，代码如下。

<color_picker name="c" x="0" y="0" w="100%" h="100%" value="orange">
  ...
	<color_component name="sv" x="0"  y="0" w="200" h="200" />
	<color_component name="h" x="210" y="0" w="20"  h="200" />
  ...
</color_picker>

4.8.4 combo_box_ex

扩展combo_box控件。支持以下功能：

1. 支持滚动。项目比较多时显示滚动条。
2. 自动调整弹出窗口的宽度。根据最长文本自动调整弹出窗口的宽度。
3. 支持分组显示。如果item的文本以"seperator."开头，视为一个分组开始，其后的文本为分组的标题。比如: "seperator.basic"，会创建一个basic为标题的分组。 combo_box_ex_t是combo_box_t的子类控件，combo_box_t函数均适用于combo_box_ex_t控件。

1. 函数

combo_box_ex提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
combo_box_ex_create	创建combo_box_ex对象

2. 示例

<!-- awtk/design/default/ui/combo_box.xml -->
<window anim_hint="htranslate">
  ...
  <combo_box_ex x="10" y="100" w="200" h="30" options="1;2;3;4;5;6;7;8;9;0;11;22;33;44;55" theme_of_popup="number"/>
  <combo_box_ex x="0" y="middle:-60" w="100" h="30" options="seperator.basic;33;44;55;seperator.user;hello;world;it is long option" text="33" readonly="true"/>
  <combo_box_ex name="combo_box_ex_for_clone" readonly="true" x="0" y="middle:100" w="100" h="30" options="1;2;3;4;5;6;7;8" theme_of_popup="number"/>
  ...
</window>

4.8.5 gif_image

GIF图片控件。需要注意的是GIF图片的尺寸大于控件大小时会自动缩小图片，但一般的嵌入式系统的硬件加速都不支持图片缩放，所以缩放图片会导致性能明显下降。如果性能不满意时，请确认一下GIF图片的尺寸是否小余控件大小。gif_image_t是image_base_t的子类控件，image_base_t的函数均适用于gif_image_t控件。

1. 函数

gif_image提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
gif_image_create	创建gif_image对象
gif_image_play	播放。
gif_image_stop	停止(并重置index为0)。
gif_image_pause	暂停。
gif_image_set_loop	设置循环播放次数。
gif_image_cast	转换为gif_image对象(供脚本语言使用)。
gif_image_get_widget_vtable	获取 gif_image 虚表。

2. 属性

gif_image还提供了下面属性，详见下表：

属性名称	类型	说明
running	bool_t	是否正在运行。
loop	uint32_t	循环播放的次数。

3. 示例

• 在xml中，使用"gif_image"标签创建GIF图片控件，代码如下：

<!-- awtk\demos\assets\default\raw\ui\gif_image.xml -->
<window anim_hint="htranslate">
  <view x="0" y="0" w="100%" h="-60" children_layout="default(c=2,r=2)">
    <gif image="bee"/>
    <gif image="bee"/>
    <gif image="bee"/>
    <gif image="bee"/>
  </view>
</window>

4.8.6 gauge

表盘控件。表盘控件就是一张图片。gauge_t是widget_t的子类控件，widget_t的函数均适用于gauge_t控件。

1. 函数

gauge提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
gauge_create	创建gauge对象
gauge_cast	转换为gauge对象(供脚本语言使用)。
gauge_set_image	设置背景图片的名称。
gauge_set_draw_type	设置图片的显示方式。
gauge_get_widget_vtable	获取 gauge 虚表。

2. 属性

gauge还提供了下面属性，详见下表：

属性名称	类型	说明
image	char*	背景图片。
draw_type	image_draw_type_t	图片的绘制方式。

3. 样式

gauge可设置的样式，详见canvas_widget一节的样式小节。样式设置示例代码如下：

<guage>
  <style name="default" border_color="black" border_width="3" border="all">
    <normal  bg_color="gray" />
	<disable  bg_color="gray" round_radius="6" x_offset="3" y_offset="3"/>
	<focused  bg_color="gray" bg_image_draw_type="center" bg_image="1"/>
  </style>
</guage>

运行效果如下图所示：

图4.51 gauge样式设置效果

4. 示例

• 在xml中，使用"gauge"标签创建表盘控件，代码如下：

<!-- awtk/demos/assets/default/raw/ui/guage.xml -->
<window style="dark" anim_hint="htranslate" >
  <guage x="c" y="10" w="240" h="240" image="guage_bg" >
    <gauge_pointer x="c" y="50" w="24" h="140" value="-128" image="gauge_pointer" 
        animation="value(from=-128, to=128, yoyo_times=1000, duration=3000, delay=1000)"/>
  </guage>
  <button name="close" x="center" y="bottom:10" w="25%" h="30" text="Close"/>
</window>

运行效果如下图所示：

图4.52 在xml中创建gauge的效果

• 在C代码中，使用gauge_create创建表盘控件，代码如下：

widget_t* guage = guage_create(win, 10, 10, 200, 200);
guage_set_image(guage, "guage_bg");

运行效果见如下图所示：

图4.53 在C中创建gauge的效果

4.8.7 gauge_pointer

仪表指针控件。仪表指针就是一张旋转的图片，图片可以是普通图片也可以是SVG图片。在嵌入式平台上对于旋转图片，SVG图片的效率比位图高数倍，所以推荐使用SVG图片。gauge_pointer_t是widget_t的子类控件，widget_t的函数均适用于gauge_pointer_t控件。

1. 函数

gauge_pointer提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
gauge_pointer_create	创建gauge_pointer对象
gauge_pointer_cast	转换为gauge_pointer对象(供脚本语言使用)。
gauge_pointer_set_angle	设置指针角度。12点钟方向为0度，顺时钟方向为正，单位为度。
gauge_pointer_set_image	设置指针的图片。
gauge_pointer_set_anchor	设置指针的旋转锚点。
gauge_pointer_get_widget_vtable	获取 gauge_pointer 虚表。

2. 属性

gauge_pointer还提供了下面属性，详见下表：

属性名称	类型	说明
angle	float_t	指针角度。12点钟方向为0度，顺时钟方向为正，单位为度。
image	char*	指针图片。
anchor_x	char*	图片旋转锚点x坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)
anchor_y	char*	图片旋转锚点x坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)

3. 样式

gauge_pointer可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
border_color	边框颜色
border_width	边框线宽
Border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
fg_color	前景颜色
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

4. 事件

gauge_pointer还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(角度)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(角度)改变事件。

5. 示例

• 在xml中，使用"gauge_pointer"标签创建仪表指针控件，代码如下：

<window style="dark" anim_hint="htranslate" >
  <guage x="c" y="10" w="240" h="240" image="guage_bg" >
    <gauge_pointer x="c" y="50" w="24" h="140" value="-128" image="gauge_pointer" 
        animation="value(from=-128, to=128, yoyo_times=1000, duration=3000, delay=1000)"/>
  </guage>
  <button name="close" x="center" y="bottom:10" w="25%" h="30" text="Close"/>
</window>

运行效果如下图所示：

图4.54 在xml中创建gauge_pointer的效果

• 在C代码中，使用gauge_pointer_create创建仪表指针控件，代码如下：

widget_t* gauge_pointer = gauge_pointer_create(guage, 10, 10, 100, 30);
gauge_pointer_set_image(gauge_pointer, "gauge_pointer");

创建之后，需要用gauge_pointer_set_image设置仪表指针图片。

4.8.8 image_animation

图片动画控件，指定一个图片前缀，依次显示指定序列的图片，从而形成动画效果。image_animation_t是widget_t的子类控件，widget_t的函数均适用于image_animation_t控件。

1. 函数

image_animation提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
image_animation_create	创建image_animation对象
image_animation_set_loop	设置是否循环播放。
image_animation_set_image	设置图片前缀。
image_animation_set_interval	设置播放间隔时间。
image_animation_set_delay	设置延迟播放时间(仅适用于自动播放)。
image_animation_set_auto_play	设置是否自动播放。
image_animation_set_sequence	设置播放序列。比如image为"fire"，sequence为"12223", 将依次播放"fire1", "fire2", "fire2", "fire2","fire3"。
image_animation_set_range_sequence	设置播放序列。比如image为"fire"，start_index为0, end_index为99, 将依次播放"fire0", ...,"fire99"。
image_animation_play	播放。
image_animation_stop	停止(并重置index为-1)。
image_animation_pause	暂停。
image_animation_next	手动切换到下一张图片。
image_animation_set_format	设置生成图片名的格式。
image_animation_set_unload_after_paint	设置绘制完成后unload图片，以释放内存空间。
image_animation_set_reverse	设置是否倒序播放。
image_animation_set_show_when_done	设置结束播放后是否保持显示最后一帧。
image_animation_cast	转换为image_animation对象(供脚本语言使用)。
image_animation_is_playing	判断是否在播放。
image_animation_get_widget_vtable	获取 image_animation 虚表。

2. 属性

image_animation还提供了下面属性，详见下表：

属性名称	类型	说明
image	char*	图片名称的前缀。
sequence	char*	播放的序列，字符可选值为数字和英文大小写字母，字符可以重复。如：0123456789或者123123abcd。
start_index	uint32_t	图片起始序数。
end_index	uint32_t	图片结束序数。
reverse	bool_t	是否倒序播放。
loop	bool_t	是否循环播放。
auto_play	bool_t	是否自动播放。
unload_after_paint	bool_t	绘制完成后unload图片，以释放内存空间。
format	char*	索引到图片名转换时的格式，缺省为"%s%d"。
interval	uint32_t	每张图片播放的时间(毫秒)。
delay	uint32_t	自动播放时延迟播放的时间(毫秒)。
show_when_done	bool_t	结束后是否继续显示最后一帧。

3. 样式

image_animation可设置的样式，详见canvas_widget一节的样式小节。样式设置代码如下：

<image_animation>
  <style name="default" border_color="black" border_width="3" border="all" >
    <normal  bg_color="gray" />
	<disable  bg_color="gray" round_radius="6" x_offset="3" y_offset="3"/>
	<focused  bg_color="gray" bg_image_draw_type="center" bg_image="1"/>
  </style>
</image_animation>

运行效果如下图所示：

图4.55 image_animation样式设置效果

4. 事件

image_animation还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_ANIM_ONCE	event_t	使能循环播放时，控件动画完成一次事件。
EVT_ANIM_END	event_t	控件动画完成事件。

5. 示例

• 在xml中，使用"image_animation"标签创建图片动画控件，代码如下，其中样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/image_animation.xml -->
<window anim_hint="htranslate">
  ...
    <image_animation image="ani" sequence="123456789abc" auto_play="true" interval="50" delay="100"/>
    <image_animation image="ani" sequence="123456789abc" auto_play="true" interval="50" delay="200"/>
    ......
  <button name="close" x="center" y="bottom:50" w="50%" h="50" text="close"/>
</window>

运行效果如下图所示：

图4.56 在xml中创建image_animation的效果

• 在C代码中，使用image_animation_create创建图片动画控件，代码如下，其中的样式设置见上文样式一节。

image_animation = image_animation_create(win, 10, 10, 200, 200);
image_animation_set_image(image_animation, "ani");
image_animation_set_interval(image_animation, 50);
image_animation_set_sequence(image_animation, "123456789abc");
image_animation_play(image_animation);

运行效果如下图所示：

图4.57 在C中创建image_animation的效果

4.8.9 image_value

图片值控件。可以用图片来表示如电池电量、WIFI信号强度和其它各种数值的值。image_value_t是widget_t的子类控件，widget_t的函数均适用于image_value_t控件。其原理如下：

1. 把value以format为格式转换成字符串。
2. 把每个字符与image（图片文件名前缀）映射成一个图片名。
3. 最后把这些图片显示出来。

1. 函数

image_value提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
image_value_create	创建image_value对象
image_value_set_image	设置图片前缀。
image_value_set_format	设置格式。
image_value_set_click_add_delta	设置点击时加上的增量。
image_value_set_value	设置值。
image_value_set_min	设置最小值。
image_value_set_max	设置最大值。
image_value_cast	转换为image_value对象(供脚本语言使用)。
image_value_get_widget_vtable	获取 image_value 虚表。

2. 属性

image_value还提供了下面属性，详见下表：

属性名称	类型	说明
image	char*	图片名称的前缀。
format	char*	数值到字符串转换时的格式，缺省为"%d"。
click_add_delta	double	点击时加上一个增量。
value	double	值。
min	double	最小值(如果设置了click_add_delta，到达最小值后回到最大值)。
max	double	最大值(如果设置了click_add_delta，到达最大值后回到最小值)。

3. 样式

image_value可设置的样式，详见canvas_widget一节的样式小节。image_value样式设置代码如下：

<image_value>
  <style name="default" border_color="black" border_width="3" border="all" >
    <normal  bg_color="gray" />
	<disable  bg_color="gray" round_radius="6" x_offset="3" y_offset="3"/>
	<focused  bg_color="gray" bg_image_draw_type="center" bg_image="1"/>
  </style>
</image_value>

运行效果如下图所示：

图4.58 image_value样式设置效果

4. 事件

image_value还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值即将改变事件(click_add_delta为非0时，点击触发)。
EVT_VALUE_CHANGED	value_change_event_t	值改变事件(click_add_delta为非0时，点击触发)。

5. 示例

• 在xml中，使用"image_value"标签创建图片值控件，代码如下，其中的样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/image_value.xml -->
<window anim_hint="htranslate">
  <view x="0" y="0" w="100%" h="100%" children_layout="default(c=2,r=3)">
    <image_value  value="0" image="battery_"
      animation="value(from=0, to=5, duration=10000)"/>
    <image_value  value="0" image="battery_"
      animation="value(from=0, to=5, duration=10000)"/>
    <image_value  value="0" format="%02d" image="num_"
      animation="value(from=10, to=100, duration=100000)"/>
    <image_value  value="0" format="%04d" image="num_"
      animation="value(from=10, to=10000, duration=100000)"/>
    ...
  </view>
</window>

运行效果如下图所示：

图4.59 在xml中创建image_value的效果

• 在C代码中，使用image_value_create创建图片值控件，代码如下，其中的样式设置见上文样式一节。

image_value = image_value_create(win, 10, 10, 200, 200);
image_value_set_image(image_value, "num_");
image_value_set_value(image_value, 100);

运行效果如下图所示：

图4.60 在C中创建image_value的效果

4.8.10 keyboard

软键盘。软键盘是一个特殊的窗口，由编辑器通过输入法自动打开和关闭。编辑器输入类型和软键盘UI资源文件的对应关系，详见下表：

输入类型	软键盘UI资源文件
INPUT_PHONE	kb_phone.xml
INPUT_INT	kb_int.xml
INPUT_FLOAT	kb_float.xml
INPUT_UINT	kb_uint.xml
INPUT_UFLOAT	kb_ufloat.xml
INPUT_HEX	kb_hex.xml
INPUT_EMAIL	kb_ascii.xml
INPUT_PASSWORD	kb_ascii.xml
INPUT_CUSTOM	使用自定义的键盘
其它	kb_default.xml

keyboard中按钮子控件的名称功能说明，详见下表：

名称	功能
return	回车键
action	定制按钮
backspace	删除键
tab	tab键
space	空格键
close	关闭软键盘
clear	清除编辑器的内容
cancel	恢复编辑器的内容
back	关闭当前窗口
back_to_home	返回home窗口
前缀key:	键值
前缀hard_key:	模拟物理键盘
前缀page:	切换到页面
前缀opt:	多个字符选择一个，点击切换到下一个，超时提交字符(用于实现九宫格输入)

1. 函数

keyboard提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
keyboard_create	创建keyboard对象
keyboard_close	关闭keyboard窗口。
keyboard_cast	转换为keyboard对象(供脚本语言使用)。
keyboard_get_widget_vtable	获取 keyboard 虚表。

2. 示例

• 创建edit输入类型hex，xml程序代码如下：

<edit name="new" x="c" y="m" w="80%" h="50"  input_type="hex"/>

运行效果如下下图所示：

图4.61 输入类型hex的键盘效果

4.8.11 candidates

输入法候选字词控件。candidates_t是widget_t的子类控件，widget_t的函数均适用于candidates_t控件。

1. 函数

candidates提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
candidates_create	创建candidates对象
candidates_cast	转换为candidates对象(供脚本语言使用)。
candidates_set_pre	设置是否为预候选字列表。
candidates_set_select_by_num	设置是否启用用数字选择候选字。
candidates_set_auto_hide	设置是否自动隐藏。
candidates_set_button_style	设置按钮的style名称。
candidates_get_widget_vtable	获取 candidates 虚表。

2. 属性

candidates还提供了下面属性，详见下表：

属性名称	类型	说明
pre	bool_t	是否为预候选字。
select_by_num	bool_t	是否启用用数字选择候选字。比如按下1选择第1个候选字，按下2选择第2个候选字。
auto_hide	bool_t	没有候选字时，是否自动隐藏控件。
button_style	char*	按钮的style名称。
enable_preview	bool_t	是否启用候选字预览。

3. 状态

candidates在样式文件中可以设置的状态，详见下表：

状态	说明
normal	正常状态
pressed	按下状态
over	悬浮状态
focused	聚焦状态

4. 示例

• 在xml中，使用"candidates"标签创建输入法候选字词控件，代码如下，如果希望启用用数字选择对应的候选字，请设置属性grab_keys="true"

<!-- awtk/demos/assets/default/raw/ui/progress_circle.xml -->
<keyboard theme="keyboard" x="0" y="bottom" w="100%" h="40%">
  ...
  <candidates x="0" y="0" w="100%" h="30" grab_keys="true"/>
  ...
</keyboard>

4.8.12 lang_indicator

输入法语言指示器。用于显示输入法的输入语言或类型，主要用于T9输入法。lang_indicator_t是widget_t的子类控件，widget_t的函数均适用于lang_indicator_t控件。

1. 函数

lang_indicator提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
lang_indicator_create	创建lang_indicator对象
lang_indicator_set_image	设置缺省获得焦点的子控件(可用控件名或类型)。
lang_indicator_cast	转换为lang_indicator对象(供脚本语言使用)。

2. 属性

lang_indicator还提供了下面属性，详见下表：

属性名称	类型	说明
image	char*	如果希望用图片格式显示，本属性用于指定图片的前缀。

3. 示例

<!-- awtk/design/default/ui/kb_default_t9ext.xml-->
<keyboard disable_anim="true" theme="keyboard" style="transparent" x="0" y="bottom" w="100%" h="78" 
    move_focus_up_key="up"
    move_focus_down_key="down"
    move_focus_left_key="left"
    move_focus_right_key="right"
    grab_keys="true">
   ...
   <lang_indicator self_layout="default(x=r:2, y=0, w=48, h=20)" />
   ...
</keyboard>

4.8.13 progress_circle

进度圆环控件。progress_circle_t是widget_t的子类控件，widget_t的函数均适用于progress_circle_t控件。

1. 函数

progress_circle提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
progress_circle_create	创建progress_circle对象
progress_circle_cast	转换为progress_circle对象(供脚本语言使用)。
progress_circle_set_value	设置值。
progress_circle_set_max	设置最大值。
progress_circle_set_format	设置格式。
progress_circle_set_line_width	设置环线的厚度。
progress_circle_set_start_angle	设置起始角度。
progress_circle_set_line_cap	设置线帽类型。
progress_circle_set_show_text	设置是否显示文本。
progress_circle_set_counter_clock_wise	设置是否为逆时针方向。
progress_circle_calc_line_dirty_rect	获取progress_circle的新值和旧值之间的绘制脏矩形。
progress_circle_get_widget_vtable	获取 progress_circle 虚表。

2. 属性

progress_circle还提供了下面属性，详见下表：

属性名称	类型	说明
value	float_t	值(缺省为0)。
max	float_t	最大值(缺省为100)。
format	char*	数值到字符串转换时的格式，缺省为"%d"。
start_angle	int32_t	起始角度(单位为度，缺省-90)。
line_width	uint32_t	环线的厚度(缺省为8)。
line_cap	char*	线帽类型(round:圆头，square:方头，butt:平头)。
counter_clock_wise	bool_t	是否为逆时针方向(缺省为FALSE)。
show_text	bool_t	是否显示文本(缺省为TRUE)。

3. 样式

progress_circle可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
Border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
fg_image	前景图片的名称
fg_image_draw_type	前景图片的显示方式（取值：详见image 控件一节）
Icon	图标的名称
Spacer	间距
Margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
icon_at	图标的位置（取值：top|bottom|left|right）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

样式设置代码如下：

<progress_circle>
  <style name="default" border_color="black" border_width="3" border="all" text_color="green">
    <normal  bg_color="gray" fg_color="red"/>
	<disable  bg_color="gray" fg_color="red" round_radius="6" x_offset="3" y_offset="3"/>
	<focused  bg_color="gray" fg_image="progress_circle"/>
  </style>
</progress_circle>

样式设置效果如下图所示：

图4.62 process_circle样式设置效果

4. 事件

progress_circle还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值改变事件。

1. 示例

• 在xml中，使用"progress_circle"标签创建进度圆环控件，代码如下，其中的样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/progress_circle.xml -->
<window >
  <view x="c" y="m" w="200" h="200" children_layout="default(r=2,c=2,s=5)">
    <progress_circle max="360" show_text="true" 
      animation="value(from=0, to=360, yoyo_times=1000, duration=3000, easing=sin_inout)"/>

    <progress_circle max="360" show_text="true" start_angle="90" 
      animation="value(from=0, to=300, yoyo_times=1000, duration=3000, easing=sin_inout)"/>

    <progress_circle style="image" max="360" show_text="true" start_angle="-213"  
      animation="value(from=0, to=300, yoyo_times=1000, duration=3000, easing=sin_inout)"/>

    <progress_circle style="image" max="100" show_text="true" start_angle="90" start_angle="-225"  
      counter_clock_wise="true" unit="%"
      animation="value(from=10, to=100, yoyo_times=1000, duration=3000, easing=sin_inout)"/>
   </view>
   
   <button name="close" x="center" y="bottom:10" w="25%" h="30" text="Close"/>
</window>

运行效果如下图所示：

图4.63 在xml中创建progress_circle的效果

• 在C代码中，使用函数progress_circle_create创建进度圆环控件，代码如下，其中的样式设置见上文样式一节。

progress_circle = progress_circle_create(win, 10, 10, 200, 200);
progress_circle_set_max(progress_circle, 360);
widget_set_value(progress_circle, 128); 

运行效果如下图所示：

图4.64 在C中创建progress_circle的效果

4.8.14 rich_text

图文混排控件，实现简单的图文混排。rich_text_t是widget_t的子类控件，widget_t的函数均适用于rich_text_t控件。

1. 函数

rich_text提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
rich_text_create	创建rich_text对象
rich_text_set_text	设置文本。
rich_text_set_yslidable	设置是否允许y方向滑动。
rich_text_cast	转换为rich_text对象(供脚本语言使用)。
rich_text_get_widget_vtable	获取 rich_text 虚表。

2. 属性

rich_text还提供了下面属性，详见下表：

属性名称	类型	说明
line_gap	uint32_t	行间距。
yoffset	int32_t	y偏移。
yslidable	bool_t	标识控件是否允许上下拖动。
need_reset	bool_t	标识控件是否需要重新绘图。

3. 样式

rich_text可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
icon	图标的名称
spacer	间距
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
icon_at	图标的位置（取值：top|bottom|left|right）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

样式设置代码如下：

<rich_text>
  <style name="default" font_name="default" font_size="30" border_color="black" border_width="3" 
  border="all" text_color="green">
    <normal  bg_color="gray"  text_align_h="left" fg_color="red"/>
	<disable  bg_color="gray" text_align_v="bottom" fg_color="red" round_radius="6" x_offset="3" 
  y_offset="3"/>
	<focused  bg_color="gray"  bg_image="1" bg_image_draw_type="scale"/>
  </style>
</rich_text>

运行效果如下图所示：

图4.65 rich_text样式设置效果

4. 示例

• 在xml中，使用"rich_text"标签创建图文混排控件，代码如下，其中的样式设置见上文样式一节。

<!-- awtk\demos\assets\default\raw\ui\rich_text1.xml -->
<window anim_hint="htranslate" >
    <rich_text line_gap="5" x="0" y="20" w="100%" h="400" 
    text="<image draw_type=&quota;auto&quota; name=&quota;1&quota;/>
	   <image name=&quota;2&quota;/>
	   <font color=&quota;red&quota; size==&quota;18&quota;>Hello world!</font>
	   <image name=&quota;earth&quota;/>
	<font color=&quota;blue&quota; size==&quota;18&quota;>ProTip!</font>"/>

  <button name="close" text="Close" x="c" y="bottom:10" w="25%" h="40"/>
</window>

运行效果如下图所示：

图4.66 在xml中创建rich_text的效果

• 在C代码中，使用rich_text_create创建图文混排控件，代码如下，其中的样式设置见上文样式一节。

widget_t* rich_text = rich_text_create(win, 0, 0, 0, 0);
widget_set_text_utf8(rich_text,
	"<image name=\"bricks\"/>                                                     \
    <font color=\"gold\" align_v=\"bottom\" size=\"24\">hello awtk!</font>        \
    <font color=\"green\" size=\"20\">ProTip!\
    The feed shows you events from people you follow and repositories you watch. nhello world. </font> \
    <font color=\"red\" size=\"20\">确定取消中文字符测试。确定。取消。中文字符测</font>");
widget_set_self_layout_params(rich_text, "center", "middle", "100%", "100%");

运行效果如下图所示：

图4.67 在C中创建rich_text的效果

4.8.15 slide_menu

左右滑动菜单控件。一般用一组按钮作为子控件，通过左右滑动改变当前的项。除了当菜单使用外，也可以用来切换页面。slide_menu_t是widget_t的子类控件，widget_t的函数均适用于slide_menu_t控件。

1. 函数

slide_menu提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
slide_menu_create	创建slide_menu对象
slide_menu_cast	转换slide_menu对象(供脚本语言使用)。
slide_menu_set_value	设置当前项。
slide_menu_set_align_v	设置垂直对齐方式。
slide_menu_set_min_scale	设置最小缩放比例。
slide_menu_set_spacer	设置菜单项之间的间距。
slide_menu_set_menu_w	设置菜单项的宽度。
slide_menu_set_clip	设置是否动态裁剪菜单项。
slide_menu_scroll_to_prev	切换至上一项。
slide_menu_scroll_to_next	切换至下一项。
slide_menu_get_widget_vtable	获取 slide_menu 虚表。

2. 属性

slide_menu还提供了下面属性，详见下表：

属性名称	类型	说明
value	int32_t	值。代表当前选中项的索引。
align_v	align_v_t	垂直对齐方式。
min_scale	float_t	最小缩放比例。
spacer	int32_t	菜单项之间的间距。
menu_w	char*	菜单项的宽度(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)(空字符串则使用控件高度)。
clip	bool_t	是否动态裁剪菜单项(默认裁剪，不裁剪时，如果显示偶数项，左边会多一项)。

3. 样式

slide_menu可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
mask_color	蒙版颜色
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

样式设置代码如下：

<style name="default" border_color="black" border_width="3" border="all">
  <normal bg_color="gray"  mask_color="red" />
  <disable bg_color="gray" round_radius="6" x_offset="3" y_offset="3"/>
  <focused  bg_image="1" bg_image_draw_type="scale"/>
</style>

运行效果如下图所示：

图4.68 slide_menu样式效果

4. 事件

slide_menu还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(当前项)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(当前项)改变事件。

5. 示例

• 在xml中，使用"slide_menu"标签创建左右滑动菜单，代码如下，其中的样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/slide_menu.xml -->
<window theme="slide_menu" children_layout="default(c=1,h=60,s=10)">
  <slide_menu style="mask" align_v="top">
    <button style="slide_button" text="0"/>
    <button style="slide_button" text="1"/>
    <button style="slide_button" text="2"/>
    <button style="slide_button" text="3"/>
    <button style="slide_button" text="4"/>
  </slide_menu>
</window>

运行效果如下图所示：

图4.69 在xml中创建slide_menu的效果

• 在C代码中，使用函数slide_menu_create创建左右滑动菜单，代码如下，样式设置见上文样式一节。

slide_menu = slide_menu_create(win, 10, 10, 300, 60);
b = button_create(slide_menu, 0, 0, 0, 0);
widget_set_text_utf8(b, "1");
b = button_create(slide_menu, 0, 0, 0, 0);
widget_set_text_utf8(b, "2");
b = button_create(slide_menu, 0, 0, 0, 0);
widget_set_text_utf8(b, "3");
b = button_create(slide_menu, 0, 0, 0, 0);
widget_set_text_utf8(b, "4"); 

运行效果如下图所示：

图4.70 在C中创建slide_menu的效果

可按下面的方法关注当前项改变的事件：

widget_on(slide_menu, EVT_VALUE_CHANGED, on_current_changed, slide_menu);

可按下面的方法关注当前按钮被点击的事件：

widget_on(b, EVT_CLICK, on_button_click, b);

4.8.16 slide_view

滑动视图。滑动视图可以管理多个页面，并通过滑动来切换当前页面。也可以管理多张图片，让它们自动切换。slide_view_t是widget_t的子类控件，widget_t的函数均适用于slide_view_t控件。

1. 函数

slide_view提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
slide_view_create	创建slide_view对象
slide_view_cast	转换为slide_view对象(供脚本语言使用)。
slide_view_set_auto_play	设置为自动播放模式。
slide_view_set_active	设置当前页的序号(默认启用动画)。
slide_view_set_active_ex	设置当前页的序号。
slide_view_set_vertical	设置为上下滑动(缺省为左右滑动)。
slide_view_set_anim_hint	设置页面切换动画。
slide_view_set_loop	设置循环切换模式。
slide_view_set_drag_threshold	设置拖拽临界值。
slide_view_set_animating_time	设置动画时间。
slide_view_remove_index	删除指定序号页面。
slide_view_get_widget_vtable	获取 slide_view 虚表。

2. 属性

slide_view还提供了下面属性，详见下表：

属性名称	类型	说明
vertical	bool_t	是否为上下滑动模式。
auto_play	uint16_t	自动播放。0表示禁止自动播放，非0表示自动播放时每一页播放的时间。
loop	bool_t	循环切换模式。
anim_hint	char*	页面切换效果。
drag_threshold	uint32_t	拖动临界值。
animating_time	uint32_t	动画时间（单位：毫秒）。

3. 样式

slide_view可设置的样式，详见canvas_widget一节的样式小节。样式设置代码如下：

<slide_view>
  <style name="default" border_color="black" border_width="3" border="all" >
    <normal  bg_color="gray" />
 	  <disable  bg_color="gray" round_radius="6" x_offset="3" y_offset="3"/>
	  <focused  bg_color="gray" bg_image_draw_type="center" bg_image="1"/>
  </style>
</slide_view>

图4.71 slide_view样式效果

4. 事件

slide_view还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(当前页)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(当前页)改变事件。
EVT_PAGE_CHANGED	event_t	页面改变事件。
EVT_PAGE_CHANGING	event_t	页面正在改变。

5. 示例

• 在xml中，使用"slide_view"标签创建滑动视图控件，代码如下，样式设置见上文样式一节。

<slide_view x="0" y="0" w="100%" h="100%" loop="true">
	<view x="0" y="0" w="100%" h="100%" children_layout="default(w=60,h=60,m=5,s=10)">
	</view>
	<view x="0" y="0" w="100%" h="100%" children_layout="default(w=60,h=60,m=5,s=10)">
	</view>
</slide_view>
<slide_indicator x="0" y="b" w="100%" h="20" style="blue"/>

运行效果如下图所示：

图4.72 在xml中创建slide_view的效果

• 在C代码中，使用函数slide_view_create创建滑动视图控件，代码如下，样式设置见上文样式一节，运行效果见上图。

slide_view = slide_view_create(win, 0, 0, win->w, win->h); 

4.8.17 svg_image

SVG图片控件。svg_image_t是image_base_t的子类控件，image_base_t的函数均适用于svg_image_t控件。

1. 函数

svg_image提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
svg_image_create	创建svg_image对象
svg_image_set_image	设置控件的图片名称。
svg_image_set_cache_mode	控件设置是否开启离线缓存渲染模式。
svg_image_set_draw_type	控件设置svg图片绘制模式。
svg_image_cast	转换为svg_image对象(供脚本语言使用)。
svg_image_get_widget_vtable	获取 svg_image 虚表。

2. 属性

svg_image还提供了下面属性，详见下表：

属性名称	类型	说明
is_cache_mode	bool_t	离线缓存渲染模式。
draw_type	image_draw_type_t	svg图片的绘制方式(支持旋转缩放, 目前仅支持scale、scale_auto模式)。

3. 样式

svg_image可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
icon	图标的名称
spacer	间距
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
icon_at	图标的位置（取值：top|bottom|left|right）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

样式设置代码如下：

<svg>
  <style name="default">
    <normal border_color="#000000" fg_color="red" />
  </style>
</svg>

4. 示例

• 在xml中，使用"svg_image"标签创建SVG图片控件，代码如下，其中的样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/svg_image.xml -->
<window anim_hint="htranslate" children_layout="default(c=4,r=4)">
  <svg image="china" />
  <svg image="pointer_1" />
  <svg image="girl" />
  <svg image="pointer_4" />
  <svg image="china" animation="rotation(from=0, to=6.28, yoyo_times=1000, duration=5000);scale(x_from=0, x_to=2, y_from=0, y_to=2, yoyo_times=1000, duration=5000);"/>
  <svg image="pointer_1" animation="rotation(from=0, to=6.28, yoyo_times=1000, duration=5000);scale(x_from=0, x_to=2, y_from=0, y_to=2, yoyo_times=1000, duration=5000);"/>
  <svg image="girl" animation="rotation(from=0, to=6.28, yoyo_times=1000, duration=5000);scale(x_from=0, x_to=2, y_from=0, y_to=2, yoyo_times=1000, duration=5000);"/>
  <svg image="pointer_4" animation="rotation(from=0, to=6.28, yoyo_times=1000, duration=5000);scale(x_from=0, x_to=2, y_from=0, y_to=2, yoyo_times=1000, duration=5000);"/>
</window>

运行效果如下图所示：

图4.73 在xml中创建svg的效果

• 在C代码中，使用函数svg_image_create创建SVG图片控件，代码如下，其中的样式设置见上文样式一节。

widget_t* image = svg_image_create(win, 10, 10, 200, 200);
image_set_image(image, "girl"); 

创建之后需要用widget_set_image设置图片名称。

图4.74 在C中创建svg的效果

4.8.18 switch

开关控件。switch_t是widget_t的子类控件，widget_t的函数均适用于switch_t控件。

使用该控件的时候需要将awtk/demos/assets/default/raw/images/x1目录下：switch.png复制到自己的应用目录下（如：res/assets/default/raw/images/xx），否则将不能正常显示。

1. 函数

switch提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
switch_create	创建switch对象
switch_set_value	设置控件的值。
switch_cast	转换switch对象(供脚本语言使用)。
switch_get_widget_vtable	获取 switch 虚表。

2. 属性

switch还提供了下面属性，详见下表：

属性名称	类型	说明
value	bool_t	值。
max_xoffset_ratio	float_t	当开关处于关闭时，图片偏移相对于图片宽度的比例(缺省为1/3)。

3. 样式

switch可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
fg_color	前景颜色
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
fg_image	前景图片的名称
fg_image_draw_type	前景图片的显示方式（取值：详见image 控件一节）
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
selected_bg_color	编辑器（包括edit和mledit控件）中选中区域的背景颜色
selected_fg_color	编辑器（包括edit和mledit控件）中选中区域的前景颜色
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

样式设置代码如下：

<switch>
  <style name="default" border_color="black" >
    <normal  bg_image="switch" />
  </style>
  <style name="no_image" border_color="black" >
    <normal  bg_color="#828282" selected_bg_color="#338fff" fg_color="#ffffff" round_radius="11"/>
  </style>
  <style name="image" border_color="black" >
    <normal  bg_image="switch" round_radius="11"/>
  </style>
</switch>

运行效果如下图所示：

图4.75 switch样式设置效果

4. 事件

switch还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_CLICK	pointer_event_t	点击事件。
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(开关状态)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(开关状态)改变事件。

5. 示例

• 在xml中，使用"switch"标签创建开关控件，代码如下，样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/switch.xml -->
<window anim_hint="htranslate">
  <switch x="10" y="60" w="60" h="22" />
  <switch x="200" y="60" w="60" h="22" round_radius="10" />
  <button name="close" x="center" y="middle" w="50%" h="30" text="close"/>
</window>

运行效果如下图所示：

图4.76 在xml中创建switch的效果

• 在C代码中，使用函数switch_create创建开关控件，代码如下，样式设置详见上文样式一节。效果见上图。

widget_t* sw = switch_create(win, 10, 10, 80, 30);
widget_on(sw, EVT_VALUE_CHANGED, on_changed, NULL); 

4.8.19 text_selector

文本选择器控件，通常用于选择日期和时间等。目前需要先设置options和visible_nr，再设置其它参数（在XML中也需要按此顺序）。text_selector_t是widget_t的子类控件，widget_t的函数均适用于text_selector_t控件。

1. 函数

text_selector提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
text_selector_create	创建text_selector对象
text_selector_cast	转换text_selector对象(供脚本语言使用)。
text_selector_reset_options	重置所有选项。
text_selector_count_options	获取选项个数。
text_selector_append_option	追加一个选项。
text_selector_set_options	设置选项。
text_selector_set_range_options_ex	设置一系列的整数选项。
text_selector_set_range_options	设置一系列的整数选项。
text_selector_get_option	获取第index个选项。
text_selector_get_value	获取text_selector的值。
text_selector_set_value	设置text_selector的值。
text_selector_get_text	获取text_selector的文本。
text_selector_set_text	设置text_selector的文本。
text_selector_set_selected_index	设置第index个选项为当前选中的选项。
text_selector_set_visible_nr	设置可见的选项数。
text_selector_set_localize_options	设置是否本地化(翻译)选项。
text_selector_set_loop_options	设置是否循环选项。
text_selector_set_yspeed_scale	设置Y轴偏移速度比例。
text_selector_set_animating_time	设置滚动动画播放时间。
text_selector_set_enable_value_animator	设置是否修改值时启用动画。
text_selector_set_mask_easing	设置绘制蒙版的变化趋势。
text_selector_set_mask_area_scale	设置绘制蒙版的区域占比（范围0~1）。
text_selector_get_widget_vtable	获取 text_selector 虚表。

2. 属性

text_selector还提供了下面属性，详见下表：

属性名称	类型	说明
visible_nr	uint32_t	可见的选项数量(只能是1或者3或者5，缺省为5)。
selected_index	int32_t	当前选中的选项。
options	char*	设置可选项(英文冒号(:)分隔值和文本，英文分号(;)分隔选项，如:1:red;2:green;3:blue)。
yspeed_scale	float_t	y偏移速度比例。
animating_time	uint32_t	滚动动画播放时间。(单位毫秒)
localize_options	bool_t	是否本地化(翻译)选项(缺省为FALSE)。
loop_options	bool_t	是否循环选项(缺省为FALSE)。
enable_value_animator	bool_t	是否修改值时启用动画。
mask_easing	easing_type_t	绘制蒙版的变化趋势。
mask_area_scale	float_t	绘制蒙版的区域占比（范围0~1）。

3. 样式

text_selector可设置的样式，详见下表。

样式属性	说明
bg_color	背景颜色
fg_color	前景颜色
mask_color	蒙版颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

样式设置代码如下：

<text_selector>
  <style name="default" fg_color="#a0a0a0" text_color="black" text_align_h="center">
    <normal bg_color="#f0f0f0"/>
  </style>
  <style name="dark" fg_color="#a0a0a0" text_color="black" text_align_h="center">
    <normal bg_color="#ffffff" mask_color="#404040" border_color="#404040"/>
  </style>
</text_selector>

4. 事件

text_selector还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(当前项)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(当前项)改变事件。

5. 示例

• 在xml中，使用"text_selector"标签创建文本选择器控件，代码如下，样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/text_selector.xml -->
<window anim_hint="htranslate">
  <row  x="10" y="30" w="100%" h="150" children_layout="default(row=1,col=3)">
    <text_selector style="dark" options="2000-2050" text="2018"/>
    <text_selector options="1-12" text="1"/>
    <text_selector options="1-31" text="1"/>
  </row>
  <button name="close" x="center" y="middle" w="50%" h="30" text="close"/>
  <row  x="10" y="bottom:30" w="100%" h="90" children_layout="default(row=1,col=3)">
    <text_selector style="dark" options="2000-2050" visible_nr="3" text="2018"/>
    <text_selector options="1-12" visible_nr="3" text="1"/>
    <text_selector options="red;green;blue;gold;orange" visible_nr="3" text="red"/>
  </row>
</window>

运行效果如下图所示：

图4.77 在xml中创建text_selector的效果

• 在C代码中，使用函数text_selector_create创建文本选择器控件，代码如下，样式设置见上文样式一节。

widget_t* ts = text_selector_create(win, 10, 10, 80, 150);
text_selector_set_options(ts, "1:red;2:green;3:blue;4:orange;5:gold");
text_selector_set_value(ts, 1);
widget_use_style(ts, "dark"); 

运行效果如下图所示：

图4.78 在C中创建text_selector的效果

4.8.20 time_clock

模拟时钟控件。time_clock_t是widget_t的子类控件，widget_t的函数均适用于time_clock_t控件。

1. 函数

time_clock提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
time_clock_create	创建time_clock对象
time_clock_cast	转换为time_clock对象(供脚本语言使用)。
time_clock_set_hour	设置小时的值。
time_clock_set_minute	设置分钟的值。
time_clock_set_second	设置秒的值。
time_clock_set_hour_image	设置小时的图片。
time_clock_set_minute_image	设置分钟的图片。
time_clock_set_second_image	设置秒的图片。
time_clock_set_bg_image	设置背景图片。
time_clock_set_image	设置中心图片。
time_clock_set_hour_anchor	设置小时指针的旋转锚点。
time_clock_set_minute_anchor	设置分钟指针的旋转锚点。
time_clock_set_second_anchor	设置秒钟指针的旋转锚点。
time_clock_get_widget_vtable	获取 time_clock 虚表。

2. 属性

time_clock还提供了下面属性，详见下表：

属性名称	类型	说明
hour	int32_t	小时。
minute	int32_t	分钟。
second	int32_t	秒。
image	char*	中心图片。
bg_image	char*	背景图片。
hour_image	char*	时针图片。
minute_image	char*	分针图片。
second_image	char*	秒针图片。
hour_anchor_x	char*	时针图片旋转锚点x坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)
hour_anchor_y	char*	时针图片旋转锚点y坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)
minute_anchor_x	char*	分针图片旋转锚点x坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)
minute_anchor_y	char*	分针图片旋转锚点y坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)
second_anchor_x	char*	秒针图片旋转锚点x坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)
second_anchor_y	char*	秒针图片旋转锚点y坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)

3. 示例

• 在xml中，使用"time_clock"标签创建模拟时钟控件，代码如下：

<!-- awtk\demos\assets\default\raw\ui\time_clock.xml -->
<window anim_hint="htranslate" >
  <time_clock x="c" y="m" w="300" h="300" bg_image="clock_bg" image="clock" hour_image="clock_hour" minute_image="clock_minute" second_image="clock_second"/>
</window>

运行效果如下：

图4.79 在xml中创建time_clock的效果

• 在C代码中，使用函数time_clock_create创建模拟时钟控件，代码如下：

widget_t* tc = time_clock_create(win, 10, 10, 300, 300);
time_clock_set_image(tc, "clock");
time_clock_set_bg_image(tc, "clock_bg");
time_clock_set_hour_image(tc, "clock_hour");
time_clock_set_minute_image(tc, "clock_minute");
time_clock_set_second_image(tc, "clock_second");

图4.80 在C中创建time_clock的效果

4.8.21 list_view

列表视图控件。列表视图控件是一个可以垂直滚动的列表控件。如果不需要滚动，可以用view控件配置适当的layout参数作为列表控件。列表视图中的列表项可以固定高度，也可以使用不同高，请参考：awtk/demos/assets/default/raw/ui/list_view_vh.xml

列表视图中的列表项可以固定高度，也可以使用不同高度。列表视图控件中可以有滚动条，也可以没有滚动条。既可以使用移动设备风格的滚动条，也可以使用桌面风格的滚动条。list_view_t是widget_t的子类控件，widget_t的函数均适用于list_view_t控件。

1. 函数

list_view提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
list_view_create	创建list_view对象
list_view_set_item_height	设置列表项的高度。
list_view_set_default_item_height	设置列表项的缺省高度。
list_view_set_auto_hide_scroll_bar	设置是否自动隐藏滚动条。
list_view_set_floating_scroll_bar	设置滚动条是否悬浮在 scroll_view 上面。
list_view_cast	转换为list_view对象(供脚本语言使用)。
list_view_reinit	list_view重新初始化。
list_view_get_widget_vtable	获取 list_view 虚表。

2. 属性

list_view还提供了下面属性，详见下表：

属性名称	类型	说明
item_height	int32_t	列表项的高度。如果 item_height > 0，所有列表项使用固定高度，否则使用列表项自身的高度。
default_item_height	int32_t	列表项的缺省高度。如果item_height <= 0 而且列表项自身的高度 <= 0，则使用缺省高度。
auto_hide_scroll_bar	bool_t	如果不需要滚动条时，自动隐藏滚动条。
floating_scroll_bar	bool_t	滚动条是否悬浮在 scroll_view 上面

设置列表项高度的优先级：item_height > 列表项自身高度 > default_item_height，具体代码如下：

<list_view x="0" y="0" w="30%" h="100%" item_height="40" default_item_height="80" >
    <scroll_view name="view" x="0"  y="0" w="-12" h="100%">
      <tab_button text="page1" value="true" h="120" />
      <tab_button text="page2" />
      ...
    </scroll_view>
    <scroll_bar_d name="bar" x="right" y="0" w="12" h="100%" value="0"/>
</list_view>

3. 样式

list_view可设置的样式，详见canvas_widget一节的样式小节。样式设置代码如下：

<list_view>
    <style name="default" text_color="white" round_radius="10">
        <normal bg_color="#292929" />
    </style>
</list_view>

4. 示例

• 在xml中，使用"list_view"标签创建列表视图控件，代码如下，list_view样式设置见上文样式一节，list_item样式设置详见list_item一节，scroll_view样式设置详见scroll_view一节。

<window anim_hint="htranslate">
<list_view x="0"  y="30" w="100%" h="-80"       item_height="60">
  <scroll_view name="view" x="0"  y="0" w="100%" h="100%">
    <list_item style="odd" children_layout="default(rows=1,cols=0)">
      <image draw_type="icon" w="30" image="earth"/>
      <label w="-30" text="1.Hello AWTK !">
        <switch x="r:10" y="m" w="60" h="20"/>
      </label>
    </list_item>
    <list_item style="odd" children_layout="default(rows=1,cols=0)">
      <label w="100%" text="1.Hello AWTK !"/>
    </list_item>
    <list_item style="odd" children_layout="default(rows=1,cols=0)">
      <label w="100%" text="1.Hello AWTK !"/>
    </list_item>
    <list_item style="odd" children_layout="default(rows=1,cols=0)">
      <label w="100%" text="1.Hello AWTK !"/>
    </list_item>
    <list_item style="odd" children_layout="default(rows=1,cols=0)">
      <label w="100%" text="1.Hello AWTK !"/>
    </list_item>
    <list_item style="odd" children_layout="default(rows=1,cols=0)">
      <label w="100%" text="1.Hello AWTK !"/>
    </list_item>
  </scroll_view>
 </list_view>
</window>

运行效果如下图所示：

图4.81 list_view、scroll_view、list_item效果

4.8.22 list_view_h

水平列表视图控件。list_view_h_t是widget_t的子类控件，widget_t的函数均适用于list_view_h_t控件。

1. 函数

list_view_h提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
list_view_h_create	创建list_view_h对象
list_view_h_set_item_width	设置列表项的宽度。
list_view_h_set_spacing	设置列表项的间距。
list_view_h_cast	转换为list_view_h对象(供脚本语言使用)。
list_view_h_get_widget_vtable	获取 list_view_h 虚表。

2. 属性

list_view_h还提供了下面属性，详见下表：

属性名称	类型	说明
item_width	int32_t	列表项的宽度。
spacing	int32_t	间距。

3. 样式

list_view_h可设置的样式，详见canvas_widget一节的样式小节。样式设置代码如下：

<list_view_h>
    <style name="default" text_color="black" border_color="black">
        <normal bg_color="gray"/>
    </style>
</list_view_h>

4. 示例

• 在xml中，使用"list_view_h"标签创建水平列表视图控件，代码如下，样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/list_view_h.xml -->
<window anim_hint="htranslate">
  <list_view_h x="center"  y="10" w="90%" h="100" item_width="200" spacing="5">
    <scroll_view name="view" w="100%" h="100%">
      <image style="border" draw_type="auto" image="1" text="1"/>
      <image style="border" draw_type="auto" image="2" text="2"/>
      <image style="border" draw_type="auto" image="3" text="3"/>
      <image style="border" draw_type="auto" image="1" text="4"/>
      <image style="border" draw_type="auto" image="2" text="5"/>
      <image style="border" draw_type="auto" image="3" text="6"/>
      <image style="border" draw_type="auto" image="1" text="7"/>
      ...
    </scroll_view>
  </list_view_h>
  <button name="close" x="center" y="bottom:10" w="50%" h="30" text="close"/>
</window>

运行效果如下图所示：

图4.82 在xml中创建list_view_h的效果

4.8.23 list_item

列表项控件。列表项控件是一个简单的容器控件，一般作为列表视图中滚动视图的子控件。list_item_t是widget_t的子类控件，widget_t的函数均适用于list_item_t控件。

1. 函数

list_item提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
list_item_create	创建list_item对象
list_item_cast	转换为list_item对象(供脚本语言使用)。
list_item_get_widget_vtable	获取 list_item 虚表。

2. 样式

list_item可设置的样式，详见canvas_widget一节的样式小节。样式设置代码如下：

<list_item>
  <style name="default" border_color="#a0a0a0"  border="bottom" text_color="black">
    <normal     bg_color="#f0f0f0" />
    <pressed    bg_color="#c0c0c0" />
    <over       bg_color="#f0f0f0" />
  </style>
<list_item>

3. 事件

list_item还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_CLICK	pointer_event_t	点击事件。

4. 示例

• 在xml中，使用"list_item"标签创建列表项控件，代码如下，样式设置见上文样式一节。

<!-- awtk/demos/assets/default/raw/ui/list_view_m.xml -->
<window anim_hint="htranslate">
  <list_view x="0"  y="30" w="100%" h="-80" item_height="60">
    <scroll_view name="view" x="0"  y="0" w="100%" h="100%">
      <list_item style="odd" children_layout="default(rows=1,cols=0)">
        <image draw_type="icon" w="30" image="earth"/>
        <label w="-30" text="1.Hello AWTK !">
          <switch x="r:10" y="m" w="60" h="20"/>
        </label>
      </list_item>
  </list_view>
  <button name="close" x="center" y="bottom:10" w="50%" h="30" text="close"/>
</window>

图4.83 在xml中创建list_item的效果

4.8.24 list_item_seperator

用来模拟实现风琴控件(accordion)和属性页分组控件。当前控件被点击时，显示/隐藏当前控件到下一个分隔符控件之间的控件。list_item_seperator_t是widget_t的子类控件，widget_t的函数均适用于list_item_seperator_t控件。

1. 函数

list_item_seperator提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
list_item_seperator_create	创建list_item_seperator对象
list_item_seperator_cast	转换为list_item_seperator对象(供脚本语言使用)。

2. 状态

list_item_seperator在样式文件中可以设置的状态。

状态	说明
normal	正常状态
over	指针悬浮状态
pressed	按下状态
focused	聚焦状态
normal_of_checked	展开后正常状态
pressed_of_checked	展开后按下状态
over_of_checked	展开后指针悬浮状态
focused_of_checked	展开后聚焦状态

3. 示例

• 在xml中使用"list_item_seperator"标签创建list_item_seperator。如：

<window>
  ...
  <list_item_seperator radio="true" text="Group2" h="32"/>
  <list_item style="empty" children_layout="default(r=1,c=0,ym=1)">
    <label w="30%" text="ASCII"/>
    <edit w="70%" text="" tips="ascii" input_type="ascii" focused="true" action_text="next"/>
  </list_item>
  <list_item style="empty" children_layout="default(r=1,c=0,ym=1)">
    <label w="30%" text="Int"/>
    <edit w="70%" text="" tips="int" input_type="int"/>
  </list_item>
  <list_item_seperator radio="true" text="Group3" h="32"/>
  <list_item style="empty" children_layout="default(r=1,c=0,ym=1)">
    <label w="30%" text="Float"/>
    <edit w="70%" text="" tips="float" input_type="float"/>
  </list_item>
  <list_item style="empty" children_layout="default(r=1,c=0,ym=1)">
    <label w="30%" text="UFloat"/>
    <edit w="70%" text="" tips="unsigned float" input_type="ufloat"/>
  </list_item>
  ...
</window>

4.8.25 scroll_bar

滚动条控件（目前只支持垂直滚动）分为：scroll_bar_d（桌面风格）和scroll_bar_m（手机风格）两种滚动条，所以在UI界面XML文件中写scroll_bar_d或者scroll_bar_m，而不是scroll_bar。scroll_bar_t是widget_t的子类控件，widget_t的函数均适用于scroll_bar_t控件。

如果需要修改滚动条中滑块中的样式，请修改dragger控件下scroll_bar样式，代码如下：

<!-- awtk/demos/assets/default/raw/styles/default.xml -->
...
<dragger>
  <style name="scroll_bar" >
    <normal     bg_color="#d0d0d0" />
    <pressed    bg_color="#c0c0c0" />
    <over       bg_color="#c0c0c0" />
  </style>
</dragger>
...

使用该控件的时候需要将awtk/demos/assets/default/raw/images/x1目录下：arrow_*.png共12张图片复制到自己的应用目录下（如：res/assets/default/raw/images/xx），否则将不能正常显示。

1. 函数

scroll_bar提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
scroll_bar_create	创建scroll_bar对象
scroll_bar_cast	转换为scroll_bar对象(供脚本语言使用)。
scroll_bar_create_mobile	创建mobile风格的scroll_bar对象
scroll_bar_create_desktop	创建desktop风格的scroll_bar对象
scroll_bar_set_params	设置参数。
scroll_bar_scroll_to	滚动到指定的值。
scroll_bar_set_value	设置值，并触发EVT_VALUE_CHANGED事件。
scroll_bar_add_delta	在当前的值上增加一个值，并触发EVT_VALUE_CHANGED事件。
scroll_bar_scroll_delta	在当前的值上增加一个值，并滚动到新的值，并触发EVT_VALUE_CHANGED事件。
scroll_bar_set_value_only	设置值，但不触发EVT_VALUE_CHANGED事件。
scroll_bar_set_auto_hide	设置auto_hide属性。
scroll_bar_is_mobile	判断是否是mobile风格的滚动条。
scroll_bar_set_animator_time	设置翻页滚动动画时间。
scroll_bar_hide_by_opacity_animation	通过动画隐藏滚动条。
scroll_bar_show_by_opacity_animation	通过动画显示滚动条。

2. 属性

scroll_bar还提供了下面属性，详见下表：

属性名称	类型	说明
virtual_size	int32_t	虚拟宽度或高度。
value	int32_t	当前的值。
row	int32_t	行的高度。
animator_time	uint32_t	翻页滚动动画时间。
animatable	bool_t	滚动时是否启用动画。
auto_hide	bool_t	是否自动隐藏(仅对mobile风格的滚动条有效)。

3. 状态

scroll_bar在样式文件中可以设置的状态，详见下表，其中scroll_bar_m没有over状态。

状态	说明
normal	正常状态
over	指针悬浮状态
disable	禁用状态

4. 事件

scroll_bar还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(滚动值)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(滚动值)改变事件。

5. 示例

• 在xml中，使用"scroll_bar"或"scroll_bar_d"或"scroll_bar_m"标签创建滚动条控件，代码如下：

<!-- awtk/demos/assets/default/raw/ui/selectm.xml -->
<dialog anim_hint="bottom_to_top" x="0" y="bottom" w="100%" h="160">
  <dialog_title style="empty" x="0" y="0" w="100%" h="30">
    <button name="quit" x="5" y="middle" w="60" h="-4" text="Done"/>
    <label x="center" y="middle" w="128" h="-4" text="Select multiple"/>
    <button name="quit" x="right:5" y="middle" w="60" h="-4" text="Cancel"/>
  </dialog_title>
  <dialog_client x="0" y="bottom" w="100%" h="-30">
  <list_view x="0"  y="0" w="100%" h="100%" item_height="30">
    <scroll_view name="view" x="0"  y="0" w="100%" h="100%">
     <check_button style="odd_icon_right" name="c1" text="Book"/>
     <check_button style="even_icon_right" name="c2" text="Pencil"/>
     <check_button style="odd_icon_right" name="c1" text="Food"/>
     <check_button style="even_icon_right" name="c2" text="Bike"/>
    </scroll_view>
    <scroll_bar_m name="bar" x="right" y="0" w="6" h="100%" value="0"/>
  </list_view>
  </dialog_client>
</dialog>

图4.84 在xml中创建scroll_bar的效果

4.8.26 scroll_view

滚动视图。scroll_view_t是widget_t的子类控件，widget_t的函数均适用于scroll_view_t控件。

1. 函数

scroll_view提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
scroll_view_create	创建scroll_view对象
scroll_view_cast	转换为scroll_view对象(供脚本语言使用)。
scroll_view_set_virtual_w	设置虚拟宽度。
scroll_view_set_virtual_h	设置虚拟高度。
scroll_view_set_xslidable	设置是否允许x方向滑动。
scroll_view_set_yslidable	设置是否允许y方向滑动。
scroll_view_set_snap_to_page	设置滚动时offset是否按页面对齐。
scroll_view_set_move_to_page	设置滚动时是否每次翻一页
scroll_view_set_recursive	设置是否递归查找全部子控件。
scroll_view_set_recursive_only	设置是否递归查找全部子控件。(不触发repaint和relayout)。
scroll_view_set_offset	设置偏移量。
scroll_view_set_speed_scale	设置偏移速度比例。
scroll_view_set_slide_limit_ratio	设置滑动到极限时可继续滑动区域的占比。
scroll_view_scroll_to	滚动到指定的偏移量。
scroll_view_scroll_delta_to	滚动到指定的偏移量。
scroll_view_get_widget_vtable	获取 scroll_view 虚表。

2. 属性

scroll_view还提供了下面属性，详见下表：

属性名称	类型	说明
virtual_w	wh_t	虚拟宽度。
virtual_h	wh_t	虚拟高度。
xoffset	int32_t	x偏移量。
yoffset	int32_t	y偏移量。
xspeed_scale	float_t	x偏移速度比例。
yspeed_scale	float_t	y偏移速度比例。
xslidable	bool_t	是否允许x方向滑动。
yslidable	bool_t	是否允许y方向滑动。
snap_to_page	bool_t	滚动时offset是否按页面对齐。
move_to_page	bool_t	是否每次翻一页（当 move_to_page 为ture 的时候才有效果，主要用于区分一次翻一页还是一次翻多页）。
recursive	bool_t	是否递归查找全部子控件。
slide_limit_ratio	float_t	滑动到极限时可继续滑动区域的占比。

3. 样式

scroll_view可设置的样式，详见canvas_widget一节的样式小节。样式设置代码如下：

<scroll_view>
    <style name="default" text_color="white">
        <normal bg_color="#292929"/>
    </style>
</scroll_view>

4. 事件

scroll_view还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_SCROLL_START	event_t	开始滚动事件。
EVT_SCROLL_END	event_t	结束滚动事件。
EVT_SCROLL	event_t	滚动事件。
EVT_PAGE_CHANGED	event_t	页面改变事件。
EVT_PAGE_CHANGING	event_t	页面正在改变。

5. 示例

• 在xml中，使用"scroll_view"标签创建滚动视图，代码如下：

<!-- awtk/demos/assets/default/raw/ui/selectm.xml -->
<dialog anim_hint="bottom_to_top" x="0" y="bottom" w="100%" h="160">
  <dialog_title style="empty" x="0" y="0" w="100%" h="30">
    <button name="quit" x="5" y="middle" w="60" h="-4" text="Done"/>
    <label x="center" y="middle" w="128" h="-4" text="Select multiple"/>
    <button name="quit" x="right:5" y="middle" w="60" h="-4" text="Cancel"/>
  </dialog_title>
  <dialog_client x="0" y="bottom" w="100%" h="-30">
  <list_view x="0"  y="0" w="100%" h="100%" item_height="30">
    <scroll_view name="view" x="0"  y="0" w="100%" h="100%">
     <check_button style="odd_icon_right" name="c1" text="Book"/>
     <check_button style="even_icon_right" name="c2" text="Pencil"/>
     <check_button style="odd_icon_right" name="c1" text="Food"/>
     <check_button style="even_icon_right" name="c2" text="Bike"/>
    </scroll_view>
    <scroll_bar_m name="bar" x="right" y="0" w="6" h="100%" value="0"/>
  </list_view>
  </dialog_client>
</dialog>

图4.85 在xml中创建scroll_view的效果

4.8.27 mutable_image

mutable图片控件。像摄像头和视频的图像是变化的，每一帧都不同，把这类图片称为mutable image。本控件辅助实现摄像头和视频的显示功能。mutable_image_t是image_base_t的子类控件，image_base_t的函数均适用于mutable_image_t控件。

1. 函数

mutable_image提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
mutable_image_create	创建mutable_image对象
mutable_image_set_need_redraw	设置need_redraw回调函数。
mutable_image_set_prepare_image	设置prepare_image回调函数。
mutable_image_set_create_image	设置create_image回调函数。
mutable_image_set_framebuffer	设置framebuffer(当硬件支持多层合成时才用)。
mutable_image_cast	转换为mutable_image对象(供脚本语言使用)。
mutable_image_init	初始化 mutable_image （提供给继承的子类使用的）
mutable_image_on_destroy	释放 mutable_image （提供给继承的子类使用的）
mutable_image_on_paint_self	mutable_image 的绘制函数 （提供给继承的子类使用的）
mutable_image_get_widget_vtable	获取 mutable_image 虚表。

2. 示例

• 在xml中，使用"mutable_image"标签创建mutable图片控件，代码如下：

<mutable_image w="100%" h="100%"/>

• 在C代码中，使用函数mutable_image_create创建mutable图片控件，代码如下：

widget_t* image = mutable_image_create(win, 10, 10, 200, 200);
mutable_image_set_prepare_image(image, get_camera_image, camera);

4.8.28 mledit

多行编辑器控件。mledit_t是widget_t的子类控件，widget_t的函数均适用于mledit_t控件。

1. 函数

mledit提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
mledit_create	创建mledit对象
mledit_set_readonly	设置编辑器是否为只读。
mledit_set_cancelable	设置编辑器是否为可撤销修改。
mledit_set_focus	设置为焦点。
mledit_set_wrap_word	设置编辑器是否自动折行。
mledit_set_overwrite	设置编辑器是否启用覆盖行（在行数达到最大行数时，可继续新增行，但最早的行将会消失）。
mledit_set_max_lines	设置编辑器的最大行数。
mledit_set_max_chars	设置编辑器的最大字符数（0 为不限制字符数）。
mledit_set_tips	设置编辑器的输入提示。
mledit_set_tr_tips	获取翻译之后的文本，然后调用mledit_set_tips。
mledit_set_keyboard	设置自定义软键盘名称。
mledit_set_cursor	设置编辑器光标位置。
mledit_get_cursor	获取编辑器光标位置。
mledit_set_scroll_line	设置编辑器滚动速度。
mledit_scroll_to_offset	设置编辑器滚动到指定偏移位置。
mledit_set_open_im_when_focused	设置编辑器是否在获得焦点时打开输入法。
mledit_set_close_im_when_blured	设置编辑器是否在失去焦点时关闭输入法。
mledit_set_select	选择编辑器中指定范围的文本。
mledit_get_selected_text	获取选中的文本。
mledit_insert_text	插入一段文本。
mledit_cast	转换为mledit对象(供脚本语言使用)。
mledit_get_widget_vtable	获取 mledit 虚表。

2. 属性

mledit还提供了下面属性，详见下表：

属性名称	类型	说明
tips	char*	输入提示。
tr_tips	char*	保存用于翻译的提示信息。
keyboard	char*	自定义软键盘名称。
max_lines	uint32_t	最大行数。
max_chars	uint32_t	最大字符数。
scroll_line	uint32_t	鼠标一次滚动行数。
overwrite	bool_t	是否启用覆盖行。
wrap_word	bool_t	是否自动折行。
readonly	bool_t	编辑器是否为只读。
cancelable	bool_t	是否支持撤销编辑。如果为TRUE，在失去焦点之前可以撤销所有修改(恢复获得焦点之前的内容)。
open_im_when_focused	bool_t	获得焦点时打开输入法。
close_im_when_blured	bool_t	是否在失去焦点时关闭输入法(默认是)。

3. 样式

mledit可设置的样式，详见edit一节的样式小节，样式设置代码如下：

<mledit selected_fg_color="#020202" selected_text_color="#010101" selected_bg_color="#b5d7fd">
  <style name="default" border_color="#a0a0a0"  text_color="black" text_align_h="left">
    <normal     bg_color="#f0f0f0" />
    <focused    bg_color="#f0f0f0" border_color="black"/>
    <disable    bg_color="gray" text_color="#d0d0d0" />
    <error      bg_color="#f0f0f0" text_color="red" />
    <empty      bg_color="#f0f0f0" text_color="#a0a0a0" />
    <empty_focus bg_color="#f0f0f0" text_color="#a0a0a0" border_color="black"/>
  </style>
</mledit>

4. 事件

mledit还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_CHANGING	value_change_event_t	文本正在改变事件(编辑中)。
EVT_VALUE_CHANGED	value_change_event_t	文本改变事件(编辑完成或设置文本时触发)。

5. 示例

• 在xml中，使用"mledit"标签创建多行编辑器控件，代码如下。其中使用的样式详见上文样式一节。

<window anim_hint="htranslate" >
  <mledit x="c" y="10" h="40%" w="90%" focus="true" left_margin="33" top_margin="2" bottom_margin="2" right_margin="16" wrap_word="true" max_lines="100">
   <line_number x="0" y="0" w="32" h="100%" value="0"/>
   <scroll_bar_d x="right" y="0" w="14" h="100%" value="0"/>
 </mledit>
 <mledit x="c" y="b:10" h="40%" w="90%" wrap_word="false">
 </mledit>
</window>

图4.86 在xml中实现mledit的效果

4.8.29 line_number

行号。多行编辑器的行号。line_number_t是widget_t的子类控件，widget_t的函数均适用于line_number_t控件。

1. 函数

line_number提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
line_number_create	创建line_number对象
line_number_set_top_margin	设置顶部边距。
line_number_set_bottom_margin	设置顶部边距。
line_number_set_line_height	设置行高。
line_number_set_yoffset	设置y偏移。
line_number_set_lines_of_each_row	设置每一个逻辑行(row)占几个物理行(line)。
line_number_cast	转换为line_number对象(供脚本语言使用)。
line_number_add_highlight_line	增加高亮行。
line_number_set_active_line	设置active行。
line_number_clear_highlight	清除高亮行。
line_number_is_highlight_line	判断指定行是否是高亮行。
line_number_get_widget_vtable	获取 line_number 虚表。

2. 样式

line_number可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
fg_color	前景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

样式设置代码如下：

<line_number>
  <style name="default">
    <normal text_color="black" bg_color="#d0d0d0" text_align_h="right"/>
  </style>
</line_number>

3. 示例

• 在xml中，使用"line_number"标签创建line_number控件，代码如下，运行效果详见mledit一节中的示例。

<!-- awtk/demos/assets/default/raw/ui/mledit.xml -->
<window anim_hint="htranslate" >
  <mledit x="c" y="10" h="40%" w="90%" focus="true" 
    left_margin="33" top_margin="2" bottom_margin="2" right_margin="16" wrap_word="true" 
	max_lines="100">
   <line_number x="0" y="0" w="32" h="100%" value="0"/>
   <scroll_bar_d x="right" y="0" w="14" h="100%" value="0"/>
 </mledit>
 <mledit x="c" y="b:10" h="40%" w="90%" wrap_word="false">
 </mledit>
</window>

4.8.30 slide_indicator

slide_view的指示器控件。支持直线、弧线排布，默认有4种绘制样式，若设置了icon/active_icon，则优先使用icon/active_icon。slide_indicator_t是widget_t的子类控件，widget_t的函数均适用于slide_indicator_t控件。

1. 函数

slide_indicator提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
slide_indicator_create	创建slide_indicator对象
slide_indicator_create_linear	创建slide_indicator对象（线性显示）
slide_indicator_create_arc	创建slide_indicator对象（圆弧显示）
slide_indicator_cast	转换为slide_indicator对象(供脚本语言使用)。
slide_indicator_set_value	设置当前页的序号。
slide_indicator_set_max	设置指示器的数量。
slide_indicator_set_default_paint	设置指示器的默认绘制类型。
slide_indicator_set_auto_hide	设置指示器是否自动隐藏。
slide_indicator_set_margin	设置指示器的边距(默认为10像素)。
slide_indicator_set_spacing	设置指示器的间距(指示器有弧度时为角度值，否则为直线间距)。
slide_indicator_set_size	设置指示器的大小(默认为8)。
slide_indicator_set_anchor	设置旋转锚点。
slide_indicator_set_indicated_target	设置指示器指示的目标。
slide_indicator_set_transition	设置是否启用过渡效果。

2. 属性

slide_indicator还提供了下面属性，详见下表：

属性名称	类型	说明
value	uint32_t	值(缺省为0)。
max	uint32_t	最大值(缺省为100)。
default_paint	indicator_default_paint_t	指示器的类型。
auto_hide	uint16_t	自动隐藏。0表示禁止，非0表示无操作后延迟多久隐藏。
margin	int32_t	指示器与边缘的边距。
spacing	float_t	指示器的中心之间的间距（圆弧显示时，间距的单位为弧度，否则为像素）。
size	uint32_t	指示器的大小。
anchor_x	char*	锚点x坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)
anchor_y	char*	锚点y坐标。(后面加上px为像素点，不加px为相对百分比坐标0.0f到1.0f)
indicated_target	char*	指示器指示的目标控件的名称。
transition	bool_t	是否启用过渡效果。

default_paint 属性指示器的类型的取值详见下表：

指示器的类型	说明
stroke_dot	镂空圆点指示器，当前项填充selected_fg_color，其他镂空fg_color
fill_dot	实心圆点指示器，当前项填充selected_fg_color，其他填充fg_color
stroke_rect	镂空矩形指示器，当前项填充selected_fg_color，其他镂空fg_color
fill_rect	实心矩形指示器，当前项填充selected_fg_color，其他填充fg_color

3. 样式

slide_indicator可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见image 控件一节）
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
fg_color	前景颜色
selected_fg_color	编辑器（包括edit和mledit控件）中选中区域的背景颜色
icon	图标的名称
active_icon	active图标的名称
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

slide_indicator的样式示例代码如下：

<slide_indicator>
  <style name="default">
    <normal  fg_color="#ff000040" selected_fg_color="#ff0000"/>
  </style>
  <style name="blue">
    <normal  fg_color="#338fff40" selected_fg_color="#338fff"/>
  </style>
  <style name="icon">
    <normal  icon="dot" active_icon="active_dot"/>
  </style>
</slide_indicator>

4. 事件

slide_indicator还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VALUE_WILL_CHANGE	value_change_event_t	值(当前页的序号)即将改变事件。
EVT_VALUE_CHANGED	value_change_event_t	值(当前页的序号)改变事件。
EVT_PAGE_CHANGED	event_t	页面改变事件。
EVT_PAGE_CHANGING	event_t	页面正在改变。

5. 示例

• 在xml中，使用"slide_indicator"标签创建slide_indicator控件，代码如下，其中使用的样式详见上文样式一节。

<window anim_hint="htranslate" text="Landscape">
  <slide_view x="0" y="0" w="100%" h="100%" vertical="true">
    <view x="0" y="0" w="100%" h="100%">
        <label x="c" y="m" w="20%" h="10%" text = "first"/>
    </view>
    <view x="0" y="0" w="100%" h="100%">
        <label x="c" y="m" w="20%" h="10%" text = "secend"/>
    </view>
    <view x="0" y="0" w="100%" h="100%">
        <label x="c" y="m" w="20%" h="10%" text = "third"/>
    </view>
  </slide_view>
  <slide_indicator x="0" y="b" w="100%" h="20"/>
</window>

运行效果如下图所示：

图4.87 在xml中创建slide_indicator的效果

4.8.31 hscroll_label

可水平滚动的文本控件，方便实现长文本滚动。hscroll_label_t是widget_t的子类控件，widget_t的函数均适用于hscroll_label_t控件。

1. 函数

hscroll_label提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
hscroll_label_create	创建hscroll_label对象
hscroll_label_set_lull	设置lull。
hscroll_label_set_duration	设置duration。
hscroll_label_set_speed	设置speed（设置后 duration 不生效）。
hscroll_label_set_only_focus	设置only_focus。
hscroll_label_set_only_parent_focus	设置only_parent_focus。
hscroll_label_set_loop	设置loop。
hscroll_label_set_yoyo	设置yoyo。
hscroll_label_set_ellipses	设置ellipses。
hscroll_label_set_stop_at_begin	设置stop_at_begin。
hscroll_label_set_xoffset	设置x偏移(一般无需用户调用)。。
hscroll_label_start	启动(一般无需用户调用)。
hscroll_label_stop	停止(一般无需用户调用)。
hscroll_label_cast	转换为hscroll_label对象(供脚本语言使用)。
hscroll_label_get_widget_vtable	获取 hscroll_label 虚表。

2. 属性

hscroll_label还提供了下面属性，详见下表：

属性名称	类型	说明
only_focus	bool_t	只有处于focus时才滚动(缺省否)。
only_parent_focus	bool_t	只有父控件处于focus时才滚动(缺省否)。
loop	bool_t	loop是否循环滚动(缺省FALSE)。
yoyo	bool_t	是否往返滚动(缺省FALSE)。
ellipses	bool_t	文本显示不下时，在行尾显示省略号(缺省FALSE)。
lull	int32_t	滚动之间的间歇时间(ms)，缺省3000ms。
duration	int32_t	完整的滚动一次需要的时间(ms)，缺省5000ms。
speed	float_t	滚动速度(px/ms)（设置后 duration 不生效）。
xoffset	int32_t	偏移量。
text_w	int32_t	文本的宽度。
stop_at_begin	bool_t	滚动完毕后停在文本开头(缺省FALSE)。

3. 样式

hscroll_label可设置的样式，详见下表：

样式属性	说明
bg_color	背景颜色
font_name	字体名称
font_size	字体大小
text_color	文本颜色
text_align_h	文本水平对齐的方式（取值：center|left|right）
text_align_v	文本垂直对齐的方式（取值：middle|top|bottom）
border_color	边框颜色
border_width	边框线宽
border	边框类型（取值：all|top|bottom|left|right）
bg_image	背景图片的名称
bg_image_draw_type	背景图片的显示方式（取值：详见表4.27）
margin	边距
margin_left	左边距
margin_right	右边距
margin_top	顶边距
margin_bottom	底边距
x_offset	x方向的偏移，方便实现按下的效果
y_offset	y方向的偏移，方便实现按下的效果
round_radius	圆角半径(仅在with_vgcanvas定义时生效)
round_radius_top_left	左上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_top_right	右上角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_left	左下角圆角半径(仅with_vgcanvas定义时生效)
round_radius_bottom_right	右下角圆角半径(仅with_vgcanvas定义时生效)

4. 示例

• 在xml中，使用"hscroll_label"标签创建hscroll_label控件，代码如下：

<window anim_hint="htranslate" text="hscroll_label" children_layout="default(c=1,h=30,xm=10,s=5)">
  <hscroll_label text="炫酷的 GUI 引擎。" />
  <hscroll_label 
    lull="1000"
    loop="true"
    yoyo="true"
    ellipses="true"
    focusable="true"
    text="(always ellipses loop yoyo)为用户提供一个功能强大、高效可靠、简单易用、
	     可轻松做出炫酷效果的 GUI 引擎。文字滚动效果呢。。。" />
</window>

运行效果如下所示：

图4.88 在xml中创建hscroll_label的效果

4.8.32 serial_widget

用于串口通信的控件，可以通过该控件简单地控制串口，serial_widget_t是widget_t的子类控件，widget_t的函数均适用于serial_widget_t控件。

1. 函数

serial_widget提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
serial_widget_create	创建serial_widget对象
serial_widget_cast	转换为serial_widget对象(供脚本语言使用)。
serial_widget_set_baudrate	设置 波特率。
serial_widget_set_device	设置 设备。
serial_widget_set_bytesize	设置 字节位数。
serial_widget_set_parity	设置 奇偶校验。
serial_widget_set_stopbits	设置 停止位。
serial_widget_set_flowcontrol	设置 流控。
serial_widget_set_check_interval	设置 轮询时间。
serial_widget_get_widget_vtable	获取 serial_widget 虚表。

2. 属性

serial_widget还提供了下面属性，详见下表：

属性名称	类型	说明
device	char*	设备(文件)名。
baudrate	uint32_t	波特率。
bytesize	uint32_t	字节位数。
parity	uint32_t	奇偶校验。
stopbits	uint32_t	停止位。
flowcontrol	uint32_t	流控。
istream	tk_istream_t*	输入流。
ostream	tk_ostream_t*	输出流。
iostream	tk_iostream_t*	输入/出流。
check_interval	uint32_t	轮询时间（单位：ms）。

3. 事件

serial_widget还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_DATA	event_t	数据到来事件。

4. 示例

• 在xml中，使用"serial"标签创建serial_widget控件，代码如下：

<window text="serial">
  <serial device="COM1" baudrate="115200"/>
</window>

4.8.33 timer_widget

定时器。主要目的是方便以拖拽的方式创建定时器。timer_widget_t是widget_t的子类控件，widget_t的函数均适用于timer_widget_t控件。

1. 函数

timer_widget提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
timer_widget_create	创建timer_widget对象
timer_widget_cast	转换为timer_widget对象(供脚本语言使用)。
timer_widget_set_duration	设置 时长(ms)。
timer_widget_get_widget_vtable	获取 timer_widget 虚表。

2. 属性

timer_widget还提供了下面属性，详见下表：

属性名称	类型	说明
duration	uint32_t	时长(ms)。

3. 事件

timer_widget还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_TIMER	event_t	定时器事件。

4. 示例

• 在xml中，使用"timer"标签创建timer_widget控件，代码如下：

<window text="timer">
  <timer x="c" y="50" w="100" h="100" duration="1000"/>
</window> 

4.8.34 vpage

虚拟页面(根据情况自动加载/卸载页面，并提供入场/出场动画)。虚拟页面只能作为pages的直接子控件使用。如果指定了ui_asset:

1. 当页面切换到后台时自动卸载，并触发EVT_VPAGE_CLOSE消息。
2. 当页面切换到前台时自动加载，在动画前出发EVT_VPAGE_WILL_OPEN消息，在动画完成时触发 EVT_VPAGE_CLOSE消息。

1. 函数

vpage提供的函数详见下表，具体请查看AWTK_API手册。

函数名称	说明
vpage_create	创建vpage对象
vpage_cast	转换为vpage对象(供脚本语言使用)。
vpage_set_ui_asset	设置 UI资源名称。
vpage_set_anim_hint	设置动画类型(vtranslate: 垂直平移，htranslate: 水平平移)。
vpage_get_widget_vtable	获取 vpage 虚表。

2. 属性

vpage还提供了下面属性，详见下表：

属性名称	类型	说明
ui_asset	char*	UI资源名称。
anim_hint	char*	动画类型(目前支持：vtranslate: 垂直平移，htranslate: 水平平移)。

3. 事件

vpage还提供了下面事件，详见下表：

事件名称	类型	说明
EVT_VPAGE_WILL_OPEN	event_t	页面即将打开(动画前)。
EVT_VPAGE_OPEN	event_t	页面打开完成(动画后)。
EVT_VPAGE_CLOSE	event_t	页面已经关闭(动画后)。

4. 示例

• 在xml中，使用"vpage"标签创建vpage控件，代码如下：

<!-- awtk/design/default/ui/vpage_vtrans.xml -->
<window text="VPage V Translate">
  <pages name="pages" x="31%" y="0" w="68%" h="100%" style="at_top">
    <vpage name="page1" w="100%" h="100%" ui_asset="tab_button_view_page1" anim_hint="vtranslate" />
    <vpage name="page2" w="100%" h="100%" ui_asset="tab_button_view_page2" anim_hint="vtranslate" />
    <vpage name="page3" w="100%" h="100%" anim_hint="vtranslate" >
      <label x="c" y="m" w="200" h="30" text="page3" />
      <button x="c" y="b:10" w="128" h="30" text="close" on:click="back()"/>
    </vpage>
</window>

4.9 自定义控件

除了使用AWTK内置的控件外，还可以自定义控件，其步骤如下：

1. 注册控件
2. 创建控件
3. 使用控件

如果想在AWTK Designer中导入自定义控件使用，那么就需要在Designer中新建自定义控件项目，新建完成后可以得到一个空白控件的框架，用户需要遵循 AWTK自定义控件规范 (opens new window) 实现控件代码。

下面以Chart-Demo演示例子中的饼图为例，看看如何实现自定义控件的。代码可以从 GitHub (opens new window) 下载，效果详见下图：

图4.89 饼图

4.9.1 注册控件

使用widget_factory_register函数注册控件，控件的类型为WIDGET_TYPE_PIE_SLICE，控件的创建函数是pie_slice_create，代码如下：

/* Chart-Demo/src/custom_widgets/custom_widgets.c */
ret_t custom_widgets_init() {
  ...
  widget_factory_register(widget_factory(), WIDGET_TYPE_PIE_SLICE, pie_slice_create);

  return RET_OK;
}

例如，在编写的UI文件中（res_800_480/assets/default/raw/ui/window_pie.xml）使用了pie_slice控件，那么AWTK在解析该XML的时候根据WIDGET_TYPE_PIE_SLICE判断是不是AWTK内置的控件。如果不是，就会根据WIDGET_TYPE_PIE_SLICE找到注册的pie_slice_create函数，然后调用该函数创建控件。

4.9.2 创建控件

要创建控件就需要了解一下struct widget_vtable_t结构体，该结构体中的成员主要完成控件的创建、响应事件以及子控件的布局等。

AWTK提供了非常便捷和灵活的方式，只需重新实现struct widget_vtable_t结构体中的几个成员函数就可以完成创建控件，通常需要实现的函数如下：

• create 控件创建函数
• on_paint_self 控件自绘函数
• on_event 控件响应键盘、鼠标等事件函数
• get_prop 获取控件属性函数
• set_prop 设置控件属性函数

其他的根据需要实现struct widget_vtable_t结构体中的成员，代码详见下文。

创建控件主要有两个步骤：

步骤一：定义struct widget_vtable_t变量

/* awtk/src/base/widget.h */
struct _widget_vtable_t {
  ...
  widget_create_t create;
  widget_get_prop_t get_prop;
  widget_get_prop_default_value_t get_prop_default_value;
  widget_set_prop_t set_prop;
  widget_on_keyup_t on_keyup;
  widget_on_keydown_t on_keydown;
  widget_on_paint_background_t on_paint_background;
  widget_on_paint_self_t on_paint_self;
  widget_on_paint_children_t on_paint_children;
  widget_on_paint_border_t on_paint_border;
  widget_on_paint_begin_t on_paint_begin;
  widget_on_paint_end_t on_paint_end;
  widget_on_pointer_down_t on_pointer_down;
  widget_on_pointer_move_t on_pointer_move;
  widget_on_pointer_up_t on_pointer_up;
  widget_on_layout_children_t on_layout_children;
  widget_invalidate_t invalidate;
  widget_on_add_child_t on_add_child;
  widget_on_remove_child_t on_remove_child;
  widget_on_event_t on_event;
  widget_on_event_before_children_t on_event_before_children;
  widget_find_target_t find_target;
  widget_on_destroy_t on_destroy;
};

饼图pie_slice实现的结构成员，代码如下：

/* Chart-Demo/src/custom_widgets/pie_slice/pie_slice.c */
static const widget_vtable_t s_pie_slice_vtable = {.size = sizeof(pie_slice_t),
                                         .type = WIDGET_TYPE_PIE_SLICE,
                                         .clone_properties = s_pie_slice_clone_properties,
                                         .create = pie_slice_create,
                                         .on_paint_self = pie_slice_on_paint_self,
                                         .on_event = pie_slice_on_event,
                                         .get_prop = pie_slice_get_prop,
                                         .set_prop = pie_slice_set_prop};

步骤二：实现struct widget_vtable_t中的结构成员

上个步骤中定义了s_pie_slice_vtable变量，它的各个结构成员所代表的含义请看下文。

(1) size

表示的是饼图pie_slice_t的大小，此时就需要定义struct pie_slice_t了，代码如下：

/* Chart-Demo/src/custom_widgets/pie_slice/pie_slice.h */
typedef struct _pie_slice_t {
  widget_t widget;
  /**
   * @property {float_t} value
   * @annotation ["set_prop","get_prop","readable","persitent","design","scriptable"]
   * 值(缺省为0)。
   */
  float_t value;
  /**
   * @property {uint32_t} max
   * @annotation ["set_prop","get_prop","readable","persitent","design","scriptable"]
   * 最大值(缺省为100)。
   */
  uint32_t max;
  /* ... */
} pie_slice_t;

(2) type

控件的类型，这个类型在注册控件的时候也会用到。

(3) clone_properties

克隆widget时需要复制的属性。

(4) create

创建控件函数，这个函数在注册控件的时候也会用到。在这个函数中主要为pie_slice_t分配内存以及初始化，还有就是将s_pie_slice_vtable赋值给pie_slice_t，代码如下：

/* Chart-Demo/src/custom_widgets/pie_slice/pie_slice.c */
widget_t* pie_slice_create(widget_t* parent, xy_t x, xy_t y, wh_t w, wh_t h) {
  pie_slice_t* pie_slice = TKMEM_ZALLOC(pie_slice_t);
  widget_t* widget = WIDGET(pie_slice);
  return_value_if_fail(pie_slice != NULL, NULL);

  widget_init(widget, parent, &s_pie_slice_vtable, x, y, w, h);

  pie_slice->max = 100;
  pie_slice->inner_radius = 8;
  pie_slice->start_angle = 0;
  pie_slice->show_text = FALSE;
  pie_slice->counter_clock_wise = FALSE;
  pie_slice->is_exploded = FALSE;
  pie_slice->explode_distancefactor = 25;
  pie_slice->is_semicircle = FALSE;

  return widget;
}

(5) on_paint_self

控件的自绘函数，在这函数中通过调用vgcanvas或者canvas接口绘制相应的图形。在饼图这个例子中调用了vgcanvas接口完成了饼图的绘制，代码如下：

/* Chart-Demo/src/custom_widgets/pie_slice/pie_slice.c */
static ret_t pie_slice_on_paint_self(widget_t* widget, canvas_t* c) {
  bitmap_t img;
  style_t* style = widget->astyle;
  color_t trans = color_init(0, 0, 0, 0);
  vgcanvas_t* vg = canvas_get_vgcanvas(c);
  pie_slice_t* pie_slice = PIE_SLICE(widget);
  color_t color = style_get_color(style, STYLE_ID_FG_COLOR, trans);
  const char* image_name = style_get_str(style, STYLE_ID_FG_IMAGE, NULL);
  bool_t has_image = image_name && widget_load_image(widget, image_name, &img) == RET_OK;

  if (pie_slice->value > pie_slice->max) {
    pie_slice->value = pie_slice->max;
  }

  if (vg != NULL && (has_image || color.rgba.a)) {
    xy_t cx = widget->w / 2;
    xy_t cy = widget->h / 2;
    float_t end_angle = 0;
    float_t r = 0;
    bool_t ccw = pie_slice->counter_clock_wise;
    float_t start_angle = TK_D2R(pie_slice->start_angle);
    float_t angle = (M_PI * 2 * pie_slice->value) / pie_slice->max;

    if (ccw) {
      end_angle = start_angle - angle + M_PI * 2;
    } else {
      end_angle = start_angle + angle;
    }

    vgcanvas_save(vg);
    vgcanvas_translate(vg, c->ox, c->oy);
    if (end_angle > start_angle) {
      vgcanvas_set_fill_color(vg, color);
      vgcanvas_begin_path(vg);
      r = tk_min(cx, cy);
      r -= pie_slice->explode_distancefactor;

      if (pie_slice->is_semicircle) {
        if (ccw) {
          start_angle = M_PI * 2 - (start_angle + angle) / 2;
          end_angle = start_angle + angle / 2;
          cy = cy + r * 0.5;
          r += pie_slice->explode_distancefactor * 1.5;
          vgcanvas_arc(vg, cx, cy, r, start_angle, end_angle, !ccw);
          r -= pie_slice->inner_radius;
          vgcanvas_arc(vg, cx, cy, r, end_angle, start_angle, ccw);
        }
      } else {
        vgcanvas_arc(vg, cx, cy, r, start_angle, end_angle, ccw);
        if (r - pie_slice->inner_radius <= 0) {
          vgcanvas_line_to(vg, cx, cy);
        } else {
          r -= pie_slice->inner_radius;
          vgcanvas_arc(vg, cx, cy, r, end_angle, start_angle, !ccw);
        }
      }

      vgcanvas_close_path(vg);
      if (has_image) {
        vgcanvas_paint(vg, FALSE, &img);
      } else {
        vgcanvas_fill(vg);
      }
    }
    vgcanvas_restore(vg);
  }

  color = style_get_color(style, STYLE_ID_TEXT_COLOR, trans);
  if (pie_slice->show_text && color.rgba.a) {
    char s[TK_NUM_MAX_LEN + TK_NUM_MAX_LEN + 1];
    const char* unit = pie_slice->unit != NULL ? pie_slice->unit : "";
    tk_snprintf(s, sizeof(s), "%u%s", (uint32_t)(pie_slice->value), unit);

    widget_set_text_utf8(widget, s);
    widget_paint_helper(widget, c, NULL, NULL);
  }

  return RET_OK;
}

(6) on_event

键盘和鼠标响应事件，如果想通过键盘或者鼠标完成某些特定的功能，就可以在这个函数中实现。例如在本例中实现了点击某个扇形的时候展开，代码如下：

/* Chart-Demo/src/custom_widgets/pie_slice/pie_slice.c */
static ret_t pie_slice_on_event(widget_t* widget, event_t* e) {
  uint16_t type = e->type;
  pie_slice_t* pie_slice = PIE_SLICE(widget);
  switch (type) {
    case EVT_POINTER_DOWN: {
      pie_slice->pressed = TRUE;
      xy_t cx = widget->w / 2;
      xy_t cy = widget->h / 2;
      float_t r = tk_min(cx, cy) - pie_slice->explode_distancefactor;
      pointer_event_t* pointer_event = (pointer_event_t*)e;
      point_t p = {pointer_event->x, pointer_event->y};
      widget_to_local(widget, &p);
      int32_t x_f = p.x - widget->w * 0.5;
      int32_t y_f = p.y - widget->h * 0.5;
      pie_slice_t* iter_result = pie_slice_get_clicked_pie(widget, pie_slice, r, &x_f, &y_f);
      if (iter_result == NULL) {
        break;
      }
      pie_slice_on_event_4_pointer_down(widget, pie_slice, r, x_f, y_f, iter_result);
      break;
    }
    case EVT_POINTER_UP: {
      pointer_event_t evt = *(pointer_event_t*)e;
      if (pie_slice->pressed && widget_is_point_in(widget, evt.x, evt.y, FALSE)) {
        evt.e = event_init(EVT_CLICK, widget->parent);
        widget_dispatch(widget, (event_t*)&evt);
        pie_slice->pressed = FALSE;
      }
      break;
    }
    default:
      break;
  }

  return RET_OK;
}

(7) get_prop

获取属性值，可以调用widget_get_prop（最终会调用pie_slice_get_prop函数）函数获取属性值，例如想要获取struct pie_slice_t中is_exploded成员的值，代码如下：

/* Chart-Demo/src/window_pie.c */
static ret_t create_animator_to_zero(widget_t* win) {
  set_btn_enable(win, FALSE);

  widget_t* pie_view = widget_lookup(win, "pie_view", TRUE);
  if (pie_view) {
    WIDGET_FOR_EACH_CHILD_BEGIN_R(pie_view, iter, i)
    value_t v;
    widget_get_prop(iter, PIE_SLICE_PROP_IS_EXPLODED, &v);
    save_pie_exploded[i] = value_bool(&v);

    pie_slice_t* pie_slice = PIE_SLICE(iter);
    if (pie_slice->is_exploded) {
      pie_slice_set_exploded(iter);
    }
    int32_t delay = 80;
    delay = delay * (nr - 1 - i);
    char param[100];
    tk_snprintf(param, sizeof(param), "value(to=0, duration=50, delay=%d, easing=sin_out)", delay);
    widget_create_animator(iter, param);
    WIDGET_FOR_EACH_CHILD_END();
  }

  return RET_OK;
}

(8) set_prop

设置属性值。可以调用widget_set_prop（最终会调用pie_slice_set_prop函数）函数设置属性值，例如想要设置struct pie_slice_t中is_exploded成员的值，代码如下：

/* Chart-Demo/src/window_pie.c */
static ret_t on_save_exploded_timer(const timer_info_t* timer) {
  widget_t* win = WIDGET(timer->ctx);

  uint32_t count = widget_animator_manager_count(widget_animator_manager());
  if (count == 0) {
    widget_t* pie_view = widget_lookup(win, "pie_view", TRUE);
    if (pie_view) {
      WIDGET_FOR_EACH_CHILD_BEGIN_R(pie_view, iter, i)
      value_t v;
      value_set_bool(&v, !save_pie_exploded[i]);
      widget_set_prop(iter, PIE_SLICE_PROP_IS_EXPLODED, &v);
      pie_slice_set_exploded(iter);
      WIDGET_FOR_EACH_CHILD_END();
    }
    set_btn_enable(win, TRUE);

    return RET_REMOVE;
  }

  return RET_REPEAT;
}

4.9.3 使用控件

注册和创建好控件就可以使用了，使用的方法和AWTK内置的控件一样。例如通过编写XML文件使用pie_slice饼图控件，代码如下：

<!-- Chart-Demo/res_800_480/assets/default/raw/ui/window_pie.xml -->
<window anim_hint="htranslate" tr_text="pie_title" x="0%" y="50" w="800" h="427" >
    <view name="pie_view" x="2%" y="m" w="60%" h="80%">
        <pie_slice name="pie1_slice" w="100%" h="100%" max="360" start_angle="0" value="0" show_text="false" inner_radius="550" style="pie1"/>
        <pie_slice name="pie2_slice" w="100%" h="100%" max="360" start_angle="0" value="0" show_text="false" inner_radius="550" style="pie2"/>
        <pie_slice name="pie3_slice" w="100%" h="100%" max="360" start_angle="0" value="0" show_text="false" inner_radius="550" style="pie3"/>
        <pie_slice name="pie4_slice" w="100%" h="100%" max="360" start_angle="0" value="0" show_text="false" inner_radius="550" style="pie4"/>
        <pie_slice name="pie5_slice" w="100%" h="100%" max="360" start_angle="0" value="0" show_text="false" inner_radius="550" style="pie5"/>
        <pie_slice name="pie6_slice" w="100%" h="100%" max="360" start_angle="0" value="0" show_text="false" inner_radius="550" style="pie6"/>
    </view>
    ...
</window>

XML文件中pie_slice里面的start_angle、show_text等设置的值，会调用pie_slice_set_prop函数，给对应的对象设置相应的值。