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

版本摘要

v1.15.0 → v1.29.1

下载 Markdown

只列对你写代码有影响的显著变化。

  • v1.15.0:数据视图虚拟化(SetItemCount 等)+ 隐藏/筛选/可见序排序(源行号 vs 可见序两套坐标);跨线程/锁语义收口;ComboBox 源索引 API;TreeView::BeginUpdate/SetNodeText。
  • v1.17.0:UIA 无障碍(默认开);外部调试/自动化通道(SetDebugEnabled,默认关,命令 1~22);布局拉伸权值(ColumnBox/RowBox/GridLayout 按权值分配剩余空间);省略文本自动 ToolTip(Label/Button);CaptionButton::Kind::Pin;TreeView 节点 bgColor/Get/SetScrollOffsetY/ScrollToNode;Window::DefaultBackdropColor 默认纯白。
  • v1.18.0:
    • 新增 ZufyUICharts.h:ChartBase / BarChart / LineChart / PieChart;BarChart 补全横向方向;PieChart 滚轮缩放。
    • 新增 TextEdit 多行编辑器 / 只读查看器;TextRun;基类新增 AcceptsTab()。
    • UIElement::ReleaseDeviceResourcesRecursive();PageHost 隐藏页缓存延迟释放(约 1.2s);ScrollViewer::UseCache()=false;SetUseCache(false) 立即释放位图。
    • 库层修复:Snap 的 DPI 上下文在 UI 线程也设置;ZSignal::Fire RAII 异常安全;TextBox shift+点击语义;Slider 0 宽 NaN 守卫;ListView 池宽度变化重测(poolW_)。
  • v1.19.0:
    • 新增拖放(ZufyUIDragDrop.h):Window::BeginDrag + DragDataBuilder;元素 SetDropTargetEnabled/OnDragEnter/Over/Leave/Drop + 信号;Label/Button/TextBox/TextEdit/ComboBox 支持拖入/拖出;跨应用文件拖出。
    • 新增 Expander(可折叠卡片:smoothstep 缓动 + 箭头旋转 + 标题悬停高亮)、SettingsList(设置行列表);图片展示用 Label::SetImage + SetImageFit(等比缩放至完整可见)。
    • ComboBox 下拉箭头改为随展开旋转的 chevron。
    • 文本拖动为移动语义:源端先删原选区再按落点插入(同控件用私有格式去重)。
  • v1.19.1:
    • TextEdit 撤销/重做改为标准方案(栈顶=当前态):撤销/重做都还原当时的选区与光标;Backspace/Delete/输入/粘贴各一步;拖放插入/移动均可撤销、可重做。
    • ScrollViewer:内容改按视口宽度测量(修复 FillWidth/换行内容期望宽度无穷大导致的“卡片被裁剪”与滚动范围错乱);内容两遍测量(出现竖滚动条后按变窄宽度重量);尊重内容元素自身的 margin;裁剪四周留 1px 出血,避免内容边缘边框被切掉一半。
    • 拖放落点光标在目标未聚焦时也显示;拖动期间保留源选区并在落点显示预览光标;落点落在原选区内 → 不变更。
    • Expander:标题条悬停高亮(不再遮挡卡片边框)、箭头随折叠缓动旋转、SetIcon 标题图标。
    • 整窗拖放:Window::SetDropTargetEnabled + 窗口级 DragEnter/DragOver/DragLeave/Drop。
    • 图片展示并入 Label(新增 SetImageFit),移除独立的 ImageView。
  • v1.19.2:
    • 新增顶部菜单栏 MenuBar(VS 风格:点击弹 Menu;悬停仅高亮不自动展开;菜单打开期间条目保持按下、关闭复原;默认叠在自定义标题栏上、空白处放行以便拖动标题栏)。
    • 新增底部状态栏 StatusBar(左右面板:可选图标 + 文本)。
    • Window:SetMenuBar / SetStatusBar / SetMenuBarInTitleBar / SetShowTitleText(标题文字与标题栏上的菜单互斥)。
    • Menu 新增 onClosed 回调;MenuWindow::OnPopupClosed。
  • v1.19.3:
    • 新增主题系统(ThemeRole / Theme / ThemeManager;Light/Dark/HighContrast;窗口级 SetTheme;UIZSignals::ThemeChanged/ThemeReapply)——按角色统一配色;切页/切标签自动重套可见子树。
    • 跟随系统:读注册表深/浅色 + 系统强调色,处理 WM_SETTINGCHANGE/WM_THEMECHANGED/WM_DWMCOLORIZATIONCOLORCHANGED/WM_SYSCOLORCHANGE;ThemeManager::SetFollowSystem(bool)。
    • 实例显式色优先:控件被显式 Set*Color 后标记“用户设色”,主题不再覆盖;ListView 单项 / TableView 单格与富格 / TreeView 单元格 / 表头 / 交叉行 / Tab 选中与悬停 / 单选框 / NumberBox 悬停 / CheckBox 悬停等全部接入主题。
    • Backdrop 令牌(窗口基色白/黑);窗口周边(标题栏三件套)跟随系统主题;ThemeManager::Map 色差重映射。
    • 修复:ThemeReapply 连接未断开的 UAF;SyncThemeBackdrop 吞用户 tint;ListView/TableView/TreeView 主题覆盖单项色。
  • v1.19.4:
    • 新增 DSL(ZufyUIDsl.h):Ref<T>(with/on/add + 布局快捷)、Make<T>、Col/Row/Grid 与各控件短工厂——链式构造 / 组子树 / 连信号;demo 新增「DSL」页压测。
    • 修复:CheckBox 构造写死 width_/height_ → 带标签时在 RowBox/ColumnBox 里被当固定宽度、标签被裁。
    • ListView/TableView 的 RefreshChildren 缓存判据改为单一签名 ChildrenSig()(判据集中一处,防将来漏加);与 TreeView 一致。
    • ChartBase::MeasureOverride:fill 但无约束/未设尺寸时回退 420×260(不再塌成 0)。
    • Window::SetMinSize 默认内容测量给 600 DIP 宽度下限;pch.h 的 ZufyUI_DEBUG 改为 #ifdef _DEBUG;Theme::HighContrast 语义色区分(不再全黄)。
  • v1.19.5:
    • DSL 增强:dsl::App() / WindowApp 窗口构建器(链式配置 + run());Page()/Menu()/Settings() 短工厂;SFINAE 门控的控件专属糖(text/checked/value/placeholder/padding/category/series/slice/item/menu)。
    • demo「DSL」页用上糖与图表组合(Pie().slice(...)、Bar().category(...).series(...)、Progress().value(...))。
  • v1.19.6:
    • 修复:ListView 按钮模式下勾选框命中位置少偏移 4px(与绘制/子元素左边界对齐)。
    • 修复:Label::MeasureOverride 的 Wrap 分支漏算内联子控件宽度(带 AddChild 的换行 Label 文本会挤压/溢出)。
    • 文档:版本号改为单一来源(API.md/README.md 顶部引用 ZufyUI.h 宏,生成器 mdapi2html.py 注入 1.29.1);清理过时项(ImageView 默认值行、Sort→SortItems、Menu::onClosed、图表 fill 说明、README 菜单 +90MB 历史条目);mdapi2html.py 修正 --theme auto 语义与 c++ 类语言名正则。
  • v1.19.7:
    • 修复:ChartBase 横/纵滚动条占位写反(viewW 用竖条、viewH 用横条)→ 最右/最底滚不到;NumberBox 滚轮焦点判断(焦点在内部 TextBox);lastActiveAnimElements_ 悬垂(析构时从动画集合擦除,防随机崩溃);Menu::ShowAt 非 shared_ptr 时抛 bad_weak_ptr;ChildrenSig 缺 EnsureView;TreeView::SetDefaultExpandDepth 对 AddRoot/AddChild 不生效。
    • 修复:ColumnBox/RowBox spacing 按“参与布局的子元素数”算;GridLayout 行列数过滤不可见元素;Label 换行漏算子控件宽度 / 多算一个间距;ListView/TableView 释放 Label 前清 childrenView_、补释放池化/富项/单元格 Label;Window::defaultIMC_ 改 ImmAssociateContext;DragData::GetFiles 缓冲 len+1;TextEdit 清选区补发 SelectionChanged;MessageBox 默认标题本地化。
    • 新增 TODO.md(合并原 FEATURE_PLAN.md/OPTIMIZATION_PLAN.md,唯一权威待办清单)。
  • v1.20.0:
    • DSL:root() 改为接受任意 Layout 子类(原先只有 Col 有专门重载,Row/Grid 会因「Ref → shared_ptr<Layout> 需要两次用户定义转换」而编译失败);titleBar/menuBar/statusBar 同样可直接收 Ref<T>。
    • DSL:add() 按容器的真实接口分派(ColumnBox/RowBox/Label → AddChild;PageHost → AddPage,非 Page 实参跳过;GridLayout 改走坐标 API)。新增 dsl::Cell(row,col,child[,rowSpan,colSpan]) 与 Ref::cell、apply() 逃生口、Wrap()。
    • DSL:补齐快捷——尺寸上下限(minWidth/minHeight/maxWidth/maxHeight/minSize/maxSize)、拉伸权重(weight/hWeight/vWeight)、cache/bleed/clipRect/noClip/cursor/dropTarget/contextMenuEnabled/accessible、spacing(Col/Row 单参、GridLayout 双参)、padding(Thickness)、background/textColor、align(GridLayout);控件糖新增 image/imageFit/items/rows/cols/header/cell/root(s)/separator/submenu;工厂新增 RadioGroup()/ScrollBar()/Glyph()(Image 是资源对象而非 UIElement,故不做工厂,走 Label::SetImage 糖)。
    • DSL:WindowApp::run() 补上 Show()——Window::Create 本身不显示窗口,原实现会跑一个没有窗口的消息循环(表现为卡死);新增 hidden/minSize/position/frameRateLimit/theme/useAppTheme/dropTarget/icon/titleBarVisible/showTitleText/menuBarInTitleBar 与窗口信号 on<&Window::Closed>(Window 的信号是裸成员、没有 Connect);WindowApp 改为可移动(内部改持 unique_ptr<Window>,因为 Window 自身既不可拷贝也不可移动)。
    • 修复:ColumnBox/RowBox/GridLayout::AddChild 补空值守卫——DSL 的 variadic 转发可能送来 nullptr,原实现会解引用空指针。
    • 修复:ZufyUIWindowTool.h 自身不完整——它用到 Label/Button/ColumnBox::AddChild 却未 include ZufyUIWidgets.h,一直依赖调用方先包含(pch.h 恰好是这个顺序);已补上,该头现在可单独包含。
    • 工程:新增 tools/build.ps1(一键:构建前自动补 BOM → 杀占用进程 → 构建 demo + ZufyUIDebugger → 跑自检)、tools/ensure_bom.ps1(只对「含非 ASCII 且缺 BOM」的 C++ 源文件补 BOM,顺带挡下 GBK 误解析导致的 C2143/C2259/C2888/C4819)、tests/zufyui_tests.cpp + tools/run_tests.ps1(47 项编译期/运行期断言,不创建窗口,可在命令行 / CI 直接跑)。
  • v1.21.0:
    • 修复:Card 悬停闪出蓝色边框——主题套用器给卡片设了 SetHoverBorderColor(Accent),而卡片本没有这个行为;已移除(悬停仍改背景色)。
    • 修复:ProgressBar 拉伸后内填充圆角与外框对不上——轨道、裁剪几何、边框三处用的仍是成员 height_(初始高度),只有填充用了实际高度;三处统一为 arrangedRect_.height / 2。
    • 修复:Button 文案有空间却被省略号裁掉——MeasureOverride 直接返回恒定 width_(构造时 DefaultWidth=120);改为按文案撑开(max(width_, 文案宽 + 2*padding)),新增 Button::AutoSizeToText(静态,默认 true)与 SetAutoSizeToText(false)。这是布局行为变更。
    • 新增:ToggleSwitch 改时长驱动 ease-in-out 缓动(DefaultAnimationDuration=0.25s,到点精确结束);修鼠标点击/键盘路径绕过 SetOn 导致动画不启动(表现为"瞬间开关")。
    • 新增:ProgressBar 数值缓动(DefaultValueAnimDuration=0.22s,填充条与百分比文字同步);同版本修 ProgressBar 悬停/数值在长空闲后一帧跳到位的观感问题(动画一律时长驱动)。
    • 新增:SplitView 折叠能力——拖到边缘阈值内先出"即将折叠"覆盖层(半透明强调色 + 方向箭头,alpha 渐入渐出,不改内容),松手才折叠(尺寸带缓动到 0);折叠后该侧显示小按钮(画在内容之上,圆角浅灰 + 指向展开方向的箭头 + 悬停缓动),点击后带缓动展开到最小极限值;SetCollapseEnabled(false) 可整体关闭。公开 API:SetCollapseEnabled/IsCollapseEnabled/SetCollapseThreshold/CollapseFirst/CollapseSecond/Expand/IsFirstCollapsed/IsSecondCollapsed/GetCollapsedSide/IsCollapsing/GetCollapseProgress/SetExpandButtonColors/SetExpandButtonSize + 信号 CollapsedChanged(int)。
    • 新增:detail::EaseOutCubic / detail::EaseInOutCubic(时长驱动缓动,库内动画统一口径)。
    • 新增:ThemeRole::Shadow(追加在枚举末尾,避免改动既有枚举值)+ 浅色/深色/高对比度取值;UIElement::DefaultShadowColor/SetDefaultShadowColor;Window::SetBackdrop(Backdrop) 跟随主题(带 tint 的重载表示锁定)+ ApplyThemeToBackdropParams 钩子。
    • 修复:PieChart Ctrl+滚轮缩放无效——PieChart 自己的 zoom_ 遮蔽了 ChartBase::zoom_(委派基类只改基类那份);现由饼图自己处理 Ctrl 并走 SetZoom。语义明确为 Ctrl+滚轮 = 缩放 / 普通滚轮 = 只平移。
    • 修复:图表滚轮平移"画面不动"——平移路径缺 SyncScrollPositions()(只改了 scrollX_/scrollY_,未重算 baseX_/baseY_)。
    • 修复:ColumnBox 会把没有显式宽度的子元素按可用宽度摆(横向不吃拉伸权值)→ 文档补充"想让卡片按内容收窄要放进 Row";SettingsList 被放进 Card 自带 GridLayout(自动列给 FLT_MAX)时会退化成 0 宽 → 文档补充正确用法(SetLayout(Col(...)) + SetFillWidth(true))。
    • 工程:tests/zufyui_tests.cpp 62 → 85 项断言(新增本批修复的回归断言:按钮自动撑宽/可关闭、Label 宽度跟随文本、进度条与开关缓动收敛、SplitView 折叠与展开到最小状态)。
  • v1.22.0(含破坏性 API 变更):
    • 修复:MessageBox(及一切模态框)首次点击穿透到后面的主窗口——模态若在 Window::OnMouseUp 的槽里弹出,该函数末尾的 ReleaseCapture() 要等模态循环结束才执行 → 整段模态期间主窗口仍持 SetCapture,系统把鼠标消息优先给捕获窗口;Window::RunModal 现于进入循环前 if (GetCapture()) ReleaseCapture();。
    • 修复:ScrollViewer 滚动链——滚到顶/底后不再吞掉滚轮(该方向不能再滚则返回 false 沿父链冒泡),外层页面可继续滚动。
    • 修复:SplitView 展开无缓动 + 小按钮跳侧——旧 Expand() 在动画开始前就清掉折叠标志,而 PaneLengths 正靠它做插值 → 尺寸瞬跳;改用贯穿折叠/展开的 collapseSide_,动画收尾才清零;按钮位置/箭头也按其判断。
    • 破坏性 · P0-1:带默认参数的成员函数拆成无默认参数的重载(让 .with() 可用):TreeView::SetCheckable(bool) + SetCheckableShallow(bool);SetNodeCheckable(node,bool) + SetNodeCheckableRecursive;SetNodeEnabled(node,bool) + SetNodeEnabledRecursive;SetNodeCheckState(node,state) + SetNodeCheckStateFull(...,updateChildren,updateParent);ListView::AddItem(text) 与富项 AddItemWidget(shared_ptr<Label>)(原名弃用);RadioGroup::AddItem / AddItemSelected / AddButton / AddButtonSelected;Menu::AddCheckItem(text,checked) / AddCheckItemCb / AddCheckItemRadio。
    • 新增 · P0-2:同名 dsl 工厂的无歧义别名 make_slider/make_card/make_page/make_menu/make_menu_bar/make_status_bar/make_radio_group/make_scroll_bar/make_expander(避开 using namespace 同时命中两类时的 C2872)。
    • 新增 · P1-2:Page::SetScrollableContent(content)——一行把整页内容套进 ScrollViewer + 边距。
    • 新增 · P1-4:ThemeManager::RegisterHook / RegisterSubtreeApplier 返回 RAII HookHandle(析构自动断开);库内部固定钩子改用 RegisterHookPermanent / RegisterSubtreeApplierPermanent。
    • 文档 · P3:新增 docs/pitfalls.md(易错点总表);AGENTS.md 增补「链式构造 / API 约定」。
  • v1.22.1:
    • 修复(布局):RowBox / ColumnBox 的 ArrangeOverride 里子元素 base 未先夹到 min/max → 带 SetMinWidth/Height 的子元素会把多余空间错误地分给拉伸兄弟,导致整行/列溢出容器(典型:标签 SetMinWidth + 滑条 SetFillWidth → 滑条超长、越出卡片)。现 base = clamp(base, min, max) 后再算 leftover。
    • 行为:ColumnBox / RowBox / GridLayout 不再“缩小”内容——空间不足即溢出,交由外层 ScrollViewer 滚动(桌面 UI 不压缩内容)。GridLayout 移除了行高/列宽不足时的等比压缩。
    • 修复(对齐):GridLayout 的 SetHorizontalAlignment/SetVerticalAlignment 此前因判据 colStretchWeights.empty() 恒为空而永不生效;改为判“全为 0”,Center/End 现在生效(仅在无列/行拉伸权值时)。
    • 修复(文本/IME):TextBox / TextEdit 合并 UTF-16 代理对(emoji/超 BMP)后整段插入;光标 ←/→、Backspace、Delete 跨整对。失焦时控件清自身组合态,Window 统一取消 IME 组合(ResetImeState())——程序/控件两侧输入法状态一起复位。TextBox::SetImeEnabled(false) 也清组合态。
    • 修复(无障碍):GetAutomationIdOrAuto() 自动编号改为每窗口计数(Window::NextAccessibleAutoId()),多窗口/多根不再撞号;ElementProviderFromPoint 先子后父下潜到最深命中后代(Label 内嵌控件也能拿到)。
    • 修复:数据视图 ListView/TableView/TreeView 的项/单元格摆放 bleedY 由固定 3.0f 改为读元素自身 GetBleed()(阴影/出血不再被切);indicatorY_ 初始化改为 -1,首帧选中指示条直接就位。
    • 修复(外观):焦点框颜色改用 ThemeRole::FocusRing、圆角改用 Theme::cornerRadius(原硬编码蓝 + 固定 4);WM_NCHITTEST 里自定义标题栏按钮优先于缩放边框(最大化按钮角落不再被 HTTOPRIGHT 抢走 → Win11 Snap Layouts 可弹)。
    • 工程:pch.h 不再包含本库头(改库头不再整份重建 PCH);新增 UIElement::MarkUserColor() 统一 40+ 处“用户设色”标记;删除死代码 ListView::FindEnabledFrom。
    • 文档:docs/pitfalls.md / AGENTS.md 持续维护。
  • v1.23.0:
    • 新增 · ZufyUIHwndView.h(HwndView):原生 HWND 内容宿主。主窗口是 NRB+DComp(子 HWND 不合成),故用顶层 owned 弹窗作宿主;SetContentHwnd 把外部窗口 SetParent 成宿主的 WS_CHILD(可跨进程)并显式显示。宿主移动时子窗口由系统一起走;裁剪 = 宿主客户区 + SetWindowRgn(元素矩形 ∩ 主窗口 ∩ 祖先 GetClipRect,含 ScrollViewer 视口)。支持 SetObscured、SetOnBoundsChanged、SetFill*。
    • 新增 · Window 外部视觉挂载:CreateExternalVisual()(WinRT ContainerVisual,插根视觉最上层,供 WebView2 put_RootVisualTarget)、SetExternalVisualBounds(DIP→物理像素)、RemoveExternalVisual;AddOverlaySync/RemoveOverlaySync/SyncOverlays(浮窗统一同步)。
    • 性能:浮窗同步改为窗口级单点(WM_MOVE/WM_SIZE/WM_DPICHANGED 立即同步 + 共享 16ms 兜底),去掉每实例定时器;缓存 DPI/客户区;跳过冗余 SetWindowPos、按变化带 SWP_NOSIZE/NOMOVE;demo 全色图静态部分缓存 DIB。
    • 修复 · NumberBox:空文本错误态在文本恢复为合法数值时清除;ResetToDefault 在通知应用后强制清错误;步进/清除按钮改为按下即触发(不再用会变化的矩形二次判定,修复点 × 后仍红)。
    • 修复 · 数据视图填充:ListView/TableView/TreeView 的 MeasureOverride 认 SetFillWidth/SetFillHeight(与图表一致),不再固定返回默认 200/400。
    • demo:新增「原生HWND」页(GDI 全色图 + Card/Grid/Column/ScrollViewer 多布局 + 进程外 --outproc 生产者窗口托管)。
  • v1.23.1:
    • 修复(布局 / 命中):PageHost::MeasureOverride 测量所有页面。此前 PageHost 只 Arrange 页面,而 Page::Arrange 仅在尺寸变化时补测 → 页面内元素由隐藏变可见(如选下拉后 SetVisible(true) 的 Expander 卡片)不会重测,新元素 arrangedRect 为 0(无边框、HitTest 点不到),直到窗口尺寸变化才恢复。未变脏的页面命中 Measure 缓存,不增加重复测量。
  • v1.23.2:
    • 构建:ZufyUI.vcxproj / ZufyUIDebugger.vcxproj 的 Debug|Win32 / Debug|x64 补 /bigobj(Release 已有);全量 Release/Debug 构建通过。
  • v1.23.3:
    • Button:内部 Label 成为真正的子元素(富文本 GetLabel()->AddChild / SetContent);新增右侧下拉区 SplitClicked / SetSplitMenu / SetSplitButton。
    • 修复(下拉菜单位置):GetDpiScale() 返回 96/144(不是 1.0/1.5);旧乘法会把菜单送到屏幕右下角。除以 96 后菜单会落在按钮下方,demo 不再弹 MessageBox。
    • 修复:SetBackdrop(Acrylic/Mica) 在未显式设 tint 时不再用不透明白盖住系统材质;ListView::SetItemHeight 夹到 ≥1px,Draw/命中不再除零。
    • 文档/清理:HwndView 跨进程风险说明;WM_ACTIVATE 冗余判断、<cstring>、demo 空回调清理。
  • v1.24.0(含破坏性变更):
    • 信号生命周期:ConnectionState::alive 改为原子;Connection::disconnect / 接收者析构会逻辑取消已排队的 UIThread / NewThread 任务;Fire 与信号析构并发明确为 UB。
    • 接收者上下文:UIElement / Window 继承 ConnectionOwner,elem->Connect(...) / Connect(elem, ...) / sig.connect(elem, ...) 自动随接收者断开;新增自由 Connect 与 ConnectWeak。
    • 破坏性:ZSignal 不可拷贝/移动;成员函数指针改用 Connect(elem, sig, &Class::Method) / ConnectWeak;elem->Connect(sig, &Class::Method) 不再支持。
    • 注意:Menu / MenuItem / Timer 仍用 signal.connect,不自动断开;信号参数按左值传递。
  • v1.25.0:
    • 新增 · Drawer:左/右/上/下 × Overlay / Push / Permanent;圆角遮罩、面板圆角/边框/外侧阴影、Esc/点外部关闭。
    • 新增 · Window::AddKeyHandler / RemoveKeyHandler:临时窗口级键处理器。
    • 改进:ScrollViewer 裁剪出血跟随内容 GetBleed();测试改名 zufyui_tests,新增信号专项与 Drawer 测试(213 项)。
  • v1.29.1:修复 PageHost EaseOut 反向进度、动画期间命中变换和动画中删页索引;OnPointerCancel 已接入 WM_CANCELMODE/WM_CAPTURECHANGED(OLE 拖出豁免);菜单等非标准窗口恢复 Opening/Opened。
  • v1.29.0:指针/焦点/输入反馈(光标状态、拖动取消、TextBox 焦点样式/光标/密码眼睛、ComboBox 键盘、Slider 松手、数据视图/滚动条/Expander 指针);窗口过渡动画 SetTransitionDurations/PresentationState/DefaultWindowSetup;菜单回调 QueueToUIThread、PageHost 反向导航;Expander/SettingsList/图表字体继承、MenuBar/Button/EnsureVisible 修正;API 文档乱码与第 8 章标题修复。
  • v1.28.0:非阻塞 Present / 高刷新帧节拍(SetNonBlockingPresent / SetDisplayFramePacing / GetDisplayRefreshHz);私有 IDWriteFontCollection;UIA 根/子 provider 统一断开、WM_DESTROY 清理 UIA 事件映射;菜单默认同步提示策略。
  • v1.27.3:窗口弹出行为。Placement(居中 owner/屏幕)、FollowOwner、MoveBounds(owner 客户区/显示器工作区)、CloseReason、RequestClose/ForceClose 与关闭拦截信号;SetMovable/SetCloseEnabled/SetCloseOnEscape;自定义标题栏按钮随窗口策略同步;弹窗首帧预推进。
  • v1.27.2:
    • 窗口裸指针/UIA 生命周期:Window::ForgetElement 统一注销焦点/按下/捕获/悬停/tooltip/待重绘/UIA provider;SetParent 脱离时提前注销,UiaDisconnectProvider 修复 CFG 崩溃。
    • TreeView::SetStretchLastColumn(默认开)末列补宽;SplitView 按钮方向/禁用态、全页面滑动切换与折叠钳制;TrayIcon v3/v4 点击回退;Drawer 关闭刷新;Card margin;密码框眼睛按钮;MessageBox 尺寸修复。
  • v1.27.1:停用实验性独立渲染线程,保留 VBLANK 帧同步;右键菜单适配非 DWM chrome;修复菜单栏残留 hover、标题栏隐藏/切回原生标题栏后的菜单位置;resize 时同步提交新帧,避免布局更新但画面透明。
  • v1.27.0:
    • Windows 10 Acrylic:Win10 在创建 HostBackdropBrush 前启用 ACCENT_ENABLE_HOSTBACKDROP,保留自定义模糊/色调/噪点链;不再把 Win11 专属 DWM 属性写到 Win10。
    • DWM / Snap:自定义边框在 Win10/Win11 都保留 DwmExtendFrameIntoClientArea({1,1,1,1});WM_SIZE/WM_WINDOWPOSCHANGED 后重新挂 frame 状态,修复 Snap 丢边框/阴影。
    • 渲染驱动:新增 RenderDriver / SetRenderDriver() / GetActiveRenderDriver() / GetRenderDeviceName();demo 支持 --warp / --gpu 与首页重启切换。WARP 只改变应用内容渲染,DWM/Compositor 仍可能使用 GPU。
    • 破坏性:删除公开圆角 API WindowCorner、SetWindowCorner()、GetWindowCorner() 与 DSL corner();Win10 保持系统直角,Win11 跟随 DWM,自定义圆角需自行调用 Win32 DWM API。
    • 控件/演示:标题栏三件套字形在 Win10 正确回退到 Segoe MDL2 Assets;最大化按钮随系统 Snap/还原状态刷新;拖动/缩放期间暂停 UI 动画更新。
  • v1.26.0:
    • 布局:Grid 显式宽高进入 cell 测量;Row/Column 有限主轴分配;Card/Page/ScrollViewer 空内容显式尺寸;Button 关闭 autoSize 也测量内容;Label 显式宽度参与 Wrap;ScrollViewer 不在 Arrange 重测。
    • UIA:provider 缓存/context 与 COM 回调线程同步,修复 CFG FAST_FAIL_GUARD_ICALL_CHECK_FAILURE。
    • 控件:Expander 首次展开/折叠再展开/裁剪修复;ToggleSwitch 按住拖动切换;Slider 拖动跟手、点击/吸附缓动、GetDisplayValue()。
查看源文件docs/src/API.md