颜色与标记
- 红色块:
易错——真实踩坑、反直觉行为、会崩溃/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)关掉以省显存。