Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

CALayer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/QuartzCore.framework
Availability
Available in Mac OS X v10.5 and later.
Declared in
CAConstraintLayoutManager.h
CALayer.h
CAScrollLayer.h
CATransform3D.h
Companion guides

Overview

CALayer is the model class for layer-tree objects. It encapsulates the position, size, and transform of a layer, which defines a its coordinate system. It also encapsulates the duration and pacing of a layer and its animations by adopting the CAMediaTiming protocol, which defines a layer’s time space.

Tasks

Creating a Layer

Accessing the Presentation Layer

Modifying the Layer Geometry

Providing Layer Content

Style Attributes

Managing the Layer Hierarchy

Updating Layer Display

Layer Animations

Managing Layer Resizing and Layout

Actions

Mapping Between Coordinate and Time Spaces

Hit Testing

Rendering

Scrolling

Modifying the Delegate

Key-Value Coding Extensions

Properties

For more about Objective-C properties, see “Properties” in The Objective-C 2.0 Programming Language.

actions

A dictionary mapping keys to objects that implement the CAAction protocol.

@property(copy) NSDictionary *actions

Discussion

The default value is nil. See actionForKey: for a description of the action search pattern.

Availability
See Also
Declared In
CALayer.h

anchorPoint

Defines the anchor point of the layer's bounds rectangle. Animatable.

@property CGPoint anchorPoint

Discussion

Described in the unit coordinate space. The bottom left corner of the bounds rectangle is (0.0,0.0), the top right corner is (1.0,1.0). Defaults to (0.5, 0.5), the center of the bounds rectangle.

Availability
See Also
Declared In
CALayer.h

autoresizingMask

A bitmask defining how the layer is resized when the bounds of its superlayer changes.

@property unsigned int autoresizingMask

Discussion

See “Autoresizing Mask” for possible values. Default value is kCALayerNotSizable.

Availability
Declared In
CALayer.h

backgroundColor

Specifies the background color of the receiver. Animatable.

@property CGColorRef backgroundColor

Discussion

The default is nil.

Availability
Declared In
CALayer.h

backgroundFilters

An optional array of CoreImage filters that are applied to the receiver’s background. Animatable.

@property(copy) NSArray *backgroundFilters

Discussion

Once an array of filters is set properties should be modified by invoking setValue:forKeyPath: using the appropriate key path. This requires that you set the name of the background filter to be modified. For example: 

CIFilter *filter = ...;
CALayer *layer = ...;
 
filter.name = @"myFilter";
layer.filters = [NSArray arrayWithObject:filter];
[layer setValue:[NSNumber numberWithInt:1] forKeyPath:@"filters.myFilter.inputScale"];

If the inputs of a background filter are directly modified after the filter is attached to a layer, the behavior is undefined.

Availability
Declared In
CALayer.h

borderColor

The color of the receiver’s border. Animatable.

@property CGColorRef borderColor

Discussion

Defaults to opaque black.

Availability
Declared In
CALayer.h

borderWidth

Specifies the width of the receiver’s border. Animatable.

@property CGFloat borderWidth

Discussion

The border is drawn inset from the receiver’s bounds by borderWidth. It is composited above the receiver’s contents and sublayers and includes the effects of the cornerRadius property. The default is 0.0.

Availability
Declared In
CALayer.h

bounds

Specifies the bounds rectangle of the receiver. Animatable.

@property CGRect bounds

Discussion

The default is an empty rectangle.

Availability
Declared In
CALayer.h

compositingFilter

A CoreImage filter used to composite the receiver’s contents with the background. Animatable.

@property(retain) CIFilter *compositingFilter

Discussion

If nil, the contents are composited using source-over. The default value is nil.

Once a filter is set its properties should be modified by invoking setValue:forKeyPath: using the appropriate key path. For example: 

CIFilter *filter = ...;
CALayer *layer = ...;
 
layer.compositingFilter = filter;
[layer setValue:[NSNumber numberWithInt:1] forKeyPath:@"compositingFilter.inputScale"];

If the inputs of the filter are modified directly after the filter is attached to a layer, the behavior is undefined.

