awtk/widget_t.md at 1980eb8df6f5cae0d5be5ac61d0d6aed04b4a16b

test/awtk

Fork 0

mirror of https://gitee.com/zlgopen/awtk.git synced 2024-11-30 02:58:26 +08:00

xianjimli 1980eb8df6 update docs

2019-01-15 14:34:05 +08:00

66 KiB

Raw Blame History

widget_t

概述

widget_t 是所有控件、窗口和窗口管理器的基类。 widget_t也是一个容器，可放其它widget_t到它的内部，形成一个树形结构。

通常widget_t通过一个矩形区域向用户呈现一些信息，接受用户的输入，并据此做出适当的反应。它负责控件的生命周期、通用状态、事件分发和Style的管理。本类提供的接口(函数和属性)除非特别说明，一般都适用于子类控件。

为了便于解释，这里特别说明一下几个术语：

父控件与子控件：父控件与子控件指的两个控件的组合关系(这是在运行时决定的)。比如：在窗口中放一个按钮，此时，我们称按钮是窗口的子控件，窗口是按钮的父控件。

子类控件与父类控件：子类控件与父类控件指的两类控件的继承关系(这是在设计时决定的)。比如：我们称button_t是widget_t的子类控件，widget_t是button_t的父类控件。

widget相关的函数都只能在GUI线程中执行，如果需在非GUI线程中想调用widget相关函数，请用idle_queue或timer_queue进行串行化。请参考demo thread

widget_t是抽象类，不要直接创建widget_t的实例。控件支持两种创建方式：

通过XML创建。如：

<button x="c" y="m" w="80" h="30" text="OK"/>

通过代码创建。如：

 widget_t* button = button_create(win, 10, 10, 128, 30);
 widget_set_text(button, L"OK");
 widget_on(button, EVT_CLICK, on_click, NULL);

函数

函数名称	说明
widget_add_child	加入一个子控件。
widget_add_timer	创建定时器。
widget_add_value	增加控件的值。
widget_animate_value_to	设置控件的值(以动画形式变化到指定的值)。
widget_cast	转换为widget对象(供脚本语言使用)。
widget_child	查找指定名称的子控件(同widget_lookup(widget, name, FALSE))。
widget_child_on	为指定名称的子控件注册指定事件的处理函数。
widget_clone	clone。
widget_count_children	获取子控件的个数。
widget_create_animator	创建动画。
widget_destroy	销毁控件。
widget_destroy_animator	销毁动画。
widget_destroy_children	销毁全部子控件。
widget_dispatch	分发一个事件。
widget_equal	判断两个widget是否相同。
widget_foreach	遍历当前控件及子控件。
widget_get_child	获取指定索引的子控件。
widget_get_prop	获取控件指定属性的值。
widget_get_prop_bool	获取布尔格式的属性。
widget_get_prop_default_value	获取控件指定属性的缺省值(在持久化控件时，无需保存缺省值)。
widget_get_prop_int	获取整数格式的属性。
widget_get_prop_str	获取字符串格式的属性。
widget_get_text	获取控件的文本。
widget_get_type	获取当前控件的类型名称。
widget_get_value	获取控件的值。只是对widget_get_prop的包装，值的意义由子类控件决定。
widget_get_window	获取当前控件所在的窗口。
widget_get_window_manager	获取当前的窗口管理器。
widget_grab	让指定子控件抓住事件。
widget_index_of	获取控件在父控件中的索引编号。
widget_insert_child	插入子控件到指定的位置。
widget_invalidate	请求重绘指定的区域，如果widget->dirty已经为TRUE，直接返回。
widget_invalidate_force	请求强制重绘控件。
widget_is_window_opened	判断当前控件所在的窗口是否已经打开。
widget_layout	布局当前控件及子控件。
widget_layout_children	layout子控件。
widget_load_asset	加载资源。
widget_load_image	加载图片。
widget_lookup	查找指定名称的子控件(返回第一个)。
widget_lookup_by_type	查找指定类型的子控件(返回第一个)。
widget_move	移动控件。
widget_move_resize	移动控件并调整控件的大小。
widget_off	注销指定事件的处理函数。
widget_off_by_func	注销指定事件的处理函数。
widget_on	注册指定事件的处理函数。
widget_pause_animator	暂停动画。
widget_remove_child	移出指定的子控件(并不销毁)。
widget_resize	调整控件的大小。
widget_restack	调整控件在父控件中的位置序数。
widget_set_animation	设置控件的动画参数(仅用于在UI文件使用)。
widget_set_animator_time_scale	设置动画的时间倍率，<0: 时间倒退，<1: 时间变慢，>1 时间变快。
widget_set_children_layout	设置子控件的布局参数。
widget_set_cursor	设置鼠标指针的图片名。
widget_set_enable	设置控件的可用性。
widget_set_floating	设置控件的floating标志。
widget_set_focused	设置控件的是否聚焦。
widget_set_name	设置控件的名称。
widget_set_opacity	设置控件的不透明度。
widget_set_prop	设置控件指定属性的值。
widget_set_prop_bool	设置布尔格式的属性。
widget_set_prop_int	设置整数格式的属性。
widget_set_prop_str	设置字符串格式的属性。
widget_set_self_layout	设置控件自己的布局参数。
widget_set_self_layout_params	设置控件自己的布局(缺省布局器)参数(过时，请用widget_set_self_layout)。
widget_set_sensitive	设置控件是否接受用户事件。
widget_set_state	设置控件的状态。
widget_set_text	设置控件的文本。
widget_set_text_utf8	设置控件的文本。
widget_set_tr_text	获取翻译之后的文本，然后调用widget_set_text。
widget_set_value	设置控件的值。
widget_set_visible	设置控件的可见性。
widget_start_animator	播放动画。
widget_stop_animator	停止动画(控件的相应属性回归原位)。
widget_to_global	将控件内的本地坐标转换成全局坐标。
widget_to_local	将屏幕坐标转换成控件内的本地坐标，即相对于控件左上角的坐标。
widget_to_screen	将控件内的本地坐标转换成屏幕上的坐标。
widget_ungrab	让指定子控件放弃抓住事件。
widget_unload_asset	卸载资源。
widget_use_style	启用指定的主题。

