Plugin-drawn custom views with inline interactive widgets. More...

Macros
#define	CANVAS_WIDGET_CHANGED 1
#define	CANVAS_WIDGET_COMMITTED 2
#define	CANVAS_WIDGET_CANCELLED 3
#define	HOST_FONT_BUILTIN 0
	Adafruit-GFX 6x8; CP437 codepoints for umlauts.
#define	HOST_FONT_BOLD_9PT 1
	FreeMonoBold 9pt; Latin-1 indexed.
#define	HOST_FONT_BOLD_12PT 2
	FreeMonoBold 12pt; Latin-1 indexed.
#define	HOST_FONT_BOLD_18PT 3
	FreeMonoBold 18pt; ASCII only.
#define	HOST_FONT_BOLD_24PT 4
	FreeMonoBold 24pt; ASCII only.
#define	HOST_FONT_COUNT 5
	Number of defined font ids.

Functions
int	host_view_canvas_push (const char *title, uint32_t key_action_id, uint32_t widget_action_id)
	Push a new canvas view.
int	host_view_canvas_get_body_size (uint16_t w, uint16_t h)
	Read the drawable body region (excluding header/footer).
int	host_view_canvas_set_footer (const char *hint)
	Override the footer hint of the canvas.
int	host_view_canvas_clear (void)
	Clear all draw state and widgets.
int	host_view_canvas_set_text_size (uint8_t size)
	Set text size multiplier (Adafruit-GFX semantics).
int	host_view_canvas_set_font (uint8_t font_id)
	Switch the canvas font to one of the canonical HOST_FONT_* ids.
int	host_text_pick_font_that_fits (const char text, int16_t max_width_px, const uint8_t candidates, uint32_t count, uint8_t *out_font_id)
	Pick the largest HOST_FONT_* whose rendered `text` fits within `max_width_px`. Candidates are evaluated in array order; sort them from largest to smallest. Falls back to the last entry when nothing fits.
int	host_view_canvas_set_text_color (bool inverted)
	Switch between normal and inverted (white on black) text.
int	host_view_canvas_draw_text (int16_t x, int16_t y, const char *text)
	Draw text at (x, y) using the current text size/colour.
int	host_view_canvas_draw_text_aligned (int16_t x, int16_t y, int16_t w, const char *text, uint8_t align)
	Draw text within a horizontal box.
int	host_view_canvas_draw_rect (int16_t x, int16_t y, int16_t w, int16_t h, bool filled)
	Draw a rectangle outline or filled rectangle.
int	host_view_canvas_invert_rect (int16_t x, int16_t y, int16_t w, int16_t h)
	Invert all pixels inside the rectangle.
int	host_view_canvas_hline (int16_t x, int16_t y, int16_t w)
	Draw a horizontal line.
int	host_view_canvas_vline (int16_t x, int16_t y, int16_t h)
	Draw a vertical line.
int	host_view_canvas_commit (bool full_refresh)
	Flush draw state to the panel.
int	host_view_canvas_add_slider (uint32_t widget_id, int32_t min, int32_t max, int32_t initial, int32_t step)
	Add an integer slider widget bound to widget_id.
int	host_view_canvas_add_text (uint32_t widget_id, uint16_t max_len, const char *initial)
	Add a T9 text input widget bound to widget_id.
int	host_view_canvas_add_button (uint32_t widget_id)
	Add a focusable button widget bound to widget_id.
int	host_view_canvas_remove_widget (uint32_t widget_id)
	Remove a widget previously added to the canvas.
int	host_view_canvas_set_value (uint32_t widget_id, int32_t value)
	Set the integer value of a slider widget.
int	host_view_canvas_get_value (uint32_t widget_id, int32_t *out)
	Read the integer value of a slider widget.
int	host_view_canvas_set_text (uint32_t widget_id, const char *text)
	Set the text of a text-input widget.
int	host_view_canvas_get_text (uint32_t widget_id, char *out, size_t cap)
	Read the text of a text-input widget.
int	host_view_canvas_set_focus (uint32_t widget_id)
	Move keyboard focus to the given widget.
int	host_view_canvas_get_focus (uint32_t *out)
	Read the currently focused widget id, 0 if none.
int	host_view_canvas_set_key_repeat (uint16_t initial_ms, uint16_t repeat_ms)
	Configure key auto-repeat timing for the canvas.
int	host_view_canvas_set_long_press_action (uint32_t action_id)
	Set the action id fired on a canvas long-press.

Detailed Description

