feat(docs): proofread/edit batch 9 (#7324)

Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com>

docs/details/main-components/animation.rst

@@ -4,27 +4,71 @@
 Animation (lv_anim)
 ===================
 
-You can automatically change the value of a variable between a start and
+Animations allow you to define the way something should move or change over time, and
-an end value using animations. Animation will happen by periodically
+let LVGL do the heavy lifting of making it happen.  What makes it so powerful is that
-calling an "animator" function with the corresponding value parameter.
+the thing being changed can be virtually anything in your system.  It is very
+convenient to apply this to LVGL Widgets in your user interface (UI), to change their
+appearance, size or location over time.  But because it is --- at its core --- a
+generic change-over-time manager, complete with a variety of optional event
+callbacks, its application can be wider than just to UI components.
 
-The *animator* functions have the following prototype:
+For each Animation you create, it accomplishes the above by providing a generic
+method of varying a signed integer from a start value to an end value over a
+specified time period.  It allows you to specify what object it applies to (the
+"variable"), which is available in the callback functions that are called as the
+Animation is playing through.
+
+This variation over time can be linear (default), it can be on a path (curve) that
+you specify, and there is even a variety of commonly-used non-linear effects that can
+be specified.
+
+The main callback called during an Animation (when it is playing) is called an
+*animator* function, which has the following prototype:
 
 .. code-block:: c
 
-   void func(void * var, lv_anim_var_t value);
+    void func(void *var , int32_t value);
+
+This prototype makes it easy to use most of the LVGL *set* functions directly or via a trivial wrapper. It includes:
+
+  - most of the widget properties
+  - functions that set :ref:`local style properties <style_local>`) directly on objects (needs a wrapper to set set the *selector*)
+  - set properties on :cpp:type:`lv_style_t` objects (e.g. :ref:`shared styles <style_initialize>`)  (``lv_obj_report_style_change`` needs to be called to notify the widgets having the style)
+
+- ``lv_style_set_<property_name>(&style, <value>)``
+- ``lv_obj_set_<property_name>(widget, <value>)``
+
+Because of the former, an animation on a single :cpp:type:`lv_style_t` object shared
+among several objects can simultaneously modify the appearance of all objects that
+use it.  See :ref:`styles` for more details.
+
+Examples of the latter are:  :cpp:expr:`lv_obj_set_x(widget, value)` or
+:cpp:expr:`lv_obj_set_width(widget, value)`.
+
+This makes it very convenient to apply to the appearance (and other attributes) of UI
+componenets.  But you can provide your own "set" functions, and so the application of
+Animations is really limited only by your imagination.
+
+The number of Animations that can be playing at the same time for a given object with
+a given *animator* callback is one (1).  However, the number of Animations that can
+be playing at the same time is limited only by available RAM and CPU time for:
+
+- a given object with different *animator* callbacks; and
+- different objects.
+
+Thus, you can have a Button's width being changed by one Animation while having its
+height being changed by another Animation.
+
 
-This prototype is compatible with the majority of the property *set*
-functions in LVGL. For example :cpp:expr:`lv_obj_set_x(widget, value)` or
-:cpp:expr:`lv_obj_set_width(widget, value)`
 
 .. _animations_create:
 
-Create an animation
+Create an Animation
 *******************
 
-To create an animation an :cpp:type:`lv_anim_t` variable has to be initialized
+To create an Animation, start by creating an Animation *template* in an
-and configured with ``lv_anim_set_...()`` functions.
+:cpp:type:`lv_anim_t` variable.  It has to be initialized and configured with
+``lv_anim_set_...()`` functions.
 
 .. code-block:: c
 
@@ -32,79 +76,77 @@ and configured with ``lv_anim_set_...()`` functions.
    /* INITIALIZE AN ANIMATION
     *-----------------------*/
 
-   lv_anim_t a;
+   static lv_anim_t   anim_template;
-   lv_anim_init(&a);
+   static lv_anim_t * running_anim;
+
+   lv_anim_init(&anim_template);
 
    /* MANDATORY SETTINGS
     *------------------*/
 
    /* Set the "animator" function */
-   lv_anim_set_exec_cb(&a, (lv_anim_exec_xcb_t) lv_obj_set_x);
+   lv_anim_set_exec_cb(&anim_template, (lv_anim_exec_xcb_t) lv_obj_set_x);
 
-   /* Set target of the animation */
+   /* Set target of the Animation */
-   lv_anim_set_var(&a, widget);
+   lv_anim_set_var(&anim_template, widget);
 
