3 交互控件 | GT-HMI Engine 用户手册 | 高通字库

3.1 图片按钮控件

　　在创建的屏幕控件中添加一个图片按钮控件并设置图片按钮控件属性。

API 参考：

函数	说明	默认值
`gt_imgbtn_create(parent)`	创建图片按钮控件	—
`gt_imgbtn_set_src(imgbtn, "src")`	设置默认图片路径	—
`gt_imgbtn_set_src_press(imgbtn, "src")`	设置按下时图片路径	—
`gt_imgbtn_set_src_release(imgbtn, "src")`	设置释放时图片路径	—
`gt_imgbtn_add_state_item(obj, "src")`	添加状态切换图片项	—
`gt_imgbtn_replace_state_item(obj, index, "src")`	替换指定索引的状态图片	—
`gt_imgbtn_remove_state_item(obj, "src")`	移除指定状态图片项	—
`gt_imgbtn_clear_all_state_item(obj)`	清除所有状态图片项	—
`bt_imgbtn_get_state_item_index(obj)`	获取当前状态项索引，-1=失败	—

/* imgbtn1 */
// 在 screen_home 屏幕控件中创建一个图片按钮控件
imgbtn1 = gt_imgbtn_create(screen_home);
// 设置图片控件的位置为 (150, 100)
gt_obj_set_pos(imgbtn1, 150, 100);
// 设置图片控件的尺寸为图片的大小尺寸（宽度 30 高度 30）
gt_obj_set_size(imgbtn1, 30, 30);
// 设置图片按钮控件按下时的图片数据访问路径
gt_imgbtn_set_src_press(imgbtn1, "f:img_97x110_112.png");
// 设置图片按钮控件未按下时的图片数据访问路径
gt_imgbtn_set_src(imgbtn1, "f:img_97x110_110.png");
// 设置图片控件按下后切换的图片数据访问路径
gt_imgbtn_add_state_item(imgbtn1, "f:img_97x110_113.png");

　　运行后的图片控件效果如下图所示，未按下时显示 110.png，按下不松手时显示 112.png 图片，按下后显示 113.png。

图2-5 图片按钮控件效果

3.2 键盘控件

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

API 参考：

函数	说明	默认值
`gt_keypad_create(parent)`	创建键盘控件	—
`gt_keypad_set_default_style(keypad, style)`	设置默认样式：`GT_KEYPAD_STYLE_26_KEY` / `NUMBER` / `9_KEY` / `OTHER_4x5` / `OTHER_11x3`	—
`gt_keypad_set_type(keypad, type)`	设置键盘类型：`GT_KEYPAD_TYPE_LOWER` / `UPPER` / `NUMBER` / `SYMBOL_EN` / `CH` / `SYMBOL_CH`	—
`gt_keypad_set_target(keypad, input)`	关联目标输入框	—
`gt_keypad_set_font_color(keypad, color)`	设置字体颜色	—
`gt_keypad_set_font_size(keypad, size)`	设置字体大小（pt）	—
`gt_keypad_set_font_gray(keypad, gray)`	设置字体灰度：1 / 2 / 4	—
`gt_keypad_set_color_background(keypad, color)`	设置键盘背景颜色	—
`gt_keypad_set_key_color_background(keypad, color)`	设置普通按键颜色	—
`gt_keypad_set_ctrl_key_color_background(keypad, color)`	设置控制键颜色	—
`gt_keypad_set_radius(keypad, radius)`	设置键盘圆角半径	—
`gt_keypad_set_auto_hide(keypad, auto_hide)`	聚焦屏幕对象时自动隐藏键盘	false

