2B. 基类对象 API

概念说明

在 GT-HMI Engine 中，所有控件（屏幕、按钮、标签、滑动条……）共享一套通用能力：位置、尺寸、透明度、背景色、滚动、焦点等。Engine 将这些共性抽到一个基础结构体 gt_obj_st 中（定义于 src/widgets/gt_obj.h），控件在此基础上扩展各自的功能。

Engine 用 C 语言的 struct 嵌套实现继承——每个控件结构体的第一个成员就是 gt_obj_st：

// 以按钮为例（src/widgets/gt_btn.c）
typedef struct _gt_btn_s {
    gt_obj_st base;             // 基类对象（第一个成员）
    _gt_vector_st * contents;   // 按钮特有：状态文本列表
    gt_color_t color_pressed;   // 按钮特有：按下颜色
    gt_color_t font_color;      // 按钮特有：字体颜色
    // ... 其他按钮专有字段
} _gt_btn_st;

由于 base 是结构体第一个成员，指向 _gt_btn_st 的指针可以直接转为 gt_obj_st *，因此所有基类函数（gt_obj_set_pos、gt_obj_set_opa 等）都能作用于任何控件类型。

控件通过 gt_obj_class_create() 统一创建，每个控件注册一个类描述表 gt_obj_class_st（定义于 src/widgets/gt_obj_class.h），其中包含初始化回调、事件回调、类型枚举和控件专属尺寸：

// 按钮的类描述表（src/widgets/gt_btn.c）
static const gt_obj_class_st gt_btn_class = {
    ._init_cb   = _btn_init_cb,        // 初始化时调用
    ._event_cb  = _btn_event_cb,       // 事件处理时调用
    .type       = GT_TYPE_BTN,         // 控件类型标识
    .size_style = sizeof(_gt_btn_st)   // 控件专属结构体的内存大小
};

一句话总结：gt_obj_st 是所有控件的公共部分，基类 API 就是操作这些公共部分的函数。你可以在任何控件上使用它们，因为任何控件都以 gt_obj_st 开头。

如何使用本页

以下函数按功能分组列出，所有函数对一切控件通用。例如 gt_obj_set_pos(obj, 100, 200) 可以设置按钮的坐标，也可以设置标签的坐标——传入对应控件对象即可。

创建与销毁

对象生命周期的起点和终点。"创建"产生一个新控件，"销毁"将其从界面移除。

父子关系

对象以树状结构组织：一个屏幕可以包含按钮、标签，按钮又可以包含图标。这些函数用来查询和操作对象的归属关系。

ID 管理

坐标与尺寸

设置和获取对象的位置（x, y）与大小（宽, 高）。支持绝对坐标、相对坐标、动画移动、按步进调整等多种方式。

外观

控制对象视觉呈现：透明度（可实现淡入淡出）、圆角半径、背景色等。

可见性与交互

控制对象是否在屏幕上显示（可见/隐藏）、是否响应用户操作（启用/禁用）、是否可触摸，以及触摸事件是否传递给父对象。

状态

控件的交互状态管理：选中/未选中、触发模式（按住触发 vs 点击切换）、遮罩效果等。

滚动

当对象内容超出可视区域时，控制滚动行为：滚动方向、对齐方式、惯性效果、滚动提示条等。

布局相关

控制对象在父容器中的布局行为：是否固定在屏幕上（不跟随滚动）、是否裁剪超出内容、子控件横向排列等。

焦点相关

焦点是当前被选中的对象（通常用物理按键或触摸切换）。焦点框是一个高亮边框，指示当前活跃控件。

事件通知

事件冒泡：子对象的触摸事件是否向上传递给父对象。手势滑动方向事件：检测用户的滑动方向。

条件编译特性

以下 API 仅在对应宏定义开启时可用。

获取滚动限制

颜色透明度常量

定义于 gt_color.h，配合 gt_obj_set_opa() 使用。