何时用信号
- 控件对外通知(点击、选中、值变化)用内置
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。