/** keyboard1 */
// 在 screen_home 屏幕控件中创建一个键盘控件
keyboard1 = gt_keypad_create(screen_home);
// 设置键盘的位置为（91, 105）
gt_obj_set_pos(keyboard1, 91, 105);
// 设置键盘的尺寸为（宽度 300 高度 170）
gt_obj_set_size(keyboard1, 300, 170);
// 设置键盘字体颜色为 0x000000 黑色
gt_keypad_set_font_color(keyboard1, gt_color_hex(0x000000));
// 设置键盘字体尺寸为 16 点
gt_keypad_set_font_size(keyboard1, 16);
// 设置键盘面板颜色为 0x242424 浅黑色
gt_keypad_set_color_background(keyboard1, gt_color_hex(0x242424));
// 设置键盘普通键颜色为 0x646464 浅灰色
gt_keypad_set_key_color_background(keyboard1, gt_color_hex(0x646464));
// 设置键盘控制键颜色为 0x3E3E3E 深灰色
gt_keypad_set_ctrl_key_color_background(keyboard1, gt_color_hex(0x3E3E3E));
// 设置键盘边框圆角半径为 6
gt_keypad_set_radius(keyboard1, 6);
// 设置键盘关联到输入框 input1
gt_keypad_set_target(keyboard1, input1);
// 修改键盘样式
gt_keypad_set_default_style(obj, GT_KEYPAD_STYLE_26_KEY);

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

图2-6 键盘控件效果

3.3 开关控件

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

API 参考：

函数	说明	默认值
`gt_switch_create(parent)`	创建开关控件	—
`gt_switch_set_color_act(switcher, color)`	设置活跃颜色	`0x13ce66`
`gt_switch_set_color_ina(switcher, color)`	设置不活跃颜色	`0xebeef5`
`gt_switch_set_color_point(switcher, color)`	设置开关点颜色	`0xffffff`
`gt_switch_set_color_divider(switcher, color)`	设置分割线颜色	`0xdcdfe6`
`gt_switch_set_style(switcher, style)`	设置开关样式：`GT_SWITCH_STYLE_DEFAULT` / `RECT` / `AXIS`	DEFAULT
`gt_switch_set_div_line(switcher, is_div_line)`	是否显示分割线	—
`gt_switch_set_div_line_size(switcher, w, h)`	设置分割线尺寸，0=自动计算	0, 0

/* switch1 */
// 在 screen_home 屏幕控件中创建一个开关控件
switch1 = gt_switch_create(screen_home);
// 设置开关控件位置为 (150, 100)
gt_obj_set_pos(switch1, 150, 100);
// 设置开关控件的尺寸为（宽度 50 高度 20）
gt_obj_set_size(switch1, 50, 20);
// 设置开关控件的初始活跃状态为活跃
gt_obj_set_state(switch1, 1);
// 设置开关控件活跃颜色为 0x13ce66 的绿色
gt_switch_set_color_act(switch1, gt_color_hex(0x13ce66));
// 设置开关控件不活跃颜色为 0xff0000 的红色
gt_switch_set_color_ina(switch1, gt_color_hex(0xff0000));
// 设置开关控件开关点的颜色为 0xffff00 的黄色
gt_switch_set_color_point(switch1, gt_color_hex(0xffff00));

　　运行后的开关控件效果如下图所示，点击控件可以切换开关的状态。

图2-7 开关控件效果

3.4 幻灯片控件

　　在创建的屏幕控件中添加一个幻灯片控件并设置控件属性。

API 参考：

函数	说明	默认值
`gt_player_create(parent)`	创建幻灯片控件	—
`gt_player_set_type(obj, type)`	设置播放类型：`GT_PLAYER_TYPE_IMG`	NONE
`gt_player_set_mode(obj, mode)`	设置播放模式：`GT_PLAYER_MODE_ONCE` / `LOOP` / `PLAYBACK`	NONE
`gt_player_set_auto_play_period(obj, period)`	设置自动播放间隔（ms），0=停止自动播放	—
`gt_player_add_item(obj, item, item_byte_size)`	添加播放项目，返回项目数	—
`gt_player_set_index(obj, index)`	设置当前播放项索引，-1=最后一项	—
`gt_player_play(obj)`	开始播放	—
`gt_player_stop(obj)`	停止播放	—
`gt_player_toggle(obj)`	播放/暂停切换	—
`gt_player_turn_prev(obj)`	切换到上一项	—
`gt_player_turn_next(obj)`	切换到下一项	—
`gt_player_set_repeat_count(obj, count)`	设置重复次数，-1=无限循环	—
`gt_player_set_real_time_update(obj, enabled)`	实时跳转模式刷新	—

