- Inherits from:
- NSObject
- Package:
- com.apple.yellow.application
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.
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.
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
:
MoveToBezierPathElement
LineToBezierPathElement
CurveToBezierPathElement
CloseBezierPathElement
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.
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.
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
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.
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 |
- 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
public NSBezierPath()
public static NSBezierPath bezierPath()
public static NSBezierPath bezierPathWithOvalInRect(NSRect aRect)
public static NSBezierPath bezierPathWithRect(NSRect aRect)
See Also: bezierPath, appendBezierPathWithRect, fillRect, strokeRect
public static void clipRect(NSRect aRect)
public static float defaultFlatness()
public static int defaultLineCapStyle()
public static int defaultLineJoinStyle()
public static float defaultLineWidth()
public static float defaultMiterLimit()
public static int defaultWindingRule()
public static void fillRect(NSRect aRect)
See Also: appendBezierPathWithRect, bezierPathWithRect, strokeRect, set (NSColor)
public static void setDefaultFlatness(float flatness)
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.
public static void setDefaultLineCapStyle(int lineCap)
Line cap styles
See Also: setDefaultLineJoinStyle, setDefaultLineWidth
public static void setDefaultLineJoinStyle(int lineJoinStyle)
Line join styles
See Also: setDefaultLineCapStyle, setDefaultLineWidth, setDefaultMiterLimit
public static void setDefaultLineWidth(float width)
See Also: setDefaultLineCapStyle, setDefaultLineJoinStyle
public static void setDefaultMiterLimit(float limit)
See Also: setDefaultLineJoinStyle
public static void setDefaultWindingRule(int windingRule)
public static void strokeLineFromPoint(
NSPoint point1,
NSPoint point2)
See Also: lineToPoint, moveToPoint, setDefaultLineCapStyle, setDefaultLineWidth, stroke
public static void strokeRect(NSRect aRect)
See Also: appendBezierPathWithRect, bezierPathWithRect, fillRect, setDefaultLineJoinStyle, setDefaultLineWidth, set (NSColor)
public void addClip()
public void appendBezierPath(NSBezierPath aPath)
public void appendBezierPathWithArcFromPoint(
NSPoint point1,
NSPoint point2,
float radius)
public void appendBezierPathWithArcWithCenter(
NSPoint center,
float radius,
float startAngle,
float endAngle,
boolean clockwise)
public void appendBezierPathWithGlyph(
int aGlyph,
NSFont fontObj)
public void appendBezierPathWithOvalInRect(NSRect aRect)
public void appendBezierPathWithRect(NSRect aRect)
See Also: bezierPathWithRect, fillRect, strokeRect
public NSBezierPath bezierPathByFlatteningPath()
public NSBezierPath bezierPathByReversingPath()
public NSRect bounds()
See Also: controlPointBounds
public boolean cachesBezierPath()
See Also: setCachesBezierPath
public void closePath()
See Also: fill
public boolean containsPoint(NSPoint aPoint)
public NSRect controlPointBounds()
See Also: bounds
public NSPoint currentPoint()
See Also: closePath, curveToPoint, lineToPoint, moveToPoint
public void curveToPoint(
NSPoint aPoint,
NSPoint controlPoint1,
NSPoint controlPoint2)
See Also: closePath, lineToPoint, moveToPoint, relativeCurveToPoint, setDefaultFlatness
public int elementCount()
BezierPathElementType
enumerated
type.See Also: elementAtIndex:, elementTypeAtIndex:associatedPoints:
public void fill()
See Also: stroke, windingRule, set (NSColor)
public boolean isEmpty()
public int lineCapStyle()
public int lineJoinStyle()
public void lineToPoint(NSPoint aPoint)
See Also: closePath, curveToPoint, moveToPoint
public float lineWidth()
public void moveToPoint(NSPoint aPoint)
See Also: closePath, curveToPoint, lineToPoint
public void relativeCurveToPoint(
NSPoint aPoint,
NSPoint controlPoint1,
NSPoint controlPoint2)
See Also: closePath, curveToPoint, relativeLineToPoint, relativeMoveToPoint
public void relativeLineToPoint(NSPoint aPoint)
See Also: closePath, lineToPoint, relativeLineToPoint, relativeMoveToPoint
public void relativeMoveToPoint(NSPoint aPoint)
See Also: closePath, moveToPoint, relativeCurveToPoint, relativeLineToPoint
public void removeAllPoints()
public void setCachesBezierPath(boolean flag)
See Also: cachesBezierPath
public void setClip()
See Also: addClip, clipRect, saveGraphicsState (NSGraphicsContext), restoreGraphicsState (NSGraphicsContext)
public void setLineCapStyle(int lineCapStyle)
public void setLineJoinStyle(int lineJoinStyle)
public void setLineWidth(float lineWidth)
public void setWindingRule(int aWindingRule)
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
public void stroke()
See Also: fill, setDefaultLineCapStyle, setDefaultLineJoinStyle, set (NSColor)
public void transformUsingAffineTransform(NSAffineTransform aTransform)
public int windingRule()
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