概念
Breadcrumb 水平排列路径节点：
• Item：每个节点有文本、可点击标志、关联值
• Separator：节点间分隔符（文本 "/" 或图标）
• Click：点击可跳转层级（最后一项通常不可点击）
• 常用于文件管理器地址栏、设置层级导航
API 速查
| 函数 | 说明 |
|---|---|
int xuiBreadcrumbCreate(xui_context pCtx, xui_widget* ppW, const xui_breadcrumb_desc_t* pDesc) | 创建面包屑 |
int xuiBreadcrumbAddItem(xui_widget pW, const char* sText, int bClickable, int iValue) | 添加项 |
int xuiBreadcrumbSetItems(xui_widget pW, const xui_breadcrumb_item_t* pItems, int iCount) | 批量设置 |
int xuiBreadcrumbClearItems(xui_widget pW) | 清空 |
int xuiBreadcrumbSetSeparator(xui_widget pW, const char* sSep) | 文本分隔符 |
int xuiBreadcrumbSetSeparatorIcon(xui_widget pW, xui_surface pSurf, xui_rect_t tSrc, float fSize) | 图标分隔符 |
int xuiBreadcrumbSetClick(xui_widget pW, onClick, void* pUser) | 点击回调 |
int xuiBreadcrumbSetTextColors(xui_widget pW, uint32_t iN, uint32_t iH, uint32_t iA, uint32_t iD) | 文本颜色 |
int xuiBreadcrumbSetMetrics(xui_widget pW, float fGap, float fPadX, float fPadY) | 间距 |
int xuiBreadcrumbGetHoverIndex(xui_widget pW) | 悬停索引 |
编译本章示例
gcc -O2 -I. -o ch153.exe ch153_main.c src\xui_*.c build\xge.lib -lm -lws2_32 -liphlpapi -lgdi32 -luser32 -lshell32 -lopengl32 -lole32 -lwinmm -lavrt
.\ch153.exe示例：文件路径导航
xui_breadcrumb_desc_t desc = { 0 };
xui_widget pCrumb;
xuiBreadcrumbCreate(pCtx, &pCrumb, &desc);
// 添加路径节点
xuiBreadcrumbAddItem(pCrumb, "C:", 1, 0);
xuiBreadcrumbAddItem(pCrumb, "Users", 1, 1);
xuiBreadcrumbAddItem(pCrumb, "Admin", 1, 2);
xuiBreadcrumbAddItem(pCrumb, "Desktop", 0, 3); // 当前目录不可点击
// 分隔符
xuiBreadcrumbSetSeparator(pCrumb, "›");
// 点击回调：导航到对应层级
xuiBreadcrumbSetClick(pCrumb, OnCrumbClick, NULL);
xuiWidgetAddChild(pToolbar, pCrumb);
static void OnCrumbClick(xui_widget pW, int iIndex, int iValue, void* pUser) {
// 截断路径到 iIndex 层级
NavigateToLevel(iValue);
}完整代码
将以下代码保存为 ch153_main.c，编译后运行即可看到面包屑导航效果：
#include "xge.h"
#include "xui.h"
#include <stdio.h>
static xui_context g_pCtx;
static void onCrumb(xui_widget pW, int iIdx, int iVal, void* p) {
(void)pW; (void)p;
printf("导航到层级 %d (value=%d)\n", iIdx, iVal);
}
static int onFrame(void* pUser) {
(void)pUser;
xgeClear(0x081114FF);
float mx, my;
xgeMouseGet(&mx, &my);
xuiInputPointerMove(g_pCtx, mx, my);
if (xgeMouseDown(XGE_MOUSE_LEFT))
xuiInputPointerDown(g_pCtx, 0);
else
xuiInputPointerUp(g_pCtx, 0);
xuiUpdate(g_pCtx, xgeGetDelta());
xuiLayout(g_pCtx);
xuiRender(g_pCtx, NULL, NULL, 0);
return XGE_OK;
}
int main(void) {
xge_desc_t d = { 0 };
d.iWidth = 800; d.iHeight = 600;
d.sTitle = "ch153 - Breadcrumb";
d.iFlags = XGE_INIT_VSYNC;
xgeInit(&d);
xuiCreate(&g_pCtx);
extern const xui_proxy_t tXgeProxy;
xui_proxy_t tXgeProxy = xuiProxyXge();
xuiSetProxy(g_pCtx, &tXgeProxy);
xuiSetViewportSize(g_pCtx, 800, 600);
xui_widget pRoot;
xuiWidgetCreate(g_pCtx, &pRoot);
xuiWidgetSetLayoutType(pRoot, XUI_LAYOUT_COLUMN);
xuiWidgetSetRect(pRoot, (xui_rect_t){0, 0, 800, 600});
xuiWidgetSetPadding(pRoot, 40, 40, 40, 40);
/* 间距：用内联样式或子控件布局参数设置 */
xuiSetRootWidget(g_pCtx, pRoot);
/* 创建面包屑 */
xui_breadcrumb_desc_t bd = { 0 };
xui_widget pCrumb;
xuiBreadcrumbCreate(g_pCtx, &pCrumb, &bd);
xuiBreadcrumbSetSeparator(pCrumb, "\xE2\x80\xBA");
xuiBreadcrumbSetClick(pCrumb, onCrumb, NULL);
xuiWidgetAddChild(pRoot, pCrumb);
/* 添加路径节点 */
xuiBreadcrumbAddItem(pCrumb, "C:", 1, 0);
xuiBreadcrumbAddItem(pCrumb, "Users", 1, 1);
xuiBreadcrumbAddItem(pCrumb, "Admin", 1, 2);
xuiBreadcrumbAddItem(pCrumb, "Desktop", 0, 3);
xgeRun(onFrame, NULL);
xuiDestroy(g_pCtx);
xgeUnit();
return 0;
}代码讲解
- AddItem(text, clickable, value)：最后一项 clickable=0 表示当前层级不可点击。
- Separator：设置文本分隔符“›”，也可用图标替代。
- Click 回调：点击某层级时触发，可截断路径导航到对应目录。
- ClearItems：路径变化时先清空再重建。
要点与陷阱
- bClickable：最后一项设为 0（当前层级不可点击）。
- iValue：关联值用于回调中识别点击了哪个层级。
- SeparatorIcon：优先于文本分隔符，适合使用箭头图标。
- ClearItems + AddItem：路径变化时先清空再重建。
- GetItemRect：获取每项矩形用于自定义 Tooltip。
进阶练习
- 文件管理器地址栏：双击目录进入，面包屑同步更新。
- 溢出省略：路径过长时中间项折叠为 "..." 下拉菜单。
