Abstract framework to create arbitrary animations. More...

Collaboration diagram for Animation:

Modules
	PropertyAnimation
	A ProperyAnimation animates the value of a "property" of a "subject" over time.

Classes
struct	AnimationHandlers

struct	AnimationImplementation

Macros
#define	ANIMATION_DURATION_INFINITE UINT32_MAX

#define	ANIMATION_PLAY_COUNT_INFINITE UINT32_MAX

#define	ANIMATION_NORMALIZED_MIN 0
	The normalized distance at the start of the animation.

#define	ANIMATION_NORMALIZED_MAX 65535
	The normalized distance at the end of the animation.

Typedefs
typedef struct Animation	Animation

typedef int32_t	AnimationProgress

typedef AnimationProgress(*	AnimationCurveFunction) (AnimationProgress linear_distance)

typedef void(*	AnimationStartedHandler) (Animation animation, void context)

typedef void(*	AnimationStoppedHandler) (Animation animation, bool finished, void context)

typedef struct AnimationHandlers	AnimationHandlers

typedef void(*	AnimationSetupImplementation) (Animation *animation)

typedef void(*	AnimationUpdateImplementation) (Animation *animation, const AnimationProgress progress)

typedef void(*	AnimationTeardownImplementation) (Animation *animation)

typedef struct AnimationImplementation	AnimationImplementation

Enumerations
enum	AnimationCurve { AnimationCurveLinear = 0, AnimationCurveEaseIn = 1, AnimationCurveEaseOut = 2, AnimationCurveEaseInOut = 3, AnimationCurveDefault = AnimationCurveEaseInOut, AnimationCurveCustomFunction = 4, AnimationCurveCustomInterpolationFunction = 5, AnimationCurve_Reserved1 = 6, AnimationCurve_Reserved2 = 7 }

Functions
Animation *	animation_create (void)

bool	animation_destroy (Animation *animation)

Animation *	animation_clone (Animation *from)

Animation *	animation_sequence_create (Animation animation_a, Animation animation_b, Animation *animation_c,...)

Animation *	animation_sequence_create_from_array (Animation **animation_array, uint32_t array_len)

Animation *	animation_spawn_create (Animation animation_a, Animation animation_b, Animation *animation_c,...)

Animation *	animation_spawn_create_from_array (Animation **animation_array, uint32_t array_len)

bool	animation_set_elapsed (Animation *animation, uint32_t elapsed_ms)

bool	animation_get_elapsed (Animation animation, int32_t elapsed_ms)

bool	animation_set_reverse (Animation *animation, bool reverse)

bool	animation_get_reverse (Animation *animation)

bool	animation_set_play_count (Animation *animation, uint32_t play_count)

uint32_t	animation_get_play_count (Animation *animation)

bool	animation_set_duration (Animation *animation, uint32_t duration_ms)

uint32_t	animation_get_duration (Animation *animation, bool include_delay, bool include_play_count)

bool	animation_set_delay (Animation *animation, uint32_t delay_ms)

uint32_t	animation_get_delay (Animation *animation)

bool	animation_set_curve (Animation *animation, AnimationCurve curve)

AnimationCurve	animation_get_curve (Animation *animation)

bool	animation_set_custom_curve (Animation *animation, AnimationCurveFunction curve_function)

AnimationCurveFunction	animation_get_custom_curve (Animation *animation)

bool	animation_set_handlers (Animation animation, AnimationHandlers callbacks, void context)

void *	animation_get_context (Animation *animation)

bool	animation_schedule (Animation *animation)

bool	animation_unschedule (Animation *animation)

void	animation_unschedule_all (void)

bool	animation_is_scheduled (Animation *animation)

bool	animation_set_implementation (Animation animation, const AnimationImplementation implementation)

const AnimationImplementation *	animation_get_implementation (Animation *animation)

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

Macro Definition Documentation

◆ ANIMATION_DURATION_INFINITE

#define ANIMATION_DURATION_INFINITE UINT32_MAX

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.; This can be returned by animation_get_duration (if the play count is infinite)

◆ ANIMATION_PLAY_COUNT_INFINITE

#define ANIMATION_PLAY_COUNT_INFINITE UINT32_MAX

