Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSBezierPath


Inherits from:
NSObject
Package:
com.apple.yellow.application


Class Description


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 of the NSBezierPath object. 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.


Constructing Paths


You can create an instance of NSBezierPath using either of the class methods bezierPath or bezierPathWithRect. The bezierPath method initializes a new bezier-path object with an empty path while the bezierPathWithRect method creates a path with the specified rectangle. (You can also allocate memory for a new instance of NSBezierPath and use the default initializer, the init method, to initialize it to an empty path).

To add path information to an NSBezierPath object, you must invoke a sequence of path construction methods such as the moveToPoint, lineToPoint, and curveToPoint methods. For example, to create a polygon path, send a moveToPoint message, followed by a series of lineToPoint messages, to the NSBezierPath object. When you are done adding points to the path and want to form a closed path, send a closePath message to connect the last point back to the starting point.

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, which can themselves be either open or closed. The current point is the last point of the most recently added line segment.

Most construction methods implicitly use the current point as the starting point of the next segment. 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. Some methods may implicitly invoke moveToPoint, thereby creating a new subpath automatically. See the method descriptions for more information.

Convenience methods are provided for appending paths and common shapes to an existing path. The new path is usually discontiguous from the receiver's original path, although the appendBezierPathWithPoints:count: method creates a contiguous path from the specified points. Use the appendBezierPath... methods to append a path to an NSBezierPath object.


Path Elements


No matter which construction methods you use, all paths are reduced to a sequence of data points and common element types corresponding to the methods moveToPoint, lineToPoint, curveToPoint, and closePath. These element types can be specified with the following constants from the enumerated type BezierPathElement:

Every element except CloseBezierPathElement has at least one data point associated with it. The only element that has more than one data point is CurveToBezierPathElement (which maintains additional control points to define the shape of the curve). NSBezierPath defines several methods for obtaining information about the path elements (and their associated points) directly, including elementAtIndex:, and elementTypeAtIndex:associatedPoints: among others. You could use these methods to break down a path and reconstruct it point by point.


Drawing Paths


You typically render NSBezierPath objects inside an NSView's drawRect method (unless you are drawing outside the bounds of an NSView object, as in a rubberbanding operation). At the time the drawRect method is invoked, the focus is locked on the view and all drawing operations are clipped to that view. Therefore, most of the time you will want to construct paths whose points are specified in the view's coordinate system. You could also construct a path using an arbitrary coordinate system and transform the path to a view's coordinate system 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 should set the graphics attributes to use for the path. You can use the set... methods of NSBezierPath to set such attributes as the line cap style, line join style, line width, miter limit, curve flatness, and halftone phase. Other attributes must be set using the appropriate objects. For example, you set the color in the current graphics context by sending set to an NSColor object.

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).

As a convenience, some class methods are provided for drawing immediate shapes without the 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 use the strokeLineFromPoint class method to draw a line segment.


Winding Rules and Filling Paths


Simple paths like an oval or rectangle are easy to fill; however, there are several ways to fill complex paths that contain intersecting line segments or that contain a subpath enclosed by another subpath (i.e., a doughnut shape). You can specify how complex paths are filled using the setWindingRule method and the constants WindingRuleNonZero or WindingRuleEvenOdd.The rules that govern the effects of each constant are as follows:


Winding Rule Description
WindingRuleNonZero A point is outside if drawing a ray from that point in any direction results in a crossing count of 0, where crossing a left-to-right path adds 1 and crossing a right-to-left path subtracts 1. Otherwise, the point is inside.
WindingRuleEvenOdd 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.

For example, given a path with two nested circles, Figure 0-4 shows the results of using each winding rule. If the winding rule is WindingRuleNonZero, the direction of the paths is used to determine whether or not a segment should be filled. When the two paths are traveling in the same direction, the entire area of both circles is filled, but when the paths travel counter to each other the interior circle is left unfilled. When the winding rule is WindingRuleEvenOdd, the interior circle is left unfilled regardless of which direction the paths travel.

Winding rule examples

[image: Art/WindingRules.gif]

Setting Path Styles


