Mac Developer Library

Developer

AppKit Framework Reference NSAnimation Class Reference

Options
Deployment Target:

On This Page
Language:

NSAnimation

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.4 and later.

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 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.

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

    Declaration

    Swift

    init(duration duration: NSTimeInterval, animationCurve animationCurve: NSAnimationCurve)

    Objective-C

    - (instancetype)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 changing the duration property, even while the animation is running. See "Constants" for descriptions of the NSAnimationCurve constants.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The blocking mode of the animation.

    Declaration

    Swift

    var animationBlockingMode: NSAnimationBlockingMode

    Objective-C

    @property NSAnimationBlockingMode animationBlockingMode

    Discussion

    The value in this property determines whether the animation blocks a given thread. The default value of this property is NSAnimationBlocking, which means that the animation runs on the main thread in a custom run-loop mode that blocks user events. When changing the value of this property, the new blocking mode takes effect the next time the animation is started and has no effect on an in-progress animation.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • An array of strings representing the run loop modes in which the animation can run. (read-only)

    Declaration

    Swift

    var runLoopModesForAnimating: [AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSArray *runLoopModesForAnimating

    Discussion

    The default value of this property is nil, which indicates that the animation can be run in the default, modal, or event-tracking modes. The value of this property is ignored if the animation blocking mode is something other than NSAnimationNonblocking.

    For information about run loop modes and for constants, see NSRunLoop Class Reference.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The timing curve for the animation.

    Declaration

    Swift

    var animationCurve: NSAnimationCurve

    Objective-C

    @property NSAnimationCurve animationCurve

    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). Changing the value of this property changes the timing of an in-progress animation. The value of this property is ignored if the delegate implements the animation:valueForProgress: method.

    Setting this property to an invalid value raises an exception. For a list of valid animation values, see NSAnimationCurve.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • duration duration Property

    The duration of the animation, in seconds.

    Declaration

    Swift

    var duration: NSTimeInterval

    Objective-C

    @property NSTimeInterval duration

    Discussion

    The value of this property must be greater than or equal to 0. Setting the duration to a negative value raises an exception.

    You can change the duration of an animation while it is running. Setting the duration to a value that is less than the current progress value ends an in-progress animation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • frameRate frameRate Property

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

    Declaration

    Swift

    var frameRate: Float

    Objective-C

    @property float frameRate

    Discussion

    The value of this property must be greater than or equal to 0. Specifying a value of 0.0 causes the animation to run as fast as possible. Setting the property to a negative value raises an exception.

    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).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • delegate delegate Property

    The animation delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSAnimationDelegate?

    Objective-C

    @property(assign) id< NSAnimationDelegate > delegate

    Discussion

    The delegate must conform to the NSAnimationDelegate Protocol.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Starts the animation represented by the receiver.

    Declaration

    Swift

    func startAnimation()

    Objective-C

    - (void)startAnimation

    Discussion

    A strong reference to the animation is maintained until the end of the animation or until its stopAnimation method is called. If the blocking mode is NSAnimationBlocking, this method 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Stops the animation represented by the receiver.

    Declaration

    Swift

    func stopAnimation()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • animating animating Property

    A Boolean value indicating whether the animation is in progress. (read-only)

    Declaration

    Swift

    var animating: Bool { get }

    Objective-C

    @property(getter=isAnimating, readonly) BOOL animating

    Discussion

    The value of this property is YEStrue when the animation is in progress or NOfalse when it is stopped.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The current progress of the animation.

    Declaration

    Swift

    var currentProgress: NSAnimationProgress

    Objective-C

    @property NSAnimationProgress currentProgress

    Discussion

    This property contains the completion percentage of the animation. Valid values are in the range 0.0 to 1.0, where 0.0 represents the beginning of the animation and 1.0 represents the end of the animation.

    Changing the value of this property adjusts the progress of a running animation. Setting this property to a value less than 0.0 sets the value of the property to 0.0. Similarly, specifying a value greater than 1.0 changes the value of the property to 1.0. The NSAnimation class updates the value of this property during the animation. To perform additional tasks at specific progress points, use the delegate’s animation:valueForProgress: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The current value of the animation effect, based on the current progress (read-only)

    Declaration

    Swift

    var currentValue: Float { get }

    Objective-C

    @property(readonly) float currentValue

    Discussion

    An NSAnimation object gets the current value from delegate’s animation:valueForProgress: method. If that method is not implemented, the animation computes the current value from the current progress by factoring in the animation curve. An animation object does not access this property directly. Instances of NSAnimation subclasses or other objects can invoke this method on a periodic basis to get the current value.

    Subclasses may override this property and 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Adds the progress mark to the receiver.

    Declaration

    Swift

    func addProgressMark(_ progressMark: NSAnimationProgress)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Removes progress mark from the receiver.

    Declaration

    Swift

    func removeProgressMark(_ progressMark: NSAnimationProgress)

    Objective-C

    - (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:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var progressMarks: [AnyObject]

    Objective-C

    @property(copy) NSArray *progressMarks

    Discussion

    The value of this property is an array of NSNumber objects, each of which contains a float value, which are typed to the NSAnimationProgress type. If there are no progress marks, the array is empty. Setting the value of this property is nil clears all progress marks.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func startWhenAnimation(_ animation: NSAnimation, reachesProgress startProgress: NSAnimationProgress)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func stopWhenAnimation(_ animation: NSAnimation, reachesProgress stopProgress: NSAnimationProgress)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func clearStartAnimation()

    Objective-C

    - (void)clearStartAnimation

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func clearStopAnimation()

    Objective-C

    - (void)clearStopAnimation

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

Data Types

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

    Declaration

    Swift

    typealias NSAnimationProgress = Float

    Objective-C

    typedef float NSAnimationProgress;

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    enum NSAnimationCurve : UInt { case EaseInOut case EaseIn case EaseOut case Linear }

    Objective-C

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

    Constants

    • EaseInOut

      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.

    • EaseIn

      NSAnimationEaseIn

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

      Available in OS X v10.4 and later.

    • EaseOut

      NSAnimationEaseOut

      Describes an animation that slowly speeds up from the start.

      Available in OS X v10.4 and later.

    • Linear

      NSAnimationLinear

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

      Available in OS X v10.4 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    enum NSAnimationBlockingMode : UInt { case Blocking case Nonblocking case NonblockingThreaded }

    Objective-C

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

    Constants

    • Blocking

      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.

    • Nonblocking

      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.

    • NonblockingThreaded

      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.

    Discussion

    You specify one of these constants in the animationBlockingMode property.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    let NSAnimationTriggerOrderIn: String let NSAnimationTriggerOrderOut: String

    Objective-C

    NSString *NSAnimationTriggerOrderIn; NSString *NSAnimationTriggerOrderOut;

    Constants

    • NSAnimationTriggerOrderIn

      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.

    • NSAnimationTriggerOrderOut

      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.

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

    Declaration

    Swift

    let NSAnimationProgressMark: String

    Objective-C

    NSString *NSAnimationProgressMark;

    Constants

    • NSAnimationProgressMark

      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.

  • 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.