pebble
  • Tutorials
  • Get the SDK
  • Guides
  • Documentation
  • Examples
  • Community
  • Blog
  • More
Privacy
Cookies
Publish

Pebble C API

  • Pebble C API
  • Pebble JavaScript API
  • PebbleKit JS
  • PebbleKit iOS
  • PebbleKit Android
  • Foundation
    • App
    • App Communication
    • App Glance
    • AppMessage
    • AppSync
    • AppWorker
    • DataLogging
    • DataStructures
      • UUID
    • Dictation
    • Dictionary
    • Event Service
      • AccelerometerService
      • AppFocusService
      • BatteryStateService
      • CompassService
      • ConnectionService
      • HealthService
      • TickTimerService
    • Exit Reason
    • Internationalization
    • Launch Reason
    • Logging
    • Math
    • Memory Management
    • Platform
    • Resources
      • File Formats
    • Storage
    • Timer
    • Wakeup
    • Wall Time
    • WatchInfo
    • Rocky
  • Graphics
    • Draw Commands
    • Drawing Paths
    • Drawing Primitives
    • Drawing Text
    • Fonts
    • Graphics Context
    • Graphics Types
      • Color Definitions
  • User Interface
    • Animation
      • PropertyAnimation
    • Clicks
    • Layers
      • ActionBarLayer
      • BitmapLayer
      • MenuLayer
      • RotBitmapLayer
      • ScrollLayer
      • SimpleMenuLayer
      • StatusBarLayer
      • TextLayer
    • Light
    • Preferences
    • UnobstructedArea
    • Vibes
    • Window
      • ActionMenu
      • NumberWindow
    • Window Stack
  • Standard C
    • Format
    • Locale
    • Math
    • Memory
    • String
    • Time

Animation

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

Modules

PropertyAnimation

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

Function Documentation

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

bool animation_destroy(Animation * animation)

Destroys an Animation previously created by animation_create.

Returns

true if successful, false on failure

Animation * animation_clone(Animation * from)
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 * 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 * 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 * 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

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.

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.

elapsed_ms (out)

pointer to variable that will contain the elapsed time in milliseconds

Returns

true if successful, false on failure

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

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

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

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

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

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.

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

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

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.

Returns

true if successful, false on failure

See Also

AnimationCurve
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.

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.

Returns

true if successful, false on failure

See Also

AnimationCurveFunction
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.

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

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

Returns

true if successful, false on failure

See Also

animation_unschedule()
bool animation_unschedule(Animation * animation)

Unschedules the animation, which in effect stops the animation.

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

Parameters

animation

The animation to unschedule.

Returns

true if successful, false on failure

See Also

animation_schedule()
void animation_unschedule_all(void)

Unschedules all animations of the application.

See Also

animation_unschedule
bool animation_is_scheduled(Animation * animation)

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.

Returns

True if the animation was scheduled, or false if it was not.

See Also

animation_schedule
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.

Returns

true if successful, false on failure

See Also

AnimationImplementation
const AnimationImplementation * animation_get_implementation(Animation * animation)

Gets the implementation of the custom animation.

Parameters

animation

The animation for which to get the implementation.

Returns

NULL if animation implementation has not been setup.

See Also

AnimationImplementation

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.

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.

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.

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”.

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

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.

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.

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.

See Also

AnimationSetupImplementation

Enum Documentation

enum AnimationCurve

Values that are used to indicate the different animation curves, which determine the speed at which the animated value(s) change(s).

Enumerators

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.

AnimationCurveDefault
AnimationCurveCustomFunction

Custom (user-provided) animation curve.

AnimationCurveCustomInterpolationFunction

User-provided interpolation function.

AnimationCurve_Reserved1
AnimationCurve_Reserved2

Typedef Documentation

typedef struct Animation Animation
typedef int32_t AnimationProgress

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

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

Note

This is called after any optional delay as set by animation_set_delay() has expired.

Parameters

animation

The animation that was started.

context

The pointer to custom, application specific data, as set using animation_set_handlers()

See Also

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

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.

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

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

Macro Definition Documentation

#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)

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

#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.

Need some help?

Modules

  • PropertyAnimation

Functions

  • animation_create
  • animation_destroy
  • animation_clone
  • animation_sequence_create
  • animation_sequence_create_from_array
  • animation_spawn_create
  • animation_spawn_create_from_array
  • animation_set_elapsed
  • animation_get_elapsed
  • animation_set_reverse
  • animation_get_reverse
  • animation_set_play_count
  • animation_get_play_count
  • animation_set_duration
  • animation_get_duration
  • animation_set_delay
  • animation_get_delay
  • animation_set_curve
  • animation_get_curve
  • animation_set_custom_curve
  • animation_get_custom_curve
  • animation_set_handlers
  • animation_get_context
  • animation_schedule
  • animation_unschedule
  • animation_unschedule_all
  • animation_is_scheduled
  • animation_set_implementation
  • animation_get_implementation

Data Structures

  • AnimationHandlers
  • AnimationImplementation

Enums

  • AnimationCurve

Typedefs

  • Animation
  • AnimationProgress
  • AnimationCurveFunction
  • AnimationStartedHandler
  • AnimationStoppedHandler
  • AnimationSetupImplementation
  • AnimationUpdateImplementation
  • AnimationTeardownImplementation

Macro Defintions

  • ANIMATION_DURATION_INFINITE
  • ANIMATION_PLAY_COUNT_INFINITE
  • ANIMATION_NORMALIZED_MIN
  • ANIMATION_NORMALIZED_MAX

Getting Help

Do you have questions about the Pebble SDK?

Do you need some help understanding something on this page?

You can either take advantage of our awesome developer community and check out the SDK Help forums, or you can send us a message through the website!