5 表单控件 | GT-HMI Engine 用户手册 | 高通字库

5.1 分组控件

　　在创建的屏幕控件中添加一个分组控件。分组组件为逻辑抽象控件，并不会在屏幕上有显示效果，无需更改样式属性。通常与单选框、复选框组合使用。

API 参考：

函数	说明	默认值
`gt_group_create(parent)`	创建分组控件	—
`gt_group_get_active_obj(group, type)`	获取组内选中/活跃的子对象	—
`gt_group_reset_selected_state(group, type)`	重置组内第一个对象为活跃状态	—
`gt_group_set_resized(group, is_resized)`	允许调整组内子对象大小	false

/* group1 */
// 在 screen_home 屏幕控件中创建一个分组控件
group1 = gt_group_create(screen_home);

5.2 单选框控件

　　在创建的分组 1 控件中添加一个单选框控件并设置单选框控件属性。

API 参考：

函数	说明	默认值
`gt_radio_create(parent)`	创建单选框控件	—
`gt_radio_set_selected(radio)`	设为选中状态	—
`gt_radio_set_text(radio, "fmt", ...)`	设置文本	—
`gt_radio_set_font_color(radio, color)`	设置字体颜色	—
`gt_radio_set_font_size(radio, size)`	设置字体大小（pt）	—
`gt_radio_set_font_align(radio, align)`	对齐方式：见枚举速查表 `gt_align_et`	—
`gt_radio_set_font_family_cn/en(radio, id)`	设置字体系列（中文/英文）	—
`gt_radio_set_font_style(radio, style)`	字体风格：见枚举速查表 `gt_font_style_et`	NORMAL
`gt_radio_set_selected_color(radio, color)`	设置选中色	—
`gt_radio_set_font_point_offset(radio, x, y)`	设置文字与选择点的偏移	—

/* radio1 */
// 在创建的分组 1 控件中创建一个单选框控件
radio1 = gt_radio_create(group1);
// 设置单选框控件位置为 (83, 155)
gt_obj_set_pos(radio1, 83, 155);
// 设置单选控件的尺寸为（宽度 60 高度 24）
gt_obj_set_size(radio1, 60, 24);
// 设置单选框控件字体颜色为 0x000000 黑色
gt_radio_set_font_color(radio1, gt_color_hex(0x000000));
// 设置单选框控件显示的字体尺寸为 16 点
gt_radio_set_font_size(radio1, 16);
// 设置对齐方式为左对齐
gt_radio_set_font_align(radio1, GT_ALIGN_LEFT);
// 设置单选框控件文本为 "one"
gt_radio_set_text(radio1, "one");
// 设置单选框状态为选中状态
gt_radio_set_selected(radio1);

5.3 复选框控件

　　在创建的分组 2 中添加一个复选框控件并设置复选框控件属性。

API 参考：

函数	说明	默认值
`gt_checkbox_create(parent)`	创建复选框控件	—
`gt_checkbox_set_text(checkbox, "fmt", ...)`	设置文本	—
`char * gt_checkbox_get_text(checkbox)`	获取文本	—
`gt_checkbox_set_font_color(checkbox, color)`	设置字体颜色	—
`gt_checkbox_set_font_size(checkbox, size)`	设置字体大小（pt）	—
`gt_checkbox_set_font_family_cn/en(checkbox, id)`	设置字体系列（中文/英文）	—
`gt_checkbox_set_font_style(checkbox, style)`	字体风格：见枚举速查表 `gt_font_style_et`	NORMAL
`gt_checkbox_set_font_point_offset(checkbox, x, y)`	设置文字与选择框的偏移	—
`gt_checkbox_set_space(checkbox, space_x, space_y)`	设置字间距	0, 0

复选框的状态切换通过基类 API gt_obj_set_state() 控制。

/* cbox1 */
// 在创建的分组 2 控件中创建一个复选框控件
cbox1 = gt_checkbox_create(group2);
// 设置复选框位置为 (218, 164)
gt_obj_set_pos(cbox1, 218, 164);
// 设置复选框控件的尺寸为（宽度 84 高度 24）
gt_obj_set_size(cbox1, 84, 24);
// 设置复选框控件字体颜色为 0x000000 黑色
gt_checkbox_set_font_color(cbox1, gt_color_hex(0x000000));
// 设置复选框控件显示的字体尺寸为 16 点
gt_checkbox_set_font_size(cbox1, 16);
// 设置对齐方式为左对齐
gt_checkbox_set_font_align(cbox1, GT_ALIGN_LEFT);
// 设置复选框控件文本为 "A"
gt_checkbox_set_text(cbox1, "A");
// 设置复选框状态为未选中状态
gt_obj_set_state(cbox1, 0);

