Animations

You can automatically change the value of a variable between a start and an end value using animations. The animation will happen by the periodical call of an “animator” function with the corresponding value parameter.

The animator functions has the following prototype:

void func(void * var, lv_anim_var_t value);

This prototype is compatible with the majority of the set function of LittlevGL. For example lv_obj_set_x(obj, value) or lv_obj_set_width(obj, value)

Create an animation

To create an animation an lv_anim_t variable has to be initialized and configured with lv_anim_set_...() functions.

lv_anim_t a;
lv_anim_set_exec_cb(&a, btn1, lv_obj_set_x);    /*Set the animator function and variable to animate*/
lv_anim_set_time(&a, duration, delay);
lv_anim_set_values(&a, start, end);             /*Set start and end values. E.g. 0, 150*/
lv_anim_set_path_cb(&a, lv_anim_path_linear);   /*Set path from `lv_anim_path_...` functions or a custom one.*/
lv_anim_set_ready_cb(&a, ready_cb);             /*Set a callback to call then animation is ready. (Optional)*/
lv_anim_set_playback(&a, wait_time);            /*Enable playback of teh animation with `wait_time` delay*/
lv_anim_set_repeat(&a, wait_time);              /*Enable repeat of teh animation with `wait_time` delay. Can be compiled with playback*/

lv_anim_create(&a);                             /*Start the animation*/

You can apply multiple different animations on the same variable at the same time. For example, animate the x and y coordinates with lv_obj_set_x and lv_obj_set_y. However, only one animation can exist with a given variable and function pair. Therefore lv_anim_create() will delete the already existing variable-function animations.

Animation path

You can determinate the path of animation. In the most simple case, it is linear, which means the current value between start and end is changed linearly. A path is a function which calculates the next value to set based on the current state of the animation. Currently, there are the following built-in paths:

  • lv_anim_path_linear linear animation

  • lv_anim_path_step change in one step at the end

  • lv_anim_path_ease_in slow at the beginning

  • lv_anim_path_ease_out slow at the end

  • lv_anim_path_ease_in_out slow at the beginning and end too

  • lv_anim_path_overshoot overshoot the end value

  • lv_anim_path_bounce bounce back a little from the end value (like hitting a wall)

Speed vs time

By default, you can set the animation time. But, in some cases, the animation speed is more practical.

The lv_anim_speed_to_time(speed, start, end) function calculates the required time in milliseconds to reach the end value from a start value with the given speed. The speed is interpreted in unit/sec dimension. For example, lv_anim_speed_to_time(20,0,100) will give 5000 milliseconds. For example, in case of lv_obj_set_x unit is pixels so 20 means 20 px/sec speed.

Delete animations

You can delete an animation by lv_anim_del(var, func) by providing the animated variable and its animator function.

API

Input device

Typedefs

typedef uint8_t lv_anim_enable_t
typedef lv_coord_t lv_anim_value_t

Type of the animated value

typedef void (*lv_anim_exec_xcb_t)(void*, lv_anim_value_t)

Generic prototype of “animator” functions. First parameter is the variable to animate. Second parameter is the value to set. Compatible with lv_xxx_set_yyy(obj, value) functions The x in _xcb_t means its not a fully generic prototype because it doesn’t receive lv_anim_t * as its first argument

typedef void (*lv_anim_custom_exec_cb_t)(struct _lv_anim_t*, lv_anim_value_t)

Same as lv_anim_exec_xcb_t but receives lv_anim_t * as the first parameter. It’s more consistent but less convenient. Might be used by binding generator functions.

typedef lv_anim_value_t (*lv_anim_path_cb_t)(const struct _lv_anim_t*)

Get the current value during an animation

typedef void (*lv_anim_ready_cb_t)(struct _lv_anim_t*)

Callback to call when the animation is ready

typedef struct _lv_anim_t lv_anim_t

Describes an animation

Enums

enum [anonymous]

Can be used to indicate if animations are enabled or disabled in a case

Values:

enumerator LV_ANIM_OFF
enumerator LV_ANIM_ON

Functions

void lv_anim_core_init(void)

Init. the animation module

void lv_anim_init(lv_anim_t *a)

Initialize an animation variable. E.g.: lv_anim_t a; lv_anim_init(&a); lv_anim_set_…(&a); lv_anim_create(&a);

Parameters

  • a: pointer to an lv_anim_t variable to initialize

void lv_anim_set_exec_cb(lv_anim_t *a, void *var, lv_anim_exec_xcb_t exec_cb)

Set a variable to animate function to execute on var

Parameters

  • a: pointer to an initialized lv_anim_t variable

  • var: pointer to a variable to animate

  • exec_cb: a function to execute. LittelvGL’s built-in functions can be used. E.g. lv_obj_set_x

void lv_anim_set_time(lv_anim_t *a, uint16_t duration, int16_t delay)

Set the duration and delay of an animation

Parameters

  • a: pointer to an initialized lv_anim_t variable

  • duration: duration of the animation in milliseconds

  • delay: delay before the animation in milliseconds

void lv_anim_set_values(lv_anim_t *a, lv_anim_value_t start, lv_anim_value_t end)

Set the start and end values of an animation

Parameters

  • a: pointer to an initialized lv_anim_t variable

  • start: the start value

  • end: the end value

void lv_anim_set_custom_exec_cb(lv_anim_t *a, lv_anim_custom_exec_cb_t exec_cb)

