高通字库
版本 V2.0 · 更新于 2026-09-24

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
GT-HMI Engine 实时渲染 · 480×320
滚动到此处后加载引擎(约 2MB,仅一次)

屏幕控件是所有控件的父容器。真机用 gt_screen_set_bgcolor 设置背景色;官网演示经通用背景色桥注入(该 setter 在 wasm 构建同样生效于下一帧重绘)。

屏幕背景色 set_bgcolor
#f0f2f5
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
screen_demo.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_HEADERgt_img_set_by_file_header(img, fh)通过文件头信息加载图片—
GT_USE_DIRECT_ADDRgt_img_set_by_direct_addr(img, addr)通过直接地址加载图片—
GT_USE_DIRECT_ADDR_CUSTOM_SIZEgt_img_set_by_custom_size_addr(img, dac)通过自定义尺寸直接地址加载—
GT_USE_IMG_TRANSFORMgt_img_set_angle(img, angle)旋转角度(0~3599,0.1度单位)GT_ANGLE_NONE
GT_USE_IMG_TRANSFORMgt_img_set_zoom(img, zoom)缩放系数(256=1.0x)GT_ZOOM_NONE
GT_USE_IMG_TRANSFORMgt_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
GT-HMI Engine 实时渲染 · 480×320
滚动到此处后加载引擎(约 2MB,仅一次)

真机流程经资源包 gt_img_set_src(".:20.bmp") 取图;官网演示无资源包,经 wasm 桥注入原始 RGBA 像素(同一解码渲染路径)。可切换三种图片内容并开关轮廓遮罩。

图片内容 set_raw_data(演示注入 RGBA)
轮廓遮罩 set_masking
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
img_demo.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_etGT_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_etNORMAL
gt_label_set_font_encoding(label, encoding)文本编码:见 枚举速查表 gt_encoding_etUTF-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_etWRAP
/* 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");

运行后的标签控件效果见下方在线演示(可直接交互):

标签 gt_label
GT-HMI Engine 实时渲染 · 480×320
滚动到此处后加载引擎(约 2MB,仅一次)

与手册 2.3 节示例一致:演示字库为 18 点 GBK 黑体点阵(4bit 灰度抗锯齿),面板可改文本、颜色、对齐与字间距。

文本 set_text
字体颜色 set_font_color
#000000
对齐 set_font_align
字间距 set_space (x)0
灰度 set_font_gray
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
label_demo.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));

运行后的文本区控件效果见下方在线演示(可直接交互):

文本区 gt_textarea
GT-HMI Engine 实时渲染 · 480×320
滚动到此处后加载引擎(约 2MB,仅一次)

与手册 2.4 节一致:逐段追加带样式的文本(每段可独立颜色/粗体),支持清空。演示字库为 18 点 GBK 点阵(4bit 灰度)。

追加文本段 add_str(带样式)
clear_all_str 清空全部文本
行间距 set_line_gap(像素)0
默认字体颜色 set_font_color
#2c3e50
背景颜色 set_bg_color
#f5f7fa
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
textarea_demo.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, "请输入...");

运行后的输入框控件效果见下方在线演示(可直接交互):

输入框 gt_input
GT-HMI Engine 实时渲染 · 480×320
滚动到此处后加载引擎(约 2MB,仅一次)

与手册 2.5 节示例一致:单行内容 + 占位符(内容为空时显示)+ 密码模式(内容以 * 隐藏)。演示字库为 18 点 GBK 点阵(4bit 灰度)。

内容 set_value_by_len(清空后显示占位符)
密码模式 hide_value(内容以 * 显示;* 数=字节数,中文 UTF-8 3 字节/字)
字体颜色 set_font_color
#2c3e50
背景颜色 set_bg_color
#f5f7fa
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
input_demo.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_HEADERgt_bit_img_add_item0_by_file_header(obj, fh)通过文件头添加 item0
GT_USE_FILE_HEADERgt_bit_img_add_item1_by_file_header(obj, fh)通过文件头添加 item1
GT_USE_FILE_HEADERgt_bit_img_add_item0_list_by_file_header(obj, fh_array, count)批量通过文件头添加 item0
GT_USE_FILE_HEADERgt_bit_img_add_item1_list_by_file_header(obj, fh_array, count)批量通过文件头添加 item1
GT_USE_DIRECT_ADDRgt_bit_img_add_item0_by_direct_addr(obj, addr)通过直接地址添加 item0
GT_USE_DIRECT_ADDRgt_bit_img_add_item1_by_direct_addr(obj, addr)通过直接地址添加 item1
GT_USE_DIRECT_ADDRgt_bit_img_add_item0_list_by_direct_addr(obj, addr_array, count)批量通过直接地址添加 item0
GT_USE_DIRECT_ADDRgt_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 个导出)。

位图 gt_bit_img
GT-HMI Engine 实时渲染 · 480×320
滚动到此处后加载引擎(约 2MB,仅一次)

与手册 2.6 节 API 一致:item0/item1 两组项目按 value 的每一位独立切换(0=item0、1=item1),active 是 16 位掩码可同时激活多个位置。大图标演示单 bit 状态切换与 8 种显示模式(2/4/5/7 为逐帧动画),LED 行演示多位掩码、指定位 set_value_bit 与移动模式/间隙。

大图标状态位 set_value(bit0:0=待机蓝 1=运行绿)
显示模式 set_disp_mode(bit=0 列 / bit=1 列;静=首帧 动=逐帧动画 无=不画)
动画周期 set_time(模式 2/4/5/7 且该组项目≥2 帧时生效)
LED 位掩码 set_value(每位独立选 item0 灰环 / item1 绿点)
指定位 set_value_bit(单独开关第 4 个 LED,即 pattern bit3)
移动模式 set_move_mode(保持位=未激活位仍占位;不保持=收拢到起点。保持模式需用高位对齐掩码,引擎从 bit16 起扫描)
激活位数 set_active(配合移动模式看布局:不保持→收拢;保持→原位保留空槽)
LED 移动间隙 set_move_gap(相邻位间距 px)28
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
bitimg_demo.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 数组(同一解码路径)

相关资源

工具与下载