概念
Progress 是只读进度指示控件：
• Range + Value：Min/Max 范围 + 当前值
• Rate：自动计算 0~1 比率
• TextTemplate：如 "{0}%" 自动替换为百分比
• FillDirection：左→右 / 右→左 / 上→下 / 下→上
• NinePatch：轨道和填充使用九宫格贴图
API 速查
| 函数 | 说明 |
|---|---|
int xuiProgressCreate(xui_context pCtx, xui_widget* ppW, const xui_progress_desc_t* pDesc) | 创建进度条 |
int xuiProgressSetRange(xui_widget pW, float fMin, float fMax) | 范围 |
int xuiProgressSetValue(xui_widget pW, float fValue) | 当前值 |
float xuiProgressGetRate(xui_widget pW) | 获取比率 |
int xuiProgressSetTextTemplate(xui_widget pW, const char* sTemplate) | 文本模板 |
int xuiProgressSetFillDirection(xui_widget pW, int iDir) | 填充方向 |
int xuiProgressSetColors(xui_widget pW, uint32_t iTrack, uint32_t iFill) | 颜色 |
int xuiProgressSetTextColor(xui_widget pW, uint32_t iColor) | 文本颜色 |
int xuiProgressSetFillTextColor(xui_widget pW, uint32_t iColor) | 填充区文本色 |
int xuiProgressSetTrackPatch(xui_widget pW, const xui_nine_patch_t* pPatch) | 轨道九宫格 |
int xuiProgressSetFillPatch(xui_widget pW, const xui_nine_patch_t* pPatch) | 填充九宫格 |
编译本章示例
gcc -O2 -I. -o ch171.exe ch171_main.c src\xui_*.c build\xge.lib -lm -lws2_32 -liphlpapi -lgdi32 -luser32 -lshell32 -lopengl32 -lole32 -lwinmm -lavrt
.\ch171.exe示例：文件下载进度
xui_progress_desc_t desc = { 0 };
xui_widget pProgress;
xuiProgressCreate(pCtx, &pProgress, &desc);
xuiProgressSetRange(pProgress, 0.0f, 100.0f);
xuiProgressSetValue(pProgress, 0.0f);
xuiProgressSetTextTemplate(pProgress, "{0}%");
xuiProgressSetColors(pProgress, 0x2A2A2AFF, 0x4FD8C2FF);
xuiProgressSetFillDirection(pProgress, 0); // 左→右
// 下载回调中更新
void OnDownloadProgress(float fPercent) {
xuiProgressSetValue(pProgress, fPercent);
}
xuiWidgetAddChild(pPanel, pProgress);完整代码
将以下代码保存为 ch171_main.c，编译后运行即可看到 Progress 进度条效果：
#include "xge.h"
#include "xui.h"
static xui_context g_pCtx;
static xui_widget g_pProgress;
static float g_fVal = 0.0f;
static int onFrame(void* pUser) {
(void)pUser;
xgeClear(0x081114FF);
/* 模拟下载进度 */
g_fVal += 0.3f;
if (g_fVal > 100.0f) g_fVal = 0.0f;
xuiProgressSetValue(g_pProgress, g_fVal);
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 = "ch171 - Progress";
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_progress_desc_t pgDesc = {0};
xuiProgressCreate(g_pCtx, &g_pProgress, &pgDesc);
xuiWidgetSetRect(g_pProgress, (xui_rect_t){0, 0, 400, 24});
xuiWidgetSetRect(g_pProgress, (xui_rect_t){200, 280, 400, 24});
xuiProgressSetRange(g_pProgress, 0.0f, 100.0f);
xuiProgressSetValue(g_pProgress, 0.0f);
xuiProgressSetTextTemplate(g_pProgress, "{0}%");
xuiProgressSetColors(g_pProgress, 0x2A2A2AFF, 0x4FD8C2FF);
xuiWidgetAddChild(pRoot, g_pProgress);
xgeRun(onFrame, NULL);
xuiDestroy(g_pCtx);
xgeUnit();
return 0;
}代码讲解
- xuiProgressCreate：创建进度条控件（只读展示）。
- SetTextTemplate("{0}%")：自动将百分比显示在进度条上。
- SetColors：轨道深色 + 填充主题色。
- 帧循环更新：每帧递增进度值，模拟下载过程。
- FillDirection：默认左→右填充，可改为其他方向。
要点与陷阱
- TextTemplate："{0}" 替换为百分比整数，"{1}" 替换为当前值。
- FillTextColor：填充区域内文本颜色（与外部文本色区分）。
- NinePatch：使用贴图时 Colors 被忽略。
- 只读：Progress 不响应用户交互，仅展示。
进阶练习
- 多段进度：多个 Progress 堆叠显示不同阶段。
- 不确定进度：动画循环填充表示"加载中"状态。