属性

名属性称	类型	说明
animation	char*	动画参数。请参考控件动画
astyle	style_t*	Style对象。
auto_created	bool_t	是否由父控件自动创建。
can_not_destroy	uint16_t	标识控件目前不能被销毁(比如正在分发事件)，如果此时调用widget_destroy，自动异步处理。
children	array_t*	全部子控件。
children_layout	children_layouter_t*	子控件布局器。请参考控件布局参数
custom_props	custom_props_t*	自定义属性。
destroying	bool_t	标识控件正在被销毁。
dirty	bool_t	标识控件是否需要重绘。
emitter	emitter_t*	事件发射器。
enable	bool_t	启用/禁用状态。
floating	bool_t	标识控件是否启用浮动布局，不受父控件的children_layout的控制。
focused	bool_t	是否得到焦点。
grab_widget	widget_t*	grab事件的子控件。
h	wh_t	高度。
key_target	widget_t*	接收按键事件的子控件。
name	char*	控件名字。
need_relayout_children	bool_t	标识控件是否需要重新layout子控件。
opacity	uint8_t	不透明度(0-255)，0完全透明，255完全不透明。
parent	widget_t*	父控件
self_layout	self_layouter_t*	控件布局器。请参考控件布局参数
sensitive	bool_t	是否接受用户事件。
state	uint8_t	控件的状态(取值参考widget_state_t)。
style	char*	style的名称。
target	widget_t*	接收事件的子控件。
text	wstr_t	文本。用途视具体情况而定。
tr_text	char*	保存用于翻译的字符串。
visible	bool_t	是否可见。
vt	widget_vtable_t	虚函数表。
w	wh_t	宽度。
x	xy_t	x坐标(相对于父控件的x坐标)。
y	xy_t	y坐标(相对于父控件的y坐标)。

事件

事件名称	类型	说明
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_PROP_WILL_CHANGE	prop_change_event_t	控件属性改变前触发(通过set_prop设置属性，才会触发)。
EVT_PROP_CHANGED	prop_change_event_t	控件属性改变后触发(通过set_prop设置属性，才会触发)。
EVT_BEFORE_PAINT	paint_event_t	控件绘制前触发。
EVT_AFTER_PAINT	paint_event_t	控件绘制完成时触发。
EVT_FOCUS	event_t	控件得到焦点时触发。
EVT_BLUR	event_t	控件失去焦点时触发。
EVT_WHEEL	wheel_event_t	鼠标滚轮事件。
EVT_POINTER_LEAVE	pointer_event_t	鼠标指针离开控件时触发。
EVT_POINTER_ENTER	pointer_event_t	鼠标指针进入控件时触发。
EVT_KEY_DOWN	pointer_event_t	键按下事件。
EVT_KEY_UP	pointer_event_t	键释放事件。
EVT_POINTER_DOWN	pointer_event_t	指针设备按下事件。
EVT_POINTER_DOWN_ABORT	pointer_event_t	取消指针设备按下事件。
EVT_POINTER_MOVE	pointer_event_t	指针设备移动事件。
EVT_POINTER_UP	pointer_event_t	指针设备释放事件。
EVT_DESTROY	event_t	控件销毁时触发。