NSBezierPath includes several methods for setting the current drawing style to be used for rendering paths. Most drawing styles are global attributes, set using class methods of NSBezierPath. The one exception to this is the winding rule attribute, which is local to a particular path. The global attributes include path-related attributes such as the line width, miter limit, line join style, line cap style, and curve flatness. For information about setting the winding rule of a path, see "Winding Rules and Filling Paths" .

To set other attributes of the path, such as the color, you must use the methods of the appropriate class. For example, to set the color of the path, you would need to create a new instance of NSColor and invoke its set method.




Constants


As a convenience, the following constants are provided by NSBezierPath:


Constant Type Description
LineCapStyleButt int 0
LineCapStyleProjectingSquare int 2
LineCapStyleRound int 1
LineJoinStyleBevel int 2
LineJoinStyleMiter int 0
LineJoinStyleRound int 1



Method Types


Constructors
NSBezierPath
Creating an NSBezierPath object
bezierPath
bezierPathWithOvalInRect
bezierPathWithRect
bezierPathByFlatteningPath
bezierPathByReversingPath
Constructing paths
moveToPoint
lineToPoint
curveToPoint
closePath
relativeMoveToPoint
relativeLineToPoint
relativeCurveToPoint
Appending paths and some common shapes
appendBezierPath
appendBezierPathWithOvalInRect
appendBezierPathWithArcFromPoint
appendBezierPathWithGlyph
Accessing attributes
defaultWindingRule
setDefaultWindingRule
setWindingRule
windingRule
defaultLineCapStyle
lineCapStyle
setLineCapStyle
setLineCapStyle
defaultLineJoinStyle
lineJoinStyle
setLineJoinStyle
setLineJoinStyle
defaultLineWidth
lineWidth
setLineWidth
setLineWidth
defaultMiterLimit
setDefaultMiterLimit
defaultFlatness
setDefaultFlatness
Drawing paths
stroke
fill
fillRect
strokeRect
strokeLineFromPoint
Clipping paths
addClip
setClip
clipRect
Hit detection
containsPoint
Querying paths
bounds
controlPointBounds
currentPoint
isEmpty
Applying transformations
transformUsingAffineTransform
Accessing elements of a path
elementCount
removeAllPoints
Caching paths
cachesBezierPath
setCachesBezierPath


Constructors



NSBezierPath

public NSBezierPath()

Description forthcoming.


Static Methods



bezierPath

public static NSBezierPath bezierPath()

Creates and returns a new NSBezierPath object. The path is initially empty.

bezierPathWithOvalInRect

public static NSBezierPath bezierPathWithOvalInRect(NSRect aRect)

Description forthcoming.

bezierPathWithRect

public static 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: bezierPath, appendBezierPathWithRect, fillRect, strokeRect



clipRect

public static 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



defaultFlatness

public static float defaultFlatness()

Description forthcoming.

defaultLineCapStyle

public static int defaultLineCapStyle()

Description forthcoming.

defaultLineJoinStyle

public static int defaultLineJoinStyle()

Description forthcoming.

defaultLineWidth

public static float defaultLineWidth()

Description forthcoming.

defaultMiterLimit

public static float defaultMiterLimit()

Description forthcoming.

defaultWindingRule

public static int defaultWindingRule()

Description forthcoming.

fillRect

public static 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, strokeRect, set (NSColor)



setDefaultFlatness

