8 控件事件 | GT-HMI Engine 用户手册 | 高通字库

8. 控件事件

　　事件是对各种控件由于应用程序内部或者外部产生的事情或动作处理的通称，在高通 GT-HMI 中常见的事件为加载屏幕，背景、字体颜色变化，位置、大小变化等。事件通常使用 gt_obj_add_event_cb 函数为控件添加事件回调函数，在回调函数中实现对应的事件处理逻辑。

8.1 加载屏幕

　　加载屏幕事件为屏幕控件特有事件，主要用于屏幕页面间跳转使用。所有页面都由页栈进行管理。

　　首先，通过枚举变量给每个页面注册页面 ID：

typedef enum {
    GT_ID_SCREEN_HOME = 0,
    GT_ID_SCREEN_1 = 1,
    GT_ID_SCREEN_2 = 2,
    GT_ID_SCREEN_3 = 3,
    GT_ID_SCREEN_4 = 4,
} gt_scr_id_et;

　　其次，创建页面对象：

gt_obj_st * screen_1 = NULL;
gt_obj_st * gt_init_screen_1(void)
{
    screen_1 = gt_obj_create(NULL);
    gt_screen_set_bgcolor(screen_1, gt_color_hex(0xFFFFFF));
    // 添加控件到页面 screen_1
    return screen_1;
}

　　然后，将页面 ID 与对应的页面绑定：

static const gt_scr_list_st gt_scr_list[] = {
    {GT_ID_SCREEN_HOME, gt_init_screen_home},
    {GT_ID_SCREEN_1, gt_init_screen_1},
    {GT_ID_SCREEN_2, gt_init_screen_2},
    {GT_ID_SCREEN_3, gt_init_screen_3},
    {GT_ID_SCREEN_4, gt_init_screen_4},
};

　　最后，初始化页栈并设置主页：

void gt_ui_init(void) {
    gt_scr_stack_register_id_list(gt_scr_list,
        sizeof(gt_scr_list) / sizeof(gt_scr_list[0]));
    gt_scr_stack_set_home_scr_id(GT_ID_SCREEN_HOME, false);
    gt_disp_stack_load_scr(GT_ID_SCREEN_HOME);
}

　　以下示例为在 screen_home 中的 btn1 按钮添加加载屏幕事件，实现点击按下 btn1 控件时跳转到 screen_1 界面：

static void btn1_0_cb(gt_event_st * e) {
    gt_disp_stack_load_scr_anim(GT_ID_SCREEN_1,
        GT_SCR_ANIM_TYPE_NONE, 500, 0, true);
}
gt_obj_add_event_cb(btn1, btn1_0_cb, GT_EVENT_TYPE_INPUT_PRESSED
    , NULL);

　　加载屏幕时可以为其添加过渡动画，以下为 screen_1 屏幕控件添加延时 0ms 执行、类型为向左移动、持续时间为 500ms 的过渡动画：

gt_disp_stack_load_scr_anim(GT_ID_SCREEN_1,
    GT_SCR_ANIM_TYPE_MOVE_LEFT, 500, 0, true);

　　返回页面时可选择返回层数，以下示例为返回上一页：

gt_disp_stack_go_back(1);

8.2 移动动画

　　移动动画事件主要用于实现平滑移动控件，以下为 btn1 按钮添加移动动画事件，当滑动 btn1 控件时将触发 btn2 按钮控件平滑地移动到（10, 10）：

static void btn1_0_cb(gt_event_st * e)
{
    static gt_anim_param_st param;
    gt_anim_param_init(&param);
    gt_anim_param_set_time(&param, 0, 100);
    gt_anim_param_set_dst_point(&param, 10, 10);
    gt_anim_param_set_path_type(&param, GT_ANIM_PATH_TYPE_OVERSHOOT);
    gt_anim_pos_move(btn2, &param);
}
gt_obj_add_event_cb(btn1, btn1_0_cb, GT_EVENT_TYPE_INPUT_SCROLL, NULL);

8.3 背景颜色变化

　　背景颜色变化主要用于实现改变控件本身的背景颜色。事件添加代码与上述重复，仅展示回调函数差异如下所示：

static void btn1_0_cb(gt_event_st * e)
{
    gt_btn_set_color_background(btn2, gt_color_hex(0xff0000));
}