Plugin-drawn custom views with inline interactive widgets.

Push one canvas, then issue draw commands and add widgets that the host routes key events to. Commit when ready to refresh the display.

Macro Definition Documentation

◆ CANVAS_WIDGET_CANCELLED

#define CANVAS_WIDGET_CANCELLED 3

Definition at line 978 of file host_api.h.

◆ CANVAS_WIDGET_CHANGED

#define CANVAS_WIDGET_CHANGED 1

Definition at line 976 of file host_api.h.

◆ CANVAS_WIDGET_COMMITTED

#define CANVAS_WIDGET_COMMITTED 2

Definition at line 977 of file host_api.h.

◆ HOST_FONT_BOLD_12PT

#define HOST_FONT_BOLD_12PT 2

FreeMonoBold 12pt; Latin-1 indexed.

Definition at line 1004 of file host_api.h.

◆ HOST_FONT_BOLD_18PT

#define HOST_FONT_BOLD_18PT 3

FreeMonoBold 18pt; ASCII only.

Definition at line 1005 of file host_api.h.

◆ HOST_FONT_BOLD_24PT

#define HOST_FONT_BOLD_24PT 4

FreeMonoBold 24pt; ASCII only.

Definition at line 1006 of file host_api.h.

◆ HOST_FONT_BOLD_9PT

#define HOST_FONT_BOLD_9PT 1

FreeMonoBold 9pt; Latin-1 indexed.

Definition at line 1003 of file host_api.h.

◆ HOST_FONT_BUILTIN

#define HOST_FONT_BUILTIN 0

Adafruit-GFX 6x8; CP437 codepoints for umlauts.

Definition at line 1002 of file host_api.h.

◆ HOST_FONT_COUNT

#define HOST_FONT_COUNT 5

Number of defined font ids.

Definition at line 1007 of file host_api.h.

Referenced by host_text_pick_font_that_fits(), and host_view_canvas_set_font().

Function Documentation

◆ host_text_pick_font_that_fits()

int host_text_pick_font_that_fits	(	const char *	text,
		int16_t	max_width_px,
		const uint8_t *	candidates,
		uint32_t	count,
		uint8_t *	out_font_id )

Pick the largest HOST_FONT_* whose rendered text fits within max_width_px. Candidates are evaluated in array order; sort them from largest to smallest. Falls back to the last entry when nothing fits.

Pure measurement; does not change canvas state. Pair with host_view_canvas_set_font to apply the picked font.

Parameters

text	Null-terminated string to measure.
max_width_px	Pixel budget.
candidates	Array of HOST_FONT_* ids.
count	Number of entries in `candidates`.
out_font_id	Receives the chosen font id.

Returns: HOST_OK on success, HOST_ERR_INVALID_ARG for empty input.

Definition at line 84 of file host_api_canvas.cpp.

References cdc::hal::getDisplayInstance(), cdc::ui::getGfxFont(), HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, HOST_FONT_COUNT, HOST_OK, cdc::ui::render::pickFontThatFits(), and cdc::plugin_manager::toDisplay().

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

◆ host_view_canvas_add_button()

int host_view_canvas_add_button ( uint32_t widget_id )

Add a focusable button widget bound to widget_id.

Definition at line 190 of file host_api_canvas.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_add_slider()

int host_view_canvas_add_slider	(	uint32_t	widget_id,
		int32_t	min,
		int32_t	max,
		int32_t	initial,
		int32_t	step )

Add an integer slider widget bound to widget_id.

Definition at line 173 of file host_api_canvas.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_add_text()

int host_view_canvas_add_text	(	uint32_t	widget_id,
		uint16_t	max_len,
		const char *	initial )

Add a T9 text input widget bound to widget_id.

Definition at line 181 of file host_api_canvas.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, HOST_OK, and cdc::plugin_manager::toDisplay().

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

◆ host_view_canvas_clear()

int host_view_canvas_clear ( void )

Clear all draw state and widgets.

Definition at line 51 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_commit()

int host_view_canvas_commit ( bool full_refresh )

Flush draw state to the panel.

Parameters

full_refresh true to force a full e-paper refresh, false for partial.

Definition at line 165 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_draw_rect()

int host_view_canvas_draw_rect	(	int16_t	x,
		int16_t	y,
		int16_t	w,
		int16_t	h,
		bool	filled )

Draw a rectangle outline or filled rectangle.

Definition at line 133 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_draw_text()

