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

Next Page > Hide TOC

NSBezierPath Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSBezierPath.h

Overview

An NSBezierPath object allows you to create paths using PostScript-style commands. Paths consist of straight and curved line segments joined together. Paths can form recognizable shapes such as rectangles, ovals, arcs, and glyphs; they can also form complex polygons using either straight or curved line segments. A single path can be closed by connecting its two endpoints, or it can be left open.

An NSBezierPath object can contain multiple disconnected paths, whether they are closed or open. Each of these paths is referred to as a subpath. The subpaths of an NSBezierPath object must be manipulated as a group. The only way to manipulate subpaths individually is to create separate NSBezierPath objects for each.

For a given NSBezierPath object, you can stroke the path’s outline or fill the region occupied by the path. You can also use the path as a clipping region for views or other regions. Using methods of NSBezierPath, you can also perform hit detection on the filled or stroked path. Hit detection is needed to implement interactive graphics, as in rubberbanding and dragging operations.

The current graphics context is automatically saved and restored for all drawing operations involving NSBezierPath objects, so your application does not need to worry about the graphics settings changing across invocations.

Adopted Protocols

NSCoding
NSCopying

Tasks

Creating an NSBezierPath Object

Constructing Paths

Appending Common Shapes to a Path

Accessing Path Attributes

Drawing Paths

Clipping Paths

Hit Detection

Querying Paths

Applying Transformations

Accessing Elements of a Path

Caching Paths

Class Methods

bezierPath

Creates and returns a new NSBezierPath object.

+ (NSBezierPath *)bezierPath

Return Value

A new empty path object.

Availability
Declared In
NSBezierPath.h

bezierPathWithOvalInRect:

Creates and returns a new NSBezierPath object initialized with an oval path inscribed in the specified rectangle.

+ (NSBezierPath *)bezierPathWithOvalInRect:(NSRect)aRect

Parameters
aRect

The rectangle in which to inscribe an oval.

Return Value

ANSBezierPath new path object with the oval path.

Discussion

If the aRect parameter specifies a square, the inscribed path is a circle. The path is constructed by starting in the lower-right quadrant of the rectangle and adding arc segments counterclockwise to complete the oval.

Availability
See Also
Declared In
NSBezierPath.h

bezierPathWithRect:

Creates and returns a new NSBezierPath object initialized with a rectangular path.

+ (NSBezierPath *)bezierPathWithRect:(NSRect)aRect

Parameters
aRect

The rectangle describing the path to create.

Return Value

A new path object with the rectangular path.

Discussion

The path is constructed by starting at the origin of aRect and adding line segments in a counterclockwise direction.

Availability
See Also
Declared In
NSBezierPath.h

bezierPathWithRoundedRect:xRadius:yRadius:

Creates and returns a new NSBezierPath object initialized with a rounded rectangular path.

+ (NSBezierPath *)bezierPathWithRoundedRect:(NSRect)rect xRadius:(CGFloat)xRadius yRadius:(CGFloat)yRadius

Parameters
rect

The rectangle that defines the basic shape of the path.

xRadius

The radius of each corner oval along the x-axis. Values larger than half the rectangle’s width are clamped to half the width.

yRadius

The radius of each corner oval along the y-axis. Values larger than half the rectangle’s height are clamped to half the height.

Return Value

A new path object with the rounded rectangular path.

Discussion

The path is constructed in a counter-clockwise direction, starting at the top-left corner of the rectangle. If either one of the radius parameters contains the value 0.0, the returned path is a plain rectangle without rounded corners.

Availability
See Also
Declared In
NSBezierPath.h

clipRect:

Intersects the specified rectangle with the clipping path of the current graphics context and makes the resulting shape the current clipping path

+ (void)clipRect:(NSRect)aRect

Parameters
aRect

The rectangle to intersect with the current clipping path.

Availability
See Also
Declared In
NSBezierPath.h

defaultFlatness

Returns the default flatness value for all paths.

+ (CGFloat)defaultFlatness

Return Value

