Animations¶

You can automatically change the value of a variable between a start and an end value using animations. The animation will happen by periodically calling an "animator" function with the corresponding value parameter.

The animator functions have the following prototype:

void func(void * var, lv_anim_var_t value);

This prototype is compatible with the majority of the set functions 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 "animator" function*/
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, lv_anim_path_ease_in);

/*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. The most simple case is linear, meaning the current value between start and end is changed with fixed steps. 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 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 at the end
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 set the animation time. But in some cases, setting 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 yield 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 with lv_anim_del(var, func) if you provide the animated variable and its animator function.

Examples¶

C¶

Start animation on an event¶

#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_SWITCH

static void anim_x_cb(void * var, int32_t v)
{
    lv_obj_set_x(var, v);
}

static void sw_event_cb(lv_event_t * e)
{
    lv_obj_t * sw = lv_event_get_target(e);
    lv_obj_t * label = lv_event_get_user_data(e);

    if(lv_obj_has_state(sw, LV_STATE_CHECKED)) {
        lv_anim_t a;
        lv_anim_init(&a);
        lv_anim_set_var(&a, label);
        lv_anim_set_values(&a, lv_obj_get_x(label), 100);
        lv_anim_set_time(&a, 500);
        lv_anim_set_exec_cb(&a, anim_x_cb);
        lv_anim_set_path_cb(&a, lv_anim_path_overshoot);
        lv_anim_start(&a);
    } else {
        lv_anim_t a;
        lv_anim_init(&a);
        lv_anim_set_var(&a, label);
        lv_anim_set_values(&a, lv_obj_get_x(label), -lv_obj_get_width(label));
        lv_anim_set_time(&a, 500);
        lv_anim_set_exec_cb(&a, anim_x_cb);
        lv_anim_set_path_cb(&a, lv_anim_path_ease_in);
        lv_anim_start(&a);
    }

}

/**
 * Start animation on an event
 */
void lv_example_anim_1(void)
{
    lv_obj_t * label = lv_label_create(lv_scr_act());
    lv_label_set_text(label, "Hello animations!");
    lv_obj_set_pos(label, 100, 10);


    lv_obj_t * sw = lv_switch_create(lv_scr_act());
    lv_obj_center(sw);
    lv_obj_add_state(sw, LV_STATE_CHECKED);
    lv_obj_add_event_cb(sw, sw_event_cb, LV_EVENT_VALUE_CHANGED, label);
}

#endif

Playback animation¶

#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_SWITCH


static void anim_x_cb(void * var, int32_t v)
{
    lv_obj_set_x(var, v);
}

static void anim_size_cb(void * var, int32_t v)
{
    lv_obj_set_size(var, v, v);
}

/**
 * Create a playback animation
 */
void lv_example_anim_2(void)
{

    lv_obj_t * obj = lv_obj_create(lv_scr_act());
    lv_obj_set_style_bg_color(obj, lv_palette_main(LV_PALETTE_RED), 0);
    lv_obj_set_style_radius(obj, LV_RADIUS_CIRCLE, 0);

    lv_obj_align(obj, LV_ALIGN_LEFT_MID, 10, 0);

    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_var(&a, obj);
    lv_anim_set_values(&a, 10, 50);
    lv_anim_set_time(&a, 1000);
    lv_anim_set_playback_delay(&a, 100);
    lv_anim_set_playback_time(&a, 300);
    lv_anim_set_repeat_delay(&a, 500);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
    lv_anim_set_path_cb(&a, lv_anim_path_ease_in_out);

    lv_anim_set_exec_cb(&a, anim_size_cb);
    lv_anim_start(&a);
    lv_anim_set_exec_cb(&a, anim_x_cb);
    lv_anim_set_values(&a, 10, 240);
    lv_anim_start(&a);
}

#endif

MicroPython¶

No examples yet.

API¶

Typedefs

typedef int32_t (*lv_anim_path_cb_t)(const struct _lv_anim_t*)¶: Get the current value during an animation

typedef void (*lv_anim_exec_xcb_t)(void*, int32_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*, int32_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 int32_t (*lv_anim_get_value_cb_t)(struct _lv_anim_t*)¶: Callback used when the animation values are relative to get the current value

typedef struct _lv_anim_t lv_anim_t¶: Describes an animation

Enums

enum lv_anim_enable_t¶

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

Values:

enumerator LV_ANIM_OFF¶

enumerator LV_ANIM_ON¶

Functions

LV_EXPORT_CONST_INT(LV_ANIM_REPEAT_INFINITE)¶

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_start(&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 LVGL'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, int32_t start, int32_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_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.

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_get_value_cb(lv_anim_t *a, lv_anim_get_value_cb_t get_value_cb)¶

Set a function to use the current value of the variable and make start and end value relative the the returned current value.

Parameters

a -- pointer to an initialized lv_anim_t variable
get_value_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, uint32_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, uint32_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, uint32_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.

static inline void lv_anim_set_early_apply(lv_anim_t *a, bool en)¶

Set a whether the animation's should be applied immediately or only when the delay expired.

Parameters

a -- pointer to an initialized lv_anim_t variable
en -- true: apply the start value immediately in lv_anim_start; false: apply the start value only when delay ms is elapsed and the animations really starts

lv_anim_t *lv_anim_start(const lv_anim_t *a)¶

Create an animation

Parameters: a -- an initialized 'anim_t' variable. Not required after call.
Returns: pointer to the created animation (different from the a parameter)

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

void lv_anim_del_all(void)¶: Delete all the animations animation

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 return first matching '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

uint32_t lv_anim_speed_to_time(uint32_t speed, int32_t start, int32_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_timer_handler can't run for a while. Shouldn't be used directly because it is called in lv_refr_now().

int32_t lv_anim_path_linear(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

int32_t lv_anim_path_ease_in(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

int32_t lv_anim_path_ease_out(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

int32_t lv_anim_path_ease_in_out(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

int32_t lv_anim_path_overshoot(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

int32_t lv_anim_path_bounce(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

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

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

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_get_value_cb_t get_value_cb¶: Get the current value in relative mode

void *user_data¶: Custom user data

lv_anim_path_cb_t path_cb¶: Describe the path (curve) of animations

int32_t start_value¶: Start value

int32_t current_value¶: Current value

int32_t end_value¶: 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

uint8_t playback_now¶: Play back is in progress

uint8_t run_round¶: Indicates the animation has run in this round

uint8_t start_cb_called¶: Indicates that the start_cb was already called

uint32_t time_orig¶