Push prebuilt UI views onto the system view stack. More...

Classes
struct	ui_item_t

Macros
#define	UI_ICON_NONE 0
#define	UI_ICON_SUCCESS 1 /* smiley */
#define	UI_ICON_ERROR 2 /* dark smiley */
#define	UI_ICON_HEART 3 /* favorite */
#define	UI_ICON_DIAMOND 4
#define	UI_ICON_CLUB 5
#define	UI_ICON_SPADE 6
#define	UI_ICON_BULLET 7
#define	UI_ICON_INVERSE_BULLET 8 /* remove / delete */
#define	UI_ICON_CIRCLE 9 /* info / hollow circle */
#define	UI_ICON_INVERSE_CIRCLE 0x0A
#define	UI_ICON_MALE 0x0B
#define	UI_ICON_FEMALE 0x0C
#define	UI_ICON_MUSIC 0x0D
#define	UI_ICON_NOTES 0x0E /* scene / playlist */
#define	UI_ICON_SUN 0x0F /* brightness / light */
#define	UI_ICON_PLAY 0x10 /* action / switch / submenu */
#define	UI_ICON_REVERSE_PLAY 0x11 /* back */
#define	UI_ICON_UPDOWN 0x12 /* cover / vertical adjust */
#define	UI_ICON_ALERT 0x13 /* double exclamation */
#define	UI_ICON_PARAGRAPH 0x14
#define	UI_ICON_SECTION 0x15
#define	UI_ICON_BAR 0x16 /* sensor / list / count */
#define	UI_ICON_UPDOWN_BAR 0x17
#define	UI_ICON_ARROW_UP 0x18
#define	UI_ICON_ARROW_DOWN 0x19
#define	UI_ICON_ARROW_RIGHT 0x1A
#define	UI_ICON_ARROW_LEFT 0x1B
#define	UI_ICON_ANGLE 0x1C
#define	UI_ICON_LEFTRIGHT 0x1D
#define	UI_ICON_TRIANGLE_UP 0x1E
#define	UI_ICON_TRIANGLE_DOWN 0x1F
#define	UI_ICON_INFO UI_ICON_CIRCLE
#define	UI_ICON_TASK UI_ICON_PLAY
#define	UI_ICON_REMOVE UI_ICON_INVERSE_BULLET
#define	UI_ICON_LIGHT UI_ICON_SUN
#define	UI_ICON_COVER UI_ICON_UPDOWN
#define	UI_ICON_SENSOR UI_ICON_BAR
#define	UI_ICON_SWITCH UI_ICON_PLAY
#define	UI_ICON_SCENE UI_ICON_NOTES
#define	UI_ICON_BACK UI_ICON_REVERSE_PLAY

Functions
int	host_ui_push_toast (const char *text, uint8_t icon, uint16_t duration_ms)
	Show a transient toast overlay.
int	host_ui_push_message (const char *text, uint8_t icon, uint32_t duration_ms)
	Show a blocking message view that auto-dismisses after duration_ms.
int	host_ui_push_confirm (const char *text, uint8_t icon, uint32_t action_id)
	Show a Y/N confirmation.
int	host_ui_push_info (const char title, const char body)
	Show a scrollable info screen with title and body.
int	host_ui_push_context_menu (const char title, const ui_item_t items, uint16_t count, uint32_t select_action_id)
	Show a context menu.
int	host_ui_push_t9_input (const char title, const char initial, uint16_t max_len, uint32_t action_id)
	Show a T9-style text entry.
int	host_ui_push_password (const char title, const char initial, uint16_t max_len, uint32_t action_id)
	Show a password entry (masked T9).
int	host_ui_push_pin_entry (const char *title, uint8_t max_len, uint8_t max_attempts, uint32_t action_id)
	Show a numeric PIN entry.
int	host_ui_push_slider (const char title, int32_t min, int32_t max, int32_t init, int32_t step, const char unit, uint32_t action_id)
	Show an integer slider.
int	host_ui_push_color_picker (uint8_t initial_r, uint8_t initial_g, uint8_t initial_b, uint32_t action_id)
	Show an RGB color picker.
