🎮 在线体验：本章控件的渲染效果可在 控件在线演示页 实时交互——GT-HMI Engine 以 WebAssembly 在浏览器内渲染，调整右侧参数即可实时查看控件效果，与真机渲染一致。
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);
分组 gt_group
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
分组控件将多个子控件组织为一个逻辑组（常配合单选/复选做互斥管理）。实测子对象坐标为屏幕绝对坐标，分组本身不平移子对象。
组内文本（set_text）
调整组内子对象大小 set_resized
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
group_demo.c
/* group1 —— 摘自手册 5.1 节 */// 在 screen_home 屏幕控件中创建一个分组控件group1 = gt_group_create(screen_home);// 设置分组控件的位置为（90, 80）gt_obj_set_pos(group1, 90, 80);// 设置分组控件的尺寸为（宽度 300 高度 160）gt_obj_set_size(group1, 300, 160);// 向分组内添加子控件（坐标为屏幕绝对坐标）label1 = gt_label_create(group1);gt_obj_set_pos(label1, 120, 110);gt_label_set_text(label1, "单选演示");// 允许调整组内子对象大小gt_group_set_resized(group1, true);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);
单选框 gt_radio
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
三个单选框放在分组控件中——同组互斥，选中一个其余自动取消（互斥只在 gt_group 父容器内生效）。文字标签需字库子集，属第二批。
选中项 set_selected（同组互斥）
圆圈颜色 gt_obj_set_bgcolor
#909399
选中色 set_selected_color
#0f97ff
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
radio_demo.c
/* radio1 —— 摘自手册 5.2 节示例（文本行需字库，此处略） */// 创建分组控件（单选框的互斥只在分组内生效）group1 = gt_group_create(screen_home);// 在分组 1 控件中创建一个单选框控件radio1 = gt_radio_create(group1);// 设置单选框控件位置为 (170, 104) —— 屏幕绝对坐标，分组不产生偏移gt_obj_set_pos(radio1, 170, 104);// 设置单选框控件的尺寸为（宽度 140 高度 28）gt_obj_set_size(radio1, 140, 28);// 设置圆圈颜色为灰色（默认白色，浅色背景上不可见）gt_obj_set_bgcolor(radio1, gt_color_hex(0x909399));// 设置选中色为蓝色（选中后圆圈内芯的颜色）gt_radio_set_selected_color(radio1, gt_color_hex(0x0F97FF));// 设置单选框控件文本为 "one"（需字库支持）gt_radio_set_text(radio1, "one");// 同组再创建两个单选框（同组互斥）radio2 = gt_radio_create(group1);gt_obj_set_pos(radio2, 170, 152);gt_obj_set_size(radio2, 140, 28);radio3 = gt_radio_create(group1);gt_obj_set_pos(radio3, 170, 200);gt_obj_set_size(radio3, 140, 28);// 选中 radio2 —— 同组其余单选框自动取消选中gt_radio_set_selected(radio2);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 的运行效果（可直接交互）。
复选框 gt_checkbox
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
三个复选框各自独立勾选/取消（不互斥）。文字标签需字库子集，属第二批。
第一个复选框 set_checked
第二个复选框
选中色 set_selected_color
#0f97ff
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
checkbox_demo.c
/* cbox1 —— 摘自手册 5.3 节示例（文本行需字库，此处略） */// 创建分组容器（复选框不互斥，分组仅用于逻辑分组）group2 = gt_group_create(screen_home);// 在分组 2 控件中创建一个复选框控件cbox1 = gt_checkbox_create(group2);// 设置复选框位置为 (170, 104) —— 屏幕绝对坐标，分组不产生偏移gt_obj_set_pos(cbox1, 170, 104);// 设置复选框控件的尺寸为（宽度 140 高度 28）gt_obj_set_size(cbox1, 140, 28);// 设置复选框文本为 "A"（需字库支持）gt_checkbox_set_text(cbox1, "A");// 设置复选框状态为选中（0 = 未选中）gt_obj_set_state(cbox1, 1);// 同组再创建两个复选框（各自独立勾选）cbox2 = gt_checkbox_create(group2);gt_obj_set_pos(cbox2, 170, 152);gt_obj_set_size(cbox2, 140, 28);cbox3 = gt_checkbox_create(group2);gt_obj_set_pos(cbox3, 170, 200);gt_obj_set_size(cbox3, 140, 28);5.4 进度条控件
在创建的屏幕控件中添加一个进度条控件并设置进度条控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_progress_bar_create(parent) | 创建进度条控件 | — |
gt_progress_bar_set_start_end(bar, start, end) | 设置起止范围 | 0, 100 |
gt_progress_bar_set_pos(bar, pos) | 设置当前进度值 | 50 |
gt_progress_bar_get_pos(bar) | 获取当前进度值 | — |
gt_progress_bar_set_color_act(bar, color) | 设置活跃颜色 | 0x409eff |
gt_progress_bar_set_color_ina(bar, color) | 设置不活跃颜色 | 0xebeef5 |
gt_progress_bar_set_dir(bar, dir) | 设置方向：见 枚举速查表 gt_bar_dir_et | GT_BAR_DIR_HOR_L2R |
/* 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);
运行后的进度条控件效果如下方在线演示所示。
进度条 gt_progress_bar
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
与手册 5.4 节示例一致：起止范围、当前值、方向、颜色实时可调。R2L 方向为从右向左填充；"当前值"滑条范围跟随起止范围同步。
当前值 set_pos30
起止范围 set_start_end（同一数值在不同刻度下的占比变化；"当前值"范围随之同步）
方向 set_dir
活动区颜色 set_color_act
#00ff00
底色 set_color_ina
#808080
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
progress_demo.c
/* bar1 —— 摘自手册 5.4 节示例 */// 在 screen_home 屏幕控件中创建一个进度条控件bar1 = gt_progress_bar_create(screen_home);// 设置进度条的位置为 (100, 145)gt_obj_set_pos(bar1, 100, 145);// 设置进度条的尺寸为（宽度 280 高度 30）gt_obj_set_size(bar1, 280, 30);// 设置进度条的起始值为 0，结束值为 100//（右侧面板可切 0~360 / -50~50，"当前值"滑条范围随之同步）gt_progress_bar_set_start_end(bar1, 0, 100);// 设置进度条的当前值为 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));// 设置进度条的方向为从左到右（右侧面板可切 R2L：从右向左填充）gt_progress_bar_set_dir(bar1, GT_BAR_DIR_HOR_L2R);5.5 滑动条控件
在创建的屏幕控件中添加一个滑动条控件并设置滑动条控件属性。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_slider_create(parent) | 创建滑动条控件 | — |
gt_slider_set_start_end(slider, start, end) | 设置起止范围 | 0, 100 |
gt_slider_set_pos(slider, pos) | 设置当前值 | 0 |
gt_slider_get_pos(slider) | 获取当前值 | — |
gt_slider_set_color_act(slider, color) | 设置活跃颜色 | 0x409eff |
gt_slider_set_color_ina(slider, color) | 设置不活跃颜色 | 0xebeef5 |
gt_slider_set_color_tag(slider, color) | 设置刻度点颜色 | 同 color_act |
gt_slider_set_dir(slider, dir) | 设置方向：见 枚举速查表 gt_bar_dir_et | GT_BAR_DIR_HOR_L2R |
gt_slider_set_step(slider, step) | 设置步进值 | 1 |
gt_slider_set_tag(slider, "src") | 设置刻度点图片 | — |
gt_slider_set_tag_visible(slider, visible) | 刻度点可见 | true |
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);
运行后的滑动条控件效果如下方在线演示所示，可以拖动设置滑动条的值。
滑动条 gt_slider
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
与手册 5.5 节示例一致：调面板参数或直接拖画布上的滑条，实时观察渲染。GT_BAR_DIR 四方向即时切换（横向 236×40 / 竖向 24×300）。
方向 gt_slider_set_dir（自带匹配几何）
当前值 set_pos50
滑轨厚度 set_thickness20
活动区颜色 set_color_act
#409eff
底色 set_color_ina
#ebeef5
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
slider_demo.c
/* slider1 —— 摘自手册 5.5 节示例 */// 在 screen_home 屏幕控件中创建一个滑动条控件slider1 = gt_slider_create(screen_home);// 设置滑动条的位置为 (120, 140)（演示画布视觉居中；手册示例为 130）gt_obj_set_pos(slider1, 120, 140);// 设置滑动条的尺寸为（宽度 236 高度 40）gt_obj_set_size(slider1, 236, 40);// 设置滑动条的起始值为 0，结束值为 100gt_slider_set_start_end(slider1, 0, 100);// 设置滑动条的当前值为 50gt_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_dir(slider1, GT_BAR_DIR_HOR_L2R);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_ALIGN_CENTER_MID |
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) | 设置每项缩减区域 | 0 |
gt_listview_set_item_radius(listview, radius) | 设置每项圆角半径 | 8 |
gt_listview_set_border_color(listview, color) | 设置边框颜色 | 0xc7c7c7 |
gt_listview_set_border_width(listview, width) | 设置边框宽度 | 2 |
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");
运行后的列表控件效果见下方在线演示（可直接交互）：
列表 gt_listview
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
与手册 5.6 节一致：列表项逐条添加（演示为纯文本项），项背景/分割线/边框/字体颜色实时可调。画布内可上下滑动选择。
增删项 add_item / del_item
字体颜色 set_font_color
#2c3e50
每项背景色 set_item_bg_color
#f5f7fa
列表背景色 set_bg_color
#ffffff
边框颜色 set_border_color
#c7c7c7
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
listview_demo.c
/* listv1 —— 摘自手册 5.6 节示例（图标项行需资源包，此处为纯文本项） */// 在 screen_home 屏幕控件中创建一个列表控件listv1 = gt_listview_create(screen_home);// 设置列表的位置为（170, 55）gt_obj_set_pos(listv1, 170, 55);// 设置列表的尺寸为（宽度 140 高度 210）gt_obj_set_size(listv1, 140, 210);// 设置列表字体颜色为深灰gt_listview_set_font_color(listv1, gt_color_hex(0x2c3e50));// 设置列表字体尺寸为 18 点gt_listview_set_font_size(listv1, 18);// 设置列表每项高度为 40（⚠ 须在添加项之前设置）gt_listview_set_item_height(listv1, 40);// 设置列表边框颜色为 0xc7c7c7 灰色（右侧面板可调）gt_listview_set_border_color(listv1, gt_color_hex(0xc7c7c7));// 设置列表每项背景颜色（右侧面板可调）gt_listview_set_item_bg_color(listv1, gt_color_hex(0xf5f7fa));// 显示每项背景gt_listview_show_item_bg(listv1, true);// 设置列表每项圆角半径为 8gt_listview_set_item_radius(listv1, 8);// 逐条添加列表项（画布内可滑动选择）gt_listview_add_item(listv1, "按钮");gt_listview_add_item(listv1, "开关");gt_listview_add_item(listv1, "滑条");gt_listview_add_item(listv1, "进度条");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);
运行后的滚轮控件效果见下方在线演示（可直接交互）：
滚轮 gt_roller
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
与手册 5.7 节一致：选项经 \n 分隔一次设置，可视项数、选中项、选中背景色实时可调。画布内可按住上下滚动。
选项集 set_options（\n 分隔）
可视项数 set_display_item_count3
滚动 go_prev / go_next
选中背景色 set_select_bgcolor
#00a8ff
字体颜色 set_font_color
#2c3e50
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
roller_demo.c
/* roller1 —— 摘自手册 5.7 节示例 */// 在 screen_home 屏幕控件中创建一个滚轮控件roller1 = gt_roller_create(screen_home);// 设置滚轮的位置为 (175, 65)gt_obj_set_pos(roller1, 175, 65);// 设置滚轮的尺寸为（宽度 130 高度 190）gt_obj_set_size(roller1, 130, 190);// 设置滚轮的字体颜色为深灰gt_roller_set_font_color(roller1, gt_color_hex(0x2c3e50));// 设置字体的大小为 18gt_roller_set_font_size(roller1, 18);// 设置滚轮显示元素数量（右侧面板可调）gt_roller_set_display_item_count(roller1, 3);// 设置滚轮选项（\n 分隔；右侧面板可切换选项集）gt_roller_set_options(roller1, "标签\n列表\n滚轮\n时钟\n按钮\n开关", GT_ROLLER_MODE_NORMAL);// 设置滚轮当前选中第 2 项（画布内可拖动滚动）gt_roller_set_selected(roller1, 1);// 设置选中项背景颜色（右侧面板可调）gt_roller_set_select_bgcolor(roller1, gt_color_hex(0x00a8ff));5.8 下拉框控件
在创建的屏幕控件中添加一个下拉框控件。下拉框是输入框与列表控件的组合控件——点击输入框区域展开下拉列表，选中项填入输入框。通过监听 GT_EVENT_TYPE_UPDATE_VALUE 事件获取选中值。
API 参考：
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_select_create(parent) | 创建下拉框控件 | — |
gt_select_add_option(obj, "text") | 添加下拉选项 | — |
gt_select_clear_all_options(obj) | 清除所有选项 | — |
gt_select_set_option_height(obj, height) | 设置每项高度 | — |
gt_select_set_placeholder(obj, "placeholder") | 设置占位文本 | — |
gt_select_set_font_color(select, color) | 设置字体颜色 | — |
gt_select_set_font_size(select, size) | 设置字体大小（pt） | — |
gt_select_set_font_gray(select, gray) | 设置字体灰度 | — |
gt_select_set_font_align(select, align) | 对齐方式：见 枚举速查表 gt_align_et | — |
gt_select_set_font_family(select, family) | 设置字体系列 | — |
gt_select_set_font_cjk(select, cjk) | 设置 CJK 字体变体 | — |
gt_select_set_font_thick_en(select, thick) | 设置英文字体粗细 | — |
gt_select_set_font_thick_cn(select, thick) | 设置中文字体粗细 | — |
gt_select_set_font_encoding(select, encoding) | 设置字体编码 | — |
gt_select_set_font_style(select, font_style) | 字体风格：见 枚举速查表 gt_font_style_et | — |
gt_select_set_selected_anti_font(select, enabled) | 选中项反色字体：true=选中时字体反色 | false |
gt_select_is_selected_anti_font(select) | 获取反色字体状态 | — |
gt_select_set_selected_anti_font_color(select, color) | 设置反色字体颜色 | — |
gt_select_get_selected_anti_font_color(select) | 获取反色字体颜色 | — |
/** select1 */
// 在 screen_home 屏幕控件中创建一个下拉框控件
gt_obj_st * select1 = gt_select_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(select1, 100, 80);
// 设置控件尺寸
gt_obj_set_size(select1, 160, 30);
// 设置字体对齐方式为居中
gt_select_set_font_align(select1, GT_ALIGN_CENTER_MID);
// 设置占位文本
gt_select_set_placeholder(select1, "请选择");
// 添加下拉选项
gt_select_add_option(select1, "选项 A");
gt_select_add_option(select1, "选项 B");
gt_select_add_option(select1, "选项 C");
运行后的下拉框控件效果见下方在线演示（可直接交互）：
下拉框 gt_select
GT-HMI Engine 实时渲染 · 480×320滚动到此处后加载引擎（约 2MB，仅一次）
下拉框控件提供选项列表，点击展开后选择。面板可换选项集、改行高与选中项反色（换选项集走销毁重建：clear+add 在本构建不重绘）。
选项集 add_option（销毁重建）
选项行高 set_option_height40
选中项反色字体 set_selected_anti_font
▸查看 C 代码收起 C 代码与手册示例一致 · 点面板参数自动高亮对应行
select_demo.c
/* select1 —— 摘自手册 5.8 节 */// 在 screen_home 屏幕控件中创建一个下拉框控件select1 = gt_select_create(screen_home);// 设置下拉框控件的位置为（150, 40）gt_obj_set_pos(select1, 150, 40);// 设置下拉框控件的尺寸为（宽度 180 高度 46）gt_obj_set_size(select1, 180, 46);// 设置字体大小为 16ptgt_select_set_font_size(select1, 16);// 设置字体颜色gt_select_set_font_color(select1, gt_color_hex(0x2C3E50));// 设置每个选项的高度为 40gt_select_set_option_height(select1, 40);// 添加下拉选项gt_select_add_option(select1, "单选");gt_select_add_option(select1, "复选");gt_select_add_option(select1, "开关");// 选中项字体反色gt_select_set_selected_anti_font(select1, true);