它解决什么

MFC 做复杂皮肤时，很多地方要自己画，改样式成本高。纯手写 XML 又没有预览，属性名也不好记。XUI 把这两件事分开：

• 结构、布局、颜色、图片、字体放在 .DuiProj 里，由设计器维护。
• 窗口生命周期、控件查找、点击和定时器放在 C++ 类里，写法接近 MFC 的 DDX 和消息映射。
• 控件本身没有 HWND。绘制和输入都由所属窗口代理。

所以它既是界面库，也带一套可以直接拿来写程序的部件：线程池、文件、网络、监听、拖拽、命令行、磁吸、DPI、字符串。这些在 MMHelper 里，不依赖控件树。

目录

仓库按库、工具、示例和预编译库分开。应用工程通常同时依赖 XUI 和 MMHelper。头文件入口是 XUI/XUIHead.h，它会继续包含 MMHelper/MMHelperHead.h。

分层

上层只使用下层暴露的类和宏。XML 和绘制细节留在框架内部。

应用窗体（继承 CDUIWnd / CDUINotifyPump）
        |
消息映射、控件查找、业务通知
        |
CDUIWnd：窗口、焦点、捕获、绘制表面、定时器
        |
控件树：CDUIControlBase 及其子类
        |
属性 CDUIPropertyObject + CDUIAttribute*
资源：字体 / 颜色 / 图片
        |
CDUIGlobal + CDUIFactory + CDUIXmlPack
        |
MMHelper + 绘制后端（Win32 为 GDI/GDI+，SDL 平台为 SDL）

窗口实现按平台分开：DUIWndWin32 和 DUIWndSDL，对外仍是 CDUIWnd。

编译开关

导出宏在 XUIHead.h：

MMHelper 使用同一套约定：MMHELPER_DLL / MMHELPLIB。

Win32 与 SDL

开关在 MMHelper/DuiPlatformSDL.props。属性 DuiPlatformSDL 默认是 false，也就是不定义 DuiPlatform_SDL，走 Win32，不需要 SDL3。改成 true 才会定义 DuiPlatform_SDL 并链接 SDL3。

Linux、macOS、Android 用 CMake，选项 XUI_PLATFORM_SDL 打开后同样定义 DuiPlatform_SDL。这三端需要 SDL3。Windows 上发布 Demo 用的是 Visual Studio 的 Win32 配置，见 新建应用。

最小流程

主示例 Demo/XUIDemo_C++/XUIDemo_C++/XUIDemo_C++.cpp 就是最小闭环。桌面端入口如下：

CDUIGlobal::GetInstance()->Init(hInstance);
CDUIGlobal::GetInstance()->LoadProjectFromFile(
    _T("../XUIDemo_C++.DuiProj/XUIDemo_C++.DuiProj"));
CMMDpi::SetProcessDPIAwareness(
    enMMPROCESS_DPI_AWARENESS::MMPROCESS_PER_MONITOR_DPI_AWARE);

CDlgDemo DlgDemo;
DlgDemo.Create(NULL, _T("XUIDemo"), DUI_WNDSTYLE_FRAME, DUI_WNDSTYLE_EX_FRAME);
DlgDemo.DoModal();

CDUIGlobal::GetInstance()->UnInit();

1. Init 保存实例，准备绘制、线程池和 DPI。
2. LoadProjectFromFile 读入整个 UI 工程：皮肤、字体、颜色、属性表、控件 ID、各个界面 XML。
3. CDlgDemo 构造时把界面名设为 "DlgMain"。这个名字对应工程里的一条界面记录。
4. Create 创建窗口，按界面名把 XML 实例化成控件树。
5. DoModal 进入模态消息循环。DoBlock 是另一种阻塞循环，Demo 的 DPI 窗口用的就是它。
6. UnInit 关闭工程并释放全局资源。

工程也可以不放在磁盘目录里：

加载失败时用 GetDuiLastError() 取最后一条错误文本。Android 上 Demo 会先把 assets 里的 DuiProj 拷到内部存储，再调用 LoadProjectFromFile。程序从可执行文件的上一级打开 ../XUIDemo_C++.DuiProj/XUIDemo_C++.DuiProj。

窗口

CDUIWnd 同时是可设计对象、动画窗口和通知泵。它上面维护根控件、捕获、焦点、悬停、按控件 ID 索引的表、单选分组、绘制表面、Tooltip、插入符和定时器。

样式宏在 DUIExport/DefineBase.h：

