[TOC] [Prev] [Next] [Bottom]

NSBezierPath

Inherits From:
NSObject

Conforms To:
NSCoding
NSCopying
NSObject (NSObject)

Declared In:
AppKit/NSBezierPath.h

Class Description

An NSBezierPath object represents an accumulated drawing path, a path made up of numerous, possibly disconnected, subpaths. The path can be used for filling, stroking, or clipping. Paths may be appended to one another. Convenience methods are provided for constructing and rendering common shapes such as ovals, rectangles, polygons, arcs, and glyph outlines. This class provides hit detection methods so that you can determine if the user clicked on a filled or stroked path, not just clicked within the bounds of an NSView object. Hit detection is needed to implement interactive graphics, as in rubberbanding and dragging operations. Paths may also be enumerated to 'play back' the drawing operations. This is useful if you want to apply custom operations on all points or subpaths.

Constructing Paths

An NSBezierPath's object is constructed by invoking a sequence of path construction methods such as the moveToPoint:, lineToPoint:, and curveToPoint:controlPoint1:controlPoint2: methods. For example, to create a polygon path you send an NSBezierPath object a moveToPoint: message, followed by a series of lineToPoint: messages, and ending with a closePath message.

The order in which path construction methods are invoked is significant. Line segments connect only if they are defined consecutively and the second segment starts where the first segment ends. A path may be made up of one or more disconnected subpaths where a subpath is a sequence of connected segments. The current point is the ending point in the most recently added segment. A subpath is closed if the ending point is connected to the starting point (as in a polygon), otherwise the subpath is opened.

Most construction methods implicitly use the current point as the starting point of the next segment, so that if you want to create a new subpath you must explicitly invoke moveToPoint: first. For example, lineToPoint: adds a line segment from the current point to the specified point.

Convenience methods are provided for appending another path and common shapes to an existing path. Use the appendPath... methods to append a path to an NSBezierPath object as in this example which uses appendBezierPathWithOvalInRect: to create a circle:

NSRect aRect = NSMakeRect(0.0, 0.0, 50.0, 50.0);
aPath = [[NSBezierPath bezierPath] appendBezierPathWithOvalInRect:aRect];

No matter which construction methods you use, all paths are reduced to a sequence of common element types corresponding to the methods: moveToPoint:, lineToPoint:, curveToPoint:controlPoint1:controlPoint2: and closePath):

Element Type
NSBezierPathElementMoveTo
NSBezierPathElementLineTo
NSBezierPathElementCurveTo
NSBezierPathElementClose

Drawing Paths

You typically render NSBezierPath objects inside an NSView's drawRect: method (unless you are drawing outside of the bounds of an NSView object, as in a rubberbanding operation). At the time the drawRect: method is invoke the focus is locked on the view and any drawing operations will be clipped to that view. Therefore, you use the view's coordinate system to construct a path-all points should be specified in the view's coordinate system. Or you could construct a path using an arbitrary coordinate system and transform the path to view coordinates just before rendering the path using an NSAffineTransform object. An NSAffineTransform object can translate, scale, and rotate paths (see the NSAffineTransform class specification for details).

Before filling or stroking an NSBezierPath object, you might want to set the graphics attributes. For example, you set the color in the current graphics context by sending set to an NSColor object. You can set the line width, cap and join styles, and curve flatness using NSBezierPath is set... class methods.

You can use either the stroke, or fill methods to render a path. The stroke method draws a line along the receiver's path using the color, line width, cap and join styles, and curve flatness drawing attributes in the current graphics context. The fill method renders the path by painting the region enclosed by the path and uses the color and curve flatness attributes. The fill method will perform a close operation (invoke closePath) if the path is not already closed. (A subpath is closed if the ending point is connected to the starting point, otherwise the subpath is opened).

Simple paths like an oval or rectangle are easy to fill; however, there are several ways to fill complex paths containing line segments that intersect or a subpath that is enclosed by another (i.e., a doughnut shape). You specify how complex paths are filled using the setWindingRule: method. For example, if the winding rule is NSWindingRuleNonZero both circles in a doughnut shape might be filled, otherwise if the winding rule is NSWindingRuleEvenOdd then just thre region between the inner circle and outer circle would be filled (see setWindingRule: below for details).