/** player1 */
// 在 screen_home 屏幕控件中创建一个幻灯片控件
player1 = gt_player_create(screen_home);
// 设置幻灯片控件位置为 (114, 97)
gt_obj_set_pos(player1, 114, 97);
// 设置幻灯片控件的尺寸为（宽度 148 高度 77）
gt_obj_set_size(player1, 148, 77);
// 添加三张图片项目到幻灯片控件
gt_player_add_item(player1, "f:img_148x77_fh.png",
    sizeof("f:img_148x77_fh.png"));
gt_player_add_item(player1, "f:img_148x77_113.png",
    sizeof("f:img_148x77_113.png"));
gt_player_add_item(player1, "f:img_148x77_110.png",
    sizeof("f:img_148x77_110.png"));
// 设置幻灯片控件文件类型为 image 图片
gt_player_set_type(player1, GT_PLAYER_TYPE_IMG);
// 设置幻灯片控件播放模式为循环播放
gt_player_set_mode(player1, GT_PLAYER_MODE_LOOP);
// 设置幻灯片控件从序号 1 项（0 开始算起）开始播放
gt_player_set_index(player1, 1);
// 设置幻灯片控件播放间隔为 500ms
gt_player_set_auto_play_period(player1, 500);
// 开始播放
gt_player_play(player1);

　　运行后的幻灯片控件效果如下图所示，以每张间隔 500ms 的时间循环切换播放设置的三张图片。

图2-8 幻灯片控件效果

3.5 计数器控件

　　在创建的屏幕控件中添加一个计数器控件并设置控件属性。

API 参考：

函数	说明	默认值
`gt_input_number_create(parent)`	创建计数器控件	—
`gt_input_number_set_value(obj, value)`	设置当前数值	0
`gt_input_number_get_value(obj)`	获取当前数值	—
`gt_input_number_set_min(obj, min)`	设置最小值	—
`gt_input_number_set_max(obj, max)`	设置最大值	—
`gt_input_number_set_step(obj, step)`	设置递增/递减步进值	—
`gt_input_number_set_fill_zero_front(obj, enabled)`	开启前导零补齐	—
`gt_input_number_set_display_integer_length(obj, len)`	设置整数显示宽度，0=自动	0
`gt_input_number_set_display_decimal_length(obj, len)`	设置小数显示宽度	2
`gt_input_number_set_font_color(obj, color)`	设置字体颜色	—
`gt_input_number_set_font_size(obj, size)`	设置字体大小（pt）	—
`gt_input_number_set_font_align(obj, align)`	对齐方式：见枚举速查表 `gt_align_et`	—
`gt_input_number_increase(obj)`	按步进递增，返回新值	—
`gt_input_number_decrease(obj)`	按步进递减，返回新值	—

/** inputNum1 */
// 在 screen_home 屏幕控件中创建一个计数器控件
inputNum1 = gt_input_number_create(screen_home);
// 设置计数器控件位置为 (68, 96)
gt_obj_set_pos(inputNum1, 68, 96);
// 设置计数器控件的尺寸为（宽度 108 高度 24）
gt_obj_set_size(inputNum1, 108, 24);
// 设置字体颜色为 0x000000 的黑色
gt_input_number_set_font_color(inputNum1, gt_color_hex(0x000000));
// 设置字号为 16 点
gt_input_number_set_font_size(inputNum1, 16);
// 设置对齐方式为左对齐
gt_input_number_set_font_align(inputNum1, GT_ALIGN_LEFT);
// 设置计数值为 2
gt_input_number_set_value(inputNum1, 2);
// 设置递增/递减的步进值为 200
gt_input_number_set_step(inputNum1, 200);
// 设置最小值为 0
gt_input_number_set_min(inputNum1, 0);
// 设置最大值为 1000
gt_input_number_set_max(inputNum1, 1000);
// 开启格式化补齐数值
gt_input_number_set_fill_zero_front(inputNum1, true);
// 设置整数部分显示宽度为 3
gt_input_number_set_display_integer_length(inputNum1, 3);
// 设置小数部分显示宽度为 1
gt_input_number_set_display_decimal_length(inputNum1, 1);

