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,

语言

维护与参考 / v1.29.1

配图说明

下载 Markdown

原则:尽量不配图;能被文字讲清的(流程 / 结构 / 分层 / 映射)一律用文字,不画图。 只保留“必须看真实界面”的截图。

需要的图片(就这几张,够用)

图片(放 docs/images/) 位置 产出方式
quickstart.png README「快速开始」第 1 步 编译运行 screenshots.cpp(无参)截图
backdrop-mica.png README 第 2 步 screenshots.exe --mica 截图
custom-titlebar.png README 第 3 步 screenshots.exe --titlebar 截图
demo-main.png README「更多控件总览」 运行 demo 主示例程序首屏截图

这 4 张 README 里已有 ![]() 占位(旧图),同名覆盖即可,路径不用改。

可选(非必需,只是“长啥样”的展示;不加也不影响):

  • textedit.png ← demo「多行文本」页
  • charts-pie.png ← demo「饼图」页(一张代表三种图)

编译(把仓库根目录加进包含路径;系统库库内已自动链接):

cl /std:c++17 /EHsc /O2 /DUNICODE /D_UNICODE /SUBSYSTEM:WINDOWS screenshots.cpp user32.lib gdi32.lib

文字版“示意图”(想加就直接贴进对应章节,不用画图)

离屏缓存流水线(元素基类 · 缓存)

更新阶段(UI 线程):  UpdateAnimation ─▶ RefreshChildren ─▶ RequestRepaint(标脏 → pendingRepaint)
缓存预通道(主帧前):  DrawDirtyCaches ─▶ EnsureCache(尺寸变? 重建 bitmap) ─▶ elem->Draw 画进 cacheBitmap
合成(主帧):          RenderContent ─▶ blit 各元素 cacheBitmap

要点:只有“脏元素”重建位图,其余直接复用;UseCache()==false 的元素每帧直接 Draw,不走缓存。

数据视图两套坐标(数据视图)

源数组 items_[src](源行号,稳定)
        │  隐藏 / 筛选 / 排序(SetItemHidden / SetFilter / SortView)
        ▼
可见序 view_[vi](屏幕第几个)

互换:SourceOfVisible(vi) → src、VisibleOfSource(src) → vi。旧 API/信号用源行号;虚拟化/隐藏/筛选相关用可见序。

PageHost 过渡(布局 · PageHost)

视口   [ 源页 from 向左平移 ] [ 目标页 to 向右平移 ]
t: 0 ─────────────────────────────────────────────▶ 1

过渡期间 GetChildren() 同时返回“源页 + 目标页”;切换是异步的(动画结束才定);隐藏页缓存延迟释放。

背景叠层(窗口 · 外观)

[ 系统背景:空 / Acrylic / Mica ]  ← 最底
        ↑ 上面叠 DefaultBackdropColor(RGB + Alpha)
        ↑ 上面是 根内容(控件树)

自定义标题栏(窗口 · 标题栏)

Window 客户区
┌───────────────────────────────┐
│ 自定义标题栏(位置 (0,0),DrawBeforeLayout,不参与布局)│
├───────────────────────────────┤
│ 根内容(被下移 customTitleBarHeight)                  │
└───────────────────────────────┘

图表绘图区(图表 · ChartBase)

┌── arrangedRect ───────────────────────────────┐
│ 图例 legendRect                                │
│ 值轴刻度 │ plot_:数据 / 网格 / 参考线        │ vBar
│ (axisLeft)│                                    │
│           ├────────────────────────────────────┤
│           │ 类别标签                            │
└───────────┴────────────────────────────────────┘
              hBar

吸附轴:plot 滚出视口时,值轴/类别轴贴在视口边缘。面积填充基线 = ValueY(clamp(0, axisMin, axisMax))。

布局拉伸权值(布局系统)

ColumnBox:先量各子元素 base 高,剩余 = 总高 − Σbase,再按子元素权值分剩余。
SetFillHeight(true) 等价“该轴垂直权值 1”;SetHeight(x) 是固定 base,不等于权重。

调试通道(无障碍与调试通道)

调试器 ── WM_COPYDATA(dwData=命令号 1..22) ──▶ 目标窗口(需 SetDebugEnabled(true))
调试器 ◀── WM_COPYDATA(dwData=0x5A554631) ── 目标的隐藏 reply sink 窗口

发送侧要带超时(SendMessageTimeout,不加 SMTO_BLOCK),否则目标忙时会卡死调试器。库不读写文件,只返回当前帧信息。

查看源文件docs/diagrams/README.md