widget_add_child 函数

函数功能：

加入一个子控件。

函数原型：

ret_t widget_add_child (widget_t* widget, widget_t* child);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
child	widget_t*	子控件对象。

widget_add_timer 函数

函数功能：

创建定时器。

该定时器在控件销毁时自动销毁，timer_info_t的ctx为widget。如果定时器的生命周期与控件无关，请直接调用timer_add，以避免不必要的内存开销。

使用示例：

static ret_t digit_clock_on_timer(const timer_info_t* info) {
 widget_t* widget = WIDGET(info->ctx);

 return RET_REPEAT;
}
...
widget_add_timer(widget, digit_clock_on_timer, 1000);

函数原型：

uint32_t widget_add_timer (widget_t* widget, timer_func_t on_timer, uint32_t duration_ms);

参数说明：

参数	类型	说明
返回值	uint32_t	返回timer的ID，TK_INVALID_ID表示失败。
widget	widget_t*	控件对象。
on_timer	timer_func_t	timer回调函数。
duration_ms	uint32_t	时间。

widget_add_value 函数

函数功能：

增加控件的值。

只是对widget_set_prop的包装，值的意义由子类控件决定。

函数原型：

ret_t widget_add_value (widget_t* widget, int32_t delta);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
delta	int32_t	增量。

widget_animate_value_to 函数

函数功能：

设置控件的值(以动画形式变化到指定的值)。

只是对widget_set_prop的包装，值的意义由子类控件决定。

函数原型：

ret_t widget_animate_value_to (widget_t* widget, int32_t value, uint32_t duration);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
value	int32_t	值。
duration	uint32_t	动画持续时间(毫秒)。

widget_cast 函数

函数功能：

转换为widget对象(供脚本语言使用)。

函数原型：

widget_t* widget_cast (widget_t* widget);

参数说明：

参数	类型	说明
返回值	widget_t*	widget对象。
widget	widget_t*	widget对象。

widget_child 函数

函数功能：

查找指定名称的子控件(同widget_lookup(widget, name, FALSE))。

函数原型：

widget_t* widget_child (widget_t* widget, char* name);

参数说明：

参数	类型	说明
返回值	widget_t*	子控件或NULL。
widget	widget_t*	控件对象。
name	char*	子控件的名称。

widget_child_on 函数

函数功能：

为指定名称的子控件注册指定事件的处理函数。

递归查找指定名称的子控件，然后为其注册指定事件的处理函数。

函数原型：

int32_t widget_child_on (widget_t* widget, char* name, uint32_t type, event_func_t on_event, void* ctx);

参数说明：

参数	类型	说明
返回值	int32_t	返回id，用于widget_off。
widget	widget_t*	控件对象。
name	char*	子控件的名称。
type	uint32_t	事件类型。
on_event	event_func_t	事件处理函数。
ctx	void*	事件处理函数上下文。

widget_clone 函数

函数功能：

clone。

函数原型：

widget_t* widget_clone (widget_t* widget, widget_t* parent);

参数说明：

参数	类型	说明
返回值	widget_t*	返回clone的对象。
widget	widget_t*	控件对象。
parent	widget_t*	clone新控件的parent对象。

widget_count_children 函数

函数功能：

获取子控件的个数。

函数原型：

int32_t widget_count_children (widget_t* widget);

参数说明：

参数	类型	说明
返回值	int32_t	子控件的个数。
widget	widget_t*	控件对象。

widget_create_animator 函数

函数功能：

创建动画。

请参考控件动画

除非指定auto_start=false，动画创建后自动启动。
除非指定auto_destroy=false，动画播放完成后自动销毁。
函数原型：

ret_t widget_create_animator (widget_t* widget, const char* animation);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
animation	const char*	动画参数。

widget_destroy 函数

函数功能：

销毁控件。

一般无需直接调用，关闭窗口时，自动销毁相关控件。

函数原型：

ret_t widget_destroy (widget_t* widget);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。

widget_destroy_animator 函数

函数功能：

销毁动画。

请参考控件动画

1.widget为NULL时，销毁所有名称为name的动画。
2.name为NULL时，销毁所有widget相关的动画。
3.widget和name均为NULL，销毁所有动画。
函数原型：

ret_t widget_destroy_animator (widget_t* widget, char* name);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	char*	动画名称。

widget_destroy_children 函数

函数功能：

销毁全部子控件。

函数原型：

ret_t widget_destroy_children (widget_t* widget);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。

widget_dispatch 函数

函数功能：

分发一个事件。

函数原型：

ret_t widget_dispatch (widget_t* widget, event_t* e);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
e	event_t*	事件。

