Popups

Docs home Quick start Architecture Lifecycle GitHub

中文English

Popups display short messages, progress, or a fixed-width integer input. In normal use, call PixelUI::showPopup...() directly instead of constructing Popup objects yourself.

Information Popup

if (!ui.showPopupInfo("Saved", "Settings", 80, 30, 1500)) {
    // The queue is full or the manager is dispatching.
}

Progress Popup

int32_t progress = 0;

ui.showPopupProgress(
    progress,
    0,
    100,
    "Updating",
    100,
    40,
    5000,
    [](int32_t value) {
        // Observe value changes here when needed.
    },
    false);

progress is a reference. It must live until this request has left the queue and the Popup has fully closed.

Fixed-width integer input

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
}

Width may range from 1 to PIXELUI_MAX_INT_FIXED_WIDTH.

Queue and capacity

PopupManager is a fixed-capacity FIFO:

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

• Only the active Popup is constructed, drawn, and receives input.
• Later requests are stored as smaller descriptors and processed in arrival order.
• PIXELUI_MAX_POPUP_NUM includes the active and pending Popups.
• There is no priority or preemption; a new request returns false when the queue is full.
• The active Popup lives in a single-slot etl::variant_pool. It is destroyed before the next Popup is constructed in the same stable slot.

Lifetime and reentrancy

Text and title pointers, value references, and callback captures are non-owning. Queueing extends their required lifetime until the request is activated and closed, not merely until showPopup...() returns.

Popping an App clears its active and pending Popups. The caller must still clean up earlier when data belongs to an even shorter-lived object.

PopupManager rejects structural changes while constructing, destroying, updating, drawing, or dispatching input. Do not synchronously open another Popup from a Popup callback. Record the request and perform it after the current input dispatch returns.

Destroying PopupValueDigits currently clears all Animations to prevent them from retaining a destroyed NumScroll. This is safe, but may also stop unrelated App Animations and is a known limitation.