Concrete animations to move a layer around over time.
Actually, property animations do more than just moving a Layer around over time. PropertyAnimation is a concrete class of animations and is built around the Animation subsystem, which covers anything timing related, but does not move anything around. A ProperyAnimation animates a "property" of a "subject".
Animating a Layer's frame property
Currently there is only one specific type of property animation offered off-the-shelf, namely one to change the frame (property) of a layer (subject), see property_animation_create_layer_frame().
Implementing a custom PropertyAnimation
It is fairly simple to create your own variant of a PropertyAnimation.
Please refer to Building User Interfaces chapter in Pebble Developer Guide
(chapter "Property Animations") for a conceptual overview of the animation framework and make sure you understand the underlying Animation, in case you are not familiar with it, before trying to implement a variation on PropertyAnimation.
To implement a custom property animation, use property_animation_create() and provide a function pointers to the accessors (getter and setter) and setup, update and teardown callbacks in the implementation argument. Note that the type of property to animate with PropertyAnimation is limited to int16_t, GPoint or GRect.
For each of these types, there are implementations provided for the necessary .update
handler of the animation: see property_animation_update_int16(), property_animation_update_gpoint() and property_animation_update_grect(). These update functions expect the .accessors
to conform to the following interface: Any getter needs to have the following function signature: __type__ getter(void *subject);
Any setter needs to have to following function signature: void setter(void *subject, __type__ value);
See Int16Getter, Int16Setter, GPointGetter, GPointSetter, GRectGetter, GRectSetter for the typedefs that accompany the update fuctions.
},
.accessors = {
.setter = { .gpoint = my_layer_set_corner_point, },
.getter = { .gpoint = (
const GPointGetter) my_layer_get_corner_point, },
},
};
static PropertyAnimation* s_my_animation_ptr = NULL;
...
struct PropertyAnimation* property_animation_create |
( |
const struct PropertyAnimationImplementation * |
implementation, |
|
|
void * |
subject, |
|
|
void * |
from_value, |
|
|
void * |
to_value |
|
) |
| |
Creates a new PropertyAnimation on the heap and and initializes it with the specified values. The same defaults are used as with animation_create(). If the from_value
or the to_value
is NULL
, the getter accessor will be called to get the current value of the property and be used instead.
- Parameters
-
implementation | Pointer to the implementation of the animation. In most cases, it makes sense to pass in a static const struct pointer. |
subject | Pointer to the "subject" being animated. This will be passed in when the getter/setter accessors are called, see PropertyAnimationAccessors, GPointSetter, and friends. The value of this pointer will be copied into the .subject field of the PropertyAnimation struct. |
from_value | Pointer to the value that the subject should animate from |
to_value | Pointer to the value that the subject should animate to |
- Note
- Pass in
NULL
as one of the value arguments to have it set automatically to the subject's current property value, as returned by the getter function. Also note that passing in NULL
for both from_value
and to_value
, will result in the animation having the same from- and to- values, effectively not doing anything.
- Returns
- A pointer to the property animation.
NULL
if animation could not be created
struct PropertyAnimation* property_animation_create_layer_frame |
( |
struct Layer * |
layer, |
|
|
GRect * |
from_frame, |
|
|
GRect * |
to_frame |
|
) |
| |
Convenience function to create and initialize a property animation that animates the frame of a Layer. It sets up the PropertyAnimation to use layer_set_frame() and layer_get_frame() as accessors and uses the layer
parameter as the subject for the animation. The same defaults are used as with animation_create().
- Parameters
-
property_animation | The property animation to initialize and set up |
layer | the layer that will be animated |
to_frame | the frame that the layer should animate to |
from_frame | the frame that the layer should animate from |
- Note
- Pass in
NULL
as one of the frame arguments to have it set automatically to the layer's current frame. This will result in a call to layer_get_frame() to get the current frame of the layer.
- Returns
- A pointer to the property animation.
NULL
if animation could not be created
void property_animation_destroy |
( |
struct PropertyAnimation * |
property_animation | ) |
|
Free a dynamically allocated property animation.
- Parameters
-
property_animation | The property animation to be freed. |
void property_animation_update_gpoint |
( |
struct PropertyAnimation * |
property_animation, |
|
|
const uint32_t |
time_normalized |
|
) |
| |
Default update callback for a property animations to update a property of type GPoint. Assign this function to the .base.update
callback field of your PropertyAnimationImplementation, in combination with a .getter
and .setter
accessors of types GPointGetter and GPointSetter. The implementation of this function will calculate the next point of the animation and call the setter to set the new point upon the subject.
- Parameters
-
property_animation | The property animation for which the update is requested. |
time_normalized | The current normalized time. See AnimationUpdateImplementation |
- Note
- This function is not supposed to be called "manually", but will be called automatically when the animation is being run.
void property_animation_update_grect |
( |
struct PropertyAnimation * |
property_animation, |
|
|
const uint32_t |
time_normalized |
|
) |
| |
Default update callback for a property animations to update a property of type GRect. Assign this function to the .base.update
callback field of your PropertyAnimationImplementation, in combination with a .getter
and .setter
accessors of types GRectGetter and GRectSetter. The implementation of this function will calculate the next rectangle of the animation and call the setter to set the new rectangle upon the subject.
- Parameters
-
property_animation | The property animation for which the update is requested. |
time_normalized | The current normalized time. See AnimationUpdateImplementation |
- Note
- This function is not supposed to be called "manually", but will be called automatically when the animation is being run.
void property_animation_update_int16 |
( |
struct PropertyAnimation * |
property_animation, |
|
|
const uint32_t |
time_normalized |
|
) |
| |
Default update callback for a property animations to update a property of type int16_t. Assign this function to the .base.update
callback field of your PropertyAnimationImplementation, in combination with a .getter
and .setter
accessors of types Int16Getter and Int16Setter. The implementation of this function will calculate the next value of the animation and call the setter to set the new value upon the subject.
- Parameters
-
property_animation | The property animation for which the update is requested. |
time_normalized | The current normalized time. See AnimationUpdateImplementation |
- Note
- This function is not supposed to be called "manually", but will be called automatically when the animation is being run.
struct PropertyAnimation.values |
The values of the property that the animation should animated from and to.
Data Fields |
values |
from |
The value of the property that the animation should animate to. When the animation starts, this value will be the initial value that is set. |
values |
to |
The value of the property that the animation should animate to. When the animation completes, this value will be the final value that is set. |
union PropertyAnimation.values.from |
The value of the property that the animation should animate to. When the animation starts, this value will be the initial value that is set.
Data Fields |
GPoint |
gpoint |
Valid when the property being animated is of type GPoint. |
GRect |
grect |
Valid when the property being animated is of type GRect. |
int16_t |
int16 |
Valid when the property being animated is of type int16_t. |
union PropertyAnimation.values.to |
The value of the property that the animation should animate to. When the animation completes, this value will be the final value that is set.
Data Fields |
GPoint |
gpoint |
Valid when the property being animated is of type GPoint. |
GRect |
grect |
Valid when the property being animated is of type GRect. |
int16_t |
int16 |
Valid when the property being animated is of type int16_t. |
struct PropertyAnimationAccessors |
union PropertyAnimationAccessors.getter |
Function pointer to the implementation of the function that gets the current property value. This function will be called during property_animation_create(), to get the current property value, in case the from_value
or to_value
argument is NULL
.
- See Also
- PropertyAnimationAccessors
union PropertyAnimationAccessors.setter |
Function pointer to the implementation of the function that sets the updated property value. This function will be called repeatedly for each animation frame.
- See Also
- PropertyAnimationAccessors
struct PropertyAnimationImplementation |
Data structure containing a collection of function pointers that form the implementation of the property animation. See the code example at the top (PropertyAnimation).
Work-around for function pointer return type GPoint avoid tripping the pre-processor to use the equally named GPoint define.
typedef void(* GPointSetter)(void *subject, GPoint gpoint) |
Work-around for function pointer return type GRect avoid tripping the pre-processor to use the equally named GRect define.
typedef void(* GRectSetter)(void *subject, GRect grect) |
typedef int16_t(* Int16Getter)(void *subject) |
typedef void(* Int16Setter)(void *subject, int16_t int16) |