Derived from | |
Framework | ApplicationServices/ApplicationServices.h |
Companion guide | |
Declared in | CGContext.h CGPath.h |
A graphics path is a description of a 2D
geometric scene using sequences of lines and Bézier curves. CGPathRef
defines
an opaque type that represents an immutable graphics path. CGMutablePathRef
defines
an opaque type that represents a mutable graphics path. To draw using
a Quartz path, you need to add the path to a graphics context—see CGContextAddPath
.
Each figure in a scene may be described by a subpath.
A subpath has an ordered set of path elements,
that represent single steps in the construction of a subpath. (For example, MoveToPoint (bottom left)
and AddLineToPoint (bottom right)
are path elements.)
A subpath also maintains state information, including a starting
point and a current point. When drawing
a path, Quartz traverses each subpath using its path elements and
its state.
The lines and curves in a subpath are always connected, but they do not necessarily form a closed figure. Furthermore, subpaths do not need to be connected to each other. For example, you could use a graphics path to draw the outlines of a sequence of text characters.
CGPathAddArc
CGPathAddArcToPoint
CGPathAddCurveToPoint
CGPathAddLines
CGPathAddLineToPoint
CGPathAddPath
CGPathAddQuadCurveToPoint
CGPathAddRect
CGPathAddRects
CGPathApply
CGPathMoveToPoint
CGPathCloseSubpath
CGPathAddEllipseInRect
CGPathEqualToPath
CGPathGetBoundingBox
CGPathGetCurrentPoint
CGPathGetTypeID
CGPathIsEmpty
CGPathIsRect
CGPathContainsPoint
Appends an arc to a mutable graphics path, possibly preceded by a straight line segment.
void CGPathAddArc ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat x, CGFloat y, CGFloat radius, CGFloat startAngle, CGFloat endAngle, bool clockwise );
The mutable graphics path to change.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the arc before it is added to the path.
The x-coordinate of the center point of the arc.
The y-coordinate of the center point of the arc.
The radius of the arc.
The angle (in radians) from horizontal that determines the starting point of the arc.
The angle (in radians) from horizontal that determines the ending point of the arc.
A Boolean value that specifies whether or not to draw the arc in the clockwise direction; true
specifies clockwise.
An arc is a segment of a circle with radius r centered at a point (x,y)
. When you call this function, you provide the center point, radius, and two angles in radians. Quartz uses this information to determine the end points of the arc, and then approximates the new arc using a sequence of cubic Bézier curves. The clockwise
parameter determines the direction in which the arc is drawn.
A transformation may be applied to the Bézier curves before they are added to the path. If no transform is needed, the second argument should be NULL
.
If the specified path already contains a subpath, Quartz implicitly adds a line connecting the current point to the beginning of the arc. If the path is empty, Quartz creates a new subpath for the arc and does not add the initial straight line segment.
The ending point of the arc becomes the new current point of the path.
CGPath.h
Appends an arc to a mutable graphics path, possibly preceded by a straight line segment.
void CGPathAddArcToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat x1, CGFloat y1, CGFloat x2, CGFloat y2, CGFloat radius );
The mutable path to change. The path must not be empty.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the arc before it is added to the path.
The x-coordinate of the user space for the end point of the first tangent line. The first tangent line is drawn from the current point to (x1,y1)
.
The y-coordinate of the user space for the end point of the first tangent line. The first tangent line is drawn from the current point to (x1,y1)
.
The x-coordinate of the user space for the end point of the second tangent line. The second tangent line is drawn from (x1,y1)
to (x2,y2)
.
The y-coordinate of the user space for the end point of the second tangent line. The second tangent line is drawn from (x1,y1)
to (x2,y2)
.
The radius of the arc, in user space coordinates.
This function uses a sequence of cubic Bézier curves to draw an arc that is tangent to the line from the current point to (x1,y1) and to the line from (x1,y1) to (x2,y2). The start and end points of the arc are located on the first and second tangent lines, respectively. The start and end points of the arc are also the “tangent points” of the lines.
If the current point and the first tangent point of the arc (the starting point) are not equal, Quartz appends a straight line segment from the current point to the first tangent point. After adding the arc, the current point is reset to the end point of the arc (the second tangent point).
For another way to draw an arc in a path, see CGPathAddArc
.
CGPath.h
Appends a Bézier curve to a mutable graphics path.
void CGPathAddCurveToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat cp1x, CGFloat cp1y, CGFloat cp2x, CGFloat cp2y, CGFloat x, CGFloat y );
The mutable path to change. The path must not be empty.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the curve before it is added to the path.
The x-coordinate of the first control point.
The y-coordinate of the first control point.
The x-coordinate of the second control point.
The y-coordinate of the second control point.
The x-coordinate of the end point of the curve.
The y-coordinate of the end point of the curve.
Appends a cubic Bézier curve from the current point in a path to the specified location using two control points, after an optional transformation. Before returning, this function updates the current point to the specified location (x,y
).
CGPath.h
Adds to a path an ellipse that fits inside a rectangle.
void CGPathAddEllipseInRect ( CGMutablePathRef path, const CGAffineTransform *m, CGRect rect );
The path to modify.
An affine transform to apply to the ellipse, or NULL
if you don’t want to transform the ellipse.
A rectangle to enclose the ellipse.
The ellipse is approximated by a sequence of Bézier curves. Its center is the midpoint of the rectangle defined by the rect
parameter. If the rectangle is square, then the ellipse is circular with a radius equal to one-half the width (or height) of the rectangle. If the rect
parameter specifies a rectangular shape, then the major and minor axes of the ellipse are defined by the width and height of the rectangle.
The ellipse forms a complete subpath of the path—that is, the ellipse drawing starts with a move-to operation and ends with a close-subpath operation, with all moves oriented in the clockwise direction. If you supply an affine transform, then the constructed Bézier curves that define the ellipse are transformed before they are added to the path.
CGPath.h
Appends an array of new line segments to a mutable graphics path.
void CGPathAddLines ( CGMutablePathRef path, const CGAffineTransform *m, const CGPoint points[], size_t count );
The mutable path to change.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the lines before adding them to the path.
An array of points that specifies the line segments to add.
The number of elements in the array.
This is a convenience function that adds a sequence of connected line segments to a path, using the following operation:
CGPathMoveToPoint (path, m, points[0].x, points[0].y); |
for (k = 1; k < count; k++) { |
CGPathAddLineToPoint (path, m, points[k].x, points[k].y); |
} |
CGPath.h
Appends a line segment to a mutable graphics path.
void CGPathAddLineToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat x, CGFloat y );
The mutable path to change. The path must not be empty.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the line before it is added to the path.
The x-coordinate of the end point of the line.
The y-coordinate of the end point of the line.
Before returning, this function updates the current point to the specified location (x,y)
.
CGPath.h
Appends a path to a mutable graphics path.
void CGPathAddPath ( CGMutablePathRef path1, const CGAffineTransform *m, CGPathRef path2 );
The mutable path to change.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to path2
before it is added to path1
.
The path to add.
CGPath.h
Appends a quadratic curve to a mutable graphics path.
void CGPathAddQuadCurveToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat cpx, CGFloat cpy, CGFloat x, CGFloat y );
The mutable path to change. The path must not be empty.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the curve before adding it to the path.
The x-coordinate of the control point.
The y-coordinate of the control point.
The x-coordinate of the end point of the curve.
The y-coordinate of the end point of the curve.
Before returning, this function updates the current point to the specified location (x, y)
.
CGPath.h
Appends a rectangle to a mutable graphics path.
void CGPathAddRect ( CGMutablePathRef path, const CGAffineTransform *m, CGRect rect );
The mutable path to change.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the rectangle before adding it to the path.
The rectangle to add.
This is a convenience function that adds a rectangle to a path, using the following sequence of operations:
// start at origin |
CGPathMoveToPoint (path, m, CGRectGetMinX(rect), CGRectGetMinY(rect)); |
// add bottom edge |
CGPathAddLineToPoint (path, m, CGRectGetMaxX(rect), CGRectGetMinY(rect)); |
// add right edge |
CGPathAddLineToPoint (path, m, CGRectGetMaxX(rect), CGRectGetMaxY(rect); |
// add top edge |
CGPathAddLineToPoint (path, m, CGRectGetMinX(rect), CGRectGetMaxY(rect)); |
// add left edge and close |
CGPathCloseSubpath (path); |
CGPath.h
Appends an array of rectangles to a mutable graphics path.
void CGPathAddRects ( CGMutablePathRef path, const CGAffineTransform *m, const CGRect rects[], size_t count );
The mutable path to change.
An affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the rectangles before adding them to the path.
The array of new rectangles to add.
The number of elements in the array.
This is a convenience function that adds an array of rectangles to a path, using the following operation:
for (k = 0; k < count; k++) { |
CGPathAddRect (path, m, rects[k]); |
} |
CGPath.h
For each element in a graphics path, calls a custom applier function.
void CGPathApply ( CGPathRef path, void *info, CGPathApplierFunction function );
The path to which the function will be applied.
A pointer to the user data that Quartz will pass to the function being applied, or NULL
.
A pointer to the function to apply. See CGPathApplierFunction
for more information.
For each element in the specified path, Quartz calls the applier function, which can examine (but not modify) the element.
CGPath.h
Closes and completes a subpath in a mutable graphics path.
void CGPathCloseSubpath ( CGMutablePathRef path );
The path to change.
Appends a line from the current point in a path to the starting point of the current subpath and ends the subpath. On return, the current point is now the previous starting point.
CGPath.h
Checks whether a point is contained in a graphics path.
bool CGPathContainsPoint ( CGPathRef path, const CGAffineTransform *m, CGPoint point, bool eoFill );
The path to evaluate the point against.
An affine transform. If m
is not NULL
then the point is transformed by this affine transform prior to determining whether the path contains the point.
The point to check.
A Boolean value that, if true
, specifies to use the even-odd fill rule to evaluate the painted region of the path. If false
, the winding fill rule is used.
Returns true
if the point is contained in the path; false
otherwise.
A point is contained in a path if it is inside the painted region when the path is filled and the path is a closed path. You can call the function CGPathCloseSubpath
to ensure that a path is closed.
CGPath.h
Creates an immutable copy of a graphics path.
CGPathRef CGPathCreateCopy ( CGPathRef path );
The path to copy.
A new, immutable copy of the specified path. You are responsible for releasing this object.
CGPath.h
Creates a mutable graphics path.
CGMutablePathRef CGPathCreateMutable ( void );
A new mutable path. You are responsible for releasing this object.
CGPath.h
Creates a mutable copy of an existing graphics path.
CGMutablePathRef CGPathCreateMutableCopy ( CGPathRef path );
The path to copy.
A new, mutable, copy of the specified path. You are responsible for releasing this object.
You can modify a mutable graphics path by calling the various CGPath geometry functions, such as CGPathAddArc
, CGPathAddLineToPoint
, and CGPathMoveToPoint
.
CGPath.h
Indicates whether two graphics paths are equivalent.
bool CGPathEqualToPath ( CGPathRef path1, CGPathRef path2 );
The first path being compared.
The second path being compared.
A Boolean value that indicates whether or not the two specified paths contain the same sequence of path elements. If the paths are not the same, returns false
.
CGPath.h
Returns the bounding box of a graphics path.
CGRect CGPathGetBoundingBox ( CGPathRef path );
The graphics path to evaluate.
A rectangle that represents the bounding box of the specified path.
The bounding box is the smallest rectangle completely enclosing all points in the path, including control points for Bézier and quadratic curves.
CGPath.h
Returns the current point in a graphics path.
CGPoint CGPathGetCurrentPoint ( CGPathRef path );
The path to evaluate.
The current point in the specified path.
If the path is empty—that is, if it has no elements—this function returns CGPointZero
(see CGGeometry
). To determine whether a path is empty, use CGPathIsEmpty
.
CGPath.h
Returns the Core Foundation type identifier for Quartz graphics paths.
CFTypeID CGPathGetTypeID ( void );
The Core Foundation identifier for the opaque type CGPathRef
.
CGPath.h
Indicates whether or not a graphics path is empty.
bool CGPathIsEmpty ( CGPathRef path );
The path to evaluate.
A Boolean value that indicates whether the specified path is empty.
An empty path contains no elements.
CGPath.h
Indicates whether or not a graphics path represents a rectangle.
bool CGPathIsRect ( CGPathRef path, CGRect *rect );
The path to evaluate.
On input, a pointer to an uninitialized rectangle. If the specified path represents a rectangle, on return contains a copy of the rectangle.
A Boolean value that indicates whether the specified path represents a rectangle. If the path represents a rectangle, returns true
.
CGPath.h
Starts a new subpath at a specified location in a mutable graphics path.
void CGPathMoveToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat x, CGFloat y );
The mutable path to change.
A pointer to an affine transformation matrix, or NULL
if no transformation is needed. If specified, Quartz applies the transformation to the point before changing the path.
The x-coordinate of the new location.
The y-coordinate of the new location.
This function initializes the starting point and the current point to the specified location (x,y) after an optional transformation.
CGPath.h
Decrements the retain count of a graphics path.
void CGPathRelease ( CGPathRef path );
The graphics path to release.
This function is equivalent to CFRelease
, except that it does not cause an error if the path
parameter is NULL
.
CGPath.h
Increments the retain count of a graphics path.
CGPathRef CGPathRetain ( CGPathRef path );
The graphics path to retain.
The same path you passed in as the path
parameter.
This function is equivalent to CFRetain
, except that it does not cause an error if the path
parameter is NULL
.
CGPath.h
Defines a callback function that can view an element in a graphics path.
typedef void (*CGPathApplierFunction) ( void *info, const CGPathElement *element );
If you name your function MyCGPathApplierFunc
, you would declare it like this:
void MyCGPathApplierFunc ( void *info, const CGPathElement *element );
See also CGPathApply
.
CGPath.h
An opaque type that represents an immutable graphics path.
typedef const struct CGPath *CGPathRef;
CGPath.h
An opaque type that represents a mutable graphics path.
typedef struct CGPath *CGMutablePathRef;
CGPath.h
A data structure that provides information about a path element.
struct CGPathElement { CGPathElementType type; CGPoint * points; }; typedef struct CGPathElement CGPathElement;
type
An element type (or operation).
points
An array of one or more points that serve as arguments.
CGPath.h
Options for rendering a path.
enum CGPathDrawingMode { kCGPathFill, kCGPathEOFill, kCGPathStroke, kCGPathFillStroke, kCGPathEOFillStroke }; typedef enum CGPathDrawingMode CGPathDrawingMode;
kCGPathFill
Render the area contained within the path using the non-zero winding number rule.
Available in Mac OS X v10.0 and later.
Declared in CGContext.h
.
kCGPathEOFill
Render the area within the path using the even-odd rule.
Available in Mac OS X v10.0 and later.
Declared in CGContext.h
.
kCGPathStroke
Render a line along the path.
Available in Mac OS X v10.0 and later.
Declared in CGContext.h
.
kCGPathFillStroke
First fill and then stroke the path, using the nonzero winding number rule.
Available in Mac OS X v10.0 and later.
Declared in CGContext.h
.
kCGPathEOFillStroke
First fill and then stroke the path, using the even-odd rule.
Available in Mac OS X v10.0 and later.
Declared in CGContext.h
.
You can pass a path drawing mode constant to the function CGContextDrawPath
to
specify how Quartz should paint a graphics context’s current path.
The type of element found in a path.
enum CGPathElementType { kCGPathElementMoveToPoint, kCGPathElementAddLineToPoint, kCGPathElementAddQuadCurveToPoint, kCGPathElementAddCurveToPoint, kCGPathElementCloseSubpath }; typedef enum CGPathElementType CGPathElementType;
kCGPathElementMoveToPoint
The path element that starts a new subpath.
See the function CGPathMoveToPoint
.
Available in Mac OS X v10.2 and later.
Declared in CGPath.h
.
kCGPathElementAddLineToPoint
The path element that adds a line from the
current point to the specified point. See the function CGPathAddLineToPoint
.
Available in Mac OS X v10.2 and later.
Declared in CGPath.h
.
kCGPathElementAddQuadCurveToPoint
The path element that adds a quadratic curve
from the current point to the specified point. See the function CGPathAddQuadCurveToPoint
.
Available in Mac OS X v10.2 and later.
Declared in CGPath.h
.
kCGPathElementAddCurveToPoint
The path element that adds a cubic curve from
the current point to the specified point. See the function CGPathAddCurveToPoint
.
Available in Mac OS X v10.2 and later.
Declared in CGPath.h
.
kCGPathElementCloseSubpath
The path element that closes and completes
a subpath. See the function CGPathCloseSubpath
.
Available in Mac OS X v10.2 and later.
Declared in CGPath.h
.
For more information about paths, see CGPathRef
.
© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-12-22)