UI - Canvas view

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_CANVAS_CLEAR_KEEP_SPRITES   0x01
#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.
#define	HOST_CANVAS_ANIM_REFRESH_AUTO
#define	HOST_CANVAS_ANIM_REFRESH_LIGHT

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. Equals host_view_canvas_clear_ex(0).
int	host_view_canvas_clear_ex (uint32_t flags)
	Clear with options: like host_view_canvas_clear, but HOST_CANVAS_CLEAR_KEEP_SPRITES keeps the sprite store intact.
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_set_shade (uint8_t shade)
	Set the fill ink for subsequent filled shapes (rect, circle, triangle).
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_draw_pixel (int16_t x, int16_t y)
	Draw a single pixel.
int	host_view_canvas_draw_line (int16_t x0, int16_t y0, int16_t x1, int16_t y1)
	Draw a line between two points.
int	host_view_canvas_draw_circle (int16_t x, int16_t y, int16_t r, bool filled)
	Draw a circle outline or filled circle of radius r centred at (x, y).
int	host_view_canvas_draw_triangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, bool filled)
	Draw a triangle outline or filled triangle through three points.
int	host_view_canvas_draw_round_rect (int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, bool filled)
	Draw a rounded rectangle outline or filled, corner radius r.
int	host_view_canvas_draw_bitmap (int16_t x, int16_t y, int16_t w, int16_t h, const uint8_t *data, uint32_t len)
	Draw a 1-bpp bitmap; set bits render black, unset bits are transparent.
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_elem_begin (uint32_t elem_id)
	Start recording draw calls under element elem_id.
int	host_view_canvas_elem_end (void)
	Stop recording draw calls into an element.
int	host_view_canvas_elem_set_offset (uint32_t elem_id, int16_t ox, int16_t oy)
	Set an element's replay offset relative to its recorded coordinates.
int	host_view_canvas_elem_move (uint32_t elem_id, int16_t dx, int16_t dy)
	Shift an element's replay offset by a delta.
int	host_view_canvas_elem_show (uint32_t elem_id, bool visible)
	Show or hide an element (hidden elements are skipped on replay).
int	host_view_canvas_elem_remove (uint32_t elem_id)
	Remove an element and all draw commands recorded under it.
int	host_view_canvas_elem_clear (uint32_t elem_id)
	Drop only an element's recorded draw commands, keeping the element.
int	host_view_canvas_elem_set_z (uint32_t elem_id, int8_t z)
	Set an element's replay layer (z-order).
int	host_view_canvas_elem_get_offset (uint32_t elem_id, int16_t *ox, int16_t *oy)
	Read an element's current replay offset.
int	host_view_canvas_elem_get_bounds (uint32_t elem_id, int16_t *x, int16_t *y, uint16_t *w, uint16_t *h)
	Bounding box of an element's recorded commands, offset applied.
int	host_view_canvas_set_anim_policy (uint8_t refresh_policy, uint8_t max_fps)
	Configure host-driven animation pacing for the current canvas.
int	host_view_canvas_draw_sprite (int16_t x, int16_t y, uint32_t sprite)
	Record a draw of a sprite's current frame at (x, y).
int	host_view_canvas_set_ink (bool white)
	Draw subsequent shapes in white instead of black.
int	host_view_canvas_marquee (int16_t x, int16_t y, int16_t window_w, const char *text, uint16_t step_px, uint16_t frame_ms)
	Record a host-driven text marquee (ticker).
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 1102 of file host_api.h.

CANVAS_WIDGET_CHANGED

#define CANVAS_WIDGET_CHANGED   1

Definition at line 1100 of file host_api.h.

CANVAS_WIDGET_COMMITTED

#define CANVAS_WIDGET_COMMITTED   2

Definition at line 1101 of file host_api.h.

HOST_CANVAS_ANIM_REFRESH_AUTO

#define HOST_CANVAS_ANIM_REFRESH_AUTO

Value:

0 /* flash-free while running, one FAST
cleanup ~1 s after going idle    */

Definition at line 1348 of file host_api.h.

HOST_CANVAS_ANIM_REFRESH_LIGHT

#define HOST_CANVAS_ANIM_REFRESH_LIGHT

Value:

1 /* never clean up automatically;
plugin manages ghosting itself   */