Availability
See Also
Declared In
CALayer.h

constraints

Specifies the constraints used to layout the receiver’s sublayers when using an CAConstraintManager instance as the layout manager.

@property NSArray *constraints

Discussion

See CAConstraintLayoutManager Class Reference for more information.

Availability
Declared In
CAConstraintLayoutManager.h

contents

An object that provides the contents of the layer. Animatable.

@property(retain) id contents

Discussion

A layer can set this property to a CGImageRef to display the image as its contents. The default value is nil.

Availability
See Also
Declared In
CALayer.h

contentsGravity

Determines how the receiver's contents are positioned within its bounds.

@property(copy) NSString *contentsGravity

Discussion

The possible values for contentsGravity are shown in “Contents Gravity Values”. The default value is kCAGravityResize.

Availability
Declared In
CALayer.h

contentsRect

A rectangle, in the unit coordinate space, defining the subrectangle of contents that the receiver should draw. Animatable.

@property CGRect contentsRect

Discussion

Defaults to the unit rectangle (0.0,0.0,1.0,1.0).

If pixels outside the unit rectangles are requested, the edge pixels of the contents image will be extended outwards.

If an empty rectangle is provided, the results are undefined.

Availability
See Also
Declared In
CALayer.h

cornerRadius

Specifies a radius used to draw the rounded corners of the receiver’s background. Animatable. 

@property CGFloat cornerRadius

Discussion

If the radius is greater than 0 the background is drawn with rounded corners. The default value is 0.0.

Availability
Declared In
CALayer.h

delegate

Specifies the receiver’s delegate object.

@property(assign) id delegate

Availability
Declared In
CALayer.h

doubleSided

Determines whether the receiver is displayed when facing away from the viewer. Animatable.

@property BOOL doubleSided

Discussion

If NO, the layer is hidden when facing away from the viewer. Defaults to YES.

Availability
See Also
Declared In
CALayer.h

edgeAntialiasingMask

A bitmask defining how the edges of the receiver are rasterized.

@property unsigned int edgeAntialiasingMask

Discussion

For each of the four edges (left, right, bottom, top) if the corresponding bit is set the edge will be antialiased.

Typically, this property is used to disable antialiasing for edges that abut edges of other layers, to eliminate the seams that would otherwise occur.

The mask values are defined in “Edge Antialiasing Mask.”

Availability
Declared In
CALayer.h

filters

An array of CoreImage filters that are applied to the contents of the receiver and its sublayers. Animatable.

@property(copy) NSArray *filters

Discussion

Defaults to nil. Filter properties should be modified by calling setValue:forKeyPath: on each layer that the filter is attached to. If the inputs of the filter are modified directly after the filter is attached to a layer, the behavior is undefined.

Availability
Declared In
CALayer.h

frame

Specifies receiver’s frame rectangle in the super-layer’s coordinate space. Animatable.

@property CGRect frame

Discussion

The frame is a function of the bounds, anchorPoint and position properties. When the frame is set, the receiver’s position and the size of the receiver’s bounds are changed to match the new frame rectangle.

Availability
Declared In
CALayer.h

hidden

Determines whether the receiver is displayed. Animatable.

@property BOOL hidden

Discussion

The default is NO.

Availability
See Also
Declared In
CALayer.h

layoutManager

Specifies the layout manager responsible for laying out the receiver’s sublayers.

@property(retain) id layoutManager

Discussion

The layoutManager must implement the CALayoutManager informal protocol. The default value is nil.

Availability
Declared In
CALayer.h

magnificationFilter

The filter used when increasing the size of the content.

@property(copy) NSString *magnificationFilter

Discussion

The possible values for magnificationFilter are shown in “Scaling Filters”. The default value is kCAFilterLinear.

Availability
Declared In
CALayer.h

mask

An optional layer whose alpha channel is used as a mask to select between the layer's background and the result of compositing the layer's contents with its filtered background. 

@property(retain) CALayer *mask

Discussion

Defaults to nil.

Special Considerations

When setting the mask to a new layer, the new layer’s superlayer must first be set to nil, otherwise the behavior is undefined.