• DUI_WNDSTYLE_FRAME：重叠窗口
• DUI_WNDSTYLE_DIALOG：弹出对话框
• DUI_WNDSTYLE_CHILD：子窗口
• DUI_WNDSTYLE_EX_FRAME / DUI_WNDSTYLE_EX_DIALOG：对应扩展样式

标题栏、关闭按钮、圆角背景由 XML 里的控件自己画。系统样式只决定窗口种类。未进入消息映射的窗口消息可以重写 OnWndMessage。Demo 用它接收托盘消息和 DPI 窗口句柄。

消息映射

输入先进入 CDUIWnd。框架做命中测试后，把鼠标、键盘、定时器转换成 DuiNotify，再交给 CDUINotifyPump。映射宏在 DUIExport/DefineMessage.h。

DuiBegin_Message_Map(CDlgDemo, CDUIWnd)
    Dui_On_Notify_Ctrl(DuiNotify_Timer, IDC_TabViewControls, OnTimerTabViewControls)
DuiEnd_Message_Map()

处理函数签名统一为 void Member(const DuiNotify &Notify)。Notify.wParam、Notify.lParam、Notify.pNotifyCtrl 携带上下文。定时器 ID 在 wParam 里。

常见通知：DuiNotify_WndInited、DuiNotify_WndLayout、DuiNotify_DpiChanged、DuiNotify_Click、DuiNotify_TextChanged、DuiNotify_SelectChanged、DuiNotify_ItemClick、DuiNotify_WndManagerAttach、DuiNotify_WndManagerDetach。

控件绑定

设计器为每个控件生成数字 ID，写在工程的 ResourceCtrlID.h。窗体类在 OnFindControl 里用 Dui_DDX_Control 绑定成员。这个宏会 FindControl 并做接口查询。

void CDlgDemo::OnFindControl()
{
    __super::OnFindControl();
    Dui_DDX_Control(CDUIContainerCtrl, m_pTabViewControls, IDC_TabViewControls)
    Dui_DDX_Control(CDUIRadioBoxCtrl, m_pRadioViewHomePageCtrl, IDC_RadioBoxHomePage)
}

OnInitDialog 适合做创建后的一次性逻辑：把子页面挂到逻辑类、创建托盘、居中、设置默认选中项。

一块窗口，多块逻辑

大窗口不要把所有逻辑堆在一个对话框类里。Demo 的做法是：

1. XML 里用 TabLayout 或 VerticalLayout 划出一块容器。
2. 另写一个继承 CDUINotifyPump 的视图类。
3. 在 OnInitDialog 里 FindSubControl 找到这块容器，调用视图类的 Attach。
4. Attach 内部 GetWndOwner()->AddINotify(this)，同一套消息映射就可以写在视图类里。

析构时要 RemoveINotify，避免窗口还在派发通知。

控件

所有可视对象都从 CDUIControlBase 派生，而它又是 CDUIPropertyObject。类名同时是 XML 节点名，工厂按这个字符串创建对象。

CDUIPropertyObject
    └── CDUIControlBase
            ├── CDUIStaticCtrl / CDUIButtonCtrl / CDUIEditCtrl / ...
            └── CDUIContainerCtrl
                    ├── CDUIHorizontalLayoutCtrl / CDUIVerticalLayoutCtrl
                    ├── CDUITabLayoutCtrl
                    ├── CDUIListViewCtrl / CDUITreeViewCtrl
                    └── CDUIGroupCtrl / ...

每个控件都有背景色、渐变、背景图、圆角、边框、自定义 Bitmap、Clone 和 SetParent。静态文本用 SetAutoCalcWidth / SetAutoCalcHeight 按文字收缩。容器用同名接口按子控件收缩。

布局

位置由 CDUIAttributePosition 描述。每个控件相对父容器声明水平和垂直对齐，再加偏移、固定宽高和最小最大尺寸。

SetFloat 让控件脱离自动流，再用 SetAbsoluteRect 按绝对矩形摆放。父容器排布时调用 GetAbsoluteRect 得到子控件矩形。DPI 变化后，内边距可以选择是否跟随缩放。

列表视图类型是：

enum enDuiListViewType
{
    ListView_List,
    ListView_TileH,
    ListView_TileV,
};

调用 CDUIListViewCtrl::SwitchListViewType 切换。网格效果由平铺模式和项尺寸组合出来。

属性