The default value for determining the smoothness of curved paths, or 0.6 if no other value has been set.

Availability
See Also
Declared In
NSBezierPath.h

defaultLineCapStyle

Returns the default line cap style for all paths.

+ (NSLineCapStyle)defaultLineCapStyle

Return Value

The default line cap style or NSButtLineCapStyle if no other style has been set. For a list of values, see “Constants.”

Discussion

The default line cap style can be overridden for individual paths by setting a custom style for that path using the setLineCapStyle: method.

Availability
See Also
Declared In
NSBezierPath.h

defaultLineJoinStyle

Returns the default line join style for all paths.

+ (NSLineJoinStyle)defaultLineJoinStyle

Return Value

The default line join style or NSMiterLineJoinStyle if no other value has been set. For a list of values, see “Constants.”

Availability
See Also
Declared In
NSBezierPath.h

defaultLineWidth

Returns the default line width for the all paths.

+ (CGFloat)defaultLineWidth

Return Value

The default line width, measured in points in the user coordinate space, or 1.0 if no other value has been set.

Availability
See Also
Declared In
NSBezierPath.h

defaultMiterLimit

Returns the default miter limit for all paths.

+ (CGFloat)defaultMiterLimit

Return Value

The default miter limit for all paths, or 10.0 if no other value has been set.

Availability
See Also
Declared In
NSBezierPath.h

defaultWindingRule

Returns the default winding rule used to fill all paths.

+ (NSWindingRule)defaultWindingRule

Return Value

The current default winding rule or NSNonZeroWindingRule if no default rule has been set. This value may be either NSNonZeroWindingRule or NSEvenOddWindingRule.

Availability
See Also
Declared In
NSBezierPath.h

drawPackedGlyphs:atPoint:

Draws a set of packed glyphs at the specified point in the current coordinate system.

+ (void)drawPackedGlyphs:(const char *)packedGlyphs atPoint:(NSPoint)aPoint

Parameters
packedGlyphs

A C-style array containing one or more CGGlyph data types terminated by a NULL character.

aPoint

The starting point at which to draw the glyphs.

Discussion

This method draws the glyphs immediately.

You should avoid using this method directly. Instead, use the appendBezierPathWithGlyph:inFont: and appendBezierPathWithGlyphs:count:inFont: methods to create a path with one or more glyphs.

Availability
See Also
Declared In
NSBezierPath.h

fillRect:

Fills the specified rectangular path with the current fill color.

+ (void)fillRect:(NSRect)aRect

Parameters
aRect

A rectangle in the current coordinate system.

Discussion

This method fills the specified region immediately. This method uses the compositing operation returned by the compositingOperation method of NSGraphicsContext.

Availability
See Also
Declared In
NSBezierPath.h

setDefaultFlatness:

Sets the default flatness value for all paths.

+ (void)setDefaultFlatness:(CGFloat)flatness

Parameters
flatness

The default flatness value.

Discussion

The flatness value specifies the accuracy (or smoothness) with which curves are rendered. It is also the maximum error tolerance (measured in pixels) for rendering curves, where smaller numbers give smoother curves at the expense of more computation. The exact interpretation may vary slightly on different rendering devices.

The default flatness value is 0.6, which yields smooth curves.

Availability
See Also
Declared In
NSBezierPath.h

setDefaultLineCapStyle:

Sets the default line cap style for all paths.

+ (void)setDefaultLineCapStyle:(NSLineCapStyle)lineCap

Parameters
lineCap

The default line cap style. For a list of values, see “Constants.”

Discussion

The line cap style specifies the shape of the endpoints of an open path when stroked. Figure 1 shows the appearance of the available line cap styles.


Figure 1  Line cap styles

Line cap styles

Availability
See Also
Declared In
NSBezierPath.h

setDefaultLineJoinStyle:

Sets the default line join style for all paths.

+ (void)setDefaultLineJoinStyle:(NSLineJoinStyle)lineJoinStyle

Parameters
lineJoinStyle

The default line join style. For a list of values, see “Constants.”

