NSAnimation Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.4 and later.
Declared in
NSAnimation.h
Companion guides
Related sample code

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 Animation Programming Guide for Cocoa.

Tasks

Initializing an NSAnimation Object

Configuring an Animation

Managing the Delegate

Controlling and Monitoring an Animation

Managing Progress Marks

Linking Animations Together

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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
Declared In
NSAnimation.h

delegate

Returns the delegate of the receiver.

- (id < NSAnimationDelegate >)delegate
Return Value

The receiver's delegate.

Availability
  • Available in OS X v10.4 and later.
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 OS X v10.4 and later.
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 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 OS X v10.4 and later.
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 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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
Declared In
NSAnimation.h

setDelegate:

Sets the delegate of the receiver.

- (void)setDelegate:(id < NSAnimationDelegate >)delegate
Parameters
delegate

The delegate for the receiver.

Availability
  • Available in OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.

Declared in NSAnimation.h.

NSAnimationEaseIn

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

Available in OS X v10.4 and later.

Declared in NSAnimation.h.

NSAnimationEaseOut

Describes an animation that slowly speeds up from the start.

Available in 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 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:.

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 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 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 OS X v10.4 and later.

Declared in NSAnimation.h.

Discussion

You specify one of these constants in setAnimationBlockingMode:.

NSAnimationProgress

NSAnimationProgress is returned in the userInfo dictionary of an NSAnimationProgressMarkNotification notification. It will have a value between 0.0 and 1.0

typedef float NSAnimationProgress;
Availability
  • Available in OS X v10.4 and later.
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 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 OS X v10.5 and later.

Declared in NSAnimation.h.

NSAnimationProgressMark Notification Key

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

NSString *NSAnimationProgressMark;
Constants
NSAnimationProgressMark

Contains the value of an NSAnimationProgress as an NSNumber instance that indicates the current animation progress. The value will be between 0.0 and 1.0.

Available in OS X v10.4 and later.

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
See Also
Declared In
NSAnimation.h