Events and actions

Making a widget do something - and reaching your own code when the built-in actions run out.

An event is a trigger on a widget and a list of actions to run when it fires. Both come from the SquareLine Studio model, so if you have used that, this is the same thing with a few additions: swipe triggers on every widget, and hardware actions that reach the data layer. The generator writes one ui_event_<Name>() handler per widget that has events, registers it with lv_obj_add_event_cb(), and dispatches on the event code inside.

The Events section of a button with one Clicked trigger running a Change Screen action.

Adding one

Select the widget, scroll the Inspector to Events, click add, pick the trigger, then add actions to it. Each action has its own fields - a Change Screen needs a screen, an Increment Slider needs a target and an amount. An action with an empty required field is reported by the validator as an error, since the generator cannot emit it.

Triggers

Trigger	Fires when
Pressed	The finger goes down.
Clicked	Pressed briefly then released, without scrolling. The one to use for buttons.
Short clicked	A brief tap.
Long pressed	Held past the long-press time.
Long pressed repeat	Repeatedly while still held after a long press - for auto-repeat.
Released	The finger lifts, click or not.
Focused / Defocused	Keyboard or encoder focus moves onto or off the widget.
Value changed	A slider, arc, switch, checkbox, dropdown, roller, spinbox or textarea changed.
Ready / Cancel	A process finished or was abandoned - the keyboard's tick and cross.
Checked / Unchecked	A checkable object toggled.
Gesture (any)	A swipe in any direction.
Swipe up / down / left / right	A swipe in that direction.
Key	A key was sent to the widget from a keypad or encoder.
Edited / Insert	Text changed or text was inserted in a textarea.
Screen loaded / unloaded, Screen load start / unload start	Screens only.

The four Screen triggers are only offered on a screen, and are the place for anything that should happen as a page appears - refreshing a readout, starting an animation. Screen loaded fires after the load animation; Screen load start before it.

Actions

Action	Fields	Does
Call function	Function name	Calls a function you write in `ui_events.c`.
Change Screen	Screen, fade mode, speed, delay, auto delete	Loads another screen with an animation.
Delete screen	Screen	Frees a screen from RAM.
Increment Arc / Bar / Slider	Target, value (and animation time)	Adds a signed amount to the target's value.
Step spinbox	Target, direction	Increments or decrements the spinbox by its step.
Modify Flag	Target, flag, Add / Remove / Toggle	Changes an object flag - toggling Hidden is the usual case.
Set Flag	Target, flag, on/off	Sets a flag to a known state.
Set Opacity	Target, opacity	Sets the target's main-part opacity.
Set Property	Target, property, value	Sets Text, Value, Value (animated), Image source, Range min or max, Selected index, Background colour or Text colour.
Play Animation	Target, property, start, end, duration, delay, path, repeat count, playback	Animates X, Y, width, height, opacity, scale or rotation with an easing path.
Set text value from arc / slider	Target label, source, prefix, postfix	Writes the source's value into a label as text.
Set text value when checked	Target label, source, checked text, unchecked text	Writes one of two strings depending on a checkbox or switch.
Switch Theme	Light / Dark	Re-initialises the theme at runtime.
Set variable	Variable, mode, value	Writes a data-layer variable. See below.
Set digital output	Output, Activate / Deactivate / Toggle	Drives a digital output, on an MCU pin or an extender.
Write to peripheral	Peripheral, channel, value	Writes to a writable channel such as a PCA9685 output.
Refresh inputs now	-	Reads every peripheral, analog and digital input immediately.

Change Screen, in detail

The most used action. Besides the target screen it takes a fade mode - None, Over left/right/top/bottom, Move left/right/top/bottom, Fade in, Fade out, Out left/right/top/bottom - a speed in milliseconds, a delay, and auto delete, which frees the screen being left. It becomes _ui_screen_change() in ui_helpers.c, which creates the target if it has been freed and calls lv_screen_load_anim(). The preview runs it too, switching the canvas to the target screen.

Call function

The escape hatch. Give it a function name and the generator declares it in ui_events.h and writes a stub in ui_events.c:

void my_callback(lv_event_t * e)
{
    // TODO: your code here
}

ui_events.c is the one generated file that is yours: the stubs are regenerated on every export but a file you have edited is never overwritten, so your code survives. Inside a callback you have the whole LVGL API and every ui_<Name> object from ui.h.

Hardware actions

The last four actions belong to the data layer and are the bridge from a touch to the firmware's state. Set variable writes a variable - a fixed value, a formula, an amount added, a toggle for a Boolean, or the value of a widget - and every binding that reads it updates on the next refresh. Set digital output drives an output on an MCU pin or an I/O extender. Write to peripheral pushes a value to a writable channel (a PCA9685 PWM channel, a NeoPixel colour). Refresh inputs now forces an immediate read of everything rather than waiting for the poll interval. The same four are available to automations.

In the preview

Events run in preview: a Clicked button changes screen, toggles a flag, steps a value, sets a variable. Since a mouse cannot swipe, a pad at the bottom of the canvas sends the four gestures and shows whether anything on the screen listens for each. Play Animation, Switch Theme and peripheral writes cannot be simulated and say so in the Console tab rather than silently doing nothing.

Event bubbling

A tap on a label inside a panel is a tap on the label, not the panel. Set the label's Event bubble flag and the panel's handler sees it as well; set Gesture bubble for swipes to travel the same way. A screen's swipe triggers rely on this: a swipe that starts on a widget without Gesture bubble stops there.