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

🎮 在线体验:本章控件的渲染效果可在 控件在线演示页 实时交互——GT-HMI Engine 以 WebAssembly 在浏览器内渲染,调整右侧参数即可实时查看控件效果,与真机渲染一致。

6.1 矩形控件

  在创建的屏幕控件中添加一个矩形控件并设置矩形控件属性。

API 参考:

函数说明默认值
gt_rect_create(parent)创建矩形控件—
gt_rect_set_bg_color(rect, color)设置背景颜色—
gt_rect_set_color_border(rect, color)设置边框颜色—
gt_rect_set_radius(rect, radius)设置圆角半径—
gt_rect_set_border(rect, border)设置边框宽度—
gt_rect_set_fill(rect, is_full)设置填充模式—
/* rect1 */
// 在 screen_home 屏幕控件中创建一个矩形控件
rect1 = gt_rect_create(screen_home);
// 设置矩形的位置为 (178, 100)
gt_obj_set_pos(rect1, 178, 100);
// 设置矩形的尺寸为(宽度 100 高度 100)
gt_obj_set_size(rect1, 100, 100);
// 设置四端角的半径为 0 即直角
gt_rect_set_radius(rect1, 0);
// 设置矩形的背景颜色为 0xff0000 红色
gt_rect_set_bg_color(rect1, gt_color_hex(0xff0000));
// 设置矩形的边框颜色为 0xff0000 红色
gt_rect_set_color_border(rect1, gt_color_hex(0xff0000));
// 设置矩形为填充
gt_rect_set_fill(rect1, 1);
// 设置矩形边框宽度为 0 即无边框
gt_rect_set_border(rect1, 0);

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

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

矩形的圆角、边框、填充/描边模式、背景色实时可调。

圆角半径 set_radius12
边框宽度 set_border0
填充模式 set_fill
背景色 set_bg_color
#409eff
边框色 set_color_border
#e6a23c
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
rect_demo.c
/* rect1 —— 摘自手册 6.1 节示例 */// 在 screen_home 屏幕控件中创建一个矩形控件rect1 = gt_rect_create(screen_home);// 设置矩形的位置为 (140, 80)gt_obj_set_pos(rect1, 140, 80);// 设置矩形的尺寸为(宽度 200 高度 160)gt_obj_set_size(rect1, 200, 160);// 设置四端角的半径为 12(右侧面板可调)gt_rect_set_radius(rect1, 12);// 设置矩形的背景颜色为 0x409eff 蓝色gt_rect_set_bg_color(rect1, gt_color_hex(0x409eff));// 设置矩形边框颜色为 0xe6a23c 橙色(边框宽度 > 0 时可见)gt_rect_set_color_border(rect1, gt_color_hex(0xe6a23c));// 设置矩形为填充模式(右侧面板可切换描边)gt_rect_set_fill(rect1, 1);// 设置矩形边框宽度为 0 即无边框(右侧面板可调)gt_rect_set_border(rect1, 0);

6.2 对话框控件

  在创建的屏幕控件中添加一个对话框控件并设置对话框控件属性。

API 参考:

函数说明默认值
gt_dialog_create(show_close_btn)创建空对话框—
gt_dialog_create_issue(show_close_btn, param)创建消息框对话框(含标题+内容+取消/确认按钮)—
gt_dialog_show(obj)显示对话框—
gt_dialog_close(obj)关闭并释放对话框—
gt_dialog_set_bgcolor(dialog, color)设置对话框背景颜色—
gt_dialog_set_border_color(dialog, color)设置边框颜色—
gt_dialog_set_border_width(dialog, width)设置边框宽度2
gt_dialog_set_border_radius(dialog, radius)设置边框圆角半径10
gt_dialog_set_max_opa(obj, max_opa)设置最大透明度—
gt_dialog_set_outside_auto_hide(dialog, auto_hide)点击外部区域自动关闭true
gt_dialog_set_anim_time(dialog, time)设置动画时间(ms)250
gt_dialog_set_content(dialog, "content")设置对话框内容—
/** dialog1 */
// 在 screen_home 屏幕控件中创建一个对话框控件
dialog1 = gt_dialog_create(true);
// 设置对话框的位置为(100, 54)
gt_obj_set_pos(dialog1, 100, 54);
// 设置对话框的尺寸为(宽度 257 高度 179)
gt_obj_set_size(dialog1, 257, 179);
// 设置对话框的背景颜色为 0xffffff 白色
gt_dialog_set_bgcolor(dialog1, gt_color_hex(0xffffff));
// 设置对话框的边框颜色为 0x000000 黑色
gt_dialog_set_border_color(dialog1, gt_color_hex(0x000000));
// 设置对话框的边框宽度为 2
gt_dialog_set_border_width(dialog1, 2);
// 设置对话框的边框圆角半径为 10
gt_dialog_set_border_radius(dialog1, 10);

  运行后点击"open dialog"按钮,显示对话框控件效果见下方在线演示(可直接交互):

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

对话框控件以顶层弹层呈现(无需父容器),show/close 控制显示与释放。注意:close 会释放控件,再次显示需重新创建;引擎销毁对象后不回填背景,故在对话框区域预置一块底板矩形用于关闭时盖掉残影。

显示 / 关闭
边框颜色 set_border_color
#3580bb
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
dialog_demo.c
/* dialog1 —— 摘自手册 6.2 节 */// 创建对话框(参数:是否显示右上角关闭按钮)dialog1 = gt_dialog_create(true);// 设置对话框的位置为(100, 70)gt_obj_set_pos(dialog1, 100, 70);// 设置对话框的尺寸为(宽度 280 高度 180)gt_obj_set_size(dialog1, 280, 180);// 设置对话框的背景颜色为白色gt_dialog_set_bgcolor(dialog1, gt_color_hex(0xFFFFFF));// 设置对话框的边框颜色gt_dialog_set_border_color(dialog1, gt_color_hex(0x3580BB));// 设置边框宽度为 2、圆角半径为 10gt_dialog_set_border_width(dialog1, 2);gt_dialog_set_border_radius(dialog1, 10);// 设置对话框内容并显示gt_dialog_set_content(dialog1, "提示消息");gt_dialog_show(dialog1);// 关闭并释放对话框(再次显示需重新创建)// gt_dialog_close(dialog1);

6.3 GIF 控件

  在创建的屏幕控件中添加一个 GIF 控件并设置 GIF 控件属性。

API 参考:

函数说明默认值
gt_gif_create(parent)创建 GIF 控件—
gt_gif_set_src(obj, "src")设置 GIF 文件路径—
char * gt_gif_get_src(obj)获取文件路径—
gt_gif_set_mode(obj, mode)设置播放模式:GT_GIF_MODE_REPEAT / ONCEREPEAT
gt_gif_play(obj)播放 GIF—
gt_gif_stop(obj)停止 GIF—
gt_gif_toggle(obj)播放/停止切换—
gt_gif_reset(obj)重置 GIF—
gt_gif_is_play(obj)是否正在播放—
/** gif1 */
// 在 screen_home 屏幕控件中创建一个 GIF 控件
gif1 = gt_gif_create(screen_home);
// 设置 GIF 控件的位置为(175,150)
gt_obj_set_pos(gif1, 175, 150);
// 设置 GIF 控件的大小为(宽度 116,高度 132)
gt_obj_set_size(gif1, 116, 132);
// 设置 GIF 文件为 "img_116x132_1.gif"
gt_gif_set_src(gif1, ".:img_116x132_1.gif");
// 播放 GIF 动图
gt_gif_play(gif1);

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

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

动图控件:内部定时器逐帧解码播放,REPEAT/ONCE 两种模式。真机经资源包 set_src(".:anim.gif") 取文件;官网演示无资源包,经 MODE 2 raw 直接注入 GIF 文件字节(6 帧 300ms 循环动画)。