widget_equal 函数

函数功能：

判断两个widget是否相同。

函数原型：

bool_t widget_equal (widget_t* widget, widget_t* other);

参数说明：

参数	类型	说明
返回值	bool_t	返回TRUE表示相同，否则表示不同。
widget	widget_t*	控件对象。
other	widget_t*	要比较的控件对象。

widget_foreach 函数

函数功能：

遍历当前控件及子控件。

函数原型：

ret_t widget_foreach (widget_t* widget, tk_visit_t visit, void* ctx);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
visit	tk_visit_t	遍历的回调函数。
ctx	void*	回调函数的上下文。

widget_get_child 函数

函数功能：

获取指定索引的子控件。

函数原型：

widget_t* widget_get_child (widget_t* widget, int32_t index);

参数说明：

参数	类型	说明
返回值	widget_t*	子控件。
widget	widget_t*	控件对象。
index	int32_t	索引。

widget_get_prop 函数

函数功能：

获取控件指定属性的值。

函数原型：

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

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
v	value_t*	返回属性的值。

widget_get_prop_bool 函数

函数功能：

获取布尔格式的属性。

函数原型：

bool_t widget_get_prop_bool (widget_t* widget, const char* name, bool_t defval);

参数说明：

参数	类型	说明
返回值	bool_t	返回属性的值。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
defval	bool_t	缺省值。

widget_get_prop_default_value 函数

函数功能：

获取控件指定属性的缺省值(在持久化控件时，无需保存缺省值)。

函数原型：

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

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
v	value_t*	返回属性的缺省值。

widget_get_prop_int 函数

函数功能：

获取整数格式的属性。

函数原型：

int32_t widget_get_prop_int (widget_t* widget, const char* name, int32_t defval);

参数说明：

参数	类型	说明
返回值	int32_t	返回属性的值。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
defval	int32_t	缺省值。

widget_get_prop_str 函数

函数功能：

获取字符串格式的属性。

函数原型：

const char* widget_get_prop_str (widget_t* widget, const char* name, const char* defval);

参数说明：

参数	类型	说明
返回值	const char*	返回属性的值。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
defval	const char*	缺省值。

widget_get_text 函数

函数功能：

获取控件的文本。

只是对widget_get_prop的包装，文本的意义由子类控件决定。

函数原型：

wchar_t* widget_get_text (widget_t* widget);

参数说明：

参数	类型	说明
返回值	wchar_t*	返回文本。
widget	widget_t*	控件对象。

widget_get_type 函数

函数功能：

获取当前控件的类型名称。

函数原型：

char* widget_get_type (widget_t* widget);

参数说明：

参数	类型	说明
返回值	char*	返回类型名。
widget	widget_t*	控件对象。

widget_get_value 函数

函数功能：

获取控件的值。只是对widget\_get\_prop的包装，值的意义由子类控件决定。

函数原型：

int32_t widget_get_value (widget_t* widget);

参数说明：

参数	类型	说明
返回值	int32_t	返回值。
widget	widget_t*	控件对象。

widget_get_window 函数

函数功能：

获取当前控件所在的窗口。

函数原型：

widget_t* widget_get_window (widget_t* widget);

参数说明：

参数	类型	说明
返回值	widget_t*	窗口对象。
widget	widget_t*	控件对象。

widget_get_window_manager 函数

函数功能：

获取当前的窗口管理器。

函数原型：

widget_t* widget_get_window_manager (widget_t* widget);

参数说明：

参数	类型	说明
返回值	widget_t*	窗口管理器对象。
widget	widget_t*	控件对象。

widget_grab 函数

函数功能：

让指定子控件抓住事件。

控件抓住之后，事件直接分发给该控件。

函数原型：

ret_t widget_grab (widget_t* widget, widget_t* child);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
child	widget_t*	子控件对象。

widget_index_of 函数

函数功能：

获取控件在父控件中的索引编号。

函数原型：

int32_t widget_index_of (widget_t* widget);

参数说明：

参数	类型	说明
返回值	int32_t	在父控件中的索引编号。
widget	widget_t*	控件对象。

widget_insert_child 函数

函数功能：

插入子控件到指定的位置。

函数原型：

ret_t widget_insert_child (widget_t* widget, uint32_t index, widget_t* child);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
index	uint32_t	位置序数(大于等于总个数，则放到最后)。
child	widget_t*	子控件对象。

widget_invalidate 函数

函数功能：

请求重绘指定的区域，如果widget->dirty已经为TRUE，直接返回。

函数原型：

ret_t widget_invalidate (widget_t* widget, rect_t* r);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
r	rect_t*	矩形对象(widget本地坐标)。

