CAKeyframeAnimation Class Reference

Inherits from
CAPropertyAnimation : CAAnimation : NSObject
Conforms to
NSCoding (CAAnimation)
NSCopying (CAAnimation)
CAAction (CAAnimation)
CAMediaTiming (CAAnimation)
NSObject (NSObject)
Framework
/System/Library/Frameworks/QuartzCore.framework
Availability
Available in iOS 2.0 and later.
Declared in
CAAnimation.h
Companion guides
Core Animation Programming Guide
Core Animation Cookbook
Related sample code

Overview

The CAKeyframeAnimation class provides keyframe animation capabilities for a layer object. You create an CAKeyframeAnimation object using the inherited animationWithKeyPath: method, specifying the key path of the property that you want to animate on the layer. You can then specify the keyframe values to use to control the timing and animation behavior.

For most types of animations, you specify the keyframe values using the values and keyTimes properties. During the animation, Core Animation generates intermediate values by interpolating between the values you provide. When animating a value that is a coordinate point, such as the layer’s position, you can specify a path for that point to follow instead of individual values. The pacing of the animation is controlled by the timing information you provide.

Tasks

Providing Keyframe Values

Keyframe Timing

Rotation Mode Attribute

Cubic Mode Attributes

Properties

biasValues

An array of NSNumber objects that define the position of the curve relative to a control point.

@property(copy) NSArray *biasValues
Discussion

This property is used only for the cubic calculation modes. Positive values move the curve before the control point while negative values move it after the control point. The first value defines the behavior of the tangent to the first control point, the second value controls the second point’s tangents, and so on. If you do not specify a value for a given control point, the value 0 is used.

Availability
  • Available in iOS 4.0 and later.
Declared In
CAAnimation.h

calculationMode

Specifies how intermediate keyframe values are calculated by the receiver.

@property(copy) NSString *calculationMode
Discussion

The possible values are described in “Value calculation modes”. The default value of this property is kCAAnimationLinear.

Availability
  • Available in iOS 2.0 and later.
Declared In
CAAnimation.h

continuityValues

An array of NSNumber objects that define the sharpness of the timing curve’s corners.

@property(copy) NSArray *continuityValues
Discussion

This property is used only for the cubic calculation modes. Positive values result in sharper corners while negative values create inverted corners. The first value defines the behavior of the tangent to the first control point, the second value controls the second point’s tangents, and so on. If you do not specify a value for a given control point, the value 0 is used.

Availability
  • Available in iOS 4.0 and later.
Declared In
CAAnimation.h

keyTimes

An optional array of NSNumber objects that define the time at which to apply a given keyframe segment.

@property(copy) NSArray *keyTimes
Discussion

Each value in the array is a floating point number between 0.0 and 1.0 that defines the time point (specified as a fraction of the animation’s total duration) at which to apply the corresponding keyframe value. Each successive value in the array must be greater than, or equal to, the previous value. For the best results, the number of elements in the array should match the number of elements in the values property or the number of control points in the path property. If they do not, the timing of your animation might not be what you expect.

The appropriate values to include in the array are dependent on the calculationMode property.

  • If the calculationMode is set to kCAAnimationLinear or kCAAnimationCubic, the first value in the array must be 0.0 and the last value must be 1.0. All intermediate values represent time points between the start and end times.

  • If the calculationMode is set to kCAAnimationDiscrete, the first value in the array must be 0.0.

  • If the calculationMode is set to kCAAnimationPaced or kCAAnimationCubicPaced, the values in this property are ignored.

If the values in this array are invalid or inappropriate for the current calculation mode, they are ignored.

Availability
  • Available in iOS 2.0 and later.
Declared In
CAAnimation.h

path

The path for a point-based property to follow.

@property CGPathRef path;
Discussion

For layer properties that contain a CGPoint data type, the path object you assign to this property defines the values for that property over the length of the animation. If you specify a value for this property, any data in the values property is ignored.

Any timing values you specify for the animation are applied to the points used to create the path. Paths can contain points defining move-to, line-to, or curve-to segments. The end point of a line-to or curve-to segment defines the keyframe value. All other points between that end value and the previous value are then interpolated. Move-to segments do not define separate keyframe values.

How the animation proceeds along the path is dependent on the value in the calculationMode property. To achieve a smooth, constant velocity animation along the path, set the calculationMode property to kCAAnimationPaced or kCAAnimationCubicPaced. To create an animation where the location value jumps from keyframe point to keyframe point (without interpolation in between), use the kCAAnimationDiscrete value. To animate along the path by interpolating values between points, use the kCAAnimationLinear value.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
CAAnimation.h

