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*/
lv_anim_set_exec_cb(&a, (lv_anim_exec_xcb_t) lv_obj_set_x); 

/*Set the variable to animate*/
lv_anim_set_var(&a, obj); 

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

/*Set start and end values. E.g. 0, 150*/
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

static inline 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

static inline 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

static inline 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

static inline 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

static inline 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

static inline 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.

static inline 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_...

static inline 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

static inline 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

static inline 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

static inline 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.

static inline 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.

static inline 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.

static inline void lv_anim_path_init(lv_anim_path_t *path)¶

Initialize an animation path

Parameters: path -- pointer to path

static inline 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

static inline 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

static inline int32_t lv_anim_get_delay(lv_anim_t *a)¶

Get a delay before starting the animation

Parameters: a -- pointer to an initialized lv_anim_t variable
Returns: delay before the animation in milliseconds

bool lv_anim_del(void *var, lv_anim_exec_xcb_t exec_cb)¶

Delete an animation of a variable with a given animator function

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

Returns

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

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.

Parameters

var -- pointer to variable
exec_cb -- a function pointer which is animating 'var', or NULL to delete all the animations of 'var'

Returns

pointer to the animation.

static inline 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.

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

Returns

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

uint16_t lv_anim_count_running(void)¶

Get the number of currently running animations

Returns: 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

Parameters

speed -- speed of animation in unit/sec
start -- start value of the animation
end -- end value of the animation

Returns

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

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

Parameters: a -- pointer to an animation
Returns: the current value to set

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

Parameters: a -- pointer to an animation
Returns: the current value to set

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

Parameters: a -- pointer to an animation
Returns: the current value to set

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)

Parameters: a -- pointer to an animation
Returns: the current value to set

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

Parameters: a -- pointer to an animation
Returns: the current value to set

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

Parameters: a -- pointer to an animation
Returns: the current value to set

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)

Parameters: a -- pointer to an animation
Returns: the current value to set

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 current¶: Current 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