Button (`gsp_button`)

Clickable content surface that triggers declarative actions or application callbacks.

When to use

Use it for the main text, image, or action on a screen.

Local interactive preview

First set up the commands from the compatibility guide, then run from an unpacked component or public repository root with gspc and gsp_sim_host:

button-preview.sh

mkdir -p gsp-out/widget-preview
gspc pack \
  examples/usage/widgets/button/button.json \
  --deployable -o gsp-out/widget-preview/button.gspb
gsp_sim_host \
  --bundle gsp-out/widget-preview/button.gspb --frames 0

These commands compile the example and open it in the ESP-GSP simulator browser preview.

Runtime behavior

For a circular button, set equal w/h and radius = w/2. The hard shadow follows the radius; shadow_spread grows its size. Shadow blur and circular image clipping are not supported. Use image transparency for circular artwork. The touch area remains rectangular.

To darken a button and hide its shadow while pressed, add pressed_dim: 64 and pressed_shadow: false. pressed_dim ranges from 0 (unchanged) to 255 (black). pressed_color sets a specific pressed background color; borders, outlines and text keep their colors. press_feedback: false disables automatic darkening and cannot be combined with pressed_dim or pressed_color.

These fields are optional. If any is present, the default dim strength is 96 and the shadow is kept unless overridden. With none present, the existing global press feedback applies. Moving beyond the edge margin or starting a parent gesture cancels release/click and restores its appearance; use cancel for application cleanup.

State images use disabled > pressed > selected > normal priority. pressed_image overrides automatic image dimming. Missing artwork falls back to selected_image when checked, otherwise image. checkable: true toggles checked on click and requires selected_image; generated APIs can also set checked. Bitmap and compiled SVG states use the same cache mechanism, but different resources occupy separate entries.

Automatic dimming is generated from authored colors and static images. Bound or themed backgrounds require pressed_color; changing the normal color later does not regenerate the pressed style. For animated or tinted images, supply pressed_image. State images cannot share a runtime resource bind. Press styles and state images are not supported inside recycled templates.

Image dimming adds a compiled resource, including a selected variant when needed. It avoids computing darkened pixels on the device, but increases bundle/cache use; first display may still require decoding.

If application code must read or update an object, give it a stable name. GSPC then generates the typed functions listed below.

Example scene

button.json

{"screen":"widget_button","w":480,"h":320,"screen_bg":"#101827","font":"../../../common/fonts/DejaVuSans.ttf","objects":[{"type":"button","parent":-1,"name":"primary","callback":"primary_click","x":70,"y":70,"w":160,"h":54,"text":"Primary","font_size":18,"bg_color":"#2563EB","fg_color":"#FFFFFF","radius":12,"shadow_color":"#000000","shadow_offset_y":4,"pressed_dim":64,"pressed_shadow":false},{"type":"button","parent":-1,"callback":"secondary_click","x":250,"y":70,"w":160,"h":54,"text":"Secondary","font_size":18,"bg_color":"#26364D","fg_color":"#DCE8F7","border_color":"#4B607D","border_width":1,"radius":12,"pressed_color":"#142033"},{"type":"button","parent":-1,"callback":"muted_click","x":150,"y":160,"w":180,"h":48,"text":"Muted","font_size":16,"bg_color":"#334155","fg_color":"#94A3B8","radius":24},{"type":"button","parent":-1,"name":"favorite","x":190,"y":232,"w":100,"h":56,"image":"favorite_normal.svg","pressed_image":"favorite_pressed.svg","selected_image":"favorite_selected.svg","disabled_image":"favorite_disabled.svg","checkable":true},{"type":"button","parent":-1,"callback":"secondary_click","x":40,"y":225,"w":64,"h":64,"bg_color":"#2563EB","radius":32,"shadow_color":"#000000","shadow_offset_y":4,"shadow_spread":2,"pressed_dim":64,"pressed_shadow":false}]}

The canonical example is examples/usage/widgets/button/button.json. Copy any relative assets referenced by the scene with it.

Generated C API

dispatch_call requires GSP_GENERATE_WEAK_EVENT_HANDLERS on an ELF GCC/Clang target; see optional business handlers.