设计器和 XML 能编辑的字段，都是 CDUIAttributeObject 的子类，挂在 CDUIPropertyObject 的属性组里。

属性值多数不直接写死在控件 XML 里，而是存一个 ValueID。真正的值在工程级 Attribute.xml 中按哈希去重。多个控件可以共享同一套圆角、字体或颜色，改一处即可作用于全部引用。

富文本允许一段文字拆成不同字体和颜色，并支持多行以及左、右、上、下、居中对齐。

资源、换肤、DPI

三类资源

CDUIGlobal 启动后维护三张表：字体 CDUIFontBase、颜色 CDUIColorBase、图片 CDUIImageBase。图片包括 PNG、JPEG、GIF、WebP、SVG。绘制支持九宫格、圆角和平铺。

换肤

颜色和图片属性可以保存一组资源名。PerformSwitchRes(nIndex) 切换当前皮肤序号，GetSwitchResIndex 读取当前序号。ColorSwitch 按这个序号取对应颜色。Demo 里的写法：

int nSkin = (CDUIGlobal::GetInstance()->GetSwitchResIndex() + 1) % 2;
CDUIGlobal::GetInstance()->PerformSwitchRes(nSkin);

换肤索引是全局的。一个进程里已加载的界面共享这个序号。资源增删改可以通过 IDuiResourceCallBack 观察。

DPI

进程级用 CMMDpi::SetProcessDPIAwareness，Demo 使用 Per-Monitor。界面级用 CDUIGlobal::SetDpi / SetScale，以及窗口自己的同名方法。SetScale(100) 表示 100%，内部按 96 DPI 换算。全局 SetDpi 会同步已经打开的窗口。只想缩放某一个窗口时，调用该 CDUIWnd 自己的 SetDpi / SetScale。

绘制与动画

CDUIWnd 维护一张后台位图。控件的 OnPaint 在裁剪区内把背景、边框、文字和前景画上去，再贴到窗口。分层透明由窗口属性 WndLayered 和 WndAlpha 控制。Win32 下 GdiplusRenderText、GdiplusRenderImage 决定文字和图片走 GDI 还是 GDI+。

动画分三处：

• 窗口属性里的入场动画：类型、帧数、帧间隔。
• CDUIAnimation::StartAnimation：通用帧动画，回调开始、步进和结束。
• 控件级拖动动画：水平、垂直或双向，用于列表换位、组合框展开。

水波纹数据挂在控件的涟漪位图上，由 CDUIWaterCtrl 和基类配合完成。

DuiProj

一个界面工程是一个目录，入口文件扩展名是 .DuiProj。Demo 的入口是 XUIDemo_C++.DuiProj，内容是资源索引：

<Version Version="5"/>
<SkinRes SkinFile="SkinRes.xml"/>
<FontRes FontFile="FontRes.xml" Default="微软雅黑-字号:12-..."/>
<ColorRes ColorFile="ColorRes.xml"/>
<Attribute AttributeFile="Attribute.xml"/>
<ResourceCtrlID CtrlIDFile="ResourceCtrlID.h"/>
<DirectUI DuiName="DlgMain" DuiType="0" DuiFile="Dlg/DlgMain.xml"/>

界面 XML 的根是窗口类名，子节点是控件类名。属性节点带 NameID、ValueID 或内联 Value。日常用设计器改界面，它会同时维护 XML、Attribute.xml 和 ResourceCtrlID.h。

运行时动态插入一块界面：

CDUIControlBase *pCtrl = CDUIGlobal::GetInstance()->LoadDui(_T("ComboxView1"), pWnd);

列表项模板应 Clone 后再插入，这样每一行是独立实例。Clone 默认会刷新控件 ID。若要保持原 ID，把刷新参数设为 false。

自定义控件

CDUIFactory 按类名字符串创建控件、资源和属性。XML 解析到 <CDUIButtonCtrl> 时，工厂调用对应的创建函数。

1. 继承最接近的基类，一般是 CDUIControlBase 或某个布局控件。
2. 头文件写 DuiDeclare_CreateControl(CMyCtrl)。
3. 源文件写 DuiImplement_CreateControl(CMyCtrl)，并在 InitProperty 里注册自己的属性组。
4. 加载 XML 之前调用 DuiRegisterCreateControl(CMyCtrl)。

设计器要识别自定义控件，需要在带设计器宏的库工程里提供控件描述。普通应用工程不必定义这个宏。XML 节点名必须和注册的类名一致，否则创建失败，整段子树加载不出来。

