Mac Developer Library

Developer

AppKit Framework Reference NSAnimation Class Reference

Options
Deployment Target:

On This Page
Language:

NSAnimation

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

Inheritance


Conforms To


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.4 and later.
  • 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 sending it a setDuration: message, even while the animation is running. See "Constants" for descriptions of the NSAnimationCurve constants.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the blocking mode of the receiver.

    Declaration

    Swift

    var animationBlockingMode: NSAnimationBlockingMode

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var animationBlockingMode: NSAnimationBlockingMode

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var runLoopModesForAnimating: [AnyObject]? { get }

    Objective-C

    @property(readonly, copy) 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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the receiver’s animation curve.

    Declaration

    Swift

    var animationCurve: NSAnimationCurve

    Objective-C

    @property NSAnimationCurve animationCurve

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the animation curve the receiver is running under.

    Declaration

    Swift

    var animationCurve: NSAnimationCurve

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var duration: NSTimeInterval

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – duration

  • Returns the duration of the animation, in seconds.

    Declaration

    Swift

    var duration: NSTimeInterval

    Objective-C

    @property NSTimeInterval duration

    Return Value

    An NSTimeInterval value indicating the duration.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the frame rate of the receiver.

    Declaration

    Swift

    var frameRate: Float

    Objective-C

    @property float frameRate

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – frameRate

  • Returns the frame rate of the animation.

    Declaration

    Swift

    var frameRate: Float

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the delegate of the receiver.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSAnimationDelegate?

    Objective-C

    @property(assign) id<NSAnimationDelegate> delegate

    Parameters

    delegate

    The delegate for the receiver.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – delegate

  • Returns the delegate of the receiver.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSAnimationDelegate?

    Objective-C

    @property(assign) id<NSAnimationDelegate> delegate

    Return Value

    The receiver's delegate.

    Import Statement

    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

    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.

    Import Statement

    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

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • isAnimating isAnimating Available in OS X v10.4 through OS X v10.9

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

    Declaration

    Objective-C

    - (BOOL)isAnimating

    Return Value

    YEStrue if the receiver is animating, NOfalse otherwise.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.9.

  • Sets the current progress of the receiver.

    Declaration

    Swift

    var currentProgress: NSAnimationProgress

    Objective-C

    @property NSAnimationProgress currentProgress

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the current progress of the receiver.

    Declaration

    Swift

    var currentProgress: NSAnimationProgress

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var currentValue: Float { get }

    Objective-C

    @property(readonly) 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.

    Import Statement

    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

    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

    enum { NSAnimationEaseInOut, NSAnimationEaseIn, NSAnimationEaseOut, NSAnimationLinear }; typedef NSUInteger 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 setAnimationCurve:.

    Import Statement

    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

    enum { NSAnimationBlocking, NSAnimationNonblocking, NSAnimationNonblockingThreaded }; typedef NSUInteger 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 setAnimationBlockingMode:.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var NSAnimationTriggerOrderIn: NSString! var NSAnimationTriggerOrderOut: NSString!

    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.

    Import Statement

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

    Declaration

    Swift

    var NSAnimationProgressMark: NSString!

    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.

    Import Statement

  • 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

    import AppKit

    Availability

    Available in OS X v10.4 and later.