PropertyAnimation

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

Collaboration diagram for PropertyAnimation:

Classes
struct	PropertyAnimationAccessors
struct	PropertyAnimationImplementation

Macros
#define	property_animation_clone(property_animation)   (PropertyAnimation *)animation_clone((Animation *)property_animation)
#define	property_animation_get_from_grect(property_animation, value_ptr)   property_animation_from(property_animation, value_ptr, sizeof(GRect), false)
#define	property_animation_set_from_grect(property_animation, value_ptr)   property_animation_from(property_animation, value_ptr, sizeof(GRect), true)
#define	property_animation_get_from_gpoint(property_animation, value_ptr)   property_animation_from(property_animation, value_ptr, sizeof(GPoint), false)
#define	property_animation_set_from_gpoint(property_animation, value_ptr)   property_animation_from(property_animation, value_ptr, sizeof(GPoint), true)
#define	property_animation_get_from_int16(property_animation, value_ptr)   property_animation_from(property_animation, value_ptr, sizeof(int16_t), false)
#define	property_animation_set_from_int16(property_animation, value_ptr)   property_animation_from(property_animation, value_ptr, sizeof(int16_t), true)
#define	property_animation_get_to_grect(property_animation, value_ptr)   property_animation_to(property_animation, value_ptr, sizeof(GRect), false)
#define	property_animation_set_to_grect(property_animation, value_ptr)   property_animation_to(property_animation, value_ptr, sizeof(GRect), true)
#define	property_animation_get_to_gpoint(property_animation, value_ptr)   property_animation_to(property_animation, value_ptr, sizeof(GPoint), false)
#define	property_animation_set_to_gpoint(property_animation, value_ptr)   property_animation_to(property_animation, value_ptr, sizeof(GPoint), true)
#define	property_animation_get_to_int16(property_animation, value_ptr)   property_animation_to(property_animation, value_ptr, sizeof(int16_t), false)
#define	property_animation_set_to_int16(property_animation, value_ptr)   property_animation_to(property_animation, value_ptr, sizeof(int16_t), true)
#define	property_animation_get_subject(property_animation, value_ptr)   property_animation_subject(property_animation, value_ptr, false)
#define	property_animation_set_subject(property_animation, value_ptr)   property_animation_subject(property_animation, value_ptr, true)

Typedefs
typedef struct PropertyAnimationAccessors	PropertyAnimationAccessors
typedef struct PropertyAnimationImplementation	PropertyAnimationImplementation
typedef struct PropertyAnimation	PropertyAnimation
typedef GPoint	GPointReturn
typedef GRect	GRectReturn
typedef void(*	Int16Setter) (void *subject, int16_t int16)
typedef int16_t(*	Int16Getter) (void *subject)
typedef void(*	UInt32Setter) (void *subject, uint32_t uint32)
typedef uint32_t(*	UInt32Getter) (void *subject)
typedef void(*	GPointSetter) (void *subject, GPoint gpoint)
typedef GPointReturn(*	GPointGetter) (void *subject)
typedef void(*	GRectSetter) (void *subject, GRect grect)
typedef GRectReturn(*	GRectGetter) (void *subject)
typedef void(*	GColor8Setter) (void *subject, GColor8 gcolor)
typedef GColor8(*	GColor8Getter) (void *subject)

Functions
PropertyAnimation *	property_animation_create_layer_frame (struct Layer *layer, GRect *from_frame, GRect *to_frame)
PropertyAnimation *	property_animation_create_bounds_origin (struct Layer *layer, GPoint *from, GPoint *to)
PropertyAnimation *	property_animation_create (const PropertyAnimationImplementation *implementation, void *subject, void *from_value, void *to_value)
void	property_animation_destroy (PropertyAnimation *property_animation)
void	property_animation_update_int16 (PropertyAnimation *property_animation, const uint32_t distance_normalized)
void	property_animation_update_uint32 (PropertyAnimation *property_animation, const uint32_t distance_normalized)
void	property_animation_update_gpoint (PropertyAnimation *property_animation, const uint32_t distance_normalized)
void	property_animation_update_grect (PropertyAnimation *property_animation, const uint32_t distance_normalized)
void	property_animation_update_gcolor8 (PropertyAnimation *property_animation, const uint32_t distance_normalized)
Animation *	property_animation_get_animation (PropertyAnimation *property_animation)
bool	property_animation_subject (PropertyAnimation *property_animation, void **subject, bool set)
bool	property_animation_from (PropertyAnimation *property_animation, void *from, size_t size, bool set)
bool	property_animation_to (PropertyAnimation *property_animation, void *to, size_t size, bool set)

