iOS Developer Library

Developer

QuartzCore Framework Reference CAKeyframeAnimation Class Reference

Options
Deployment Target:

On This Page
Language:

CAKeyframeAnimation

Inherits From


Conforms To


Import Statement


Swift

import QuartzCore

Objective-C

@import QuartzCore;

Availability


Available in iOS 2.0 and later

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.

  • values values Property

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

    Declaration

    Swift

    var values: [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 2.0 and later

  • path path Property

    The path for a point-based property to follow.

    Declaration

    Swift

    var path: CGPath!

    Objective-C

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 2.0 and later

    See Also

    rotationMode

  • keyTimes keyTimes Property

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

    Declaration

    Swift

    var keyTimes: [AnyObject]!

    Objective-C

    @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. Usually, 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 and the last value must be 1.0. The array should have one more entry than appears in the values array. For example, if there are two values, there should be three key times.

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    var timingFunctions: [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 2.0 and later

  • Specifies how intermediate keyframe values are calculated by the receiver.

    Declaration

    Swift

    var calculationMode: String!

    Objective-C

    @property(copy) NSString *calculationMode

    Discussion

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    var rotationMode: String!

    Objective-C

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 2.0 and later

    See Also

    path

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

    Declaration

    Swift

    var tensionValues: [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    var continuityValues: [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    var biasValues: [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in iOS 4.0 and later

  • These constants are used by the rotationMode property.

    Declaration

    Swift

    let kCAAnimationRotateAuto: String let kCAAnimationRotateAutoReverse: String

    Objective-C

    NSString * const kCAAnimationRotateAuto NSString * const kCAAnimationRotateAutoReverse

    Constants

    • kCAAnimationRotateAuto

      kCAAnimationRotateAuto

      The objects travel on a tangent to the path.

      Available in iOS 2.0 and later

    • kCAAnimationRotateAutoReverse

      kCAAnimationRotateAutoReverse

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

      Available in iOS 2.0 and later

  • These constants are used by the calculationMode property.

    Declaration

    Swift

    let kCAAnimationLinear: String let kCAAnimationDiscrete: String let kCAAnimationPaced: String let kCAAnimationCubic: String let kCAAnimationCubicPaced: String

    Objective-C

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

    Constants

    • kCAAnimationLinear

      kCAAnimationLinear

      Simple linear calculation between keyframe values.

      Available in iOS 2.0 and later

    • kCAAnimationDiscrete

      kCAAnimationDiscrete

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

      Available in iOS 2.0 and later

    • kCAAnimationPaced

      kCAAnimationPaced

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

      Available in iOS 2.0 and later

    • kCAAnimationCubic

      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

    • kCAAnimationCubicPaced

      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