Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.4 and later. |
Declared in | NSAnimation.h |
Companion guides | |
Related sample code |
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.
Note: For simple tasks requiring a timing mechanism, consider using NSTimer
.
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.
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.
– setAnimationBlockingMode:
– animationBlockingMode
– runLoopModesForAnimating
– setAnimationCurve:
– animationCurve
– setDuration:
– duration
– setFrameRate:
– frameRate
– startAnimation
– stopAnimation
– isAnimating
– setCurrentProgress:
– currentProgress
– currentValue
– animationDidEnd:
delegate method
– animationDidStop:
delegate method
– animationShouldStart:
delegate method
– animation:valueForProgress:
delegate method
– addProgressMark:
– removeProgressMark:
– setProgressMarks:
– progressMarks
– animation:didReachProgressMark:
delegate method
– startWhenAnimation:reachesProgress:
– stopWhenAnimation:reachesProgress:
– clearStartAnimation
– clearStopAnimation
Adds the progress mark to the receiver.
- (void)addProgressMark:(NSAnimationProgress)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.
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.
NSAnimation.h
Returns the blocking mode the receiver is next scheduled to run under.
- (NSAnimationBlockingMode)animationBlockingMode
A constant representing the receiver's blocking mode. See “NSAnimationBlockingMode” for valid values.
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
.
NSAnimation.h
Returns the animation curve the receiver is running under.
- (NSAnimationCurve)animationCurve
An NSAnimationCurve
constant indicating the animation curve.
The animation curve describes the relative frame rate over the course of the animation. See “NSAnimationCurve” for valid NSAnimationCurve constants.
NSAnimation.h
Clears linkage to another animation that causes the receiver to start.
- (void)clearStartAnimation
The linkage to the other animation is made with startWhenAnimation:reachesProgress:
.
NSAnimation.h
Clears linkage to another animation that causes the receiver to stop.
- (void)clearStopAnimation
The linkage to the other animation is made with stopWhenAnimation:reachesProgress:
.
NSAnimation.h
Returns the current progress of the receiver.
- (NSAnimationProgress)currentProgress
A float
value typed as NSAnimationProgress that indicates the current progress of the animation.
The current progress is a value between 0.0 and 1.0 that represents the percentage of the animation currently completed.
NSAnimation.h
Returns the current value of the effect based on the current progress.
- (float)currentValue
A float
value that indicates the current value of the animation effect.
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.
NSAnimation.h
Returns the delegate of the receiver.
- (id)delegate
The receiver's delegate.
NSAnimation.h
Returns the duration of the animation, in seconds.
- (NSTimeInterval)duration
An NSTimeInterval
value indicating the duration.
NSAnimation.h
Returns the frame rate of the animation.
- (float)frameRate
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.
NSAnimation.h
Returns an NSAnimation
object initialized with the specified duration and animation-curve values.
- (id)initWithDuration:(NSTimeInterval)duration animationCurve:(NSAnimationCurve)animationCurve
The number of seconds over which the animation occurs. Specifying a negative number raises an exception.
An NSAnimationCurve
constant that describes the relative speed of the animation over its course; if it is zero, the default curve (NSAnimationEaseInOut
) is used.
An initialized NSAnimation
instance. Returns nil
if the object could not be initialized.
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.
NSAnimation.h
Returns a Boolean value that indicates whether the receiver is currently animating.
- (BOOL)isAnimating
YES
if the receiver is animating, NO
otherwise.
NSAnimation.h
Returns the receiver’s progress marks.
- (NSArray *)progressMarks
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.
NSAnimation.h
Removes progress mark from the receiver.
- (void)removeProgressMark:(NSAnimationProgress)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:.
NSAnimation.h
Overridden to return the run-loop modes that the receiver uses to run the animation timer in.
- (NSArray *)runLoopModesForAnimating
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
The value returned from this method is ignored if the animation blocking mode is something other than NSAnimationNonblocking
.
NSAnimation.h
Sets the blocking mode of the receiver.
- (void)setAnimationBlockingMode:(NSAnimationBlockingMode)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.
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.
NSAnimation.h
Sets the receiver’s animation curve.
- (void)setAnimationCurve:(NSAnimationCurve)curve
An NSAnimationCurve
constant specifying the animation curve. Invalid values raise an exception.
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.
NSAnimation.h
Sets the current progress of the receiver.
- (void)setCurrentProgress:(NSAnimationProgress)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.
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:
.
NSAnimation.h
Sets the delegate of the receiver.
- (void)setDelegate:(id)delegate
The delegate for the receiver.
NSAnimation.h
Sets the duration of the animation to a specified number of seconds.
- (void)setDuration:(NSTimeInterval)duration
An NSTimeInterval
value specifying the duration of the animation. Negative values raise an exception.
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.
NSAnimation.h
Sets the frame rate of the receiver.
- (void)setFrameRate:(float)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.
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).
NSAnimation.h
Sets the receiver’s progress marks to the values specified in the passed-in array.
- (void)setProgressMarks:(NSArray *)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.
NSAnimation.h
Starts the animation represented by the receiver.
- (void)startAnimation
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.
NSAnimation.h
Starts running the animation represented by the receiver when another animation reaches a specific progress mark.
- (void)startWhenAnimation:(NSAnimation *)animation reachesProgress:(NSAnimationProgress)startProgress
The other NSAnimation
object with which the receiver is linked.
A float
value (typed as NSAnimationProgress) that specifies a progress mark of the other animation.
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.
NSAnimation.h
Stops the animation represented by the receiver.
- (void)stopAnimation
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.
NSAnimation.h
Stops running the animation represented by the receiver when another animation reaches a specific progress mark.
- (void)stopWhenAnimation:(NSAnimation *)animation reachesProgress:(NSAnimationProgress)stopProgress
The other NSAnimation
object with which the receiver is linked.
A float
value (typed as NSAnimationProgress) that specifies a progress mark of the other animation.
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.
NSAnimation.h
Sent to the delegate when an animation reaches a specific progress mark.
- (void)animation:(NSAnimation *)animation didReachProgressMark:(NSAnimationProgress)progress
A running NSAnimation
object that has reached a progress mark.
A float
value (typed as NSAnimationProgress
) that indicates a progress mark of animation
.
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.
NSAnimation.h
Requests a custom curve value for the current progress value.
- (float)animation:(NSAnimation *)animation valueForProgress:(NSAnimationProgress)progress
An NSAnimation
object that is running.
A float
value (typed as NSAnimationProgress
) that indicates a progress mark of animation
. This value is always between 0.0 and 1.0.
A float
value representing a custom curve.
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.
NSAnimation.h
Sent to the delegate when the specified animation completes its run.
- (void)animationDidEnd:(NSAnimation *)animation
The NSAnimation
instance that completed its run.
When an NSAnimation
object reaches the end of its planned duration, it has a progress value of 1.0.
NSAnimation.h
Sent to the delegate when the specified animation is stopped before it completes its run.
- (void)animationDidStop:(NSAnimation *)animation
The NSAnimation
instance that was stopped.
An NSAnimation
object stops running when it receives a stopAnimation
message.
NSAnimation.h
Sent to the delegate just after an animation is started.
- (BOOL)animationShouldStart:(NSAnimation *)animation
The NSAnimation
object that was just started.
NO
to cancel the animation, YES
to have the animation proceed.
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.
NSAnimation.h
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;
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
.
You initialize an NSAnimation
object using one of these constants with initWithDuration:animationCurve:
and you can set it thereafter with setAnimationCurve:
.
NSAnimation.h
These constants indicate the blocking mode of an NSAnimation
object when it is running.
enum { NSAnimationBlocking, NSAnimationNonblocking, NSAnimationNonblockingThreaded }; typedef NSUInteger NSAnimationBlockingMode;
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
.
You specify one of these constants in setAnimationBlockingMode:
.
NSAnimation.h
These constants are used by the NSAnimatablePropertyContainer
methods defaultAnimationForKey:
and animationForKey:
.
NSString *NSAnimationTriggerOrderIn; NSString *NSAnimationTriggerOrderOut;
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
.
NSAnimation.h
This constant is returned in the userInfo dictionary of the NSAnimationProgressMarkNotification
notification.
NSString* NSAnimationProgressMark;
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
.
NSAnimation.h
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
.
NSAnimation.h
© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)