#include <ListView.h>

Inheritance diagram for cdc::ui::ListView:

Public Types
using	SelectCallback = void()(uint16_t index, void userData)
using	MenuCallback = void()(uint16_t index, void userData)
using	ItemRenderCallback

Public Member Functions
void	init (const char title, const ListItem items, uint16_t count)
	Initializes list data and selection state.
void	setOnSelect (SelectCallback callback)
void	setOnMenu (MenuCallback callback)
void	setEditMutex (SemaphoreHandle_t mutex)
void	setItemRenderer (ItemRenderCallback callback, void *userCtx=nullptr)
void	setHint (const char *hint)
void	setEmptyText (const char *text)
void	setItemHeight (uint8_t height)
uint16_t	getSelection () const
void	setSelection (uint16_t index)
	Sets the selected item index.
uint16_t	getItemCount () const
const ListItem *	getSelectedItem () const
	Returns the currently selected item.
void	updateItem (uint16_t index)
	Marks the list dirty after the caller updated a backing item.
void	insertItem (uint16_t index)
	Reflects a caller-side insertion at index and marks dirty.
void	removeItem (uint16_t index)
	Reflects a caller-side removal at index and marks dirty.
void	repaintPartial ()
	Requests a redraw; the actual repaint happens once per render cycle.
void	preservePosition ()
void	render (bool partial) override
	Renders list rows, selection, scroll indicators, and footer.
InputResult	onKey (char key) override
	Handles key input for list navigation and actions.
InputResult	onLongPress (char key) override
const char *	getName () const override
const char *	getFooterHint () const override
	Returns footer hint text for this list.
Public Member Functions inherited from cdc::ui::ViewBase
virtual	~ViewBase ()=default
void	onEnter (void *context) override
void	onExit () override
void	onResume () override
void	onPause () override
void	setLifecycleHooks (void(onHide)(void ), void(onShow)(void ), void *userData) override
bool	needsRender () const override
void	markDirty () override
void	clearDirty () override
void	setFooterHint (const char *hint) override
const char *	getFooterHint () const override
Public Member Functions inherited from cdc::ui::IView
virtual	~IView ()=default
virtual bool	prefersLightRefresh () const
virtual void	onTick (uint32_t nowMs)

Static Public Attributes
static constexpr uint16_t	MAX_ITEMS = 2048
static constexpr uint8_t	DEFAULT_ITEM_HEIGHT = 18

Additional Inherited Members
Protected Member Functions inherited from cdc::ui::ViewBase
void	setTitle (const char *title)
const char *	getTitle () const
Protected Attributes inherited from cdc::ui::ViewBase
bool	dirty_ = true
const char *	title_ = nullptr
const char *	customFooter_ = nullptr
void(*	onHide_ )(void *) = nullptr
void(*	onShow_ )(void *) = nullptr
void *	lifecycleUserData_ = nullptr

Detailed Description

ListView - Highly dynamic scrollable selection menu

Reusable component for any list-based UI. Dynamically calculates visible items based on display size.

Keys: 2 = Up 8 = Down Y = Select (triggers callback) N = Back (REQUEST_POP)

Definition at line 34 of file ListView.h.

Member Typedef Documentation

◆ ItemRenderCallback

using cdc::ui::ListView::ItemRenderCallback

Initial value:

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

Optional per-row renderer. Return true if the row is fully rendered, false to fall back to default.

Definition at line 59 of file ListView.h.

◆ MenuCallback

using cdc::ui::ListView::MenuCallback = void(*)(uint16_t index, void* userData)

Context/menu callback (e.g., key '3')

Parameters

index	Selected item index
userData	User data from ListItem

Definition at line 53 of file ListView.h.

◆ SelectCallback

using cdc::ui::ListView::SelectCallback = void(*)(uint16_t index, void* userData)

Selection callback

Parameters

index	Selected item index
userData	User data from ListItem

Definition at line 46 of file ListView.h.

Member Function Documentation

◆ getFooterHint()

const char * cdc::ui::ListView::getFooterHint ( ) const

overridevirtual

Returns footer hint text for this list.

Returns: Footer hint string.

Reimplemented from cdc::ui::IView.

Definition at line 219 of file ListView.cpp.

References cdc::ui::ViewBase::customFooter_, and cdc::ui::tr().

Referenced by render().

◆ getItemCount()

uint16_t cdc::ui::ListView::getItemCount ( ) const

inline

Get item count

Definition at line 131 of file ListView.h.

◆ getName()

