NSBezierPath Class Reference

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.

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.

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.

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.

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.

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.

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.

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.

Discussion

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

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.

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.

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.

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.

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.

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.

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.

Discussion

If the receiver is empty, this method raises NSGenericException.

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.

Discussion

Path elements describe the commands used to define a path and include basic commands such as moving to a specific point, creating a line segment, creating a curve, or closing the path. The elements are stored in the order of their execution.

Discussion

If you specify a value for the points parameter, your array must be large enough to hold the number of points for the given path element. Move, close path, and line segment commands return one point. Curve operations return three points.

For curve operations, the order of the points is controlPoint1 (points[0]), controlPoint2 (points[1]), endPoint (points[2]).

Discussion

Each element type corresponds to one of the operations described in “Path Elements”.

Discussion

This method fills the path using the current fill color and the receiver's current winding rule. If the path contains any open subpaths, this method implicitly closes them before painting the fill region.

The painted region includes the pixels right up to, but not including, the path line itself. For paths with large line widths, this can result in overlap between the fill region and the stroked path (which is itself centered on the path line).

Discussion

The array in the pattern parameter must be large enough to hold all of the returned values in the pattern. If you are not sure how many values there might be, you can call this method twice. The first time you call it, do not pass a value for pattern but use the returned value in count to allocate an array of floating-point numbers that you can then pass in the second time.

Discussion

This method creates a straight line segment starting at the current point and ending at the point specified by the aPoint parameter. The current point is the last point in the receiver’s most recently added segment.

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.

Discussion

If no value was set explicitly for the receiver, this method returns the default line width.

Discussion

This method implicitly closes the current subpath (if any) and sets the current point to the value in aPoint. When closing the previous subpath, this method does not cause a line to be created from the first and last points in the subpath.

For many path operations, you must invoke this method before issuing any commands that cause a line or curve segment to be drawn.

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.

Discussion

The destination point is relative to the current point. For example, if the current point is (1, 1) and aPoint contains the value (1, 2), a line segment is created between the points (1, 1) and (2, 3).

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.

Discussion

This method implicitly closes the current subpath (if any) and updates the location of the current point. For example, if the current point is (1, 1) and aPoint contains the value (1, 2), the previous subpath would be closed and the current point would become (2, 3). When closing the previous subpath, this method does not cause a line to be created from the first and last points in the subpath.

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.

Discussion

You can use this method to change the points associated with a path quickly and without recreating the path. You cannot use this method to change the type of the path element.

The following example shows you how you would modify the point associated with a line path element. The path created by this example results in a path with two elements. The first path element specifies a move to point (0, 0) while the second creates a line to point (100, 100). It then changes the line to go only to the point (50,50) using this method:

NSBezierPath *bezierPath = [NSBezierPath bezierPath];

NSPoint newPoint = NSMakePoint(50.0, 50.0);

[bezierPath moveToPoint: NSMakePoint(0.0, 0.0)];

[bezierPath lineToPoint: NSMakePoint(100.0, 100.0)];

// Modifies the point added by lineToPoint: method (100.0, 100.0)

// to the new point (50.0, 50.0)

[bezierPath setAssociatedPoints: &newPoint atIndex: 1];

Discussion

You should avoid using this method as a way of adjusting the clipping path, as it may expand the clipping path beyond the bounds set by the enclosing view. If you do use this method, be sure to save the graphics state prior to modifying the clipping path and restore the graphics state when you are done.

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

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.

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.

Discussion

For example, to produce a supermarket coupon type of dashed line:

array[0] = 5.0; //segment painted with stroke color

array[1] = 2.0; //segment not painted with a color

[path setLineDash: array count: 2 phase: 0.0];

In the above example, if you set phase to 6.0, the line dash would begin exactly six units into pattern, which would start the pattern in the middle of the first gap.

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.

Discussion

The line width defines the thickness of the receiver's stroked path. 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.

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.

Discussion

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

Discussion

The drawn line is centered on the path with its sides parallel to the path segment. This method uses the current drawing attributes associated with the receiver. If a particular attribute is not set for the receiver, this method uses the corresponding default attribute.

Discussion

This method applies the transform to the path's points immediately. The following code translates a line from 0,0 to 100,100 to a line from 10,10 to 110,110.

NSBezierPath *bezierPath = [NSBezierPath bezierPath];

NSAffineTransform *transform = [NSAffineTransform transform];

[bezierPath moveToPoint: NSMakePoint(0.0, 0.0)];

[bezierPath lineToPoint: NSMakePoint(100.0, 100.0)];

[transform translateXBy: 10.0 yBy: 10.0];

[bezierPath transformUsingAffineTransform: transform];

Discussion

This value overrides the default value returned by defaultWindingRule.

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