2. 基础控件
🎮 在线体验:本章控件的渲染效果可在 控件在线演示页 实时交互——GT-HMI Engine 以 WebAssembly 在浏览器内渲染,调整右侧参数即可实时查看控件效果,与真机渲染一致。
什么是控件?控件又称组件或者部件,指用户看到的所有可视化界面以及界面中的元素,例如按钮、标签、文本框等。为方便用户开发,高通 GT-HMI Designer 提供了多种现成的控件以满足用户实现相关功能的需求。而这些控件的实现,离不开 GT-HMI Engine 的底层支持。本文档将通过对各控件的简单调用效果及 GT-HMI Designer 生成的代码(你可以在工程项目文件的 screen 文件夹中找到 gt_init_screen_xxx.c 文件查看)协助你认识 GT-HMI Designer 的控件并理解 GT-HMI Engine 的控件接口函数是如何使用的。
2.1 屏幕控件
屏幕控件是所有其他控件的基础,在创建项目工程时,系统将默认创建一个屏幕控件,该控件背景颜色默认为白色,一个项目工程中需要存在一个以上屏幕控件,当只剩下最后一个屏幕控件时,该屏幕控件将无法删除。
API 参考:
屏幕控件通过 gt_obj_create(NULL) 创建。除基类 API 外,屏幕专用函数如下:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_screen_set_bgcolor(screen, color) | 设置屏幕背景颜色 | gt_color_white() |
gt_screen_get_bgcolor(screen) | 获取屏幕背景颜色 | — |
所有基类对象 API(坐标、尺寸、透明度等)同样适用于屏幕控件,详见 基类对象 API 参考。
gt_obj_st * gt_init_screen_home()
{
// 创建一个屏幕控件
screen_home = gt_obj_create(NULL);
// 设置屏幕的背景颜色为白色
gt_screen_set_bgcolor(screen_home, gt_color_hex(0xFFFFFF));
return screen_home;
}
屏幕控件是所有控件的父容器。真机用 gt_screen_set_bgcolor 设置背景色;官网演示经通用背景色桥注入(该 setter 在 wasm 构建同样生效于下一帧重绘)。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* screen_home —— 摘自手册 2.1 节 */// 初始化屏幕(作为所有控件的父容器)screen_home = gt_init_screen_home();// 设置屏幕背景颜色为白色gt_screen_set_bgcolor(screen_home, gt_color_white());// 官网演示:经通用对象背景色桥注入并失效重绘// gt_obj_set_bgcolor(screen_home, gt_color_hex(0xF0F2F5));2.2 图片控件
在创建的屏幕控件中,添加一个图片控件并设置图片控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_img_create(parent) | 创建图片控件 | — |
gt_img_set_src(img, "src") | 设置图片文件路径 | — |
char * gt_img_get_src(img) | 获取图片路径 | — |
uint16_t gt_img_get_width(img) | 获取图片原始宽度 | — |
uint16_t gt_img_get_height(img) | 获取图片原始高度 | — |
gt_img_set_raw_data(img, raw) | 直接使用原始数据显示图片 | — |
gt_img_set_masking(img, masking) | 设置图片轮廓遮罩效果 | — |
条件编译特性(需开启对应宏):
| 条件宏 | 函数 | 说明 | 默认值 |
|---|---|---|---|
GT_USE_FILE_HEADER | gt_img_set_by_file_header(img, fh) | 通过文件头信息加载图片 | — |
GT_USE_DIRECT_ADDR | gt_img_set_by_direct_addr(img, addr) | 通过直接地址加载图片 | — |
GT_USE_DIRECT_ADDR_CUSTOM_SIZE | gt_img_set_by_custom_size_addr(img, dac) | 通过自定义尺寸直接地址加载 | — |
GT_USE_IMG_TRANSFORM | gt_img_set_angle(img, angle) | 旋转角度(0~3599,0.1度单位) | GT_ANGLE_NONE |
GT_USE_IMG_TRANSFORM | gt_img_set_zoom(img, zoom) | 缩放系数(256=1.0x) | GT_ZOOM_NONE |
GT_USE_IMG_TRANSFORM | gt_img_set_pivot(img, x, y) | 旋转/缩放中心点,-1=自动居中 | -1, -1 |
/* img1 */
// 在 screen_home 屏幕控件中创建一个图片控件
img1 = gt_img_create(screen_home);
// 设置图片控件的位置为 (120, 120)
gt_obj_set_pos(img1, 120, 120);
// 设置图片控件的尺寸为图片的大小尺寸(宽度 30 高度 30)
gt_obj_set_size(img1, 30, 30);
// 设置图片控件的图片数据访问路径
gt_img_set_src(img1, ".:20.bmp");
运行后的图片控件效果见下方在线演示(可直接交互):
真机流程经资源包 gt_img_set_src(".:20.bmp") 取图;官网演示无资源包,经 wasm 桥注入原始 RGBA 像素(同一解码渲染路径)。可切换三种图片内容并开关轮廓遮罩。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* img1 —— 摘自手册 2.2 节示例 */// 在 screen_home 屏幕控件中创建一个图片控件img1 = gt_img_create(screen_home);// 设置图片控件的位置为 (140, 90)gt_obj_set_pos(img1, 140, 90);// 设置图片控件的尺寸为(宽度 200 高度 140)gt_obj_set_size(img1, 200, 140);// 设置图片控件的图片数据访问路径(真机:资源包内图片)gt_img_set_src(img1, ".:20.bmp");// 官网演示无资源包:经 wasm 桥注入原始 RGBA 像素(右侧面板可切换三种内容)// gt_img_set_raw_data(img1, raw_rgba_data);// 设置图片轮廓遮罩效果(右侧面板可开关)gt_img_set_masking(img1, false);2.3 标签控件
在创建的屏幕控件中再添加一个标签控件并设置标签控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_label_create(parent) | 创建标签控件 | — |
gt_label_set_text(label, "fmt", ...) | 设置标签文本(printf 格式) | "label" |
gt_label_set_text_by_len(label, "text", len) | 按长度设置文本 | — |
char * gt_label_get_text(label) | 获取标签文本 | — |
gt_label_set_font_color(label, color) | 设置字体颜色 | 0x000000 |
gt_label_set_font_size(label, size) | 设置字体大小(pt) | — |
gt_label_set_font_align(label, align) | 对齐方式:见 枚举速查表 gt_align_et | GT_ALIGN_LEFT |
gt_label_set_font_family(label, family) | 设置字体系列 | — |
gt_label_set_font_cjk(label, cjk) | 设置 CJK 字体变体 | — |
gt_label_set_font_gray(label, gray) | 设置字体灰度:1 / 2 / 4 | — |
gt_label_set_font_style(label, style) | 字体风格:见 枚举速查表 gt_font_style_et | NORMAL |
gt_label_set_font_encoding(label, encoding) | 文本编码:见 枚举速查表 gt_encoding_et | UTF-8 |
gt_label_set_space(label, x, y) | 设置字间距 | 0, 0 |
gt_label_set_auto_scroll_single_line(label, enabled) | 单行自动滚动(文本超宽时) | false |
gt_label_set_scroll_time(label, time_ms) | 设置滚动周期(ms) | — |
gt_label_set_long_mode(label, mode) | 长文本模式:见 枚举速查表 gt_text_long_mode_et | WRAP |
/* lab1 */
// 在 screen_home 屏幕控件中创建一个标签控件
lab1 = gt_label_create(screen_home);
// 设置标签控件的位置为 (160, 120)
gt_obj_set_pos(lab1, 160, 120);
// 设置标签控件的尺寸(宽度 50 高度 24)
gt_obj_set_size(lab1, 50, 24);
// 设置标签控件文本颜色为 0xff0000 红色
gt_label_set_font_color(lab1, gt_color_hex(0xff0000));
// 设置标签控件显示的字体尺寸为 16 点
gt_label_set_font_size(lab1, 16);
// 设置对齐方式为左对齐
gt_label_set_font_align(lab1, GT_ALIGN_LEFT);
// 设置标签控件显示的文本为 "Hello"
gt_label_set_text(lab1, "Hello");
运行后的标签控件效果见下方在线演示(可直接交互):
与手册 2.3 节示例一致:演示字库为 18 点 GBK 黑体点阵(4bit 灰度抗锯齿),面板可改文本、颜色、对齐与字间距。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* lab1 —— 摘自手册 2.3 节示例 */// 在 screen_home 屏幕控件中创建一个标签控件lab1 = gt_label_create(screen_home);// 设置标签控件的位置为 (40, 130)gt_obj_set_pos(lab1, 40, 130);// 设置标签控件的尺寸(宽度 400 高度 60)gt_obj_set_size(lab1, 400, 60);// 使用 0 号字体系列(本页演示字库:18 点 GBK 黑体点阵,4bit 灰度抗锯齿)gt_label_set_font_family(lab1, 0);// 设置标签控件显示的字体尺寸为 18 点gt_label_set_font_size(lab1, 18);// 设置对齐方式为水平垂直居中gt_label_set_font_align(lab1, GT_ALIGN_CENTER_MID);// 设置标签控件文本颜色为 0x000000 黑色gt_label_set_font_color(lab1, gt_color_hex(0x000000));// 设置标签控件显示的文本gt_label_set_text(lab1, "高通字体引擎");2.4 文本区控件
在创建的屏幕控件中添加一个文本区控件并设置文本区控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_textarea_create(parent) | 创建文本区控件 | — |
gt_textarea_add_str(textarea, "text", flags, color) | 追加带样式的文本段。flags 为 gt_font_style_et 枚举值 | — |
gt_textarea_add_str_by_len(textarea, "text", len, flags, color) | 追加带样式的文本段(指定长度) | — |
gt_textarea_clear_all_str(textarea) | 清空所有文本 | — |
gt_textarea_set_font_color(textarea, color) | 设置默认字体颜色 | — |
gt_textarea_set_font_size(textarea, size) | 设置字体大小(pt) | — |
gt_textarea_set_font_align(textarea, align) | 对齐方式:见 枚举速查表 gt_align_et | — |
gt_textarea_set_font_family(textarea, family) | 设置字体系列 | — |
gt_textarea_set_font_cjk(textarea, cjk) | 设置 CJK 字体变体 | — |
gt_textarea_set_bg_color(textarea, color) | 设置背景颜色 | — |
gt_textarea_set_line_gap(textarea, gap) | 设置行间距(像素) | — |
gt_textarea_set_scroll_bottom(textarea) | 滚动到底部 | — |
/* textarea1 */
// 在 screen_home 屏幕控件中创建一个文本区控件
textarea1 = gt_textarea_create(screen_home);
// 设置文本区控件的位置为 (0, 0)
gt_obj_set_pos(textarea1, 0, 0);
// 设置文本区控件的尺寸(宽度 480 高度 320)
gt_obj_set_size(textarea1, 480, 320);
// 设置字体颜色为黑色
gt_textarea_set_font_color(textarea1, gt_color_hex(0x000000));
// 设置字体大小
gt_textarea_set_font_size(textarea1, 16);
// 添加文本段,GT_FONT_STYLE_NORMAL 表示普通样式
gt_textarea_add_str(textarea1, "Hello World!", GT_FONT_STYLE_NORMAL, gt_color_hex(0x000000));
运行后的文本区控件效果见下方在线演示(可直接交互):
与手册 2.4 节一致:逐段追加带样式的文本(每段可独立颜色/粗体),支持清空。演示字库为 18 点 GBK 点阵(4bit 灰度)。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* textarea1 —— 摘自手册 2.4 节示例 */// 在 screen_home 屏幕控件中创建一个文本区控件textarea1 = gt_textarea_create(screen_home);// 设置文本区控件的位置为 (60, 70)gt_obj_set_pos(textarea1, 60, 70);// 设置文本区控件的尺寸(宽度 360 高度 180)gt_obj_set_size(textarea1, 360, 180);// 设置文本区背景颜色为浅灰gt_textarea_set_bg_color(textarea1, gt_color_hex(0xf5f7fa));// 设置默认字体颜色为深灰gt_textarea_set_font_color(textarea1, gt_color_hex(0x2c3e50));// 设置字体大小为 18 点gt_textarea_set_font_size(textarea1, 18);// 逐段追加文本:每段可带独立样式与颜色(GT_FONT_STYLE_NORMAL / BOLD)gt_textarea_add_str(textarea1, "中英混排演示\n", GT_FONT_STYLE_NORMAL, gt_color_hex(0x2c3e50));gt_textarea_add_str(textarea1, "点阵四比特灰度渲染\n", GT_FONT_STYLE_BOLD, gt_color_hex(0xe74c3c));// 设置内边距为 14 像素(注意:需在 add_str 之后调用,add 前设置会被文本布局覆盖)gt_textarea_set_padding(textarea1, 14);// 清空全部文本(右侧面板可操作)// gt_textarea_clear_all_str(textarea1);2.5 输入框控件
在创建的屏幕控件中添加一个输入框控件并设置输入框控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_input_create(parent) | 创建输入框控件 | — |
gt_input_set_value(input, "fmt", ...) | 设置输入框内容 | — |
gt_input_set_value_by_len(input, "str", len) | 按长度设置内容 | — |
char * gt_input_get_value(input) | 获取输入框内容 | — |
gt_input_set_placeholder(input, "text") | 设置占位符文本 | — |
gt_input_set_placeholder_auto_scroll(input, enabled) | 占位符自动滚动 | true |
gt_input_hide_value(input, hide) | 密码模式(用 "*" 隐藏内容) | false |
gt_input_append_value(input, "value") | 末尾追加内容 | — |
gt_input_append_char(input, chr) | 末尾追加单个字符 | — |
gt_input_set_font_color(input, color) | 设置字体颜色 | — |
gt_input_set_font_size(input, size) | 设置字体大小(pt) | — |
gt_input_set_font_align(input, align) | 对齐方式:见 枚举速查表 gt_align_et | — |
gt_input_set_bg_color(input, color) | 设置背景颜色 | — |
/* input1 */
// 在 screen_home 屏幕控件中创建一个输入框控件
input1 = gt_input_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(input1, 160, 120);
// 设置控件尺寸
gt_obj_set_size(input1, 100, 32);
// 设置字体颜色为黑色
gt_input_set_font_color(input1, gt_color_hex(0x000000));
// 设置字体大小
gt_input_set_font_size(input1, 16);
// 设置占位符文本
gt_input_set_placeholder(input1, "请输入...");
运行后的输入框控件效果见下方在线演示(可直接交互):
与手册 2.5 节示例一致:单行内容 + 占位符(内容为空时显示)+ 密码模式(内容以 * 隐藏)。演示字库为 18 点 GBK 点阵(4bit 灰度)。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* input1 —— 摘自手册 2.5 节示例 */// 在 screen_home 屏幕控件中创建一个输入框控件input1 = gt_input_create(screen_home);// 设置输入框控件的位置为 (120, 138)gt_obj_set_pos(input1, 120, 138);// 设置输入框控件的尺寸(宽度 240 高度 44)gt_obj_set_size(input1, 240, 44);// 设置字体颜色为深灰gt_input_set_font_color(input1, gt_color_hex(0x2c3e50));// 设置字体大小为 18 点gt_input_set_font_size(input1, 18);// 设置占位符文本(内容为空时显示)gt_input_set_placeholder(input1, "输入演示");// 设置输入内容(右侧面板可切换,含密码模式)gt_input_set_value(input1, "admin");2.6 位图控件
在创建的屏幕控件中添加一个位图控件。位图控件支持两组项目(item0/item1),根据数值位切换显示,支持 8 种显示模式和 4 种移动模式,适用于图标状态切换、位图动画等场景。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_bit_img_create(parent) | 创建位图控件 | — |
gt_bit_img_remove_all_items(obj) | 移除所有位图项目 | — |
gt_bit_img_add_item0(obj, item, byte_size) | 添加 item0 项目,返回项目计数(-1=失败) | — |
gt_bit_img_add_item1(obj, item, byte_size) | 添加 item1 项目,返回项目计数(-1=失败) | — |
gt_bit_img_set_disp_mode(obj, mode) | 设置显示模式:BIN_VAR_DISP_MODE_0 ~ 7(8 种 item0/item1 组合) | — |
gt_bit_img_set_move_mode(obj, mode) | 设置移动模式:X/Y 轴、保持/不保持位 | — |
gt_bit_img_set_move_gap(obj, gap) | 设置移动间隙 | — |
gt_bit_img_set_active(obj, act) | 设置活动索引:bit[0]=active, bit[1]=inactive | — |
gt_bit_img_get_active(obj) | 获取活动索引 | — |
gt_bit_img_set_value(obj, value) | 设置位值 | — |
gt_bit_img_get_value(obj) | 获取位值 | — |
gt_bit_img_set_value_bit(obj, bit, value) | 设置指定位的值 | — |
gt_bit_img_get_value_bit(obj, bit) | 获取指定位的值 | — |
gt_bit_img_set_time(obj, time) | 设置动画时间(ms) | 500 |
条件编译特性(需开启对应宏):
| 条件宏 | 函数 | 说明 |
|---|---|---|
GT_USE_FILE_HEADER | gt_bit_img_add_item0_by_file_header(obj, fh) | 通过文件头添加 item0 |
GT_USE_FILE_HEADER | gt_bit_img_add_item1_by_file_header(obj, fh) | 通过文件头添加 item1 |
GT_USE_FILE_HEADER | gt_bit_img_add_item0_list_by_file_header(obj, fh_array, count) | 批量通过文件头添加 item0 |
GT_USE_FILE_HEADER | gt_bit_img_add_item1_list_by_file_header(obj, fh_array, count) | 批量通过文件头添加 item1 |
GT_USE_DIRECT_ADDR | gt_bit_img_add_item0_by_direct_addr(obj, addr) | 通过直接地址添加 item0 |
GT_USE_DIRECT_ADDR | gt_bit_img_add_item1_by_direct_addr(obj, addr) | 通过直接地址添加 item1 |
GT_USE_DIRECT_ADDR | gt_bit_img_add_item0_list_by_direct_addr(obj, addr_array, count) | 批量通过直接地址添加 item0 |
GT_USE_DIRECT_ADDR | gt_bit_img_add_item1_list_by_direct_addr(obj, addr_array, count) | 批量通过直接地址添加 item1 |
/** bitimg1 */
// 在 screen_home 屏幕控件中创建一个位图控件
gt_obj_st * bitimg1 = gt_bit_img_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(bitimg1, 100, 80);
// 设置控件尺寸
gt_obj_set_size(bitimg1, 48, 48);
// 设置位图值
gt_bit_img_set_value(bitimg1, 1);
// 设置动画时间 500ms
gt_bit_img_set_time(bitimg1, 500);
注:
gt_bit_img_add_item0/1的item_byte_size参数须传名字完整长度——引擎按该长度拷贝后自补结束符,传短一位名字即被截断,与资源包路径匹配失败会导致静默不画(无报错)。本节效果可在上方在线演示卡实时交互(v1.4.16 起在线演示所用 wasm 构建已编入gt_bit_img_*全部 14 个导出)。
与手册 2.6 节 API 一致:item0/item1 两组项目按 value 的每一位独立切换(0=item0、1=item1),active 是 16 位掩码可同时激活多个位置。大图标演示单 bit 状态切换与 8 种显示模式(2/4/5/7 为逐帧动画),LED 行演示多位掩码、指定位 set_value_bit 与移动模式/间隙。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* bitimg1 —— 摘自手册 2.6 节示例 */// 在 screen_home 屏幕控件中创建一个位图控件gt_obj_st * bitimg1 = gt_bit_img_create(screen_home);// 设置控件坐标gt_obj_set_pos(bitimg1, 100, 80);// 设置控件尺寸(首次取图后按 item 实际宽高自动修正)gt_obj_set_size(bitimg1, 48, 48);// 添加两组项目(真机:资源包内图片名;byte_size 须传名字完整长度,传短名字被截断将匹配失败)gt_bit_img_add_item0(bitimg1, ".:icon_off.bmp", 14);gt_bit_img_add_item1(bitimg1, ".:icon_on.bmp", 13);// 激活位(16 位掩码:多个 bit 同时激活即多位排列,右侧面板 LED 行为 6 位示例)gt_bit_img_set_active(bitimg1, 0x0001);// 设置位值:每一位独立选择该位的 item0(位=0)/ item1(位=1)gt_bit_img_set_value(bitimg1, 1);// 设置动画时间 500ms(显示模式 2/4/5/7 且对应组项目≥2 帧时逐帧播放)gt_bit_img_set_time(bitimg1, 500);// 官网演示无资源包:经 gt_src_init 把合成 BGRA 图按同名注册进 src 数组(同一解码路径)
