lv_anim.h

Defines

LV_ANIM_REPEAT_INFINITE

LV_ANIM_PLAYTIME_INFINITE

_PARA(a, x1, y1, x2, y2)

LV_ANIM_SET_EASE_IN_SINE(a)

LV_ANIM_SET_EASE_OUT_SINE(a)

LV_ANIM_SET_EASE_IN_OUT_SINE(a)

LV_ANIM_SET_EASE_IN_QUAD(a)

LV_ANIM_SET_EASE_OUT_QUAD(a)

LV_ANIM_SET_EASE_IN_OUT_QUAD(a)

LV_ANIM_SET_EASE_IN_CUBIC(a)

LV_ANIM_SET_EASE_OUT_CUBIC(a)

LV_ANIM_SET_EASE_IN_OUT_CUBIC(a)

LV_ANIM_SET_EASE_IN_QUART(a)

LV_ANIM_SET_EASE_OUT_QUART(a)

LV_ANIM_SET_EASE_IN_OUT_QUART(a)

LV_ANIM_SET_EASE_IN_QUINT(a)

LV_ANIM_SET_EASE_OUT_QUINT(a)

LV_ANIM_SET_EASE_IN_OUT_QUINT(a)

LV_ANIM_SET_EASE_IN_EXPO(a)

LV_ANIM_SET_EASE_OUT_EXPO(a)

LV_ANIM_SET_EASE_IN_OUT_EXPO(a)

LV_ANIM_SET_EASE_IN_CIRC(a)

LV_ANIM_SET_EASE_OUT_CIRC(a)

LV_ANIM_SET_EASE_IN_OUT_CIRC(a)

LV_ANIM_SET_EASE_IN_BACK(a)

LV_ANIM_SET_EASE_OUT_BACK(a)

LV_ANIM_SET_EASE_IN_OUT_BACK(a)

Typedefs

typedef int32_t (*lv_anim_path_cb_t)(const 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 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)(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_completed_cb_t)(lv_anim_t*)

Callback to call when the animation is ready

typedef void (*lv_anim_start_cb_t)(lv_anim_t*)

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

typedef int32_t (*lv_anim_get_value_cb_t)(lv_anim_t*)

Callback used when the animation values are relative to get the current value

typedef void (*lv_anim_deleted_cb_t)(lv_anim_t*)

Callback used when the animation is deleted

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

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

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 LVGL's built-in functions can be used. E.g. lv_obj_set_x

