🎮 在线体验:本章控件的渲染效果可在 控件在线演示页 实时交互——GT-HMI Engine 以 WebAssembly 在浏览器内渲染,调整右侧参数即可实时查看控件效果,与真机渲染一致。
4.1 条形码控件
在创建的屏幕控件中添加一个条形码控件并设置控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_barcode_create(parent) | 创建条形码控件 | — |
gt_barcode_set_type(barcode, family) | 设置条码类型(由 Designer 导出,见 barcode_type_te) | GT_FAMILY_BARCODE_TYPE_EAN_13 |
gt_barcode_set_code_text(barcode, "code") | 设置条码编码内容 | "1234567890128" |
gt_barcode_set_mode_w(barcode, value) | 设置条码模块宽度(像素) | 2 |
gt_barcode_set_mode_h(barcode, value) | 设置条码模块高度(像素) | 64 |
gt_barcode_set_hri_type(barcode, family) | 设置条码底部 HRI 字幕类型 | GT_FAMILY_BARCODE_HRI_TYPE_DOWN |
gt_barcode_set_upc_e_sys_code(barcode, value) | 设置 UPC-E 系统码位 | 0 |
/** barcode1 */
// 在 screen_home 屏幕控件中创建一个条形码控件
barcode1 = gt_barcode_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(barcode1, 300, 100);
// 设置控件尺寸
gt_obj_set_size(barcode1, 138, 80);
// 设置条形码类型为 EAN-13
gt_barcode_set_type(barcode1, GT_FAMILY_BARCODE_TYPE_EAN_13);
// 设置条形码模块宽度为 2 个像素
gt_barcode_set_mode_w(barcode1, 2);
// 设置条形码模块高度为 64 个像素
gt_barcode_set_mode_h(barcode1, 64);
// 设置条形码内容
gt_barcode_set_code_text(barcode1, "1234567890128");
运行后的条形码控件效果见下方在线演示(可直接交互):
EAN-13 条形码,模块宽度/高度(黑白条粗细与条高)实时可调。引擎按条码自然尺寸重设控件区域并左上锚定,模块参数变化后演示会自动重新居中。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* barcode1 —— 摘自手册 4.1 节示例 */// 在 screen_home 屏幕控件中创建一个条形码控件barcode1 = gt_barcode_create(screen_home);// 设置控件坐标(引擎绘制时把控件区域重设为条码自然尺寸并左上锚定,// 模块宽/高变化后需重新 set_pos 居中——右侧面板调参时演示自动处理)gt_obj_set_pos(barcode1, 143, 128);// 设置条形码类型为 EAN-13(默认)gt_barcode_set_type(barcode1, GT_FAMILY_BARCODE_TYPE_EAN_13);// 设置条形码模块宽度为 2 个像素(右侧面板可调)gt_barcode_set_mode_w(barcode1, 2);// 设置条形码模块高度为 64 个像素(右侧面板可调)gt_barcode_set_mode_h(barcode1, 64);// 设置条形码内容gt_barcode_set_code_text(barcode1, "1234567890128");4.2 二维码控件
在创建的屏幕控件中添加一个二维码控件并设置控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_qrcode_create(parent) | 创建二维码控件 | — |
gt_qrcode_set_version(qr_code, version) | 设置二维码版本:GT_FAMILY_QRCODE_VERSION_3 ~ 17 | GT_FAMILY_QRCODE_VERSION_10 |
gt_qrcode_set_str(qr_code, "str") | 设置二维码内容 | "https://www.hmi.gaotongfont.cn/" |
gt_qrcode_set_background(qr_code, color) | 设置背景颜色 | gt_color_white() |
gt_qrcode_set_forecolor(qr_code, color) | 设置前景颜色 | gt_color_black() |
/** qrcode1 */
// 在 screen_home 屏幕控件中创建一个二维码控件
qrcode1 = gt_qrcode_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(qrcode1, 468, 356);
// 设置控件尺寸
gt_obj_set_size(qrcode1, 37, 37);
// 设置二维码版本
gt_qrcode_set_version(qrcode1, GT_FAMILY_QRCODE_VERSION_8);
// 设置二维码背景色
gt_qrcode_set_background(qrcode1, gt_color_hex(0xFFFFFF));
// 设置二维码前景色
gt_qrcode_set_forecolor(qrcode1, gt_color_hex(0x000000));
// 设置二维码内容
gt_qrcode_set_str(qrcode1, "https://www.hmi.gaotongfont.cn/");
运行后的二维码控件效果见下方在线演示(可直接交互):
编码引擎实际使用的二维码控件(gt_qr_ext),内容为官网地址,模块大小与前景色实时可调。码图尺寸随内容/模块自适应(区域只增不减、码在区域内居中),属性变化后演示自动重新居中。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* qrcode1 —— 手册 4.2 节示例(编码引擎实际控件为 gt_qr_ext) */// 在屏幕控件中创建一个二维码控件qrcode1 = gt_qr_ext_create(screen_home);// 设置控件坐标(码图尺寸随内容/模块大小自适应,内容变化后需重新 set_pos 居中——// 右侧面板调参时演示自动处理)gt_obj_set_pos(qrcode1, 172, 92);// 设置二维码内容(官网地址)gt_qr_ext_set_text_by_len(qrcode1, "https://www.hmi.gaotongfont.cn/", 29);// 设置二维码码点颜色为黑色(右侧面板可调)gt_qr_ext_set_module_color(qrcode1, gt_color_hex(0x000000));// 设置二维码码点模块大小为 4 像素(右侧面板可调)gt_qr_ext_set_module_size(qrcode1, 4);// 设置二维码四周留白为 2 像素(注:wasm 构建实际绘制自适应控件区域,留白无视觉差异)gt_qr_ext_set_margin(qrcode1, 2);4.3 滑窗控件
在创建的屏幕控件中添加一个滑窗控件并设置控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_view_pager_create(parent) | 创建滑窗控件 | — |
gt_view_pager_set_fragment_count(obj, count) | 设置总页数 | — |
gt_view_pager_add_fragment(obj) | 添加一个空白页,返回页索引 | — |
gt_view_pager_fragment_add_widget(vp, idx, child) | 将子控件添加到指定页(idx 从 0 开始) | — |
gt_view_pager_scroll_to_fragment(obj, index) | 滚动到指定页 | — |
gt_view_pager_set_scroll_effect(obj, effect) | 滚动效果:DEFAULT(默认)/ STATIC / NO_FINGER_FOLLOW | DEFAULT |
gt_view_pager_get_cur_page(obj) | 获取当前页索引 | — |
gt_view_pager_get_widget_belong_fragment(vp, child) | 获取子控件所属页索引,-1=未找到 | — |
gt_view_pager_set_glass(obj, enabled) | 背景玻璃效果 | false |
gt_view_pager_set_glass_color(obj, color) | 玻璃效果颜色 | — |
gt_view_pager_set_window_size(obj, w, h) | 设置可视窗口尺寸(创建后、添加页之前调用) | 与父容器一致 |
gt_view_pager_set_direction(obj, dir) | 滚动方向:GT_VIEW_PAGER_DIR_HORIZONTAL(默认) / VERTICAL | HORIZONTAL |
gt_view_pager_set_tip_bar_pos(obj, pos) | 指示条位置:DEFAULT / OPPOSITE | DEFAULT |
// 在 screen_home 屏幕控件中创建一个滑窗控件
viewPager1 = gt_view_pager_create(screen_home);
// 设置滑窗控件的位置 (0, 0)
gt_obj_set_pos(viewPager1, 0, 0);
// 设置滑窗控件的尺寸(宽度 480,高度 320 默认为屏幕尺寸)
gt_obj_set_size(viewPager1, 480, 320);
// 设置滑窗控件的透明度
gt_obj_set_opa(viewPager1, GT_OPA_0);
// 设置滑窗控件的页数
gt_view_pager_set_fragment_count(viewPager1, 2);
// 设置滑窗控件背景的玻璃效果
gt_view_pager_set_glass(viewPager1, 0);
与之对应的在其他控件设置所属的滑窗,以添加控件到滑窗内部。
// 为滑窗控件的第一页(从 0 开始)添加图片控件 1
gt_view_pager_fragment_add_widget(viewPager1, 0, img1);
// 为滑窗控件的第二页添加图片控件 4
gt_view_pager_fragment_add_widget(viewPager1, 1, img4);
运行后的滑窗结果见下方在线演示(可直接交互):
滑窗控件提供多页横滑容器(每页可放任意子控件),底部带页指示条。面板可切换当前页。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* view_pager1 —— 摘自手册 4.3 节 */// 在 screen_home 屏幕控件中创建一个滑窗控件view_pager1 = gt_view_pager_create(screen_home);// 设置滑窗控件的位置为(60, 50)gt_obj_set_pos(view_pager1, 60, 50);// 设置滑窗控件的尺寸为(宽度 360 高度 220)gt_obj_set_size(view_pager1, 360, 220);// 设置可视窗口尺寸(创建后、添加页之前调用)gt_view_pager_set_window_size(view_pager1, 360, 220);// 添加三页,并把标签放进每一页uint8_t idx = gt_view_pager_add_fragment(view_pager1);label1 = gt_label_create(view_pager1);gt_label_set_text(label1, "第一页");gt_view_pager_fragment_add_widget(view_pager1, idx, label1);// 滚动到指定页(索引从 0 开始)gt_view_pager_scroll_to_fragment(view_pager1, 1);4.4 直线控件
在创建的屏幕控件中添加一个直线控件并设置控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_line_create(parent) | 创建直线控件 | — |
gt_line_set_color(line, color) | 设置线条颜色 | — |
gt_line_set_start_point(line, xs, ys) | 设置起点坐标(屏幕绝对坐标) | — |
gt_line_set_end_point(line, xe, ye) | 设置终点坐标(屏幕绝对坐标) | — |
gt_line_set_hor_line(line, length) | 设为水平线(长度=length),以 gt_obj_set_pos() 设定的控件位置为起点 | — |
gt_line_set_ver_line(line, length) | 设为垂直线(长度=length),以 gt_obj_set_pos() 设定的控件位置为起点 | — |
gt_line_set_line_width(line, line_width) | 设置线宽(像素) | — |
gt_line_set_brush_type(line, type) | 端点样式:GT_BRUSH_TYPE_ROUND(圆形)或 GT_BRUSH_TYPE_RECT(方形) | ROUND |
gt_line_get_start_point(line, ret_p) | 获取起点坐标 | — |
gt_line_get_end_point(line, ret_p) | 获取终点坐标 | — |
坐标语义:
gt_line_set_start_point()/gt_line_set_end_point()的坐标为屏幕绝对坐标,直接对应线段在屏幕上的绘制位置,不随gt_obj_set_pos()设定的控件位置叠加偏移(设置端点后,控件区域会自动调整为包住整条线段)。若只需水平线或垂直线,用gt_line_set_hor_line()/gt_line_set_ver_line()更方便——它们以gt_obj_set_pos()设定的控件位置为起点、按给定长度生成端点。
/** line1 */
// 在 screen_home 屏幕控件中创建一个直线控件
line1 = gt_line_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(line1, 50, 50);
// 设置水平线长度为 200 像素
gt_line_set_hor_line(line1, 200);
// 设置线宽为 3 像素
gt_line_set_line_width(line1, 3);
// 设置线条颜色为红色
gt_line_set_color(line1, gt_color_hex(0xFF0000));
// 设置端点样式为圆形
gt_line_set_brush_type(line1, GT_BRUSH_TYPE_ROUND);
水平线 / 垂直线 / 对角线三种形态,线宽、颜色、端点样式实时可调。端点坐标为屏幕绝对坐标(引擎按端点反算控件区域),三种形态均居中于画布。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* line1 —— 摘自手册 4.4 节示例(端点坐标按引擎实际语义标注) */// 在 screen_home 屏幕控件中创建一个直线控件line1 = gt_line_create(screen_home);// 设置起点坐标——屏幕绝对坐标(引擎按端点反算控件区域;// 注:手册本节"相对控件左上角"的说明与引擎实际行为不符,已实测确认)gt_line_set_start_point(line1, 150, 230);// 设置终点坐标(屏幕绝对坐标,右侧面板可切换水平/垂直/对角三种形态)gt_line_set_end_point(line1, 330, 90);// 设置线宽为 4 像素(右侧面板可调)gt_line_set_line_width(line1, 4);// 设置线条颜色为红色(右侧面板可调)gt_line_set_color(line1, gt_color_hex(0xFF0000));// 设置端点样式为圆形(右侧面板可切换方形)gt_line_set_brush_type(line1, GT_BRUSH_TYPE_ROUND);4.5 表格控件
表格控件支持多行多列表格显示。需先添加表头(确定列数),再添加内容,最后调用 gt_table_refresh()。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_table_create(parent) | 创建表格控件 | — |
gt_table_add_header_text_by_len(table, "text", len, align) | 添加表头单元格(确定列数)。align 推荐 GT_ALIGN_LEFT_MID / CENTER_MID / RIGHT_MID | — |
gt_table_add_content_text_by_len(table, "text", len) | 添加内容单元格(自动换行填充,逐列添加) | — |
gt_table_refresh(table) | 必须调用。添加完表头和内容后计算每列的最大宽高 | — |
gt_table_set_font_color(table, color) | 设置字体颜色 | — |
gt_table_set_font_size(table, size) | 设置字体大小(pt) | — |
gt_table_set_font_gray(table, gray) | 设置字体灰度:1 / 2 / 4 | — |
gt_table_set_font_scale_size(table, scale_size) | 软件缩放目标尺寸(0=不缩放) | 0 |
gt_table_set_font_family(table, family) | 设置字体系列 | — |
gt_table_set_font_cjk(table, cjk) | 设置 CJK 字体变体 | — |
gt_table_set_font_thick_en(table, thick) | 设置英文字体粗细 | — |
gt_table_set_font_thick_cn(table, thick) | 设置中文字体粗细 | — |
gt_table_set_font_encoding(table, encoding) | 设置文本编码:见 枚举速查表 gt_encoding_et | — |
gt_table_set_font_style(table, font_style) | 设置字体风格:见 枚举速查表 gt_font_style_et | NORMAL |
gt_table_set_header_bold(table, is_bold) | 表头加粗 | false |
gt_table_set_font_info(table, font_info) | 批量设置字体信息(gt_font_info_st 结构体) | — |
/** table1 */
// 在 screen_home 屏幕控件中创建一个表格控件
table1 = gt_table_create(screen_home);
// 设置控件坐标和尺寸
gt_obj_set_pos(table1, 10, 10);
gt_obj_set_size(table1, 460, 300);
// 设置字体大小
gt_table_set_font_size(table1, 16);
// 表头加粗
gt_table_set_header_bold(table1, true);
// 添加表头(3 列)
gt_table_add_header_text_by_len(table1, "序号", strlen("序号"), GT_ALIGN_CENTER_MID);
gt_table_add_header_text_by_len(table1, "名称", strlen("名称"), GT_ALIGN_LEFT_MID);
gt_table_add_header_text_by_len(table1, "数值", strlen("数值"), GT_ALIGN_RIGHT_MID);
// 添加内容
gt_table_add_content_text_by_len(table1, "1", strlen("1"));
gt_table_add_content_text_by_len(table1, "温度", strlen("温度"));
gt_table_add_content_text_by_len(table1, "25.6°C", strlen("25.6°C"));
gt_table_add_content_text_by_len(table1, "2", strlen("2"));
gt_table_add_content_text_by_len(table1, "湿度", strlen("湿度"));
gt_table_add_content_text_by_len(table1, "68%", strlen("68%"));
// 必须调用 refresh 使表格生效
gt_table_refresh(table1);
运行后的表格控件效果见下方在线演示(可直接交互):
在线交互演示见本页控件演示区"表格 gt_table"卡片(表头对齐 / 追加内容可实时调整,无需重新编译)。
表格控件按"表头定列数 + 内容逐格填充"的方式构建,添加完必须调用 gt_table_refresh 计算行列尺寸。面板可切表头加粗与字色。
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
/* table1 —— 摘自手册 4.5 节 */// 在 screen_home 屏幕控件中创建一个表格控件table1 = gt_table_create(screen_home);// 设置表格控件的位置为(40, 60)gt_obj_set_pos(table1, 40, 60);// 设置表格控件的尺寸为(宽度 400 高度 200)gt_obj_set_size(table1, 400, 200);// 设置字体大小为 16ptgt_table_set_font_size(table1, 16);// 添加表头单元格(确定列数),align 为左中对齐gt_table_add_header_text_by_len(table1, "状态", 6, GT_ALIGN_LEFT_MID);gt_table_add_header_text_by_len(table1, "大小", 6, GT_ALIGN_LEFT_MID);gt_table_add_header_text_by_len(table1, "默认", 6, GT_ALIGN_LEFT_MID);// 添加内容单元格(逐行逐列填充)gt_table_add_content_text_by_len(table1, "启停", 6);gt_table_add_content_text_by_len(table1, "大小", 6);// 【必须】添加完后刷新,计算每列的最大宽高gt_table_refresh(table1);// 表头加粗gt_table_set_header_bold(table1, true);
