1# Animations
2
3You can automatically change the value of a variable between a start and an end value using animations.
4Animation will happen by periodically calling an "animator" function with the corresponding value parameter.
5
6The *animator* functions have the following prototype:
7```c
8void func(void * var, lv_anim_var_t value);
9```
10This 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)`
11
12
13## Create an animation
14To create an animation an `lv_anim_t` variable has to be initialized and configured with `lv_anim_set_...()` functions.
15
16```c
17
18/* INITIALIZE AN ANIMATION
19 *-----------------------*/
20
21lv_anim_t a;
22lv_anim_init(&a);
23
24/* MANDATORY SETTINGS
25 *------------------*/
26
27/*Set the "animator" function*/
28lv_anim_set_exec_cb(&a, (lv_anim_exec_xcb_t) lv_obj_set_x);
29
30/*Set target of the animation*/
31lv_anim_set_var(&a, obj);
32
33/*Length of the animation [ms]*/
34lv_anim_set_time(&a, duration);
35
36/*Set start and end values. E.g. 0, 150*/
37lv_anim_set_values(&a, start, end);
38
39/* OPTIONAL SETTINGS
40 *------------------*/
41
42/*Time to wait before starting the animation [ms]*/
43lv_anim_set_delay(&a, delay);
44
45/*Set path (curve). Default is linear*/
46lv_anim_set_path(&a, lv_anim_path_ease_in);
47
48/*Set a callback to indicate when the animation is ready (idle).*/
49lv_anim_set_ready_cb(&a, ready_cb);
50
51/*Set a callback to indicate when the animation is deleted (idle).*/
52lv_anim_set_deleted_cb(&a, deleted_cb);
53
54/*Set a callback to indicate when the animation is started (after delay).*/
55lv_anim_set_start_cb(&a, start_cb);
56
57/*When ready, play the animation backward with this duration. Default is 0 (disabled) [ms]*/
58lv_anim_set_playback_time(&a, time);
59
60/*Delay before playback. Default is 0 (disabled) [ms]*/
61lv_anim_set_playback_delay(&a, delay);
62
63/*Number of repetitions. Default is 1. LV_ANIM_REPEAT_INFINITE for infinite repetition*/
64lv_anim_set_repeat_count(&a, cnt);
65
66/*Delay before repeat. Default is 0 (disabled) [ms]*/
67lv_anim_set_repeat_delay(&a, delay);
68
69/*true (default): apply the start value immediately, false: apply start value after delay when the anim. really starts. */
70lv_anim_set_early_apply(&a, true/false);
71
72/* START THE ANIMATION
73 *------------------*/
74lv_anim_start(&a);                             /*Start the animation*/
75```
76
77
78You can apply multiple different animations on the same variable at the same time.
79For 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.
80
81## Animation path
82
83You 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.
84A *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:
85
86- `lv_anim_path_linear` linear animation
87- `lv_anim_path_step` change in one step at the end
88- `lv_anim_path_ease_in` slow at the beginning
89- `lv_anim_path_ease_out` slow at the end
90- `lv_anim_path_ease_in_out` slow at the beginning and end
91- `lv_anim_path_overshoot` overshoot the end value
92- `lv_anim_path_bounce` bounce back a little from the end value (like hitting a wall)
93
94
95## Speed vs time
96By default, you set the animation time directly. But in some cases, setting the animation speed is more practical.
97
98The `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.
99The 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.
100
101## Delete animations
102
103You can delete an animation with `lv_anim_del(var, func)` if you provide the animated variable and its animator function.
104
105## Timeline
106A timeline is a collection of multiple animations which makes it easy to create complex composite animations.
107
108Firstly, create an animation element but don’t call `lv_anim_start()`.
109
110Secondly, create an animation timeline object by calling `lv_anim_timeline_create()`.
111
112Thirdly, 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`.
113
114Finally, call `lv_anim_timeline_start(at)` to start the animation timeline.
115
116It supports forward and backward playback of the entire animation group, using `lv_anim_timeline_set_reverse(at, reverse)`.
117
118Call `lv_anim_timeline_stop(at)` to stop the animation timeline.
119
120Call `lv_anim_timeline_set_progress(at, progress)` function to set the state of the object corresponding to the progress of the timeline.
121
122Call `lv_anim_timeline_get_playtime(at)` function to get the total duration of the entire animation timeline.
123
124Call `lv_anim_timeline_get_reverse(at)` function to get whether to reverse the animation timeline.
125
126Call `lv_anim_timeline_del(at)` function to delete the animation timeline.
127
128![](/misc/anim-timeline.png "timeline diagram")
129
130## Examples
131
132```eval_rst
133
134.. include:: ../../examples/anim/index.rst
135
136```
137## API
138
139```eval_rst
140
141.. doxygenfile:: lv_anim.h
142  :project: lvgl
143
144```
145