public static void setDefaultFlatness(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 flatness value for a graphic context is 1.0. Flatness values that are less than 0.2 or greater than 100 are normalized to those boundaries.



setDefaultLineCapStyle

public static void setDefaultLineCapStyle(int 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. Figure 0-5 shows the appearance of the available line cap styles.

Line cap styles

[image: Art/LineCaps.gif]

See Also: setDefaultLineJoinStyle, setDefaultLineWidth



setDefaultLineJoinStyle

public static void setDefaultLineJoinStyle(int lineJoinStyle)

Sets the current graphics context's line join style to lineJoinStyle. The line join style specifies the shape of the joints between connected segments of a stroked path. Figure 0-6 shows the appearance of the available line join styles.

Line join styles

[image: Art/LineJoins.gif]

See Also: setDefaultLineCapStyle, setDefaultLineWidth, setDefaultMiterLimit



setDefaultLineWidth

public static void setDefaultLineWidth(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. The width of the line may also be affected by scaling factors specified in the current transformation matrix of the active graphics context.

See Also: setDefaultLineCapStyle, setDefaultLineJoinStyle



setDefaultMiterLimit

public static void setDefaultMiterLimit(float limit)

Sets the current graphics context's miter limit to limit. Setting the miter limit avoids spikes produced by line segments that join at sharp angles. If the ratio of the miter length-the diagonal length of the miter-to the line thickness exceeds the miter limit, the corner is treated as a bevel join instead of a miter join. The default miter limit value is 10, which cuts off miters at angles less than 11 degrees.

See Also: setDefaultLineJoinStyle



setDefaultWindingRule

public static void setDefaultWindingRule(int windingRule)

Description forthcoming.

strokeLineFromPoint

public static void strokeLineFromPoint( NSPoint point1, 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, setDefaultLineCapStyle, setDefaultLineWidth, stroke



strokeRect

public static void strokeRect(NSRect aRect)

Strokes a rectangular path specified by aRect using the current graphics context's drawing style and color. The path is stroked beginning at the rectangle's origin and proceeding in a counterclockwise direction.

See Also: appendBezierPathWithRect, bezierPathWithRect, fillRect, setDefaultLineJoinStyle, setDefaultLineWidth, set (NSColor)




Instance Methods



addClip

public 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. The current winding rule is applied to determine the clipping area of the receiver. This method does not affect the receiver's path.

See Also: clipRect, setClip



appendBezierPath

public void appendBezierPath(NSBezierPath aPath)

Appends aPath to the receiver's path. This method adds the operations used to create aPath to the end of the receiver's path. This method does not explicitly try to connect the two paths, although the operations in aPath may still cause this effect.

appendBezierPathWithArcFromPoint

public void appendBezierPathWithArcFromPoint( NSPoint point1, NSPoint point2, float radius)

Description forthcoming.

appendBezierPathWithArcWithCenter

public void appendBezierPathWithArcWithCenter( NSPoint center, float radius, float startAngle, float endAngle, boolean clockwise)

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

appendBezierPathWithGlyph

public void appendBezierPathWithGlyph( int aGlyph, NSFont fontObj)

Appends an outline of aGlyph in fontObj to the receiver's path. If aGlyph is not encoded in fontObj-that is, the font does not have an entry for the specified glyph-then no path is appended to the receiver.

appendBezierPathWithOvalInRect

public void appendBezierPathWithOvalInRect(NSRect aRect)

Appends an oval path, inscribed in the rectangle aRect, to the receiver's path. If aRect specifies a square, the inscribed path is a circle. The inscribed path starts at the top center of aRect and arc segments are constructed counterclockwise to complete the oval.

appendBezierPathWithRect

public 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 line segments are added proceeding counterclockwise from the origin, ending with a message to closePath to complete the path.

See Also: bezierPathWithRect, fillRect, strokeRect



bezierPathByFlatteningPath

public NSBezierPath bezierPathByFlatteningPath()

Description forthcoming.

bezierPathByReversingPath

public NSBezierPath bezierPathByReversingPath()

Description forthcoming.

bounds

public NSRect bounds()

Returns the bounding box of the receiver's path. If the path contains curve segments, the bounding box encloses the curve but may not enclose the control points used to calculate the curve.

See Also: controlPointBounds



cachesBezierPath

public boolean cachesBezierPath()

Returns true if this object maintains a cached image of its path, otherwise returns false. The cached image is stored in a display user object.

See Also: setCachesBezierPath



closePath

public 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



containsPoint

public boolean containsPoint(NSPoint aPoint)

Description forthcoming.

controlPointBounds

public 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

public NSPoint currentPoint()

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

See Also: closePath, curveToPoint, lineToPoint, moveToPoint



curveToPoint

public void curveToPoint( NSPoint aPoint, NSPoint controlPoint1, 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. To create a relative curve, use the relativeCurveToPoint method.

See Also: closePath, lineToPoint, moveToPoint, relativeCurveToPoint, setDefaultFlatness



elementCount

public int elementCount()

Returns the number of element types currently stored by the receiver's path. Each element type corresponds to one of the operations specified by the BezierPathElementType enumerated type.

See Also: elementAtIndex:, elementTypeAtIndex:associatedPoints:



fill

public void fill()

Renders the receiver's path by painting the region enclosed by the path. Uses the winding rule, specified by invoking 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: stroke, windingRule, set (NSColor)



isEmpty

public boolean isEmpty()

Description forthcoming.

lineCapStyle

public int lineCapStyle()

Description forthcoming.

lineJoinStyle

public int lineJoinStyle()

Description forthcoming.

lineToPoint

public void lineToPoint(NSPoint aPoint)

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

See Also: closePath, curveToPoint, moveToPoint



lineWidth

public float lineWidth()

Description forthcoming.

moveToPoint

public 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, lineToPoint



relativeCurveToPoint

public void relativeCurveToPoint( NSPoint aPoint, NSPoint controlPoint1, NSPoint controlPoint2)

Adds a Bezier cubic curve to the receiver's path from the current point to a new location, which is specified as a relative distance from the current point. (The control points are similarly specified as relative distances from the current point.) The aPoint parameter specifies the end point of the curve as a relative distance from the current point. The controlPoint1 and controlPoint2 parameters specify the location of the two control points as relative distances from the current point. Throws GenericException if the path is empty.

See Also: closePath, curveToPoint, relativeLineToPoint, relativeMoveToPoint



relativeLineToPoint

public void relativeLineToPoint(NSPoint aPoint)

Appends a straight line to the receiver's path from the current point to aPoint, which is specified as a relative distance from the current point. Throws GenericException if the path is empty.

See Also: closePath, lineToPoint, relativeLineToPoint, relativeMoveToPoint



relativeMoveToPoint

public void relativeMoveToPoint(NSPoint aPoint)

Moves the receiver's current point to a new point, specified by the parameter aPoint as a relative distance from the current point. This method starts a new subpath without adding any line segments.

See Also: closePath, moveToPoint, relativeCurveToPoint, relativeLineToPoint



removeAllPoints

public void removeAllPoints()

Description forthcoming.

setCachesBezierPath

public void setCachesBezierPath(boolean flag)

Sets whether the receiver should cache its path information. Caching improves subsequent drawing times but requires extra memory to store the cached path representation. If caching is being turned on (flag is true), the receiver's cache is marked as needing to be calculated. Otherwise, if caching is being turned off, any existing cached data is deleted.

See Also: cachesBezierPath



setClip

public 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), restoreGraphicsState (NSGraphicsContext)



setLineCapStyle

public void setLineCapStyle(int lineCapStyle)

Description forthcoming.

setLineJoinStyle

public void setLineJoinStyle(int lineJoinStyle)

Description forthcoming.

setLineWidth

public void setLineWidth(float lineWidth)

Description forthcoming.

setWindingRule

public void setWindingRule(int aWindingRule)

Sets the winding rule used to fill the receiver's path, that is, paint the region enclosed by the path. Possible values for the aWindingRule parameter are WindingRuleNonZero or WindingRuleEvenOdd. See "Winding Rules and Filling Paths" for more information on how winding rules affect the appearance of filled paths.

See Also: fill, windingRule



stroke

public 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 setDefaultLineWidth class method) parallel to the path segment.

See Also: fill, setDefaultLineCapStyle, setDefaultLineJoinStyle, set (NSColor)



transformUsingAffineTransform

public void transformUsingAffineTransform(NSAffineTransform aTransform)

Description forthcoming.

windingRule

public int windingRule()

Returns the winding rule used to fill the receiver's path, that is, paint the region enclosed by the path. Possible return values are WindingRuleNonZero or WindingRuleEvenOdd. See "Winding Rules and Filling Paths" for more information on how winding rules affect the appearance of filled paths.

See Also: fill, setWindingRule




Table of Contents