---

Creating a Path

When you want to construct a path in a graphics context, you signal Quartz by calling the function CGContextBeginPath. Next, you set the starting point for the first shape, or subpath, in the path by calling the function CGContextMoveToPoint. After you establish the first point, you can add lines, arcs, curves, and rectangles to the path, keeping in mind the following:

• Lines, arcs, and curves are drawn starting at the current point.

• When you want to close a subpath within a path, call the function CGContextClosePath to connect the current point to the starting point.

• When you draw arcs, Quartz draws a line between the current point and the starting point.

• Quartz does not draw a line between the current point and the origin of a rectangle.

• You must call a painting function to fill or stroke the path because creating a path does not draw the path. See “Painting a Path” for detailed information.

• Before you begin a new path you call the function CGContextBeginPath.

After you paint a path, it is flushed from the graphics context. You might not want to lose your path so easily, especially if it depicts a complex scene you want to use over and over again. For that reason, Quartz provides two data types for creating reusable paths—CGPathRef and CGMutablePathRef. You can call the function CGPathCreateMutable to create a mutable CGPath object to which you can add lines, arcs, curves, and rectangles. Quartz provides a set of CGPath functions that parallel the functions discussed in “The Building Blocks.” The path functions operate on a CGPath object instead of a graphics context. These functions are:

• CGPathCreateMutable, which takes the place of CGContextBeginPath

• CGPathMoveToPoint, which is similar to CGContextMoveToPoint

• CGPathAddLineToPoint, which is similar toCGContextAddLineToPoint

• CGPathAddCurveToPoint, which is similar to CGContextAddCurveToPoint

• CGPathAddEllipseInRect, which is similar to CGContextAddEllipseInRect

• CGPathAddArc, which is similar to CGContextAddArc

• CGPathAddRect, which is similar to CGContextAddRect

• CGPathCloseSubpath, which is similar to CGContextClosePath

See Quartz 2D Reference Collection for a complete list of the path functions.

When you want to append the path to a graphics context, you call the function CGContextAddPath. The path stays in the graphics context until Quartz paints it. You can add the path again by calling CGContextAddPath.

---