widget_invalidate_force 函数

函数功能：

请求强制重绘控件。

函数原型：

ret_t widget_invalidate_force (widget_t* widget, rect_t* r);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
r	rect_t*	矩形对象(widget本地坐标)。

widget_is_window_opened 函数

函数功能：

判断当前控件所在的窗口是否已经打开。

函数原型：

bool_t widget_is_window_opened (widget_t* widget);

参数说明：

参数	类型	说明
返回值	bool_t	返回当前控件所在的窗口是否已经打开。
widget	widget_t*	控件对象。

widget_layout 函数

函数功能：

布局当前控件及子控件。

函数原型：

ret_t widget_layout (widget_t* widget);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	widget对象。

widget_layout_children 函数

函数功能：

layout子控件。

函数原型：

ret_t widget_layout_children (widget_t* widget);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。

widget_load_asset 函数

函数功能：

加载资源。

使用示例：

const asset_info_t* asset = widget_load_asset(widget, ASSET_TYPE_IMAGE, "mysvg");
...
widget_unload_asset(widget, asset);

函数原型：

const asset_info_t* widget_load_asset (widget_t* widget, asset_type_t type, const char* name);

参数说明：

参数	类型	说明
返回值	const asset_info_t*	返回资源句柄。
widget	widget_t*	控件对象。
type	asset_type_t	资源类型。
name	const char*	资源名。

widget_load_image 函数

函数功能：

加载图片。

返回的bitmap对象只在当前调用有效，请不保存对bitmap对象的引用。

使用示例：

bitmap_t bitmap;
widget_load_image(widget, "myimage", &bitmap);

函数原型：

ret_t widget_load_image (widget_t* widget, const char* name, bitmap_t* bitmap);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	图片名(不带扩展名)。
bitmap	bitmap_t*	返回图片对象。

widget_lookup 函数

函数功能：

查找指定名称的子控件(返回第一个)。

函数原型：

widget_t* widget_lookup (widget_t* widget, char* name, bool_t recursive);

参数说明：

参数	类型	说明
返回值	widget_t*	子控件或NULL。
widget	widget_t*	控件对象。
name	char*	子控件的名称。
recursive	bool_t	是否递归查找全部子控件。

widget_lookup_by_type 函数

函数功能：

查找指定类型的子控件(返回第一个)。

函数原型：

widget_t* widget_lookup_by_type (widget_t* widget, char* type, bool_t recursive);

参数说明：

参数	类型	说明
返回值	widget_t*	子控件或NULL。
widget	widget_t*	控件对象。
type	char*	子控件的名称。
recursive	bool_t	是否递归查找全部子控件。

widget_move 函数

函数功能：

移动控件。

函数原型：

ret_t widget_move (widget_t* widget, xy_t x, xy_t y);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
x	xy_t	x坐标
y	xy_t	y坐标

widget_move_resize 函数

函数功能：

移动控件并调整控件的大小。

函数原型：

ret_t widget_move_resize (widget_t* widget, xy_t x, xy_t y, wh_t w, wh_t h);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
x	xy_t	x坐标
y	xy_t	y坐标
w	wh_t	宽度
h	wh_t	高度

widget_off 函数

函数功能：

注销指定事件的处理函数。

函数原型：

ret_t widget_off (widget_t* widget, int32_t id);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
id	int32_t	widget_on返回的ID。

widget_off_by_func 函数

函数功能：

注销指定事件的处理函数。

仅用于辅助实现脚本绑定。

函数原型：

ret_t widget_off_by_func (widget_t* widget, uint32_t type, event_func_t on_event, void* ctx);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
type	uint32_t	事件类型。
on_event	event_func_t	事件处理函数。
ctx	void*	事件处理函数上下文。

widget_on 函数

函数功能：

注册指定事件的处理函数。

使用示例：

widget_t* ok = button_create(win, 10, 10, 80, 30);
widget_on(ok, EVT_CLICK, on_click, NULL);

函数原型：

int32_t widget_on (widget_t* widget, uint32_t type, event_func_t on_event, void* ctx);

参数说明：

参数	类型	说明
返回值	int32_t	返回id，用于widget_off。
widget	widget_t*	控件对象。
type	uint32_t	事件类型。
on_event	event_func_t	事件处理函数。
ctx	void*	事件处理函数上下文。

widget_pause_animator 函数

函数功能：

暂停动画。

请参考控件动画

1.widget为NULL时，暂停所有名称为name的动画。
2.name为NULL时，暂停所有widget相关的动画。
3.widget和name均为NULL，暂停所有动画。
函数原型：

ret_t widget_pause_animator (widget_t* widget, char* name);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	char*	动画名称。

widget_remove_child 函数