int	host_ui_push_date (const char *title, uint8_t d, uint8_t m, uint16_t y, uint32_t action_id)
	Show a date picker.
int	host_ui_push_time (const char *title, uint8_t h, uint8_t m, uint32_t action_id)
	Show a time-of-day picker.
int	host_ui_push_list (const char title, const ui_item_t items, uint16_t count, uint32_t select_action_id, uint32_t menu_action_id)
	Show a list view.
int	host_ui_replace_list (const char title, const ui_item_t items, uint16_t count, uint32_t select_action_id, uint32_t menu_action_id)
	Replace the plugin's top list view in place; falls back to push when none.
int	host_ui_set_view_footer (const char *hint)
	Override the footer hint of the plugin's current top view.
int	host_ui_set_view_empty (const char *text)
	Override the empty-state text shown by an empty list view.
int	host_ui_set_view_lifecycle (uint32_t hide_action_id, uint32_t show_action_id)
	Register hide/show callbacks for the plugin's current top view.
int	host_ui_update_list_item (uint16_t index, const ui_item_t *item)
	Update one list row in place (partial redraw).
int	host_ui_insert_list_item (uint16_t index, const ui_item_t *item)
	Insert a list row at index (partial redraw).
int	host_ui_remove_list_item (uint16_t index)
	Remove the list row at index (partial redraw).
int	host_ui_pop (void)
	Pop the topmost view.
int	host_ui_pop_to_plugin (void)
	Pop back to the plugin's first view.
int	host_ui_repaint (void)
	Force a repaint of the current view.
int	host_ui_consume_input_text (char *out, size_t out_size)
	Read text input committed by the most recent input view.
int	host_ui_consume_input_int (int32_t *out)
	Read integer input committed by the most recent input view.
int	host_ui_acquire_exclusive (void)
	Claim exclusive UI ownership (block other plugins from pushing views).
int	host_ui_release_exclusive (void)
	Release a previously acquired exclusive UI lock.
int	host_ui_set_inactivity (uint32_t timeout_ms, uint32_t action_id)
	Arm an inactivity timer for the plugin's current view.
int	host_ui_wink (uint8_t count, uint16_t period_ms)
	Blink the backlight as a visual identification signal.

Detailed Description

Push prebuilt UI views onto the system view stack.

Plugins drive the UI by pushing high-level views (toasts, lists, T9 inputs, sliders, ...) and reacting to action callbacks. Input results are read back with host_ui_consume_input_text or host_ui_consume_input_int.

Macro Definition Documentation

◆ UI_ICON_ALERT

#define UI_ICON_ALERT 0x13 /* double exclamation */

Definition at line 754 of file host_api.h.

◆ UI_ICON_ANGLE

#define UI_ICON_ANGLE 0x1C

Definition at line 763 of file host_api.h.

◆ UI_ICON_ARROW_DOWN

#define UI_ICON_ARROW_DOWN 0x19

Definition at line 760 of file host_api.h.

◆ UI_ICON_ARROW_LEFT

#define UI_ICON_ARROW_LEFT 0x1B

Definition at line 762 of file host_api.h.

◆ UI_ICON_ARROW_RIGHT

#define UI_ICON_ARROW_RIGHT 0x1A

Definition at line 761 of file host_api.h.

◆ UI_ICON_ARROW_UP

#define UI_ICON_ARROW_UP 0x18

Definition at line 759 of file host_api.h.

◆ UI_ICON_BACK

#define UI_ICON_BACK UI_ICON_REVERSE_PLAY

Definition at line 778 of file host_api.h.

◆ UI_ICON_BAR

#define UI_ICON_BAR 0x16 /* sensor / list / count */

Definition at line 757 of file host_api.h.

◆ UI_ICON_BULLET

#define UI_ICON_BULLET 7

Definition at line 742 of file host_api.h.

◆ UI_ICON_CIRCLE

#define UI_ICON_CIRCLE 9 /* info / hollow circle */

Definition at line 744 of file host_api.h.

◆ UI_ICON_CLUB

#define UI_ICON_CLUB 5

