---

NSAnimation Class Reference

Overview

Objects of the NSAnimation class manage the timing and progress of animations in the user interface. The class 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 setCurrentProgress: method to invoke the superclass implementation and then perform whatever animation action is needed. The method implementation might invoke currentValue and then use that value to update some drawing; as a consequence of invoking currentValue, 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 Cocoa Drawing Guide.

Tasks

Initializing an NSAnimation Object

• – initWithDuration:animationCurve:

Configuring an Animation

• – setAnimationBlockingMode:
• – animationBlockingMode
• – runLoopModesForAnimating
• – setAnimationCurve:
• – animationCurve
• – setDuration:
• – duration
• – setFrameRate:
• – frameRate

Managing the Delegate

• – setDelegate:
• – delegate

Controlling and Monitoring an Animation

• – startAnimation
• – stopAnimation
• – isAnimating
• – setCurrentProgress:
• – currentProgress
• – currentValue
• – animationDidEnd:  delegate method
• – animationDidStop:  delegate method
• – animationShouldStart:  delegate method
• – animation:valueForProgress:  delegate method

Managing Progress Marks

• – addProgressMark:
• – removeProgressMark:
• – setProgressMarks:
• – progressMarks
• – animation:didReachProgressMark:  delegate method

Linking Animations Together

• – startWhenAnimation:reachesProgress:
• – stopWhenAnimation:reachesProgress:
• – clearStartAnimation
• – clearStopAnimation

Instance Methods

addProgressMark:

Adds the progress mark to the receiver.

- (void)addProgressMark:(NSAnimationProgress)progressMark

Parameters

progressMark

A float value (typed as NSAnimationProgress) between 0.0 and 1.0. Values outside that range are pinned to 0.0 or 1.0, whichever is nearest.

Discussion

A progress mark represents a percentage of the animation completed. When the animation reaches a progress mark, an animation:didReachProgressMark: message is sent to the delegate and an NSAnimationProgressMarkNotification is broadcast to all observers. You might receive multiple notifications of progress advances over multiple marks.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – currentProgress
• – removeProgressMark:

Declared In

NSAnimation.h

animationBlockingMode

Returns the blocking mode the receiver is next scheduled to run under.

- (NSAnimationBlockingMode)animationBlockingMode

Return Value

A constant representing the receiver's blocking mode. See “NSAnimationBlockingMode” for valid values.

Discussion

The animation can run in blocking mode or non-blocking mode; non-blocking mode can be either on the main thread or on a separate thread. The default mode is NSAnimationBlocking.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setAnimationBlockingMode:

Declared In

NSAnimation.h

animationCurve

Returns the animation curve the receiver is running under.

- (NSAnimationCurve)animationCurve

Return Value

An NSAnimationCurve constant indicating the animation curve.

Discussion

The animation curve describes the relative frame rate over the course of the animation. See “NSAnimationCurve” for valid NSAnimationCurve constants.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setAnimationCurve:

Declared In

NSAnimation.h

clearStartAnimation

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

- (void)clearStartAnimation

Discussion

The linkage to the other animation is made with startWhenAnimation:reachesProgress:.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – startAnimation

Declared In

NSAnimation.h

clearStopAnimation

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

- (void)clearStopAnimation

Discussion

The linkage to the other animation is made with stopWhenAnimation:reachesProgress:.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – stopAnimation

Declared In

NSAnimation.h

currentProgress

Returns the current progress of the receiver.

- (NSAnimationProgress)currentProgress

Return Value

A float value typed as NSAnimationProgress that indicates the current progress of the animation.

Discussion

The current progress is a value between 0.0 and 1.0 that represents the percentage of the animation currently completed.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setCurrentProgress:

Declared In

NSAnimation.h

currentValue

Returns the current value of the effect based on the current progress.

- (float)currentValue

Return Value

A float value that indicates the current value of the animation effect.

Discussion