int host_view_canvas_draw_text	(	int16_t	x,
		int16_t	y,
		const char *	text )

Draw text at (x, y) using the current text size/colour.

Definition at line 116 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, HOST_OK, and cdc::plugin_manager::toDisplay().

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

◆ host_view_canvas_draw_text_aligned()

int host_view_canvas_draw_text_aligned	(	int16_t	x,
		int16_t	y,
		int16_t	w,
		const char *	text,
		uint8_t	align )

Draw text within a horizontal box.

Parameters

align 0 = left, 1 = center, 2 = right.

Definition at line 124 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, HOST_OK, and cdc::plugin_manager::toDisplay().

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

◆ host_view_canvas_get_body_size()

int host_view_canvas_get_body_size	(	uint16_t *	w,
		uint16_t *	h )

Read the drawable body region (excluding header/footer).

Definition at line 38 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_get_focus()

int host_view_canvas_get_focus ( uint32_t * out )

Read the currently focused widget id, 0 if none.

Definition at line 246 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_get_text()

int host_view_canvas_get_text	(	uint32_t	widget_id,
		char *	out,
		size_t	cap )

Read the text of a text-input widget.

Definition at line 226 of file host_api_canvas.cpp.

References cdc::plugin_manager::copyUtf8(), HOST_ERR_INVALID_ARG, and HOST_ERR_NOT_FOUND.

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

◆ host_view_canvas_get_value()

int host_view_canvas_get_value	(	uint32_t	widget_id,
		int32_t *	out )

Read the integer value of a slider widget.

Definition at line 211 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_hline()

int host_view_canvas_hline	(	int16_t	x,
		int16_t	y,
		int16_t	w )

Draw a horizontal line.

Definition at line 149 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_invert_rect()

int host_view_canvas_invert_rect	(	int16_t	x,
		int16_t	y,
		int16_t	w,
		int16_t	h )

Invert all pixels inside the rectangle.

Definition at line 141 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_push()

int host_view_canvas_push	(	const char *	title,
		uint32_t	key_action_id,
		uint32_t	widget_action_id )

Push a new canvas view.

Parameters

key_action_id	Fired on raw key events not consumed by a focused widget, with idx = focused widget id and user_data = the ASCII key code.
widget_action_id	Fired for widget interaction events with idx = widget id and user_data = the event subtype (see CANVAS_WIDGET_*).

Definition at line 31 of file host_api_canvas.cpp.

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

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

◆ host_view_canvas_remove_widget()

int host_view_canvas_remove_widget ( uint32_t widget_id )

Remove a widget previously added to the canvas.

Definition at line 197 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_set_focus()

int host_view_canvas_set_focus ( uint32_t widget_id )

Move keyboard focus to the given widget.

Definition at line 239 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_set_font()

int host_view_canvas_set_font ( uint8_t font_id )

Switch the canvas font to one of the canonical HOST_FONT_* ids.

Persists across draw calls until the next host_view_canvas_clear or a further set_font call. All text drawing functions take UTF-8; the host renders umlauts correctly for whichever font is active, both the builtin 6x8 font (HOST_FONT_BUILTIN) and the Latin-1-indexed FreeMonoBold fonts.

Parameters

font_id One of HOST_FONT_*.

Returns: HOST_OK on success, HOST_ERR_INVALID_ARG for out-of-range ids.

Definition at line 75 of file host_api_canvas.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, HOST_FONT_COUNT, and HOST_OK.

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

◆ host_view_canvas_set_footer()

int host_view_canvas_set_footer ( const char * hint )

Override the footer hint of the canvas.

Definition at line 46 of file host_api_canvas.cpp.

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

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

◆ host_view_canvas_set_key_repeat()

int host_view_canvas_set_key_repeat	(	uint16_t	initial_ms,
		uint16_t	repeat_ms )

Configure key auto-repeat timing for the canvas.

Parameters

initial_ms	Delay before the first repeat.
repeat_ms	Period between subsequent repeats.

Definition at line 254 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

◆ host_view_canvas_set_long_press_action()

int host_view_canvas_set_long_press_action ( uint32_t action_id )

Set the action id fired on a canvas long-press.

Registering a non-zero action opts the canvas into deferred short-press input: a tap fires the key callback on release while a hold (>= long-press threshold) fires this action with idx = 0 and user_data = the ASCII key code, and suppresses the short press. Pass 0 to disable.

Parameters

action_id Action fired on long-press, or 0 to disable.

Definition at line 262 of file host_api_canvas.cpp.

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

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