播放控制
播放模式 set_mode
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
gif_demo.c
/* gif —— 摘自手册 6.3 节 */// 创建 GIF 控件gt_obj_st * gif1 = gt_gif_create(screen_home);// 设置位置 (200, 120) 与尺寸 80 x 80gt_obj_set_pos(gif1, 200, 120);gt_obj_set_size(gif1, 80, 80);// 设置 GIF 文件(资源包路径)gt_gif_set_src(gif1, ".:anim.gif");// 设置循环播放模式(默认 REPEAT)gt_gif_set_mode(gif1, GT_GIF_MODE_REPEAT);// 开始播放gt_gif_play(gif1);// 停止 / 重置// gt_gif_stop(gif1);// gt_gif_reset(gif1);

6.4 状态栏控件

  在创建的屏幕控件中添加一个状态栏控件并设置状态栏控件属性。

API 参考:

函数说明默认值
gt_status_bar_create(have_background)创建状态栏(全局单例)—
gt_status_bar_set_height(height)设置状态栏高度—
gt_status_bar_set_scale(left, center, right)设置左中右三区比例30, 40, 30
gt_status_bar_show_bg(show)显示/隐藏背景—
gt_status_bar_set_bg_color(color)设置背景颜色—
gt_status_bar_set_bg_opa(opa)设置背景透明度—
gt_status_bar_set_font_color(color)设置文本颜色—
gt_status_bar_set_font_size(size)设置字体大小(pt)—
gt_status_bar_set_font_family_cn/en(id)设置字体系列(中文/英文)—
gt_status_bar_set_font_thick_cn/en(thick)设置字体粗细—
gt_status_bar_left_add_icon("src")左侧添加图标—
gt_status_bar_left_add_text("text", width)左侧添加文本—
gt_status_bar_center_set_text("text")中间设置文本—
gt_status_bar_right_add_icon("src")右侧添加图标—
gt_status_bar_set_hide(hide)在当前屏幕隐藏/显示false
/** status_bar1 */
// 在 gt_ui_init UI 初始化时创建一个状态栏控件
gt_status_bar_create(true);
// 设置状态栏控件的高度为 30
gt_status_bar_set_height(30);
// 设置状态栏控件内元素宽度比例为(左:30,标题:40,右:30)
gt_status_bar_set_scale(30, 40, 30);
// 设置状态栏控件显示状态栏背景
gt_status_bar_show_bg(true);
// 设置状态栏控件背景颜色为 0x000000 黑色
gt_status_bar_set_bg_color(gt_color_hex(0x000000));
// 设置状态栏控件的左边文本为 "GT",文本宽度为 30
gt_status_bar_left_add_text("GT", 30);
// 设置状态栏控件的中间文本为 "12:17"
gt_status_bar_center_set_text("12:17");
// 设置状态栏控件的右边第一个图标为 1.png
gt_status_bar_right_add_icon(".:1.png");
// 设置状态栏控件的右边第二个图标为 2.png
gt_status_bar_right_add_icon(".:2.png");
// 设置状态栏控件的文本字体为矢量英文黑正
gt_status_bar_set_font_family_en(90);
// 设置状态栏控件的文本字体大小为 16
gt_status_bar_set_font_size(16);
// 设置状态栏控件的中字体使用 1Bit 灰度字体
gt_status_bar_set_font_gray(1);
// 设置状态栏控件的文本颜色为 0xffffff 白色
gt_status_bar_set_font_color(gt_color_hex(0xffffff));
// 设置状态栏控件的中文字体粗细为 22
gt_status_bar_set_font_thick_cn(22);
// 设置状态栏控件的英文字体粗细为 22
gt_status_bar_set_font_thick_en(22);

  运行后显示状态栏控件效果见下方在线演示(可直接交互):

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

状态栏是全局单例(无父容器、create 不返回对象),创建后横贯屏幕顶部:左侧可追加多个图标/文本槽,中间按比例占位一行文本。会遮挡所在屏幕顶部区域。