Definition at line 740 of file host_api.h.

◆ UI_ICON_COVER

#define UI_ICON_COVER UI_ICON_UPDOWN

Definition at line 774 of file host_api.h.

◆ UI_ICON_DIAMOND

#define UI_ICON_DIAMOND 4

Definition at line 739 of file host_api.h.

◆ UI_ICON_ERROR

#define UI_ICON_ERROR 2 /* dark smiley */

Definition at line 737 of file host_api.h.

◆ UI_ICON_FEMALE

#define UI_ICON_FEMALE 0x0C

Definition at line 747 of file host_api.h.

◆ UI_ICON_HEART

#define UI_ICON_HEART 3 /* favorite */

Definition at line 738 of file host_api.h.

◆ UI_ICON_INFO

#define UI_ICON_INFO UI_ICON_CIRCLE

Definition at line 770 of file host_api.h.

◆ UI_ICON_INVERSE_BULLET

#define UI_ICON_INVERSE_BULLET 8 /* remove / delete */

Definition at line 743 of file host_api.h.

◆ UI_ICON_INVERSE_CIRCLE

#define UI_ICON_INVERSE_CIRCLE 0x0A

Definition at line 745 of file host_api.h.

◆ UI_ICON_LEFTRIGHT

#define UI_ICON_LEFTRIGHT 0x1D

Definition at line 764 of file host_api.h.

◆ UI_ICON_LIGHT

#define UI_ICON_LIGHT UI_ICON_SUN

Definition at line 773 of file host_api.h.

◆ UI_ICON_MALE

#define UI_ICON_MALE 0x0B

Definition at line 746 of file host_api.h.

◆ UI_ICON_MUSIC

#define UI_ICON_MUSIC 0x0D

Definition at line 748 of file host_api.h.

◆ UI_ICON_NONE

#define UI_ICON_NONE 0

Definition at line 735 of file host_api.h.

◆ UI_ICON_NOTES

#define UI_ICON_NOTES 0x0E /* scene / playlist */

Definition at line 749 of file host_api.h.

◆ UI_ICON_PARAGRAPH

#define UI_ICON_PARAGRAPH 0x14

Definition at line 755 of file host_api.h.

◆ UI_ICON_PLAY

#define UI_ICON_PLAY 0x10 /* action / switch / submenu */

Definition at line 751 of file host_api.h.

◆ UI_ICON_REMOVE

#define UI_ICON_REMOVE UI_ICON_INVERSE_BULLET

Definition at line 772 of file host_api.h.

◆ UI_ICON_REVERSE_PLAY

#define UI_ICON_REVERSE_PLAY 0x11 /* back */

Definition at line 752 of file host_api.h.

◆ UI_ICON_SCENE

#define UI_ICON_SCENE UI_ICON_NOTES

Definition at line 777 of file host_api.h.

◆ UI_ICON_SECTION

#define UI_ICON_SECTION 0x15

Definition at line 756 of file host_api.h.

◆ UI_ICON_SENSOR

#define UI_ICON_SENSOR UI_ICON_BAR

Definition at line 775 of file host_api.h.

◆ UI_ICON_SPADE

#define UI_ICON_SPADE 6

Definition at line 741 of file host_api.h.

◆ UI_ICON_SUCCESS

#define UI_ICON_SUCCESS 1 /* smiley */

Definition at line 736 of file host_api.h.

◆ UI_ICON_SUN

#define UI_ICON_SUN 0x0F /* brightness / light */

Definition at line 750 of file host_api.h.

◆ UI_ICON_SWITCH

#define UI_ICON_SWITCH UI_ICON_PLAY

Definition at line 776 of file host_api.h.

◆ UI_ICON_TASK

#define UI_ICON_TASK UI_ICON_PLAY

Definition at line 771 of file host_api.h.

◆ UI_ICON_TRIANGLE_DOWN

#define UI_ICON_TRIANGLE_DOWN 0x1F

Definition at line 766 of file host_api.h.

◆ UI_ICON_TRIANGLE_UP

#define UI_ICON_TRIANGLE_UP 0x1E

Definition at line 765 of file host_api.h.

