滚动控件¶

概述¶

滚动控件用于在有限的显示区域内展示超出屏幕范围的内容。EmbeddedGUI 提供了四种滚动容器：Scroll 支持垂直滚动，ViewPage 和 ViewPageCache 支持水平翻页，TileView 支持二维网格式的瓦片导航。这些控件都内置了触摸拖拽和惯性滑动支持。

Scroll¶

垂直滚动容器，内部使用 LinearLayout 自动排列子控件。当子控件总高度超过容器高度时，支持触摸拖拽和惯性滚动。

效果展示¶

在线演示

API¶

函数	说明
`egui_view_scroll_init(self, core)`	初始化 Scroll
`egui_view_scroll_init_with_params(self, core, params)`	使用参数初始化
`egui_view_scroll_add_child(self, child)`	添加子控件
`egui_view_scroll_set_size(self, width, height)`	设置容器大小
`egui_view_scroll_start_container_scroll(self, diff_y)`	程序化滚动指定偏移
`egui_view_scroll_fling(self, velocity_y)`	以指定速度惯性滚动
`egui_view_scroll_set_scrollbar_enabled(self, enabled)`	启用滚动条(需开启 SCROLLBAR)

参数宏¶

EGUI_VIEW_SCROLL_PARAMS_INIT(name, x, y, w, h);

代码示例¶

static egui_view_scroll_t scroll;
static egui_view_label_t items[10];

EGUI_VIEW_SCROLL_PARAMS_INIT(scroll_params, 0, 0, 200, 120);

void init_ui(egui_core_t *core)
{
    egui_view_scroll_init_with_params(
        EGUI_VIEW_OF(&scroll), core, &scroll_params);

    char buf[16];
    for (int i = 0; i < 10; i++)
    {
        egui_view_label_init(EGUI_VIEW_OF(&items[i]), core);
        egui_view_set_size(EGUI_VIEW_OF(&items[i]), 180, 30);
        egui_view_label_set_text(EGUI_VIEW_OF(&items[i]), "Item");
        egui_view_set_margin_all(EGUI_VIEW_OF(&items[i]), 2);
        egui_view_scroll_add_child(
            EGUI_VIEW_OF(&scroll), EGUI_VIEW_OF(&items[i]));
    }

    egui_core_add_user_root_view(core, EGUI_VIEW_OF(&scroll));
}

配置选项¶

宏	说明
`EGUI_CONFIG_FUNCTION_SUPPORT_SCROLLBAR`	启用滚动条显示

ViewPage¶

水平翻页容器，每次显示一个子页面，支持触摸左右滑动切换页面。适合实现引导页、Tab 页面等场景。

效果展示¶

在线演示

API¶

函数	说明
`egui_view_viewpage_init(self, core)`	初始化 ViewPage
`egui_view_viewpage_init_with_params(self, core, params)`	使用参数初始化
`egui_view_viewpage_add_child(self, child)`	添加页面
`egui_view_viewpage_remove_child(self, child)`	移除页面
`egui_view_viewpage_set_current_page(self, page_index)`	直接跳转到指定页
`egui_view_viewpage_scroll_to_page(self, page_index)`	平滑滚动到指定页
`egui_view_viewpage_set_on_page_changed(self, callback)`	设置页面切换回调
`egui_view_viewpage_set_size(self, width, height)`	设置容器大小
`egui_view_viewpage_set_scrollbar_enabled(self, enabled)`	启用滚动条(需开启 SCROLLBAR)

参数宏¶

EGUI_VIEW_VIEWPAGE_PARAMS_INIT(name, x, y, w, h);

代码示例¶

static egui_view_viewpage_t viewpage;
static egui_view_label_t page1, page2, page3;

EGUI_VIEW_VIEWPAGE_PARAMS_INIT(vp_params, 0, 0, 240, 200);

static void on_page_changed(egui_view_t *self, int page_index)
{
    EGUI_LOG_INF("Page changed to: %d\n", page_index);
}