void lv_anim_set_duration(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_time(lv_anim_t *a, uint32_t duration)

Legacy lv_anim_set_time API will be removed soon, use lv_anim_set_duration instead.

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, 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

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 bound 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 to set the current value of the animation.

void lv_anim_set_start_cb(lv_anim_t *a, lv_anim_start_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_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 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

void lv_anim_set_completed_cb(lv_anim_t *a, lv_anim_completed_cb_t completed_cb)

Set a function call when the animation is completed

Parameters:

• a – pointer to an initialized lv_anim_t variable

• completed_cb – a function call when the animation is fully completed

void lv_anim_set_deleted_cb(lv_anim_t *a, lv_anim_deleted_cb_t deleted_cb)

Set a function call when the animation is deleted.

Parameters:

• a – pointer to an initialized lv_anim_t variable

• deleted_cb – a function call when the animation is deleted

void lv_anim_set_reverse_duration(lv_anim_t *a, uint32_t duration)

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

Parameters:

• a – pointer to an initialized lv_anim_t variable

• duration – duration of playback animation in milliseconds. 0: disable playback

void lv_anim_set_reverse_time(lv_anim_t *a, uint32_t duration)

Legacy lv_anim_set_reverse_time API will be removed soon, use lv_anim_set_reverse_duration instead.

void lv_anim_set_reverse_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.

void lv_anim_set_repeat_count(lv_anim_t *a, uint32_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, 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.

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

void lv_anim_set_user_data(lv_anim_t *a, void *user_data)

Set the custom user data field of the animation.

Parameters:

• a – pointer to an initialized lv_anim_t variable

• user_data – pointer to the new user_data.

void lv_anim_set_bezier3_param(lv_anim_t *a, int16_t x1, int16_t y1, int16_t x2, int16_t y2)

Set parameter for cubic bezier path

Parameters:

• a – pointer to an initialized lv_anim_t variable

• x1 – first control point X

• y1 – first control point Y

• x2 – second control point X

• y2 – second control point Y

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)

uint32_t lv_anim_get_delay(const 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

uint32_t lv_anim_get_playtime(const lv_anim_t *a)

Get the time used to play the animation.

Parameters:

a – pointer to an animation.

Returns:

the play time in milliseconds.

uint32_t lv_anim_get_time(const lv_anim_t *a)

Get the duration of an animation

Parameters:

a – pointer to an initialized lv_anim_t variable

Returns:

the duration of the animation in milliseconds

uint32_t lv_anim_get_repeat_count(const lv_anim_t *a)

Get the repeat count of the animation.

Parameters:

a – pointer to an initialized lv_anim_t variable

Returns:

the repeat count or LV_ANIM_REPEAT_INFINITE for infinite repetition. 0: disabled repetition.

void *lv_anim_get_user_data(const lv_anim_t *a)

Get the user_data field of the animation

Parameters:

a – pointer to an initialized lv_anim_t variable

Returns:

the pointer to the custom user_data of the animation

bool lv_anim_delete(void *var, lv_anim_exec_xcb_t exec_cb)

Delete animation(s) 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_delete_all(void)

Delete all the animations

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.

lv_timer_t *lv_anim_get_timer(void)

Get global animation refresher timer.

Returns:

pointer to the animation refresher timer.

bool lv_anim_custom_delete(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

lv_anim_t *lv_anim_custom_get(lv_anim_t *a, lv_anim_custom_exec_cb_t exec_cb)

Get the animation of a variable and its exec_cb. 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 return first matching 'var'

Returns:

pointer to the animation.

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(uint32_t speed)

Store the speed as a special value which can be used as time in animations. It will be converted to time internally based on the start and end values

Parameters:

speed – the speed of the animation in with unit / sec resolution in 0..10k range

Returns:

a special value which can be used as an animation time

uint32_t lv_anim_speed_clamped(uint32_t speed, uint32_t min_time, uint32_t max_time)

Store the speed as a special value which can be used as time in animations. It will be converted to time internally based on the start and end values

Note

internally speed is stored as 10 unit/sec

Note

internally min/max_time are stored with 10 ms unit

Parameters:

• speed – the speed of the animation in as unit / sec resolution in 0..10k range

• min_time – the minimum time in 0..10k range

• max_time – the maximum time in 0..10k range

Returns:

a special value in where all three values are stored and can be used as an animation time

uint32_t lv_anim_speed_to_time(uint32_t speed, int32_t start, int32_t end)

Calculate the time of an animation based on its speed, start and end values.

Parameters:

• speed – the speed of the animation

• start – the start value

• end – the end value

Returns:

the time of the animation in milliseconds

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

int32_t lv_anim_path_custom_bezier3(const lv_anim_t *a)

A custom cubic bezier animation path, need to specify cubic-parameters in a->parameter.bezier3

Parameters:

a – pointer to an animation

Returns:

the current value to set

struct lv_anim_bezier3_para_t

#include <lv_anim.h>

Parameter used when path is custom_bezier

Public Members

int16_t x1

int16_t y1

int16_t x2

int16_t y2

struct _lv_anim_t

#include <lv_anim.h>

Describes an animation

Public Members

void *var

Variable (Widget or other user-provided object) to animate

lv_anim_exec_xcb_t exec_cb

Function to execute to animate

lv_anim_custom_exec_cb_t custom_exec_cb

Function to execute to animate, same purpose as exec_cb but different parameters

lv_anim_start_cb_t start_cb

Call it when animation is starts (considering delay)

lv_anim_completed_cb_t completed_cb

Call it when animation is fully completed

lv_anim_deleted_cb_t deleted_cb

Call it when animation is deleted

lv_anim_get_value_cb_t get_value_cb

Get current value in relative mode

void *user_data

Custom user data

lv_anim_path_cb_t path_cb

Provides path (curve) of animation

int32_t start_value

Start value

int32_t current_value

Current value

int32_t end_value

End value

int32_t duration

Animation duration in ms

int32_t act_time

Ms elapsed since animation started. Set to negative to make delay.

uint32_t reverse_delay

Wait (in ms) after forward play ends and before reverse play begins.

uint32_t reverse_duration

Reverse animation duration in ms

uint32_t repeat_delay

Wait before repeating

uint32_t repeat_cnt

Repeat count for animation

union _lv_anim_t::_lv_anim_path_para_t parameter

uint32_t last_timer_run

uint8_t reverse_play_in_progress

Reverse play is in progress

uint8_t run_round

When not equal to global.anim_state.anim_run_round (which toggles each time animation timer executes), indicates this animation needs to be updated.

uint8_t start_cb_called

Indicates that start_cb was already called

uint8_t early_apply

1: Apply start value immediately even is there is a delay

union _lv_anim_path_para_t

Public Members

lv_anim_bezier3_para_t bezier3

Parameter used when path is custom_bezier