Definition at line 1349 of file host_api.h.

HOST_CANVAS_CLEAR_KEEP_SPRITES

#define HOST_CANVAS_CLEAR_KEEP_SPRITES   0x01

Sprite assets survive the clear.

Definition at line 1124 of file host_api.h.

Referenced by host_view_canvas_clear_ex().

HOST_FONT_BOLD_12PT

#define HOST_FONT_BOLD_12PT   2

FreeMonoBold 12pt; Latin-1 indexed.

Definition at line 1147 of file host_api.h.

HOST_FONT_BOLD_18PT

#define HOST_FONT_BOLD_18PT   3

FreeMonoBold 18pt; ASCII only.

Definition at line 1148 of file host_api.h.

HOST_FONT_BOLD_24PT

#define HOST_FONT_BOLD_24PT   4

FreeMonoBold 24pt; ASCII only.

Definition at line 1149 of file host_api.h.

HOST_FONT_BOLD_9PT

#define HOST_FONT_BOLD_9PT   1

FreeMonoBold 9pt; Latin-1 indexed.

Definition at line 1146 of file host_api.h.

HOST_FONT_BUILTIN

#define HOST_FONT_BUILTIN   0

Adafruit-GFX 6x8; CP437 codepoints for umlauts.

Definition at line 1145 of file host_api.h.

HOST_FONT_COUNT

#define HOST_FONT_COUNT   5

Number of defined font ids.

Definition at line 1150 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 100 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 547 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 530 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 538 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. Equals host_view_canvas_clear_ex(0).

Definition at line 51 of file host_api_canvas.cpp.

References host_view_canvas_clear_ex().

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

host_view_canvas_clear_ex()

int host_view_canvas_clear_ex

(

uint32_t

flags

)

Clear with options: like host_view_canvas_clear, but HOST_CANVAS_CLEAR_KEEP_SPRITES keeps the sprite store intact.

Kept sprites retain frames, masks, flags, scale and the current frame index, so a plugin can create its sheets once and rebuild screens around them. Their PLAYBACK is stopped (an orphaned loop such as a marquee's backing sprite would otherwise keep the animation clock and the panel busy with nothing to show) - call host_sprite_play again after re-recording the new screen. Elements, tweens and widgets are dropped either way.

Returns

HOST_OK, HOST_ERR_INVALID_ARG (unknown flag), HOST_ERR_NOT_FOUND (no canvas).

Definition at line 56 of file host_api_canvas.cpp.

References flags, HOST_CANVAS_CLEAR_KEEP_SPRITES, HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by host_view_canvas_clear(), and cdc::plugin_manager::w_host_view_canvas_clear_ex().

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 225 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_bitmap()

int host_view_canvas_draw_bitmap	(	int16_t	x,
		int16_t	y,
		int16_t	w,
		int16_t	h,
		const uint8_t *	data,
		uint32_t	len )

Draw a 1-bpp bitmap; set bits render black, unset bits are transparent.

Rows are byte-padded (stride = (w + 7) / 8), MSB first per Adafruit-GFX convention. The pixel data is copied into the canvas, so the buffer may be reused after the call.

Parameters

data	Packed 1-bpp pixel data, length stride * h.
len	Length of data in bytes.

Definition at line 199 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_draw_bitmap().

host_view_canvas_draw_circle()

int host_view_canvas_draw_circle	(	int16_t	x,
		int16_t	y,
		int16_t	r,
		bool	filled )

Draw a circle outline or filled circle of radius r centred at (x, y).

Definition at line 173 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_draw_line()

int host_view_canvas_draw_line	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1 )

Draw a line between two points.

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_draw_line().

host_view_canvas_draw_pixel()

int host_view_canvas_draw_pixel	(	int16_t	x,
		int16_t	y )

Draw a single pixel.

Definition at line 157 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

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 149 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_round_rect()

int host_view_canvas_draw_round_rect	(	int16_t	x,
		int16_t	y,
		int16_t	w,
		int16_t	h,
		int16_t	r,
		bool	filled )

Draw a rounded rectangle outline or filled, corner radius r.

Definition at line 190 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_draw_sprite()

int host_view_canvas_draw_sprite	(	int16_t	x,
		int16_t	y,
		uint32_t	sprite )

Record a draw of a sprite's current frame at (x, y).

