## 颜色与标记 - **红色块**:`易错`——真实踩坑、反直觉行为、会崩溃/UAF/竞争的用法,优先看。 - **橙色块**:`注意`——线程、生命周期、绘制顺序等契约;不一定是错误,但违反后容易出问题。 - **绿色块**:`推荐`——推荐写法、所有权模型、最佳实践。 - 普通项目符号表示普通语义、默认值或版本变化,不代表没有风险。 ## 命名空间与头文件 - 所有内容位于 `namespace ZufyUI`。 - 头文件**按使用分层**: - `ZufyUI.h`:核心——类型 / 信号槽 / 字体 / 元素基类 / 布局 / 菜单 / 窗口。 - `ZufyUIAcrylic.h`:手写 DComp 合成效果 + 官方亚克力/云母配方(由 `ZufyUI.h` 包含)。 - `ZufyUIWidgets.h`:基础控件(Label/Button/TextBox/TextEdit/ComboBox/…/ScrollViewer/TabView/图标…),内部 `#include "ZufyUI.h"`。 - `ZDataViewer.h`:数据视图(ListView/TableView/TreeView),依赖前两者。 - `ZufyUICharts.h`:**图表(BarChart/LineChart/PieChart)**,依赖 `ZufyUI.h`。 - `ZufyUIImages.h`:`Image` / `ImageManager`(图片加载与设备缓存)。 - `ZufyUIIcons.h`:`FontIcon` 字形控件(`Icon` 枚举本身在 `ZufyUIWidgets.h`)。 - `ZufyUIWindowTool.h`:窗口周边(标题栏 / MessageBox / 托盘 / 系统对话框 / 无障碍提供程序 / 调试通道);**自 v1.20.0 起自身包含 `ZufyUIWidgets.h`**,可单独包含;末尾包含 `ZufyUIHwndView.h`。 - `ZufyUIHwndView.h`:原生 HWND 宿主 `HwndView`(WebView2 / 摄像头 / 第三方 / 进程外窗口)。 - `ZufyUIDragDrop.h`:拖放(由 `ZufyUI.h` 末尾包含)。 - `ZufyUIDsl.h`:可选**链式构造 DSL**(纯附加,不修改任何现有控件)。 - 全部是**纯头文件**;`#pragma comment(lib, ...)` 会自动链接 `d2d1 / dwrite / dwmapi / imm32 / winmm`。 - **源码编码**:含中文的 `.h` / `.cpp` 必须存为 **UTF-8 带 BOM**(否则 MSVC 按本地代码页解析,报 `C2143/C2259/C2888/C4819`);`.md` / `.tex` 存为 **UTF-8 无 BOM**。需要无 BOM / 纯 ASCII 副本时,用 `tools/export_ascii.py` 生成 `dist/ascii`(不提交;详见 README「纯 ASCII 导出」)。 ## 单位 - 所有坐标与尺寸都是 **DIP**(设备无关像素),不是物理像素。 - 框架在绘制前用内部 `Snap()` 吸附到物理像素网格;你写代码时**不需要**自己做 DPI 换算。 - 鼠标事件坐标也是 DIP。屏幕坐标只在系统 API(`Create`、`ShowAt`、`FileDialog`)里出现。 ###block_red_start **易错** ###block_red_end ## 对象模型与生命周期 - 控件一律 `std::shared_ptr<T>` 拥有,用 `std::make_shared<T>()` 创建。 - 通过布局/容器的 `AddChild()` 挂到父容器;父容器保存子元素的 `shared_ptr`,**父容器存活期间子元素不会释放**。 - 脱离布局后若没有其它 `shared_ptr`,元素即回收;元素析构会自动释放自身离屏缓存与已注册连接(内部 `ConnectionGroup`)。 ###block_green_start **推荐的所有权模型** 控件由 `std::shared_ptr` 拥有;父容器通过 `AddChild` 持有子元素。跨层引用用裸指针或 `weak_ptr`,不要反向持有父容器的 `shared_ptr`,也不要让两个容器同时拥有同一个控件。 ###block_green_end ###block_red_start **易错** - `UIElement::SetParent` 存的是**裸指针**(非拥有);所有权永远在容器/`Application` 的 `shared_ptr` 上。窗口在元素里只以 **window id** 记录,避免窗口先销毁导致 UAF。 ###block_red_end ## 信号与事件 - 用 `Connect(signal, slot)` 绑定,返回 `Connection`,默认随宿主元素析构自动断开。 - 槽可以是任意可调用对象(lambda / 函数指针 / `std::function`)。 ###block_red_start **易错** - 不要用“按值捕获宿主自身 `shared_ptr`”的 lambda 连接宿主自己的信号 → 引用环,整棵子树泄漏。详见「事件与信号」章。 ###block_red_end ## 默认值体系 - 每个控件有 `inline static` 的 `Default*` 静态字段(如 `Button::DefaultSize`)。 - `static SetDefault*()` 修改后**只影响之后新建的实例**;实例级 setter 只影响该实例。 ###block_red_start **易错** - 静态默认字段是**进程全局**的;多窗口若需要不同观感,请在创建前设置或逐实例 setter。 ###block_red_end ## 禁用、焦点、缓存三个通用概念(贯穿所有控件) - **启用/禁用**:`UIElement::SetEnabled(false)` 让该元素及子树不可交互(鼠标/键盘被拦截),控件需自己用 `IsEffectivelyEnabled()` 决定是否画灰。**禁用不改变布局**(仍占位)。`SetEnabled(false)` ≠ `SetVisible(false)`。 - **焦点**:只有 `IsFocusable()` 为 true 的元素能拿键盘焦点。窗口按 Tab 遍历聚焦元素;焦点环只在“通过 Tab 获得焦点”时显示,鼠标点击焦点不显示。 - **离屏缓存**:见「元素基类」的“缓存机制”。默认开启;动画频繁/实例极多的控件用 `SetUseCache(false)` 关掉以省显存。
约定
命名空间、单位、生命周期、版本与易错标注约定
颜色与标记
- 红色块:
易错——真实踩坑、反直觉行为、会崩溃/UAF/竞争的用法,优先看。 - 橙色块:
注意——线程、生命周期、绘制顺序等契约;不一定是错误,但违反后容易出问题。 - 绿色块:
推荐——推荐写法、所有权模型、最佳实践。 - 普通项目符号表示普通语义、默认值或版本变化,不代表没有风险。
命名空间与头文件
- 所有内容位于
namespace ZufyUI。 - 头文件按使用分层:
ZufyUI.h:核心——类型 / 信号槽 / 字体 / 元素基类 / 布局 / 菜单 / 窗口。ZufyUIAcrylic.h:手写 DComp 合成效果 + 官方亚克力/云母配方(由ZufyUI.h包含)。ZufyUIWidgets.h:基础控件(Label/Button/TextBox/TextEdit/ComboBox/…/ScrollViewer/TabView/图标…),内部#include "ZufyUI.h"。ZDataViewer.h:数据视图(ListView/TableView/TreeView),依赖前两者。ZufyUICharts.h:图表(BarChart/LineChart/PieChart),依赖ZufyUI.h。ZufyUIImages.h:Image/ImageManager(图片加载与设备缓存)。ZufyUIIcons.h:FontIcon字形控件(Icon枚举本身在ZufyUIWidgets.h)。ZufyUIWindowTool.h:窗口周边(标题栏 / MessageBox / 托盘 / 系统对话框 / 无障碍提供程序 / 调试通道);自 v1.20.0 起自身包含ZufyUIWidgets.h,可单独包含;末尾包含ZufyUIHwndView.h。ZufyUIHwndView.h:原生 HWND 宿主HwndView(WebView2 / 摄像头 / 第三方 / 进程外窗口)。ZufyUIDragDrop.h:拖放(由ZufyUI.h末尾包含)。ZufyUIDsl.h:可选链式构造 DSL(纯附加,不修改任何现有控件)。- 全部是纯头文件;
#pragma comment(lib, ...)会自动链接d2d1 / dwrite / dwmapi / imm32 / winmm。 - 源码编码:含中文的
.h/.cpp必须存为 UTF-8 带 BOM(否则 MSVC 按本地代码页解析,报C2143/C2259/C2888/C4819);.md/.tex存为 UTF-8 无 BOM。需要无 BOM / 纯 ASCII 副本时,用tools/export_ascii.py生成dist/ascii(不提交;详见 README「纯 ASCII 导出」)。
单位
- 所有坐标与尺寸都是 DIP(设备无关像素),不是物理像素。
- 框架在绘制前用内部
Snap()吸附到物理像素网格;你写代码时不需要自己做 DPI 换算。 - 鼠标事件坐标也是 DIP。屏幕坐标只在系统 API(
Create、ShowAt、FileDialog)里出现。
易错
对象模型与生命周期
- 控件一律
std::shared_ptr<T>拥有,用std::make_shared<T>()创建。 - 通过布局/容器的
AddChild()挂到父容器;父容器保存子元素的shared_ptr,父容器存活期间子元素不会释放。 - 脱离布局后若没有其它
shared_ptr,元素即回收;元素析构会自动释放自身离屏缓存与已注册连接(内部ConnectionGroup)。
推荐的所有权模型
控件由 std::shared_ptr 拥有;父容器通过 AddChild 持有子元素。跨层引用用裸指针或 weak_ptr,不要反向持有父容器的 shared_ptr,也不要让两个容器同时拥有同一个控件。
易错
UIElement::SetParent存的是裸指针(非拥有);所有权永远在容器/Application的shared_ptr上。窗口在元素里只以 window id 记录,避免窗口先销毁导致 UAF。
信号与事件
- 用
Connect(signal, slot)绑定,返回Connection,默认随宿主元素析构自动断开。 - 槽可以是任意可调用对象(lambda / 函数指针 /
std::function)。
易错
- 不要用“按值捕获宿主自身
shared_ptr”的 lambda 连接宿主自己的信号 → 引用环,整棵子树泄漏。详见「事件与信号」章。
默认值体系
- 每个控件有
inline static的Default*静态字段(如Button::DefaultSize)。 static SetDefault*()修改后只影响之后新建的实例;实例级 setter 只影响该实例。
易错
- 静态默认字段是进程全局的;多窗口若需要不同观感,请在创建前设置或逐实例 setter。
禁用、焦点、缓存三个通用概念(贯穿所有控件)
- 启用/禁用:
UIElement::SetEnabled(false)让该元素及子树不可交互(鼠标/键盘被拦截),控件需自己用IsEffectivelyEnabled()决定是否画灰。禁用不改变布局(仍占位)。SetEnabled(false)≠SetVisible(false)。 - 焦点:只有
IsFocusable()为 true 的元素能拿键盘焦点。窗口按 Tab 遍历聚焦元素;焦点环只在“通过 Tab 获得焦点”时显示,鼠标点击焦点不显示。 - 离屏缓存:见「元素基类」的“缓存机制”。默认开启;动画频繁/实例极多的控件用
SetUseCache(false)关掉以省显存。