bool gsp_widget_button_dispatch_call( esp_gsp_handle_t gsp, const esp_gsp_event_t *event, void *user_ctx)
bool gsp_widget_button_event_decode_call( const esp_gsp_event_t *event, gsp_widget_button_call_event_t *out_event)
bool gsp_widget_button_event_is_muted_click( const esp_gsp_event_t *event)
bool gsp_widget_button_event_is_primary_click( const esp_gsp_event_t *event)
bool gsp_widget_button_event_is_secondary_click( const esp_gsp_event_t *event)
const gsp_component_directory_t *const * gsp_button_docs_component_directories(uint16_t *out_count)
esp_err_t gsp_widget_button_favorite_get_checked(esp_gsp_handle_t gsp, bool *out_checked)
esp_err_t gsp_widget_button_favorite_get_effective_visible(esp_gsp_handle_t gsp, bool *out_visible)
esp_err_t gsp_widget_button_favorite_get_enabled(esp_gsp_handle_t gsp, bool *out_enabled)
esp_err_t gsp_widget_button_favorite_get_info(esp_gsp_handle_t gsp, esp_gsp_component_info_t *out_info)
esp_err_t gsp_widget_button_favorite_set_checked(esp_gsp_handle_t gsp, bool checked)
esp_err_t gsp_widget_button_favorite_set_enabled(esp_gsp_handle_t gsp, bool enabled)
esp_err_t gsp_widget_button_primary_get_effective_visible(esp_gsp_handle_t gsp, bool *out_visible)
esp_err_t gsp_widget_button_primary_get_info(esp_gsp_handle_t gsp, esp_gsp_component_info_t *out_info)
esp_gsp_config_t gsp_button_docs_config(void)
size_t gsp_button_docs_dynamic_image_slots(void)

These signatures come from the actual compiler output for this JSON.

Fields in this example