8.4 手势返回

　　手势返回主要用于实现页面切换，以下为 screen_home 屏幕添加手势返回事件，当在 screen_home 屏幕控件中右滑时将返回上一页：

static void screen_home_0_cb(gt_event_st * e) {
    gt_disp_stack_go_back(1);
}
gt_obj_add_event_cb(screen_home, screen_home_0_cb,
    GT_EVENT_TYPE_INPUT_HOME_GESTURE_RIGHT, NULL);

8.5 其他事件

　　其他诸如字体颜色变化、位置变化、大小变化、透明度变化、文本变化、隐藏等事件与背景颜色变化事件类似，皆为在回调函数中调用控件函数接口实现，本文档不再一一列举。

8.6 事件 API 参考

添加/移除事件

函数	说明
`void gt_obj_add_event_cb(gt_obj_st * obj, gt_event_cb_t event, gt_event_type_et filter, void * user_data)`	为对象添加事件回调。user_data 默认传 NULL
`void gt_obj_add_replace_core_event_cb(gt_obj_st * obj, gt_event_cb_t event, gt_event_type_et filter, void * user_data)`	[高级] 用自定义回调替换内核默认事件处理
`bool gt_event_has_event_cb(gt_obj_st * obj, gt_event_type_et filter)`	检查是否已注册指定类型事件回调
`bool gt_event_has_the_same_cb(gt_obj_st * obj, gt_event_cb_t event, gt_event_type_et filter)`	检查是否已注册完全相同的事件回调
`uint16_t gt_obj_get_user_event_count(gt_obj_st * obj)`	获取对象已注册的事件回调数量
`void gt_obj_remove_all_event_cb(gt_obj_st * obj)`	[安全] 移除对象所有事件回调
`void gt_obj_remove_all_event_cb_immediately(gt_obj_st * obj)`	[不安全] 立即移除所有事件回调

发送事件

函数	说明
`gt_res_t gt_event_send(gt_obj_st * parent, gt_event_type_et event, void * parms)`	向对象发送事件
`gt_res_t gt_event_send_delay(gt_obj_st * parent, gt_event_type_et event, void * parms, int32_t delay_ms)`	延时发送事件
`gt_res_t gt_event_send_to_childs(gt_obj_st * parent, gt_event_type_et event, void * parms)`	向对象的所有子对象发送事件
`gt_res_t gt_event_send_by_id(gt_id_t widget_id, gt_event_type_et event, void * parms)`	按控件 ID 发送事件

全局事件

条件编译宏：GT_USE_LAYER_TOP

函数	说明
`void gt_global_add_event_cb(gt_event_cb_t event, gt_event_type_et filter, void * user_data)`	注册全局事件回调
`void gt_global_remove_all_event_cb(void)`	[安全] 移除所有全局事件回调

获取事件信息

函数	说明
`gt_event_type_et gt_event_get_code(gt_event_st * e)`	获取事件的类型码

8.7 事件类型速查表

完整事件类型枚举定义于 gt_event.h。

输入设备事件