Availability
Declared In
CALayer.h

masksToBounds

Determines if the sublayers are clipped to the receiver’s bounds. Animatable.

@property BOOL masksToBounds

Discussion

If YES, an implicit mask matching the layer bounds is applied to the layer, including the effects of the cornerRadius property. If YES and a mask property is specified, the two masks are multiplied to get the actual mask values. Defaults to NO.

Availability
Declared In
CALayer.h

minificationFilter

The filter used when reducing the size of the content.

@property(copy) NSString *minificationFilter

Discussion

The possible values for minifcationFilter are shown in “Scaling Filters”. The default value is kCAFilterLinear.

Availability
Declared In
CALayer.h

name

The name of the receiver.

@property(copy) NSString *name

Discussion

The layer name is used by some layout managers to identify a layer. Defaults to nil.

Availability
Declared In
CALayer.h

needsDisplayOnBoundsChange

Returns whether the receiver must be redisplayed when the bounds rectangle is updated.

@property BOOL needsDisplayOnBoundsChange

Discussion

When YES, setNeedsDisplay is automatically invoked when the receiver’s bounds is changed. Default value is NO.

Availability
Declared In
CALayer.h

opacity

Determines the opacity of the receiver. Animatable.

@property float opacity

Discussion

Possible values are between 0.0 (transparent) and 1.0 (opaque). The default is 1.0.

Availability
Declared In
CALayer.h

opaque

Specifies a hint marking that the pixel data provided by the contents property is completely opaque.

@property BOOL opaque

Discussion

Defaults to NO.

Availability
See Also
Declared In
CALayer.h

position

Specifies the receiver’s position in the superlayer’s coordinate system. Animatable.

@property CGPoint position

Discussion

The position is relative to anchorPoint. The default is (0.0,0.0).

Availability
See Also
Declared In
CALayer.h

shadowColor

Specifies the color of the receiver’s shadow. Animatable.

@property CGColorRef shadowColor

Discussion

The default is opaque black.

Availability
Declared In
CALayer.h

shadowOffset

Specifies the offset of the receiver’s shadow. Animatable.

@property CGSize shadowOffset

Discussion

The default is (0.0,-3.0).

Availability
Declared In
CALayer.h

shadowOpacity

Specifies the opacity of the receiver’s shadow. Animatable.

@property float shadowOpacity

Discussion

The default is 0.0.

Availability
Declared In
CALayer.h

shadowRadius

Specifies the blur radius used to render the receiver’s shadow. Animatable.

@property CGFloat shadowRadius

Discussion

The default value is 3.0.

Availability
Declared In
CALayer.h

style

An optional dictionary referenced to find property values that aren't explicitly defined by the receiver.

@property(copy) NSDictionary *style

Discussion

This dictionary may in turn have a style key, forming a hierarchy of default values. In the case of hierarchical style dictionaries the shallowest value for a property is used. For example, the value for “style.someValue” takes precedence over “style.style.someValue”.

If the style dictionary doesn't define a value for an attribute, the receiver’s defaultValueForKey: method is called. Defaults to nil.

The style dictionary is not consulted for the following keys: bounds, frame.

!

Warning: If the style dictionary or any of its ancestors are modified, the values of the layer's properties are undefined until the style property is reset.

Availability
Declared In
CALayer.h

sublayers

An array containing the receiver's sublayers.

@property(copy) NSArray *sublayers

Discussion

The layers are listed in back to front order. Defaults to nil.

Special Considerations

When setting the sublayers property to an array populated with layer objects you must ensure that the layers have had their superlayer set to nil.

Availability
Declared In
CALayer.h

sublayerTransform

Specifies a transform applied to each sublayer when rendering. Animatable.

@property CATransform3D sublayerTransform

Discussion

This property is typically used as the projection matrix to add perspective and other viewing effects to the receiver. Defaults to the identity transform.

Availability
Declared In
CALayer.h

superlayer

Specifies receiver's superlayer.

@property(readonly) CALayer *superlayer

Availability
Declared In
CALayer.h

transform

Specifies the transform applied to the receiver, relative to the center of its bounds. Animatable.

