1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
.. _animations:
==========
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:
.. code:: c
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 :cpp:expr:`lv_obj_set_x(obj, value)` or
:cpp:expr:`lv_obj_set_width(obj, value)`
.. _animations_create:
Create an animation
*******************
To create an animation an :cpp:type:`lv_anim_t` variable has to be initialized
and configured with ``lv_anim_set_...()`` functions.
.. code:: c
/* 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_duration(&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_cb(&a, lv_anim_path_ease_in);
/*Set a callback to indicate when the animation is completed.*/
lv_anim_set_completed_cb(&a, completed_cb);
/*Set a callback to indicate when the animation is deleted (idle).*/
lv_anim_set_deleted_cb(&a, deleted_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_duration(&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
:cpp:func:`lv_obj_set_x` and :cpp:func:`lv_obj_set_y`. However, only one animation can
exist with a given variable and function pair and :cpp:func:`lv_anim_start`
will remove any existing animations for such a pair.
.. _animations_path:
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:
- :cpp:func:`lv_anim_path_linear`: linear animation
- :cpp:func:`lv_anim_path_step`: change in one step at the end
- :cpp:func:`lv_anim_path_ease_in`: slow at the beginning
- :cpp:func:`lv_anim_path_ease_out`: slow at the end
- :cpp:func:`lv_anim_path_ease_in_out`: slow at the beginning and end
- :cpp:func:`lv_anim_path_overshoot`: overshoot the end value
- :cpp:func:`lv_anim_path_bounce`: bounce back a little from the end value (like
hitting a wall)
.. _animations_speed_vs_time:
Speed vs time
*************
By default, you set the animation time directly. But in some cases,
setting the animation speed is more practical.
The :cpp:expr:`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, :cpp:expr:`lv_anim_speed_to_time(20, 0, 100)` will yield 5000
milliseconds. For example, in the case of :cpp:func:`lv_obj_set_x` *unit* is
pixels so *20* means *20 px/sec* speed.
.. _animations_delete:
Delete animations
*****************
You can delete an animation with :cpp:expr:`lv_anim_delete(var, func)` if you
provide the animated variable and its animator function.
.. _animations_timeline:
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 :cpp:func:`lv_anim_start`.
Secondly, create an animation timeline object by calling
:cpp:func:`lv_anim_timeline_create`.
Thirdly, add animation elements to the animation timeline by calling
:cpp:expr:`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 :cpp:expr:`lv_anim_timeline_start(at)` to start the animation
timeline.
It supports forward and backward playback of the entire animation group,
using :cpp:expr:`lv_anim_timeline_set_reverse(at, reverse)`.
Note that if you want to play in reverse from the end of the timeline,
you need to call :cpp:expr:`lv_anim_timeline_set_progress(at, LV_ANIM_TIMELINE_PROGRESS_MAX)`
after adding all animations and before starting to play.
Call :cpp:expr:`lv_anim_timeline_stop(at)` to stop the animation timeline.
Call :cpp:expr:`lv_anim_timeline_set_progress(at, progress)` function to set the
state of the object corresponding to the progress of the timeline.
Call :cpp:expr:`lv_anim_timeline_get_playtime(at)` function to get the total
duration of the entire animation timeline.
Call :cpp:expr:`lv_anim_timeline_get_reverse(at)` function to get whether to
reverse the animation timeline.
Call :cpp:expr:`lv_anim_timeline_delete(at)` function to delete the animation timeline.
**Note**: If you need to delete an object during animation, be sure to delete the
anim timeline before deleting the object. Otherwise, the program may crash or behave abnormally.
.. image:: /misc/anim-timeline.png
.. _animations_example:
Examples
********
.. include:: ../examples/anim/index.rst
.. _animations_api:
API
***
|
