2B. 基类对象 API
gt_obj_st 是所有控件的基类。以下 API 适用于所有控件类型（屏幕、按钮、标签、滑动条等），除非另有说明。
创建与销毁
| 函数 | 说明 |
|---|
gt_obj_st * gt_obj_create(gt_obj_st * parent) | 创建对象。parent 为 NULL 时创建屏幕 |
void gt_obj_destroy(gt_obj_st * obj) | [安全] 销毁对象（延迟释放，避免回调中释放自身） |
void gt_obj_destroy_immediately(gt_obj_st * obj) | [不安全] 立即销毁对象 |
父子关系
| 函数 | 说明 |
|---|
gt_obj_st * gt_obj_get_parent(gt_obj_st * obj) | 获取父对象 |
gt_obj_st * gt_obj_change_parent(gt_obj_st * obj, gt_obj_st * to) | 更换父对象（to 不能为 NULL） |
bool gt_obj_is_child(gt_obj_st * obj, gt_obj_st * parent) | 判断是否为指定父对象的子对象 |
uint16_t gt_obj_get_child_index(gt_obj_st * parent, gt_obj_st * obj) | 获取子对象索引，失败返回 0xFFFF |
gt_obj_st * gt_obj_search_child_by_type(gt_obj_st * parent, gt_obj_type_et type) | 按类型搜索子对象 |
gt_obj_st * gt_obj_search_child_by_id(gt_obj_st * parent, gt_id_t id) | 按 ID 搜索子对象 |
gt_res_t gt_obj_bring_to_front(gt_obj_st * obj) | 将对象移到父容器最上层 |
gt_obj_st * gt_obj_within_which_scr(gt_obj_st * obj) | 获取对象所属的屏幕对象 |
ID 管理
| 函数 | 说明 |
|---|
void gt_obj_register_id(gt_obj_st * obj, gt_id_t id) | 注册对象 ID（id >= 0），默认值为 -1（无效） |
gt_id_t gt_obj_get_id(gt_obj_st * obj) | 获取对象 ID |
gt_obj_st * gt_obj_find_by_id(gt_id_t widget_id) | 按 ID 查找全局对象 |
坐标与尺寸
| 函数 | 说明 | 默认值 |
|---|
void gt_obj_set_pos(gt_obj_st * obj, gt_size_t x, gt_size_t y) | 设置坐标 | — |
void gt_obj_set_pos_anim(gt_obj_st * obj, gt_size_t x, gt_size_t y) | 带动画设置坐标 | — |
void gt_obj_set_pos_step(gt_obj_st * obj, gt_size_t step_x, gt_size_t step_y) | 按步进值调整坐标 | — |
void gt_obj_set_pos_relative(gt_obj_st * obj, gt_obj_st * target, gt_size_t diff_x, gt_size_t diff_y) | 相对目标对象设置坐标。target=NULL 时相对于父对象 | — |
void gt_obj_set_x(gt_obj_st * obj, gt_size_t x) | 设置 X 坐标 | — |
void gt_obj_set_y(gt_obj_st * obj, gt_size_t y) | 设置 Y 坐标 | — |
void gt_obj_set_size(gt_obj_st * obj, uint16_t w, uint16_t h) | 设置宽度和高度 | — |
void gt_obj_set_size_anim(gt_obj_st * obj, uint16_t w, uint16_t h) | 带动画设置尺寸 | — |
void gt_obj_set_w(gt_obj_st * obj, uint16_t w) | 设置宽度 | — |
void gt_obj_set_h(gt_obj_st * obj, uint16_t h) | 设置高度 | — |
gt_size_t gt_obj_get_x(gt_obj_st * obj) | 获取 X 坐标 | — |
gt_size_t gt_obj_get_y(gt_obj_st * obj) | 获取 Y 坐标 | — |
uint16_t gt_obj_get_w(gt_obj_st * obj) | 获取宽度 | — |
uint16_t gt_obj_get_h(gt_obj_st * obj) | 获取高度 | — |
外观
| 函数 | 说明 | 默认值 |
|---|
void gt_obj_set_opa(gt_obj_st * obj, gt_opa_t opa) | 设置透明度。范围 0（全透明）~ 255（不透明） | 255 |
gt_anim_st * gt_obj_set_opa_anim(gt_obj_st * obj, gt_opa_t opa) | 带动画设置透明度，返回动画对象 | — |
void gt_obj_set_radius(gt_obj_st * obj, gt_radius_t radius) | 设置圆角半径（像素） | 0 |
void gt_obj_set_radius_anim(gt_obj_st * obj, gt_radius_t radius) | 带动画设置圆角 | — |
void gt_obj_set_bgcolor(gt_obj_st * obj, gt_color_t color) | 设置背景颜色 | — |
gt_color_t gt_obj_get_bgcolor(gt_obj_st * obj) | 获取背景颜色 | — |
void gt_obj_show_bg(gt_obj_st * obj, bool show) | 是否显示背景颜色。false 时 bgcolor 不可见 | false |
bool gt_obj_is_show_bg(gt_obj_st * obj) | 获取背景显示状态 | — |
void gt_screen_set_bgcolor(gt_obj_st * obj, gt_color_t color) | 设置屏幕背景颜色（仅屏幕对象） | — |
gt_color_t gt_screen_get_bgcolor(gt_obj_st * obj) | 获取屏幕背景颜色 | — |
可见性与交互
| 函数 | 说明 | 默认值 |
|---|
void gt_obj_set_visible(gt_obj_st * obj, gt_visible_et is_visible) | 设置可见性：GT_VISIBLE 或 GT_INVISIBLE | GT_VISIBLE |
gt_visible_et gt_obj_get_visible(gt_obj_st * obj) | 获取可见状态 | — |
void gt_obj_set_disabled(gt_obj_st * obj, gt_disabled_et is_disabled) | 启用/禁用控件：GT_ENABLED 或 GT_DISABLED | GT_ENABLED |
bool gt_obj_is_disabled(gt_obj_st * obj) | 获取禁用状态 | — |
void gt_obj_set_untouchability(gt_obj_st * obj, bool is_untouchability) | 设置控件是否可触摸。true=不可触摸 | false |
bool gt_obj_is_untouchability(gt_obj_st * obj) | 获取不可触摸状态 | — |
void gt_obj_set_touch_parent(gt_obj_st * obj, bool is_touch_parent) | 触摸事件传递给父对象 | false |
bool gt_obj_get_touch_parent(gt_obj_st * obj) | 获取触摸传递状态 | — |
状态
| 函数 | 说明 | 默认值 |
|---|
void gt_obj_set_state(gt_obj_st * obj, gt_state_et state) | 设置选中状态：GT_STATE_NONE 或 GT_STATE_PRESSED | GT_STATE_NONE |
gt_state_et gt_obj_get_state(gt_obj_st * obj) | 获取选中状态 | — |
void gt_obj_set_trigger_mode(gt_obj_st * obj, gt_obj_trigger_mode_et mode) | 状态切换模式：GT_OBJ_TRIGGER_MODE_HOLD_ON（按住）或 GT_OBJ_TRIGGER_MODE_SWITCH（切换） | HOLD_ON |
void gt_obj_set_mask_effect(gt_obj_st * obj, bool is_keep_alive) | 选中状态时启用遮罩效果 | false |
bool gt_obj_get_mask_effect(gt_obj_st * obj) | 获取遮罩效果状态 | — |
滚动
| 函数 | 说明 | 默认值 |
|---|
void gt_obj_set_scroll_dir(gt_obj_st * obj, gt_scroll_dir_et dir) | 滚动方向：GT_SCROLL_DISABLE / GT_SCROLL_HORIZONTAL / GT_SCROLL_VERTICAL / GT_SCROLL_ALL | GT_SCROLL_ALL |
gt_scroll_dir_et gt_obj_get_scroll_dir(gt_obj_st * obj) | 获取滚动方向 | — |
void gt_obj_set_scroll_snap_x(gt_obj_st * obj, gt_scroll_snap_em snap) | 水平滚动对齐：GT_SCROLL_SNAP_NONE / START / END / CENTER | GT_SCROLL_SNAP_NONE |
void gt_obj_set_scroll_snap_y(gt_obj_st * obj, gt_scroll_snap_em snap) | 垂直滚动对齐：同上可选值 | GT_SCROLL_SNAP_NONE |
void gt_obj_set_scroll_lr(gt_obj_st * obj, bool is_scroll_right) | 设置水平滚动方向：false=左滚，true=右滚 | — |
void gt_obj_set_scroll_ud(gt_obj_st * obj, bool is_scroll_down) | 设置垂直滚动方向：false=上滚，true=下滚 | — |
void gt_obj_set_scroll_tip(gt_obj_st * obj, gt_scroll_tip_et mode) | 滚动提示条位置：GT_SCROLL_TIP_NONE / LEFT / RIGHT / TOP / BOTTOM | GT_SCROLL_TIP_NONE |
void gt_obj_set_scroll_tip_always(gt_obj_st * obj, bool always) | 滚动提示条常显。false=自动隐藏 | false |
void gt_obj_set_rebound(gt_obj_st * obj, bool enabled) | 滚动回弹效果 | false |
void gt_obj_set_ignore_throw(gt_obj_st * obj, bool is_ignore_throw) | 忽略滚动惯性（立即停止） | false |
布局相关
| 函数 | 说明 | 默认值 |
|---|
void gt_obj_set_fixed(gt_obj_st * obj, bool is_fixed) | 锁定对象位置。锁定后不跟随父容器滚动 | false |
bool gt_obj_get_fixed(gt_obj_st * obj) | 获取锁定状态 | — |
void gt_obj_set_overflow(gt_obj_st * obj, bool is_overflow) | 允许控件尺寸超出屏幕范围独立滑动 | false |
bool gt_obj_get_overflow(gt_obj_st * obj) | 获取溢出状态 | — |
void gt_obj_set_inside(gt_obj_st * obj, bool is_inside) | 控件仅在父区域内显示（裁剪） | false |
bool gt_obj_get_inside(gt_obj_st * obj) | 获取裁剪状态 | — |
void gt_obj_set_virtual(gt_obj_st * obj, bool is_virtual) | 虚拟控件标志。true=不可接收触摸 | false |
void gt_obj_set_row_layout(gt_obj_st * obj, bool is_row_layout) | 子控件横向排列 | false |
void gt_obj_set_grow_invert(gt_obj_st * obj, bool is_grow_invert) | 横向排列时反向增长 | false |
焦点相关
| 函数 | 说明 | 默认值 |
|---|
void gt_obj_set_focus(gt_obj_st * obj, bool is_focus) | 设置焦点状态 | false |
bool gt_obj_is_focus(gt_obj_st * obj) | 获取焦点状态 | — |
void gt_obj_set_focus_disabled(gt_obj_st * obj, gt_disabled_et is_disabled) | 禁用焦点 | GT_ENABLED |
void gt_obj_set_focus_skip(gt_obj_st * obj, bool is_skip) | 焦点跳过当前对象直接到子对象 | false |
void gt_obj_set_focus_w(gt_obj_st * obj, uint8_t focus_w) | 焦点框边框宽度（像素） | 2 |
void gt_obj_set_focus_gap(gt_obj_st * obj, uint8_t focus_gap) | 焦点框与控件间距（像素） | 0 |
事件通知
| 函数 | 说明 | 默认值 |
|---|
void gt_obj_set_bubble_notify(gt_obj_st * obj, bool is_bubble_notify) | 对象事件冒泡通知父对象 | false |
bool gt_obj_is_bubble_notify(gt_obj_st * obj) | 获取冒泡通知状态 | — |
void gt_obj_set_swipe_dir(gt_obj_st * obj, bool enabled) | 启用手势滑动方向事件（需配合 GT_EVENT_TYPE_SWIPE_*） | false |
条件编译特性
以下 API 仅在对应宏定义开启时可用。
| 条件宏 | API | 说明 |
|---|
GT_USE_CUSTOM_TOUCH_EXPAND_SIZE | void gt_obj_set_touch_expand_area(gt_obj_st * obj, gt_size_t hor, gt_size_t ver) | 设置触摸扩展区域 |
GT_USE_WIDGET_DYNAMIC_FRAME_RATE | void gt_obj_set_frame_rate(gt_obj_st * obj, gt_obj_frame_rate_et frame_rate) | 设置动态帧率：GT_OBJ_FRAME_RATE_HIGH / MIDDLE / LOW |
获取滚动限制
| 函数 | 说明 |
|---|
gt_size_t gt_obj_get_limit_right(gt_obj_st * obj) | 获取子对象最大右边界 |
gt_size_t gt_obj_get_limit_bottom(gt_obj_st * obj) | 获取子对象最大下边界 |
gt_point_st gt_obj_calc_scroll_limit(gt_obj_st * parent) | 计算可滚动的最大距离 |
gt_obj_st * gt_obj_find_by_id(gt_id_t widget_id) | 按 ID 查找全局对象 |
颜色透明度常量
定义于 gt_color.h，配合 gt_obj_set_opa() 使用。
| 常量 | 值 | 说明 |
|---|
GT_OPA_0 | 0 | 全透明 |
GT_OPA_10 | 25 | 10% 不透明 |
GT_OPA_20 | 51 | 20% |
GT_OPA_30 | 76 | 30% |
GT_OPA_40 | 102 | 40% |
GT_OPA_50 | 127 | 50% |
GT_OPA_60 | 153 | 60% |
GT_OPA_70 | 178 | 70% |
GT_OPA_80 | 204 | 80% |
GT_OPA_90 | 229 | 90% |
GT_OPA_COVER | 255 | 完全不透明 |