-   /* Length of the animation [ms] */
+   /* Length of the Animation [ms] */
-   lv_anim_set_duration(&a, duration);
+   lv_anim_set_duration(&anim_template, duration_in_ms);
 
    /* Set start and end values. E.g. 0, 150 */
-   lv_anim_set_values(&a, start, end);
+   lv_anim_set_values(&anim_template, start, end);
 
    /* OPTIONAL SETTINGS
     *------------------*/
 
-   /* Time to wait before starting the animation [ms] */
+   /* Time to wait before starting the Animation [ms] */
-   lv_anim_set_delay(&a, delay);
+   lv_anim_set_delay(&anim_template, delay);
 
    /* Set path (curve). Default is linear */
-   lv_anim_set_path_cb(&a, lv_anim_path_ease_in);
+   lv_anim_set_path_cb(&anim_template, lv_anim_path_ease_in);
 
-   /* Set a callback to indicate when the animation is completed. */
+   /* Set anim_template callback to indicate when the Animation is completed. */
-   lv_anim_set_completed_cb(&a, completed_cb);
+   lv_anim_set_completed_cb(&anim_template, completed_cb);
 
-   /* Set a callback to indicate when the animation is deleted (idle). */
+   /* Set anim_template callback to indicate when the Animation is deleted (idle). */
-   lv_anim_set_deleted_cb(&a, deleted_cb);
+   lv_anim_set_deleted_cb(&anim_template, deleted_cb);
 
-   /* Set a callback to indicate when the animation is started (after delay). */
+   /* Set anim_template callback to indicate when the Animation is started (after delay). */
-   lv_anim_set_start_cb(&a, start_cb);
+   lv_anim_set_start_cb(&anim_template, start_cb);
 
-   /* When ready, play the animation backward with this duration. Default is 0 (disabled) [ms] */
+   /* When ready, play the Animation backward with this duration. Default is 0 (disabled) [ms] */
-   lv_anim_set_playback_duration(&a, time);
+   lv_anim_set_playback_duration(&anim_template, time);
 
    /* Delay before playback. Default is 0 (disabled) [ms] */
-   lv_anim_set_playback_delay(&a, delay);
+   lv_anim_set_playback_delay(&anim_template, delay);
 
    /* Number of repetitions. Default is 1. LV_ANIM_REPEAT_INFINITE for infinite repetition */
-   lv_anim_set_repeat_count(&a, cnt);
+   lv_anim_set_repeat_count(&anim_template, cnt);
 
    /* Delay before repeat. Default is 0 (disabled) [ms] */
-   lv_anim_set_repeat_delay(&a, delay);
+   lv_anim_set_repeat_delay(&anim_template, delay);
 
-   /* true (default): apply the start value immediately, false: apply start value after delay when the anim. really starts. */
+   /* 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);
+   lv_anim_set_early_apply(&anim_template, true/false);
 
    /* START THE ANIMATION
     *------------------*/
