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

事件与信号

ZSignal、Connection、跨线程

下载 Markdown

何时用信号

  • 控件对外通知(点击、选中、值变化)用内置 ZSignal。
  • 自定义控件对外事件:自己声明 ZSignal<...> 成员并 Fire。

ConnectionThread

enum class ConnectionThread { CurrentThread, NewThread, UIThread };
  • CurrentThread(默认):槽在 Fire 的线程同步执行。
  • NewThread:每次 Fire 起一个 detach 线程执行槽——不要在槽里碰 UI;已开始执行的槽无法中途取消;不适合高频信号,高频场景用 UIThread 或自行池化。
  • UIThread:把槽投递到 UI 线程(后台线程改 UI 的唯一正确方式);disconnect / 接收者析构后,已排队任务执行时检查存活并跳过。

易错

  • Fire 默认应在 UI 线程执行;从后台线程 Fire 且槽使用 CurrentThread 会直接在后台执行 UI 槽,属于调用方违约。跨线程触发请让槽用 UIThread,或自行保证订阅者存活。
  • NewThread + 捕获裸 this + 接收者可能提前析构 = UAF;需要保活用 ConnectWeak,或改用 UIThread。
  • 版本:v1.15.0 起跨线程与锁语义收口;v1.24.0 起队列任务带存活检查。

Connection(Qt 风格被动句柄)

class Connection {
    void disconnect();
    bool isConnected() const;
    explicit operator bool() const;   // 析构不自动断开
};
  • 默认随接收者的 ConnectionGroup 在其析构时断开;Connection 自身析构不断开。
  • disconnect() 会让已排队的 UIThread / NewThread 任务逻辑失效,但不会中断已经执行中的槽。

易错

  • Connection 不是 RAII 守卫;临时句柄析构不会断开,必须显式 disconnect() 或依赖接收者 group。
  • 可以忽略 connect 的返回值;信号销毁后再 disconnect 是安全的(alive 为原子标志)。
  • 版本:v1.8.1 起为被动句柄语义;v1.24.0 起存活标志原子化并取消排队任务。

ConnectionGroup

class ConnectionGroup : public std::enable_shared_from_this<ConnectionGroup> {
    void disconnectAll(); size_t size() const;
};
  • UIElement / Window 内部用它批量断开自己注册的所有连接。
  • size() 只统计仍存活的连接;已手动断开的连接不计数。

易错

  • ConnectionGroup 的 disconnectAll() 只移除连接,不执行用户槽。

ZSignal

template<typename... TArgs> class ZSignal {
    using SlotType = std::function<void(TArgs...)>;
    Connection connect(SlotType slot,
                       ConnectionThread thread = ConnectionThread::CurrentThread,
                       std::shared_ptr<ConnectionGroup> group = nullptr);
    template<class Receiver, class Slot>
    Connection connect(Receiver* receiver, Slot&& slot,
                       ConnectionThread thread = ConnectionThread::CurrentThread);
    void Fire(TArgs... targs) const;    // 触发
    void operator()(TArgs... targs) const;
};
  • 触发用 Fire(没有 emit 宏)。
  • ZSignal 不可拷贝、不可移动;信号是控件/窗口的成员,不要放进可移动容器。
  • 信号参数按左值传给槽;槽不要写 T&& 形参,大对象建议 const T&。

易错

  • Fire 基于快照遍历,槽内可以安全 disconnect;槽内再次 Fire 同一信号会走“重入”分支(局部拷贝),不要在重入里做递归深链。
  • Fire 与 ZSignal 析构并发是 UB;信号必须在同一线程完成触发/析构。
  • 槽抛异常会直接穿出 Fire,后续槽不再执行;信号槽内不建议抛异常。
  • 版本:v1.18.0 加 RAII 守卫:槽抛异常也会正确还原重入深度并释放快照;v1.24.0 禁止移动。