Detailed Description

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

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

static const PropertyAnimationImplementation my_implementation = {
  .base = {
    // using the "stock" update callback:
    .update = (AnimationUpdateImplementation) property_animation_update_gpoint,
  },
  .accessors = {
    // my accessors that get/set a GPoint from/onto my subject:
    .setter = { .gpoint = my_layer_set_corner_point, },
    .getter = { .gpoint = (const GPointGetter) my_layer_get_corner_point, },
  },
};
static PropertyAnimation* s_my_animation_ptr = NULL;
static GPoint s_to_point = GPointZero;
...
// Use NULL as 'from' value, this will make the animation framework call the getter
// to get the current value of the property and use that as the 'from' value:
s_my_animation_ptr = property_animation_create(&my_implementation, my_layer, NULL, &s_to_point);
animation_schedule(property_animation_get_animation(s_my_animation_ptr));

Macro Definition Documentation

property_animation_clone

#define property_animation_clone

(

property_animation

)

(PropertyAnimation *)animation_clone((Animation *)property_animation)

Convenience function to clone a property animation instance

Parameters

property_animation

The property animation

Returns

A clone of the original Animation

property_animation_get_from_gpoint

#define property_animation_get_from_gpoint	(		property_animation,
			value_ptr
	)		property_animation_from(property_animation, value_ptr, sizeof(GPoint), false)

Convenience function to retrieve the 'from' GPoint value from property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	The value will be retrieved into this pointer

Returns

true on success, false on failure

property_animation_get_from_grect

#define property_animation_get_from_grect	(		property_animation,
			value_ptr
	)		property_animation_from(property_animation, value_ptr, sizeof(GRect), false)

Convenience function to retrieve the 'from' GRect value from property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	The value will be retrieved into this pointer

Returns

true on success, false on failure

property_animation_get_from_int16

#define property_animation_get_from_int16	(		property_animation,
			value_ptr
	)		property_animation_from(property_animation, value_ptr, sizeof(int16_t), false)

Convenience function to retrieve the 'from' int16_t value from property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	The value will be retrieved into this pointer

Returns

true on success, false on failure

property_animation_get_subject

#define property_animation_get_subject	(		property_animation,
			value_ptr
	)		property_animation_subject(property_animation, value_ptr, false)

Retrieve the subject of a property animation

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	Pointer used to store the subject of this property animation

Returns

The subject of this PropertyAnimation

property_animation_get_to_gpoint

#define property_animation_get_to_gpoint	(		property_animation,
			value_ptr
	)		property_animation_to(property_animation, value_ptr, sizeof(GPoint), false)

Convenience function to retrieve the 'to' GPoint value from property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	The value will be retrieved into this pointer

Returns

true on success, false on failure

property_animation_get_to_grect

#define property_animation_get_to_grect	(		property_animation,
			value_ptr
	)		property_animation_to(property_animation, value_ptr, sizeof(GRect), false)

Convenience function to retrieve the 'to' GRect value from property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	The value will be retrieved into this pointer

Returns

true on success, false on failure

property_animation_get_to_int16

#define property_animation_get_to_int16	(		property_animation,
			value_ptr
	)		property_animation_to(property_animation, value_ptr, sizeof(int16_t), false)

Convenience function to retrieve the 'to' int16_t value from property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	The value will be retrieved into this pointer

Returns

true on success, false on failure

property_animation_set_from_gpoint

#define property_animation_set_from_gpoint	(		property_animation,
			value_ptr
	)		property_animation_from(property_animation, value_ptr, sizeof(GPoint), true)

Convenience function to set the 'from' GPoint value of property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	Pointer to the new value

Returns

true on success, false on failure

property_animation_set_from_grect

#define property_animation_set_from_grect	(		property_animation,
			value_ptr
	)		property_animation_from(property_animation, value_ptr, sizeof(GRect), true)

Convenience function to set the 'from' GRect value of property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	Pointer to the new value

Returns

true on success, false on failure

property_animation_set_from_int16

#define property_animation_set_from_int16	(		property_animation,
			value_ptr
	)		property_animation_from(property_animation, value_ptr, sizeof(int16_t), true)

Convenience function to set the 'from' int16_t value of property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	Pointer to the new value

Returns

true on success, false on failure

property_animation_set_subject

