CATransaction Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/QuartzCore.framework
Availability
Available in iOS 2.0 and later.
Declared in
CATransaction.h
Companion guides
Core Animation Programming Guide
Core Animation Cookbook
Related sample code

Overview

CATransaction is the Core Animation mechanism for batching multiple layer-tree operations into atomic updates to the render tree. Every modification to a layer tree must be part of a transaction. Nested transactions are supported.

Core Animation supports two types of transactions: implicit transactions and explicit transactions. Implicit transactions are created automatically when the layer tree is modified by a thread without an active transaction and are committed automatically when the thread's run-loop next iterates. Explicit transactions occur when the the application sends the CATransaction class a begin message before modifying the layer tree, and a commit message afterwards.

CATransaction allows you to override default animation properties that are set for animatable properties. You can customize duration, timing function, whether changes to properties trigger animations, and provide a handler that informs you when all animations from the transaction group are completed.

During a transaction you can temporarily acquire a recursive spin-lock for managing property atomicity.

Tasks

Creating and Committing Transactions

Overriding Animation Duration and Timing

Temporarily Disabling Property Animations

Getting and Setting Completion Block Objects

Managing Concurrency

Getting and Setting Transaction Properties

Class Methods

animationDuration

Returns the animation duration used by all animations within this transaction group.

+ (CFTimeInterval)animationDuration
Return Value

An interval of time used as the duration.

Discussion

You can retrieve the animation duration for a specific transaction by calling the valueForKey: method of the transaction object and asking for the kCATransactionAnimationDuration key.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
CATransaction.h

animationTimingFunction

Returns the timing function used for all animations within this transaction group.

+ (CAMediaTimingFunction *)animationTimingFunction
Return Value

An instance of CAMediaTimingFunction.

Discussion

This is a convenience method that returns the CAMediaTimingFunction for the valueForKey: value returned by the kCATransactionAnimationTimingFunction key.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
CATransaction.h

begin

Begin a new transaction for the current thread.

+ (void)begin
Discussion

The transaction is nested within the thread’s current transaction, if there is one.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
CATransaction.h

commit

Commit all changes made during the current transaction.

+ (void)commit
Special Considerations

Raises an exception if no current transaction exists.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
CATransaction.h

completionBlock

Returns the completion block object.

+ (void)completionBlock
Discussion

See setCompletionBlock: for a description of the role of the completion block object.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CATransaction.h

disableActions

Returns whether actions triggered as a result of property changes made within this transaction group are suppressed.

+ (BOOL)disableActions
Return Value

YES if actions are disabled.

Discussion

This is a convenience method that returns the boolValue for the valueForKey: value returned by the kCATransactionDisableActions key.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
CATransaction.h

flush

Flushes any extant implicit transaction.

+ (void)flush
Discussion

Delays the commit until any nested explicit transactions have completed.

Flush is typically called automatically at the end of the current runloop, regardless of the runloop mode. If your application does not have a runloop, you must call this method explicitly.

However, you should attempt to avoid calling flush explicitly. By allowing flush to execute during the runloop your application will achieve better performance, atomic screen updates will be preserved, and transactions and animations that work from transaction to transaction will continue to function.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
CATransaction.h

lock

Attempts to acquire a recursive spin-lock lock, ensuring that returned layer values are valid until unlocked.

+ (void)lock
Discussion

Core Animation uses a data model that promises not to corrupt the internal data structures when called from multiple threads concurrently, but not that data returned is still valid if the property was valid on another thread. By locking during a transaction you can ensure data that is read, modified, and set is correctly managed.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
CATransaction.h

setAnimationDuration:

Sets the animation duration used by all animations within this transaction group.

+ (void)setAnimationDuration:(CFTimeInterval)duration
Parameters
duration

An interval of time used as the duration.

Discussion

You can also set the animation duration for a specific transaction object by calling the setValue:forKey: method of that object and specifying the kCATransactionAnimationDuration key.

Availability
  • Available in iOS 3.0 and later.
See Also
Related Sample Code
Declared In
CATransaction.h

setAnimationTimingFunction:

Sets the timing function used for all animations within this transaction group.

+ (void)setAnimationTimingFunction:(CAMediaTimingFunction *)function
Parameters
function

An instance of CAMediaTimingFunction.

Discussion

This is a convenience method that sets the CAMediaTimingFunction for the valueForKey: value of the kCATransactionAnimationTimingFunction key.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
CATransaction.h

setCompletionBlock:

Sets the completion block object.

+ (void)setCompletionBlock:(void (^)(void))block
Parameters
block

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

The block object takes no parameters and returns no value.

Discussion

The completion block object that is guaranteed to be called (on the main thread) as soon as all animations subsequently added by this transaction group have completed (or have been removed.) If no animations are added before the current transaction group is committed (or the completion block is set to a different value,) the block will be invoked immediately.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CATransaction.h

setDisableActions:

Sets whether actions triggered as a result of property changes made within this transaction group are suppressed.

+ (void)setDisableActions:(BOOL)flag
Parameters
flag

YES, if actions should be disabled.

Discussion

This is a convenience method that invokes setValue:forKey: with an NSNumber containing a YES for the kCATransactionDisableActions key.

Availability
  • Available in iOS 3.0 and later.
See Also
Related Sample Code
Declared In
CATransaction.h

setValue:forKey:

Sets the arbitrary keyed-data for the specified key.

+ (void)setValue:(id)anObject forKey:(NSString *)key
Parameters
anObject

The value for the key identified by key.

key

The name of one of the receiver's properties.

Discussion

Nested transactions have nested data scope; setting a key always sets it in the innermost scope.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CATransaction.h

unlock

Relinquishes a previously acquired transaction lock.

+ (void)unlock
Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
CATransaction.h

valueForKey:

Returns the arbitrary keyed-data specified by the given key.

+ (id)valueForKey:(NSString *)key
Parameters
key

The name of one of the receiver's properties.

Return Value

The value for the data specified by the key.

Discussion

Nested transactions have nested data scope. Requesting a value for a key first searches the innermost scope, then the enclosing transactions.

Availability
  • Available in iOS 2.0 and later.
Declared In
CATransaction.h

Constants

Transaction properties

These constants define the property keys used by valueForKey: and setValue:forKey:.

NSString * const kCATransactionAnimationDuration;
NSString * const kCATransactionDisableActions;
NSString * const kCATransactionAnimationTimingFunction;
NSString * const kCATransactionCompletionBlock;
Constants
kCATransactionAnimationDuration

Duration, in seconds, for animations triggered within the transaction group. The value for this key must be an instance of NSNumber.

Available in iOS 2.0 and later.

Declared in CATransaction.h.

kCATransactionDisableActions

If YES, implicit actions for property changes made within the transaction group are suppressed. The value for this key must be an instance of NSNumber.

Available in iOS 2.0 and later.

Declared in CATransaction.h.

kCATransactionAnimationTimingFunction

An instance of CAMediaTimingFunction that overrides the timing function for all animations triggered within the transaction group.

Available in iOS 3.0 and later.

Declared in CATransaction.h.

kCATransactionCompletionBlock

A completion block object that is guaranteed to be called (on the main thread) as soon as all animations subsequently added by this transaction group have completed (or have been removed.) If no animations are added before the current transaction group is committed (or the completion block is set to a different value,) the block will be invoked immediately.

Available in iOS 4.0 and later.

Declared in CATransaction.h.

Declared In
CATransaction.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-12-13)

Did this document help you? Yes It's good, but... Not helpful...