2 基础控件 | GT-HMI Engine 用户手册 | 高通字库

2. 基础控件

什么是控件？控件又称组件或者部件，指用户看到的所有可视化界面以及界面中的元素，例如按钮、标签、文本框等。为方便用户开发，高通 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_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;
}

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_HEADER`	`gt_img_set_by_file_header(img, fh)`	通过文件头信息加载图片
`GT_USE_DIRECT_ADDR`	`gt_img_set_by_direct_addr(img, addr)`	通过直接地址加载图片
`GT_USE_DIRECT_ADDR_CUSTOM_SIZE`	`gt_img_set_by_custom_size_addr(img, dac)`	通过自定义尺寸直接地址加载
`GT_USE_IMG_TRANSFORM`	`gt_img_set_angle(img, angle)`	旋转角度（0~3599，0.1度单位）
`GT_USE_IMG_TRANSFORM`	`gt_img_set_zoom(img, zoom)`	缩放系数（256=1.0x）
`GT_USE_IMG_TRANSFORM`	`gt_img_set_pivot(img, x, y)`	旋转/缩放中心点

/* 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");

运行后的图片控件效果如下图所示：

图2-1 图片控件效果

2.3 标签控件

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

API 参考：

函数	说明	默认值
`gt_label_create(parent)`	创建标签控件	—
`gt_label_set_text(label, "fmt", ...)`	设置标签文本（printf 格式）	—
`gt_label_set_text_by_len(label, "text", len)`	按长度设置文本	—
`char * gt_label_get_text(label)`	获取标签文本	—
`gt_label_set_font_color(label, color)`	设置字体颜色	—
`gt_label_set_font_size(label, size)`	设置字体大小（pt）	—
`gt_label_set_font_align(label, align)`	对齐方式：见枚举速查表 `gt_align_et`	—
`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_et`	NORMAL
`gt_label_set_font_encoding(label, encoding)`	文本编码：见枚举速查表 `gt_encoding_et`	UTF-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_et`	WRAP

/* 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");

运行后的标签控件效果如下图所示：

图2-2 标签控件效果

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

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, "请输入...");