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

元素基类

UIElement(布局属性、缓存、事件、无障碍、调试)

下载 Markdown

布局属性

virtual Size MeasureOverride(const Size& avail) = 0;
Size Measure(const Size& avail);      Size GetDesiredSize() const;
virtual void ArrangeOverride(const Rect&);   void Arrange(const Rect&);
Rect GetArrangedRect() const;
void InvalidateLayout();      // 冒泡:向根标脏
void InvalidateLayoutSelf();  // 只标自己(池化/虚拟 rebind 用,不冒泡)
void SetWidth/SetHeight(float);  float GetWidth/GetHeight() const;
void SetFillWidth/SetFillHeight(bool);   bool GetFillWidth/GetFillHeight() const;
void SetMargin(const Thickness&);
void SetMinWidth/SetMinHeight/SetMaxWidth/SetMaxHeight(float);
void SetMinSize/SetMaxSize(float,float);
void SetStretchWeights(float h, float v);
void SetHorizontalStretchWeight(float);   void SetVerticalStretchWeight(float);
virtual float GetDefaultHorizontalStretchWeight() const;   // 同理 Vertical
  • 拉伸权值:容器(ColumnBox/RowBox/GridLayout)把剩余空间按子元素权值分配。FillWidth/Height 等价“该轴权值 1”。GetDefault* 是类型默认,Set* 覆盖它。

易错

  • SetWidth/SetHeight 是固定尺寸;SetFillWidth/Height 是填满父轴;两者与拉伸权值叠加,行为要分清。
  • GetDesiredSize() 是上一次 Measure 的结果;未测量过/刚改内容时可能是旧值。
  • 版本:SetStretchWeights/GetDefault* 自初版存在;ColumnBox/RowBox/GridLayout 真正按显式权值分配剩余空间 = v1.17.0。

绘制 / 子元素 / 裁剪 / 缓存

virtual void Draw(ID2D1RenderTarget* rt) = 0;
virtual void RefreshChildren();                       // 更新阶段(UI 线程)重建可见子列表
virtual const std::vector<UIElement*>& GetChildren() const;   // 渲染阶段纯读
virtual bool UseCache() const;   void SetUseCache(bool);      // 默认 true
virtual std::optional<D2D1_RECT_F> GetClipRect() const;
void SetClipRect(const std::optional<Rect>&);
void SetBleed(float);            // 阴影/外发光留边
virtual void ReleaseDeviceResources();        // 只释放自身
void ReleaseDeviceResourcesRecursive();        // 释放整棵子树
virtual D2D1::Matrix3x2F GetChildRenderTransform(UIElement* child) const;
  • 缓存机制:UseCache()==true 的元素渲染到自身 ID2D1Bitmap1 离屏位图;仅当被 RequestRepaint() 标记或尺寸变化时重建。出现阴影时自动加 bleed。

易错

  • 每帧内容在变(动画、实时文本、旋转)或实例极多(上千个)的控件应 SetUseCache(false),否则显存与重建开销爆炸。
  • GetChildren() 在渲染阶段必须纯读;渲染前要保证 RefreshChildren() 已调用(窗口在 AdvanceFrame 里统一做)。
  • ReleaseDeviceResources() 只释放自身;释放整棵子树用 ReleaseDeviceResourcesRecursive()。
  • 版本:ReleaseDeviceResourcesRecursive() = v1.18.0(用于隐藏页缓存延迟释放);SetUseCache(false) 现在会立即释放已有位图。

可见性 / 启用 / 提示 / 光标

void SetVisible(bool);  void SetVisibleNoInvalidate(bool);  bool IsVisible() const;
void SetEnabled(bool);  bool IsEnabled() const;  bool IsEffectivelyEnabled() const;  // 沿父链
void SetToolTip(const std::wstring&);   virtual std::wstring GetToolTip() const;
void SetCursor(HCURSOR);   HCURSOR GetDesiredCursor() const;
void SetPointerCursors(HCURSOR normal, HCURSOR pressed, HCURSOR disabled);
HCURSOR GetPointerCursor(bool pressed) const;  virtual HCURSOR GetPointerCursorAt(float x, float y, bool pressed) const;
virtual void OnPointerCancel();   // capture stolen/system cancel
  • 禁用元素不参与命中/悬停。提示会向上解析父级提示(如 Button → Label)。

易错

  • SetCursor 不直接调 ::SetCursor,而是延迟到 WM_SETCURSOR,避免闪烁。

右键菜单 / 拖动区 / 布局参与

void SetContextMenu(std::shared_ptr<Menu>);
void SetContextMenuFactory(std::function<std::shared_ptr<Menu>()>);
std::shared_ptr<Menu> BuildContextMenu() const;
enum class LayoutParticipation { Normal, DrawBeforeLayout, DrawAfterLayout };
void SetLayoutParticipation(LayoutParticipation);
void SetDraggable(bool); void SetDragRegion(const Rect&); void ClearDragRegion();
virtual int NonClientHitTest(float x, float y) const;