Draw-by-reference: one display-list slot, no pixel copy; frame changes from host_sprite_play or host_sprite_set_frame replay automatically. Record it inside an element to move, hide, layer or tween the sprite. Destroying the sprite later leaves the command recorded but skipped.

Returns

HOST_OK, HOST_ERR_NOT_FOUND (unknown sprite or no canvas), HOST_ERR_NO_MEMORY (display list full).

Definition at line 313 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

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 132 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 140 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_draw_triangle()

int host_view_canvas_draw_triangle	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		bool	filled )

Draw a triangle outline or filled triangle through three points.

Definition at line 181 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_begin()

int host_view_canvas_elem_begin

(

uint32_t

elem_id

)

Start recording draw calls under element elem_id.

Elements group draw commands so they can later be moved, hidden or removed without rebuilding the whole display list. They are the building block for animations: record an element once, then per frame adjust its offset and call host_view_canvas_commit. The element is created on first use; calling begin again with the same id appends further commands to it. Element ids live in their own namespace (unrelated to widget ids); at most 16 elements can exist at once. host_view_canvas_clear drops all elements together with the display list.

Parameters

elem_id

Non-zero element id chosen by the plugin.

Returns

HOST_OK, HOST_ERR_INVALID_ARG (id 0), HOST_ERR_NO_MEMORY (element table full), HOST_ERR_NOT_FOUND (no canvas).

Definition at line 233 of file host_api_canvas.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_clear()

int host_view_canvas_elem_clear

(

uint32_t

elem_id

)

Drop only an element's recorded draw commands, keeping the element.

Offset, visibility, z layer and running tweens survive; follow with host_view_canvas_elem_begin plus draw calls to re-record the content in place (live counters, changing labels). Arena bytes are reclaimed.

Returns

HOST_OK, HOST_ERR_NOT_FOUND (unknown element or no canvas).

Definition at line 277 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_end()

int host_view_canvas_elem_end

(

void

)

Stop recording draw calls into an element.

Subsequent draw calls are untagged (static background). Ending is implicit when host_view_canvas_elem_begin switches to another element.

Definition at line 241 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_get_bounds()

int host_view_canvas_elem_get_bounds	(	uint32_t	elem_id,
		int16_t *	x,
		int16_t *	y,
		uint16_t *	w,
		uint16_t *	h )

Bounding box of an element's recorded commands, offset applied.

Body-local pixels; useful for edge/collision checks while animating.

Returns

HOST_OK, HOST_ERR_NOT_FOUND (unknown/empty element or no canvas).

Definition at line 298 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_get_offset()

int host_view_canvas_elem_get_offset	(	uint32_t	elem_id,
		int16_t *	ox,
		int16_t *	oy )

Read an element's current replay offset.

Definition at line 291 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_move()

int host_view_canvas_elem_move	(	uint32_t	elem_id,
		int16_t	dx,
		int16_t	dy )

Shift an element's replay offset by a delta.

Returns

HOST_OK, HOST_ERR_NOT_FOUND (unknown element or no canvas).

Definition at line 256 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_remove()

int host_view_canvas_elem_remove

(

uint32_t

elem_id

)

Remove an element and all draw commands recorded under it.

Display-list slots and arena bytes are reclaimed, so elements can be removed and re-recorded repeatedly (sprite whose content changes). Call host_view_canvas_commit afterwards.

Returns

HOST_OK, HOST_ERR_NOT_FOUND (unknown element or no canvas).

Definition at line 270 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_set_offset()

int host_view_canvas_elem_set_offset	(	uint32_t	elem_id,
		int16_t	ox,
		int16_t	oy )

Set an element's replay offset relative to its recorded coordinates.

The offset is applied when the display list is replayed; call host_view_canvas_commit afterwards to show the change. (0, 0) restores the recorded position.

Returns

HOST_OK, HOST_ERR_NOT_FOUND (unknown element or no canvas).

Definition at line 249 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_set_z()

int host_view_canvas_elem_set_z	(	uint32_t	elem_id,
		int8_t	z )

Set an element's replay layer (z-order).

Layers draw in ascending order; untagged draw commands and untouched elements live in layer 0. Ties keep recording order, so existing plugins are unaffected until they opt in.

Parameters

z	Layer, -128..127 (default 0).