高度 set_height30
背景色 set_bg_color
#252c36
显隐 set_hide
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
status-bar_demo.c
/* status_bar —— 摘自手册 6.4 节 */// 创建状态栏(全局单例,参数:是否显示背景)gt_status_bar_create(true);// 设置状态栏高度为 30gt_status_bar_set_height(30);// 设置左/中/右三区宽度比例为(30:40:30)gt_status_bar_set_scale(30, 40, 30);// 显示状态栏背景gt_status_bar_show_bg(true);// 设置背景颜色为深灰gt_status_bar_set_bg_color(gt_color_hex(0x252C36));// 左侧添加文本 "GT"(宽度 30)gt_status_bar_left_add_text("GT", 30);// 中间设置文本 "12:17"gt_status_bar_center_set_text("12:17");// 设置文本颜色为白色、字号 16gt_status_bar_set_font_color(gt_color_hex(0xFFFFFF));gt_status_bar_set_font_size(16);// 在当前屏幕隐藏 / 重新显示// gt_status_bar_set_hide(true);

6.5 图表控件

  在创建的屏幕控件中添加一个图表控件并设置图表控件属性。

API 参考:

函数说明默认值
gt_graphs_create(parent)创建图表控件—
gt_graphs_set_axis(obj, axis)设置坐标轴配置(含刻度、标尺、外框)—
gt_graphs_add_series_line(obj, line_style)添加数据系列线配置(类型/颜色/线宽/透明度)—
gt_graphs_series_add_point_list_by(obj, series_idx, list, count)按索引批量添加数据点—
gt_graphs_series_add_point_by(obj, series_idx, point, text)按索引添加单个数据点—
gt_graphs_set_self_adaptive(obj, enabled)自适应坐标范围false
gt_graphs_set_show_ruler(obj, enabled)显示坐标标尺false
gt_graphs_set_anti_axis_hor_dir(obj, enabled)反转横坐标方向—
gt_graphs_set_anti_axis_ver_dir(obj, enabled)反转纵坐标方向—
gt_graphs_set_fifo_max_points_count(obj, depth)FIFO 模式,自动删除旧点,0=不限制0
gt_graphs_show_point_value(obj, series_idx, enabled)显示数据点数值false
gt_graphs_set_font_color(graphs, color)设置坐标轴字体颜色gt_color_black()
gt_graphs_set_font_size(graphs, size)设置坐标轴字体大小(pt)—
/** graph1 */
// 在 screen_home 屏幕控件中创建一个图表控件
graph1 = gt_graphs_create(screen_home);
// 设置图表控件的位置为(16,13)
gt_obj_set_pos(graph1, 16, 13);
// 设置图表控件的尺寸为(宽 409,高 283)
gt_obj_set_size(graph1, 409, 283);
// 初始化坐标集
gt_point_f_st graph1Rand0[] = {
    { 30, 30 },
    { 60, 70 },
    { 90, 70 },
    { 120, 150 },
    { 150, 130 },
    { 180, 180 }
};
// 初始化线图配置结构体
gt_axis_st graph1Axis = {
    // 水平轴
    .hor = { .start = 0, .end = 200 },
    // 垂直轴
    .ver = { .start = 0, .end = 200 },
    // 标尺水平跨度为 10
    .hor_unit = 10,
    // 标尺垂直跨度为 10
    .ver_unit = 10,
    // 外边框设置
    .scale = {
        .width = 3,                      // 外边框线宽为 3
        .color = gt_color_hex(0x000000), // 外边框颜色
        .opa = GT_OPA_70,                // 外边框透明度为 70
    },
    // 标尺设置
    .grid = {
        .width = 1,                      // 标尺线宽为 1
        .color = gt_color_hex(0x000000), // 标尺颜色
        .opa = GT_OPA_30,                // 标尺透明度为 30
    },
};
// 用线图配置结构体配置图表控件
gt_graphs_set_axis(graph1, &graph1Axis);
// 设置图表控件关闭横坐标反转
gt_graphs_set_anti_axis_hor_dir(graph1, false);
// 设置图表控件关闭纵坐标反转
gt_graphs_set_anti_axis_ver_dir(graph1, false);
// 初始化线设置配置结构体
gt_line_st graph1Line0 = {
    .width = 2,                      // 线宽为 2
    .color = gt_color_hex(0xff0000), // 线颜色为 0xff0000
    .opa = GT_OPA_80,                // 线透明度为 80
    .type = GT_GRAPHS_TYPE_LINE,     // 图表类型为折线图
};
// 用线设置配置结构体配置图表控件
gt_series_points_st * graph1Ser0 =
    gt_graphs_add_series_line(graph1, &graph1Line0);