Discussion

The line join style specifies the shape of the joints between connected segments of a stroked path. Figure 2 shows the appearance of the available line join styles.


Figure 2  Line join styles

Line join styles

Availability
See Also
Declared In
NSBezierPath.h

setDefaultLineWidth:

Sets the default line width for all paths.

+ (void)setDefaultLineWidth:(CGFloat)width

Parameters
width

The default line width, measured in points in the user coordinate space.

Discussion

The line width defines the thickness of stroked paths. A width of 0 is interpreted as the thinnest line that can be rendered on a particular device. The actual rendered line width may vary from the specified width by as much as 2 device pixels, depending on the position of the line with respect to the pixel grid and the current anti-aliasing settings. The width of the line may also be affected by scaling factors specified in the current transformation matrix of the active graphics context.

Availability
See Also
Declared In
NSBezierPath.h

setDefaultMiterLimit:

Sets the default miter limit for all paths.

+ (void)setDefaultMiterLimit:(CGFloat)limit

Parameters
limit

The default limit at which miter joins are converted to bevel joins.

Discussion

The miter limit helps you avoid spikes at the junction of two line segments connected by a miter join (NSMiterLineJoinStyle). If the ratio of the miter length—the diagonal length of the miter join—to the line thickness exceeds the miter limit, the joint is converted to a bevel join. The default miter limit value is 10, which converts miters whose angle at the joint is less than 11 degrees.

Availability
See Also
Declared In
NSBezierPath.h

setDefaultWindingRule:

Sets the default winding rule used to fill all paths.

+ (void)setDefaultWindingRule:(NSWindingRule)windingRule

Parameters
windingRule

The winding rule to use if no winding rule is set explicitly for a path object. This value may be either NSNonZeroWindingRule or NSEvenOddWindingRule.

Discussion

Winding rules determine how to paint (or fill) the region enclosed by a path. You use this method to set the default rule that is applied to paths that do not have a custom winding rule assigned.

For more information on how winding rules affect the appearance of filled paths, see “Winding Rules and Filling Paths”.

Availability
See Also
Declared In
NSBezierPath.h

strokeLineFromPoint:toPoint:

Strokes a line between two points using the current stroke color and the default drawing attributes.

+ (void)strokeLineFromPoint:(NSPoint)point1 toPoint:(NSPoint)point2

Parameters
point1

The starting point of the line.

point2

The ending point of the line.

Discussion

This method strokes the specified path immediately.

Availability
See Also
Declared In
NSBezierPath.h

strokeRect:

Strokes the path of the specified rectangle using the current stroke color and the default drawing attributes.

+ (void)strokeRect:(NSRect)aRect

Parameters
aRect

A rectangle in the current coordinate system.

Discussion

The path is drawn beginning at the rectangle’s origin and proceeding in a counterclockwise direction. This method strokes the specified path immediately.

Availability
See Also
Declared In
NSBezierPath.h

Instance Methods

addClip

Intersects the area enclosed by the receiver's path with the clipping path of the current graphics context and makes the resulting shape the current clipping path.

- (void)addClip

Discussion

This method uses the current winding rule to determine the clipping shape of the receiver. This method does not affect the receiver’s path.

Availability
See Also
Declared In
NSBezierPath.h

appendBezierPath:

Appends the contents of the specified path object to the receiver’s path.

- (void)appendBezierPath:(NSBezierPath *)aPath

Parameters
aPath

The path to add to the receiver.

Discussion

This method adds the commands used to create aPath to the end of the receiver’s path. This method does not explicitly try to connect the subpaths in the two objects, although the operations in aPath may still cause that effect.

Availability
Declared In
NSBezierPath.h

appendBezierPathWithArcFromPoint:toPoint:radius:

Appends an arc to the receiver’s path.

- (void)appendBezierPathWithArcFromPoint:(NSPoint)fromPoint toPoint:(NSPoint)toPoint radius:(CGFloat)radius

Parameters
fromPoint

The middle point of the angle.

toPoint