-   lv_anim_start(&a);                             /* Start the animation */
+   running_anim = lv_anim_start(&anim_template);   /* 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
+.. _animation_path:
+
+Animation Path
 **************
 
-You can control the path of an animation. The most simple case is
+You can control the Path (curve) of an Animation.  The simplest case is linear,
-linear, meaning the current value between *start* and *end* is changed
+meaning the current value between *start* and *end* is changed at the same rate (i.e.
-with fixed steps. A *path* is a function which calculates the next value
+with fixed steps) over the duration of the Animation.  A *Path* is a function which
-to set based on the current state of the animation. Currently, there are
+calculates the next value to set based on the current state of the Animation.
-the following built-in path functions:
+There are a number of built-in *Paths* that can be used:
 
--  :cpp:func:`lv_anim_path_linear`: linear animation
+-  :cpp:func:`lv_anim_path_linear`: linear Animation (default)
 -  :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
@@ -113,70 +155,200 @@ the following built-in path functions:
 -  :cpp:func:`lv_anim_path_bounce`: bounce back a little from the end value (like
    hitting a wall)
 
-.. _animations_speed_vs_time:
+Alternately, you can provide your own Path function.
 
-Speed vs time
+:cpp:expr:`lv_anim_init(&my_anim)` sets the Path to :cpp:func:`lv_anim_path_linear`
+by default.  If you want to use a different Path (including a custom Path function
+you provide), you set it using :cpp:expr:`lv_anim_set_path_cb(&anim_template, path_cb)`.
+
+If you provide your own custom Path function, its prototype is:
+
+.. code-block:: c
+
+    int32_t   calculate_value(lv_anim_t * anim);
+
+
+
+.. _animation_speed_vs_time:
+
+Speed vs Time
 *************
 
-By default, you set the animation time directly. But in some cases,
+Normally, you set the Animation duration directly using
-setting the animation speed is more practical.
+:cpp:expr:`lv_anim_set_duration(&anim_template, duration_in_ms)`.  But in some cases
+the *rate* is known but the duration is not known.  Given an Animation's ``start``
+and ``end`` values, *rate* here means the number of units of change per second, i.e.
+how quickly (units per second) the Animation's value needs to change between the
+``start`` and ``end`` value.  For such cases there is a utility function
+:cpp:func:`lv_anim_speed_to_time` you can use to compute the Animation's duration, so
+you can set it like this:
 
-The :cpp:expr:`lv_anim_speed_to_time(speed, start, end)` function calculates the
+.. code-block:: c
-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:
+    uint32_t  change_per_sec = 20;
+    uint32_t  duration_in_ms = lv_anim_speed_to_time(change_per_sec, 0, 100);
+    /* `duration_in_ms` will be 5000 */
+    lv_anim_set_duration(&anim_template, duration_in_ms);
+
+
+
+.. _animation_direction
+
+Animating in Both Directions
+****************************
+
+Sometimes an Animation needs to play forward, and then play backwards, effectively
+reversing course, animating from the ``end`` value back to the ``start`` value again.
+To do this, pass a non-zero value to this function to set the duration for the
+reverse portion of the Animation:
+:cpp:expr:`lv_anim_set_playback_duration(&anim_template, duration_in_ms)`.
+
+Optionally, you can also introduce a delay between the forward and backward
+directions using :cpp:expr:`lv_anim_set_playback_delay(&anim_template, delay_in_ms)`
+
+
+
+.. _animation_start:
+
+Starting an Amination
+*********************
+
+After you have set up your :cpp:type:`lv_anim_t` object, it is important to realize
+that what you have set up is a "template" for a live, running Animation that has
+not been created yet.  When you call :cpp:expr:`lv_anim_start(&anim_template)`
+passing the *template* you have set up, it uses your template to dynamically allocate
+an internal object that is a *live, running* Animation.  This function returns a
+pointer to that object.
+
+.. code-block:: c
+
+    static lv_anim_t   anim_template;
+    static lv_anim_t * running_anim;
+
+    /* Set up template... */
+    lv_anim_init(&anim_template);
+    /* ...and other set-up functions above. */
+
+    /* Later... */
+    running_anim = lv_anim_start(&anim_template);
+
+.. note::
+
+    :cpp:expr:`lv_anim_start(&anim_template)` makes its own copy of the Animation
+    template, so if you do not need it later, its contents do not need to be
+    preserved after this call.
+
+Once a *live running* Animation has been started, it runs until it has completed,
+or until it is deleted (see below), whichever comes first.  An Animation has
+completed when:
+
+- its "value" has reached the desginated ``end`` value;
+- if the Animation has a non-zero *reverse* duration value, then its value
+  has run from the ``end`` value back to the ``start`` value again;
+- if a non-zero repeat count has been set, it has repeated the Animation
+  that number of times.
+
+Once the *live, running* Animation reaches completion, it is automatically deleted
+from the list of running Animations.  This does not impact your Animation template.
+
+.. note::
+
+    If :cpp:expr:`lv_anim_set_repeat_count(&anim_template, cnt)` has been called
+    passing :c:macro:`LV_ANIM_REPEAT_INFINITE`, the animation never reaches a state
+    of being "completed".  In this case, it must be deleted to terminate the
+    Animation.
+
+
+
+.. _animation_delete:
+
+Deleting Animations
+*******************
+
+You should delete an Animation using :cpp:expr:`lv_anim_delete(var, func)` if one of
+these two conditions exists:
+
+- the object (variable) being animated is deleted (and it is not a Widget) or
+- a running animation needs to be stopped before it is completed.
+
+.. note::
+
+    If the object (variable) being deleted is a type of Widget, the housekeeping code
+    involved in deleting it also deletes any running animations that are connected
+    with it.  So :cpp:expr:`lv_anim_delete(var, func)` only needs to be called if the
+    object being deleted is *not* one of the Widgets.
+
+If you kept a copy of the pointer returned by :cpp:func:`lv_anim_start` as
+``running_anim``, you can delete the running animation like this:
+
+.. code-block:: c
+
+    lv_anim_delete(running_anim->var, running_anim->exec_cb);
+
+In the event that the Animation completes *after* you have determined it needs to be
+deleted, and before the call to :cpp:func:`lv_anim_delete` is made, it does no harm
+to call it a second time --- no damage will occur.
+
+This function returns a Boolean value indicating whether any *live, running*
+Animations were deleted.
 
