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 LVGL. 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.


/* INITIALIZE AN ANIMATION
 *-----------------------*/

lv_anim_t a;
lv_anim_init(&a);

/* MANDATORY SETTINGS
 *------------------*/

/*Set the animator function and variable to animate*/
lv_anim_set_exec_cb(&a, btn1, (lv_anim_exec_xcb_t) lv_obj_set_x); 

/*Length of the animation [ms]*/
lv_anim_set_time(&a, duration);

/*Set start and end values. E.g. 0, 150 [ms]*/
lv_anim_set_values(&a, start, end);

/* OPTIONAL SETTINGS
 *------------------*/

/*Time to wait before starting the animation [ms]*/
lv_anim_set_delay(&a, delay);

/*Set path (curve). Default is linear*/
lv_anim_set_path(&a, &path);

/*Set a callback to call when animation is ready.*/
lv_anim_set_ready_cb(&a, ready_cb);

/*Set a callback to call when animation is started (after delay).*/
lv_anim_set_start_cb(&a, start_cb);

/*Play the animation backward too with this duration. Default is 0 (disabled) [ms]*/
lv_anim_set_playback_time(&a, wait_time); 

/*Delay before playback. Default is 0 (disabled) [ms]*/
lv_anim_set_playback_delay(&a, wait_time);

/*Number of repetitions. Default is 1.  LV_ANIM_REPEAT_INFINIT for infinite repetition*/
lv_anim_set_repeat_count(&a, wait_time);

/*Delay before repeat. Default is 0 (disabled) [ms]*/
lv_anim_set_repeat_delay(&a, wait_time);

/*true (default): apply the start vale immediately, false: apply start vale after delay when then anim. really starts. */
lv_anim_set_early_apply(&a, true/false);

/* START THE ANIMATION
 *------------------*/
lv_anim_start(&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_start() 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 mainly 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 functions:

  • 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)

A path can be initialized like this:

lv_anim_path_t path;
lv_anim_path_init(&path);
lv_anim_path_set_cb(&path, lv_anim_path_overshoot);
lv_anim_path_set_user_data(&path, &foo); /*Optional for custom functions*/

/*Set the path in an animation*/
lv_anim_set_path(&a, &path);

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 lv_anim_value_t (*lv_anim_path_cb_t)(const struct _lv_anim_path_t*, const struct _lv_anim_t*)

Get the current value during an animation

typedef struct _lv_anim_path_t lv_anim_path_t
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 void (*lv_anim_ready_cb_t)(struct _lv_anim_t*)

Callback to call when the animation is ready

typedef void (*lv_anim_start_cb_t)(struct _lv_anim_t*)

Callback to call when the animation really stars (considering delay)

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);

Parameters
  • a: pointer to an lv_anim_t variable to initialize

void lv_anim_set_var(lv_anim_t *a, void *var)

Set a variable to animate

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • var: pointer to a variable to animate

void lv_anim_set_exec_cb(lv_anim_t *a, lv_anim_exec_xcb_t exec_cb)

Set a function to animate var

Parameters
  • a: pointer to an initialized lv_anim_t variable

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

void lv_anim_set_time(lv_anim_t *a, uint32_t duration)

Set the duration of an animation

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • duration: duration of the animation in milliseconds

void lv_anim_set_delay(lv_anim_t *a, uint32_t delay)

Set a delay before starting the animation

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • 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_exec_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 LVGL is binded to other languages because it's more consistent to have lv_anim_t * as first parameter. The variable to animate can be stored in the animation's user_sata

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • exec_cb: a function to execute.

void lv_anim_set_path(lv_anim_t *a, const lv_anim_path_t *path)

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_start_cb(lv_anim_t *a, lv_anim_ready_cb_t start_cb)

Set a function call when the animation really starts (considering delay)

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • start_cb: a function call when the animation starts

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_time(lv_anim_t *a, uint16_t time)

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

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • time: the duration of the playback animation in in milliseconds. 0: disable playback

void lv_anim_set_playback_delay(lv_anim_t *a, uint16_t delay)

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

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • delay: delay in milliseconds before starting the playback animation.

void lv_anim_set_repeat_count(lv_anim_t *a, uint16_t cnt)

Make the animation repeat itself.

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • cnt: repeat count or LV_ANIM_REPEAT_INFINITE for infinite repetition. 0: to disable repetition.

void lv_anim_set_repeat_delay(lv_anim_t *a, uint16_t delay)

Set a delay before repeating the animation.

Parameters
  • a: pointer to an initialized lv_anim_t variable

  • delay: delay in milliseconds before repeating the animation.

void lv_anim_start(lv_anim_t *a)

Create an animation

Parameters
  • a: an initialized 'anim_t' variable. Not required after call.

void lv_anim_path_init(lv_anim_path_t *path)

Initialize an animation path

Parameters
  • path: pointer to path

void lv_anim_path_set_cb(lv_anim_path_t *path, lv_anim_path_cb_t cb)

Set a callback for a path

Parameters
  • path: pointer to an initialized path

  • cb: the callback

void lv_anim_path_set_user_data(lv_anim_path_t *path, void *user_data)

Set a user data for a path

Parameters
  • path: pointer to an initialized path

  • user_data: pointer to the user data

int32_t lv_anim_get_delay(lv_anim_t *a)

Get a delay before starting the animation

Return

delay before the animation in milliseconds

Parameters
  • a: pointer to an initialized lv_anim_t variable

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

lv_anim_t *lv_anim_get(void *var, lv_anim_exec_xcb_t exec_cb)

Get the animation of a variable and its exec_cb.

Return

pointer to the animation.

Parameters
  • var: pointer to variable

  • exec_cb: a function pointer which is animating 'var', or NULL to 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 animation by getting the animated variable from a. Only animations with exec_cb will be deleted. This function exists because it's logical that all anim. functions receives an lv_anim_t as their first parameter. It's not practical in C but might make the API more consequent and makes easier to generate 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

void lv_anim_refr_now(void)

Manually refresh the state of the animations. Useful to make the animations running in a blocking process where lv_task_handler can't run for a while. Shouldn't be used directly because it is called in lv_refr_now().

lv_anim_value_t lv_anim_path_linear(const lv_anim_path_t *path, 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_path_t *path, 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_path_t *path, 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_path_t *path, 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_path_t *path, 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_path_t *path, 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_path_t *path, 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

Variables

const lv_anim_path_t lv_anim_path_def
struct _lv_anim_path_t

Public Members

lv_anim_path_cb_t cb
void *user_data
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_start_cb_t start_cb

Call it when the animation is starts (considering delay)

lv_anim_ready_cb_t ready_cb

Call it when the animation is ready

lv_anim_path_t path

Describe the path (curve) of animations

int32_t start

Start value

int32_t end

End value

int32_t time

Animation time in ms

int32_t act_time

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

uint32_t playback_delay

Wait before play back

uint32_t playback_time

Duration of playback animation

uint32_t repeat_delay

Wait before repeat

uint16_t repeat_cnt

Repeat count for the animation

uint8_t early_apply

1: Apply start value immediately even is there is delay

lv_anim_user_data_t user_data

Custom user data

uint32_t time_orig
uint8_t playback_now

Play back is in progress

uint32_t has_run

Indicates the animation has run in this round