◆ UI_ICON_UPDOWN

#define UI_ICON_UPDOWN 0x12 /* cover / vertical adjust */

Definition at line 753 of file host_api.h.

◆ UI_ICON_UPDOWN_BAR

#define UI_ICON_UPDOWN_BAR 0x17

Definition at line 758 of file host_api.h.

Function Documentation

◆ host_ui_acquire_exclusive()

int host_ui_acquire_exclusive ( void )

Claim exclusive UI ownership (block other plugins from pushing views).

Definition at line 120 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::acquireExclusive(), and cdc::plugin_manager::PluginUiState::instance().

Referenced by cdc::plugin_manager::w_host_ui_acquire_exclusive().

◆ host_ui_consume_input_int()

int host_ui_consume_input_int ( int32_t * out )

Read integer input committed by the most recent input view.

Definition at line 142 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::consumeInputInt(), and cdc::plugin_manager::PluginUiState::instance().

Referenced by cdc::plugin_manager::w_host_ui_consume_input_int().

◆ host_ui_consume_input_text()

int host_ui_consume_input_text	(	char *	out,
		size_t	out_size )

Read text input committed by the most recent input view.

Definition at line 136 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::consumeInputText(), and cdc::plugin_manager::PluginUiState::instance().

Referenced by cdc::plugin_manager::w_host_ui_consume_input_text().

◆ host_ui_insert_list_item()

int host_ui_insert_list_item	(	uint16_t	index,
		const ui_item_t *	item )

Insert a list row at index (partial redraw).

Definition at line 51 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::insertListItem(), and cdc::plugin_manager::PluginUiState::instance().

Referenced by cdc::plugin_manager::w_host_ui_insert_list_item().

◆ host_ui_pop()

int host_ui_pop ( void )

Pop the topmost view.

Definition at line 66 of file host_api_ui.cpp.

References HOST_OK, and cdc::ui::ViewStack::instance().

Referenced by cdc::plugin_manager::w_host_ui_pop().

◆ host_ui_pop_to_plugin()

int host_ui_pop_to_plugin ( void )

Pop back to the plugin's first view.

Pops every view the plugin pushed during or after plugin_on_enter, back to its first view (the stack depth recorded at entry). Views below the plugin are untouched. No-op if the plugin pushed nothing.

Definition at line 81 of file host_api_ui.cpp.

References HOST_OK, cdc::plugin_manager::PluginManager::instance(), cdc::ui::ViewStack::instance(), cdc::plugin_manager::PluginManager::pluginBaseDepth(), and cdc::ui::ViewStack::popToDepth().

Referenced by cdc::plugin_manager::w_host_ui_pop_to_plugin().

◆ host_ui_push_color_picker()

int host_ui_push_color_picker	(	uint8_t	initial_r,
		uint8_t	initial_g,
		uint8_t	initial_b,
		uint32_t	action_id )

Show an RGB color picker.

Definition at line 102 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::instance(), and cdc::plugin_manager::PluginUiState::pushColorPicker().

Referenced by cdc::plugin_manager::w_host_ui_push_color_picker().

◆ host_ui_push_confirm()

int host_ui_push_confirm	(	const char *	text,
		uint8_t	icon,
		uint32_t	action_id )

Show a Y/N confirmation.

Parameters

action_id Fired with user_data = 1 on Y, user_data = 0 on N (idx unused).

Definition at line 68 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::instance(), and cdc::plugin_manager::PluginUiState::pushConfirm().

Referenced by cdc::plugin_manager::w_host_ui_push_confirm().

◆ host_ui_push_context_menu()

int host_ui_push_context_menu	(	const char *	title,
		const ui_item_t *	items,
		uint16_t	count,
		uint32_t	select_action_id )

Show a context menu.

Parameters

select_action_id Fired on selection with idx = selected item position (0-based) and user_data = items[i].item_id.

Definition at line 61 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::instance(), and cdc::plugin_manager::PluginUiState::pushContextMenu().

Referenced by cdc::plugin_manager::w_host_ui_push_context_menu().

◆ host_ui_push_date()