函数功能：

移出指定的子控件(并不销毁)。

函数原型：

ret_t widget_remove_child (widget_t* widget, widget_t* child);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
child	widget_t*	子控件对象。

widget_resize 函数

函数功能：

调整控件的大小。

函数原型：

ret_t widget_resize (widget_t* widget, wh_t w, wh_t h);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
w	wh_t	宽度
h	wh_t	高度

widget_restack 函数

函数功能：

调整控件在父控件中的位置序数。

函数原型：

ret_t widget_restack (widget_t* widget, uint32_t index);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
index	uint32_t	位置序数(大于等于总个数，则放到最后)。

widget_set_animation 函数

函数功能：

设置控件的动画参数(仅用于在UI文件使用)。

请参考控件动画

函数原型：

ret_t widget_set_animation (widget_t* widget, const char* animation);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
animation	const char*	动画参数。

widget_set_animator_time_scale 函数

函数功能：

设置动画的时间倍率，<0: 时间倒退，<1: 时间变慢，>1 时间变快。

请参考控件动画

1.widget为NULL时，设置所有名称为name的动画的时间倍率。
2.name为NULL时，设置所有widget相关的动画的时间倍率。
3.widget和name均为NULL，设置所有动画的时间倍率。
函数原型：

ret_t widget_set_animator_time_scale (widget_t* widget, const char* name, float_t time_scale);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	动画名称。
time_scale	float_t	时间倍率。

widget_set_children_layout 函数

函数功能：

设置子控件的布局参数。

函数原型：

ret_t widget_set_children_layout (widget_t* widget, const char* params);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
params	const char*	布局参数。

widget_set_cursor 函数

函数功能：

设置鼠标指针的图片名。

函数原型：

ret_t widget_set_cursor (widget_t* widget, char* cursor);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
cursor	char*	图片名称(无扩展名)。

widget_set_enable 函数

函数功能：

设置控件的可用性。

函数原型：

ret_t widget_set_enable (widget_t* widget, bool_t enable);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
enable	bool_t	是否可用性。

widget_set_floating 函数

函数功能：

设置控件的floating标志。

函数原型：

ret_t widget_set_floating (widget_t* widget, bool_t floating);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
floating	bool_t	是否启用floating布局。

widget_set_focused 函数

函数功能：

设置控件的是否聚焦。

函数原型：

ret_t widget_set_focused (widget_t* widget, bool_t focused);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
focused	bool_t	是否聚焦。

widget_set_name 函数

函数功能：

设置控件的名称。

函数原型：

ret_t widget_set_name (widget_t* widget, char* name);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	char*	名称。

widget_set_opacity 函数

函数功能：

设置控件的不透明度。

函数原型：

ret_t widget_set_opacity (widget_t* widget, uint8_t opacity);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
opacity	uint8_t	不透明度。

widget_set_prop 函数

函数功能：

设置控件指定属性的值。

函数原型：

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

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
v	value_t*	属性的值。

widget_set_prop_bool 函数

函数功能：

设置布尔格式的属性。

函数原型：

ret_t widget_set_prop_bool (widget_t* widget, const char* name, bool_t v);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
v	bool_t	属性的值。

widget_set_prop_int 函数

函数功能：

设置整数格式的属性。

函数原型：

ret_t widget_set_prop_int (widget_t* widget, const char* name, int32_t v);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
v	int32_t	属性的值。

widget_set_prop_str 函数

函数功能：

设置字符串格式的属性。

函数原型：

ret_t widget_set_prop_str (widget_t* widget, const char* name, const char* v);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	属性的名称。
v	const char*	属性的值。

widget_set_self_layout 函数

函数功能：

设置控件自己的布局参数。

函数原型：

ret_t widget_set_self_layout (widget_t* widget, const char* params);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
params	const char*	布局参数。

widget_set_self_layout_params 函数

函数功能：

设置控件自己的布局(缺省布局器)参数(过时，请用widget\_set\_self\_layout)。

函数原型：

ret_t widget_set_self_layout_params (widget_t* widget, const char* x, const char* y, const char* w, const char* h);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
x	const char*	x参数。
y	const char*	y参数。
w	const char*	w参数。
h	const char*	h参数。

widget_set_sensitive 函数

函数功能：

设置控件是否接受用户事件。

函数原型：

ret_t widget_set_sensitive (widget_t* widget, bool_t sensitive);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
sensitive	bool_t	是否接受用户事件。

widget_set_state 函数

函数功能：

设置控件的状态。

函数原型：

ret_t widget_set_state (widget_t* widget, const char* state);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
state	const char*	状态(必须为真正的常量字符串，在widget的整个生命周期有效)。

widget_set_text 函数

