NSAnimationContext Class Reference

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

Overview

NSAnimationContext is analogous to CATransaction and are similar in overall concept to NSGraphicsContext. Each thread maintains its own stack of nestable NSAnimationContext instances, with each new instance initialized as a copy of the instance below (so, inheriting its current properties).

Multiple NSAnimationContext instances can be nested, allowing a given block of code to initiate animations using its own specified duration without affecting animations initiated by surrounding code.

[NSAnimationContext beginGrouping];
// Animate enclosed operations with a duration of 1 second
[[NSAnimationContext currentContext] setDuration:1.0];
[[aView animator] setFrame:newFrame];
...
    [NSAnimationContext beginGrouping];
    // Animate alpha fades with half-second duration
    [[NSAnimationContext currentContext] setDuration:0.5];
    [[aView animator] setAlphaValue:0.75];
    [[bView animator] setAlphaValue:0.75];
    [NSAnimationContext endGrouping];
...
// Will animate with a duration of 1 second
[[bView animator] setFrame:secondFrame];
[NSAnimationContext endGrouping];

Tasks

Grouping Transactions

Getting the Current Animation Context

Animation Completion Handlers

Modifying the Animation Duration

Implicit Animation

Properties

allowsImplicitAnimation

Determine if animations are enabled or not for animations that occur as a result of another property change.

@property BOOL allowsImplicitAnimation
Discussion

Using the animator proxy will automatically set allowsImplicitAnimation to YES. When YES, other properties can implicitly animate along with the initially changed property.

For instance, calling [[view animator] setFrame:frame] will allow subviews to also animate their frame positions. When the value is NO the behavior is diabled.

The default value is NO.

This is only applicable when layer backed on OS v10.8 and later.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSAnimationContext.h

completionHandler

A completion Block that is called when the animations in the grouping are completed.

@property(copy) void(^completionHandler)(void)
Discussion

If set to a non-nil value, a context’s completionHandler is guaranteed to be called on the main thread as soon as all animations subsequently added to the current NSAnimationContext grouping have completed or been cancelled.

This method drives the underlying CATransactioncompletionBlock property, although the Application Kit may assign a different, intermediary completionBlock to the current CATransaction.

The completion handler waits for all animations to which the handler applies, independent of whether they are evaluated by the Application Kit or delegated to Core Animation for evaluation in the render tree before firing.

If no animations are added before the current grouping is ended—or the completionHandler is set to a different value—the handler will be invoked immediately.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSAnimationContext.h

duration

The duration used by animations created as a result of setting new values for an animatable property.

@property NSTimeInterval duration
Discussion

Any animations that occur as a result of setting the values of animatable properties in the current context will run for this duration.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSAnimationContext.h

timingFunction

The timing function used for all animations within this animation proxy group.

@property(retain) CAMediaTimingFunction *timingFunction
Discussion

The NSAnimationContext timing function is analogous to the CATransaction setAnimationTimingFunction: method.

Animations initiated through the “animator” proxy syntax, that do not have an explicitly specified timing functions, will inherit the enclosing NSAnimationContext instance’s timingFunction if it is not nil (which is the default).

As with the existing duration property, changing a timing function causes the same change in the underlying CATransaction instance’s animationTimingFunction.

Also as with the duration property, you may change the timingFunction any number of times within a given NSAnimationContext beginGrouping and endGrouping block. Changes to the timingFunction will apply to any animations that are subsequently initiated in that NSAnimationContext grouping, until the timingFunction is possibly changed again.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSAnimationContext.h

Class Methods

beginGrouping

Creates a new animation grouping.

+ (void)beginGrouping
Availability
  • Available in OS X v10.5 and later.
Declared In
NSAnimationContext.h

currentContext

Returns the current animation context.

+ (NSAnimationContext *)currentContext
Return Value

The current animation context.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSAnimationContext.h

endGrouping

Ends the current animation grouping.

+ (void)endGrouping
Availability
  • Available in OS X v10.5 and later.
Declared In
NSAnimationContext.h

runAnimationGroup:completionHandler:

Allows you to specify a completion block body after the set of animation actions whose completion will trigger the completion block.

+ (void)runAnimationGroup:(void (^)(NSAnimationContext *context))changes completionHandler:(void (^)(void))completionHandler
Parameters
changes

A block object containing animations for this transaction group.

The context parameter passes the thread’s current NSAnimationContext to the Block as a convenience, so code within the Block that wants to change or query properties of the current context does not have to call currentContext.

The block object returns no value.

completionHandler

A Block object called when animations for this transaction group are completed.

The Block object takes no parameters and returns no value.

Discussion

Using this method allows you to more naturally group animations and an completion Block.

An example use is as follows. Using this method you would write the following code fragment:

[NSAnimationContext runAnimationGroup:^(NSAnimationContext *context){
    // Start some animations.
    [[myView animator] setFrameSize:newViewSize];
    [[myWindow animator] setFrame:newWindowFrame display:YES];
  } completionHandler:^{
    // This block will be invoked when all of the animations
    // started above have completed or been cancelled.
    NSLog(@"All done!");
}];

The above code is semantically equivalent to the following:

[NSAnimationContext beginGrouping];
    [NSAnimationContext setCompletionHandler:^{
       // This block will be invoked when all of the animations
       //  started below have completed or been cancelled.
        NSLog(@"All done!");
    }];
    // Start some animations.
    [[myView animator] setFrameSize:newViewSize];
    [[myWindow animator] setFrame:newWindowFrame display:YES];
[NSAnimationContext endGrouping];
Availability
  • Available in OS X v10.7 and later.
Declared In
NSAnimationContext.h