const char * cdc::ui::ListView::getName ( ) const

inlineoverridevirtual

Get view name for debugging

Implements cdc::ui::IView.

Definition at line 189 of file ListView.h.

◆ getSelectedItem()

const ListItem * cdc::ui::ListView::getSelectedItem ( ) const

Returns the currently selected item.

Get selected item

Returns: Pointer to selected item or nullptr.

Definition at line 88 of file ListView.cpp.

◆ getSelection()

uint16_t cdc::ui::ListView::getSelection ( ) const

inline

Get current selection index

Definition at line 121 of file ListView.h.

◆ init()

void cdc::ui::ListView::init	(	const char *	title,
		const ListItem *	items,
		uint16_t	count )

Initializes list data and selection state.

Initialize list view

Parameters

title	List title
items	Array of items (pointer is stored, not copied)
count	Number of items
title	List title text.
items	Item array pointer.
count	Number of items in items.

Returns: void

Definition at line 49 of file ListView.cpp.

References cdc::ui::ViewBase::dirty_, LOG_D, MAX_ITEMS, cdc::ui::TAG, and VISIBLE_ITEMS.

◆ insertItem()

void cdc::ui::ListView::insertItem ( uint16_t index )

Reflects a caller-side insertion at index and marks dirty.

Insert-notify: the backing array (passed to init(), pointer stored) has had one item inserted at index (shifting later items down); the caller must have done that shift and kept capacity. Bumps the count, keeps the currently-selected item selected, and partial-repaints. Must be called from the UI task.

Parameters

index	Position the new item was inserted at (clamped to count).
index	Insertion position (clamped to the current count).

Returns: void

Definition at line 389 of file ListView.cpp.

References cdc::ui::ViewBase::markDirty(), and MAX_ITEMS.

◆ onKey()

InputResult cdc::ui::ListView::onKey ( char key )

overridevirtual

Handles key input for list navigation and actions.

Parameters

key	Pressed key code.

Returns: Input handling result for the view stack.

Implements cdc::ui::IView.

Definition at line 144 of file ListView.cpp.

References cdc::ui::CONSUMED, cdc::ui::IGNORED, cdc::ui::KEY_DOWN, cdc::ui::KEY_MENU, cdc::ui::KEY_NO, cdc::ui::KEY_UP, cdc::ui::KEY_YES, cdc::ui::REQUEST_POP, and valid.

◆ onLongPress()

InputResult cdc::ui::ListView::onLongPress ( char key )

overridevirtual

Handle long key press (optional)

Parameters

key	Key character

Returns: Input result

Reimplemented from cdc::ui::IView.

Definition at line 205 of file ListView.cpp.

References cdc::ui::CONSUMED, cdc::ui::IGNORED, cdc::ui::KEY_DOWN, cdc::ui::KEY_UP, and setSelection().

◆ preservePosition()

void cdc::ui::ListView::preservePosition ( )

inline

Preserve current position (selection and scroll) on next init Call this before init() to retain position when returning to the list

Definition at line 183 of file ListView.h.

◆ removeItem()

void cdc::ui::ListView::removeItem ( uint16_t index )

Reflects a caller-side removal at index and marks dirty.

Remove-notify: the backing array has had the item at index removed (shifting later items up); the caller must have done that shift. Drops the count, keeps the selection valid, and partial-repaints. Must be called from the UI task.

Parameters

index	Index of the removed item.
index	Index of the removed item.

Returns: void

Definition at line 409 of file ListView.cpp.

References cdc::ui::ViewBase::markDirty().

◆ render()

void cdc::ui::ListView::render ( bool partial )

overridevirtual

Renders list rows, selection, scroll indicators, and footer.

Parameters

partial Indicates partial/full redraw mode.

Returns: void

Implements cdc::ui::IView.

Definition at line 234 of file ListView.cpp.

References cdc::ui::ViewBase::dirty_, cdc::ui::display, cdc::ui::render::drawFooterBar(), cdc::ui::render::drawHeaderLeft(), cdc::ui::render::drawScrollIndicator(), cdc::hal::getDisplayInstance(), getFooterHint(), ITEM_PADDING_X, LIST_START_Y, cdc::ui::render::printText(), SCROLL_INDICATOR_WIDTH, and cdc::ui::TITLE_Y.

◆ repaintPartial()

void cdc::ui::ListView::repaintPartial ( )

Requests a redraw; the actual repaint happens once per render cycle.