void init_ui(egui_core_t *core)
{
    egui_view_viewpage_init_with_params(
        EGUI_VIEW_OF(&viewpage), core, &vp_params);

    egui_view_label_init(EGUI_VIEW_OF(&page1), core);
    egui_view_set_size(EGUI_VIEW_OF(&page1), 240, 200);
    egui_view_label_set_text(EGUI_VIEW_OF(&page1), "Page 1");

    egui_view_label_init(EGUI_VIEW_OF(&page2), core);
    egui_view_set_size(EGUI_VIEW_OF(&page2), 240, 200);
    egui_view_label_set_text(EGUI_VIEW_OF(&page2), "Page 2");

    egui_view_label_init(EGUI_VIEW_OF(&page3), core);
    egui_view_set_size(EGUI_VIEW_OF(&page3), 240, 200);
    egui_view_label_set_text(EGUI_VIEW_OF(&page3), "Page 3");

    egui_view_viewpage_add_child(
        EGUI_VIEW_OF(&viewpage), EGUI_VIEW_OF(&page1));
    egui_view_viewpage_add_child(
        EGUI_VIEW_OF(&viewpage), EGUI_VIEW_OF(&page2));
    egui_view_viewpage_add_child(
        EGUI_VIEW_OF(&viewpage), EGUI_VIEW_OF(&page3));

    egui_view_viewpage_set_on_page_changed(
        EGUI_VIEW_OF(&viewpage), on_page_changed);

    egui_core_add_user_root_view(core, EGUI_VIEW_OF(&viewpage));
}

配置选项¶

宏	说明
`EGUI_CONFIG_FUNCTION_SUPPORT_SCROLLBAR`	启用滚动条显示

ViewPageCache¶

带缓存机制的翻页容器，适用于页面数量较多的场景。仅缓存当前页及相邻页面(最多 3 页)，通过回调动态加载和释放页面，大幅降低内存占用。

效果展示¶

在线演示

API¶

函数	说明
`egui_view_viewpage_cache_init(self, core)`	初始化 ViewPageCache
`egui_view_viewpage_cache_init_with_params(self, core, params)`	使用参数初始化
`egui_view_viewpage_cache_set_child_total_cnt(self, cnt)`	设置总页面数
`egui_view_viewpage_cache_set_current_page(self, page_index)`	直接跳转到指定页
`egui_view_viewpage_cache_scroll_to_page(self, page_index)`	平滑滚动到指定页
`egui_view_viewpage_cache_set_on_page_changed_listener(self, listener)`	设置页面切换回调
`egui_view_viewpage_cache_set_on_page_load_listener(self, listener)`	设置页面加载回调
`egui_view_viewpage_cache_set_on_page_free_listener(self, listener)`	设置页面释放回调
`egui_view_viewpage_cache_set_size(self, width, height)`	设置容器大小
`egui_view_viewpage_cache_on_paged_free_all(self)`	释放所有缓存页面

参数宏¶

EGUI_VIEW_VIEWPAGE_CACHE_PARAMS_INIT(name, x, y, w, h);

回调函数签名¶

// 页面切换回调
typedef void (*egui_view_viewpage_cache_on_page_changed_listener_t)(
    egui_view_t *self, int current_page_index);

// 页面加载回调 - 返回创建的页面视图指针
typedef void *(*egui_view_viewpage_cache_on_page_load_listener_t)(
    egui_view_t *self, int current_page_index);

// 页面释放回调
typedef void (*egui_view_viewpage_cache_on_page_free_listener_t)(
    egui_view_t *self, int current_page_index, egui_view_t *page);

代码示例¶

static egui_view_viewpage_cache_t vp_cache;
static egui_view_label_t cached_pages[3];

EGUI_VIEW_VIEWPAGE_CACHE_PARAMS_INIT(vpc_params, 0, 0, 240, 200);

static void *on_page_load(egui_view_t *self, int page_index)
{
    int cache_idx = page_index % 3;
    egui_view_label_init(EGUI_VIEW_OF(&cached_pages[cache_idx]), core);
    egui_view_set_size(
        EGUI_VIEW_OF(&cached_pages[cache_idx]), 240, 200);
    egui_view_label_set_text(
        EGUI_VIEW_OF(&cached_pages[cache_idx]), "Cached Page");
    return &cached_pages[cache_idx];
}

