ViewStack.h

Go to the documentation of this file.

#pragma once
 
#include "IView.h"
#include <cstdint>
#include <freertos/FreeRTOS.h>
#include <freertos/semphr.h>
 
namespace cdc::ui {

class ViewStack {
public:
    static constexpr uint8_t MAX_DEPTH = 20;

    static ViewStack& instance();

    void push(IView* view, void* context = nullptr);

    void pop();

    void replace(IView* view, void* context = nullptr);

    void popToRoot();

    void popToAnchor(IView* anchor);

    void popToDepth(uint8_t targetDepth);

    IView* current() const;

    IView* at(uint8_t depth) const;

    uint8_t depth() const { return depth_; }

    bool isEmpty() const { return depth_ == 0; }
 
    // === Input dispatch ===

    void dispatchKey(char key);

    InputResult dispatchLongPress(char key);

    void dispatchTick(uint32_t nowMs);
 
    // === Rendering ===

    void render(bool synchronous = false);

    bool needsRender() const;
 
    // === Modal support ===

    void showModal(IView* modal);

    void hideModal();

    void removeModal(IView* modal);

    bool hasModal() const { return modalDepth_ > 0; }

    IView* getModal() const { return modalDepth_ > 0 ? modals_[modalDepth_ - 1] : nullptr; }

    void forceFullRefresh() { forceRefresh(hal::RefreshMode::FULL); }

    void forceRefresh(hal::RefreshMode mode);
 
    // === Exclusive lock (e.g. for FIDO2 prompts) ===

    bool acquireExclusive(const void* owner);

    bool releaseExclusive(const void* owner);

    const void* exclusiveOwner() const { return exclusiveOwner_; }
 
    // === Inactivity timeout ===

    using InactivityCallback = void(*)();

    void setInactivityTimeout(InactivityCallback callback, uint32_t timeoutMs);

    void resetInactivityTimer();

    void checkInactivity(uint32_t nowMs);
 
private:
    ViewStack() = default;
 
    static constexpr uint8_t MAX_MODAL_DEPTH = 4;
 
    IView* stack_[MAX_DEPTH] = {};
    uint8_t depth_ = 0;
    IView* modals_[MAX_MODAL_DEPTH] = {};
    uint8_t modalDepth_ = 0;
    IView* pendingPush_ = nullptr;
    void* pendingContext_ = nullptr;
    // Strongest refresh mode requested for the next flush. Starts at FULL so
    // the very first render after boot fully cleans the panel; afterwards it
    // resets to PARTIAL_LIGHT ("no extra requirement") and transitions or
    // views escalate it as needed.
    hal::RefreshMode pendingRefresh_ = hal::RefreshMode::FULL;
    // The framebuffer composite (base view + modal stack) must be repainted
    // from the bottom up, e.g. after a modal was dismissed so nothing of it
    // lingers. Independent of the refresh waveform above.
    bool needsCompositeRepaint_ = false;
    const void* exclusiveOwner_ = nullptr;
    SemaphoreHandle_t mutex_ = nullptr;
 
    void ensureMutex();
 
    // Unlocked helpers used when the caller already holds mutex_.
    void push_unlocked(IView* view, void* context);
    void pop_unlocked();
    void hideModal_unlocked();
    void removeModal_unlocked(IView* modal);
    void escalatePending_unlocked(hal::RefreshMode mode);
 
    // Inactivity timeout
    InactivityCallback inactivityCallback_ = nullptr;
    uint32_t inactivityTimeoutMs_ = 0;
    uint32_t lastActivityMs_ = 0;
};
 
} // namespace cdc::ui