NSAnimation gets the current value from the delegate in animation:valueForProgress: or, if that method is not implemented, computes it from the current progress by factoring in the animation curve. NSAnimation itself does not invoke this method currently. Instances of NSAnimation subclasses or other objects can invoke this method on a periodic basis to get the current value. Although this method has no corresponding setter method, those NSAnimation subclasses may override this method to return a custom curve value instead of implementing animation:valueForProgress:, thereby saving on the overhead of using a delegate. The current value can be less than 0.0 or greater than 1.0. For example, if you make the value greater than 1.0 you can achieve a “rubber effect” where the size of a view is temporarily larger before its final size.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – currentProgress
• – setAnimationCurve:

Declared In

NSAnimation.h

delegate

Returns the delegate of the receiver.

- (id)delegate

Return Value

The receiver's delegate.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setDelegate:

Declared In

NSAnimation.h

duration

Returns the duration of the animation, in seconds.

- (NSTimeInterval)duration

Return Value

An NSTimeInterval value indicating the duration.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setDuration:

Declared In

NSAnimation.h

frameRate

Returns the frame rate of the animation.

- (float)frameRate

Discussion

The frame rate is the number of updates per second. It is not guaranteed to be accurate because of differences between systems on the time needed to process a frame.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSAnimation.h

initWithDuration:animationCurve:

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

- (id)initWithDuration:(NSTimeInterval)duration animationCurve:(NSAnimationCurve)animationCurve

Parameters

duration

The number of seconds over which the animation occurs. Specifying a negative number raises an exception.

animationCurve

An NSAnimationCurve constant that describes the relative speed of the animation over its course; if it is zero, the default curve (NSAnimationEaseInOut) is used.

Return Value

An initialized NSAnimation instance. Returns nil if the object could not be initialized.

Discussion

You can always later change the duration of an NSAnimation object by sending it a setDuration: message, even while the animation is running. See "Constants" for descriptions of the NSAnimationCurve constants.

Availability

• Available in Mac OS X v10.4 and later.

Related Sample Code

• CarbonCocoaCoreImageTab
• Reducer

Declared In

NSAnimation.h

isAnimating

Returns a Boolean value that indicates whether the receiver is currently animating.

- (BOOL)isAnimating

Return Value

YES if the receiver is animating, NO otherwise.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSAnimation.h

progressMarks

Returns the receiver’s progress marks.

- (NSArray *)progressMarks

Return Value

An array of NSNumber objects, each encapsulating a float value (typed as NSAnimationProgress) that represents a current progress mark. If the receiver has no progress marks, an empty array is returned.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addProgressMark:
• – setProgressMarks:

Declared In

NSAnimation.h

removeProgressMark:

Removes progress mark from the receiver.

- (void)removeProgressMark:(NSAnimationProgress)progressMark

Parameters

progressMark

A float value (typed as NSAnimationProgress) that indicates the portion of the animation completed. The value should correspond to a progress mark set with addProgressMark: or setProgressMarks:.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addProgressMark:

Declared In

NSAnimation.h

runLoopModesForAnimating

Overridden to return the run-loop modes that the receiver uses to run the animation timer in.

- (NSArray *)runLoopModesForAnimating

Return Value

An array of constants that indicate the modes the animation's run loop can be in. By default, the method returns nil, which indicates that the animation can be run in default, modal, or event-tracking mode. See the NSRunLoop class reference for information about the mode constants

Discussion

The value returned from this method is ignored if the animation blocking mode is something other than NSAnimationNonblocking.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setAnimationBlockingMode:

Declared In

NSAnimation.h

setAnimationBlockingMode:

Sets the blocking mode of the receiver.

- (void)setAnimationBlockingMode:(NSAnimationBlockingMode)animationBlockingMode

Parameters

animationBlockingMode

A constant representing the blocking mode the animation is next scheduled to run under. See “NSAnimationBlockingMode” for valid values.