#define property_animation_set_subject	(		property_animation,
			value_ptr
	)		property_animation_subject(property_animation, value_ptr, true)

Set the subject of a property animation

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	Pointer to the new subject value

property_animation_set_to_gpoint

#define property_animation_set_to_gpoint	(		property_animation,
			value_ptr
	)		property_animation_to(property_animation, value_ptr, sizeof(GPoint), true)

Convenience function to set the 'to' GPoint value of property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	Pointer to the new value

Returns

true on success, false on failure

property_animation_set_to_grect

#define property_animation_set_to_grect	(		property_animation,
			value_ptr
	)		property_animation_to(property_animation, value_ptr, sizeof(GRect), true)

Convenience function to set the 'to' GRect value of property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	Pointer to the new value

Returns

true on success, false on failure

property_animation_set_to_int16

#define property_animation_set_to_int16	(		property_animation,
			value_ptr
	)		property_animation_to(property_animation, value_ptr, sizeof(int16_t), true)

Convenience function to set the 'to' int16_t value of property animation handle

Parameters

property_animation	The PropertyAnimation to be accessed
value_ptr	Pointer to the new value

Returns

true on success, false on failure

Typedef Documentation

GColor8Getter

typedef GColor8(* GColor8Getter) (void *subject)

Function signature of a getter function to get the current property of type GColor8 of the subject.

See also

property_animation_create()

PropertyAnimationAccessors

GColor8Setter

typedef void(* GColor8Setter) (void *subject, GColor8 gcolor)

Function signature of a setter function to set a property of type GColor8 onto the subject.

See also

property_animation_update_gcolor8()

PropertyAnimationAccessors

GPointGetter

typedef GPointReturn(* GPointGetter) (void *subject)

Function signature of a getter function to get the current property of type GPoint of the subject.

See also

property_animation_create()

PropertyAnimationAccessors

GPointReturn

typedef GPoint GPointReturn

Work-around for function pointer return type GPoint to avoid tripping the pre-processor to use the equally named GPoint define

GPointSetter

typedef void(* GPointSetter) (void *subject, GPoint gpoint)

Function signature of a setter function to set a property of type GPoint onto the subject.

See also

property_animation_update_gpoint()

PropertyAnimationAccessors

GRectGetter

typedef GRectReturn(* GRectGetter) (void *subject)

Function signature of a getter function to get the current property of type GRect of the subject.

See also

property_animation_create()

PropertyAnimationAccessors

GRectReturn

typedef GRect GRectReturn

Work-around for function pointer return type GRect to avoid tripping the pre-processor to use the equally named GRect define

GRectSetter

typedef void(* GRectSetter) (void *subject, GRect grect)

Function signature of a setter function to set a property of type GRect onto the subject.

See also

property_animation_update_grect()

PropertyAnimationAccessors

Int16Getter

typedef int16_t(* Int16Getter) (void *subject)

Function signature of a getter function to get the current property of type int16_t of the subject.

See also

property_animation_create()

PropertyAnimationAccessors

Int16Setter

typedef void(* Int16Setter) (void *subject, int16_t int16)

Function signature of a setter function to set a property of type int16_t onto the subject.

See also

property_animation_update_int16()

PropertyAnimationAccessors

PropertyAnimationAccessors

typedef struct PropertyAnimationAccessors PropertyAnimationAccessors

Data structure containing the setter and getter function pointers that the property animation should use. The specified setter function will be used by the animation's update callback.
Based on the type of the property (int16_t, GPoint or GRect), the accompanying update callback should be used, see property_animation_update_int16(), property_animation_update_gpoint() and property_animation_update_grect().
The getter function is used when the animation is initialized, to assign the current value of the subject's property as "from" or "to" value, see property_animation_create().

PropertyAnimationImplementation

typedef struct PropertyAnimationImplementation 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).

UInt32Getter

typedef uint32_t(* UInt32Getter) (void *subject)

Function signature of a getter function to get the current property of type uint32_t of the subject.

See also

property_animation_create()

PropertyAnimationAccessors

UInt32Setter

typedef void(* UInt32Setter) (void *subject, uint32_t uint32)

Function signature of a setter function to set a property of type uint32_t onto the subject.

See also

property_animation_update_int16()

PropertyAnimationAccessors

Function Documentation

property_animation_create()