rotationMode

Determines whether objects animating along the path rotate to match the path tangent.

@property(copy) NSString *rotationMode
Discussion

The possible values for this property are described in “Rotation Mode Values”. The default value of this property is nil, which indicates that objects should not rotate to follow the path.

The effect of setting this property to a non-nil value when no path object is supplied is undefined.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
CAAnimation.h

tensionValues

An array of NSNumber objects that define the tightness of the curve.

@property(copy) NSArray *tensionValues
Discussion

This property is used only for the cubic calculation modes. Positive values indicate a tighter curve while negative values indicate a rounder curve. The first value defines the behavior of the tangent to the first control point, the second value controls the second point’s tangents, and so on. If you do not specify a value for a given control point, the value 0 is used.

Availability
  • Available in iOS 4.0 and later.
Declared In
CAAnimation.h

timingFunctions

An optional array of CAMediaTimingFunction objects that define the pacing for each keyframe segment.

@property(copy) NSArray *timingFunctions
Discussion

You can use this array to apply ease-in, ease-out, or custom timing curves to the points that lie between two keyframe values. If the number of keyframes in the values property is n, then this property should contain n-1 objects.

If you provide timing information in the keyTimes property, the timing functions you specify using this property further modify the timing between those values. If you do not assign a value to the keyTimes property, the timing functions modify the default timing provided by the animation object.

If you also specify a timing function in the animation object’s timingFunction property, that function is applied first followed by the timing function for the specific keyframe segment.

For information on how to create a timing function, see CAMediaTimingFunction Class Reference.

Availability
  • Available in iOS 2.0 and later.
Declared In
CAAnimation.h

values

An array of objects that specify the keyframe values to use for the animation.

@property(copy) NSArray *values
Discussion

The keyframe values represent the values through which the animation must proceed. The time at which a given keyframe value is applied to the layer depends on the animation timing, which is controlled by the calculationMode, keyTimes, and timingFunctions properties. Values between keyframes are created using interpolation, unless the calculation mode is set to kCAAnimationDiscrete.

Depending on the type of the property, you may need to wrap the values in this array with an NSNumber of NSValue object. For some Core Graphics data types, you may also need to cast them to id before adding them to the array.

The values in this property are used only if the value in the path property is nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
CAAnimation.h

Constants

Rotation Mode Values

These constants are used by the rotationMode property.

NSString * const kCAAnimationRotateAuto
NSString * const kCAAnimationRotateAutoReverse
Constants
kCAAnimationRotateAuto

The objects travel on a tangent to the path.

Available in iOS 2.0 and later.

Declared in CAAnimation.h.

kCAAnimationRotateAutoReverse

The objects travel at a 180 degree tangent to the path.

Available in iOS 2.0 and later.

Declared in CAAnimation.h.

Value calculation modes

These constants are used by the calculationMode property.

NSString * const kCAAnimationLinear;
NSString * const kCAAnimationDiscrete;
NSString * const kCAAnimationPaced;
NSString * const kCAAnimationCubic;
NSString * const kCAAnimationCubicPaced;
Constants
kCAAnimationLinear

Simple linear calculation between keyframe values.

Available in iOS 2.0 and later.

Declared in CAAnimation.h.

kCAAnimationDiscrete

Each keyframe value is used in turn, no interpolated values are calculated.

Available in iOS 2.0 and later.

Declared in CAAnimation.h.

kCAAnimationPaced

Keyframe values are interpolated to produce an even pace throughout the animation.

Available in iOS 2.0 and later.

Declared in CAAnimation.h.

kCAAnimationCubic

Intermediate frames are computed using a Catmull-Rom spline that passes through the keyframes. You can adjust the shape of the spline by specifying an optional set of tension, continuity, and bias values, which modify the spline using the standard Kochanek-Bartels form.

Available in iOS 4.0 and later.

Declared in CAAnimation.h.

kCAAnimationCubicPaced

Intermediate frames are computed using the cubic scheme but the keyTimes and timingFunctions properties of the animation are ignored. Instead, timing parameters are calculated implicitly to give the animation a constant velocity.

Available in iOS 4.0 and later.

Declared in CAAnimation.h.



© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-01-28)

Did this document help you? Yes It's good, but... Not helpful...