Returns

HOST_OK, HOST_ERR_NOT_FOUND (unknown element or no canvas).

Definition at line 284 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_elem_show()

int host_view_canvas_elem_show	(	uint32_t	elem_id,
		bool	visible )

Show or hide an element (hidden elements are skipped on replay).

Hiding keeps the element's draw commands recorded, so it can be shown again cheaply (blink patterns). Call host_view_canvas_commit afterwards.

Returns

HOST_OK, HOST_ERR_NOT_FOUND (unknown element or no canvas).

Definition at line 263 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

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 603 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 583 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 568 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 209 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_marquee()

int host_view_canvas_marquee	(	int16_t	x,
		int16_t	y,
		int16_t	window_w,
		const char *	text,
		uint16_t	step_px,
		uint16_t	frame_ms )

Record a host-driven text marquee (ticker).

The text is rendered once with the current font/size into an internal sprite; a window_w-wide window then scrolls through it seamlessly on the host clock (content + a window-sized gap, wrap-around). No per-frame plugin code and no display-list churn. Record inside an element to move, hide or layer the ticker.

Parameters

step_px

Pixels advanced per animation beat (pair with the beat duration frame_ms, floored at 50).

Returns

Backing sprite handle >= 1 (pause via host_sprite_stop, remove via host_sprite_destroy), HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND (no canvas).

Definition at line 331 of file host_api_canvas.cpp.

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

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

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 554 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_anim_policy()

int host_view_canvas_set_anim_policy	(	uint8_t	refresh_policy,
		uint8_t	max_fps )

Configure host-driven animation pacing for the current canvas.

While tweens or sprite playback are active the host advances them, commits the canvas automatically and keeps partial refreshes flash-free (no escalation mid-motion). Under AUTO (default) the panel gets one FAST cleanup refresh about a second after the last animation ends, and endless animations get a rare hygiene FAST to bound ghosting.

Parameters

refresh_policy	One of HOST_CANVAS_ANIM_REFRESH_*.
max_fps	Animation step-rate cap 1..5 (0 = default 4). The panel's partial waveform (~250 ms) makes ~5 the physical ceiling; steps are computed from elapsed time, so slow refreshes drop frames instead of slowing motion down. Think in tween durations of 500 ms and up.

Returns

HOST_OK, HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND (no canvas).

Definition at line 306 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_set_anim_policy().

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 596 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 91 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_ink()

int host_view_canvas_set_ink

(

bool

white

)

Draw subsequent shapes in white instead of black.

Applies to rects, circles, triangles, round-rects, lines and pixels recorded afterwards - an eraser for wipe transitions and cut-outs over previously drawn content (dither shades erase dithered). Text keeps its own host_view_canvas_set_text_color. Reset by host_view_canvas_clear.

Parameters

white

1 = white ink, 0 = black (default).

Definition at line 323 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

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 611 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 619 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().

host_view_canvas_set_shade()

int host_view_canvas_set_shade

(

uint8_t

shade

)

Set the fill ink for subsequent filled shapes (rect, circle, triangle).

0 = none (nothing drawn), 255 = solid black (default). Values in between are rendered as an ordered-dither grey approximation (8x8 Bayer, ~64 levels) so a 1-bpp panel can fake greyscale fills. Outlines, lines, text and bitmaps are unaffected and always solid.

Parameters

shade

Fill ink level, 0 (white) .. 255 (solid black).

Definition at line 83 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_set_text()

int host_view_canvas_set_text	(	uint32_t	widget_id,
		const char *	text )

Set the text of a text-input widget.

Definition at line 575 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_set_text().

host_view_canvas_set_text_color()

int host_view_canvas_set_text_color

(

bool

inverted

)

Switch between normal and inverted (white on black) text.

Definition at line 75 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_set_text_size()

int host_view_canvas_set_text_size

(

uint8_t

size

)

Set text size multiplier (Adafruit-GFX semantics).

Definition at line 67 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_set_value()

int host_view_canvas_set_value	(	uint32_t	widget_id,
		int32_t	value )

Set the integer value of a slider widget.

Definition at line 561 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_view_canvas_vline()

int host_view_canvas_vline	(	int16_t	x,
		int16_t	y,
		int16_t	h )

Draw a vertical line.

Definition at line 217 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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