PropertyAnimation* property_animation_create	(	const 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 handle to the property animation. NULL if animation could not be created

property_animation_create_bounds_origin()

PropertyAnimation* property_animation_create_bounds_origin	(	struct Layer *	layer,
		GPoint *	from,
		GPoint *	to
	)

Convenience function to create and initialize a property animation that animates the bound's origin of a Layer. It sets up the PropertyAnimation to use layer_set_bounds() and layer_get_bounds() as accessors and uses the layer parameter as the subject for the animation. The same defaults are used as with animation_create().

Parameters

layer	the layer that will be animated
from_origin	the origin that the bounds should animate from
to_origin	the origin that the layer should animate to

Returns

A handle to the property animation. NULL if animation could not be created

property_animation_create_layer_frame()

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

layer	the layer that will be animated
from_frame	the frame that the layer should animate from
to_frame	the frame that the layer should animate to

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 handle to the property animation. NULL if animation could not be created

property_animation_destroy()

void property_animation_destroy

(

PropertyAnimation *

property_animation

)

Destroy a property animation allocated by property_animation_create() or relatives.

Parameters

property_animation

the return value from property_animation_create

property_animation_from()

bool property_animation_from	(	PropertyAnimation *	property_animation,
		void *	from,
		size_t	size,
		bool	set
	)

Helper function used by the property_animation_get|set_from_.* macros

Parameters

property_animation	Handle to the property animation
from	Pointer to the value
size	Size of the from value
set	true to set new value, false to retrieve existing one

Returns

true if successful, false on failure (usually a bad animation_h)

property_animation_get_animation()

Animation* property_animation_get_animation

(

PropertyAnimation *

property_animation

)

Convenience function to retrieve an animation instance from a property animation instance

Parameters

property_animation

The property animation

Returns

The Animation within this PropertyAnimation

property_animation_subject()

bool property_animation_subject	(	PropertyAnimation *	property_animation,
		void **	subject,
		bool	set
	)

Helper function used by the property_animation_get|set_subject macros

Parameters

property_animation	Handle to the property animation
subject	The subject to get or set.
set	true to set new subject, false to retrieve existing value

Returns

true if successful, false on failure (usually a bad animation_h)

property_animation_to()

bool property_animation_to	(	PropertyAnimation *	property_animation,
		void *	to,
		size_t	size,
		bool	set
	)

Helper function used by the property_animation_get|set_to_.* macros

Parameters

property_animation	handle to the property animation
to	Pointer to the value
size	Size of the to value
set	true to set new value, false to retrieve existing one

Returns

true if successful, false on failure (usually a bad animation_h)

property_animation_update_gcolor8()

void property_animation_update_gcolor8	(	PropertyAnimation *	property_animation,
		const uint32_t	distance_normalized
	)

Default update callback for a property animations to update a property of type GColor8. Assign this function to the .base.update callback field of your PropertyAnimationImplementation, in combination with a .getter and .setter accessors of types GColor8Getter and GColor8Setter. The implementation of this function will calculate the next rectangle 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.
distance_normalized	The current normalized distance. See AnimationUpdateImplementation

Note

This function is not supposed to be called "manually", but will be called automatically when the animation is being run.

property_animation_update_gpoint()

void property_animation_update_gpoint	(	PropertyAnimation *	property_animation,
		const uint32_t	distance_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.
distance_normalized	The current normalized distance. See AnimationUpdateImplementation

Note

This function is not supposed to be called "manually", but will be called automatically when the animation is being run.

property_animation_update_grect()

void property_animation_update_grect	(	PropertyAnimation *	property_animation,
		const uint32_t	distance_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.
distance_normalized	The current normalized distance. See AnimationUpdateImplementation

Note

This function is not supposed to be called "manually", but will be called automatically when the animation is being run.

property_animation_update_int16()

void property_animation_update_int16	(	PropertyAnimation *	property_animation,
		const uint32_t	distance_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.
distance_normalized	The current normalized distance. See AnimationUpdateImplementation

Note

This function is not supposed to be called "manually", but will be called automatically when the animation is being run.

property_animation_update_uint32()

void property_animation_update_uint32	(	PropertyAnimation *	property_animation,
		const uint32_t	distance_normalized
	)

Default update callback for a property animations to update a property of type uint32_t. Assign this function to the .base.update callback field of your PropertyAnimationImplementation, in combination with a .getter and .setter accessors of types UInt32Getter and UInt32Setter. 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.
distance_normalized	The current normalized distance. See AnimationUpdateImplementation

Note

This function is not supposed to be called "manually", but will be called automatically when the animation is being run.