函数功能：

设置控件的文本。

只是对widget_set_prop的包装，文本的意义由子类控件决定。

函数原型：

ret_t widget_set_text (widget_t* widget, wchar_t* text);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
text	wchar_t*	文本。

widget_set_text_utf8 函数

函数功能：

设置控件的文本。

只是对widget_set_prop的包装，文本的意义由子类控件决定。

函数原型：

ret_t widget_set_text_utf8 (widget_t* widget, char* text);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
text	char*	文本。

widget_set_tr_text 函数

函数功能：

获取翻译之后的文本，然后调用widget_set_text。

函数原型：

ret_t widget_set_tr_text (widget_t* widget, char* text);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
text	char*	文本。

widget_set_value 函数

函数功能：

设置控件的值。

只是对widget_set_prop的包装，值的意义由子类控件决定。

函数原型：

ret_t widget_set_value (widget_t* widget, int32_t value);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
value	int32_t	值。

widget_set_visible 函数

函数功能：

设置控件的可见性。

函数原型：

ret_t widget_set_visible (widget_t* widget, bool_t visible, bool_t recursive);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
visible	bool_t	是否可见。
recursive	bool_t	是否递归设置全部子控件。

widget_start_animator 函数

函数功能：

播放动画。

请参考控件动画

1.widget为NULL时，播放所有名称为name的动画。
2.name为NULL时，播放所有widget相关的动画。
3.widget和name均为NULL，播放所有动画。
函数原型：

ret_t widget_start_animator (widget_t* widget, const char* name);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	const char*	动画名称。

widget_stop_animator 函数

函数功能：

停止动画(控件的相应属性回归原位)。

请参考控件动画

1.widget为NULL时，停止所有名称为name的动画。
2.name为NULL时，停止所有widget相关的动画。
3.widget和name均为NULL，停止所有动画。
函数原型：

ret_t widget_stop_animator (widget_t* widget, char* name);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
name	char*	动画名称。

widget_to_global 函数

函数功能：

将控件内的本地坐标转换成全局坐标。

函数原型：

ret_t widget_to_global (widget_t* widget, point_t* p);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
p	point_t*	坐标点。

widget_to_local 函数

函数功能：

将屏幕坐标转换成控件内的本地坐标，即相对于控件左上角的坐标。

函数原型：

ret_t widget_to_local (widget_t* widget, point_t* p);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
p	point_t*	坐标点。

widget_to_screen 函数

函数功能：

将控件内的本地坐标转换成屏幕上的坐标。

函数原型：

ret_t widget_to_screen (widget_t* widget, point_t* p);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
p	point_t*	坐标点。

widget_ungrab 函数

函数功能：

让指定子控件放弃抓住事件。

函数原型：

ret_t widget_ungrab (widget_t* widget, widget_t* child);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
child	widget_t*	子控件对象。

widget_unload_asset 函数

函数功能：

卸载资源。

使用示例：

const asset_info_t* asset = widget_load_asset(widget, ASSET_TYPE_IMAGE, "mysvg");
...
widget_unload_asset(widget, asset);

函数原型：

ret_t widget_unload_asset (widget_t* widget, const asset_info_t* asset);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
asset	const asset_info_t*	资源句柄。

widget_use_style 函数

函数功能：

启用指定的主题。

函数原型：

ret_t widget_use_style (widget_t* widget, char* style);

参数说明：

参数	类型	说明
返回值	ret_t	返回RET_OK表示成功，否则表示失败。
widget	widget_t*	控件对象。
style	char*	style的名称。

animation 属性

