Abstract framework to create arbitrary animations.
The Animation framework provides your Pebble app with an base layer to create arbitrary animations. The simplest way to work with animations is to use the layer frame PropertyAnimation, which enables you to move a Layer around on the screen. Using animation_set_implementation(), you can implement a custom animation.
Refer to theBuilding User Interfaces chapter in Pebble Developer Guide
(chapter "Animation") for a conceptual overview of the animation framework and on how to write custom animations.
struct Animation* animation_create |
( |
void |
) | |
|
Creates a new Animation on the heap and initalizes it with the default values.
- Duration: 250ms,
- Curve: AnimationCurveEaseInOut (ease-in-out),
- Delay: 0ms,
- Handlers:
{NULL, NULL}
(none),
- Context:
NULL
(none),
- Implementation:
NULL
(no implementation),
- Scheduled: no
- Returns
- A pointer to the animation.
NULL
if the animation could not be created
void animation_destroy |
( |
struct Animation * |
animation) | |
|
Destroys an Animation previously created by animation_create.
void* animation_get_context |
( |
struct Animation * |
animation) | |
|
Gets the application-specific callback context of the animation. This void
pointer is passed as an argument when the animation system calls AnimationHandlers callbacks. The context pointer can be set to point to any application specific data using animation_set_handlers().
- Parameters
-
- See Also
- animation_set_handlers
bool animation_is_scheduled |
( |
struct Animation * |
animation) | |
|
- Returns
- True if the animation was scheduled, or false if it was not.
- Note
- An animation will be scheduled when it is running and not finished yet. An animation that has finished is automatically unscheduled.
- Parameters
-
animation | The animation for which to get its scheduled state. |
- See Also
- animation_schedule
-
animation_unschedule
void animation_schedule |
( |
struct Animation * |
animation) | |
|
Schedules the animation. Call this once after configuring an animation to get it to start running.
If the animation's implementation has a .setup
callback it will get called before this function returns.
- Note
- If the animation was already scheduled, it will first unschedule it and then re-schedule it again. Note that in that case, the animation's
.stopped
handler, the implementation's .teardown
and .setup
will get called, due to the unscheduling and scheduling.
- Parameters
-
animation | The animation to schedule. |
- See Also
- animation_unschedule()
void animation_set_curve |
( |
struct Animation * |
animation, |
|
|
AnimationCurve |
curve |
|
) |
| |
Sets the animation curve for the animation.
- Parameters
-
animation | The animation for which to set the curve. |
curve | The type of curve. |
- See Also
- AnimationCurve
Sets a custom animation curve function.
- Parameters
-
animation | The animation for which to set the curve. |
curve_function | The custom animation curve function. |
- See Also
- AnimationCurveFunction
void animation_set_delay |
( |
struct Animation * |
animation, |
|
|
uint32_t |
delay_ms |
|
) |
| |
Sets an optional delay for the animation.
- Parameters
-
animation | The animation for which to set the delay. |
delay_ms | The delay in milliseconds that the animation system should wait from the moment the animation is scheduled to starting the animation. |
void animation_set_duration |
( |
struct Animation * |
animation, |
|
|
uint32_t |
duration_ms |
|
) |
| |
Sets the time in milliseconds that an animation takes from start to finish.
- Parameters
-
animation | The animation for which to set the duration. |
duration_ms | The duration in milliseconds of the animation. This excludes any optional delay as set using animation_set_delay(). |
void animation_set_handlers |
( |
struct Animation * |
animation, |
|
|
AnimationHandlers |
callbacks, |
|
|
void * |
context |
|
) |
| |
Sets the callbacks for the animation. Often an application needs to run code at the start or at the end of an animation. Using this function is possible to register callback functions with an animation, that will get called at the start and end of the animation.
- Parameters
-
animation | The animation for which to set up the callbacks. |
callbacks | The callbacks. |
context | A pointer to application specific data, that will be passed as an argument by the animation subsystem when a callback is called. |
Sets the implementation of the custom animation. When implementing custom animations, use this function to specify what functions need to be called to for the setup, frame update and teardown of the animation.
- Parameters
-
animation | The animation for which to set the implementation. |
implementation | The structure with function pointers to the implementation of the setup, update and teardown functions. |
- See Also
- AnimationImplementation
void animation_unschedule |
( |
struct Animation * |
animation) | |
|
Unschedules the animation, which in effect stops the animation.
- Parameters
-
animation | The animation to unschedule. |
- Note
- If the animation was not yet finished, unscheduling it will cause its
.stopped
handler to get called, with the "finished" argument set to false.
-
If the animation is not scheduled or NULL, calling this routine is effectively a no-op
- See Also
- animation_schedule()
void animation_unschedule_all |
( |
void |
) | |
|
The handlers that will get called when an animation starts and stops. See documentation with the function pointer types for more information.
- See Also
- animation_set_handlers
struct AnimationImplementation |
The 3 callbacks that implement a custom animation. Only the .update
callback is mandatory, .setup
and .teardown
are optional. See the documentation with the function pointer typedefs for more information.
- Note
- The
.setup
callback is called immediately after scheduling the animation, regardless if there is a delay set for that animation using animation_set_delay().
The diagram below illustrates the order in which callbacks can be expected to get called over the life cycle of an animation. It also illustrates where the implementation of different animation callbacks are intended to be “living”.
- See Also
- AnimationSetupImplementation
-
AnimationUpdateImplementation
-
AnimationTeardownImplementation
Data Fields |
AnimationSetupImplementation |
setup |
Called by the animation system when an animation is scheduled, to prepare it for running. This callback is optional and can be left NULL when not needed. |
AnimationTeardownImplementation |
teardown |
Called by the animation system when an animation is unscheduled, to clean up after it has run. This callback is optional and can be left NULL when not needed. |
AnimationUpdateImplementation |
update |
Called by the animation system when the animation needs to calculate the next animation frame. This callback is mandatory and should not be left NULL . |
The function pointer type of a custom animation curve.
- Parameters
-
linear_distance | The linear normalized animation distance to be curved. |
- See Also
- animation_set_custom_curve
typedef void(* AnimationSetupImplementation)(struct Animation *animation) |
Pointer to function that (optionally) prepares the animation for running. This callback is called when the animation is added to the scheduler.
- Parameters
-
animation | The animation that needs to be set up. |
- See Also
- animation_schedule
-
AnimationTeardownImplementation
typedef void(* AnimationStartedHandler)(struct Animation *animation, void *context) |
The function pointer type of the handler that will be called when an animation is started, just before updating the first frame of the animation.
- Parameters
-
animation | The animation that was started. |
context | The pointer to custom, application specific data, as set using animation_set_handlers() |
- Note
- This is called after any optional delay as set by animation_set_delay() has expired.
- See Also
- animation_set_handlers
typedef void(* AnimationStoppedHandler)(struct Animation *animation, bool finished, void *context) |
The function pointer type of the handler that will be called when the animation is stopped.
- Parameters
-
animation | The animation that was stopped. |
finished | True if the animation was stopped because it was finished normally, or False if the animation was stopped prematurely, because it was unscheduled before finishing. |
context | The pointer to custom, application specific data, as set using animation_set_handlers() |
- See Also
- animation_set_handlers
typedef void(* AnimationTeardownImplementation)(struct Animation *animation) |
Pointer to function that (optionally) cleans up the animation. This callback is called when the animation is removed from the scheduler. In case the .setup
implementation allocated any memory, this is a good place to release that memory again.
- Parameters
-
animation | The animation that needs to be teared down. |
- See Also
- animation_unschedule
-
AnimationSetupImplementation
typedef void(* AnimationUpdateImplementation)(struct Animation *animation, const uint32_t distance_normalized) |
Pointer to function that updates the animation according to the given normalized distance. This callback will be called repeatedly by the animation scheduler whenever the animation needs to be updated.
- Parameters
-
Values that are used to indicate the different animation curves, which determine the speed at which the animated value(s) change(s).
Enumerator |
---|
AnimationCurveLinear |
Linear curve: the velocity is constant.
|
AnimationCurveEaseIn |
Bicubic ease-in: accelerate from zero velocity.
|
AnimationCurveEaseOut |
Bicubic ease-in: decelerate to zero velocity.
|
AnimationCurveEaseInOut |
Bicubic ease-in-out: accelerate from zero velocity, decelerate to zero velocity.
|
AnimationCurveCustomFunction |
Custom (user-provided) animation curve.
|
AnimationCurve_Reserved1 |
Reserved for forward-compatibility use.
|
#define ANIMATION_DURATION_INFINITE ((uint32_t) ~0) |
Constant to indicate "infinite" duration. This can be used with animation_set_duration() to indicate that the animation should run indefinitely. This is useful when implementing for example a frame-by-frame simulation that does not have a clear ending (e.g. a game).
- Note
- Note that
distance_normalized
parameter that is passed into the .update
implementation is meaningless in when an infinite duration is used.
#define ANIMATION_NORMALIZED_MAX 65535 |
The normalized distance at the end of the animation.
#define ANIMATION_NORMALIZED_MIN 0 |
The normalized distance at the start of the animation.