The end point of the angle.

radius

The radius of the circle inscribed in the angle.

Discussion

The created arc is defined by a circle inscribed inside the angle specified by three points: the current point, the fromPoint parameter, and the toPoint parameter (in that order). The arc itself lies on the perimeter of the circle, whose radius is specified by the radius parameter. The arc is drawn between the two points of the circle that are tangent to the two legs of the angle.

The arc usually does not contain the points in the fromPoint and toPoint parameters. If the starting point of the arc does not coincide with the current point, a line is drawn between the two points. The starting point of the arc lies on the line defined by the current point and the fromPoint parameter.

You must set the path's current point (using the moveToPoint: method or through the creation of a preceding line or curve segment) before you invoke this method. If the path is empty, this method raises an NSGenericException exception.

Depending on the length of the arc, this method may add multiple connected curve segments to the path.

Availability
Declared In
NSBezierPath.h

appendBezierPathWithArcWithCenter:radius:startAngle:endAngle:

Appends an arc of a circle to the receiver’s path.

- (void)appendBezierPathWithArcWithCenter:(NSPoint)center radius:(CGFloat)radius startAngle:(CGFloat)startAngle endAngle:(CGFloat)endAngle

Parameters
center

Specifies the center point of the circle used to define the arc.

radius

Specifies the radius of the circle used to define the arc.

startAngle

Specifies the starting angle of the arc, measured in degrees counterclockwise from the x-axis.

endAngle

Specifies the end angle of the arc, measured in degrees counterclockwise from the x-axis.

Discussion

The created arc lies on the perimeter of the circle, between the angles specified by the startAngle and endAngle parameters. The arc is drawn in a counterclockwise direction. If the receiver's path is empty, this method sets the current point to the beginning of the arc before adding the arc segment. If the receiver's path is not empty, a line is drawn from the current point to the starting point of the arc.

Depending on the length of the arc, this method may add multiple connected curve segments to the path.

Availability
Declared In
NSBezierPath.h

appendBezierPathWithArcWithCenter:radius:startAngle:endAngle:clockwise:

Appends an arc of a circle to the receiver’s path.

- (void)appendBezierPathWithArcWithCenter:(NSPoint)center radius:(CGFloat)radius startAngle:(CGFloat)startAngle endAngle:(CGFloat)endAngle clockwise:(BOOL)clockwise

Parameters
center

Specifies the center point of the circle used to define the arc.

radius

Specifies the radius of the circle used to define the arc.

startAngle

Specifies the starting angle of the arc, measured in degrees counterclockwise from the x-axis.

endAngle

Specifies the end angle of the arc, measured in degrees counterclockwise from the x-axis.

clockwise

YES if you want the arc to be drawn in a clockwise direction; otherwise NO to draw the arc in a counterclockwise direction.

Discussion

The created arc lies on the perimeter of the circle, between the angles specified by the startAngle and endAngle parameters. The arc is drawn in the direction indicated by the clockwise parameter. If the receiver's path is empty, this method sets the current point to the beginning of the arc before adding the arc segment. If the receiver's path is not empty, a line is drawn from the current point to the starting point of the arc.

Depending on the length of the arc, this method may add multiple connected curve segments to the path.

Availability
Declared In
NSBezierPath.h

appendBezierPathWithGlyph:inFont:

Appends an outline of the specified glyph to the receiver’s path.

- (void)appendBezierPathWithGlyph:(NSGlyph)aGlyph inFont:(NSFont *)fontObj

Parameters
aGlyph

The glyph to add to the path.

fontObj

The font in which the glyph is encoded.

Discussion

If the glyph is not encoded in the font specified by the fontObj parameter—that is, the font does not have an entry for the specified glyph—then no path is appended to the receiver.

You must set the path's current point (using the moveToPoint: method or through the creation of a preceding line or curve segment) before you invoke this method. If the path is empty, this method raises an NSGenericException exception.

Availability
See Also
Declared In
NSBezierPath.h

appendBezierPathWithGlyphs:count:inFont:

