An object that manages the timing and progress of animations in the user interface.


@interface NSAnimation : NSObject


NSAnimation also lets you link together multiple animations so that when one animation ends another one starts. It does not provide any drawing support for animation and does not directly deal with views, targets, or actions.

NSAnimation objects have several characteristics, including duration, frame rate, and animation curve, which describes the relative speed of the animation over its course. You can set progress marks in an animation, each of which specifies a percentage of the animation completed; when an animation reaches a progress mark, it notifies its delegate and posts a notification to any observers. Animations execute in one of three blocking modes: blocking, non-blocking on the main thread, and non-blocking on a separate thread. The non-blocking modes permit the handling of user events while the animation is running.

Subclassing Notes

The usual usage pattern for NSAnimation is to make a subclass that overrides (at least) the currentProgress property to invoke the superclass implementation and then perform whatever animation action is needed. The method implementation might use the currentValue property and then use that value to update some drawing; as a consequence of getting the current value, the method animation:valueForProgress: is sent to the delegate (if there is a delegate that implements the method). For more information on subclassing NSAnimation, see Animation Programming Guide for Cocoa.


Initializing an NSAnimation Object

- initWithDuration:animationCurve:

Returns an NSAnimation object initialized with the specified duration and animation-curve values.

Configuring an Animation


The blocking mode of the animation.


An array of strings representing the run loop modes in which the animation can run.


The timing curve for the animation.


The duration of the animation, in seconds.


The number of frame updates per second to generate for the animation.

Managing the Delegate


The animation delegate.

Controlling and Monitoring an Animation

- startAnimation

Starts the animation represented by the receiver.

- stopAnimation

Stops the animation represented by the receiver.


A Boolean value indicating whether the animation is in progress.


The current progress of the animation.


The current value of the animation effect, based on the current progress

Managing Progress Marks

- addProgressMark:

Adds the progress mark to the receiver.

- removeProgressMark:

Removes progress mark from the receiver.


An array of floating-point numbers representing current progress marks.

Linking Animations Together

- startWhenAnimation:reachesProgress:

Starts running the animation represented by the receiver when another animation reaches a specific progress mark.

- stopWhenAnimation:reachesProgress:

Stops running the animation represented by the receiver when another animation reaches a specific progress mark.

- clearStartAnimation

Clears linkage to another animation that causes the receiver to start.

- clearStopAnimation

Clears linkage to another animation that causes the receiver to stop.



These constants describe the curve of an animation—that is, the relative speed of an animation from start to finish.


These constants indicate the blocking mode of an NSAnimation object when it is running.


The animation progress, as a floating-point number between 0.0 and 1.0.

NSAnimationProgressMark Notification Key

This constant is returned in the userInfo dictionary of the NSAnimationProgressMarkNotification notification.



Posted when the current progress of a running animation reaches one of its progress marks.



Inherits From

Conforms To

See Also

Custom Animations


A set of optional methods implemented by delegates of NSAnimation objects.