If the constant is NSAnimationNonblocking, the animation runs in the main thread in one of the standard run-loop modes or in a mode returned from runLoopModesForAnimating. If animationBlockingMode is NSAnimationNonblockingThreaded, a new thread is spawned to run the animation.

Discussion

The default mode is NSAnimationBlocking, which means that the animation runs on the main thread in a custom run-loop mode that blocks user events. The new blocking mode takes effect the next time the receiver is started and has no effect on an animation underway.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – animationBlockingMode

Related Sample Code

• Reducer

Declared In

NSAnimation.h

setAnimationCurve:

Sets the receiver’s animation curve.

- (void)setAnimationCurve:(NSAnimationCurve)curve

Parameters

curve

An NSAnimationCurve constant specifying the animation curve. Invalid values raise an exception.

Discussion

The animation curve describes the relative frame rate over the course of the animation; predefined curves are linear, ease in (slow down near end), ease out (slowly speed up at start), and ease in-ease out (S-curve). Sending this message affects animations already in progress. The NSAnimationCurve setting is ignored if the delegate implements animation:valueForProgress:. See “NSAnimationCurve” for valid NSAnimationCurve constants.

Availability

• Available in Mac OS X v10.4 and later.

Related Sample Code

• QTCoreVideo301

Declared In

NSAnimation.h

setCurrentProgress:

Sets the current progress of the receiver.

- (void)setCurrentProgress:(NSAnimationProgress)progress

Parameters

progress

A float value typed as NSAnimationProgress that specifies the current progress of the animation. This value should be between 0.0 and 1.0; values that are out of range are pinned to 0.0 or 1.0, whichever is closer.

Discussion

You can use this method to adjust the progress of a running animation. The NSAnimation class invokes this method while the animation is running to change the progress for the next frame. Subclasses can override this method to get the latest value and perform their action with it, possibly in a secondary thread. Alternatively, you can implement the delegation method animation:valueForProgress:.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – currentProgress

Declared In

NSAnimation.h

setDelegate:

Sets the delegate of the receiver.

- (void)setDelegate:(id)delegate

Parameters

delegate

The delegate for the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – delegate

Declared In

NSAnimation.h

setDuration:

Sets the duration of the animation to a specified number of seconds.

- (void)setDuration:(NSTimeInterval)duration

Parameters

duration

An NSTimeInterval value specifying the duration of the animation. Negative values raise an exception.

Discussion

You can change the duration of an animation while it is running. However, setting the duration of a running animation to an interval shorter than the current progress ends the animation.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – duration

Related Sample Code

• QTCoreVideo301
• Reducer

Declared In

NSAnimation.h

setFrameRate:

Sets the frame rate of the receiver.

- (void)setFrameRate:(float)framesPerSecond

Parameters

framesPerSecond

A float value specifying the number of updates per second for the animation. This value must be positive; negative values raise an exception. A frame rate of 0.0 means to go as fast as possible.

Discussion

The frame rate is not guaranteed due to differences among systems for the time needed to process a frame. You can change the frame rate while an animation is running and the new value is used at the next frame. The default frame rate is set to a reasonable value (which is subject to future change).

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – frameRate

Declared In

NSAnimation.h

setProgressMarks:

Sets the receiver’s progress marks to the values specified in the passed-in array.

- (void)setProgressMarks:(NSArray *)progressMarks

Parameters

progressMarks

An array of NSNumber objects, each encapsulating a float value (typed as NSAnimationProgress) that represents a current progress mark. Passing in nil clears all progress marks.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – progressMarks

Declared In

NSAnimation.h

startAnimation

Starts the animation represented by the receiver.

- (void)startAnimation

Discussion

The receiver retains itself and is then autoreleased at the end of the animation or when it receives stopAnimation. If the blocking mode is NSAnimationBlocking, the method only returns after the animation has completed or the delegate sends it stopAnimation. If the receiver has a progress of 1.0, it starts again at 0.0.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – startWhenAnimation:reachesProgress:
• – stopAnimation