// 设置图表控件的坐标集为 graph1Rand0
gt_graphs_series_add_point_list_by(graph1, 0, graph1Rand0, 6);
// 设置图表控件线图为关闭自适应最值
gt_graphs_set_self_adaptive(graph1, false);
// 设置图表控件显示坐标系数
gt_graphs_set_show_ruler(graph1, true);

  运行后图表控件效果如下方在线演示所示,还可以将图表控件设置为散点图、曲线图和柱状图。

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

同一组数据可在散点/折线/曲线/柱状四种形态间切换(gt_line_st.type),支持双系列对照;默认开启 FIFO 滚动窗口(深度 20),旧点自动删除、曲线始终在图表范围内。

数据 series_add_point_by
图表形态 gt_line_st.type(同一组数据换形态重绘)
系列数(副系列橙色,opa<GT_OPA_MIN 时引擎跳过绘制)
标尺区 set_show_ruler(开启后为刻度预留边距)
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
graphs_demo.c
/* graph1 —— 手册 6.5 节示例(节选) */// 在 screen_home 屏幕控件中创建一个图表控件graph1 = gt_graphs_create(screen_home);// 设置图表控件的位置与尺寸gt_obj_set_pos(graph1, 40, 40);gt_obj_set_size(graph1, 400, 240);// 初始化坐标集(数据点 {x, y})gt_point_f_st graph1Rand0[] = {    { 0, 30 }, { 25, 70 }, { 50, 55 },    { 75, 130 }, { 100, 110 }, { 125, 170 }};// 初始化坐标轴:水平/垂直范围 0~200,标尺步长 20gt_axis_st graph1Axis = {    .hor = { .start = 0, .end = 200 },    .ver = { .start = 0, .end = 200 },    .hor_unit = 20,    .ver_unit = 20,    .scale = { .width = 2, .color = gt_color_hex(0x000000) },};gt_graphs_set_axis(graph1, &graph1Axis);// 添加折线系列(蓝色 2px),再逐点加入数据。// 系列形态由 gt_line_st.type 决定:GT_GRAPHS_TYPE_POINT(散点) / LINE(折线)// / CURVE(曲线) / BAR(柱状,line.width 即柱宽);opa < GT_OPA_MIN(3) 则该系列不绘制gt_graphs_add_series_line(graph1, &(gt_line_st){    .color = gt_color_hex(0x409eff), .opa = 255,    .width = 2, .type = GT_GRAPHS_TYPE_LINE });for (unsigned i = 0; i < 6; i++)    gt_graphs_series_add_point_by(graph1, 0, &graph1Rand0[i], NULL);// 多系列:再调一次 add_series_line(series_index 依次 0、1…),本页"双系列"即此gt_graphs_add_series_line(graph1, &(gt_line_st){    .color = gt_color_hex(0xe6a23c), .width = 2, .type = GT_GRAPHS_TYPE_BAR });// FIFO 模式:点数超过深度后自动删最旧的点(滚动波形)gt_graphs_set_fifo_max_points_count(graph1, 20);

6.6 布局控件

  在创建的屏幕控件中添加一个自适应布局控件并设置自适应布局控件属性。

API 参考:

函数说明默认值
gt_layout_init(obj, container)用配置结构体初始化布局—
gt_layout_set_type(obj, type)动态切换布局类型:GT_LAYOUT_TYPE_FIXED / FLEXFIXED
gt_layout_get_type(obj)获取当前布局类型—
gt_layout_update_core(obj)触发布局重算—
gt_layout_row_grow(obj)子控件横向排列—