@property CATransform3D transform

Discussion

Defaults to the identity transform.

Availability
Declared In
CALayer.h

visibleRect

Returns the visible region of the receiver, in its own coordinate space.

@property(readonly) CGRect visibleRect

Discussion

The visible region is the area not clipped by the containing scroll layer.

Availability
Declared In
CAScrollLayer.h

zPosition

Specifies the receiver’s position on the z axis. Animatable.

@property CGFloat zPosition

Discussion

Defaults to 0.

Availability
Declared In
CALayer.h

Class Methods

defaultActionForKey:

Returns an object that implements the default action for the specified identifier.

+ (id<CAAction>)defaultActionForKey:(NSString *)aKey

Parameters
aKey

The identifier of the action.

Return Value

Returns the object that provides the action for aKey. The object must implement the CAAction protocol.

Discussion

See actionForKey: for a description of the action search pattern.

Availability
See Also
Declared In
CALayer.h

defaultValueForKey:

Specifies the default value of the property with the specified key.

+ (id)defaultValueForKey:(NSString *)key

Parameters
key

The name of one of the receiver’s properties.

Return Value

The default value for the named property. Returns nil if no default value has been set.

Discussion

If this method returns nil a suitable “zero” default value for the property is provided, based on the declared type of the key. For example, if key is a CGSize object, a size of (0.0,0.0) is returned. For a CGRect an empty rectangle is returned. For CGAffineTransform and CATransform3D, the appropriate identity matrix is returned.

Special Considerations

If key is not a known for property of the class, the result of the method is undefined.

Availability
Declared In
CALayer.h

layer

Creates and returns an instance of CALayer.

+ (id)layer

Return Value

The initialized CALayer object or nil if initialization is not successful.

Availability
Declared In
CALayer.h

Instance Methods

actionForKey:

Returns an object that implements the action for the specified identifier.

- (id<CAAction>)actionForKey:(NSString *)aKey

Parameters
aKey

The identifier of the action.

Return Value

Returns the object that provides the action for aKey. The object must implement the CAAction protocol.

Discussion

There are three types of actions: property changes, externally-defined events, and layer-defined events. Whenever a layer property is modified, the event with the same name as the property is triggered. External events are defined by the owner of the layer calling actionForKey: to lookup the action associated with the identifier and directly messaging the returned object (if non-nil.)

The default implementation searches for an action object as follows:

If any of these steps results in a non-nil action object, the remaining steps are ignored and the action is returned. If a step returns an NSNull object, the remaining steps are ignored and nil is returned.

When an action object is invoked it receives three parameters: the name of the event, the object on which the event happened (the layer), and a dictionary of named arguments specific to each event kind.

Availability
See Also
Declared In
CALayer.h

addAnimation:forKey:

Add an animation object to the receiver’s render tree for the specified key.

- (void)addAnimation:(CAAnimation *)anim forKey:(NSString *)key

Parameters
anim

The animation to be added to the render tree. Note that the object is copied by the render tree, not referenced. Any subsequent modifications to the object will not be propagated into the render tree.

key

A string that specifies an identifier for the animation. Only one animation per unique key is added to the layer. The special key kCATransition is automatically used for transition animations. The nil pointer is also a valid key.

Discussion

Typically this is implicitly invoked through an action that is an CAAnimation object. If the duration property of the animation is zero or negative it is given the default duration, either the current value of the kCATransactionAnimationDuration transaction property, otherwise .25 seconds

Availability
Declared In
CALayer.h

addConstraint:

Adds the constraint to the receiver's array of constraint objects.

- (void)addConstraint:(CAConstraint *)aConstraint

Parameters
aConstraint

The constraint object to add to the receiver’s array of constraint objects.

Discussion

See CAConstraintLayoutManager Class Reference for more information.

Availability
Declared In
CAConstraintLayoutManager.h

addSublayer:

Appends the layer to the receiver’s sublayers array.

- (void)addSublayer:(CALayer *)aLayer

Parameters
aLayer

The layer to be added to the receiver’s sublayers array.

Availability
Declared In
CALayer.h