　　运行后的计数器显示效果如下，2 不足 3 位以 0 补齐为 002，保留 1 位小数显示为 002.0。与 add 按钮配合触发递增事件后，增加设定的步进值 200 变为 202.0。

图2-9 计数器控件效果

3.6 按钮控件

　　在创建的屏幕控件中，添加一个按钮控件并设置按钮的属性。

API 参考：

函数	说明	默认值
`gt_btn_create(parent)`	创建按钮控件	—
`gt_btn_set_text(btn, "fmt", ...)`	设置按钮文本（printf 格式）	—
`gt_btn_set_text_by_len(btn, "text", len)`	按长度设置文本	—
`char * gt_btn_get_text(btn)`	获取按钮文本	—
`gt_btn_set_font_color(btn, color)`	设置字体颜色	—
`gt_btn_set_font_color_pressed(btn, color)`	设置按下时字体颜色	—
`gt_btn_set_font_size(btn, size)`	设置字体大小（pt）	—
`gt_btn_set_font_align(btn, align)`	对齐方式：见枚举速查表 `gt_align_et`	—
`gt_btn_set_font_family_cn/en/numb(btn, id)`	设置字体系列（中文/英文/数字）	—
`gt_btn_set_color_background(btn, color)`	设置背景颜色	—
`gt_btn_set_color_pressed(btn, color)`	设置按下时背景颜色	—
`gt_btn_set_color_border(btn, color)`	设置边框颜色	—
`gt_btn_set_border_width(btn, width)`	设置边框宽度	—
`gt_btn_set_radius(btn, radius)`	设置圆角半径	—
`gt_btn_set_corner_radius(btn, tl, tr, bl, br)`	独立设置四角圆角，false=直角	—
`gt_btn_set_space(btn, space_x, space_y)`	设置字间距	0, 0
`gt_btn_set_font_style(btn, style)`	字体风格：见枚举速查表 `gt_font_style_et`	NORMAL
`gt_btn_add_state_content(btn, "str")`	添加切换状态文本	—
`gt_btn_set_selected(obj)`	设为选中状态	—
`gt_btn_set_state_enabled(obj, enabled)`	开启/关闭状态切换功能	true
`gt_btn_set_auto_scroll_single_line(obj, enabled)`	单行自动滚动（文本超宽时）	false
`gt_btn_set_auto_scroll_total_time(btn, total_time_ms)`	设置自动滚动总时长（ms），0=默认 2s	—
`gt_btn_set_button_id(btn, button_id)`	绑定物理按键 ID	—

// 设置屏幕的背景颜色为白色
gt_screen_set_bgcolor(screen_home, gt_color_hex(0xFFFFFF));
/* btn1 */
// 在 screen_home 屏幕控件中创建一个 Button 按钮控件
btn1 = gt_btn_create(screen_home);
// 设置 Button 控件的位置为 (100, 100)
gt_obj_set_pos(btn1, 100, 100);
// 设置 Button 控件的尺寸（宽度 60 高度 30）
gt_obj_set_size(btn1, 60, 30);
// 设置 Button 控件显示的字体颜色为黑色
gt_btn_set_font_color(btn1, gt_color_hex(0x000000));
// 设置 Button 控件显示的字体尺寸为 16 点
gt_btn_set_font_size(btn1, 16);
// 设置 Button 控件显示的文本为 "btn"
gt_btn_set_text(btn1, "btn");
// 设置 Button 控件本身的背景颜色为 R-0x35 G-0x80 B-0xbb 的蓝色
gt_btn_set_color_background(btn1, gt_color_hex(0x3580bb));
// 设置 Button 控件圆角矩形圆角的圆半径为 4
gt_btn_set_radius(btn1, 4);
// 设置中文字体
gt_btn_set_font_family_cn(btn1, 11);
// 设置外文字体
gt_btn_set_font_family_en(btn1, 41);
// 设置数字符号
gt_btn_set_font_family_numb(btn1, 113);
// 设置对齐方式为居中对齐
gt_btn_set_font_align(btn1, GT_ALIGN_CENTER);
// 设置字 x 间隔为 1，y 间隔为 0
gt_btn_set_space(btn1, 1, 0);
// 添加点击时文本内容变化为 123
gt_btn_add_state_content(btn1, "123");