Related Sample Code

• QTCoreVideo301
• Reducer

Declared In

NSAnimation.h

startWhenAnimation:reachesProgress:

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

- (void)startWhenAnimation:(NSAnimation *)animation reachesProgress:(NSAnimationProgress)startProgress

Parameters

animation

The other NSAnimation object with which the receiver is linked.

startProgress

A float value (typed as NSAnimationProgress) that specifies a progress mark of the other animation.

Discussion

This method links the running of two animations together. You can set only one NSAnimation object as a start animation and one as a stop animation at any one time. Setting a new start animation removes any animation previously set.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – clearStartAnimation
• – startAnimation
• – stopWhenAnimation:reachesProgress:

Declared In

NSAnimation.h

stopAnimation

Stops the animation represented by the receiver.

- (void)stopAnimation

Discussion

The current progress of the receiver is not reset. When this method is sent to instances of NSViewAnimation (a subclass of NSAnimation) the receiver moves to the end frame location.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – startAnimation
• – stopWhenAnimation:reachesProgress:

Declared In

NSAnimation.h

stopWhenAnimation:reachesProgress:

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

- (void)stopWhenAnimation:(NSAnimation *)animation reachesProgress:(NSAnimationProgress)stopProgress

Parameters

animation

The other NSAnimation object with which the receiver is linked.

stopProgress

A float value (typed as NSAnimationProgress) that specifies a progress mark of the other animation.

Discussion

This method links the running of two animations together. You can set only one NSAnimation object as a start animation and one as a stop animation at any one time. Setting a new stop animation removes any animation previously set.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – clearStopAnimation
• – startWhenAnimation:reachesProgress:
• – stopAnimation

Declared In

NSAnimation.h

Delegate Methods

animation:didReachProgressMark:

Sent to the delegate when an animation reaches a specific progress mark.

- (void)animation:(NSAnimation *)animation didReachProgressMark:(NSAnimationProgress)progress

Parameters

animation

A running NSAnimation object that has reached a progress mark.

progress

A float value (typed as NSAnimationProgress) that indicates a progress mark of animation.

Discussion

The delegate typically implements this method to perform some animation effect for the time slice indicated by progress, such as redrawing objects in a view with new coordinates or changing the frame location or size of a window or view. As an alternative to this delegation message, you may choose to observe the NSAnimationProgressMarkNotification notification.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSAnimation.h

animation:valueForProgress:

Requests a custom curve value for the current progress value.

- (float)animation:(NSAnimation *)animation valueForProgress:(NSAnimationProgress)progress

Parameters

animation

An NSAnimation object that is running.

progress

A float value (typed as NSAnimationProgress) that indicates a progress mark of animation. This value is always between 0.0 and 1.0.

Return Value

A float value representing a custom curve.

Discussion

The delegate can compute and return a custom curve value for the given progress value. If the delegate does not implement this method, NSAnimation computes the current curve value.

The animation:valueForProgress: message is sent to the delegate when an NSAnimation object receives a currentValue message. The value the delegate returns is used as the value of currentValue; if there is no delegate, or it doesn't implement animation:valueForProgress:, NSAnimation computes and returns the current value. NSAnimation does not invoke currentValue itself, but subclasses might.

See the description of currentValue for more information.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – currentValue

Declared In

NSAnimation.h

animationDidEnd:

Sent to the delegate when the specified animation completes its run.

- (void)animationDidEnd:(NSAnimation *)animation

Parameters

animation

The NSAnimation instance that completed its run.

Discussion

When an NSAnimation object reaches the end of its planned duration, it has a progress value of 1.0.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – animationDidStop:
• – currentProgress

Declared In

NSAnimation.h

animationDidStop:

Sent to the delegate when the specified animation is stopped before it completes its run.

- (void)animationDidStop:(NSAnimation *)animation

Parameters

animation

The NSAnimation instance that was stopped.

Discussion

