ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

从这里开始 · 支持全文搜索

框架概览

轻量到几 MB,快到原生合成。 纯头文件、零第三方依赖的 C++20 Windows 自绘 UI 框架,直接构建在 Direct2D 1.1 + DirectComposition 之上。 - 没有 Qt 的打包包袱,没有 Electron 的内存税。 几个头文件,include 即用;应用工程不链

易错点

> 这份文件把散落在代码注释、HANDOFF.md、TODO.md 里的“坑”集中到一处。接手/使用前先扫一遍。 > 优先级:易错 = 违反必踩;注意 = 契约/限制,违反易出问题;约定 = 库的取向;不要 = 明确不做。 --- 1. 链式构造 DSL(ZufyUIDsl.h) | | 状态 |

参考总览

> 本文档覆盖 ZufyUI 框架的全部公开 API,按“使用分类”组织(不是按代码/头文件顺序)。 > 配套阅读:[项目说明与构建](https://github.com/zhc9968/ZufyUI/blob/master/README.md)。 > 阅读方式:本文不是“签名清单”,而是按“它是

约定

颜色与标记 - 红色块:易错——真实踩坑、反直觉行为、会崩溃/UAF/竞争的用法,优先看。 - 橙色块:注意——线程、生命周期、绘制顺序等契约;不一定是错误,但违反后容易出问题。 - 绿色块:推荐——推荐写法、所有权模型、最佳实践。 - 普通项目符号表示普通语义、默认值或版本变化,不代表没有风险。

快速开始

最小程序 cpp include "ZufyUI.h" include "ZufyUIWidgets.h" using namespace ZufyUI; int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) { // Windows 子系

基础类型

Color cpp struct Color { float r, g, b, a; // 分量范围 [0,1],不是 0..255 Color(float r=0, float g=0, float b=0, float a=1.0f); static Color FromArgb(uint8t

事件与信号

何时用信号 - 控件对外通知(点击、选中、值变化)用内置 ZSignal。 - 自定义控件对外事件:自己声明 ZSignal 成员并 Fire。 ConnectionThread cpp enum class ConnectionThread { CurrentThread, NewThread,

语言

API 参考 / v1.29.1

约定

命名空间、单位、生命周期、版本与易错标注约定

下载 Markdown

颜色与标记

  • 红色块:易错——真实踩坑、反直觉行为、会崩溃/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) 关掉以省显存。
查看源文件docs/src/API.md