Constant to indicate infinite play count. Can be passed to animation_set_play_count() to repeat indefinitely.

Note: This can be returned by animation_get_play_count().

Typedef Documentation

◆ AnimationCurveFunction

typedef AnimationProgress(* AnimationCurveFunction) (AnimationProgress linear_distance)

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

◆ AnimationHandlers

typedef struct AnimationHandlers 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

◆ AnimationImplementation

typedef struct AnimationImplementation 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

◆ AnimationProgress

typedef int32_t AnimationProgress

The type used to represent how far an animation has progressed. This is passed to the animation's update handler

◆ AnimationSetupImplementation

typedef void(* AnimationSetupImplementation) (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

◆ AnimationStartedHandler

typedef void(* AnimationStartedHandler) (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

◆ AnimationStoppedHandler

typedef void(* AnimationStoppedHandler) (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

Note: This animation (i.e.: the animation parameter) may be destroyed here. It is not recommended to unschedule or destroy a different Animation within this Animation's stopped handler.

◆ AnimationTeardownImplementation

typedef void(* AnimationTeardownImplementation) (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

◆ AnimationUpdateImplementation

typedef void(* AnimationUpdateImplementation) (Animation *animation, const AnimationProgress progress)

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

Parameters

animation The animation that needs to update; gets passed in by the animation framework.

progress

The current normalized progress; gets passed in by the animation framework for each animation frame. The value ANIMATION_NORMALIZED_MIN represents the start and ANIMATION_NORMALIZED_MAX represents the end. Values outside this range (generated by a custom curve function) can be used to implement features like a bounce back effect, where the progress exceeds the desired final value before returning to complete the animation. When using a system provided curve function, each frame during the animation will have a progress value between ANIMATION_NORMALIZED_MIN and ANIMATION_NORMALIZED_MAX based on the animation duration and the AnimationCurve. For example, say an animation was scheduled at t = 1.0s, has a delay of 1.0s, a duration of 2.0s and a curve of AnimationCurveLinear. Then the .update callback will get called on t = 2.0s with distance_normalized = ANIMATION_NORMALIZED_MIN. For each frame thereafter until t = 4.0s, the update callback will get called where distance_normalized is (ANIMATION_NORMALIZED_MIN

(((ANIMATION_NORMALIZED_MAX - ANIMATION_NORMALIZED_MIN) * t) / duration)). Other system animation curve functions will result in a non-linear relation between distance_normalized and time.

Enumeration Type Documentation

◆ AnimationCurve

enum AnimationCurve

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.
AnimationCurveCustomInterpolationFunction	User-provided interpolation function.

Function Documentation

◆ animation_create()

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

◆ animation_destroy()

bool animation_destroy ( Animation * animation )

Destroys an Animation previously created by animation_create.

Returns: true if successful, false on failure

◆ animation_get_context()

void* animation_get_context ( 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

animation The animation.

See also: animation_set_handlers

◆ animation_get_curve()

AnimationCurve animation_get_curve ( Animation * animation )

Gets the animation curve for the animation.

Parameters

animation The animation for which to get the curve.

Returns: The type of curve.

◆ animation_get_custom_curve()

AnimationCurveFunction animation_get_custom_curve ( Animation * animation )

Gets the custom animation curve function for the animation.

Parameters

animation The animation for which to get the curve.

Returns: The custom animation curve function for the given animation. NULL if not set.

◆ animation_get_delay()

uint32_t animation_get_delay ( Animation * animation )

Get the delay of an animation in milliseconds

Parameters

animation The animation for which to get the setting

Returns: the delay in milliseconds

◆ animation_get_duration()

uint32_t animation_get_duration	(	Animation *	animation,
		bool	include_delay,
		bool	include_play_count
	)

Get the static duration of an animation from start to end (ignoring how much has already played, if any).

Parameters

animation	The animation for which to get the duration
include_delay	if true, include the delay time
include_play_count	if true, incorporate the play_count

Returns: the duration, in milliseconds. This includes any optional delay a set using animation_set_delay.

◆ animation_get_elapsed()

bool animation_get_elapsed	(	Animation *	animation,
		int32_t *	elapsed_ms
	)

Get the current location in the animation.

Note: The animation must be scheduled to get the elapsed time. If it is not schedule, this method will return false.

Parameters

	animation	The animation for which to fetch the elapsed.
[out]	elapsed_ms	pointer to variable that will contain the elapsed time in milliseconds

Returns: true if successful, false on failure

◆ animation_get_implementation()

const AnimationImplementation* animation_get_implementation ( Animation * animation )

Gets the implementation of the custom animation.

Parameters

animation The animation for which to get the implementation.

See also: AnimationImplementation

Returns: NULL if animation implementation has not been setup.

◆ animation_get_play_count()

uint32_t animation_get_play_count ( Animation * animation )

Get the play count of an animation

Parameters

animation The animation for which to get the setting

Returns: the play count

◆ animation_get_reverse()

bool animation_get_reverse ( Animation * animation )

Get the reverse setting of an animation

Parameters

animation The animation for which to get the setting

Returns: the reverse setting

◆ animation_is_scheduled()

bool animation_is_scheduled ( 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. For convenience, passing in a NULL animation argument will simply return false

Parameters

animation The animation for which to get its scheduled state.

See also: animation_schedule; animation_unschedule

◆ animation_schedule()

bool animation_schedule ( 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()

Returns: true if successful, false on failure

◆ animation_sequence_create()

Animation* animation_sequence_create	(	Animation *	animation_a,
		Animation *	animation_b,
		Animation *	animation_c,
			...
	)

Create a new sequence animation from a list of 2 or more other animations. The returned animation owns the animations that were provided as arguments and no further write operations on those handles are allowed. The variable length argument list must be terminated with a NULL ptr

Note: the maximum number of animations that can be supplied to this method is 20

Parameters

animation_a	the first required component animation
animation_b	the second required component animation
animation_c	either the third component, or NULL if only adding 2 components

Returns: The newly created sequence animation

◆ animation_sequence_create_from_array()

Animation* animation_sequence_create_from_array	(	Animation **	animation_array,
		uint32_t	array_len
	)

An alternate form of animation_sequence_create() that accepts an array of other animations.

Note: the maximum number of elements allowed in animation_array is 256

Parameters

animation_array	an array of component animations to include
array_len	the number of elements in the animation_array

Returns: The newly created sequence animation

◆ animation_set_curve()

bool animation_set_curve	(	Animation *	animation,
		AnimationCurve	curve
	)

Sets the animation curve for the animation.

Note: Trying to set an attribute when an animation is immutable will return false (failure). An animation is immutable once it has been added to a sequence or spawn animation or has been scheduled.

Parameters

animation	The animation for which to set the curve.
curve	The type of curve.

See also: AnimationCurve

Returns: true if successful, false on failure

◆ animation_set_custom_curve()

bool animation_set_custom_curve	(	Animation *	animation,
		AnimationCurveFunction	curve_function
	)

Sets a custom animation curve function.

Note: Trying to set an attribute when an animation is immutable will return false (failure). An animation is immutable once it has been added to a sequence or spawn animation or has been scheduled.

Parameters

animation	The animation for which to set the curve.
curve_function	The custom animation curve function.

See also: AnimationCurveFunction

Returns: true if successful, false on failure

◆ animation_set_delay()

bool animation_set_delay	(	Animation *	animation,
		uint32_t	delay_ms
	)

Sets an optional delay for the animation.

Note: Trying to set an attribute when an animation is immutable will return false (failure). An animation is immutable once it has been added to a sequence or spawn animation or has been scheduled.

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.

Returns: true if successful, false on failure

◆ animation_set_duration()

bool animation_set_duration	(	Animation *	animation,
		uint32_t	duration_ms
	)

Sets the time in milliseconds that an animation takes from start to finish.

Note: Trying to set an attribute when an animation is immutable will return false (failure). An animation is immutable once it has been added to a sequence or spawn animation or has been scheduled.

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().

Returns: true if successful, false on failure

◆ animation_set_elapsed()

bool animation_set_elapsed	(	Animation *	animation,
		uint32_t	elapsed_ms
	)

Seek to a specific location in the animation. Only forward seeking is allowed. Returns true if successful, false if the passed in seek location is invalid.

Parameters

animation	the animation for which to set the elapsed.
elapsed_ms	the new elapsed time in milliseconds

Returns: true if successful, false if the requested elapsed is invalid.

◆ animation_set_handlers()

bool animation_set_handlers	(	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.

Note: Trying to set an attribute when an animation is immutable will return false (failure). An animation is immutable once it has been added to a sequence or spawn animation or has been scheduled.

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.

Returns: true if successful, false on failure

◆ animation_set_implementation()

bool animation_set_implementation	(	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.

Note: Trying to set an attribute when an animation is immutable will return false (failure). An animation is immutable once it has been added to a sequence or spawn animation or has been scheduled.

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

Returns: true if successful, false on failure

◆ animation_set_play_count()

bool animation_set_play_count	(	Animation *	animation,
		uint32_t	play_count
	)

Set an animation to play N times. The default is 1.

Note: Trying to set an attribute when an animation is immutable will return false (failure). An animation is immutable once it has been added to a sequence or spawn animation or has been scheduled.

Parameters

animation	the animation to set the play count of
play_count	number of times to play this animation. Set to ANIMATION_PLAY_COUNT_INFINITE to make an animation repeat indefinitely.

Returns: true if successful, false on failure

◆ animation_set_reverse()

bool animation_set_reverse	(	Animation *	animation,
		bool	reverse
	)

Set an animation to run in reverse (or forward)

Note: Trying to set an attribute when an animation is immutable will return false (failure). An animation is immutable once it has been added to a sequence or spawn animation or has been scheduled.

Parameters

animation	the animation to operate on
reverse	set to true to run in reverse, false to run forward

Returns: true if successful, false on failure

◆ animation_spawn_create()

Animation* animation_spawn_create	(	Animation *	animation_a,
		Animation *	animation_b,
		Animation *	animation_c,
			...
	)

Create a new spawn animation from a list of 2 or more other animations. The returned animation owns the animations that were provided as arguments and no further write operations on those handles are allowed. The variable length argument list must be terminated with a NULL ptr

Note: the maximum number of animations that can be supplied to this method is 20

Parameters

animation_a	the first required component animation
animation_b	the second required component animation
animation_c	either the third component, or NULL if only adding 2 components

Returns: The newly created spawn animation or NULL on failure

◆ animation_spawn_create_from_array()

Animation* animation_spawn_create_from_array	(	Animation **	animation_array,
		uint32_t	array_len
	)

An alternate form of animation_spawn_create() that accepts an array of other animations.

Note: the maximum number of elements allowed in animation_array is 256

Parameters

animation_array	an array of component animations to include
array_len	the number of elements in the animation_array

Returns: The newly created spawn animation or NULL on failure

◆ animation_unschedule()

bool animation_unschedule ( 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()

Returns: true if successful, false on failure

◆ animation_unschedule_all()

void animation_unschedule_all ( void )

Unschedules all animations of the application.

See also: animation_unschedule

Modules

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ANIMATION_DURATION_INFINITE

◆ ANIMATION_PLAY_COUNT_INFINITE

Typedef Documentation

◆ AnimationCurveFunction

◆ AnimationHandlers

◆ AnimationImplementation

◆ AnimationProgress

◆ AnimationSetupImplementation

◆ AnimationStartedHandler

◆ AnimationStoppedHandler

◆ AnimationTeardownImplementation

◆ AnimationUpdateImplementation

Enumeration Type Documentation

◆ AnimationCurve

Function Documentation

◆ animation_create()

◆ animation_destroy()

◆ animation_get_context()

◆ animation_get_curve()

◆ animation_get_custom_curve()

◆ animation_get_delay()

◆ animation_get_duration()

◆ animation_get_elapsed()

◆ animation_get_implementation()

◆ animation_get_play_count()

◆ animation_get_reverse()

◆ animation_is_scheduled()

◆ animation_schedule()

◆ animation_sequence_create()

◆ animation_sequence_create_from_array()

◆ animation_set_curve()

◆ animation_set_custom_curve()

◆ animation_set_delay()

◆ animation_set_duration()

◆ animation_set_elapsed()

◆ animation_set_handlers()

◆ animation_set_implementation()

◆ animation_set_play_count()

◆ animation_set_reverse()

◆ animation_spawn_create()

◆ animation_spawn_create_from_array()

◆ animation_unschedule()

◆ animation_unschedule_all()