　　下图为添加两个单选框到分组 1，两个复选框到分组 2 的运行效果。

图2-15 单选框与复选框控件效果

5.4 进度条控件

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

API 参考：

函数	说明	默认值
`gt_progress_bar_create(parent)`	创建进度条控件	—
`gt_progress_bar_set_start_end(bar, start, end)`	设置起止范围	—
`gt_progress_bar_set_pos(bar, pos)`	设置当前进度值	—
`gt_progress_bar_get_pos(bar)`	获取当前进度值	—
`gt_progress_bar_set_color_act(bar, color)`	设置活跃颜色	—
`gt_progress_bar_set_color_ina(bar, color)`	设置不活跃颜色	—
`gt_progress_bar_set_dir(bar, dir)`	设置方向：见枚举速查表 `gt_bar_dir_et`	—

/* bar1 */
// 在 screen_home 屏幕控件中创建一个进度条控件
bar1 = gt_progress_bar_create(screen_home);
// 设置进度条的位置为 (100, 80)
gt_obj_set_pos(bar1, 100, 80);
// 设置进度条的尺寸为（宽度 200 高度 30）
gt_obj_set_size(bar1, 200, 30);
// 设置进度条的起始值为 -20 结束值为 180
gt_progress_bar_set_start_end(bar1, -20, 180);
// 设置进度条的当前值为 30
gt_progress_bar_set_pos(bar1, 30);
// 设置进度条的活跃颜色为 0x00ff00 的绿色
gt_progress_bar_set_color_act(bar1, gt_color_hex(0x00ff00));
// 设置进度条的不活跃颜色为 0x808080 的灰色
gt_progress_bar_set_color_ina(bar1, gt_color_hex(0x808080));
// 设置进度条的方向为从左到右
gt_progress_bar_set_dir(bar1, GT_BAR_DIR_HOR_L2R);

　　运行后的进度条控件效果如下图所示。

图2-16 进度条控件效果

5.5 滑动条控件

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

API 参考：

函数	说明	默认值
`gt_slider_create(parent)`	创建滑动条控件	—
`gt_slider_set_start_end(slider, start, end)`	设置起止范围	—
`gt_slider_set_pos(slider, pos)`	设置当前值	—
`gt_slider_get_pos(slider)`	获取当前值	—
`gt_slider_set_color_act(slider, color)`	设置活跃颜色	—
`gt_slider_set_color_ina(slider, color)`	设置不活跃颜色	—
`gt_slider_set_color_tag(slider, color)`	设置刻度点颜色	—
`gt_slider_set_dir(slider, dir)`	设置方向：见枚举速查表 `gt_bar_dir_et`	—
`gt_slider_set_step(slider, step)`	设置步进值	—
`gt_slider_set_tag(slider, "src")`	设置刻度点图片	—
`gt_slider_set_tag_visible(slider, visible)`	刻度点可见	—
`gt_slider_set_tag_size(slider, size)`	刻度点大小	—
`gt_slider_set_tag_inside(slider, inside)`	刻度点在轨道内部	false
`gt_slider_set_thickness(slider, thickness)`	设置长条宽度（像素）	—
`gt_slider_set_mode(slider, mode)`	设置模式：`GT_SLIDER_MODE_DEFAULT` / `STEP`	DEFAULT
`gt_slider_set_pos_range(slider, min, max)`	设置滑块位置限制范围	—
`gt_slider_set_touch_mode(slider, touch_mode)`	设置触摸模式，true=仅滑动生效	—