IDuiControlCallBack 用来在不改控件类的情况下监听绘制、尺寸、可见性和释放。

MMHelper

MMHelper 不依赖控件树。XUI 和普通 Win32 程序都能用。CDUIGlobal 自己持有线程池，界面线程和后台任务可以通过服务消息通信。

Demo 里的托盘使用 CMMTrayIcon，鼠标消息以自定义窗口消息回到 OnWndMessage。命令行使用 CMMCommandLine，用来区分主 Demo 和 DPI 预览进程。

新建应用

Windows

用 Visual Studio 打开 XUI.2017.sln，配置选 Release_Unicode | Win32，先编出库。DLL 会拷到仓库的 bin（XUI.2017.dll、MMHelper.2017.dll）。保持 DuiPlatformSDL 为 false，这一端不需要 SDL3。

再打开 Demo/XUIDemo_C++/XUIDemo_C++.sln，配置选 Release | Win32，确认示例能跑起来。新工程照它的包含目录和库目录来：包含 XUIHead.h，运行目录能找到对应 DLL。字符集使用 Unicode。头文件里已经写了公共控件 6.0 的 manifest。

Linux、macOS、Android

这三端打开 XUI_PLATFORM_SDL，需要 SDL3。Linux 在 WSL 里直接编译本机仓库，macOS 用 CMake 生成 App，Android 用 Gradle 打 APK。各端命令和打包步骤在 平台 Demo。

最小窗体

class CMainWnd : public CDUIWnd
{
    DuiDeclare_Message_Map()
public:
    CMainWnd() : CDUIWnd(_T("DlgMain")) {}
protected:
    CDUIButtonCtrl *m_pClose = NULL;
    void OnFindControl() override
    {
        __super::OnFindControl();
        Dui_DDX_Control(CDUIButtonCtrl, m_pClose, IDC_BtnClose)
    }
    void OnClickClose(const DuiNotify &)
    {
        Close(IDOK);
    }
};

DuiBegin_Message_Map(CMainWnd, CDUIWnd)
    Dui_On_Click_Ctrl(IDC_BtnClose, OnClickClose)
DuiEnd_Message_Map()

IDC_BtnClose 必须来自设计器生成的 ResourceCtrlID.h，并且 XML 里该按钮的 ID 与宏一致。入口顺序与 最小流程 相同。

发布与设计器

界面资源怎么带上

开发时用目录形式的 .DuiProj，方便设计器来回保存。发布可以：

1. 把整个工程目录放在可执行文件旁边，继续 LoadProjectFromFile。可执行文件在 Release/ 里时，DuiProj 目录要放在它的上一级。
2. 打成 zip，LoadProjectFromZip。
3. 把 zip 放进程序资源，LoadProjectFromResZip。

图片文件在 SkinRes/。SkinRes.xml 只记录资源名到文件名的映射。

设计器

设计器单独提供，绑定 Visual Studio 的解决方案后可以：

• 像 MFC 一样生成窗体类、控件变量和消息映射。
• 拖放、对齐，改属性立即看到结果。
• 集中查看图片、字体、颜色。
• 控件树里用 Shift + Up / Down 调整 Z 序。
• 按一级、二级、三级编辑菜单。
• 支持 Ctrl + C / V / Z / Y，也能把界面复制到另一个视图。
• 注册开发者自定义控件，并预览各 DPI。

手写 XML 可以跑通框架，但属性哈希和控件 ID 很容易和 Attribute.xml、ResourceCtrlID.h 对不上。新界面在设计器里做，C++ 只处理绑定之后的行为。设计器安装包在页面顶部的「下载设计器」。

示例与注意

读 Demo/XUIDemo_C++ 时，先看 .DuiProj 里的 DuiName，再在 C++ 里搜同名构造，就能把 XML 和类对上。

Demo/FlowSheet 是流程类小示例。Demo/Scratch 是更小的启动样例。

写代码时注意

• 控件由框架创建，延迟删除走窗口的删除队列。不要在通知回调里直接 delete 正在派发事件的控件。
• FindControl 依赖 InitControls 建立的 ID 表。动态插入后要让控件进入当前窗口。
• 消息映射函数必须是 CDUINotifyPump 派生类的成员，控件 ID 用编译期常量。
• 换肤索引是进程全局的。只缩放一个窗口时，调用该窗口自己的 SetScale。

入口与支持

接口和示例以仓库为准。使用问题进 QQ 群。