Repaint the visible rows in partial-refresh mode and flush immediately. For out-of-band updates (after re-pointing items via init()) that should not wait for the next render cycle. Must be called from the UI task.

Returns: void

Definition at line 380 of file ListView.cpp.

References cdc::ui::ViewBase::markDirty().

◆ setEditMutex()

void cdc::ui::ListView::setEditMutex ( SemaphoreHandle_t mutex )

inline

Set an optional recursive mutex serialising buffer access.

When set (non-null), render(), navigation and the item-buffer reads in onKey() acquire it. A cross-task writer that re-points the backing array via init()/repaintPartial() must hold the same mutex around the swap, so the UI task never reads a half-replaced or freed buffer. Null (default) disables locking entirely for single-task lists.

Definition at line 93 of file ListView.h.

References mutex.

◆ setEmptyText()

void cdc::ui::ListView::setEmptyText ( const char * text )

inline

Set placeholder text shown in the body area when the list is empty.

Definition at line 111 of file ListView.h.

◆ setHint()

void cdc::ui::ListView::setHint ( const char * hint )

inline

Set custom footer hint text (nullptr = default)

Definition at line 106 of file ListView.h.

◆ setItemHeight()

void cdc::ui::ListView::setItemHeight ( uint8_t height )

inline

Set custom item height (0 = auto-calculate)

Definition at line 116 of file ListView.h.

References DEFAULT_ITEM_HEIGHT.

◆ setItemRenderer()

void cdc::ui::ListView::setItemRenderer	(	ItemRenderCallback	callback,
		void *	userCtx = nullptr )

inline

Set optional row renderer

Definition at line 98 of file ListView.h.

◆ setOnMenu()

void cdc::ui::ListView::setOnMenu ( MenuCallback callback )

inline

Set context menu callback (key '3')

Definition at line 82 of file ListView.h.

◆ setOnSelect()

void cdc::ui::ListView::setOnSelect ( SelectCallback callback )

inline

Set selection callback

Definition at line 77 of file ListView.h.

◆ setSelection()

void cdc::ui::ListView::setSelection ( uint16_t index )

Sets the selected item index.

Set current selection

Parameters

index Target selection index.

Returns: void

Definition at line 76 of file ListView.cpp.

References cdc::ui::ViewBase::dirty_.

Referenced by onLongPress().

◆ updateItem()

void cdc::ui::ListView::updateItem ( uint16_t index )

Marks the list dirty after the caller updated a backing item.

Redraw a single list row in place and partial-refresh the panel.

The backing item (in the array passed to init(), whose pointer is stored) must already be updated by the caller; this only repaints that one row, avoiding a full render() of the whole view. No-op when the item is not currently on screen (it will appear on the next scroll/render). Must be called from the UI task.

Parameters

index Item index to redraw.

Does not touch the panel: a burst of edits within one tick coalesces into a single partial refresh performed by the view-stack render cycle, instead of one e-paper refresh per edit.

Parameters

index Item index that changed.

Returns: void

Definition at line 370 of file ListView.cpp.

References cdc::ui::ViewBase::markDirty().

Member Data Documentation

◆ DEFAULT_ITEM_HEIGHT

uint8_t cdc::ui::ListView::DEFAULT_ITEM_HEIGHT = 18

staticconstexpr

Definition at line 37 of file ListView.h.

Referenced by setItemHeight().

◆ MAX_ITEMS

uint16_t cdc::ui::ListView::MAX_ITEMS = 2048

staticconstexpr

Definition at line 36 of file ListView.h.

Referenced by init(), insertItem(), and cdc::plugin_manager::PluginUiState::insertListItem().

The documentation for this class was generated from the following files:

components/cdc_views/include/cdc_views/ListView.h
components/cdc_views/src/ListView.cpp

Public Types

Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ItemRenderCallback

◆ MenuCallback

◆ SelectCallback

Member Function Documentation

◆ getFooterHint()

◆ getItemCount()

◆ getName()

◆ getSelectedItem()

◆ getSelection()

◆ init()

◆ insertItem()

◆ onKey()

◆ onLongPress()

◆ preservePosition()

◆ removeItem()

◆ render()

◆ repaintPartial()

◆ setEditMutex()

◆ setEmptyText()

◆ setHint()

◆ setItemHeight()

◆ setItemRenderer()

◆ setOnMenu()

◆ setOnSelect()

◆ setSelection()

◆ updateItem()

Member Data Documentation

◆ DEFAULT_ITEM_HEIGHT

◆ MAX_ITEMS