All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

Detailed Description

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 the Building User Interfaces chapter in Pebble Developer Guide (chapter "Animation") for a conceptual overview of the animation framework and on how to write custom animations.

Modules

 PropertyAnimation
 Concrete animations to move a layer around over time.
 

Function Documentation

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
animationThe animation.
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
animationThe 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
animationThe animation to schedule.
See Also
animation_unschedule()
void animation_set_curve ( struct Animation *  animation,
AnimationCurve  curve 
)

Sets the animation curve for the animation.

Parameters
animationThe animation for which to set the curve.
curveThe type of curve.
See Also
AnimationCurve
Note
It is up to the implementation of the animation to actually use the curve. Because a curve type is often used for animations, it is included in the animation base layer.
void animation_set_delay ( struct Animation *  animation,
uint32_t  delay_ms 
)

Sets an optional delay for the animation.

Parameters
animationThe animation for which to set the delay.
delay_msThe 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
animationThe animation for which to set the duration.
duration_msThe 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
animationThe animation for which to set up the callbacks.
callbacksThe callbacks.
contextA pointer to application specific data, that will be passed as an argument by the animation subsystem when a callback is called.
void animation_set_implementation ( struct Animation *  animation,
const AnimationImplementation implementation 
)

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
animationThe animation for which to set the implementation.
implementationThe 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
animationThe 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.
See Also
animation_schedule()
void animation_unschedule_all ( void  )

Unschedules all animations of the application.

See Also
animation_unschedule

Data Structure Documentation

struct AnimationHandlers

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
Data Fields
AnimationStartedHandler started The handler that will be called when an animation is started.
AnimationStoppedHandler stopped The handler that will be called when an animation is stopped.
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”.

animations.png
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.

Typedef Documentation

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
animationThe 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
animationThe animation that was started.
contextThe 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
animationThe animation that was stopped.
finishedTrue if the animation was stopped because it was finished normally, or False if the animation was stopped prematurely, because it was unscheduled before finishing.
contextThe 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
animationThe animation that needs to be teared down.
See Also
animation_unschedule
AnimationSetupImplementation
typedef void(* AnimationUpdateImplementation)(struct Animation *animation, const uint32_t time_normalized)

Pointer to function that updates the animation according to the given normalized time. This callback will be called repeatedly by the animation scheduler whenever the animation needs to be updated.

Parameters
animationThe animation that needs to update; gets passed in by the animation framework.
time_normalizedThe current normalized time; gets passed in by the animation framework for each animation frame. This is a value between ANIMATION_NORMALIZED_MIN and ANIMATION_NORMALIZED_MAX. At the start of the animation, the value will be ANIMATION_NORMALIZED_MIN. At the end of the animation, the value will be ANIMATION_NORMALIZED_MAX. For each frame during the animation, the value will be the running time, mapped linearly between ANIMATION_NORMALIZED_MIN and ANIMATION_NORMALIZED_MAX. For example, say an animation was scheduled at t = 1.0s, has a delay of 1.0s and a duration of 2.0s. Then the .update callback will get called on t = 2.0s with time_normalized = ANIMATION_NORMALIZED_MIN. For each frame thereafter until t = 4.0s, the update callback will get called where time_normalized is (ANIMATION_NORMALIZED_MIN + (((ANIMATION_NORMALIZED_MAX - ANIMATION_NORMALIZED_MIN) * t) / duration)).

Enumeration Type Documentation

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.

NumAnimationCurve 

Number of available AnimationCurve types.

Macro Definition Documentation

#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 time_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 time at the end of the animation.

#define ANIMATION_NORMALIZED_MIN   0

The normalized time at the start of the animation.