概念
PropertyGrid 是 Visual Studio 风格属性面板：
• Category：属性分类（可折叠）
• Property：单个属性项（名称 + 编辑器）
• Editor：文本/数字/布尔/颜色/枚举/文件路径等
• 选中：点击属性行高亮，编辑值
典型用途：游戏对象属性、控件样式编辑、配置面板。
API 速查
| 函数 | 说明 |
|---|---|
int xuiPropertyGridCreate(pCtx, ppW, pDesc) | 创建属性网格 |
int xuiPropertyGridAddCategory(pW, sId, sName, bExpanded) | 添加分类 |
int xuiPropertyGridAddProperty(pW, iCategory, pDesc) | 添加属性 |
int xuiPropertyGridSetCategoryExpanded(pW, iCat, bExpanded) | 展开/折叠 |
int xuiPropertyGridSetSelected(pW, iProperty) | 选中属性 |
int xuiPropertyGridSetValue(pW, iProperty, sValue) | 设置值 |
编译本章示例
gcc -O2 -I. -o ch184.exe ch184_main.c src\xui_*.c build\xge.lib -lm -lws2_32 -liphlpapi -lgdi32 -luser32 -lshell32 -lopengl32 -lole32 -lwinmm -lavrt
.\ch184.exe示例：对象属性面板
xui_property_grid_desc_t desc = { 0 };
xui_widget pGrid;
xuiPropertyGridCreate(pCtx, &pGrid, &desc);
// 添加 "Transform" 分类
int iTransform = xuiPropertyGridAddCategory(
pGrid, "transform", "Transform", 1);
// 添加属性
xui_property_desc_t prop = { 0 };
prop.sId = "pos_x";
prop.sName = "Position X";
prop.iEditorType = 1; // 数字编辑器
prop.sValue = "0.0";
xuiPropertyGridAddProperty(pGrid, iTransform, &prop);
prop.sId = "pos_y";
prop.sName = "Position Y";
xuiPropertyGridAddProperty(pGrid, iTransform, &prop);
// 颜色分类
int iAppearance = xuiPropertyGridAddCategory(
pGrid, "appearance", "Appearance", 1);
prop.sId = "color";
prop.sName = "Color";
prop.iEditorType = 4; // 颜色编辑器
prop.sValue = "#FF0000";
xuiPropertyGridAddProperty(pGrid, iAppearance, &prop);完整代码
将以下代码保存为 ch184_main.c，编译后运行即可看到 VS 风格属性面板：
#include "xge.h"
#include "xui.h"
static xui_context g_pCtx;
static int onFrame(void* pUser) {
(void)pUser;
xgeClear(0x252526FF);
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 = 400; d.iHeight = 600;
d.sTitle = "ch184 - PropertyGrid";
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, 400, 600);
// 创建属性网格
xui_property_grid_desc_t gdesc = { 0 };
xui_widget pGrid;
xuiPropertyGridCreate(g_pCtx, &pGrid, &gdesc);
// Transform 分类
int iTrans = xuiPropertyGridAddCategory(
pGrid, "transform", "Transform", 1);
xui_property_desc_t prop = { 0 };
prop.sId = "pos_x"; prop.sName = "Position X";
prop.iEditorType = 1; prop.sValue = "128.0";
xuiPropertyGridAddProperty(pGrid, iTrans, &prop);
prop.sId = "pos_y"; prop.sName = "Position Y";
prop.sValue = "64.0";
xuiPropertyGridAddProperty(pGrid, iTrans, &prop);
prop.sId = "rotation"; prop.sName = "Rotation";
prop.sValue = "45.0";
xuiPropertyGridAddProperty(pGrid, iTrans, &prop);
// Appearance 分类
int iAppear = xuiPropertyGridAddCategory(
pGrid, "appearance", "Appearance", 1);
prop.sId = "color"; prop.sName = "Color";
prop.iEditorType = 4; prop.sValue = "#FF6600";
xuiPropertyGridAddProperty(pGrid, iAppear, &prop);
prop.sId = "visible"; prop.sName = "Visible";
prop.iEditorType = 3; prop.sValue = "true";
xuiPropertyGridAddProperty(pGrid, iAppear, &prop);
xui_widget pRoot = xuiGetRootWidget(g_pCtx);
xuiWidgetAddChild(pRoot, pGrid);
xuiWidgetSetRect(pGrid, (xui_rect_t){0, 0, 400, 600});
xgeRun(onFrame, NULL);
xuiDestroy(g_pCtx);
xgeUnit();
return 0;
}代码讲解
- PropertyGridCreate：创建属性网格控件。
- AddCategory：添加可折叠分类，bExpanded=1 初始展开。
- AddProperty：向分类添加属性项，iEditorType 决定编辑器类型（1=数字 3=布尔 4=颜色）。
- sValue：所有值以字符串传递，编辑器内部解析。
要点与陷阱
- EditorType：决定属性编辑器类型（文本/数字/布尔/颜色/枚举）。
- Value 字符串：所有值以字符串传递，编辑器内部解析。
- Category 折叠：bExpanded=0 初始折叠，减少视觉噪音。
- 联动：选中对象变化时重建 PropertyGrid 内容。
进阶练习
- 场景对象检查器：选中场景节点，PropertyGrid 显示其属性。
- 撤销支持：属性修改时记录历史，Ctrl+Z 恢复。