static void on_page_free(egui_view_t *self, int page_index,
    egui_view_t *page)
{
    // 释放页面资源
}

void init_ui(egui_core_t *core)
{
    egui_view_viewpage_cache_init_with_params(
        EGUI_VIEW_OF(&vp_cache), core, &vpc_params);
    egui_view_viewpage_cache_set_child_total_cnt(
        EGUI_VIEW_OF(&vp_cache), 10);
    egui_view_viewpage_cache_set_on_page_load_listener(
        EGUI_VIEW_OF(&vp_cache), on_page_load);
    egui_view_viewpage_cache_set_on_page_free_listener(
        EGUI_VIEW_OF(&vp_cache), on_page_free);
    egui_view_viewpage_cache_set_current_page(
        EGUI_VIEW_OF(&vp_cache), 0);

    egui_core_add_user_root_view(core, EGUI_VIEW_OF(&vp_cache));
}

TileView¶

二维瓦片导航容器，子视图按行列网格排列，支持上下左右四方向滑动切换。适合智能手表等需要多方向导航的场景。

效果展示¶

在线演示

API¶

函数	说明
`egui_view_tileview_init(self, core)`	初始化 TileView
`egui_view_tileview_init_with_params(self, core, params)`	使用参数初始化
`egui_view_tileview_add_tile(self, tile_view, col, row)`	在指定行列添加瓦片
`egui_view_tileview_set_current(self, col, row)`	切换到指定行列的瓦片
`egui_view_tileview_set_on_changed(self, callback)`	设置瓦片切换回调

参数宏¶

EGUI_VIEW_TILEVIEW_PARAMS_INIT(name, x, y, w, h);

常量¶

常量	说明
`EGUI_VIEW_TILEVIEW_MAX_TILES`	最大瓦片数量(默认 9)
`EGUI_VIEW_TILEVIEW_SWIPE_THRESH`	滑动触发阈值(默认 20 像素)

代码示例¶

static egui_view_tileview_t tileview;
static egui_view_label_t tile_main, tile_right, tile_bottom;

EGUI_VIEW_TILEVIEW_PARAMS_INIT(tv_params, 0, 0, 240, 240);

static void on_tile_changed(egui_view_t *self,
    uint8_t col, uint8_t row)
{
    EGUI_LOG_INF("Tile: col=%d, row=%d\n", col, row);
}

void init_ui(egui_core_t *core)
{
    egui_view_tileview_init_with_params(
        EGUI_VIEW_OF(&tileview), core, &tv_params);

    egui_view_label_init(EGUI_VIEW_OF(&tile_main), core);
    egui_view_set_size(EGUI_VIEW_OF(&tile_main), 240, 240);
    egui_view_label_set_text(EGUI_VIEW_OF(&tile_main), "Main");

    egui_view_label_init(EGUI_VIEW_OF(&tile_right), core);
    egui_view_set_size(EGUI_VIEW_OF(&tile_right), 240, 240);
    egui_view_label_set_text(EGUI_VIEW_OF(&tile_right), "Right");

    egui_view_label_init(EGUI_VIEW_OF(&tile_bottom), core);
    egui_view_set_size(EGUI_VIEW_OF(&tile_bottom), 240, 240);
    egui_view_label_set_text(EGUI_VIEW_OF(&tile_bottom), "Bottom");

    // col=0,row=0: 主页; col=1,row=0: 右侧; col=0,row=1: 下方
    egui_view_tileview_add_tile(
        EGUI_VIEW_OF(&tileview), EGUI_VIEW_OF(&tile_main), 0, 0);
    egui_view_tileview_add_tile(
        EGUI_VIEW_OF(&tileview), EGUI_VIEW_OF(&tile_right), 1, 0);
    egui_view_tileview_add_tile(
        EGUI_VIEW_OF(&tileview), EGUI_VIEW_OF(&tile_bottom), 0, 1);

    egui_view_tileview_set_on_changed(
        EGUI_VIEW_OF(&tileview), on_tile_changed);
    egui_view_tileview_set_current(EGUI_VIEW_OF(&tileview), 0, 0);

    egui_core_add_user_root_view(core, EGUI_VIEW_OF(&tileview));
}