Similar to lv_anim_set_var_and_cb but lv_anim_custom_exec_cb_t receives lv_anim_t * as its first parameter instead of void *. This function might be used when LittlevGL is binded to other languages because it’s more consistent to have lv_anim_t * as first parameter.

Parameters

  • a: pointer to an initialized lv_anim_t variable

  • exec_cb: a function to execute.

void lv_anim_set_path_cb(lv_anim_t *a, lv_anim_path_cb_t path_cb)

Set the path (curve) of the animation.

Parameters

  • a: pointer to an initialized lv_anim_t variable

  • path_cb: a function the get the current value of the animation. The built in functions starts with lv_anim_path_...

void lv_anim_set_ready_cb(lv_anim_t *a, lv_anim_ready_cb_t ready_cb)

Set a function call when the animation is ready

Parameters

  • a: pointer to an initialized lv_anim_t variable

  • ready_cb: a function call when the animation is ready

void lv_anim_set_playback(lv_anim_t *a, uint16_t wait_time)

Make the animation to play back to when the forward direction is ready

Parameters

  • a: pointer to an initialized lv_anim_t variable

  • wait_time: time in milliseconds to wait before starting the back direction

void lv_anim_clear_playback(lv_anim_t *a)

Disable playback. (Disabled after lv_anim_init())

Parameters

  • a: pointer to an initialized lv_anim_t variable

void lv_anim_set_repeat(lv_anim_t *a, uint16_t wait_time)

Make the animation to start again when ready.

Parameters

  • a: pointer to an initialized lv_anim_t variable

  • wait_time: time in milliseconds to wait before starting the animation again

void lv_anim_clear_repeat(lv_anim_t *a)

Disable repeat. (Disabled after lv_anim_init())

Parameters

  • a: pointer to an initialized lv_anim_t variable

void lv_anim_create(lv_anim_t *a)

Create an animation

Parameters

  • a: an initialized ‘anim_t’ variable. Not required after call.

bool lv_anim_del(void *var, lv_anim_exec_xcb_t exec_cb)

Delete an animation of a variable with a given animator function

Return

true: at least 1 animation is deleted, false: no animation is deleted

Parameters

  • var: pointer to variable

  • exec_cb: a function pointer which is animating ‘var’, or NULL to ignore it and delete all the animations of ‘var

bool lv_anim_custom_del(lv_anim_t *a, lv_anim_custom_exec_cb_t exec_cb)

Delete an aniamation by getting the animated variable from a. Only animations with exec_cb will be deleted. This function exist becasue it’s logical that all anim functions receives an lv_anim_t as their first parameter. It’s not practical in C but might makes the API more conequent and makes easier to genrate bindings.

Return

true: at least 1 animation is deleted, false: no animation is deleted

Parameters

  • a: pointer to an animation.

  • exec_cb: a function pointer which is animating ‘var’, or NULL to ignore it and delete all the animations of ‘var

uint16_t lv_anim_count_running(void)

Get the number of currently running animations

Return

the number of running animations

uint16_t lv_anim_speed_to_time(uint16_t speed, lv_anim_value_t start, lv_anim_value_t end)

Calculate the time of an animation with a given speed and the start and end values

Return

the required time [ms] for the animation with the given parameters

Parameters

  • speed: speed of animation in unit/sec

  • start: start value of the animation

  • end: end value of the animation

lv_anim_value_t lv_anim_path_linear(const lv_anim_t *a)

Calculate the current value of an animation applying linear characteristic

Return

the current value to set

Parameters

  • a: pointer to an animation

lv_anim_value_t lv_anim_path_ease_in(const lv_anim_t *a)

Calculate the current value of an animation slowing down the start phase

Return

the current value to set

Parameters

  • a: pointer to an animation

lv_anim_value_t lv_anim_path_ease_out(const lv_anim_t *a)

Calculate the current value of an animation slowing down the end phase

Return

the current value to set

Parameters

  • a: pointer to an animation

lv_anim_value_t lv_anim_path_ease_in_out(const lv_anim_t *a)

Calculate the current value of an animation applying an “S” characteristic (cosine)

Return

the current value to set

Parameters

  • a: pointer to an animation

lv_anim_value_t lv_anim_path_overshoot(const lv_anim_t *a)

Calculate the current value of an animation with overshoot at the end

Return

the current value to set

Parameters

  • a: pointer to an animation

lv_anim_value_t lv_anim_path_bounce(const lv_anim_t *a)

Calculate the current value of an animation with 3 bounces

Return

the current value to set

Parameters

  • a: pointer to an animation

lv_anim_value_t lv_anim_path_step(const lv_anim_t *a)

Calculate the current value of an animation applying step characteristic. (Set end value on the end of the animation)

Return

the current value to set

Parameters

  • a: pointer to an animation

struct _lv_anim_t
#include <lv_anim.h>

Describes an animation

Public Members

void *var

Variable to animate

lv_anim_exec_xcb_t exec_cb

Function to execute to animate

lv_anim_path_cb_t path_cb

Function to get the steps of animations

lv_anim_ready_cb_t ready_cb

Call it when the animation is ready

int32_t start

Start value

int32_t end

End value

uint16_t time

Animation time in ms

int16_t act_time

Current time in animation. Set to negative to make delay.

uint16_t playback_pause

Wait before play back

uint16_t repeat_pause

Wait before repeat

lv_anim_user_data_t user_data

Custom user data

uint8_t playback

When the animation is ready play it back

uint8_t repeat

Repeat the animation infinitely

uint8_t playback_now

Play back is in progress

uint32_t has_run

Indicates the animation has run in this round