面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
## 何时用信号

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

## ConnectionThread

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

###block_red_start
**易错**

- `Fire` 默认应在 UI 线程执行;从后台线程 Fire 且槽使用 `CurrentThread` 会直接在后台执行 UI 槽,属于调用方违约。跨线程触发请让槽用 `UIThread`,或自行保证订阅者存活。
- `NewThread` + 捕获裸 `this` + 接收者可能提前析构 = UAF;需要保活用 `ConnectWeak`,或改用 `UIThread`。
###block_red_end

- **`版本`**:`v1.15.0` 起跨线程与锁语义收口;`v1.24.0` 起队列任务带存活检查。

## Connection(Qt 风格被动句柄)

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

###block_red_start
**易错**

- `Connection` **不是 RAII 守卫**;临时句柄析构不会断开,必须显式 `disconnect()` 或依赖接收者 group。
- 可以忽略 `connect` 的返回值;信号销毁后再 `disconnect` 是安全的(`alive` 为原子标志)。
###block_red_end

- **`版本`**:`v1.8.1` 起为被动句柄语义;`v1.24.0` 起存活标志原子化并取消排队任务。

## ConnectionGroup

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

###block_red_start
**易错**

- `ConnectionGroup` 的 `disconnectAll()` 只移除连接,不执行用户槽。
###block_red_end

## ZSignal

```cpp
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&`。

###block_red_start
**易错**

- `Fire` 基于**快照**遍历,槽内可以安全 `disconnect`;槽内再次 `Fire` 同一信号会走“重入”分支(局部拷贝),**不要**在重入里做递归深链。
- `Fire` 与 `ZSignal` 析构并发是 UB;信号必须在同一线程完成触发/析构。
- 槽抛异常会直接穿出 `Fire`,后续槽不再执行;信号槽内不建议抛异常。
###block_red_end

- **`版本`**:`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)` 不再支持。

```cpp
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);
```

###block_orange_start

###block_red_start
**易错**

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

## 异步任务 / RunAsync

```cpp
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

```cpp
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

```cpp
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`)。

###block_red_start
**易错**

- `DrawOverlay` 带 `Window*`,subscriber **必须**按 `GetWindow()` 过滤,否则窗口 A 的浮层会画到窗口 B 上(经典多窗口串扰)。
###block_red_end

- **`版本`**:`UIZSignals::Error` = `v1.16.0`。
第 4 章

事件与信号

ZSignal、Connection、跨线程

何时用信号

ConnectionThread

cpp
enum class ConnectionThread { CurrentThread, NewThread, UIThread };

易错

  • Fire 默认应在 UI 线程执行;从后台线程 Fire 且槽使用 CurrentThread 会直接在后台执行 UI 槽,属于调用方违约。跨线程触发请让槽用 UIThread,或自行保证订阅者存活。
  • NewThread + 捕获裸 this + 接收者可能提前析构 = UAF;需要保活用 ConnectWeak,或改用 UIThread。

Connection(Qt 风格被动句柄)

cpp
class Connection {
    void disconnect();
    bool isConnected() const;
    explicit operator bool() const;   // 析构不自动断开
};

易错

  • Connection 不是 RAII 守卫;临时句柄析构不会断开,必须显式 disconnect() 或依赖接收者 group。
  • 可以忽略 connect 的返回值;信号销毁后再 disconnect 是安全的(alive 为原子标志)。

ConnectionGroup

cpp
class ConnectionGroup : public std::enable_shared_from_this<ConnectionGroup> {
    void disconnectAll(); size_t size() const;
};

易错

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

ZSignal

cpp
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 基于快照遍历,槽内可以安全 disconnect;槽内再次 Fire 同一信号会走“重入”分支(局部拷贝),不要在重入里做递归深链。
  • Fire 与 ZSignal 析构并发是 UB;信号必须在同一线程完成触发/析构。
  • 槽抛异常会直接穿出 Fire,后续槽不再执行;信号槽内不建议抛异常。

接收者上下文与 ConnectWeak

cpp
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);

block_orange_start

易错

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

异步任务 / RunAsync

cpp
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 = {});

ViewCore / virtual view scaffolding

cpp
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; };

全局信号 UIZSignals

cpp
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
}

易错

  • DrawOverlay 带 Window*,subscriber 必须按 GetWindow() 过滤,否则窗口 A 的浮层会画到窗口 B 上(经典多窗口串扰)。
↑