　　运行后的按钮控件效果如下所示：

图2-10 按钮控件效果

3.7 时钟控件

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

API 参考：

函数	说明	默认值
`gt_clock_create(parent)`	创建时钟控件	—
`gt_clock_set_time(obj, hour, minute, second)`	设置当前时间	—
`gt_clock_set_date(obj, year, month, day)`	设置日期	—
`gt_clock_set_alert_time(obj, hour, minute, second)`	设置闹钟时间	—
`gt_clock_get_time(obj, time)`	获取当前时间，返回值=时间戳	—
`gt_clock_get_alert_time(obj, time)`	获取闹钟时间，返回值=时间戳	—
`gt_clock_set_mode(obj, mode)`	设置工作模式：`GT_CLOCK_MODE_TIME` / `COUNTDOWN`	TIME
`gt_clock_set_format(obj, "format")`	设置时间显示格式。格式符：hh/mm/ss/yyyy/MM/dd/EEE	`"hh:mm:ss"`
`gt_clock_set_12_hours_mode(obj, enabled)`	启用 12 小时制	false
`gt_clock_set_meridiem_mode(obj, enabled)`	显示 AM/PM（仅在 12 小时制有效）	false
`gt_clock_set_twinkle_colon_mode(obj, enabled)`	冒号闪烁模式	false
`gt_clock_set_twinkle_colon_period(obj, period_ms)`	冒号闪烁周期	500ms
`gt_clock_set_font_color(obj, color)`	设置字体颜色	—
`gt_clock_set_font_size(obj, size)`	设置字体大小（pt）	—
`gt_clock_set_font_align(obj, align)`	对齐方式：见枚举速查表 `gt_align_et`	—
`gt_clock_set_font_family_cn/en(obj, id)`	设置字体系列（中文/英文）	—
`gt_clock_start(obj)`	启动时钟	—
`gt_clock_stop(obj)`	停止时钟	—
`gt_clock_toggle(obj)`	切换启停状态	—
`gt_clock_set_alert_cb(obj, alert_cb, user_data)`	闹钟回调（倒计时到 00:00:00 触发）	—
`gt_clock_set_next_day_cb(obj, next_day_cb, user_data)`	跨天回调	—

/** clock1 */
// 在 screen_home 屏幕控件中创建一个时钟控件
clock1 = gt_clock_create(screen_home);
// 设置时钟控件位置为 (168, 123)
gt_obj_set_pos(clock1, 168, 123);
// 设置时钟控件的尺寸为（宽度 200，高度 24）
gt_obj_set_size(clock1, 200, 24);
// 设置字体颜色为 0x000000 的黑色
gt_clock_set_font_color(clock1, gt_color_hex(0x000000));
// 设置字号为 24 点
gt_clock_set_font_size(clock1, 24);
// 设置中文字体
gt_clock_set_font_family_cn(clock1, 5);
// 设置英文字体
gt_clock_set_font_family_en(clock1, 41);
// 设置当前时间为 0 时 5 分 0 秒
gt_clock_set_time(clock1, 0, 5, 0);
// 设置定时时间为 0 时 3 分 0 秒
gt_clock_set_alert_time(clock1, 0, 3, 0);
// 设置时钟的工作模式为倒计时
gt_clock_set_mode(clock1, GT_CLOCK_MODE_COUNTDOWN);
// 设置时钟的显示格式
gt_clock_set_format(clock1, "hh时mm分ss秒");
// 设置对齐方式为左对齐
gt_clock_set_font_align(clock1, GT_ALIGN_LEFT);
// 设置为 12 小时制
gt_clock_set_12_hours_mode(clock1, true);
// 设置启用 AM/PM
gt_clock_set_meridiem_mode(clock1, true);
// 开启时钟
gt_clock_start(clock1);

　　运行后的时钟控件显示效果如下：在倒计时到 3 分时，将会触发你添加的定时事件。

图2-11 时钟控件效果