Appends the outlines of the specified glyphs to the receiver’s path.

- (void)appendBezierPathWithGlyphs:(NSGlyph *)glyphs count:(NSInteger)count inFont:(NSFont *)fontObj

Parameters
glyphs

A C-style array of NSGlyph data types to add to the path.

count

The number of glyphs in the glyphs parameter.

fontObj

The font in which the glyphs are encoded.

Discussion

If the glyphs are not encoded in the font specified by the fontObj parameter—that is, the font does not have an entry for one of the specified glyphs—then no path is appended to the receiver.

You must set the path's current point (using the moveToPoint: method or through the creation of a preceding line or curve segment) before you invoke this method. If the path is empty, this method raises an NSGenericException exception.

Availability
See Also
Declared In
NSBezierPath.h

appendBezierPathWithOvalInRect:

Appends an oval path to the receiver, inscribing the oval in the specified rectangle.

- (void)appendBezierPathWithOvalInRect:(NSRect)aRect

Parameters
aRect

The rectangle in which to inscribe the oval.

Discussion

Before adding the oval, this method moves the current point, which implicitly closes the current subpath. If the aRect parameter specifies a square, the inscribed path is a circle. The path is constructed by starting in the lower-right quadrant of the rectangle and adding arc segments counterclockwise to complete the oval.

Availability
Declared In
NSBezierPath.h

appendBezierPathWithPackedGlyphs:

Appends an array of packed glyphs to the receiver’s path.

- (void)appendBezierPathWithPackedGlyphs:(const char *)packedGlyphs

Parameters
packedGlyphs

A C-style array containing one or more CGGlyph data types terminated by a NULL character.

Discussion

You should avoid using this method directly. Instead, use the appendBezierPathWithGlyph:inFont: and appendBezierPathWithGlyphs:count:inFont: methods to append glyphs to a path.

Availability
See Also
Declared In
NSBezierPath.h

appendBezierPathWithPoints:count:

Appends a series of line segments to the receiver’s path.

- (void)appendBezierPathWithPoints:(NSPointArray)points count:(NSInteger)count

Parameters
points

A C-style array of NSPoint data types, each of which contains the end point of the next line segment.

count

The number of points in the points parameter.

Discussion

This method interprets the points as a set of connected line segments. If the current path contains an open subpath, a line is created from the last point in that subpath to the first point in the points array. If the current path is empty, the first point in the points array is used to set the starting point of the line segments. Subsequent line segments are added using the remaining points in the array.

This method does not close the path that is created. If you wish to create a closed path, you must do so by explicitly invoking the receiver’s closePath method.

Availability
Declared In
NSBezierPath.h

appendBezierPathWithRect:

Appends a rectangular path to the receiver’s path.

- (void)appendBezierPathWithRect:(NSRect)aRect

Parameters
aRect

The rectangle describing the path to create.

Discussion

Before adding the rectangle, this method moves the current point to the origin of the rectangle, which implicitly closes the current subpath (if any). The path is constructed by starting at the origin of aRect and adding line segments in a counterclockwise direction. The final segment is added using a closePath message.

Availability
See Also
Declared In
NSBezierPath.h

appendBezierPathWithRoundedRect:xRadius:yRadius:

Appends a rounded rectangular path to the receiver’s path.

- (void)appendBezierPathWithRoundedRect:(NSRect)rect xRadius:(CGFloat)xRadius yRadius:(CGFloat)yRadius

Parameters
rect

The rectangle that defines the basic shape of the path.

xRadius

The radius of each corner oval along the x-axis. Values larger than half the rectangle’s width are clamped to half the width.

yRadius

The radius of each corner oval along the y-axis. Values larger than half the rectangle’s height are clamped to half the height.

Discussion

The path is constructed in a counter-clockwise direction, starting at the top-left corner of the rectangle. If either one of the radius parameters contains the value 0.0, the returned path is a plain rectangle without rounded corners.

Availability
See Also
Declared In
NSBezierPath.h

bezierPathByFlatteningPath