易错

  • DrawBeforeLayout/DrawAfterLayout 由独立通道绘制,不要再放进根树,否则画两遍。自定义标题栏就是 DrawBeforeLayout 且自己管位置。

事件虚函数与元素信号

virtual UIElement* HitTest(float x, float y);
virtual void OnMouseEnter/Leave/Move/Down/Up(...);  virtual bool OnContextMenu(float,float);
virtual void OnKeyDown/Up(WPARAM,LPARAM);  virtual void OnChar(wchar_t);
virtual void OnFocus()/OnBlur();
virtual void UpdateAnimation(float dt);  virtual bool HasActiveAnimation() const;
virtual bool OnMouseWheel(float dx, float dy);
virtual bool IsTextInput() const;  virtual bool AcceptsTab() const;  virtual bool IsFocusable() const;
virtual Rect GetImeCandidateRect() const;  virtual void SetCompositionText(...);
// 元素内置信号
ZSignal<> MouseEnter, MouseLeave, Focused, Blurred;
ZSignal<float,float> MouseMove, MouseDown, MouseUp;
ZSignal<WPARAM,LPARAM> KeyDown, KeyUp;   ZSignal<wchar_t> Char;

易错

  • 有动画的控件必须让 HasActiveAnimation() 正确返回,否则帧循环停了动画就不走。
  • 多行编辑器要让 AcceptsTab() 返回 true 才会吞掉 Tab 做缩进,否则 Tab 切焦点。
  • 版本:AcceptsTab() = v1.18.0(配合 TextEdit)。

无障碍(UIA)— v1.17.0

void SetAccessibleName(const std::wstring&);  std::wstring GetAccessibleName() const;
void SetAccessibleDescription(const std::wstring&);
void SetAutomationId(const std::wstring&);     std::wstring GetAutomationIdOrAuto() const;  // 自动 e{n}
void SetAccessibleRole(AccessibleRole);  virtual AccessibleRole GetAccessibleRole() const;
virtual std::wstring DefaultAccessibleName() const;  virtual bool IsAccessibilityIgnored() const;
std::vector<UIElement*> GetAccessibleChildren() const;
// Pattern 虚函数(按角色分派)
virtual void AccessibilityInvoke();
virtual std::wstring GetAccessibleValue() const;  virtual void SetAccessibleValue(const std::wstring&);
virtual bool IsAccessibleReadOnly() const;
virtual int  GetAccessibleToggleState() const;  virtual void AccessibilityToggle();
virtual int  GetAccessibleExpandState() const;  virtual void AccessibilityExpand/Collapse();
virtual double GetAccessibleRangeValue() const; virtual void SetAccessibleRangeValue(double);
virtual double GetAccessibleRangeMin/Max/Step() const;
void AccessibilityNotifyFocus/PropertyChanged/StructureChanged();

易错

  • 角色决定暴露哪些 UIA Pattern:Button/MenuItem→Invoke;Edit/Document→Value;Slider/ProgressBar→RangeValue;toggle 状态 ≥0→Toggle;expand 状态 ≥0→ExpandCollapse。隐藏节点默认不暴露。
  • 版本:整套 = v1.17.0(对应 Window::SetAccessibilityEnabled,默认开)。v1.26.0 起 UIA provider 缓存/context 生命周期与 COM 回调线程同步,避免 provider 已释放后仍被 UIA 调用。

字体(元素级)

static void SetGlobalFont(const FontSpec&);  void SetFont(const FontSpec&);
void SetFontFamily/SetFontSize/SetFontWeight(...);  void ClearFont();
virtual std::optional<FontSpec> GetTypeDefaultFont() const;  FontSpec GetEffectiveFontSpec() const;
  • 解析链:实例覆盖 → 类型默认 → 全局。

易错

  • 写 fontOverride_(含 std::wstring)必须与渲染串行;已挂载元素的 StoreFontOverride/InvalidateFontCache 内部会取 renderLock_。

阴影

void SetShadow(bool);  bool HasShadow() const;
void SetShadowColor(Color); SetShadowBlur(float); SetShadowOffset(float,float); SetShadowCornerRadius(float);
float GetShadowExtent() const;
  • 阴影仅对开启缓存的元素生效(Card 设阴影会自动开缓存)。

调试计数(按元素)

DebugMeasureCount/ArrangeCount/RepaintCount/DrawCount/CacheValid/CacheBytes/MeasureMs/ArrangeMs/DrawMs/AnimationProgress/ResetCounters 等。

  • 版本:v1.17.0 加入的逐元素调试计数,配合调试通道 Top-N 使用。
查看源文件docs/src/API.md