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 函数

• 函数功能：

加入一个子控件。

• 函数原型：

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

• 参数说明：

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);

• 参数说明：

widget_add_value 函数

• 函数功能：

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

• 函数原型：

ret_t widget_add_value (widget_t* widget, int32_t delta);

• 参数说明：

widget_animate_value_to 函数

• 函数功能：

设置控件的值(以动画形式变化到指定的值)。
只是对widget_set_prop的包装，值的意义由子类控件决定。

• 函数原型：

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

• 参数说明：

widget_cast 函数

• 函数功能：

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

• 函数原型：

widget_t* widget_cast (widget_t* widget);

• 参数说明：

widget_child 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_child_on 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_clone 函数

• 函数功能：

clone。

• 函数原型：

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

• 参数说明：

widget_count_children 函数

• 函数功能：

获取子控件的个数。

• 函数原型：

int32_t widget_count_children (widget_t* widget);

• 参数说明：

widget_create_animator 函数

• 函数功能：

创建动画。
请参考控件动画

• 除非指定auto_start=false，动画创建后自动启动。
• 除非指定auto_destroy=false，动画播放完成后自动销毁。

• 函数原型：

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

• 参数说明：

widget_destroy 函数

• 函数功能：

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

• 函数原型：

ret_t widget_destroy (widget_t* widget);

• 参数说明：

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);

• 参数说明：

widget_destroy_children 函数

• 函数功能：

销毁全部子控件。

• 函数原型：

ret_t widget_destroy_children (widget_t* widget);

• 参数说明：

widget_dispatch 函数

• 函数功能：

分发一个事件。

• 函数原型：

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

• 参数说明：

widget_equal 函数

• 函数功能：

判断两个widget是否相同。

• 函数原型：

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

• 参数说明：

widget_foreach 函数

• 函数功能：

遍历当前控件及子控件。

• 函数原型：

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

• 参数说明：

widget_get_child 函数

• 函数功能：

获取指定索引的子控件。

• 函数原型：

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

• 参数说明：

widget_get_prop 函数

• 函数功能：

获取控件指定属性的值。

• 函数原型：

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

• 参数说明：

widget_get_prop_bool 函数

• 函数功能：

获取布尔格式的属性。

• 函数原型：

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

• 参数说明：

widget_get_prop_default_value 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_get_prop_int 函数

• 函数功能：

获取整数格式的属性。

• 函数原型：

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

• 参数说明：

widget_get_prop_pointer 函数

• 函数功能：

获取指针格式的属性。

• 函数原型：

void* widget_get_prop_pointer (widget_t* widget, const char* name);

• 参数说明：

widget_get_prop_str 函数

• 函数功能：

获取字符串格式的属性。

• 函数原型：

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

• 参数说明：

widget_get_text 函数

• 函数功能：

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

• 函数原型：

wchar_t* widget_get_text (widget_t* widget);

• 参数说明：

widget_get_type 函数

• 函数功能：

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

• 函数原型：

char* widget_get_type (widget_t* widget);

• 参数说明：

widget_get_value 函数

• 函数功能：

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

• 函数原型：

int32_t widget_get_value (widget_t* widget);

• 参数说明：

widget_get_window 函数

• 函数功能：

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

• 函数原型：

widget_t* widget_get_window (widget_t* widget);

• 参数说明：

widget_get_window_manager 函数

• 函数功能：

获取当前的窗口管理器。

• 函数原型：

widget_t* widget_get_window_manager (widget_t* widget);

• 参数说明：

widget_grab 函数

• 函数功能：

让指定子控件抓住事件。
控件抓住之后，事件直接分发给该控件。

• 函数原型：

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

• 参数说明：

widget_index_of 函数

• 函数功能：

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

• 函数原型：

int32_t widget_index_of (widget_t* widget);

• 参数说明：

widget_insert_child 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_invalidate 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_invalidate_force 函数

• 函数功能：

请求强制重绘控件。

• 函数原型：

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

• 参数说明：

widget_is_designing_window 函数

• 函数功能：

判断当前控件是否是设计窗口。

• 函数原型：

bool_t widget_is_designing_window (widget_t* widget);

• 参数说明：

widget_is_window 函数

• 函数功能：

判断当前控件是否是窗口。

• 函数原型：

bool_t widget_is_window (widget_t* widget);

• 参数说明：

widget_is_window_manager 函数

• 函数功能：

判断当前控件是否是窗口管理器。

• 函数原型：

bool_t widget_is_window_manager (widget_t* widget);

• 参数说明：

widget_is_window_opened 函数

• 函数功能：

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

• 函数原型：

bool_t widget_is_window_opened (widget_t* widget);

• 参数说明：

widget_layout 函数

• 函数功能：

布局当前控件及子控件。

• 函数原型：

ret_t widget_layout (widget_t* widget);

• 参数说明：

widget_layout_children 函数

• 函数功能：

layout子控件。

• 函数原型：

ret_t widget_layout_children (widget_t* widget);

• 参数说明：

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);

• 参数说明：

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);

• 参数说明：

widget_lookup 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_lookup_by_type 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_move 函数

• 函数功能：

移动控件。

• 函数原型：

ret_t widget_move (widget_t* widget, xy_t x, 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);

• 参数说明：

widget_off 函数

• 函数功能：

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

• 函数原型：

ret_t widget_off (widget_t* widget, int32_t id);

• 参数说明：

widget_off_by_func 函数

• 函数功能：

注销指定事件的处理函数。
仅用于辅助实现脚本绑定。