-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
+You can create a series of related animations that are linked together using an
-create complex composite animations.
+Animation Timeline.  A Timeline is a collection of multiple Animations which makes it
+easy to create complex composite Animations.  To create and use an Animation Timeline:
 
-Firstly, create an animation element but don't call :cpp:func:`lv_anim_start`.
+- Create an Animation template but do not call :cpp:func:`lv_anim_start` on it.
 
-Secondly, create an animation timeline object by calling
+- Create an Animation Timeline object by calling :cpp:func:`lv_anim_timeline_create`.
-:cpp:func:`lv_anim_timeline_create`.
 
-Thirdly, add animation elements to the animation timeline by calling
+- Add Animation templates to the Timeline by calling
-:cpp:expr:`lv_anim_timeline_add(at, start_time, &a)`. ``start_time`` is the
+  :cpp:expr:`lv_anim_timeline_add(timeline, start_time, &anim_template)`.
-start time of the animation on the timeline. Note that ``start_time``
+  ``start_time`` is the start time of the Animation on the Timeline.  Note that
-will override the value of ``delay``.
+  ``start_time`` will override any value given to
+  :cpp:expr:`lv_anim_set_delay(&anim_template, delay)`.
 
-Finally, call :cpp:expr:`lv_anim_timeline_start(at)` to start the animation
+- Call :cpp:expr:`lv_anim_timeline_start(timeline)` to start the Animation Timeline.
-timeline.
 
-It supports forward and backward playback of the entire animation group,
+.. note::
-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.
+    :cpp:expr:`lv_anim_timeline_add(timeline, start_time, &anim_template)` makes its
+    own copy of the contents of the Animation template, so if you do not need it
+    later, its contents do not need to be preserved after this call.
 
-Call :cpp:expr:`lv_anim_timeline_set_progress(at, progress)` function to set the
+It supports forward and backward playback of the entire Animation group, using
-state of the Widget corresponding to the progress of the timeline.
+:cpp:expr:`lv_anim_timeline_set_reverse(timeline, 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(timeline, LV_ANIM_TIMELINE_PROGRESS_MAX)`
+after adding all Animations and before telling it to start playing.
 
-Call :cpp:expr:`lv_anim_timeline_get_playtime(at)` function to get the total
+Call :cpp:expr:`lv_anim_timeline_pause(timeline)` to pause the Animation Timeline.
-duration of the entire animation timeline.
+Note:  this does not preserve its state.  The only way to start it again is to call
+:cpp:expr:`lv_anim_timeline_start(timeline)`, which starts the Timeline from the
+beginning or at the point set by
+:cpp:expr:`lv_anim_timeline_set_progress(timeline, progress)`.
 
-Call :cpp:expr:`lv_anim_timeline_get_reverse(at)` function to get whether to
+Call :cpp:expr:`lv_anim_timeline_set_progress(timeline, progress)` function to set the
-reverse the animation timeline.
+state of the Animation Timeline according to the ``progress`` value.  ``progress`` is
+a value between ``0`` and ``32767`` (:c:macro:`LV_ANIM_TIMELINE_PROGRESS_MAX`) to indicate the
+proportion of the Timeline that has "played".  Example:  a ``progress`` value of
+:cpp:expr:`LV_ANIM_TIMELINE_PROGRESS_MAX / 2` would set the Timeline playback to its
+half-way point.
 
-Call :cpp:expr:`lv_anim_timeline_delete(at)` function to delete the animation timeline.
+Call :cpp:expr:`lv_anim_timeline_get_playtime(timeline)` function to get the total
-**Note**: If you need to delete a Widget during animation, be sure to delete the
+duration (in milliseconds) of the entire Animation Timeline.
-anim timeline before deleting the Widget. Otherwise, the program may crash or behave abnormally.
+
+Call :cpp:expr:`lv_anim_timeline_get_reverse(timeline)` function to get whether the
+Animation Timeline is also played in reverse after its forward play completes.
+
+Call :cpp:expr:`lv_anim_timeline_delete(timeline)` function to delete the Animation Timeline.
+**Note**: If you need to delete a Widget during Animation, be sure to delete the
+Animation Timeline before deleting the Widget. Otherwise, the program may crash or behave abnormally.
 
 .. image:: /misc/anim-timeline.png