Popups / 弹窗

Popup 用来显示短消息、进度或输入一个固定位数的整数。普通使用时直接调 PixelUI::showPopup...()，不需要自己构造 Popup 对象。

信息弹窗

1
2
3

if (!ui.showPopupInfo("Saved", "Settings", 80, 30, 1500)) {
    // 队列已满或 manager 正在 dispatch
}

进度弹窗

int32_t progress = 0;

ui.showPopupProgress(
    progress,
    0,
    100,
    "Updating",
    100,
    40,
    5000,
    [](int32_t value) {
        // 如果需要，在这里观察值变化。
    },
    false);

progress 是引用，必须活到这个请求从队列中取出并完全关闭。

固定位数整数输入

int32_t setpoint = 25;

if (!ui.showPopupValueDigits(
        setpoint,
        3,          // 1..PIXELUI_MAX_INT_FIXED_WIDTH
        "Target",
        80,
        40,
        3000,
        [this](int32_t value) { target_ = value; })) {
    // request rejected
}

位数可以是 1 到 PIXELUI_MAX_INT_FIXED_WIDTH。

队列和容量

PopupManager 是固定容量 FIFO：

1	active Popup -> pending request 1 -> pending request 2

只有 active Popup 会被构造、绘制和接收输入。
后来的请求保存为较小的描述符，按先进先出处理。
PIXELUI_MAX_POPUP_NUM 包含 active 和 pending。
没有 priority 和抢占；队列满时新请求返回 false。
active Popup 存在单槽 etl::variant_pool中，完成后销毁，再在同一个稳定槽位构造下一个。

生命周期与重入

text/title 指针、数值引用和回调捕获都是非拥有的。排队会把它们的寿命要求延长到“真正激活并关闭”，不只是 showPopup...() 返回之后。

App pop 时会清理 active 和 pending Popup。若数据来自寿命更短的对象，调用者仍要自己提前清理。

PopupManager 在构造、销毁、更新、绘制和派发输入期间拒绝结构修改。因此 Popup 回调里不要同步再弹一个 Popup；记下请求，等当前输入派发返回后再做。

PopupValueDigits 销毁时目前会清理全部动画，以避免动画继续引用已销毁的 NumScroll。这个做法安全，但可能一起停止 App 的其他动画，属于当前已知限制。