CAShapeLayer Class Reference

Inherits from
CALayer : NSObject
Conforms to
NSCoding (CALayer)
CAMediaTiming (CALayer)
NSObject (NSObject)
Framework
/System/Library/Frameworks/QuartzCore.framework
Availability
Available in OS X v10.6 and later.
Declared in
CAShapeLayer.h
Related sample code

Overview

The CAShapeLayer class draws a cubic Bezier spline in its coordinate space. The shape is composited between the layer's contents and its first sublayer.

The shape will be drawn antialiased, and whenever possible it will be mapped into screen space before being rasterized to preserve resolution independence. However, certain kinds of image processing operations, such as CoreImage filters, applied to the layer or its ancestors may force rasterization in a local coordinate space.

Tasks

Specifying the Shape Path

Accessing Shape Style Properties

Properties

fillColor

The color used to fill the shape’s path. Animatable.

@property CGColorRef fillColor
Discussion

Setting fillColor to nil results in no fill being rendered.

Default is opaque black.

Availability
  • Available in OS X v10.6 and later.
Declared In
CAShapeLayer.h

fillRule

The fill rule used when filling the shape’s path.

@property(copy) NSString *fillRule
Discussion

The possible values are shown in “Shape Fill Mode Values.” The default is kCAFillRuleNonZero. See “Winding Rules” in Cocoa Drawing Guide for examples of the two fill rules.

Availability
  • Available in OS X v10.6 and later.
Declared In
CAShapeLayer.h

lineCap

Specifies the line cap style for the shape’s path.

@property(copy) NSString *lineCap
Discussion

The line cap style specifies the shape of the endpoints of an open path when stroked. The supported values are described in “Line Cap Values.” Figure 1 shows the appearance of the available line cap styles.

Figure 1  Line cap styles

The default is kCALineCapButt.

Availability
  • Available in OS X v10.6 and later.
Declared In
CAShapeLayer.h

lineDashPattern

The dash pattern applied to the shape’s path when stroked.

@property(copy) NSArray *lineDashPattern
Discussion

The dash pattern is specified as an array of NSNumber objects that specify the lengths of the painted segments and unpainted segments, respectively, of the dash pattern.

For example, passing an array with the values [2,3] sets a dash pattern that alternates between a 2-user-space-unit-long painted segment and a 3-user-space-unit-long unpainted segment. Passing the values [1,3,4,2] sets the pattern to a 1-unit painted segment, a 3-unit unpainted segment, a 4-unit painted segment, and a 2-unit unpainted segment.

Default is nil, a solid line.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
CAShapeLayer.h

lineDashPhase

The dash phase applied to the shape’s path when stroked. Animatable.

@property CGFloat lineDashPhase
Discussion

Line dash phase specifies how far into the dash pattern the line starts.

Default is 0.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
CAShapeLayer.h

lineJoin

Specifies the line join style for the shape’s path.

@property(copy) NSString *lineJoin
Discussion

The line join style specifies the shape of the joints between connected segments of a stroked path. The supported values are described in “Line Join Values.” Figure 2 shows the appearance of the available line join styles.

Figure 2  Line join styles

The default is kCALineJoinMiter.

Availability
  • Available in OS X v10.6 and later.
Declared In
CAShapeLayer.h

lineWidth

Specifies the line width of the shape’s path. Animatable.

@property CGFloat lineWidth
Availability
  • Available in OS X v10.6 and later.
Declared In
CAShapeLayer.h

miterLimit

The miter limit used when stroking the shape’s path. Animatable.

@property CGFloat miterLimit
Discussion

If the current line join style is set to kCALineJoinMiter (see lineJoin), the miter limit determines whether the lines should be joined with a bevel instead of a miter. The length of the miter is divided by the line width. If the result is greater than the miter limit, the path is drawn with a bevel.

Default is 10.0.

Availability
  • Available in OS X v10.6 and later.
Declared In
CAShapeLayer.h

path

The path defining the shape to be rendered. Animatable.

@property CGPathRef path
Discussion

Unlike most animatable properties, path (as with all CGPathRef animatable properties) does not support implicit animation.