As a convenience, some immediate mode drawing methods of common paths are provided which do not require creation of an NSBezierPath object. For example, use the fillRect: and strokeRect: class methods to draw a filled rectangle or outline of a rectangle, and the stokeLineFromPoint:toPoint: class method to draw a line segment.

Hit Detection

Hit detection is necessary if you want the user to be able to select your paths or graphical shapes. The Application Kit will let you know if the user clicked within the bounds of an NSView object by invoking one of the NSResponder mouse... methods. You use the NSBezierPath isHitByPoint: method to determine if the user clicked a filled path, and the isStrokeHitByPoint: method to determine if the user clicked on a stroked path. The isHitByRect: and isStrokeHitByRect: methods are useful if the user has selected a region (for example, by rubberbanding a rectangle) and you want to determine which paths lie inside that region.

Enumerating Paths

Paths may also be enumerated to 'play back' the drawing operations. This is useful if you want to apply custom operations to a path. For example, an NSBezierPath object enumerates its path to compute its bounds. An NSAffineTransform object enumerates a path when transforming a path (see NSAffineTransform's transformBezierPath: method).

<<forthcoming>>


Adopted Protocols

NSCoding
- encodeWithCoder:
- initWithCoder:
NSCopying
- copyWithZone:

Method Types

Creating an NSBezierPath object
+ bezierPath
+ bezierPathWithRect:
Contructing paths
- moveToPoint:
- lineToPoint:
- curveToPoint:controlPoint1:controlPoint2:
- closePath
- reset
- relativeMoveToPoint:
- relativeLineToPoint:
- relativeCurveToPoint:controlPoint1:controlPoint2:
Appending paths and some common shapes
- appendBezierPath:
- appendBezierPathWithRect:
- appendBezierPathWithPoints:count:
- appendBezierPathWithOvalInRect:
- appendBezierPathWithArcWithCenter:radius:startAngle:endAngle:
- appendBezierPathWithGlyph:inFont:
- appendBezierPathWithGlyphs:count:inFont:
- appendBezierPathWithPackedGlyphs:count:
Setting attributes
- setWindingRule:
- windingRule
+ setLineCapStyle:
+ setLineJoinStyle:
+ setLineWidth:
+ setFlatness:
+ setHalftonePhase:
Drawing paths
- stroke
- fill
+ fillRect:
+ strokeRect:
+ strokeLineFromPoint:toPoint:
+ drawPackedGlyphs:atPoint:
Clipping paths
- addClip
- setClip
+ clipRect:
Hit detection
- isHitByPoint:
- isHitByRect:
- isHitByPath:
- isStrokeHitByPoint:
- isStrokeHitByRect:
- isStrokeHitByPath:
Querying paths
- bounds
- controlPointBounds
- currentPoint
Accessing elements of a path
- elementCount
- elementTypeAtIndex:
- elementTypeAtIndex:associatedPoints:
- removeLastElement
- pointCount
- pointAtIndex:
- setPointAtIndex:toPoint:
- pointIndexForPathElementIndex:
- pathElementIndexForPointIndex:
Caching paths
- cachesBezierPath
- setCachesBezierPath:

Class Methods

bezierPath

+ (NSBezierPath *)bezierPath

Creates and returns a new NSBezierPath object.


bezierPathWithRect:

+ (NSBezierPath *)bezierPathWithRect:(NSRect)aRect

Creates and returns a new NSBezierPath object with a rectangular path specified by aRect. The path starts at the origin of aRect, and is constructed counterclockwise.

See also: - appendBezierPathWithRect:, + fillRect:, + strokeRect:


clipRect:

+ (void)clipRect:(NSRect)aRect

Intersects the current clipping path, stored in the current graphics context, with the rectangle referred to by aRect, and replaces the current clipping path with the resulting path.

See also: - addClip, - setClip


drawPackedGlyphs:atPoint:

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

<<Forthcoming>>

See also: - appendBezierPathWithGlyph:inFont:, - appendBezierPathWithGlyphs:count:inFont:, - appendBezierPathWithPackedGlyphs:count:, - set (NSColor)


fillRect:

+ (void)fillRect:(NSRect)aRect

Fills a rectangular path specified by aRect with the current color (stored in the current graphics context).

See also: - appendBezierPathWithRect:, + bezierPathWithRect:, - set (NSColor), + strokeRect:


setFlatness:

+ (void)setFlatness:(float)flatness

Sets the current graphics context's flatness attribute to flatness. The flatness attribute is the accuracy (or smoothness) with which curves are rendered. flatness is the maximum error tolerance, measured in pixels, where smaller numbers give smoother curves at the expense of more computation. The exact interpretation may vary slightly on different rendering devices. The default value is 1.0.


setHalftonePhase:

+ (void)setHalftonePhase:(NSPoint)aPoint

Sets the current graphics context's halftone phase to aPoint. The halftone phase is a shift in the alignment of halftone and pattern cells in device space to compensate for window system operations that involve scrolling. This is a device dependent property. The default value is (0, 0).


setLineCapStyle:

+ (void)setLineCapStyle:(NSLineCapStyle)lineCap

Sets the current graphics context's line cap style to lineCap. The line cap style specifies the shape of the endpoints of an open path when stroked. The available line cap styles are:

Line Cap Style Example
NSLineCapButt
NSLineCapRound
NSLineCapProjectingSquare

See also: + setLineJoinStyle:, + setLineWidth:


setLineJoinStyle:

+ (void)setLineJoinStyle:(NSLineJoinStyle)lineJoinStyle

Sets the current graphics context's line join style to lineJoinStyle. The line join style specifies the shape of joints between connected segments of a stroked path. The available line join styles are:

Line Join Style Example
NSLineJoinMiter
NSLineJoinRound
NSLineJoinBevel

See also: + setLineCapStyle:, + setLineWidth:, + setMiterLimit:


setLineWidth:

+ (void)setLineWidth:(float)width

Sets the current graphics context's line width to width points. The line width is the thickness of stroked paths. A width of zero is interpreted as the thinnest line that can be rendered on a particular device. The actual rendered line width may vary from width by as much as two device pixels, depending on the position of the line with respect to the pixel grid.

See also: + setLineCapStyle:, + setLineJoinStyle:


setMiterLimit:

+ (void)setMiterLimit:(float)limit

Sets the current graphics context's miter limit to limit. The miter limit is the maximum length of a mitered line joint. Setting the miter limit avoids spikes produced by line segments that join at sharp angles. If the ratio of the miter length to the line thickness exceeds the miter limit parameter, the corner is treated as a bevel join instead of a miter join. The default value is 10 for a miter cutoff below 11 degrees.

See also: + setLineJoinStyle:


strokeLineFromPoint:toPoint:

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

Strokes a line from point1 to point2 using the current graphics context's drawing attributes (for example, color, line cap style, and line width).

See also: - lineToPoint:, - moveToPoint:, + setLineCapStyle:, + setLineWidth:, - stroke


strokeRect:

+ (void)strokeRect:(NSRect)aRect

Strokes a rectangular path specified by aRect using the current graphics context's drawing style and color.

See also: - appendBezierPathWithRect:,+ bezierPathWithRect:, + fillRect:, - set (NSColor), + setLineJoinStyle:, + setLineWidth:


Instance Methods

appendBezierPath:

- (void)appendBezierPath:(NSBezierPath *)aPath

Appends aPath to the receiver's path. If aPath starts with a move to the receiver's current point, then the move operation is omitted. This avoids constructing a new subpath and will ensure proper line joins.


appendBezierPathWithArcWithCenter:radius:startAngle:endAngle:

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

Appends an arc of a circle to the receiver's path The circle is centered at center with radius radius. The first endpoint and second endpoint of the arc lies on the perimeter of the circle at startAngle and endAngle, measured in degrees counterclockwise from the x-axis.


appendBezierPathWithGlyph:inFont:

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

Appends an outline of aGlyph in fontObj to the receiver's path. If aGlyph is not encoded in fontObj, then no path is appended to the receiver (for example, if the outline of fontObj is protected).

See also: - appendBezierPathWithGlyphs:count:inFont:, - appendBezierPathWithPackedGlyphs:count:, + drawPackedGlyphs:atPoint:


appendBezierPathWithGlyphs:count:inFont:

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

Appends the outlines of the NSGlyphs in the glyphs array using fontObj. count is the number of NSGlyphs in glyphs. If an NSGlyph is not encoded in fontObj, then no path is appended for that glyph (for example, if the outline of fontObj is protected).

See also: - appendBezierPathWithGlyph:inFont:, - appendBezierPathWithPackedGlyphs:count:, + drawPackedGlyphs:atPoint:


appendBezierPathWithOvalInRect:

- (void)appendBezierPathWithOvalInRect:(NSRect)aRect

Appends an oval path bounded by aRect to the receiver's path. If aRect is square, a circle is appended to the receiver's path. The path starts at the top center of aRect, and is constructed counterclockwise


appendBezierPathWithPackedGlyphs:count:

- appendBezierPathWithPackedGlyphs:(NSGlyph *)glyphs count:(int)count

Appends a path outlining glyphs to the receiver's path. count is the number of glyphs in glyphs.

See also: - appendBezierPathWithGlyph:inFont:, - appendBezierPathWithGlyphs:count:inFont:, + drawPackedGlyphs:atPoint:


appendBezierPathWithPoints:count:

- (void)appendBezierPathWithPoints:(NSPoint *)points count:(int)count

Appends a series of line segments with count number of vertices in points to the receiver's path. To append a polygon, invoke closePath after invoking this method.


appendBezierPathWithRect:

- (void)appendBezierPathWithRect:(NSRect)aRect

Appends a rectangular path, specified by aRect, to the receiver's path. The path starts at the origin of aRect, and is constructed counterclockwise.

See also: + bezierPathWithRect:, + fillRect:, + strokeRect:


addClip

- (void)addClip

Intersects the current clipping path, stored in the current graphics context with the receiver's path, and replaces the current clipping path with the resulting path.

See also: + clipRect:, - setClip


bounds

- (NSRect)bounds

Returns the bounding box of the receiver's path. If the path contains curve segments, the bounding box may not enclose all control points.

See also: - controlPointBounds


cachesBezierPath

- (BOOL)cachesBezierPath

<< Description forthcoming >>


closePath

- (void)closePath

Closes the most recently added subpath by appending a straight line segment from the current point to the subpath's starting point. A subpath is a sequence of connected segments; a path may be made up of one or more disconnected subpaths. The current point is the ending point in the most recently added segment.

See also: - fill


controlPointBounds

- (NSRect)controlPointBounds

Returns the bounding box of the receiver's path including any control points. If the path contains curve segments, the bounding box encloses the control points of the curves as well as the curves themselves.

See also: - bounds


currentPoint

- (NSPoint)currentPoint

Returns the path's current point (the trailing point or ending point in the most recently added segment). Raises NSGraphicsNoCurrentPointException if the path is empty.

See also: - closePath, - curveToPoint:controlPoint1:controlPoint2:, - lineToPoint:, - moveToPoint:, - reset


curveToPoint:controlPoint1:controlPoint2:

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

Adds a Bezier cubic curve to the receiver's path from the current point to aPoint, using controlPoint1 and controlPoint2 as the Bezier cubic control points. The current point is the ending point in the most recently added segment. Raises NSGraphicsNoCurrentPointException if the path is empty.

See also: - closePath, - lineToPoint:, - moveToPoint:, + setFlatness:


elementCount

- (int)elementCount

<<forthcoming>>

See also: - elementTypeAtIndex:, - elementTypeAtIndex:associatedPoints:, - removeLastElement


elementTypeAtIndex:

- (NSBezierPathElementType)elementTypeAtIndex:(int)index

<<forthcoming>>

See also: - elementCount, - elementTypeAtIndex:associatedPoints:, - removeLastElement


elementTypeAtIndex:associatedPoints:

- (NSBezierPathElementType)elementTypeAtIndex:(int)index associatedPoints:(NSPoint *)points

<<forthcoming>>

See also: - elementCount, - elementTypeAtIndex:, - removeLastElement


fill

- (void)fill

Renders the receiver's path by painting the region enclosed by the path. Uses the winding rule, specified by inoking setWindingRule:, and the current graphics context's color to fill the path. Closes any open subpaths. A subpath is a sequence of connected segments; a path may be made up of one or more disconnected subpaths. A subpath is closed if the ending point is connected to the starting point (as in a polygon).

See also: - set (NSColor), - setWindingRule:, - stroke, - windingRule


isHitByPath:

- (BOOL)isHitByPath:(NSBezierPath *)aBezierPath

Returns YES if the receiver's path hits any part of aBezierPath when filled, otherwise returns NO.

See also: - isHitByPoint:, - isHitByRect:, - isStrokeHitByPath:


isHitByPoint:

- (BOOL)isHitByPoint:(NSPoint)aPoint

Returns YES if the receiver's path hits aPoint when filled, otherwise returns NO.

See also: - isHitByPath:, - isHitByRect:, - isStrokeHitByPoint:


isHitByRect:

- (BOOL)isHitByRect:(NSRect)aRect

Returns YES if the receiver's path hits aRect when filled, otherwise returns NO.

See also: - isHitByPath:, - isHitByPoint:, - isStrokeHitByRect:


isStrokeHitByPath:

- (BOOL)isStrokeHitByPath:(NSBezierpath *)aBezierPath

Returns YES if the receiver's path hits aBezierPath when both paths are stroked, otherwise returns NO.

See also: - isStrokeHitByPoint:, - isStrokeHitByRect:, - isHitByPath:


isStrokeHitByPoint:

- (BOOL)isStrokeHitByPoint:(NSPoint)aPoint

Returns YES if the receiver's path hits aPoint when stroked, otherwise returns NO.

See also: - isStrokeHitByPath:, - isStrokeHitByRect:, - isHitByPoint:


isStrokeHitByRect:

- (BOOL)isStrokeHitByRect:(NSRect)aRect

Returns YES if the receiver's path hits aRect when both are stroked, otherwise returns NO.

See also: - isStrokeHitByPath:, - isStrokeHitByPoint:, - isHitByRect:


lineToPoint:

- (void)lineToPoint:(NSPoint)aPoint

Appends a straight line to the receiver's path from the current point, the ending point in the most recently added segment, to aPoint.

See also: - closePath, - curveToPoint:controlPoint1:controlPoint2:, - moveToPoint:


moveToPoint:

- (void)moveToPoint:(NSPoint)aPoint

Moves the receiver's current point to aPoint, starting a new subpath, without adding any line segments. A subpath is a sequence of connected segments; a path may be made up of one or more disconnected subpaths. The current point is the ending point in the most recently added segment.

See also: - closePath, - curveToPoint:controlPoint1:controlPoint2:, - lineToPoint:


pathElementIndexForPointIndex:

- (int)pathElementIndexForPointIndex:(int)index

<<forthcoming>>

See also: - pointAtIndex:, - pointCount, - pointIndexForPathElementIndex:, - setPointAtIndex: toPoint:


pointAtIndex:

- (NSPoint)pointAtIndex:(int)index

<<forthcoming>>

See also: - pathElementIndexForPointIndex:, - pointCount, - pointIndexForPathElementIndex:, - setPointAtIndex:toPoint:


pointCount

- (int)pointCount

<<forthcoming>>

See also: - pathElementIndexForPointIndex:, - pointAtIndex:, - pointIndexForPathElementIndex:, - setPointAtIndex:toPoint:


pointIndexForPathElementIndex:

- (int)pointIndexForPathElementIndex:(int)index

<<forthcoming>>

See also: - pathElementIndexForPointIndex:, - pointAtIndex:, - pointCount, - setPointAtIndex: toPoint:


relativeCurveToPoint:controlPoint1:controlPoint2:

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

Adds a Bezier cubic curve to the receiver's path from the current point to aPoint, using controlPoint1 and controlPoint2 as the Bezier cubic control points. The current point is the ending point in the most recently added segment. The three points, aPoint, controlPoint1 and controlPoint2 are specified relative to the current point. Raises NSGraphicsNoCurrentPointException if the path is empty.

See also: - closePath, - curveToPoint:controlPoint1:controlPoint2:, - relativeLineToPoint:, - relativeMoveToPoint:


relativeLineToPoint:

- (void)relativeLineToPoint:(NSPoint)aPoint

Appends a straight line to the receiver's path from the current point, the ending point in the most recently added segment, to aPoint, specified relative to the current point. Raises NSGraphicsNoCurrentPointException if the path is empty.

See also: - closePath, - lineToPoint:, - relativeCurveToPoint:controlPoint1:controlPoint2:, - relativeMoveToPoint:


relativeMoveToPoint:

- (void)relativeMoveToPoint:(NSPoint)aPoint

Moves the receiver's current point to aPoint, relative to the current point. Starts a new subpath without adding any line segments. A subpath is a sequence of connected segments; a path may be made up of one or more disconnected subpaths. The current point is the ending point in the most recently added segment.

See also: - closePath, - moveToPoint:, - relativeCurveToPoint:controlPoint1:controlPoint2:, - relativeLineToPoint:


removeLastElement

- (void)removeLastElement

<<forthcoming>>

See also: - elementCount, - elementTypeAtIndex:, - elementTypeAtIndex:associatedPoints:


reset

- (void)reset

Sets the receiver's path to an empty path, a path containing no subpaths. A subpath is a sequence of connected segments; a path may be made up of one or more disconnected subpaths. After invoking this method the current point is undefined.


setCachesBezierPath:

- (void)setCachesBezierPath:(BOOL)flag

<<forthcoming>>

See also: - cachesBezierPath


setClip

- (void)setClip

Replace the current clipping path with the area inside this path as determined by the winding rule. This is not a preferred method of adjusting the clipping path, as it may expand the clipping path beyond the bounds set by the enclosing NSView. The graphics state should be saved and restored before and after invoking this method.

See also: - addClip, + clipRect:, - saveGraphicsState (NSGraphicsContext)


setPointAtIndex:toPoint:

- (void)setPointAtIndex:(int)index toPoint:(NSPoint)aPoint

<<forthcoming>>

See also: - pathElementIndexForPointIndex:, - pointAtIndex:, - pointCount, - pointIndexForPathElementIndex:


setWindingRule:

- (void)setWindingRule:(NSWindingRule)aWindingRule

Sets the winding rule used to fill the receiver's path, that is, paint the region enclosed by the path. It is easy to determine the enclosed region of a simple path such as the path of a circle or rectangle, but complex paths that intersect themselves can be rendered differently. The winding rule specifies how the interior regions of complex paths are filled. The possible winding rule values are:

Winding Rule Example
NSWindingRuleNonZero
NSWindingRuleEvenOdd

See also: - fill, - windingRule


stroke

- (void)stroke

Draws a line along the receiver's path using the current graphic context's color and other drawing attributes (for example, line cap style, line join style, and line width). The drawn line is centered on the path with sides (specified by the setLineWidth: class method) parallel to the path segment.

See also: - fill, - set (NSColor), + setLineCapStyle:, + setLineJoinStyle:, + setLineWidth:


windingRule

- (NSWindingRule)windingRule

Returns the receiver's winding rule used to fill the receiver's path, that is, paint the region enclosed by the path. It is easy to determine the enclosed region of a simple path such as the path of a circle or rectangle, but complex paths that intersect themselves can be rendered differently. The winding rule specifies how the interior regions of complex paths are filled. The possible winding rule values are:

Winding Rule Description Example
NSWindingRuleNonZero
NSWindingRuleEvenOdd A point is inside if drawing a ray from that point in any direction and counting the number of path segments that the ray crosses is odd, otherwise the point is outside. Inside points are filled, outside points are not.

See also: - fill, - setWindingRule:



[TOC] [Prev] [Next] [Bottom]

Copyright © 1997, Apple Computer, Inc. All rights reserved.