概念
StepBar 是多步流程导航/指示：
• Steps：步骤标题数组
• Current：当前步骤索引
• Style：箭头形 / 圆点形
• 三态颜色：Done（已完成）/ Active（当前）/ Pending（未到）
• Metrics：条高度、圆点半径、连接线宽度
API 速查
| 函数 | 说明 |
|---|---|
int xuiStepBarCreate(xui_context pCtx, xui_widget* ppW, const xui_step_bar_desc_t* pDesc) | 创建步骤条 |
int xuiStepBarSetSteps(xui_widget pW, const char* const* ppTitles, int iCount) | 设置步骤 |
int xuiStepBarSetTitle(xui_widget pW, int iIndex, const char* sTitle) | 修改标题 |
int xuiStepBarSetCurrent(xui_widget pW, int iCurrent) | 当前步骤 |
int xuiStepBarGetCurrent(xui_widget pW) | 获取当前 |
int xuiStepBarSetStyle(xui_widget pW, int iStyle) | 样式 |
int xuiStepBarSetColors(xui_widget pW, uint32_t iDone, uint32_t iActive, uint32_t iPending, uint32_t iLine) | 颜色 |
int xuiStepBarSetTextColors(xui_widget pW, uint32_t iText, uint32_t iActiveText, uint32_t iPendingText) | 文本颜色 |
int xuiStepBarSetMetrics(xui_widget pW, float fBarHeight, float fDotRadius, float fLineWidth) | 尺寸 |
编译本章示例
gcc -O2 -I. -o ch172.exe ch172_main.c src\xui_*.c build\xge.lib -lm -lws2_32 -liphlpapi -lgdi32 -luser32 -lshell32 -lopengl32 -lole32 -lwinmm -lavrt
.\ch172.exe示例：安装向导
xui_step_bar_desc_t desc = { 0 };
xui_widget pStepBar;
xuiStepBarCreate(pCtx, &pStepBar, &desc);
// 步骤标题
const char* steps[] = {
"欢迎", "许可协议", "安装路径", "安装中", "完成"
};
xuiStepBarSetSteps(pStepBar, steps, 5);
xuiStepBarSetCurrent(pStepBar, 0);
xuiStepBarSetStyle(pStepBar, 0); // 箭头
// 颜色
xuiStepBarSetColors(pStepBar,
0x4FD8C2FF, 0xFFB454FF, 0x444444FF, 0x333333FF);
// 下一步
void OnNextClick(void) {
int cur = xuiStepBarGetCurrent(pStepBar);
if (cur < 4)
xuiStepBarSetCurrent(pStepBar, cur + 1);
}完整代码
将以下代码保存为 ch172_main.c，编译后运行即可看到 StepBar 步骤条效果：
#include "xge.h"
#include "xui.h"
static xui_context g_pCtx;
static xui_widget g_pStepBar;
static void OnNextClick(xui_widget pW, int iValue, void* pUser) {
(void)pW; (void)iValue; (void)pUser;
int cur = xuiStepBarGetCurrent(g_pStepBar);
if (cur < 4)
xuiStepBarSetCurrent(g_pStepBar, cur + 1);
}
static int onFrame(void* pUser) {
(void)pUser;
xgeClear(0x081114FF);
xui_vec2_t pos; xgeMouseGet(&pos.x, &pos.y);
xuiInputPointerMove(g_pCtx, pos.x, pos.y);
if (xgeMouseDown(XGE_MOUSE_LEFT)) xuiInputPointerDown(g_pCtx, pos.x, pos.y, 0);
else xuiInputPointerUp(g_pCtx, pos.x, pos.y, 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 = "ch172 - StepBar";
d.iFlags = XGE_INIT_VSYNC;
xgeInit(&d);
xuiCreate(&g_pCtx);
/* XGE 官方代理由 xuiProxyXge() 提供 */
xui_proxy_t tXgeProxy = xuiProxyXge();
xuiSetProxy(g_pCtx, &tXgeProxy);
xuiSetViewportSize(g_pCtx, 800, 600);
xui_widget pRoot;
xuiPanelCreate(g_pCtx, &pRoot, NULL);
xuiWidgetSetRect(pRoot, (xui_rect_t){0, 0, 800, 600});
/* 步骤条 */
xui_step_bar_desc_t sbDesc = {0};
xuiStepBarCreate(g_pCtx, &g_pStepBar, &sbDesc);
xuiWidgetSetRect(g_pStepBar, (xui_rect_t){0, 0, 600, 40});
xuiWidgetSetRect(g_pStepBar, (xui_rect_t){100, 200, 600, 40});
const char* steps[] = {
"欢迎", "许可协议", "安装路径", "安装中", "完成"
};
xuiStepBarSetSteps(g_pStepBar, steps, 5);
xuiStepBarSetCurrent(g_pStepBar, 0);
xuiStepBarSetStyle(g_pStepBar, 0);
xuiStepBarSetColors(g_pStepBar,
0x4FD8C2FF, 0xFFB454FF, 0x444444FF, 0x333333FF);
xuiWidgetAddChild(pRoot, g_pStepBar);
/* 下一步按钮 */
xui_widget pBtn;
xuiButtonCreate(g_pCtx, &pBtn, NULL);
xuiWidgetSetRect(pBtn, (xui_rect_t){0, 0, 120, 36});
xuiWidgetSetRect(pBtn, (xui_rect_t){340, 350, 120, 36});
xuiButtonSetText(pBtn, "下一步");
xuiButtonSetClick(pBtn, OnNextClick, NULL);
xuiWidgetAddChild(pRoot, pBtn);
xgeRun(onFrame, NULL);
xuiDestroy(g_pCtx);
xgeUnit();
return 0;
}代码讲解
- xuiStepBarCreate：创建步骤条控件。
- SetSteps：传入 5 个步骤标题字符串。
- SetStyle(0)：箭头形样式，适合向导流程。
- SetColors：Done=绿, Active=橙, Pending=灰, Line=深灰。
- 按钮驱动：StepBar 本身不响应点击，通过外部按钮切换步骤。
要点与陷阱
- Style：0=箭头形（适合向导），1=圆点形（适合进度指示）。
- Current：索引从 0 开始，超出范围无效。
- 三态：索引 < Current 为 Done，== Current 为 Active，> 为 Pending。
- 只读：StepBar 本身不响应点击，需外部按钮驱动步骤切换。
进阶练习
- 可点击步骤：圆点样式 + 点击已完成步骤回跳。
- 垂直步骤条：侧边栏显示流程进度。
