🎮 在线体验：本章控件的渲染效果可在 控件在线演示页 实时交互——GT-HMI Engine 以 WebAssembly 在浏览器内渲染，调整右侧参数即可实时查看控件效果，与真机渲染一致。
7.1 Media Player 播放器流控件
在创建的屏幕控件中添加一个 Media Player 播放器流控件并设置 Media Player 播放器流控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_media_player_create(parent) | 创建播放器流控件 | — |
gt_media_player_set_raw(obj, raw) | 设置帧数据格式 | — |
gt_media_player_set_total_time(obj, total_time) | 设置总时长（秒） | — |
gt_media_player_set_current_time(obj, current_time) | 设置当前进度（秒） | — |
gt_media_player_get_current_time(obj) | 获取当前进度（秒） | — |
gt_media_player_set_play_cb(obj, play_cb, user_data) | 设置播放回调 | — |
gt_media_player_set_stop_cb(obj, stop_cb, user_data) | 设置暂停回调 | — |
gt_media_player_set_slider_change_cb(obj, cb, user_data) | 设置滑动条跳转回调 | — |
/** media_player1 */
// 初始化播放图片格式结构体
gt_img_raw_st raw_st = {
.buffer = raw_buf, // 图片颜色数据
.opa = NULL, // 图片透明度
.width = 138, // 图片宽度
.height = 131, // 初始图片高度
};
// 在 screen_home 屏幕控件中创建一个 Media Player 播放器流控件
media_player1 = gt_media_player_create(screen_home);
// 设置 Media Player 播放器流控件的位置为（29, 39）
gt_obj_set_pos(media_player1, 29, 39);
// 设置 Media Player 播放器流控件的大小为（宽 240，高 240）
gt_obj_set_size(media_player1, 240, 240);
// 设置 Media Player 播放器流控件的总时长为 MEDIA_NUM_MAX
gt_media_player_set_total_time(media_player1, MEDIA_NUM_MAX);
// 设置 Media Player 播放器流控件的当前进度为 0
gt_media_player_set_current_time(media_player1, 0);
// 设置 Media Player 播放器流控件的播放图片格式
gt_media_player_set_raw(media_player1, &raw_st);
// 设置 Media Player 播放器流控件的播放回调函数为 play_cb
gt_media_player_set_play_cb(media_player1, play_cb, NULL);
// 设置 Media Player 播放器流控件的暂停回调函数为 stop_cb
gt_media_player_set_stop_cb(media_player1, stop_cb, NULL);
// 设置 Media Player 播放器流控件通过滑动条来设置当前时间
gt_media_player_set_slider_change_cb(media_player1, value_change_cb, NULL);
// 设置 Media Player 播放器流控件开始播放
gt_anim_init_start();
还需要定义一个动画播放函数。
static void gt_anim_init_start(void)
{
gt_anim_st anim_del;
gt_anim_init(&anim_del);
// 设置动画的时间间隔为 1000ms
gt_anim_set_time(&anim_del, 1000);
// 设置动画播放的次数为无限循环
gt_anim_set_repeat_count(&anim_del, GT_ANIM_REPEAT_INFINITE);
gt_anim_set_target(&anim_del, media_player1);
gt_anim_set_exec_cb(&anim_del, _scr_anim_del_ready_cb);
anim_del_p = gt_anim_start(&anim_del);
if (NULL == anim_del_p) {
GT_CHECK_PRINT(anim_del_p = gt_anim_start(&anim_del));
}
}
// 每一帧的播放回调函数
static void _scr_anim_del_ready_cb(struct gt_anim_s * anim)
{
// 读取一帧图片的数据
bsp_qspi_flash_read(media_current * IMG_BUFF_SIZE,
IMG_BUFF_SIZE, raw_buf);
// 设置 Media Player 播放器流控件的当前进度
gt_media_player_set_current_time(media_player1, media_current);
// 显示新的一帧内容
gt_disp_invalid_area(media_player1);
// 帧数加一
++media_current;
// 到最后一帧后，回到第一帧
if (media_current == MEDIA_NUM_MAX) {
media_current = 0;
}
}
交互状态机说明（实测确认，建议开发者注意）：
gt_media_player_set_raw内部会将控件置为播放态（playing=true、隐藏标题栏），播放态下只显示封面/帧画面。- 进度滑条是控件的子对象，创建时即为隐藏状态，唯一的浮现路径是控件收到点击释放事件（
GT_EVENT_TYPE_INPUT_RELEASED）：播放态点击画布 → 切换为暂停态并浮现进度条（约 150ms 动画）；暂停态再次点击 → 恢复播放并隐藏进度条。 - 因此
gt_media_player_set_current_time写入的进度值只有在暂停态（滑条可见）时才会反映到画面上；播放态调用值会照写但画面无变化——这不是不生效，是滑条不可见的设计行为。演示或调试时请先将控件切到暂停态再观察进度变化。
播放器流 gt_media_player
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
视频流播放壳：封面图 + 播放/暂停按钮 + 进度滑条。引擎交互设计为播放态只显封面，暂停（停止）态浮现进度滑条与暂停符号；播放/暂停经事件回调对接业务，进度由 set_current_time 驱动。
播放控制（与画布点击等效）
当前进度 set_current_time（秒）60
总时长 set_total_time（秒）240
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
media-player_demo.c
/* media_player —— 摘自手册 7.1 节 */// 创建播放器流控件gt_obj_st * mplayer = gt_media_player_create(screen_home);// 位置 (90, 60)，尺寸 300 x 200gt_obj_set_pos(mplayer, 90, 60);gt_obj_set_size(mplayer, 300, 200);// 设置封面帧数据（真机为视频流首帧 / 资源图）gt_media_player_set_raw(mplayer, &cover_raw);// 设置总时长 240 秒、当前进度 60 秒（进度滑条同步）gt_media_player_set_total_time(mplayer, 240);gt_media_player_set_current_time(mplayer, 60);// 注册播放 / 暂停回调（对接业务播放器）gt_media_player_set_play_cb(mplayer, on_play, NULL);gt_media_player_set_stop_cb(mplayer, on_stop, NULL);// 注册进度条拖动回调（拖动跳转）gt_media_player_set_slider_change_cb(mplayer, on_seek, NULL);// 引擎交互：播放态只显封面；停止（暂停）态浮现进度滑条。// 真机由触摸释放事件切换，官网演示经事件注入：gt_event_send(mplayer, GT_EVENT_TYPE_INPUT_RELEASED, NULL);7.2 圆弧控件
在创建的屏幕控件中添加一个圆弧控件并设置圆弧控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_arc_create(parent) | 创建圆弧控件 | — |
gt_arc_set_rounded(obj, rounded) | 设置弧形指针为圆形 | false |
gt_arc_set_bg_color(obj, color) | 设置背景颜色 | — |
gt_arc_set_bg_start_end_angle(obj, start, end) | 设置背景起始/结束角度 | 0, 0 |
gt_arc_set_bg_width(obj, width) | 设置背景宽度 | 0 |
gt_arc_set_act_color(obj, color) | 设置活跃颜色 | — |
gt_arc_set_act_start_end_angle(obj, start, end) | 设置活跃起始/结束角度 | 0, 0 |
gt_arc_set_act_width(obj, width) | 设置活跃宽度 | 0 |
gt_arc_set_value_min_max(obj, min, max) | 设置数值范围 | 0, 0 |
gt_arc_set_value(obj, value) | 设置当前值 | 0 |
gt_arc_set_value_step(obj, step) | 设置步进值 | 0 |
gt_arc_get_value(obj) | 获取当前值 | — |
gt_arc_set_knob_color(obj, color) | 设置旋钮颜色 | — |
gt_arc_set_knob_width(obj, width) | 设置旋钮宽度 | 0 |
gt_arc_set_knob_dot(obj, width) | 设置活跃弧末端的指示点直径，0=禁用 | 0 |
gt_arc_set_touch_disable(obj, disable) | 禁用触摸 | false |
gt_arc_set_draw_bg(obj, draw_bg) | 是否绘制背景弧 | true |
gt_arc_set_act_img(obj, "src") | 设置活跃弧图片 | — |
gt_arc_set_bg_img(obj, "src") | 设置背景弧图片 | — |
gt_arc_set_knob_img(obj, "src") | 设置旋钮图片 | — |
gt_arc_set_act_fade(obj, inner_w, outer_w) | 设置活跃弧内/外边缘渐隐宽度 | 0, 0 |
// 在 screen_home 屏幕控件中创建一个圆弧控件
gt_obj_st * arc_obj = gt_arc_create(screen_home);
// 设置圆弧控件的位置为(100, 50)
gt_obj_set_pos(arc_obj, 100, 50);
// 设置圆弧控件的大小为(400, 400)
gt_obj_set_size(arc_obj, 400, 400);
// 设置圆弧控件的背景颜色为 0X000000
gt_obj_set_bgcolor(arc_obj, gt_color_hex(0X000000));
// 设置圆弧控件的活跃颜色为 0x03F6FF
gt_arc_set_act_color(arc_obj, gt_color_hex(0x03F6FF));
// 将弧形指针设置为圆形
gt_arc_set_rounded(arc_obj, true);
// 设置背景宽度为 20
gt_arc_set_bg_width(arc_obj, 20);
// 设置活跃宽度为 20
gt_arc_set_act_width(arc_obj, 20);
// 设置起始角度为210,结束角度为330
gt_arc_set_bg_start_end_angle(arc_obj, 210, 330);
// 设置圆弧的最小值为0,最大值为100
gt_arc_set_value_min_max(arc_obj, 0, 100);
// 设置圆弧起始值为30
gt_arc_set_value(arc_obj, 30);
// 设置圆弧步进单位为1
gt_arc_set_value_step(arc_obj, 1);
// 设置圆弧控件旋钮宽为30
gt_arc_set_knob_width(arc_obj, 30);
// 设置圆弧控件旋钮颜色为 0X03F6FF
gt_arc_set_knob_color(arc_obj, gt_color_hex(0X03F6FF));
圆弧 gt_arc
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
与手册 7.2 节示例一致：调当前值看活跃弧长度变化；画布内可直接拖动旋钮。
当前值 set_value30
弧宽度 set_bg_width / set_act_width20
活跃弧颜色 set_act_color
#03f6ff
背景弧颜色 set_bg_color
#dcdfe6
旋钮颜色 set_knob_color
#409eff
旋钮中心点直径 set_knob_dot36
中心点独立颜色 set_knob_dot_color
#ff9f43
指针形状 set_rounded
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
arc_demo.c
/* arc_obj —— 摘自手册 7.2 节示例 */// 在 screen_home 屏幕控件中创建一个圆弧控件gt_obj_st * arc_obj = gt_arc_create(screen_home);// 设置圆弧控件的位置与大小gt_obj_set_pos(arc_obj, 120, 40);gt_obj_set_size(arc_obj, 240, 240);// 设置活跃弧颜色为 0x03f6ff 青色gt_arc_set_act_color(arc_obj, gt_color_hex(0x03F6FF));// 将弧形指针设置为圆形（右侧面板可切换平头）gt_arc_set_rounded(arc_obj, true);// 设置背景弧宽度为 20（右侧面板可调）gt_arc_set_bg_width(arc_obj, 20);// 设置活跃弧宽度为 20gt_arc_set_act_width(arc_obj, 20);// 设置起始角度为 210，结束角度为 330gt_arc_set_bg_start_end_angle(arc_obj, 210, 330);// 设置圆弧的最小值为 0，最大值为 100gt_arc_set_value_min_max(arc_obj, 0, 100);// 设置圆弧当前值为 30（右侧面板可调，也可在画布上拖动）gt_arc_set_value(arc_obj, 30);// 设置圆弧步进单位为 1gt_arc_set_value_step(arc_obj, 1);// 设置圆弧控件旋钮宽为 30gt_arc_set_knob_width(arc_obj, 30);// 设置旋钮颜色（右侧面板可调）gt_arc_set_knob_color(arc_obj, gt_color_hex(0xFFFFFF));// 设置旋钮中心点直径——引擎与旋钮同心、同色绘制，直径需大于旋钮宽 30 才可见gt_arc_set_knob_dot(arc_obj, 36);7.3 日历控件
在创建的屏幕控件中添加一个日历控件并设置日历控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_calendar_create(parent) | 创建日历控件 | — |
gt_calendar_set_cn(obj, is_cn) | 显示中文日期 | — |
gt_calendar_set_today(obj, year, month, day) | 设置当前日期 | — |
gt_calendar_set_day_type(obj, year, month, day, type) | 设置日期类型：GT_CALENDAR_DAY_TYPE_NORMAL / HOLIDAY / WORKDAY | — |
gt_calendar_set_border_color(obj, color) | 设置边框颜色 | — |
gt_calendar_set_border_width(obj, width) | 设置边框宽度 | — |
gt_calendar_set_font_color(obj, color) | 设置字体颜色 | gt_color_white() |
gt_calendar_set_font_size(obj, size) | 设置字体大小（pt） | — |
gt_calendar_set_font_align(obj, align) | 对齐方式：见 枚举速查表 gt_align_et | GT_ALIGN_CENTER_MID |
gt_calendar_set_font_family(obj, family) | 设置字体系列 | — |
gt_calendar_set_font_cjk(obj, cjk) | 设置 CJK 字体变体 | — |
gt_calendar_set_font_color_to_today(obj, color) | 设置今日日期颜色 | gt_color_red() |
gt_calendar_set_font_color_to_weekend(obj, color) | 设置周末日期颜色 | 0x808080 |
gt_calendar_set_font_color_to_other_month(obj, color) | 设置其他月份日期颜色 | 0x404040 |
// 在 screen_home 屏幕控件中创建一个日历控件
gt_obj_st * calendar_obj = gt_calendar_create(screen_home);
// 设置日历控件在屏幕中的相对位置为(89, 40)
gt_obj_set_pos_relative(calendar_obj, screen_home, 89, 40);
// 设置日历控件的大小为(289, 209)
gt_obj_set_size(calendar_obj, 289, 209);
// 设置日历控件的背景颜色为 0x252C36
gt_obj_set_bgcolor(calendar_obj, gt_color_hex(0x252C36));
// 设置日历控件的字体颜色为 0xFFFFFF
gt_calendar_set_font_color(calendar_obj, gt_color_hex(0xFFFFFF));
// 设置日历控件的字体类型 _16_dian_zhen_zhong_wen__ji_chu_
gt_calendar_set_font_family(calendar_obj
, _16_dian_zhen_zhong_wen__ji_chu_);
gt_calendar_set_font_cjk(calendar_obj, 0);
// 设置日历控件字体对齐方式为居中对齐
gt_calendar_set_font_align(calendar_obj, GT_ALIGN_CENTER_MID);
// 设置日历控件的边框颜色为 0x0097e6
gt_calendar_set_border_color(calendar_obj
, gt_color_hex(0x0097e6));
// 设置日历控件的边框宽度为 0
gt_calendar_set_border_width(calendar_obj, 0);
// 设置日历控件显示中文日期
gt_calendar_set_cn(calendar_obj, true);
// 设置日历控件当前日期为2000/12/17
gt_calendar_set_today(calendar_obj, 2000, 12, 17);
// 设置日历控件当前日期颜色为 0x0097e6
gt_calendar_set_font_color_to_today(calendar_obj
, gt_color_hex(0x0097e6));
// 设置日历控件休息日日期颜色为 0xFF0000
gt_calendar_set_font_color_to_weekend(calendar_obj
,gt_color_hex(0xFF0000));
// 设置日历控件其他月份日期颜色为 0x777777
gt_calendar_set_font_color_to_other_month(calendar_obj
,gt_color_hex(0x777777));
日历 gt_calendar
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
月历视图：深色底白字，今日日期高亮，支持中文日期头与切换日期（换月自动翻页）。
当前日期 set_today
今日高亮 set_font_color_to_today
#e69700
底色 gt_obj_set_bgcolor
#252c36
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
calendar_demo.c
/* calendar —— 摘自手册 7.3 节 */// 创建日历控件gt_obj_st * calendar_obj = gt_calendar_create(screen_home);// 位置 (89, 40)，尺寸 289 x 240gt_obj_set_pos(calendar_obj, 89, 40);gt_obj_set_size(calendar_obj, 289, 240);// 深色背景 + 白色字体gt_obj_set_bgcolor(calendar_obj, gt_color_hex(0x252C36));gt_calendar_set_font_color(calendar_obj, gt_color_hex(0xFFFFFF));gt_calendar_set_font_size(calendar_obj, 16);// 显示中文日期头gt_calendar_set_cn(calendar_obj, true);// 设置当前日期（切换日期自动翻月）gt_calendar_set_today(calendar_obj, 2026, 10, 15);// 今日日期高亮颜色gt_calendar_set_font_color_to_today(calendar_obj, gt_color_hex(0xE69700));// 周末 / 其他月份日期颜色// gt_calendar_set_font_color_to_weekend(calendar_obj, gt_color_hex(0xFF0000));// gt_calendar_set_font_color_to_other_month(calendar_obj, gt_color_hex(0x777777));7.4 聊天框控件
在创建的屏幕控件中添加一个聊天框控件并设置聊天框控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_chat_create(parent) | 创建聊天框控件 | — |
gt_chat_set_bg_color(chat, color) | 设置聊天框背景颜色 | — |
gt_chat_set_msg_radius(chat, radius) | 设置消息气泡圆角 | 0 |
gt_chat_set_msg_space(chat, space_x, space_y) | 设置消息间距 | 0, 0 |
gt_chat_set_send_msg_bg_color(chat, color) | 设置发送消息背景颜色 | — |
gt_chat_set_received_msg_bg_color(chat, color) | 设置接收消息背景颜色 | — |
gt_chat_set_send_msg_border_color(chat, color) | 设置发送消息边框颜色 | — |
gt_chat_set_received_msg_border_color(chat, color) | 设置接收消息边框颜色 | — |
gt_chat_set_send_msg_border_width(chat, width) | 设置发送消息边框宽度 | — |
gt_chat_set_received_msg_border_width(chat, width) | 设置接收消息边框宽度 | — |
gt_chat_set_send_msg_font_color(chat, color) | 设置发送消息字体颜色 | — |
gt_chat_set_received_msg_font_color(chat, color) | 设置接收消息字体颜色 | — |
gt_chat_set_font_size(chat, size) | 设置字体大小（pt） | — |
gt_chat_set_font_family(chat, family) | 设置字体系列 | — |
gt_chat_set_font_cjk(chat, cjk) | 设置 CJK 字体变体 | — |
gt_chat_add_send_text_msg(chat, "msg") | 添加发送文本消息 | — |
gt_chat_add_received_text_msg(chat, "msg") | 添加接收文本消息 | — |
gt_chat_add_send_voice_msg(chat, tim_s) | 添加发送语音消息（秒） | — |
gt_chat_add_received_voice_msg(chat, tim_s) | 添加接收语音消息（秒） | — |
gt_chat_clean_all_msg(chat) | 清除所有消息 | — |
// 在 screen_home 屏幕控件中创建一个聊天框控件
gt_obj_st * chat_obj = gt_chat_create(screen_home);
// 设置聊天框控件在屏幕中的相对位置为(78, 41)
gt_obj_set_pos_relative(chat_obj, screen_home, 78, 41);
// 设置聊天框控件的大小为(300, 226)
gt_obj_set_size(chat_obj, 300, 226);
// 设置聊天框控件显示背景
gt_obj_show_bg(chat_obj, true);
// 设置聊天框控件的字体为 _16_dian_zhen_zhong_wen__ji_chu_
gt_chat_set_font_family(chat_obj
, _16_dian_zhen_zhong_wen__ji_chu_);
gt_chat_set_font_cjk(chat_obj, 0);
// 设置聊天框背景的颜色为 0xf5f5f5
gt_chat_set_bg_color(chat_obj, gt_color_hex(0xf5f5f5));
// 设置聊天框控件的信息圆角为 6
gt_chat_set_msg_radius(chat_obj, 6);
// 设置聊天框控件的信息间隔为(6, 6)
gt_chat_set_msg_space(chat_obj, 6, 6);
// 设置聊天框控件的发送信息背景颜色为 0x95ec69
gt_chat_set_send_msg_bg_color(chat_obj
, gt_color_hex(0x95ec69));
// 设置聊天框控件的接收信息背景颜色为 0xffffff
gt_chat_set_received_msg_bg_color(chat_obj
, gt_color_hex(0xffffff));
// 设置聊天框控件的发送信息边框颜色为 0x95ec69
gt_chat_set_send_msg_border_color(chat_obj
, gt_color_hex(0x95ec69));
// 设置聊天框控件的接收信息边框颜色为 0xdcdcdc
gt_chat_set_received_msg_border_color(chat_obj
, gt_color_hex(0xdcdcdc));
// 设置聊天框控件的发送信息边框宽度为0
gt_chat_set_send_msg_border_width(chat_obj, 0);
// 设置聊天框控件的接收信息边框宽度为1
gt_chat_set_received_msg_border_width(chat_obj, 1);
// 设置聊天框控件的发送信息字体颜色为 0x000000
gt_chat_set_send_msg_font_color(chat_obj
, gt_color_hex(0x000000));
// 设置聊天框控件的接收信息字体颜色为 0x000000
gt_chat_set_received_msg_font_color(chat_obj
, gt_color_hex(0x000000));
// 添加聊天框控件的接收信息 "你好"
gt_chat_add_received_text_msg(chat_obj, "你好");
// 添加聊天框控件的发送信息 "Hi"
gt_chat_add_send_text_msg(chat_obj, "Hi");
// 添加聊天框控件接收一条6秒的语音
gt_chat_add_received_voice_msg(chat_obj, 6);
// 添加聊天框控件发送一条10秒的语音
gt_chat_add_send_voice_msg(chat_obj, 10);
聊天框 gt_chat
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
即时通讯式消息列表：接收（左侧白底）与发送（右侧绿底）气泡分行排列，支持文本与语音消息、气泡圆角与底色调色。
添加消息
清空 clean_all_msg
气泡圆角 set_msg_radius6
发送气泡底色
#95ec69
接收气泡底色
#ffffff
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
chat_demo.c
/* chat —— 摘自手册 7.4 节 */// 创建聊天框控件gt_obj_st * chat_obj = gt_chat_create(screen_home);// 位置 (60, 40)，尺寸 360 x 240gt_obj_set_pos(chat_obj, 60, 40);gt_obj_set_size(chat_obj, 360, 240);// 聊天框背景 / 气泡圆角 / 消息间距gt_chat_set_bg_color(chat_obj, gt_color_hex(0xF5F5F5));gt_chat_set_msg_radius(chat_obj, 6);gt_chat_set_msg_space(chat_obj, 6, 6);// 发送消息绿底、接收消息白底，字体均黑色gt_chat_set_send_msg_bg_color(chat_obj, gt_color_hex(0x95EC69));gt_chat_set_received_msg_bg_color(chat_obj, gt_color_hex(0xFFFFFF));gt_chat_set_send_msg_font_color(chat_obj, gt_color_hex(0x000000));gt_chat_set_received_msg_font_color(chat_obj, gt_color_hex(0x000000));gt_chat_set_font_size(chat_obj, 16);// 添加文本消息（接收在左、发送在右）gt_chat_add_received_text_msg(chat_obj, "文本第二行");gt_chat_add_send_text_msg(chat_obj, "确定");// 添加一条 6 秒的语音消息gt_chat_add_received_voice_msg(chat_obj, 6);// 清除所有消息// gt_chat_clean_all_msg(chat_obj);7.5 MarkDown 解析控件
在创建的屏幕控件中添加一个 MarkDown 解析控件并设置 MarkDown 解析控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_markdown_create(parent) | 创建 Markdown 解析控件 | — |
gt_markdown_set_text(markdown, "text", len) | 设置 Markdown 源文本（⚠ 必须在 gt_obj_set_size 之后调用） | — |
gt_markdown_set_font_info_large(markdown, font_info) | 设置大型文本字体（h1/h2） | — |
gt_markdown_set_font_info_middle(markdown, font_info) | 设置中型文本字体（h3/h4） | — |
gt_markdown_set_font_info_small(markdown, font_info) | 设置小型文本字体（h5/h6/正文） | — |
gt_markdown_get_font_info_large(markdown) | 获取大型文本字体配置 | — |
gt_markdown_get_font_info_middle(markdown) | 获取中型文本字体配置 | — |
gt_markdown_get_font_info_small(markdown) | 获取小型文本字体配置 | — |
gt_markdown_set_font_color(markdown, color) | 设置全局字体颜色 | — |
gt_markdown_set_align_latex_baseline(markdown, align) | LaTeX 公式与文本基线对齐 | false |
gt_font_info_st结构体包含：family（字库 ID）、cjk（CJK 变体）、size（字号）、gray（灰度）等字段。
// 在 screen_home 屏幕控件中创建一个 MarkDown 解析控件
gt_obj_st * markdown_obj = gt_markdown_create(screen_home);
// 设置 MarkDown 解析控件在屏幕中的相对位置为(31, 28)
gt_obj_set_pos_relative(markdown_obj, screen_home, 31, 28);
// 设置 MarkDown 解析控件的大小为(424, 167)
gt_obj_set_size(markdown_obj, 424, 267);
// 设置 MarkDown 解析控件的边框半径为4
gt_obj_set_radius(markdown_obj, 4);
// 设置 MarkDown 解析控件的背景颜色为 0x0097e6
gt_obj_set_bgcolor(markdown_obj, gt_color_hex(0x0097e6));
// 设置 MarkDown 解析控件的文本内容
const char * markdown_obj_text = "## 1 介绍\r\n\r\nGT-HMI Engine"
"的window仿真测试环境, 以及 GT-HMI Designer 的工程测试环境."
"\r\n\r\n## 2 软件架构\r\n\r\n软件架构说明\r\n\r\napp/ -> "
"GT-HMI/gui-hmi-tools/gui-win/app/ 目录架构等同环境;\r\n\r\n"
"gui/ -> 想要测试的gui代码仓库\r\n\r\nmk-gui/ -> 用于构建工程"
"的脚本工具";
gt_markdown_set_text(markdown_obj, markdown_obj_text
, strlen(markdown_obj_text));
// 设置 MarkDown 解析控件的大型文本字体
gt_font_info_st markdown_obj_large = {
.family = _16_dian_zhen_zhong_wen__ji_chu_,
.cjk = 0,
.size = 16,
};
gt_markdown_set_font_info_large(markdown_obj
, &markdown_obj_large);
// 设置 MarkDown 解析控件的标准文本字体
gt_font_info_st markdown_obj_middle = {
.family = _16_dian_zhen_zhong_wen__ji_chu_,
.cjk = 0,
.size = 16,
};
gt_markdown_set_font_info_middle(markdown_obj
, &markdown_obj_middle);
// 设置 MarkDown 解析控件的小型文本字体
gt_font_info_st markdown_obj_small = {
.family = _16_dian_zhen_zhong_wen__ji_chu_,
.cjk = 0,
.size = 16,
};
gt_markdown_set_font_info_small(markdown_obj
, &markdown_obj_small);
Markdown 解析 gt_markdown
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
轻量 Markdown 渲染：## 标题与 - 无序列表自动排版（标题行加粗放大）。set_text 必须在 set_size 之后调用。
渲染内容 set_text
字体色 set_font_color
#2c3e50
底色 gt_obj_set_bgcolor
#ffffff
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
markdown_demo.c
/* markdown —— 摘自手册 7.5 节 */// 创建 MarkDown 解析控件gt_obj_st * markdown_obj = gt_markdown_create(screen_home);// 位置 (31, 28)，尺寸 424 x 264，圆角 4，白底gt_obj_set_pos(markdown_obj, 31, 28);gt_obj_set_size(markdown_obj, 424, 264);gt_obj_set_radius(markdown_obj, 4);gt_obj_set_bgcolor(markdown_obj, gt_color_hex(0xFFFFFF));// 设置 Markdown 源文本（⚠ 必须在 set_size 之后调用，换行为 \r\n）const char * text = "## 标签控件\r\n\r\n文本第二行渲染验证。\r\n\r\n- 按钮开关\r\n- 滑条进度条";gt_markdown_set_text(markdown_obj, text, strlen(text));// 分级字体（h1/h2 大型、h3/h4 中型、h5/h6 与正文小型）gt_font_info_st large = { .family = demo_font, .size = 20 };gt_markdown_set_font_info_large(markdown_obj, &large);// 全局字体颜色gt_markdown_set_font_color(markdown_obj, gt_color_hex(0x2C3E50));7.6 频谱控件
在创建的屏幕控件中添加一个频谱控件并设置频谱控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_spectrum_create(parent) | 创建频谱控件 | — |
gt_spectrum_set_type(obj, type) | 设置频谱类型：见 枚举速查表 gt_spectrum_type_et | CIRCLE |
gt_spectrum_set_color_type(obj, type) | 设置颜色渐变模式：见 枚举速查表 gt_spectrum_color_type_et | RANGE |
gt_spectrum_set_period(obj, period) | 设置动画间隔（ms） | — |
gt_spectrum_set_item_numb(obj, numb, gap) | 设置线段数量和间距 | — |
gt_spectrum_set_item_range(obj, height, steps) | 设置高度和层级数 | — |
gt_spectrum_set_item_range_gap(obj, gap) | 设置层级间隙（仅 STAIR 类型） | 0 |
gt_spectrum_set_item_range_reflect(obj, reflect) | 设置上下反射（仅 STAIR 类型） | false |
gt_spectrum_set_item_range_not_random(obj, not_random) | 关闭随机值，启用手动推送 | false |
gt_spectrum_push_item_range_value(obj, value) | 推送指定值（not_random 模式下） | — |
gt_spectrum_add_gradient_color(obj, start, end, steps) | 添加渐变色段（steps >= 2） | — |
gt_spectrum_clear_gradient_color(obj) | 清空已设渐变色段 | — |
gt_spectrum_set_color_move(obj, enable, dir, gap) | 设置颜色移动：dir=true 左移 | — |
gt_spectrum_play(obj) | 开始动画 | — |
gt_spectrum_stop(obj) | 停止动画 | — |
// 在 screen_home 屏幕控件中创建一个频谱控件
gt_obj_st * spectrum_obj = gt_spectrum_create(screen_home);
// 设置频谱控件在屏幕中的相对位置为(89, 94)
gt_obj_set_pos_relative(spectrum_obj, screen_home, 89, 94);
// 设置频谱控件的大小为(227, 80)
gt_obj_set_size(spectrum_obj, 227, 80);
// 设置频谱控件的背景为 0x000000
gt_obj_set_bgcolor(spectrum_obj, gt_color_hex(0x000000));
// 设置频谱控件的类型为矩形
gt_spectrum_set_type(spectrum_obj, GT_SPECTRUM_TYPE_RECT);
// 设置频谱控件开启颜色渐变模式
gt_spectrum_set_color_type(spectrum_obj
, GT_SPECTRUM_COLOR_TYPE_NUMB);
// 设置频谱控件的动画间隔为600ms
gt_spectrum_set_period(spectrum_obj,600);
// 设置频谱控件的线段数量为10 横向间距为2
gt_spectrum_set_item_numb(spectrum_obj,10,2);
// 设置频谱控件的线段数量为10，高度层级数为4
gt_spectrum_set_item_range(spectrum_obj,10,4);
// 设置频谱控件的值为随机值
gt_spectrum_set_item_range_not_random(spectrum_obj,false);
// 设置频谱控件的颜色不移动，移动方向向右，移动跨度为1
gt_spectrum_set_color_move(spectrum_obj,false,true,1);
// 设置频谱控件的渐变颜色条的颜色值
gt_spectrum_add_gradient_color(spectrum_obj,gt_color_hex(0xd02828)
,gt_color_hex(0x0ea997),2);
gt_spectrum_add_gradient_color(spectrum_obj,gt_color_hex(0x0ea997)
,gt_color_hex(0x259e3d),2);
gt_spectrum_add_gradient_color(spectrum_obj,gt_color_hex(0x259e3d)
,gt_color_hex(0x3787c9),2);
gt_spectrum_add_gradient_color(spectrum_obj,gt_color_hex(0x3787c9)
,gt_color_hex(0x7922b8),2);
gt_spectrum_add_gradient_color(spectrum_obj,gt_color_hex(0x7922b8)
,gt_color_hex(0xd5236a),2);
// 设置频谱控件开始动画
gt_spectrum_play(spectrum_obj);
频谱 gt_spectrum
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
与手册 7.6 节及工程原型 screen_spectrum 一致：双频谱同屏——左圆形（CIRCLE 环形弧条、四段闭环渐变、颜色左移）+ 右阶梯（STAIR 层间隙、不反射、三段渐变、颜色右移），COLOR_TYPE_NUMB 按线段序号渐变，引擎任务驱动随机跳动。
动画 play / stop（双频谱同控）
左侧频谱类型 set_type
动画间隔 set_period（ms）220
右侧阶梯上下反射 set_item_range_reflect
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
spectrum_demo.c
/* spectrum_obj —— 摘自手册 7.6 节 + 工程原型 screen_spectrum（480×320 适配） */// 深色屏底（原型同款）gt_obj_set_bgcolor(screen_home, gt_color_hex(0x10141A));// —— 左：圆形频谱 ——gt_obj_st * circle = gt_spectrum_create(screen_home);gt_obj_set_pos(circle, 25, 50);gt_obj_set_size(circle, 220, 220);gt_obj_show_bg(circle, false); // 不画自身背景gt_spectrum_set_type(circle, GT_SPECTRUM_TYPE_CIRCLE);gt_spectrum_set_period(circle, 220); // 动画间隔 ms（右侧面板可调）gt_spectrum_set_item_numb(circle, 28, 3); // 28 条弧，角间隙 3gt_spectrum_set_item_range(circle, 80, 9); // 环带厚度 80，9 个层级gt_spectrum_set_color_type(circle, GT_SPECTRUM_COLOR_TYPE_NUMB);gt_spectrum_add_gradient_color(circle, gt_color_hex(0x00D4FF), gt_color_hex(0x35E38A), 7);gt_spectrum_add_gradient_color(circle, gt_color_hex(0x35E38A), gt_color_hex(0xFFD166), 7);gt_spectrum_add_gradient_color(circle, gt_color_hex(0xFFD166), gt_color_hex(0xFF5C7A), 7);gt_spectrum_add_gradient_color(circle, gt_color_hex(0xFF5C7A), gt_color_hex(0x00D4FF), 7);gt_spectrum_set_color_move(circle, true, true, 1);// 颜色随动画左移gt_spectrum_play(circle);// —— 右：阶梯频谱 ——gt_obj_st * stair = gt_spectrum_create(screen_home);gt_obj_set_pos(stair, 255, 85);gt_obj_set_size(stair, 190, 150);gt_obj_show_bg(stair, false);gt_spectrum_set_type(stair, GT_SPECTRUM_TYPE_STAIR);gt_spectrum_set_period(stair, 220);gt_spectrum_set_item_numb(stair, 18, 3);gt_spectrum_set_item_range(stair, 150, 12); // 高度 150，12 个层级gt_spectrum_set_item_range_gap(stair, 2); // 层间隙 2（仅 STAIR）gt_spectrum_set_item_range_reflect(stair, false); // 不上下反射（仅 STAIR，右侧面板可切）gt_spectrum_set_color_type(stair, GT_SPECTRUM_COLOR_TYPE_NUMB);gt_spectrum_add_gradient_color(stair, gt_color_hex(0x00D4FF), gt_color_hex(0x35E38A), 6);gt_spectrum_add_gradient_color(stair, gt_color_hex(0x35E38A), gt_color_hex(0xFFD166), 6);gt_spectrum_add_gradient_color(stair, gt_color_hex(0xFFD166), gt_color_hex(0xFF5C7A), 6);gt_spectrum_set_color_move(stair, true, false, 1);// 颜色随动画右移gt_spectrum_play(stair);7.7 频谱线控件
在创建的屏幕控件中添加一个频谱线控件并设置频谱线控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_spectrum_line_create(parent) | 创建频谱线控件 | — |
gt_spectrum_line_add(obj, width, color) | 添加一条线，返回线条索引 | — |
gt_spectrum_line_add_point(obj, line_index, point) | 添加点到指定线条，返回点索引 | — |
gt_spectrum_line_move_copy(obj, count, start, end) | 按模式复制线条，总数 count，渐变色 start→end | — |
gt_spectrum_line_set_period(obj, period) | 设置刷新周期（ms） | — |
gt_spectrum_line_set_gen_next_func(obj, func) | 设置波动函数（默认 gt_triangle_generator_next） | triangle |
gt_spectrum_line_play(obj) | 开始动画 | — |
gt_spectrum_line_stop(obj) | 停止动画 | — |
// 点列表
static gt_sp_point_st _sp1_point[] = {
{.point.x = 0, .point.y = 0, .gen.min_val = -20,
.gen.max_val = 20, .gen.step = 2, .gen.dir = 1, .gen.cur_val = 0},
{.point.x = 20, .point.y = 40, .gen.min_val = -20,
.gen.max_val = 20, .gen.step = 2, .gen.dir = -1, .gen.cur_val = 0},
{.point.x = 60, .point.y = 0, .gen.min_val = -20,
.gen.max_val = 20, .gen.step = 2, .gen.dir = -1, .gen.cur_val = 0},
{.point.x = 150, .point.y = 10, .gen.min_val = 10,
.gen.max_val = 74, .gen.step = 4, .gen.dir = 1, .gen.cur_val = 0},
{.point.x = 220, .point.y = -40, .gen.min_val = -20,
.gen.max_val = 20, .gen.step = 2, .gen.dir = 1, .gen.cur_val = 0},
{.point.x = 260, .point.y = 40, .gen.min_val = -20,
.gen.max_val = 20, .gen.step = 2, .gen.dir = -1, .gen.cur_val = 0},
{.point.x = 280, .point.y = 32, .gen.min_val = -32,
.gen.max_val = 32, .gen.step = 4, .gen.dir = -1, .gen.cur_val = 0},
{.point.x = 300, .point.y = 24, .gen.min_val = -20,
.gen.max_val = 20, .gen.step = 2, .gen.dir = -1, .gen.cur_val = 0},
};
/**
* @brief 设置频谱线的点偏移
*
* @param point 点数据列表
* @param numb 点数量
* @param off_x x轴偏移
* @param off_y y轴偏移
*/
static void _sp1_point_set_offset(gt_sp_point_st* point
, uint16_t numb, int16_t off_x, int16_t off_y)
{
for(uint16_t i = 0; i < numb; ++i) {
point[i].point.x += off_x;
point[i].point.y += off_y;
point[i].gen.min_val += off_y;
point[i].gen.max_val += off_y;
point[i].gen.cur_val = point[i].point.y;
}
}
// 在 screen_home 屏幕控件中创建一个频谱线控件
gt_obj_st * sp_line1 = gt_spectrum_line_create(screen_home);
// 设置频谱线控件的位置为(100, 100)
gt_obj_set_pos(sp_line1, 100, 100);
// 设置频谱线控件的大小为(300, 300)
gt_obj_set_size(sp_line1, 300, 300);
// 添加频谱线的线条，宽度为2，颜色为红色
gt_size_t line_index = gt_spectrum_line_add(sp_line1, 2
, gt_color_red());
// 设置并添加频谱线控件的线条
_sp1_point_set_offset(_sp1_point, 8, sp_line1->area.x
, sp_line1->area.y + (sp_line1->area.h >> 2));
for(uint8_t i = 0; i < 7; i++) {
gt_spectrum_line_add_point(sp_line1, line_index
, _sp1_point[i]);
}
// 基于第一行的内容，按照其移动模式复制其余行
gt_spectrum_line_move_copy(sp_line1, 8, gt_color_red()
, gt_color_yellow());
// 设置关键点波动功能
gt_spectrum_line_set_gen_next_func(sp_line1
, gt_sawtooth_generator_next);
gt_spectrum_line_set_period(sp_line1, 100);
// 设置频谱线控件动画开始
gt_spectrum_line_play(sp_line1);
坐标系约定（实测确认，易踩坑）：
- 每个关键点的实际绘制 Y 取波动函数的当前值
gen.cur_val（即get_gen_next(&gen)的输出），而不是point.y。point.y只决定初始值，播放中线条起伏完全由 gen 驱动。 - 因此
gen.min_val/gen.max_val/gen.cur_val必须与point.y同属屏幕绝对坐标系——上面示例中_sp1_point_set_offset给point.y和 gen 三值同时加off_y正是在维护这个约定。 - 典型误区：gen 填 ±18 这类"围绕 0 的小幅波动"值，整条线的所有点都会落在 y∈[-18,18] 区间——远在控件区域之外，被裁剪后画布完全空白，极易误判为控件不渲染的 bug。正确做法是让波动范围落在控件可视区内（如控件在 (100,100)、高 300，则 gen 范围取 140~180 一带）。
- 波动函数默认
gt_triangle_generator_next（三角波），示例改用gt_sawtooth_generator_next（锯齿波），可通过gt_spectrum_line_set_gen_next_func切换。
频谱线 gt_spectrum_line
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
与手册 7.7 节一致：首线加关键点定义波形，move_copy 按首行模式复制多条渐变色线条，引擎任务驱动波动刷新。
动画 play / stop
刷新周期 set_period（ms）100
波形函数 set_gen_next_type
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
spectrum-line_demo.c
/* sp_line1 —— 摘自手册 7.7 节示例（关键点表节选） */// 在 screen_home 屏幕控件中创建一个频谱线控件gt_obj_st * sp_line1 = gt_spectrum_line_create(screen_home);// 设置频谱线控件的位置为 (40, 130)gt_obj_set_pos(sp_line1, 40, 130);// 设置频谱线控件的大小为 (400, 60)gt_obj_set_size(sp_line1, 400, 60);// 添加首条线条：宽度 2，橙色（返回首线 index）gt_size_t line_index = gt_spectrum_line_add(sp_line1, 2, gt_color_hex(0xe6a23c));// 关键点：绘制 Y 取自发生器值，故 gen.min/max 与 point.y 同为屏幕绝对坐标// （手册 7.7 的 _sp1_point_set_offset 即按 area 偏移同步平移 min/max、cur_val=point.y）static gt_sp_point_st _pts[] = { { .point = { 45, 158 }, .gen = { .min_val = 140, .max_val = 180, .step = 3, .cur_val = 158, .dir = 1 } }, { .point = { 115, 142 }, .gen = { .min_val = 140, .max_val = 180, .step = 3, .cur_val = 142, .dir = -1 } }, { .point = { 190, 172 }, .gen = { .min_val = 140, .max_val = 180, .step = 3, .cur_val = 172, .dir = 1 } }, { .point = { 265, 145 }, .gen = { .min_val = 140, .max_val = 180, .step = 3, .cur_val = 145, .dir = -1 } }, { .point = { 340, 168 }, .gen = { .min_val = 140, .max_val = 180, .step = 3, .cur_val = 168, .dir = 1 } }, { .point = { 432, 155 }, .gen = { .min_val = 140, .max_val = 180, .step = 3, .cur_val = 155, .dir = -1 } },};for (unsigned i = 0; i < 6; i++) gt_spectrum_line_add_point(sp_line1, line_index, _pts[i]);// 按首行移动模式复制 16 条线，渐变色 蓝 → 绿gt_spectrum_line_move_copy(sp_line1, 16, gt_color_hex(0x1ba1fa), gt_color_hex(0x67c23a));// 设置刷新周期为 100ms（右侧面板可调）gt_spectrum_line_set_period(sp_line1, 100);// 开始动画（右侧面板可启停/切波形）gt_spectrum_line_play(sp_line1);7.8 弹窗提示词控件
设置弹窗提示词控件属性，并显示。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_toast(param) | 显示弹窗提示词 | — |
gt_toast_close() | 关闭弹窗 | — |
gt_toast_is_showing() | 是否正在显示 | — |
gt_toast_reset(toast) | 重置全局设置 | — |
gt_toast_global_set_font_size(size) | 全局设置字体大小（pt） | — |
gt_toast_global_set_font_family(family) | 全局设置字体系列 | — |
gt_toast_global_set_font_align(align) | 全局设置对齐方式 | — |
gt_toast_param_st结构体字段：
message— 提示文本bg_color— 背景颜色font_color— 字体颜色duration— 显示时长（ms），0=永久显示，默认 2000msposition— 位置：GT_TOAST_POS_MIDDLE/TOP/BOTTOM，默认 MIDDLEopa— 透明度
gt_toast_param_st toast = {
// 设置弹窗提示词背景颜色为红色
.bg_color = gt_color_hex(GT_COLOR_RED),
// 设置弹窗提示词字体颜色为白色
.font_color = gt_color_white(),
// 设置弹窗提示词显示时间为5000ms
.duration = 5000,
// 设置弹窗提示词文本为 "hello word"
.message = "hello word",
// 设置弹窗提示词显示位置为中间
.position = GT_TOAST_POS_TOP,
};
// 显示弹窗提示词
gt_toast(&toast);
弹窗提示词 gt_toast
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
Toast 以全局函数调用弹出（非控件创建），消息、颜色、时长、位置由 gt_toast_param_st 结构体一次传入，超时自动关闭。
文本（gt_toast）
显示位置 position
关闭 gt_toast_close
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
toast_demo.c
/* toast —— 摘自手册 7.8 节 */// 定义弹窗提示词参数结构体gt_toast_param_st toast = { // 设置弹窗提示词背景颜色为蓝色 .bg_color = gt_color_hex(0x3580BB), // 设置弹窗提示词字体颜色为白色 .font_color = gt_color_white(), // 设置弹窗提示词显示时间为 5000ms .duration = 5000, // 设置弹窗提示词文本 .message = "提示消息", // 设置弹窗提示词显示位置为顶部 .position = GT_TOAST_POS_TOP,};// 显示弹窗提示词gt_toast(&toast);// 立即关闭// gt_toast_close();7.9 歌词控件
在创建的屏幕控件中添加一个歌词控件并设置歌词控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_lrc_create(parent) | 创建歌词控件 | — |
gt_lrc_add_text(obj, time, "text") | 添加歌词行（time 单位 ms） | — |
gt_lrc_clear_all_text(obj) | 清除所有歌词 | — |
gt_lrc_set_select_index(obj, index) | 设置当前选中歌词索引 | — |
gt_lrc_set_select_color(obj, color) | 设置选中歌词颜色 | — |
gt_lrc_set_font_color(obj, color) | 设置字体颜色 | — |
gt_lrc_set_font_size(obj, size) | 设置字体大小（pt） | — |
gt_lrc_set_font_align(obj, align) | 对齐方式：见 枚举速查表 gt_align_et | — |
gt_lrc_set_font_family(obj, family) | 设置字体系列 | — |
gt_lrc_set_font_cjk(obj, cjk) | 设置 CJK 字体变体 | — |
gt_lrc_set_font_thick_en(obj, thick) | 设置英文字体粗细 | — |
gt_lrc_set_font_thick_cn(obj, thick) | 设置中文字体粗细 | — |
gt_lrc_set_font_gray(obj, gray) | 设置字体灰度：1 / 2 / 4 | — |
gt_lrc_set_font_encoding(obj, encoding) | 设置文本编码：见 枚举速查表 gt_encoding_et | — |
gt_lrc_set_space(obj, space_x, space_y) | 设置文本间距 | — |
gt_lrc_set_border_color(obj, color) | 设置边框颜色 | — |
gt_lrc_set_border_width(obj, width) | 设置边框宽度 | — |
gt_lrc_set_fixed_line(obj, line) | 设置固定行 | — |
gt_lrc_start(obj) | 启动内部定时器 | — |
gt_lrc_paused(obj) | 暂停内部定时器 | — |
gt_lrc_resume(obj) | 恢复内部定时器 | — |
gt_lrc_correction_time(obj, time) | 校正时间（需先 start） | — |
gt_lrc_set_current_time(obj, time) | 直接设置当前时间（无需 start） | — |
// 在 screen_home 屏幕控件中创建一个歌词控件
gt_obj_st * lrc_obj = gt_lrc_create(screen_home);
// 设置歌词控件的位置为(150, 70)
gt_obj_set_pos(lrc_obj, 150, 70);
// 设置歌词控件的大小为(500, 120)
gt_obj_set_size(lrc_obj, 500, 120);
// 设置歌词控件的字体颜色为 0x199FF7
gt_lrc_set_font_color(lrc_obj, gt_color_hex(0x199FF7));
// 设置歌词控件的字体为 _16_dian_zhen_zhong_wen__ji_chu_
gt_lrc_set_font_family(lrc_obj
, _16_dian_zhen_zhong_wen__ji_chu_);
gt_lrc_set_font_cjk(lrc_obj, 0);
// 设置歌词控件的字体对齐方式为居中对齐
gt_lrc_set_font_align(lrc_obj, GT_ALIGN_CENTER_MID);
// 设置歌词控件当前歌词的颜色为 0xFF0000
gt_lrc_set_select_color(lrc_obj, gt_color_hex(0xFF0000));
// 添加歌词到歌词控件（time 单位：ms）
gt_lrc_add_text(lrc_obj, 7000
, "Take me to your heart take me to your soul");
gt_lrc_add_text(lrc_obj, 4000
, "Give me your hand and hold me");
gt_lrc_add_text(lrc_obj, 6000
, "Show me what love is - be my guiding star");
gt_lrc_add_text(lrc_obj, 5000
, "It's easy, take me to your heart");
// 设置当前选中的歌词下标
gt_lrc_set_select_index(lrc_obj, 2);
歌词 gt_lrc
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
歌词滚动控件：每行绑定时间戳（ms），start 启动内部定时器后随播放进度自动切换高亮行；选中行与普通行分色显示。
选中行 set_select_index0
歌词颜色 set_font_color
#666666
选中行颜色 set_select_color
#0097e6
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
lrc_demo.c
/* lrc —— 摘自手册 7.9 节 */// 创建歌词控件gt_obj_st * lrc_obj = gt_lrc_create(screen_home);// 位置 (40, 90)，尺寸 400 x 160gt_obj_set_pos(lrc_obj, 40, 90);gt_obj_set_size(lrc_obj, 400, 160);// 普通行灰色、当前行蓝色gt_lrc_set_font_color(lrc_obj, gt_color_hex(0x666666));gt_lrc_set_select_color(lrc_obj, gt_color_hex(0x0097E6));// 添加歌词行（第二个参数为该行时间戳，单位 ms）gt_lrc_add_text(lrc_obj, 7000, "高通字体引擎");gt_lrc_add_text(lrc_obj, 4000, "中英混排演示");gt_lrc_add_text(lrc_obj, 6000, "渲染验证");// 设置当前选中行下标并启动内部定时器（随时间自动切换高亮行）gt_lrc_set_select_index(lrc_obj, 0);gt_lrc_start(lrc_obj);// 暂停 / 恢复 / 校正时间// gt_lrc_paused(lrc_obj);// gt_lrc_resume(lrc_obj);// gt_lrc_correction_time(lrc_obj, 1000);7.10 艺术字控件
在创建的屏幕控件中添加一个艺术字控件并设置艺术字控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_wordart_create(parent) | 创建艺术字控件 | — |
gt_wordart_items_init(wordart, total) | 初始化最大项目数 | — |
gt_wordart_set_text(wordart, "fmt", ...) | 设置文本（按字符匹配图片） | — |
gt_wordart_get_text(wordart) | 获取文本 | — |
gt_wordart_add_item(wordart, coding, "src") | 添加字符编码→图片映射 | — |
gt_wordart_remove_all_items(wordart) | 清除所有映射 | — |
gt_wordart_set_space(wordart, space_x, space_y) | 设置字间距 | 0, 0 |
gt_wordart_set_number(wordart, number, int_len, dec_len, is_float) | 格式化显示数字 | — |
// 在 screen_home 屏幕控件中创建一个艺术字控件
gt_obj_st * wordart_obj = gt_wordart_create(screen_home);
// 设置艺术字控件在屏幕中的相对位置为(85, 81)
gt_obj_set_pos_relative(wordart_obj, screen_home, 85, 81);
// 初始化艺术字控件的最大项数为2
gt_wordart_items_init(wordart_obj, 2);
// 设置艺术字控件的文本为"你好"
gt_wordart_set_text(wordart_obj, "你好");
// 添加艺术字控件文本对应的图片
gt_wordart_add_item(wordart_obj, 0x4F60, ".:img__50.bmp");
gt_wordart_add_item(wordart_obj, 0x597D, ".:img__51.bmp");
艺术字 gt_wordart
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
艺术字控件不经过字体渲染：每个字符编码绑定一张彩色位图，set_text 按字符逐图拼接。真机经资源包 add_item(".:gao.bmp") 绑定；官网演示注入渐变像素图（"高/通/字"三张 40×40 字模图）。
文本 set_text（按字符匹配图片）
字间距 set_space8
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
wordart_demo.c
/* wordart —— 摘自手册 7.10 节 */// 创建艺术字控件gt_obj_st * wordart1 = gt_wordart_create(screen_home);// 位置 (100, 130)，尺寸 280 x 60gt_obj_set_pos(wordart1, 100, 130);gt_obj_set_size(wordart1, 280, 60);// 初始化最大字符映射数gt_wordart_items_init(wordart1, 4);// 绑定字符编码 → 图片（'高'=0x9AD8，资源包路径）gt_wordart_add_item(wordart1, 0x9AD8, ".:gao.bmp");gt_wordart_add_item(wordart1, 0x901A, ".:tong.bmp");gt_wordart_add_item(wordart1, 0x5B57, ".:zi.bmp");// 设置字符间距gt_wordart_set_space(wordart1, 8, 0);// 设置文本：按字符逐图拼接显示gt_wordart_set_text(wordart1, "高通字");7.11 十字交叉布局控件
在创建的屏幕控件中添加一个十字交叉布局控件并设置十字交叉布局控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_cross_layout_create(parent) | 创建十字交叉布局控件 | — |
gt_cross_layout_set_gap(layout, hor_gap, ver_gap) | 设置水平/垂直间隙 | — |
gt_cross_layout_set_hor_roll_mode(layout, mode) | 水平滚动模式：见 枚举速查表 gt_cross_roll_mode_et | DEFAULT |
gt_cross_layout_set_ver_roll_mode(layout, mode) | 垂直滚动模式：见 枚举速查表 gt_cross_roll_mode_et | DEFAULT |
gt_cross_layout_set_hor_obj_area(layout, x, y, w, h) | 设置水平布局区域 | — |
gt_cross_layout_set_ver_obj_area(layout, x, y, w, h) | 设置垂直布局区域 | — |
gt_cross_layout_set_hor_offset(layout, offset) | 设置水平偏移 | — |
gt_cross_layout_set_ver_offset(layout, offset) | 设置垂直偏移 | — |
gt_cross_layout_get_hor_obj(layout) | 获取水平容器对象 | — |
gt_cross_layout_get_ver_obj(layout) | 获取垂直容器对象 | — |
gt_cross_layout_hor_add_item(layout, obj, ver_index) | 添加控件到横向（指定垂直页索引） | — |
gt_cross_layout_ver_add_item(layout, obj) | 添加控件到纵向 | — |
gt_cross_layout_set_hor_index(layout, index) | 设置当前水平页索引 | — |
gt_cross_layout_set_ver_index(layout, index) | 设置当前垂直页索引 | — |
gt_cross_layout_set_touch_mode(layout, mode) | 设置触摸模式：见 枚举速查表 gt_cross_touch_mode_et | INDEPENDENT |
// 在 screen_home 屏幕控件中创建一个十字交叉布局控件
gt_obj_st * cl_obj = gt_cross_layout_create(screen_home);
// 设置十字交叉布局控件的位置为(0, 10)
gt_obj_set_pos(cl_obj, 0, 10);
// 设置十字交叉布局控件的大小为(320, 240)
gt_obj_set_size(cl_obj, 320, 240);
// 设置十字交叉布局控件的间隙x方向20,y方向30
gt_cross_layout_set_gap(cl_obj, 20, 30);
// 设置十字交叉布局控件纵向布局偏移为60
gt_cross_layout_set_ver_offset(cl_obj, 60);
// 设置十字交叉布局控件纵向滚动模式为循环滚动
gt_cross_layout_set_ver_roll_mode(cl_obj, GT_CROSS_ROLL_LOOP);
// 设置十字交叉布局控件横向滚动模式为循环滚动
gt_cross_layout_set_hor_roll_mode(cl_obj, GT_CROSS_ROLL_LOOP);
// 设置横向布局的位置为(60, 20) 大小为(260, 144)
gt_cross_layout_set_hor_obj_area(cl_obj, 60, 20, 260, 144);
// 循环创建横向布局的控件对象
for(int i = 0; i < 10; i++)
{
hor_obj[i] = gt_obj_create(gt_cross_layout_get_hor_obj(cl_obj));
gt_obj_set_fixed(hor_obj[i], true);
gt_obj_set_pos(hor_obj[i], 70 + 92 * i, 47);
gt_obj_set_size(hor_obj[i], 72, 72);
hor[i] = gt_img_create(hor_obj[i]);
gt_obj_set_pos(hor[i], 70 + 92 * i, 47);
}
// 设置横向布局控件的图片路径
gt_img_set_src(hor[0], ".:img__1010_countdown.png");
gt_img_set_src(hor[1], ".:img__1020_ai.png");
gt_img_set_src(hor[2], ".:img__1030_alarm_clock.png");
gt_img_set_src(hor[3], ".:img__1040_weather.png");
gt_img_set_src(hor[4], ".:img__1050_set.png");
gt_img_set_src(hor[5], ".:img__1060_stopwatch.png");
gt_img_set_src(hor[6], ".:img__1120_ai_role.png");
gt_img_set_src(hor[7], ".:img__1130_user_settings.png");
gt_img_set_src(hor[8], ".:img__1141_binding.png");
gt_img_set_src(hor[9], ".:img__1149_sync_textbook.png");
// 循环创建纵向布局的控件对象
gt_cross_layout_set_ver_obj_area(cl_obj, 00, 20, 50, 144);
for(int i = 0; i < 4; i++)
{
ver[i] = gt_img_create(gt_cross_layout_get_ver_obj(cl_obj));
gt_obj_set_visible(ver[i], GT_INVISIBLE);
}
// 设置纵向布局控件的图片路径
gt_img_set_src(ver[0], ".:img__hmi_03_ai.png");
gt_img_set_src(ver[1], ".:img__hmi_03_common.png");
gt_img_set_src(ver[2], ".:img__hmi_04_setting.png");
gt_img_set_src(ver[3], ".:img__hmi_05_study.png");
// 将纵向布局的控件添加到纵向布局
gt_cross_layout_ver_add_item(cl_obj, ver[0]);
gt_cross_layout_ver_add_item(cl_obj, ver[1]);
gt_cross_layout_ver_add_item(cl_obj, ver[2]);
gt_cross_layout_ver_add_item(cl_obj, ver[3]);
// 将横向布局的控件添加到横向布局
gt_cross_layout_hor_add_item(cl_obj, hor_obj[0], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[1], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[2], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[3], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[4], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[5], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[6], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[7], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[8], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[9], 0);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[5], 1);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[6], 2);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[7], 2);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[8], 2);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[9], 3);
gt_cross_layout_hor_add_item(cl_obj, hor_obj[0], 3);
图2-37 十字交叉布局控件效果
7.12 公式控件
在创建的屏幕控件中添加一个公式控件，用于渲染数学公式（LaTeX 语法）。支持 printf 格式化文本、多级字体配置和首行偏移。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_formula_create(parent) | 创建公式控件 | — |
gt_formula_set_text(obj, "fmt", ...) | 设置公式文本（printf 格式） | — |
gt_formula_set_text_by_len(obj, "text", len) | 按长度设置公式文本 | — |
gt_formula_set_font_color(obj, color) | 设置字体颜色 | — |
gt_formula_set_max_width(obj, max_width) | 设置最大宽度，0=自动计算 | 0 |
gt_formula_set_font_config(obj, cfg) | 配置各级 LaTeX 字体和字号 | — |
gt_formula_set_first_line_offset(obj, off_x, off_y) | 设置首行 X/Y 偏移 | — |
/** formula1 */
// 在 screen_home 屏幕控件中创建一个公式控件
gt_obj_st * formula1 = gt_formula_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(formula1, 50, 100);
// 设置公式内容（LaTeX 语法）
gt_formula_set_text(formula1, "E = mc^2");
// 设置字体颜色
gt_formula_set_font_color(formula1, gt_color_hex(0x000000));
注：公式控件当前端到端尚未可用——上位机（Designer 仿真）未实现，下位机固件与配套公式字库仍在开发中（本页在线演示的 wasm 构建同样无
gt_formula_*导出）。本章 API 供工程预留参考，正式可用时间以引擎组发布为准。