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

易错点总表

  • 颜色:Color 分量是 [0,1];整数用 Color::FromArgb。
  • 尺寸/布局:SetWidth/Height 是固定尺寸;SetFill* 是填满父轴;拉伸权值分配剩余空间(v1.17.0);图表默认权值 0,SetFill* 在父级有约束时生效、无约束时回退 420×260(v1.19.4)。
  • 窗口最小尺寸:含长文本/图表的窗口建议显式 SetMinSize,否则会被内容测量结果撑大。
  • 重绘:RequestRepaint() 只标脏、不排帧;不要试图在标脏处强制出帧(会持续重渲染卡顿)。InvalidateLayout() 冒泡,InvalidateLayoutSelf() 不冒泡(池化/虚拟 rebind 用)。
  • 缓存:默认开;每帧内容变化/实例极多的控件 SetUseCache(false);释放整棵子树用 ReleaseDeviceResourcesRecursive()。
  • 文本:SetTextFast 不重绘(池化专用);FontManager 返回的 layout/format 共享只读,勿改;GetFormat 的共享 format 是 ParagraphAlignment=CENTER,多行自绘要自己设 NEAR 或走 GetStyledLayout。
  • 信号:Fire 快照遍历、可安全 disconnect;Connection 析构不断开;DrawOverlay 必须按窗口过滤;别用捕获自身 shared_ptr 的 lambda 连自己;AddKeyHandler 的 handler 是快照调用,移除不取消当前轮。
  • 数据视图:源行号 vs 可见序两套坐标;SortItems 重排并清多选,SortView 只改可见序;parent 是 weak_ptr;行背景用 node->bgColor;SetFilter/SetViewComparator 会保存 lambda;行高必须 >0。
  • 多行编辑:AcceptsTab 为真时 Tab 是缩进;富文本只读;换行宽度变化重建全部行 layout。
  • 滚动条:宿主用 ShrunkWidthRatio 预留槽位;空闲缩小是惰性的。
  • Drawer:SetContent 是主内容、SetPanel 是抽屉面板;SetPanelSize 是外框且默认 16px padding 会扣内容;Permanent 下 Close 无效;Scrim 只在 Overlay+Modal 生效,SetScrimOpacity(0) 仍拦点击。
  • 窗口周边:Window 没有尺寸/DPI 变化信号;StatusBar::AddPanel 没有点击回调;任务栏 COM 失败静默,FLASHW_CAPTION 对自绘标题栏无效。
  • 无障碍/调试:角色决定暴露的 UIA Pattern;调试命令发送要带超时。
  • DSL(ZufyUIDsl.h,可选):root() 收任意 Layout 子类;add() 按容器真实接口分派(GridLayout 必须用 .cell(row,col,child) 或 dsl::Cell(...));空元素(nullptr / 空 Ref)一律被忽略;with() 只接成员函数指针,多步逻辑用 apply(lambda);WindowApp::run() 会 Show()(Window::Create 不显示窗口),隐藏启动用 .hidden()。
查看源文件docs/src/API.md