App:Library:LVGL:docs:Overview:Animations

https://docs.lvgl.io/8.2/overview/animation.html

Animations

You can automatically change the value of a variable between a start and an end value using animations. 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 property set functions in 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 target of the animation*/
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 indicate when the animation is ready (idle).*/
lv_anim_set_ready_cb(&a, ready_cb);

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

/*When ready, play the animation backward with this duration. Default is 0 (disabled) [ms]*/
lv_anim_set_playback_time(&a, time);

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

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

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

/*true (default): apply the start value immediately, false: apply start value after delay when the 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 and lv_anim_start() will remove any existing animations for such a pair.

Animation path

You can control the path of an 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 path 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
• 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 directly. 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 the 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.

Timeline

A timeline is a collection of multiple animations which makes it easy to create complex composite animations.

Firstly, create an animation element but don’t call lv_anim_start().

Secondly, create an animation timeline object by calling lv_anim_timeline_create().

Thirdly, add animation elements to the animation timeline by calling lv_anim_timeline_add(at, start_time, &a). start_time is the start time of the animation on the timeline. Note that start_time will override the value of delay.

Finally, call lv_anim_timeline_start(at) to start the animation timeline.

It supports forward and backward playback of the entire animation group, using lv_anim_timeline_set_reverse(at, reverse).

Call lv_anim_timeline_stop(at) to stop the animation timeline.

Call lv_anim_timeline_set_progress(at, progress) function to set the state of the object corresponding to the progress of the timeline.

Call lv_anim_timeline_get_playtime(at) function to get the total duration of the entire animation timeline.

Call lv_anim_timeline_get_reverse(at) function to get whether to reverse the animation timeline.

Call lv_anim_timeline_del(at) function to delete the animation timeline.

Examples

Start animation on an event

---

Playback animation

---

Animation timeline

---

API

Typedefs

typedef int32_t (*lv_anim_path_cb_t)(const struct _lv_anim_t*)[1]

Get the current value during an animation

typedef voi[2]d (*lv_anim_exec_xcb_t)(void*, int32_t)[3]

Generic prototype of "animator" functions. Fir[4]st 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 it's 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)[5]

Same as lv_anim_exec_xcb_t but receives lv_anim_t * as the first [6]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*)[7]

Callback to call when the animation is ready

[8]typedef void (*lv_anim_start_cb_t)(struct _lv_anim_t*)[9]

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

typedef int32_t (*lv_anim_get_value_cb_t)(struct _lv_anim_t*)[11]

Callback used when the animation values are relative to g[12]et the current value

typedef struct _lv_anim_t lv_anim_t[13]

Describes an animation

Enums[14]

enum lv_anim_enable_t[15]

Can be used to in[16]dicate if animations are enabled or disabled in a case Values:

enumerator LV_ANIM_OFF[17]

enumerator L[18]V_ANIM_ON[19]

Functions

[20]

LV_EXPORT_CONST_INT(LV_ANIM_REPEAT_INFINITE)[21]

LV_EXPORT_CONST_INT(LV_ANIM_PLAYTI[22]ME_INFINITE)[23]

void _lv_anim_core_init(void)[24]

I[25]nit. the animation modul[26]e

void lv_anim_init(lv_anim_t *a)[27]

Initialize an animation var[28]iable. 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)[29]

Set a variable to animate

Parameters

• a -- point[30]er 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)[31]

Set a function to animate var

Parameters

• a -- pointer to an initiali[32]zed 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)[33]

Set the duration of an animation

Parameters

• a -- pointer[34] 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)[35]

Set a delay before starting the animation

Parameters

• a[36] -- 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)[37]

Set the start and end values of an animation

Parameters

• a -- pointe[38]r 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)[39]

Similar to lv_anim_set_exec_cb but lv_anim_custom_exec_cb_t receives lv_anim_t * as its f[40]irst parameter instead of void *. This function might be used when LVGL is bound 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_data

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)[41]

Set the path (curve) of the animation.

Parameters

• a -- pointer to a[42]n initialized lv_anim_t variable
• path_cb -- a function to set the current value of the animation.

static inline void lv_anim_set_start_cb(lv_anim_t *a, lv_anim_start_cb_t start_cb)[43]

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

Pa[44]rameters

• 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)[45]

Set a function to use the current value of the variable and make start and end value relat[46]ive to 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)[47]

Set a function call when the animation is ready

Parameters

• a -- pointe[48]r 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)[49]

Make the animation to play back to when the forward direction is read[50]y

Parameters

• a -- pointer to an initialized lv_anim_t variable
• time -- the duration of the playback animation in milliseconds. 0: disable playback

static inline void lv_anim_set_playback_delay(lv_anim_t *a, uint32_t delay)[51]

Make the animation to play back to when the forward direction is ready [52]

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)[53]

Make the animation repeat itself.

Parameters

• a -- pointer t[54]o 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)[55]

Set a delay before repeating the animation.

Parameters

• a -- p[56]ointer 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)[57]

Set a whether the animation's should be applied immediately o[58]r 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

static inline void lv_anim_set_user_data(lv_anim_t *a, void *user_data)[59]

Set the custom user data field of the animation.

Parameters

• [60] a -- pointer to an initialized lv_anim_t variable
• user_data -- pointer to the new user_data.

lv_anim_t *lv_anim_start(const lv_anim_t *a)[61]

Create an animation

Parameters

a -[62]- 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)[63]

Get a delay before starting the animation

Param[64]eters

a -- pointer to an initialized lv_anim_t variable

Returns

delay before the animation in milliseconds

uint32_t lv_anim_get_playtime(lv_anim_t *a)[65]

Get the time used to play the animation[66].

Parameters

a -- pointer to an animation.

Returns

the play time in milliseconds.

static inline void *lv_anim_get_user_data(lv_anim_t *a)[67]

Get the user_data field of the animation

Paramet[68]ers

a -- pointer to an initialized lv_anim_t variable

Returns

the pointer to the custom user_data of the animation

bool lv_anim_del(void *var, lv_anim_exec_xcb_t exec_cb)[69]

Delete an animation of a variable with a given anim[70]ator 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)[71]

Delete all the animati[72]ons

lv_anim_t *lv_anim_get(void *var, lv_anim_exec_xcb_t exec_cb)[73]

Get the animation of a variable and its exec_cb.

Param[74]eters

• 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)[75]

Delete an animation by getting the animated variable from a. Only animations with[76] 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

static inline lv_anim_t *lv_anim_custom_get(lv_anim_t *a, lv_anim_custom_exec_cb_t exec_cb)[77]

Get the animation of a variable and its exec_cb. This function exists because it's logi[78]cal 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 return first matching 'var'

Returns

pointer to the animation.

uint16_t lv_anim_count_running(void)[79]

Get the number of currently runn[80]ing animations

Returns

the number of running animations

uint32_t lv_anim_speed_to_time(uint32_t speed, int32_t start, int32_t end)[81]

Calculate the time of an animation with a given speed and the start an[82]d 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)[83]

Manually refresh the st[84]ate 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)[85]

Calculate the current value of an animation[86] 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)[87]

Calculate the current value of an animation [88]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)[89]

Calculate the current value of an animation s[90]lowing 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)[91]

Calculate the current value of an animation appl[92]ying 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)[93]

Calculate the current value of an animation wi[94]th 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)[95]

Calculate the current value of an animation[96] 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)[97]

Calculate the current value of an animati[98]on 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[99]

#include <lv_[100]anim.h> Describes an animation Public Members

void *var[101]

Varia[102]ble to animate

lv_anim_exec_xcb_t exec_cb[103]

Function to execute to[104] animate

lv_anim_start_cb_t start_cb[105]

Call it when the animat[106]ion is starts (considering delay)

lv_anim_ready_cb_t ready_cb[107]

Call it when the animat[108]ion is ready

lv_anim_get_value_cb_t get_value_cb[109]

Get the current value in relati[110]ve mode

void *user_data[111]

Custom user[112] data

lv_anim_path_cb_t path_cb[113]

Describe the path (cu[114]rve) of animations

int32_t start_value[115]

Start value

[116]

int32_t current_value[117]

Current value

[118]

int32_t end_value[119]

End value

[120]

int32_t time[121]

Animatio[122]n time in ms

int32_t act_time[123]

Current time[124] in animation. Set to negative to make delay.

uint32_t playback_delay[125]

Wait before play ba[126]ck

uint32_t playback_time[127]

Duration of playba[128]ck animation

uint32_t repeat_delay[129]

Wait before repea[130]t

uint16_t repeat_cnt[131]

Repeat count fo[132]r the animation

uint8_t early_apply[133]

1: Apply start [134]value immediately even is there is delay

uint8_t playback_now[135]

Play back is in [136]progress

uint8_t run_round[137]

Indicates the[138] animation has run in this round

uint8_t start_cb_called[139]

Indicates that the [140]start_cb was already called

戻る : Previous