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 | |
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
-
– setAnimationBlockingMode: -
– animationBlockingMode -
– runLoopModesForAnimating -
– setAnimationCurve: -
– animationCurve -
– setDuration: -
– duration -
– setFrameRate: -
– frameRate
Managing the Delegate
Controlling and Monitoring an Animation
-
– startAnimation -
– stopAnimation -
– isAnimating -
– setCurrentProgress: -
– currentProgress -
– currentValue
Managing Progress Marks
Linking Animations Together
Instance Methods
addProgressMark:
Adds the progress mark to the receiver.
Parameters
- progressMark
A
floatvalue (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.
See Also
Declared In
NSAnimation.hanimationBlockingMode
Returns the blocking mode the receiver is next scheduled to run under.
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.
See Also
Declared In
NSAnimation.hanimationCurve
Returns the animation curve the receiver is running under.
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.
See Also
Declared In
NSAnimation.hclearStartAnimation
Clears linkage to another animation that causes the receiver to start.
Discussion
The linkage to the other animation is made with startWhenAnimation:reachesProgress:.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSAnimation.hclearStopAnimation
Clears linkage to another animation that causes the receiver to stop.
Discussion
The linkage to the other animation is made with stopWhenAnimation:reachesProgress:.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSAnimation.hcurrentProgress
Returns the current progress of the receiver.
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.
See Also
Declared In
NSAnimation.hcurrentValue
Returns the current value of the effect based on the current progress.
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.
See Also
Declared In
NSAnimation.hdelegate
Returns the delegate of the receiver.
Return Value
The receiver's delegate.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSAnimation.hduration
Returns the duration of the animation, in seconds.
Return Value
An NSTimeInterval value indicating the duration.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSAnimation.hframeRate
Returns the frame rate of the animation.
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.hinitWithDuration:animationCurve:
Returns an NSAnimation object initialized with the specified duration and animation-curve values.
Parameters
- duration
The number of seconds over which the animation occurs. Specifying a negative number raises an exception.
- animationCurve
An
NSAnimationCurveconstant 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.hisAnimating
Returns a Boolean value that indicates whether the receiver is currently animating.
Return Value
YES if the receiver is animating, NO otherwise.
Availability
- Available in OS X v10.4 and later.
Declared In
NSAnimation.hprogressMarks
Returns the receiver’s progress marks.
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.
See Also
Declared In
NSAnimation.hremoveProgressMark:
Removes progress mark from the receiver.
Parameters
- progressMark
A
floatvalue (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.
See Also
Declared In
NSAnimation.hrunLoopModesForAnimating
Overridden to return the run-loop modes that the receiver uses to run the animation timer in.
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.
See Also
Declared In
NSAnimation.hsetAnimationBlockingMode:
Sets the blocking mode of the receiver.
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 fromrunLoopModesForAnimating. If animationBlockingMode isNSAnimationNonblockingThreaded, 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.
See Also
Declared In
NSAnimation.hsetAnimationCurve:
Sets the receiver’s animation curve.
Parameters
- curve
An
NSAnimationCurveconstant 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.hsetCurrentProgress:
Sets the current progress of the receiver.
Parameters
- progress
A
floatvalue 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.
See Also
Declared In
NSAnimation.hsetDelegate:
Sets the delegate of the receiver.
Parameters
- delegate
The delegate for the receiver.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSAnimation.hsetDuration:
Sets the duration of the animation to a specified number of seconds.
Parameters
- duration
An
NSTimeIntervalvalue 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.hsetFrameRate:
Sets the frame rate of the receiver.
Parameters
- framesPerSecond
A
floatvalue 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.
See Also
Declared In
NSAnimation.hsetProgressMarks:
Sets the receiver’s progress marks to the values specified in the passed-in array.
Parameters
- progressMarks
An array of
NSNumberobjects, each encapsulating afloatvalue (typed as NSAnimationProgress) that represents a current progress mark. Passing innilclears all progress marks.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSAnimation.hstartAnimation
Starts the animation represented by the receiver.
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.hstartWhenAnimation:reachesProgress:
Starts running the animation represented by the receiver when another animation reaches a specific progress mark.
Parameters
- animation
The other
NSAnimationobject with which the receiver is linked.- startProgress
A
floatvalue (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.hstopAnimation
Stops the animation represented by the receiver.
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.hstopWhenAnimation:reachesProgress:
Stops running the animation represented by the receiver when another animation reaches a specific progress mark.
Parameters
- animation
The other
NSAnimationobject with which the receiver is linked.- stopProgress
A
floatvalue (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.hConstants
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
NSAnimationEaseInOutDescribes 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.NSAnimationEaseInDescribes an animation that slows down as it reaches the end.
Available in OS X v10.4 and later.
Declared in
NSAnimation.h.NSAnimationEaseOutDescribes an animation that slowly speeds up from the start.
Available in OS X v10.4 and later.
Declared in
NSAnimation.h.NSAnimationLinearDescribes 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
NSAnimationBlockingRequests 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.NSAnimationNonblockingRequests 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.NSAnimationNonblockingThreadedRequests the animation to run in a separate thread that is spawned by the
NSAnimationobject.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.hAnimation action triggers
These constants are used by the NSAnimatablePropertyContainer methods defaultAnimationForKey: and animationForKey:.
NSString *NSAnimationTriggerOrderIn; NSString *NSAnimationTriggerOrderOut;
Constants
NSAnimationTriggerOrderInThe 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.NSAnimationTriggerOrderOutThe 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
NSAnimationProgressMarkContains the value of an
NSAnimationProgressas anNSNumberinstance 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
The notification object is a running NSAnimation object. The userInfo dictionary contains the current progress mark, accessed via the key NSAnimationProgressMark.
Availability
- Available in OS X v10.4 and later.
See Also
-
– animation:didReachProgressMark:(NSAnimationDelegate)
Declared In
NSAnimation.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-04-17)