--- # Copyright 2025 Google LLC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. title: Animations description: | How to use Animations and Timers to add life to your app. guide_group: graphics-and-animations order: 0 related_docs: - Animation - Timer - AnimationImplementation related_examples: - title: Composite Animations Example url: https://github.com/pebble-examples/composite-animations-example - title: Feature Property Animation url: https://github.com/pebble-examples/feature-property-animation --- The ``Animation`` API allows a variety of different types of value to be smoothly animated from an initial value to a new value over time. Animations can also use built-in easing curves to affect how the transition behaves. ## Using PropertyAnimations The most common use of animations is to move a ``Layer`` (or similar) around the display. For example, to show or hide some information or animate the time changing in a watchface. The simplest method of animating a ``Layer`` (such as a ``TextLayer``) is to use a ``PropertyAnimation``, which animates a property of the target object. In this example, the target is the frame property, which is a ``GRect`` To animate the this property, ``property_animation_create_layer_frame()`` is used, which is a convenience ``PropertyAnimation`` implementation provided by the SDK. ```c static Layer *s_layer; ``` Create the Layer during ``Window`` initialization: ```c // Create the Layer s_layer = layer_create(some_bounds); ``` Determine the start and end values of the ``Layer``'s frame. These are the 'from' and 'to' locations and sizes of the ``Layer`` before and after the animation takes place: ```c // The start and end frames - move the Layer 40 pixels to the right GRect start = GRect(10, 10, 20, 20); GRect finish = GRect(50, 10, 20, 20); ``` At the appropriate time, create a ``PropertyAnimation`` to animate the ``Layer``, specifying the `start` and `finish` values as parameters: ```c // Animate the Layer PropertyAnimation *prop_anim = property_animation_create_layer_frame(s_layer, &start, &finish); ``` Configure the attributes of the ``Animation``, such as the delay before starting, and total duration (in milliseconds): ```c // Get the Animation Animation *anim = property_animation_get_animation(prop_anim); // Choose parameters const int delay_ms = 1000; const int duration_ms = 500; // Configure the Animation's curve, delay, and duration animation_set_curve(anim, AnimationCurveEaseOut); animation_set_delay(anim, delay_ms); animation_set_duration(anim, duration_ms); ``` Finally, schedule the ``Animation`` to play at the next possible opportunity (usually immediately): ```c // Play the animation animation_schedule(anim); ``` If the app requires knowledge of the start and end times of an ``Animation``, it is possible to register ``AnimationHandlers`` to be notified of these events. The handlers should be created with the signature of these examples shown below: ```c static void anim_started_handler(Animation *animation, void *context) { APP_LOG(APP_LOG_LEVEL_DEBUG, "Animation started!"); } static void anim_stopped_handler(Animation *animation, bool finished, void *context) { APP_LOG(APP_LOG_LEVEL_DEBUG, "Animation stopped!"); } ``` Register the handlers with an optional third context parameter **before** scheduling the ``Animation``: ```c // Set some handlers animation_set_handlers(anim, (AnimationHandlers) { .started = anim_started_handler, .stopped = anim_stopped_handler }, NULL); ``` With the handlers registered, the start and end times of the ``Animation`` can be detected by the app and used as appropriate. ### Other Types of PropertyAnimation In addition to ``property_animation_create_layer_frame()``, it is also possible to animate the origin of a ``Layer``'s bounds using ``property_animation_create_bounds_origin()``. Animation of more types of data can be achieved using custom implementations and one the following provided update implementations and the associated [getters and setters](``property_animation_update_int16``): * ``property_animation_update_int16`` - Animate an `int16`. * ``property_animation_update_uint32`` - Animate a `uint32`. * ``property_animation_update_gpoint`` - Animate a ``GPoint``. * ``property_animation_update_grect`` - Animate a ``GRect`` * ``property_animation_update_gcolor8`` - Animate a ``GColor8``. ## Custom Animation Implementations Beyond the convenience functions provided by the SDK, apps can implement their own ``Animation`` by using custom callbacks for each stage of the animation playback process. A ``PropertyAnimation`` is an example of such an implementation. The callbacks to implement are the `.setup`, `.update`, and `.teardown` members of an ``AnimationImplementation`` object. Some example implementations are shown below. It is in the `.update` callback where the value of `progress` can be used to modify the custom target of the animation. For example, some percentage of completion: ```c static void implementation_setup(Animation *animation) { APP_LOG(APP_LOG_LEVEL_INFO, "Animation started!"); } static void implementation_update(Animation *animation, const AnimationProgress progress) { // Animate some completion variable s_animation_percent = ((int)progress * 100) / ANIMATION_NORMALIZED_MAX; APP_LOG(APP_LOG_LEVEL_INFO, "Animation progress: %d%%", s_animation_percent); } static void implementation_teardown(Animation *animation) { APP_LOG(APP_LOG_LEVEL_INFO, "Animation finished!"); } ``` Once these are in place, create a new ``Animation`` , specifying the new custom implementation as a `const` object pointer at the appropriate time: ```c // Create a new Animation Animation *animation = animation_create(); animation_set_delay(animation, 1000); animation_set_duration(animation, 1000); // Create the AnimationImplementation const AnimationImplementation implementation = { .setup = implementation_setup, .update = implementation_update, .teardown = implementation_teardown }; animation_set_implementation(animation, &implementation); // Play the Animation animation_schedule(animation); ``` The output of the example above will look like the snippet shown below (edited for brevity). Note the effect of the easing ``AnimationCurve`` on the progress value: ```nc|text [13:42:33] main.c:11> Animation started! [13:42:34] main.c:19> Animation progress: 0% [13:42:34] main.c:19> Animation progress: 0% [13:42:34] main.c:19> Animation progress: 0% [13:42:34] main.c:19> Animation progress: 2% [13:42:34] main.c:19> Animation progress: 3% [13:42:34] main.c:19> Animation progress: 5% [13:42:34] main.c:19> Animation progress: 7% [13:42:34] main.c:19> Animation progress: 10% [13:42:34] main.c:19> Animation progress: 14% [13:42:35] main.c:19> Animation progress: 17% [13:42:35] main.c:19> Animation progress: 21% [13:42:35] main.c:19> Animation progress: 26% ... [13:42:35] main.c:19> Animation progress: 85% [13:42:35] main.c:19> Animation progress: 88% [13:42:35] main.c:19> Animation progress: 91% [13:42:35] main.c:19> Animation progress: 93% [13:42:35] main.c:19> Animation progress: 95% [13:42:35] main.c:19> Animation progress: 97% [13:42:35] main.c:19> Animation progress: 98% [13:42:35] main.c:19> Animation progress: 99% [13:42:35] main.c:19> Animation progress: 99% [13:42:35] main.c:19> Animation progress: 100% [13:42:35] main.c:23> Animation finished! ``` ## Timers [`AppTimer`](``Timer``) objects can be used to schedule updates to variables and objects at a later time. They can be used to implement frame-by-frame animations as an alternative to using the ``Animation`` API. They can also be used in a more general way to schedule events to occur at some point in the future (such as UI updates) while the app is open. A thread-blocking alternative for small pauses is ``psleep()``, but this is **not** recommended for use in loops updating UI (such as a counter), or for scheduling ``AppMessage`` messages, which rely on the event loop to do their work. > Note: To create timed events in the future that persist after an app is > closed, check out the ``Wakeup`` API. When a timer elapses, it will call a developer-defined ``AppTimerCallback``. This is where the code to be executed after the timed interval should be placed. The callback will only be called once, so use this opportunity to re-register the timer if it should repeat. ```c static void timer_callback(void *context) { APP_LOG(APP_LOG_LEVEL_INFO, "Timer elapsed!"); } ``` Schedule the timer with a specific `delay` interval, the name of the callback to fire, and an optional context pointer: ```c const int delay_ms = 5000; // Schedule the timer app_timer_register(delay_ms, timer_callback, NULL); ``` If the timer may need to be cancelled or rescheduled at a later time, ensure a reference to it is kept for later use: ```c static AppTimer *s_timer; ``` ```c // Register the timer, and keep a handle to it s_timer = app_timer_register(delay_ms, timer_callback, NULL); ``` If the timer needs to be cancelled, use the previous reference. If it has already elapsed, nothing will occur: ```c // Cancel the timer app_timer_cancel(s_timer); ``` ## Sequence and Spawn Animations The Pebble SDK also includes the capability to build up composite animations built from other ``Animation`` objects. There are two types: a sequence animation and a spawn animation. * A sequence animation is a set of two or more other animations that are played out in **series** (one after another). For example, a pair of timed animations to show and hide a ``Layer``. * A spawn animation is a set of two or more other animations that are played out in **parallel**. A spawn animation acts the same as creating and starting two or more animations at the same time, but has the advantage that it can be included as part of a sequence animation. > Note: Composite animations can be composed of other composite animations. ### Important Considerations When incorporating an ``Animation`` into a sequence or spawn animation, there are a couple of points to note: * Any single animation cannot appear more than once in the list of animations used to create a more complex animation. * A composite animation assumes ownership of its component animations once it has been created. * Once an animation has been added to a composite animation, it becomes immutable. This means it can only be read, and not written to. Attempts to modify such an animation after it has been added to a composite animation will fail. * Once an animation has been added to a composite animation, it cannot then be used to build a different composite animation. ### Creating a Sequence Animation To create a sequence animation, first create the component ``Animation`` objects that will be used to build it. ```c // Create the first Animation PropertyAnimation *prop_anim = property_animation_create_layer_frame(s_layer, &start, &finish); Animation *animation_a = property_animation_get_animation(prop_anim); // Set some properties animation_set_delay(animation_a, 1000); animation_set_duration(animation_a, 500); // Clone the first, modify the duration and reverse it. Animation *animation_b = animation_clone(animation_a); animation_set_reverse(animation_b, true); animation_set_duration(animation_b, 1000); ``` Use these component animations to create the sequence animation. You can either specify the components as a list or pass an array. Both approaches are shown below. #### Using a List You can specify up to 20 ``Animation`` objects as parameters to `animation_sequence_create()`. The list must always be terminated with `NULL` to mark the end. ```c // Create the sequence Animation *sequence = animation_sequence_create(animation_a, animation_b, NULL); // Play the sequence animation_schedule(sequence); ``` #### Using an Array You can also specify the component animations using a dynamically allocated array. Give this to `animation_sequence_create_from_array()` along with the size of the array. ```c const uint32_t array_length = 2; // Create the array Animation **arr = (Animation**)malloc(array_length * sizeof(Animation*)); arr[0] = animation_a; arr[1] = animation_b; // Create the sequence, set to loop forever Animation *sequence = animation_sequence_create_from_array(arr, array_length); animation_set_play_count(sequence, ANIMATION_DURATION_INFINITE); // Play the sequence animation_schedule(sequence); // Destroy the array free(arr); ``` ### Creating a Spawn Animation Creating a spawn animation is done in a very similiar way to a sequence animation. The animation is built up from component animations which are then all started at the same time. This simplifies the task of precisely timing animations that are designed to coincide. The first step is the same as for sequence animations, which is to create a number of component animations to be spawned together. ```c // Create the first animation Animation *animation_a = animation_create(); animation_set_duration(animation_a, 1000); // Clone the first, modify the duration and reverse it. Animation *animation_b = animation_clone(animation_a); animation_set_reverse(animation_b, true); animation_set_duration(animation_b, 300); ``` Next, the spawn animation is created in a similar manner to the sequence animation with a `NULL` terminated list of parameters: ```c // Create the spawn animation Animation *spawn = animation_spawn_create(animation_a, animation_b, NULL); // Play the animation animation_schedule(spawn); ``` Alternatively the spawn animation can be created with an array of ``Animation`` objects. ```c const uint32_t array_length = 2; // Create the array Animation **arr = (Animation**)malloc(array_length * sizeof(Animation*)); arr[0] = animation_a; arr[1] = animation_b; // Create the sequence and set the play count to 3 Animation *spawn = animation_spawn_create_from_array(arr, array_length); animation_set_play_count(spawn, 3); // Play the spawn animation animation_schedule(spawn); // Destroy the array free(arr); ```