布局通过 gt_obj_container_st 结构体配置。结构体字段和可选值详见 枚举速查表 布局相关枚举。

/** layout1 init */
// 在 screen_home 屏幕控件中创建一个自适应布局控件
gt_obj_st * layout1 = gt_obj_create(screen_1);
// 初始化自适应布局的配置结构体
gt_obj_container_st layout1container = {
    .gap = 0,                                          // 左右边距为 0
    .layout_type = GT_LAYOUT_TYPE_FLEX,                // 溢出时不压缩
    .flex_direction = GT_LAYOUT_FLEX_DIR_ROW,          // 主轴方向为水平向右
    .justify_content = GT_LAYOUT_JUSTIFY_CONTENT_CENTER, // 主轴对齐方式为居中对齐
    .align_items = GT_LAYOUT_ALIGN_ITEMS_START,        // 交叉轴对齐方式为顶部对齐
};
// 用配置结构体配置自适应布局控件
gt_layout_init(layout1, &layout1container);
// 设置自适应布局控件的位置为(148,85)
gt_obj_set_pos(layout1, 148, 85);
// 设置自适应布局控件的尺寸为(宽 230,高 137)
gt_obj_set_size(layout1, 230, 137);
// 需要添加到自适应布局控件中的其他控件,应修改其所属布局
input1 = gt_input_create(layout1);

  主轴和交叉轴的基本概念:

  • 主轴:Flex 组件布局方向的轴线,子元素默认沿着主轴排列。主轴开始的位置称为主轴起始点,结束位置称为主轴结束点。
  • 交叉轴:垂直于主轴方向的轴线,交叉轴开始的位置称为交叉轴起始点,结束位置称为交叉轴结束点。

  主轴为水平方向的 Flex 容器示意图见下方在线演示(可直接交互):

图2-25 Flex容器主轴示意图

图2-25 Flex容器主轴示意图

  主轴方向为水平向右时不同的主轴对齐方式的结构示意图见下方在线演示(可直接交互):

图2-26 主轴对齐方式示意图

图2-26 主轴对齐方式示意图

  主轴方向为水平向右时不同的交叉轴对齐方式的结构示意图见下方在线演示(可直接交互):

图2-27 交叉轴对齐方式示意图

图2-27 交叉轴对齐方式示意图

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

Flex 布局容器:子控件沿主轴按对齐方式与间距自动排列,无需逐个 set_pos。三个标签子项随右侧面板的间距 / 主轴对齐 / 排列方向即时重排。

子项间距 gap20
主轴对齐 justify_content
排列方向 flex_direction
▸查看 C 代码与手册示例一致 · 点面板参数自动高亮对应行
layout_demo.c
/* layout —— 摘自手册 6.6 节 */// 创建自适应布局容器(普通 obj + container 配置)gt_obj_st * layout1 = gt_obj_create(screen_1);// 初始化布局配置结构体gt_obj_container_st layout1container = {    .gap = 20,                                            // 子项间距    .layout_type = GT_LAYOUT_TYPE_FLEX,                   // 自适应布局    .flex_direction = GT_LAYOUT_FLEX_DIR_ROW,             // 主轴水平向右    .justify_content = GT_LAYOUT_JUSTIFY_CONTENT_CENTER,  // 主轴居中对齐    .align_items = GT_LAYOUT_ALIGN_ITEMS_START,           // 交叉轴顶部对齐};gt_layout_init(layout1, &layout1container);// 设置布局容器的位置与尺寸gt_obj_set_pos(layout1, 60, 80);gt_obj_set_size(layout1, 360, 160);// 子控件直接创建在布局容器下(注意:create 后需 update 触发排列)label1 = gt_label_create(layout1);gt_obj_set_size(label1, 60, 40);// … 再添加两个标签后触发布局重算gt_layout_update_core(layout1);// 运行期可动态改 gap / 对齐方式后再次 update_core 重排

相关资源

工具与下载