/** slider1 */
// 在 screen_home 屏幕控件中创建一个滑动条控件
slider1 = gt_slider_create(screen_home);
// 设置滑动条的位置为（120, 130）
gt_obj_set_pos(slider1, 120, 130);
// 设置滑动条的尺寸为（宽度 236 高度 40）
gt_obj_set_size(slider1, 236, 40);
// 设置滑动条的起始值为 0，结束值为 100
gt_slider_set_start_end(slider1, 0, 100);
// 设置滑动条的当前值为 50
gt_slider_set_pos(slider1, 50);
// 设置滑动条的活跃颜色为 0x409eff 蓝色
gt_slider_set_color_act(slider1, gt_color_hex(0x409eff));
// 设置滑动条的不活跃颜色为 0xebeef5 浅灰色
gt_slider_set_color_ina(slider1, gt_color_hex(0xebeef5));
// 设置滑动条的刻度点可见
gt_slider_set_tag_visible(slider1, 1);
// 设置滑动条的滑动方向为从左到右
gt_slider_set_dir(slider1, GT_BAR_DIR_HOR_L2R);
// 设置滑动条的长条宽度为 20
gt_slider_set_thickness(slider1, 20);
// 设置滑动条的刻度点大小为 40
gt_slider_set_tag_size(slider1, 40);

　　运行后的滑动条控件效果如下图所示，可以拖动设置滑动条的值。

图2-17 滑动条控件效果

5.6 列表控件

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

API 参考：

函数	说明	默认值
`gt_listview_create(parent)`	创建列表控件	—
`gt_listview_add_item(listview, "text")`	添加纯文本项	—
`gt_listview_add_item_icon(listview, "img", "text")`	添加图标+文本项	—
`gt_listview_add_item_icons(listview, left_img, "text", right_img)`	添加左图标+文本+右图标项	—
`gt_listview_set_item_height(listview, height)`	设置每项高度（⚠ 添加项之前设置）	—
`gt_listview_set_next_row_item_count(listview, count)`	设置下一行每行列数	1
`gt_listview_set_scale(listview, icon, label)`	设置图标+文本比例	25, 75
`gt_listview_set_scale_triple(listview, left, center, right)`	设置三区比例	20, 60, 20
`gt_listview_set_font_color(listview, color)`	设置字体颜色	—
`gt_listview_set_font_size(listview, size)`	设置字体大小（pt）	—
`gt_listview_set_font_align(listview, align)`	对齐方式：见枚举速查表 `gt_align_et`	—
`gt_listview_set_bg_color(listview, color)`	设置背景颜色	—
`gt_listview_set_item_bg_color(listview, color)`	设置每项背景颜色	—
`gt_listview_show_item_bg(listview, show)`	显示每项背景	false
`gt_listview_set_item_reduce(listview, reduce)`	设置每项缩减区域	2
`gt_listview_set_item_radius(listview, radius)`	设置每项圆角半径	10
`gt_listview_set_border_color(listview, color)`	设置边框颜色	—
`gt_listview_set_border_width(listview, width)`	设置边框宽度	—
`gt_listview_set_septal_line(listview, enabled)`	显示项分割线	true
`gt_listview_set_selected_effect(listview, enabled)`	启用选中效果	true
`gt_listview_set_highlight_mode(listview, enabled)`	选中项高亮模式	—
`gt_listview_set_multiple(listview, enabled)`	多选模式	false
`gt_listview_set_horizontal(listview, enabled)`	水平滑动模式（⚠ 添加项之前设置）	false
`gt_listview_set_item_width(listview, width)`	水平模式下每项宽度（⚠ 添加项之前设置）	—
`gt_listview_del_item(listview, item_idx)`	删除指定项	—
`gt_listview_clear_all_items(listview)`	清除所有项	—

