---

CATransaction Class Reference

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.

In some circumstances (for example, if there is no run-loop, or the run-loop is blocked) it may be necessary to use explicit transactions to get timely render tree updates.

Tasks

Creating and Committing Transactions

• + begin
• + commit
• + flush

Getting and Setting Transaction Properties

• + valueForKey:
• + setValue:forKey:

Class Methods

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 Mac OS X v10.5 and later.

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 Mac OS X v10.5 and later.

Declared In

CATransaction.h

flush

Flushes any extant implicit transaction.

+ (void)flush

Discussion

Delays the commit until any nested explicit transactions have completed.

Availability

• Available in Mac OS X v10.5 and later.

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 Mac OS X v10.5 and later.

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 Mac OS X v10.5 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;

Constants

kCATransactionAnimationDuration

Default duration, in seconds, for animations added to layers. The value for this key must be an instance of NSNumber.

Available in Mac OS X v10.5 and later.

Declared in CATransaction.h.

kCATransactionDisableActions

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

Available in Mac OS X v10.5 and later.

Declared in CATransaction.h.

Declared In

CATransaction.h

---