Field	Type	Required	Default / range	Dynamic	Compiler definition
type	string	yes	—	—	widget type
parent	int	yes	default -1; -1…65534	—	parent object index (-1 = screen root)
x	int	yes	default 0; -32768…32767	scene: yes; template: —	x relative to parent
y	int	yes	default 0; -32768…32767	scene: yes; template: —	y relative to parent
w	int	yes	0…65535	scene: —; template: —	width in px
h	int	yes	0…65535	scene: —; template: —	height in px
name	identifier	—	—	—	stable component name; generates GSP_OBJ_KEY_<NAME>
fg_color	color	—	—	—	foreground color (text/knob/line/mark per type)
bg_color	color	—	—	yes	background/fill color (#RRGGBB or #RRGGBBAA)
radius	int	—	default 0; 0…65535	scene: —; template: —	corner radius in px
shadow_color	color	—	—	—	static hard-shadow color
shadow_offset_y	int	—	-32768…32767	—	static hard-shadow y offset
shadow_spread	int	—	0…4096	—	static hard-shadow spread in px
text	string	—	—	yes	static text content (UTF-8)
font_size	int	—	1…255	—	per-object font pixel size
border_color	color	—	—	—	border stroke color
border_width	int	—	0…65535	—	border stroke width (needs border_color)
image	path	—	—	yes	image file path (raster or compiled SVG)
callback	identifier	—	—	—	app callback name; generates scene-qualified event helpers
pressed_image	path	—	—	—	pressed-state image path
selected_image	path	—	—	—	selected-state image path
disabled_image	path	—	—	—	disabled-state image path
checkable	bool	—	default false	—	toggle selected state on click
pressed_dim	int	—	0…255	—	pressed background/image darkening, 0 unchanged to 255 black
pressed_color	color	—	—	—	pressed background color, overriding automatic background darkening
pressed_shadow	bool	—	—	—	keep the static shadow while pressed (default true)

Show other fields supported by this Widget

Field	Type	Required	Default / range	Dynamic	Compiler definition
min_width	int	—	0…65535	—	compile-time minimum width in px
max_width	int	—	0…65535	—	compile-time maximum width in px
min_height	int	—	0…65535	—	compile-time minimum height in px
max_height	int	—	0…65535	—	compile-time maximum height in px
layout	enum	—	row, column, grid	—	child auto-layout: row/column/grid
layout_wrap	bool	—	default false	—	wrap row/column children into additional lines
grid_columns	int	—	1…65535	—	equal-width column count for grid layout
grid_column_span	int	—	default 1; 1…65535	—	column span in the parent grid layout
gap	int	—	default 0; 0…4096	—	auto-layout gap in px
padding	int	—	default 0; 0…4096	—	auto-layout padding in px
padding_left	int	—	0…4096	—	row layout: leading padding override
padding_right	int	—	0…4096	—	row layout: trailing padding override
padding_top	int	—	0…4096	—	column layout: leading padding override
padding_bottom	int	—	0…4096	—	column layout: trailing padding override
grow	int	—	default 0; 0…100	—	auto-layout grow weight
margin	int	—	default 0; 0…4096	—	auto-layout space on both child sides
margin_left	int	—	0…4096	—	auto-layout leading margin on the x axis
margin_right	int	—	0…4096	—	auto-layout trailing margin on the x axis
margin_top	int	—	0…4096	—	auto-layout leading margin on the y axis
margin_bottom	int	—	0…4096	—	auto-layout trailing margin on the y axis
align_main	enum	—	start, center, end, space_between	—	auto-layout main-axis placement
align_cross	enum	—	start, center, end, stretch	—	auto-layout cross-axis placement
hidden	bool	—	default false	yes	start hidden (show via actions or set_visible)
opacity	int	—	default 255; 0…255	scene: —; template: —	0-255 blend opacity
bg_gradient	color	—	—	—	second gradient stop (with bg_color)
gradient_dir	enum	—	default vertical; vertical, horizontal	—	gradient direction
shadow_opacity	int	—	default 96; 0…255	—	static hard-shadow opacity
shadow_offset_x	int	—	-32768…32767	—	static hard-shadow x offset
shadow_radius	int	—	0…65535	—	static hard-shadow corner radius
text_line_space	int	—	default 0; 0…4096	—	extra spacing between static text rows in px
text_vertical_align	enum	—	default auto; auto, top, center, bottom	—	static text block placement; auto preserves single-line center and multiline top
text_align	enum	—	left, center, right	—	text alignment
overflow	enum	—	default clip; clip, ellipsis	—	single-line overflow
font	path	—	—	—	per-object TTF/OTF override
font_charset	string	—	—	—	glyphs available to runtime-bound text; static text is added automatically
font_charset_file	path	—	—	—	UTF-8 character corpus relative to the scene; combined with font_charset and static text
font_link	enum	—	embedded, external, auto	—	font storage policy: embedded/external/auto
input	bool	—	default false	—	text field: attaches the caret/keyboard flow
bg_opacity	int	—	default 255; 0…255	—	background-only opacity; multiplied by opacity and color alpha
border_opacity	int	—	default 255; 0…255	—	border stroke opacity
outline_color	color	—	—	—	outside outline color
outline_width	int	—	default 0; 0…65535	—	outside outline width
outline_opacity	int	—	default 255; 0…255	—	outside outline opacity
outline_pad	int	—	default 0; 0…4096	—	gap between the element and its outline
border_side	enum	—	default all; all, none, top, bottom, left, right, horizontal, vertical	—	inside border selection; partial sides require static rectangular geometry
animation_codec	enum	—	lossless, jpeg, hardware_jpeg	—	animation frame policy: lossless patches, JPEG full frames, or JPEG when the target has hardware decoding
svg_layout	enum	—	content, canvas	—	SVG part placement: cropped content or original canvas
morph_to	path	—	—	—	SVG end shape with matching paths and paints
morph	int	—	0…100	—	SVG shape interpolation progress (percent); generates a runtime setter
svg_element	string	—	—	—	SVG element id; imports its painted bounds as an independent image
tint	color	—	—	—	SVG silhouette color; generates a runtime color setter
codec	enum	—	raw, lossless, jpeg, auto, speed, size, store, qoi, rle16, rle16_a8, rle32, default, hardware_jpeg	—	image codec
quality	int	—	1…100	—	JPEG quality 1-100 (omitted = profile default)
jpeg_quality	int	—	1…100	—	legacy JPEG quality alias
compress	bool	—	—	—	image compression toggle (legacy; prefer codec)
cache_policy	enum	—	mmap_direct, mmap, decode_lru, lru, preload	—	image cache policy: mmap_direct, decode_lru or preload
store_scale	number	—	0.05…1.0	—	pre-scale factor applied when encoding
max_fps	int	—	0…120	—	GIF/animation frame-rate cap (0 = uncapped)
fit	enum	—	default stretch; stretch, fill, contain, cover	—	image fit mode
position_x	number	—	default 0.5; 0.0…1.0	—	image fit horizontal alignment
position_y	number	—	default 0.5; 0.0…1.0	—	image fit vertical alignment
rotation	int	—	default 0; -32768…32767	scene: image; template: —	clockwise image rotation around the bounding-box center; source alpha is supported; clipped to the box
scalable	bool	—	default false	—	enable runtime image scaling
scale	number	—	default 1.0; 0.0625…16.0	—	initial runtime image scale
min_scale	number	—	default 0.5; 0.0625…16.0	—	minimum runtime image scale
max_scale	number	—	default 4.0; 0.0625…16.0	—	maximum runtime image scale
checked	bool	—	default false	yes	initial on/off state
enabled	bool	—	—	—	initial interaction state; when present, exposes a runtime enabled property inherited by descendant controls
disabled_color	color	—	default #808080	—	disabled-state overlay color
disabled_opacity	int	—	default 112; 0…255	—	disabled-state overlay opacity
bind	identifier	—	—	—	public state name; generates GSP_BIND_<NAME>
bind_target	enum	—	visible, value, color, text, resource, data	—	explicit bind state family
events	action_list	—	—	—	input bindings: [{event, action, ...}]
template	identifier	—	—	—	declare this subtree as a render template
max_instances	int	—	1…65535	—	maximum simultaneously live template instances; included in the automatic pool requirement
dynamic_color	bool	—	—	—	template member exposes a per-instance color slot
dynamic_image	bool	—	—	—	template image exposes a per-instance resource slot
press_feedback	bool	—	—	—	enable shape-aware press feedback; false disables automatic shading

Show fields shared by every Widget

Field	Type	Required	Default / range	Dynamic	Compiler definition
parent_name	string	—	—	—	parent by name instead of index