An NSAnimation object stops running when it receives a stopAnimation message.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – animationDidEnd:

Declared In

NSAnimation.h

animationShouldStart:

Sent to the delegate just after an animation is started.

- (BOOL)animationShouldStart:(NSAnimation *)animation

Parameters

animation

The NSAnimation object that was just started.

Return Value

NO to cancel the animation, YES to have the animation proceed.

Discussion

The delegate is sent this message just after animation receives a startAnimation message. The delegate can use this method to prepare objects and resources for the effect.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – animationDidEnd:
• – animationDidStop:

Declared In

NSAnimation.h

Constants

NSAnimationCurve

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

enum {
   NSAnimationEaseInOut,
   NSAnimationEaseIn,
   NSAnimationEaseOut,
   NSAnimationLinear
};
typedef NSUInteger NSAnimationCurve;

Constants

NSAnimationEaseInOut

Describes an S-curve in which the animation slowly speeds up and then slows down near the end of the animation. This constant is the default.

Available in Mac OS X v10.4 and later.

Declared in NSAnimation.h.

NSAnimationEaseIn

Describes an animation that slows down as it reaches the end.

Available in Mac OS X v10.4 and later.

Declared in NSAnimation.h.

NSAnimationEaseOut

Describes an animation that slowly speeds up from the start.

Available in Mac OS X v10.4 and later.

Declared in NSAnimation.h.

NSAnimationLinear

Describes an animation in which there is no change in frame rate.

Available in Mac OS X v10.4 and later.

Declared in NSAnimation.h.

Discussion

You initialize an NSAnimation object using one of these constants with initWithDuration:animationCurve: and you can set it thereafter with setAnimationCurve:.

Declared In

NSAnimation.h

NSAnimationBlockingMode

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

enum {
   NSAnimationBlocking,
   NSAnimationNonblocking,
   NSAnimationNonblockingThreaded
};
typedef NSUInteger NSAnimationBlockingMode;

Constants

NSAnimationBlocking

Requests the animation to run in the main thread in a custom run-loop mode that blocks user input.

This is the default.

Available in Mac OS X v10.4 and later.

Declared in NSAnimation.h.

NSAnimationNonblocking

Requests the animation to run in a standard or specified run-loop mode that allows user input.

Available in Mac OS X v10.4 and later.

Declared in NSAnimation.h.

NSAnimationNonblockingThreaded

Requests the animation to run in a separate thread that is spawned by the NSAnimation object.

The secondary thread has its own run loop.

Available in Mac OS X v10.4 and later.

Declared in NSAnimation.h.

Discussion

You specify one of these constants in setAnimationBlockingMode:.

Declared In

NSAnimation.h

Animation action triggers

These constants are used by the NSAnimatablePropertyContainer methods defaultAnimationForKey: and animationForKey:.

NSString *NSAnimationTriggerOrderIn;
NSString *NSAnimationTriggerOrderOut;

Constants

NSAnimationTriggerOrderIn

The trigger that represents the action taken when a view becomes visible, either as a result of being inserted into the visible view hierarchy or the view is no longer set as hidden.

Available in Mac OS X v10.5 and later.

Declared in NSAnimation.h.

NSAnimationTriggerOrderOut

The trigger that represents the action taken when the view is either removed from the view hierarchy or is hidden.

Available in Mac OS X v10.5 and later.

Declared in NSAnimation.h.

Declared In

NSAnimation.h

Notification Key

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

NSString*    NSAnimationProgressMark;

Constants

NSAnimationProgressMark

Contains a float as an NSNumber instance that indicates the current animation progress.

Available in Mac OS X v10.4 and later.

Declared in NSAnimation.h.

Declared In

NSAnimation.h

Notifications

NSAnimationProgressMarkNotification

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

The notification object is a running NSAnimation object. The userInfo dictionary contains the current progress mark, accessed via the key NSAnimationProgressMark.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – animation:didReachProgressMark:

Declared In

NSAnimation.h

---