The path object may be animated using any of the concrete subclasses of CAPropertyAnimation. Paths will interpolate as a linear blend of the "on-line" points; "off-line" points may be interpolated non-linearly (e.g. to preserve continuity of the curve's derivative). If the two paths have a different number of control points or segments the results are undefined. If the path extends outside the layer bounds it will not automatically be clipped to the layer, only if the normal layer masking rules cause that.

If the value in this property is non-nil, the path is created using the specified path instead of the layer’s composited alpha channel. The path defines the outline of the shape layer. It is filled using the non-zero winding rule and the current color, opacity, and blur radius.

Specifying an explicit path usually improves rendering performance.

The default value of this property is NULL.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
CAShapeLayer.h

strokeColor

The color used to stroke the shape’s path. Animatable.

@property CGColorRef strokeColor
Discussion

Setting strokeColor to nil results in no stroke being rendered.

Default is nil.

Availability
  • Available in OS X v10.6 and later.
Declared In
CAShapeLayer.h

strokeEnd

The relative location at which to stop stroking the path. Animatable.

@property CGFloat strokeEnd
Discussion

The value of this property must be in the range 0.0 to 1.0. The default value of this property is 1.0.

Combined with the strokeStart property, this property defines the subregion of the path to stroke. The value in this property indicates the relative point along the path at which to finish stroking while the strokeStart property defines the starting point. A value of 0.0 represents the beginning of the path while a value of 1.0 represents the end of the path. Values in between are interpreted linearly along the path length.

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

strokeStart

The relative location at which to begin stroking the path. Animatable.

@property CGFloat strokeStart
Discussion

The value of this property must be in the range 0.0 to 1.0. The default value of this property is 0.0.

Combined with the strokeEnd property, this property defines the subregion of the path to stroke. The value in this property indicates the relative point along the path at which to begin stroking while the strokeEnd property defines the end point. A value of 0.0 represents the beginning of the path while a value of 1.0 represents the end of the path. Values in between are interpreted linearly along the path length.

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

Constants

Shape Fill Mode Values

These constants specify the possible fill modes for fillRule. 

NSString *const kCAFillRuleNonZero;
NSString *const kCAFillRuleEvenOdd;
Constants
kCAFillRuleNonZero

Specifies the non-zero winding rule. Count each left-to-right path as +1 and each right-to-left path as -1. If the sum of all crossings is 0, the point is outside the path. If the sum is nonzero, the point is inside the path and the region containing it is filled.

Available in OS X v10.6 and later.

Declared in CAShapeLayer.h.

kCAFillRuleEvenOdd

Specifies the even-odd winding rule. Count the total number of path crossings. If the number of crossings is even, the point is outside the path. If the number of crossings is odd, the point is inside the path and the region containing it should be filled.

Available in OS X v10.6 and later.

Declared in CAShapeLayer.h.

Line Join Values

These constants specify the shape of the joints between connected segments of a stroked path. Used by lineJoin. Figure 2 shows the appearance of the line join styles.

NSString *const kCALineJoinMiter;
NSString *const kCALineJoinRound;
NSString *const kCALineJoinBevel;
Constants
kCALineJoinMiter

Specifies a miter line shape of the joints between connected segments of a stroked path.

Available in OS X v10.6 and later.

Declared in CAShapeLayer.h.

kCALineJoinRound

Specifies a round line shape of the joints between connected segments of a stroked path.

Available in OS X v10.6 and later.

Declared in CAShapeLayer.h.

kCALineJoinBevel

Specifies a bevel line shape of the joints between connected segments of a stroked path.

Available in OS X v10.6 and later.

Declared in CAShapeLayer.h.

Line Cap Values

These constants specify the shape of endpoints for an open path when stroked. Used by lineCap. Figure 1 shows the appearance of the line cap styles.

NSString *const kCALineCapButt;
NSString *const kCALineCapRound;
NSString *const kCALineCapSquare;
Constants
kCALineCapButt

Specifies a butt line cap style for endpoints for an open path when stroked.

Available in OS X v10.6 and later.

Declared in CAShapeLayer.h.

kCALineCapRound

Specifies a round line cap style for endpoints for an open path when stroked.

Available in OS X v10.6 and later.

Declared in CAShapeLayer.h.

kCALineCapSquare

Specifies a square line cap style for endpoints for an open path when stroked.

Available in OS X v10.6 and later.

Declared in CAShapeLayer.h.



© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-01-11)

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