事件常量	说明	适用场景
`GT_EVENT_TYPE_INPUT_RELEASED`	释放	按钮松开
`GT_EVENT_TYPE_INPUT_PRESSING`	持续按下（未滚动时）	按住不放
`GT_EVENT_TYPE_INPUT_PRESSED`	按下（点击）	按钮点击
`GT_EVENT_TYPE_INPUT_LONG_PRESSED`	长按	长按操作
`GT_EVENT_TYPE_INPUT_PRESS_LOST`	按下后移出控件丢失焦点	误触取消
`GT_EVENT_TYPE_INPUT_SCROLL_START`	开始滚动	滚动检测
`GT_EVENT_TYPE_INPUT_SCROLL`	滚动中	滑动时连续触发
`GT_EVENT_TYPE_INPUT_SCROLL_END`	滚动结束	滚动停止
`GT_EVENT_TYPE_INPUT_KEY`	键盘按键按下	键盘控件
`GT_EVENT_TYPE_INPUT_KEY_PRESSING`	键盘按键持续按下	键盘长按
`GT_EVENT_TYPE_INPUT_KEY_RELEASED`	键盘按键松开	键盘释放
`GT_EVENT_TYPE_INPUT_KEY_LONG_PRESSED`	键盘按键长按	键盘长按
`GT_EVENT_TYPE_INPUT_FOCUSED`	获得焦点	焦点切换
`GT_EVENT_TYPE_INPUT_SCROLL_UP`	向上滚动	方向检测
`GT_EVENT_TYPE_INPUT_SCROLL_DOWN`	向下滚动	方向检测
`GT_EVENT_TYPE_INPUT_SCROLL_LEFT`	向左滚动	方向检测
`GT_EVENT_TYPE_INPUT_SCROLL_RIGHT`	向右滚动	方向检测
`GT_EVENT_TYPE_INPUT_HIDED`	浮层控件需隐藏	系统内部
`GT_EVENT_TYPE_INPUT_HOME_GESTURE_TOP`	顶部手势	手势返回
`GT_EVENT_TYPE_INPUT_HOME_GESTURE_BOTTOM`	底部手势	手势返回
`GT_EVENT_TYPE_INPUT_HOME_GESTURE_LEFT`	左侧手势	手势返回
`GT_EVENT_TYPE_INPUT_HOME_GESTURE_RIGHT`	右侧手势	手势返回
`GT_EVENT_TYPE_INPUT_PLAY_START`	开始播放	媒体/动画
`GT_EVENT_TYPE_INPUT_PLAY_END`	播放结束	媒体/动画

值更新事件

事件常量	说明	适用场景
`GT_EVENT_TYPE_UPDATE_VALUE`	值更新（需重绘）	滑动条、计数器等
`GT_EVENT_TYPE_UPDATE_STYLE`	样式更新	主题切换

绘制事件

事件常量	说明
`GT_EVENT_TYPE_DRAW_START`	开始绘制
`GT_EVENT_TYPE_DRAW_END`	绘制结束
`GT_EVENT_TYPE_DRAW_REDRAW`	重绘请求
`GT_EVENT_TYPE_SCREEN_LOAD_BEFORE`	[内核调用] 屏幕加载前
`GT_EVENT_TYPE_SCREEN_HIDE`	[内核调用] 当前屏幕被新屏幕覆盖
`GT_EVENT_TYPE_SCREEN_BEFORE_GO_BACK`	[内核调用] 屏幕返回前

控件变化事件

事件常量	说明
`GT_EVENT_TYPE_CHANGE_CHILD_REMOVE`	[内核调用] 移除子控件前
`GT_EVENT_TYPE_CHANGE_CHILD_REMOVED`	[内核调用] 移除子控件完成
`GT_EVENT_TYPE_CHANGE_CHILD_ADD`	[内核调用] 添加子控件
`GT_EVENT_TYPE_CHANGE_CHILD_DELETE`	[内核调用] 删除子控件前
`GT_EVENT_TYPE_CHANGE_CHILD_DELETED`	[内核调用] 删除子控件完成
`GT_EVENT_TYPE_CHANGE_DELETED`	[内核调用] 自身删除完成

边界与手势事件

事件常量	说明	启用条件
`GT_EVENT_TYPE_PULL_TO_REFRESH`	[内核调用] 滚动到顶部，下拉刷新	自动触发
`GT_EVENT_TYPE_LOAD_MORE`	[内核调用] 滚动到底部，加载更多	自动触发
`GT_EVENT_TYPE_SWIPE_UP`	上滑手势	`gt_obj_set_swipe_dir(obj, true)`
`GT_EVENT_TYPE_SWIPE_DOWN`	下滑手势	`gt_obj_set_swipe_dir(obj, true)`
`GT_EVENT_TYPE_SWIPE_LEFT`	左滑手势	`gt_obj_set_swipe_dir(obj, true)`
`GT_EVENT_TYPE_SWIPE_RIGHT`	右滑手势	`gt_obj_set_swipe_dir(obj, true)`

通知事件

事件常量	说明
`GT_EVENT_TYPE_NOTIFY_CLOSE`	通知控件关闭

禁用屏幕动画时暂停事件：如果 GT_USE_SCREEN_ANIM 启用，可通过 gt_event_set_enabled(bool) 在屏幕动画期间禁用/启用事件处理。