接收者上下文与 ConnectWeak

  • elem->Connect(sig, slot)、Connect(elem, sig, slot)、sig.connect(elem, slot) 都把连接登记到 elem 的 ConnectionGroup,elem 析构时自动断开;Window 同样支持。
  • ConnectWeak(self, sig, slot) 用弱引用;槽第一个参数为 T* 或 T&,执行期间 self 保活;对象已销毁则不调用。
  • 成员函数指针只走自由 Connect / ConnectWeak(有编译期类型检查);elem->Connect(sig, &Class::Method) 不再支持。
auto panel = std::make_shared<Panel>();

panel->Connect(btn->Clicked, [this] { Refresh(); });
Connect(panel, btn->Clicked, &Panel::OnClick);
btn->Clicked.connect(panel, [this] { Refresh(); });

ConnectWeak(panel, btn->Clicked, [](Panel* self) { self->Refresh(); });
ConnectWeak(panel, btn->Clicked, &Panel::OnClick);

易错

  • ConnectWeak 的槽里不要再按值捕获 self 的 shared_ptr,否则会形成“信号→槽→self→信号”的强引用环。

异步任务 / RunAsync

enum class AsyncTaskStatus { Pending, Running, Completed, Canceled, Failed };
class AsyncOwner { /* weak owner: callbacks are dropped after it dies */ };
class AsyncCancelToken { bool IsCancellationRequested() const; void ThrowIfCancellationRequested() const; };
class AsyncProgress { void Report(float value, const std::wstring& message = {}); };
template<class T> class AsyncTask { bool Cancel(); bool Wait(); AsyncTaskStatus GetStatus() const; AsyncCancelToken GetCancelToken() const; };
template<class T, class Work> std::shared_ptr<AsyncTask<T>> RunAsync(AsyncOwner, Work&&,
    std::function<void(T)> onCompleted, std::function<void(std::exception_ptr)> onFailed = {},
    std::function<void(float, const std::wstring&)> onProgress = {}, std::function<void()> onCanceled = {});
  • v1.27.2 异步: RunAsync<T> 在后台执行,AsyncCancelToken 取消,AsyncProgress::Report 合并到 UI 线程;完成/失败/取消回调都在 UI 线程发送,AsyncOwner 弱引用失效后丢弃回调。

ViewCore / virtual view scaffolding

struct ScrollAxis { float offset, target, viewport, content, maxOffset;
    void SetMetrics(float viewport, float content);  void ScrollTo(float);  void EnsureVisible(float start, float size);
    Range VisibleRange(float itemExtent, float overscan = 0, int itemCount = -1) const; };
template<class T> class RecyclePool { std::shared_ptr<T> Acquire();  void Release(std::shared_ptr<T>);
    void Trim(size_t maxIdle);  void Clear(); };
template<class Result> class FetchFlow { void Start(AsyncOwner, Work, Ready, Error = {}, Progress = {}, Canceled = {});
    void Cancel();  bool Wait();  FetchState GetState() const; };
  • ViewCore 只抽象滚动、元素回收和请求生命周期,不定义通用数据源;ListView 已经用 ScrollAxis 管理垂直滚动状态。

全局信号 UIZSignals

namespace UIZSignals {
    inline ZSignal<Window*, ID2D1RenderTarget*> DrawOverlay;
    inline ZSignal<Window*, float, float> GlobalMouseDown;
    inline ZSignal<Window*> WindowActivated, WindowDeactivated;
    inline ZSignal<Window*, UIElement*> ElementCaptureRequest, ElementCaptureRelease, RepaintRequest;
    inline ZSignal<Window*> LayoutInvalidated;
    inline ZSignal<> DeviceReset, ReloadAcrylic;
    inline ZSignal<const std::wstring&> Error;         // v1.16.0
}
  • RepaintRequest/LayoutInvalidated/capture 信号只对未挂载元素兜底;已挂载元素直接走 Window。
  • DeviceReset:释放一切与渲染目标/设备绑定的缓存(如 ImageDeviceCache)。

易错

  • DrawOverlay 带 Window*,subscriber 必须按 GetWindow() 过滤,否则窗口 A 的浮层会画到窗口 B 上(经典多窗口串扰)。
  • 版本:UIZSignals::Error = v1.16.0。
查看源文件docs/src/API.md