动画参数。请参考[控件动画](https://github.com/zlgopen/awtk/blob/master/docs/widget_animator.md)

类型：char*

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

astyle 属性

Style对象。

类型：style_t*

特性	是否支持
可直接读取	是
可直接修改	否

auto_created 属性

是否由父控件自动创建。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	否

can_not_destroy 属性

标识控件目前不能被销毁(比如正在分发事件)，如果此时调用widget\_destroy，自动异步处理。

类型：uint16_t

特性	是否支持
可直接读取	是
可直接修改	否

children 属性

全部子控件。

类型：array_t*

特性	是否支持
可直接读取	是
可直接修改	否

children_layout 属性

子控件布局器。请参考[控件布局参数](https://github.com/zlgopen/awtk/blob/master/docs/layout.md)

类型：children_layouter_t*

特性	是否支持
可直接读取	是
可直接修改	否
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

custom_props 属性

自定义属性。

类型：custom_props_t*

特性	是否支持
可直接读取	是
可直接修改	否

destroying 属性

标识控件正在被销毁。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	否

dirty 属性

标识控件是否需要重绘。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	否

emitter 属性

事件发射器。

类型：emitter_t*

特性	是否支持
可直接读取	是
可直接修改	否

enable 属性

启用/禁用状态。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

floating 属性

标识控件是否启用浮动布局，不受父控件的children_layout的控制。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

focused 属性

是否得到焦点。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	否

grab_widget 属性

grab事件的子控件。

类型：widget_t*

特性	是否支持
可直接读取	是
可直接修改	否

h 属性

高度。

类型：wh_t

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

key_target 属性

接收按键事件的子控件。

类型：widget_t*

特性	是否支持
可直接读取	是
可直接修改	否

name 属性

控件名字。

类型：char*

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

need_relayout_children 属性

标识控件是否需要重新layout子控件。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	否

opacity 属性

不透明度(0-255)，0完全透明，255完全不透明。

类型：uint8_t

特性	是否支持
可直接读取	是
可直接修改	否

parent 属性

父控件

类型：widget_t*

特性	是否支持
可直接读取	是
可直接修改	否

self_layout 属性

控件布局器。请参考[控件布局参数](https://github.com/zlgopen/awtk/blob/master/docs/layout.md)

类型：self_layouter_t*

特性	是否支持
可直接读取	是
可直接修改	否
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

sensitive 属性

是否接受用户事件。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	是
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

state 属性

控件的状态(取值参考widget_state_t)。

类型：uint8_t

特性	是否支持
可直接读取	是
可直接修改	否

style 属性

style的名称。

类型：char*

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

target 属性

接收事件的子控件。

类型：widget_t*

特性	是否支持
可直接读取	是
可直接修改	否

text 属性

文本。用途视具体情况而定。

类型：wstr_t

特性	是否支持
可直接读取	是
可直接修改	否

tr_text 属性

保存用于翻译的字符串。

类型：char*

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

visible 属性

是否可见。

类型：bool_t

特性	是否支持
可直接读取	是
可直接修改	是
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

vt 属性

虚函数表。

类型：widget_vtable_t

特性	是否支持
可直接读取	是
可直接修改	否

w 属性

宽度。

类型：wh_t

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

x 属性

x坐标(相对于父控件的x坐标)。

类型：xy_t

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

y 属性

y坐标(相对于父控件的y坐标)。

类型：xy_t

特性	是否支持
可直接读取	是
可直接修改	否
可持久化	是
可脚本化	是
可在IDE中设置	是
可在XML中设置	是
可通过widget_get_prop读取	是
可通过widget_set_prop修改	是

66 KiB Raw Blame History Unescape Escape

widget_t

概述

函数

属性

事件

widget_add_child 函数

widget_add_timer 函数

widget_add_value 函数

widget_animate_value_to 函数

widget_cast 函数

widget_child 函数

widget_child_on 函数

widget_clone 函数

widget_count_children 函数

widget_create_animator 函数

widget_destroy 函数

widget_destroy_animator 函数

widget_destroy_children 函数

widget_dispatch 函数

widget_equal 函数

widget_foreach 函数

widget_get_child 函数

widget_get_prop 函数

widget_get_prop_bool 函数

widget_get_prop_default_value 函数

widget_get_prop_int 函数

widget_get_prop_str 函数

widget_get_text 函数

widget_get_type 函数

widget_get_value 函数

widget_get_window 函数

widget_get_window_manager 函数

widget_grab 函数

widget_index_of 函数

widget_insert_child 函数

widget_invalidate 函数

widget_invalidate_force 函数

widget_is_window_opened 函数

widget_layout 函数

widget_layout_children 函数

widget_load_asset 函数

widget_load_image 函数

widget_lookup 函数

widget_lookup_by_type 函数

widget_move 函数

widget_move_resize 函数

widget_off 函数

widget_off_by_func 函数

widget_on 函数

widget_pause_animator 函数

widget_remove_child 函数

widget_resize 函数

widget_restack 函数

widget_set_animation 函数

widget_set_animator_time_scale 函数

widget_set_children_layout 函数

widget_set_cursor 函数

widget_set_enable 函数

widget_set_floating 函数

widget_set_focused 函数

widget_set_name 函数

widget_set_opacity 函数

widget_set_prop 函数

widget_set_prop_bool 函数

widget_set_prop_int 函数

widget_set_prop_str 函数

widget_set_self_layout 函数

widget_set_self_layout_params 函数

widget_set_sensitive 函数

widget_set_state 函数

widget_set_text 函数

widget_set_text_utf8 函数

widget_set_tr_text 函数

widget_set_value 函数

widget_set_visible 函数

widget_start_animator 函数

widget_stop_animator 函数

widget_to_global 函数

widget_to_local 函数

66 KiB

Raw Blame History