• 函数原型：

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

• 参数说明：

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);

• 参数说明：

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);

• 参数说明：

widget_remove_child 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_resize 函数

• 函数功能：

调整控件的大小。

• 函数原型：

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

• 参数说明：

widget_restack 函数

• 函数功能：

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

• 函数原型：

ret_t widget_restack (widget_t* widget, uint32_t index);

• 参数说明：

widget_set_animation 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

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);

• 参数说明：

widget_set_children_layout 函数

• 函数功能：

设置子控件的布局参数。

• 函数原型：

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

• 参数说明：

widget_set_cursor 函数

• 函数功能：

设置鼠标指针的图片名。

• 函数原型：

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

• 参数说明：

widget_set_enable 函数

• 函数功能：

设置控件的可用性。

• 函数原型：

ret_t widget_set_enable (widget_t* widget, bool_t enable);

• 参数说明：

widget_set_floating 函数

• 函数功能：

设置控件的floating标志。

• 函数原型：

ret_t widget_set_floating (widget_t* widget, bool_t floating);

• 参数说明：

widget_set_focused 函数

• 函数功能：

设置控件的是否聚焦。

• 函数原型：

ret_t widget_set_focused (widget_t* widget, bool_t focused);

• 参数说明：

widget_set_name 函数

• 函数功能：

设置控件的名称。

• 函数原型：

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

• 参数说明：

widget_set_opacity 函数

• 函数功能：

设置控件的不透明度。

• 函数原型：

ret_t widget_set_opacity (widget_t* widget, uint8_t opacity);

• 参数说明：

widget_set_prop 函数

• 函数功能：

设置控件指定属性的值。

• 函数原型：

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

• 参数说明：

widget_set_prop_bool 函数

• 函数功能：

设置布尔格式的属性。

• 函数原型：

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

• 参数说明：

widget_set_prop_int 函数

• 函数功能：

设置整数格式的属性。

• 函数原型：

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

• 参数说明：

widget_set_prop_pointer 函数

• 函数功能：

设置指针格式的属性。

• 函数原型：

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

• 参数说明：

widget_set_prop_str 函数

• 函数功能：

设置字符串格式的属性。

• 函数原型：

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

• 参数说明：

widget_set_self_layout 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

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);

• 参数说明：

widget_set_sensitive 函数

• 函数功能：

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

• 函数原型：

ret_t widget_set_sensitive (widget_t* widget, bool_t sensitive);

• 参数说明：

widget_set_state 函数

• 函数功能：

设置控件的状态。

• 函数原型：

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

• 参数说明：

widget_set_text 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_set_text_utf8 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_set_tr_text 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_set_value 函数

• 函数功能：

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

• 函数原型：

ret_t widget_set_value (widget_t* widget, int32_t value);

• 参数说明：

widget_set_visible 函数

• 函数功能：

设置控件的可见性。

• 函数原型：

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

• 参数说明：

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);

• 参数说明：

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);

• 参数说明：

widget_to_global 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_to_local 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_to_screen 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

widget_ungrab 函数

• 函数功能：

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

• 函数原型：

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

• 参数说明：

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);

• 参数说明：

widget_unload_image 函数

• 函数功能：

卸载图片。

一般不需要调用，只有确认在图片不再需要时才调用本函数卸载。

• 函数原型：

ret_t widget_unload_image (widget_t* widget, bitmap_t* bitmap);

• 参数说明：

widget_use_style 函数

• 函数功能：

启用指定的主题。

• 函数原型：

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

• 参数说明：

animation 属性

动画参数。请参考控件动画

• 类型：char*

astyle 属性

Style对象。

• 类型：style_t*

auto_created 属性

是否由父控件自动创建。

• 类型：bool_t

can_not_destroy 属性

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

• 类型：uint16_t

children 属性

全部子控件。

• 类型：darray_t*

children_layout 属性

子控件布局器。请参考控件布局参数

• 类型：children_layouter_t*

custom_props 属性

自定义属性。

• 类型：object_t*

destroying 属性

标识控件正在被销毁。

• 类型：bool_t

dirty 属性

标识控件是否需要重绘。

• 类型：bool_t

emitter 属性

事件发射器。

• 类型：emitter_t*

enable 属性

启用/禁用状态。

• 类型：bool_t

floating 属性

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

• 类型：bool_t

focused 属性

是否得到焦点。

• 类型：bool_t

grab_widget 属性

grab事件的子控件。

• 类型：widget_t*

h 属性

高度。

• 类型：wh_t

initializing 属性

标识控件正在初始化。

• 类型：bool_t

key_target 属性

接收按键事件的子控件。

• 类型：widget_t*

name 属性

控件名字。

• 类型：char*

need_relayout_children 属性

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

• 类型：bool_t

opacity 属性

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

• 类型：uint8_t

parent 属性

父控件

• 类型：widget_t*

self_layout 属性

控件布局器。请参考控件布局参数

• 类型：self_layouter_t*

sensitive 属性

是否接受用户事件。

• 类型：bool_t

state 属性

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

• 类型：uint8_t

style 属性

style的名称。

• 类型：char*

target 属性

接收事件的子控件。

• 类型：widget_t*

text 属性

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

• 类型：wstr_t

tr_text 属性

保存用于翻译的字符串。

• 类型：char*

visible 属性

是否可见。

• 类型：bool_t

vt 属性

虚函数表。

• 类型：widget_vtable_t

w 属性

宽度。

• 类型：wh_t

x 属性

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

• 类型：xy_t

y 属性

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

• 类型：xy_t