int host_ui_push_date	(	const char *	title,
		uint8_t	d,
		uint8_t	m,
		uint16_t	y,
		uint32_t	action_id )

Show a date picker.

Definition at line 108 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::instance(), and cdc::plugin_manager::PluginUiState::pushDate().

Referenced by cdc::plugin_manager::w_host_ui_push_date().

◆ host_ui_push_info()

int host_ui_push_info	(	const char *	title,
		const char *	body )

Show a scrollable info screen with title and body.

Definition at line 55 of file host_api_ui.cpp.

References HOST_ERR_INVALID_ARG, HOST_OK, cdc::ui::ViewStack::instance(), cdc::ui::ViewStack::push(), and cdc::plugin_manager::toDisplay().

Referenced by host_fs_view(), and cdc::plugin_manager::w_host_ui_push_info().

◆ host_ui_push_list()

int host_ui_push_list	(	const char *	title,
		const ui_item_t *	items,
		uint16_t	count,
		uint32_t	select_action_id,
		uint32_t	menu_action_id )

Show a list view.

Parameters

select_action_id	Fired on item select with idx = selected row index and user_data = items[i].item_id.
menu_action_id	Fired when the user opens the per-item context menu (same idx/user_data as select); 0 to disable.

Definition at line 16 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::instance(), and cdc::plugin_manager::PluginUiState::pushList().

◆ host_ui_push_message()

int host_ui_push_message	(	const char *	text,
		uint8_t	icon,
		uint32_t	duration_ms )

Show a blocking message view that auto-dismisses after duration_ms.

Definition at line 50 of file host_api_ui.cpp.

References host_ui_push_toast().

Referenced by cdc::plugin_manager::w_host_ui_push_message().

◆ host_ui_push_password()

int host_ui_push_password	(	const char *	title,
		const char *	initial,
		uint16_t	max_len,
		uint32_t	action_id )

Show a password entry (masked T9).

Parameters

initial	Pre-filled text, or NULL/empty for blank.
action_id	Same contract as host_ui_push_t9_input: confirm fires with user_data = 1 and idx = text length; cancel fires with user_data = 0.

Definition at line 81 of file host_api_ui_views.cpp.

References host_ui_push_t9_input().

Referenced by cdc::plugin_manager::w_host_ui_push_password().

◆ host_ui_push_pin_entry()

int host_ui_push_pin_entry	(	const char *	title,
		uint8_t	max_len,
		uint8_t	max_attempts,
		uint32_t	action_id )

Show a numeric PIN entry.

Parameters

max_attempts	0 for unlimited.
action_id	On confirm fires with user_data = 1 and idx = PIN length; on cancel fires with user_data = 0. The view pops itself first.

Definition at line 88 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::instance(), and cdc::plugin_manager::PluginUiState::pushPin().

Referenced by cdc::plugin_manager::w_host_ui_push_pin_entry().

◆ host_ui_push_slider()

int host_ui_push_slider	(	const char *	title,
		int32_t	min,
		int32_t	max,
		int32_t	init,
		int32_t	step,
		const char *	unit,
		uint32_t	action_id )

Show an integer slider.

Definition at line 95 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::instance(), and cdc::plugin_manager::PluginUiState::pushSlider().

Referenced by cdc::plugin_manager::w_host_ui_push_slider().

◆ host_ui_push_t9_input()

int host_ui_push_t9_input	(	const char *	title,
		const char *	initial,
		uint16_t	max_len,
		uint32_t	action_id )

Show a T9-style text entry.

Parameters

initial	Pre-filled text, or NULL/empty for blank.
action_id	Fired on both outcomes; the view pops itself before it fires. On confirm: user_data = 1, idx = entered text length, read the text via host_ui_consume_input_text. On cancel: user_data = 0, idx = 0 and no text is pending (host_ui_consume_input_text returns nothing).

Definition at line 74 of file host_api_ui_views.cpp.

References cdc::plugin_manager::PluginUiState::instance(), and cdc::plugin_manager::PluginUiState::pushT9().

Referenced by host_ui_push_password(), and cdc::plugin_manager::w_host_ui_push_t9_input().