ListView.h

Go to the documentation of this file.

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

struct ListItem {
    const char* label;          // Display text
    uint8_t icon = 0;           // Icon type (0 = none)
    bool iconDisabled = false;  // Draw icon crossed-out
    void* userData = nullptr;   // Optional user data
};

class ListView : public ViewBase {
public:
    static constexpr uint16_t MAX_ITEMS = 2048;
    static constexpr uint8_t DEFAULT_ITEM_HEIGHT = 18;
    // The actual visible-row count is the file-scope VISIBLE_ITEMS in
    // ListView.cpp (fixed at 4 for the 296x128 panel).

    using SelectCallback = void(*)(uint16_t index, void* userData);

    using MenuCallback = void(*)(uint16_t index, void* userData);

    using ItemRenderCallback = bool(*)(Gdey029T94* gfx,
                                       const ListItem& item,
                                       uint16_t index,
                                       int x, int y, int w, int h,
                                       bool selected,
                                       void* userCtx);

    void init(const char* title, const ListItem* items, uint16_t count);

    void setOnSelect(SelectCallback callback) { onSelect_ = callback; }

    void setOnMenu(MenuCallback callback) { onMenu_ = callback; }

    void setEditMutex(SemaphoreHandle_t mutex) { editMutex_ = mutex; }

    void setItemRenderer(ItemRenderCallback callback, void* userCtx = nullptr) {
        itemRenderer_ = callback;
        itemRendererCtx_ = userCtx;
    }

    void setHint(const char* hint) { customHint_ = hint; }

    void setEmptyText(const char* text) { emptyText_ = text; }

    void setItemHeight(uint8_t height) { itemHeight_ = height > 0 ? height : DEFAULT_ITEM_HEIGHT; }

    uint16_t getSelection() const { return selection_; }

    void setSelection(uint16_t index);

    uint16_t getItemCount() const { return itemCount_; }

    const ListItem* getSelectedItem() const;

    void updateItem(uint16_t index);

    void insertItem(uint16_t index);

    void removeItem(uint16_t index);

    void repaintPartial();

    void preservePosition() { preservePosition_ = true; }
 
    // IView implementation
    void render(bool partial) override;
    InputResult onKey(char key) override;
    InputResult onLongPress(char key) override;
    const char* getName() const override { return "ListView"; }
    const char* getFooterHint() const override;
 
private:
    const char* title_ = nullptr;
    const char* customHint_ = nullptr;
    const char* emptyText_ = nullptr;
    const ListItem* items_ = nullptr;
    uint16_t itemCount_ = 0;
    uint16_t selection_ = 0;
    uint16_t scrollPos_ = 0;
    SelectCallback onSelect_ = nullptr;
    MenuCallback onMenu_ = nullptr;
    ItemRenderCallback itemRenderer_ = nullptr;
    void* itemRendererCtx_ = nullptr;
    bool preservePosition_ = false;
    uint8_t itemHeight_ = DEFAULT_ITEM_HEIGHT;
    // Optional, borrowed (not owned): serialises item-buffer access with a
    // cross-task writer. Null disables locking. See setEditMutex().
    SemaphoreHandle_t editMutex_ = nullptr;
 
    // Calculated at render time based on display dimensions
    uint8_t visibleItems_ = 4;
 
    void navigate(bool down);
    void ensureVisible();
    void drawRow(Gdey029T94* gfx, uint16_t itemIndex, int y, int rowWidth);
};
 
// ============================================================================
// Convenience Functions
// ============================================================================

ListView* showListView(const char* title, const ListItem* items, uint16_t count,
                       ListView::SelectCallback onSelect, const char* hint = nullptr);
 
} // namespace cdc::ui