/** listv1 */
// 在 screen_home 屏幕控件中创建一个列表控件
listv1 = gt_listview_create(screen_home);
// 设置列表的位置为（180, 180）
gt_obj_set_pos(listv1, 180, 180);
// 设置列表的尺寸为（宽度 120 高度 100）
gt_obj_set_size(listv1, 120, 100);
// 设置列表字体颜色为 0x000000 黑色
gt_listview_set_font_color(listv1, gt_color_hex(0x000000));
// 设置列表字体尺寸为 16 点
gt_listview_set_font_size(listv1, 16);
// 设置列表对齐方式为居中对齐
gt_listview_set_font_align(listv1, GT_ALIGN_CENTER_MID);
// 设置列表每项高度为 24
gt_listview_set_item_height(listv1, 24);
// 设置列表边框颜色为 0xc7c7c7 灰色
gt_listview_set_border_color(listv1, gt_color_hex(0xc7c7c7));
// 设置列表边框宽度为 2
gt_listview_set_border_width(listv1, 2);
// 设置列表每项分割线
gt_listview_set_septal_line(listv1, 1);
// 设置列表选中高亮模式
gt_listview_set_highlight_mode(listv1, 1);
// 设置列表背景颜色为 0xffffff 白色
gt_listview_set_bg_color(listv1, gt_color_hex(0xffffff));
// 设置列表每项背景颜色为 0xffffff 白色
gt_listview_set_item_bg_color(listv1, gt_color_hex(0xffffff));
// 设置列表显示每项背景颜色
gt_listview_show_item_bg(listv1, true);
// 设置列表每项内边距为 2
gt_listview_set_item_reduce(listv1, 2);
// 设置列表每项边框半径为 10
gt_listview_set_item_radius(listv1, 10);
// 设置列表中单图标样式比例为文本 80：图标 20
gt_listview_set_scale(listv1, 20, 80);
// 设置列表中单图标样式比例为左图标：20 文本 60：右图标 20
gt_listview_set_scale_triple(listv1, 20, 60, 20);
// 设置列表一行显示列数为单列
gt_listview_set_next_row_item_count(listv1, 1);
// 设置列表第一行图标 1.png，文本为 hello
gt_listview_add_item_icon(listv1, ".:1.png", "hello");
// 设置列表第二行左图标 2.png，文本为 hi，右图标为 3.png
gt_listview_add_item_icons(listv1, ".:2.png", "hi", ".:3.png");
// 设置列表第三行文本为 HMI
gt_listview_add_item(listv1, "HMI");
// 设置列表一行显示列数为双列
gt_listview_set_next_row_item_count(listv1, 2);
// 设置列表第四行左文本为 test，右文本为 GT
gt_listview_add_item(listv1, "test");
gt_listview_add_item(listv1, "GT");

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

图2-18 列表控件效果

5.7 滚轮控件

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

API 参考：

函数	说明	默认值
`gt_roller_create(parent)`	创建滚轮控件	—
`gt_roller_set_options(obj, "A\nB\nC", mode)`	设置选项内容（`\n` 分隔），最大 256 项。mode：`GT_ROLLER_MODE_NORMAL` / `INFINITE`	NORMAL
`gt_roller_set_display_item_count(obj, count)`	设置可视项数量	3
`gt_roller_set_selected(obj, index)`	设置当前选中项索引（0 起始）	—
`gt_roller_get_selected(obj)`	获取当前选中项索引，-1=失败	—
`gt_roller_set_select_bgcolor(obj, color)`	设置选中项背景颜色	`0x00a8ff`
`gt_roller_set_font_color(obj, color)`	设置字体颜色	—
`gt_roller_set_font_size(obj, size)`	设置字体大小（pt）	—
`gt_roller_set_font_align(obj, align)`	对齐方式：见枚举速查表 `gt_align_et`	—
`gt_roller_set_line_space(obj, space)`	设置行间距	—
`gt_roller_go_prev(obj)`	上一项（返回新索引）	—
`gt_roller_go_next(obj)`	下一项（返回新索引）	—
`gt_roller_hide_background(obj, hide)`	隐藏背景	false

// 在 screen_home 屏幕控件中创建一个滚轮控件
roller1 = gt_roller_create(screen_home);
// 设置矩形的位置为 (184, 85)
gt_obj_set_pos(roller1, 184, 85);
// 设置滚轮的尺寸为（宽度 100 高度 100）
gt_obj_set_size(roller1, 100, 100);
// 设置滚轮的字体颜色为黑色
gt_roller_set_font_color(roller1, gt_color_hex(0x000000));
// 设置字体的大小为 16
gt_roller_set_font_size(roller1, 16);
// 设置对齐方式为居中对齐
gt_roller_set_font_align(roller1, GT_ALIGN_CENTER_MID);
// 设置滚轮显示元素数量
gt_roller_set_display_item_count(roller1, 3);
// 设置滚轮选项
gt_roller_set_options(roller1, "1\n2\n3\n4\n5\n6\n7\n8",
    GT_ROLLER_MODE_NORMAL);
// 设置滚轮元素行间距
gt_roller_set_line_space(roller1, 17);
// 设置滚轮当前选中第几项
gt_roller_set_selected(roller1, 1);

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

图2-19 滚轮控件效果