高通字库
版本 V2.0 · 更新于 2026-05-25

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);

  运行后的矩形控件效果如下图所示:

图2-20 矩形控件效果

图2-20 矩形控件效果

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"按钮,显示对话框控件效果如下图所示:

图2-21 对话框控件效果

图2-21 对话框控件效果

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 控件效果如下图所示:

图2-22 GIF控件效果

图2-22 GIF控件效果

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);

  运行后显示状态栏控件效果如下图所示:

图2-23 状态栏控件效果

图2-23 状态栏控件效果

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)自适应坐标范围
gt_graphs_set_show_ruler(obj, enabled)显示坐标标尺
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_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);

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

图2-24 图表控件效果

图2-24 图表控件效果

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 交叉轴对齐方式示意图