Creates and returns a “flattened” copy of the receiver.

- (NSBezierPath *)bezierPathByFlatteningPath

Return Value

A new path object whose contents are a flattened version of the receiver's path.

Discussion

Flattening a path converts all curved line segments into straight line approximations. The granularity of the approximations is controlled by the path's current flatness value, which is set using the setDefaultFlatness: method.

Availability
Declared In
NSBezierPath.h

bezierPathByReversingPath

Creates and returns a new NSBezierPath object with the reversed contents of the receiver’s path.

- (NSBezierPath *)bezierPathByReversingPath

Return Value

A new path object whose contents are a reversed version of the receiver's path.

Discussion

Reversing a path does not necessarily change the appearance of the path when rendered. Instead, it changes the direction in which path segments are drawn. For example, reversing the path of a rectangle (whose line segments are normally drawn starting at the origin and proceeding in a counterclockwise direction) causes its line segments to be drawn in a clockwise direction instead. Drawing a reversed path could affect the appearance of a filled pattern, depending on the pattern and the fill rule in use.

This method reverses each whole or partial subpath in the path object individually.

Availability
Declared In
NSBezierPath.h

bounds

Returns the bounding box of the receiver’s path.

- (NSRect)bounds

Return Value

The rectangle that encloses the path of the receiver. If the path contains curve segments, the bounding box encloses the curve but may not enclose the control points used to calculate the curve.

Availability
See Also
Declared In
NSBezierPath.h

cachesBezierPath

Returns a Boolean value indicating whether this object maintains a cached image of its path.

- (BOOL)cachesBezierPath

Return Value

YES if the path maintains a cached image; otherwise, NO.

Discussion

Caching of paths currently has no effect, so method always returns NO.

Availability
See Also
Declared In
NSBezierPath.h

closePath

Closes the most recently added subpath.

- (void)closePath

Discussion

This method closes the current subpath by creating a line segment between the first and last points in the subpath. This method subsequently updates the current point to the end of the newly created line segment, which is also the first point in the now closed subpath.

Availability
See Also
Declared In
NSBezierPath.h

containsPoint:

Returns a Boolean value indicating whether the receiver contains the specified point.

- (BOOL)containsPoint:(NSPoint)aPoint

Parameters
aPoint

The point to test against the path, specified in the path object's coordinate system.

Return Value

YES if the path's enclosed area contains the specified point; otherwise, NO.

Discussion

This method checks the point against the path itself and the area it encloses. When determining hits in the enclosed area, this method uses the non-zero winding rule (NSNonZeroWindingRule). It does not take into account the line width used to stroke the path.

Availability
Declared In
NSBezierPath.h

controlPointBounds

Returns the bounding box of the receiver’s path, including any control points.

- (NSRect)controlPointBounds

Return Value

The rectangle that encloses the receiver's path. If the path contains curve segments, the bounding box encloses the control points of the curves as well as the curves themselves.

Availability
See Also
Declared In
NSBezierPath.h

currentPoint

Returns the receiver’s current point (the trailing point or ending point in the most recently added segment).

- (NSPoint)currentPoint

Return Value

The point from which the next drawn line or curve segment begins.

Discussion

If the receiver is empty, this method raises NSGenericException.

Availability
See Also
Declared In
NSBezierPath.h

curveToPoint:controlPoint1:controlPoint2:

Adds a Bezier cubic curve to the receiver’s path.

- (void)curveToPoint:(NSPoint)aPoint controlPoint1:(NSPoint)controlPoint1 controlPoint2:(NSPoint)controlPoint2

Parameters
aPoint

The destination point of the curve segment, specified in the current coordinate system

controlPoint1

The point that determines the shape of the curve near the current point.

controlPoint2

The point that determines the shape of the curve near the destination point.

Discussion

You must set the path's current point (using the moveToPoint: method or through the creation of a preceding line or curve segment) before you invoke this method. If the path is empty, this method raises an NSGenericException exception.

Availability
See Also
Declared In
NSBezierPath.h