Class: UIBezierPath
Overview
The UIBezierPath class lets you define a path consisting of straight and curved line segments and render that path in your custom views. You use this class initially to specify just the geometry for your path. Paths can define simple shapes such as rectangles, ovals, and arcs or they can define complex polygons that incorporate a mixture of straight and curved line segments. After defining the shape, you can use additional methods of this class to render the path in the current drawing context.
Instance Attribute Summary (collapse)
-
- bounds
readonly
The bounding rectangle of the path.
-
- CGPath
The Core Graphics representation of the path.
-
- currentPoint
readonly
The current point in the graphics path.
-
- empty
readonly
A Boolean value indicating whether the path has any valid elements.
-
- flatness
The factor that determines the rendering accuracy for curved path segments.
-
- lineCapStyle
The shape of the paths end points when stroked.
-
- lineJoinStyle
The shape of the joints between connected segments of a stroked path.
-
- lineWidth
The line width of the path.
-
- miterLimit
The limiting value that helps avoid spikes at junctions between connected line segments.
-
- usesEvenOddFillRule
A Boolean indicating whether the even-odd winding rule is in use for drawing paths.
Class Method Summary (collapse)
-
+ bezierPath
Creates and returns a new UIBezierPath object.
-
+ bezierPathWithArcCenter:radius:startAngle:endAngle:clockwise:
Creates and returns a new UIBezierPath object initialized with an arc of a circle.
-
+ bezierPathWithCGPath:
Creates and returns a new UIBezierPath object initialized with the contents of a Core Graphics path.
-
+ bezierPathWithOvalInRect:
Creates and returns a new UIBezierPath object initialized with an oval path inscribed in the specified rectangle This method creates a closed subpath that approximates the oval using a sequence of Bézier curves.
-
+ bezierPathWithRect:
Creates and returns a new UIBezierPath object initialized with a rectangular path.
-
+ bezierPathWithRoundedRect:byRoundingCorners:cornerRadii:
Creates and returns a new UIBezierPath object initialized with a rounded rectangular path.
-
+ bezierPathWithRoundedRect:cornerRadius:
Creates and returns a new UIBezierPath object initialized with a rounded rectangular path.
Instance Method Summary (collapse)
-
- addArcWithCenter:radius:startAngle:endAngle:clockwise:
Appends an arc to the receiver’s path.
-
- addClip
Intersects the area enclosed by the receiver’s path with the clipping path of the current graphics context and makes the resulting shape the current clipping path.
-
- addCurveToPoint:controlPoint1:controlPoint2:
Appends a cubic Bézier curve to the receiver’s path.
-
- addLineToPoint:
Appends a straight line to the receiver’s path.
-
- addQuadCurveToPoint:controlPoint:
Appends a quadratic Bézier curve to the receiver’s path.
-
- appendPath:
Appends the contents of the specified path object to the receiver’s path.
-
- applyTransform:
Transforms all points in the path using the specified affine transform matrix.
-
- bezierPathByReversingPath
Creates and returns a new bezier path object with the reversed contents of the current path.
-
- closePath
Closes the most recently added subpath.
-
- containsPoint:
Returns a Boolean value indicating whether the area enclosed by the receiver contains the specified point.
-
- fill
Paints the region enclosed by the receiver’s path using the current drawing properties.
-
- fillWithBlendMode:alpha:
Paints the region enclosed by the receiver’s path using the specified blend mode and transparency values.
-
- getLineDash:count:phase:
Retrieves the line-stroking pattern for the path.
-
- moveToPoint:
Moves the receiver’s current point to the specified location.
-
- removeAllPoints
Removes all points from the receiver, effectively deleting all subpaths.
-
- setLineDash:count:phase:
Sets the line-stroking pattern for the path.
-
- stroke
Draws a line along the receiver’s path using the current drawing properties.
-
- strokeWithBlendMode:alpha:
Draws a line along the receiver’s path using the specified blend mode and transparency values.
Methods inherited from NSObject
#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version
Constructor Details
This class inherits a constructor from NSObject
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class NSObject
Instance Attribute Details
- (CGRect) bounds (readonly)
The bounding rectangle of the path. (read-only) The value in this property represents the smallest rectangle that completely encloses all points in the path, including any control points for Bézier and quadratic curves.
- (CGPathRef) CGPath
The Core Graphics representation of the path. This property contains a snapshot of the path at any given point in time. Getting this property returns an immutable path object that you can pass to Core Graphics functions. The path object itself is owned by the UIBezierPath object and is valid only until you make further modifications to the path. You can set the value of this property to a path you built using the functions of the Core Graphics framework. When setting a new path, this method makes a copy of the path you provide.
- (CGPoint) currentPoint (readonly)
The current point in the graphics path. (read-only) The value in this property represents the starting point for new line and curve segments. If the path is currently empty, this property contains the value CGPointZero.
- (Boolean) empty (readonly)
A Boolean value indicating whether the path has any valid elements. (read-only) Valid path elements include commands to move to a specified point, draw a line or curve segment, or close the path. Thus, a path is not considered empty even if all you do is call the moveToPoint: method.
- (Float) flatness
The factor that determines the rendering accuracy for curved path segments. The flatness value measures the largest permissible distance (measured in pixels) between a point on the true curve and a point on the rendered curve. Smaller values result in smoother curves but require more computation time. Larger values result in more jagged curves but are rendered much faster. The default flatness value is 0.6. In most cases, you should not change the flatness value. However, you might increase the flatness value temporarily to minimize the amount of time it takes to draw a shape temporarily (such as during scrolling).
- (CGLineCap) lineCapStyle
The shape of the paths end points when stroked. The line cap style is applied to the start and end points of any open subpaths. This property does not affect closed subpaths. The default line cap style is kCGLineCapButt.
- (CGLineJoin) lineJoinStyle
The shape of the joints between connected segments of a stroked path. The default line join style is kCGLineJoinMiter.
- (Float) lineWidth
The line width of the path. 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.The default line width is 1.0.
- (Float) miterLimit
The limiting value that helps avoid spikes at junctions between connected line segments. The miter limit helps you avoid spikes in paths that use the kCGLineJoinMiter join style. If the ratio of the miter length—that is, 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 is 10, which results in the conversion of miters whose angle at the joint is less than 11 degrees.
- (Boolean) usesEvenOddFillRule
A Boolean indicating whether the even-odd winding rule is in use for drawing paths. If YES, the path is filled using the even-odd rule. If NO, it is filled using the non-zero rule. Both rules are algorithms to determine which areas of a path to fill with the current fill color. A ray is drawn from a point inside a given region to a point anywhere outside the path’s bounds. The total number of crossed path lines (including implicit path lines) and the direction of each path line are then interpreted as follows:For the even-odd rule, if the total number of path crossings is odd, the point is considered to be inside the path and the corresponding region is filled. If the number of crossings is even, the point is considered to be outside the path and the region is not filled.For the non-zero rule, the crossing of a left-to-right path counts as +1 and the crossing of a right-to-left path counts as -1. If the sum of the crossings is nonzero, the point is considered to be inside the path and the corresponding region is filled. If the sum is 0, the point is outside the path and the region is not filled. The default value of this property is NO. For more information about winding rules and how they are applied to subpaths, see Quartz 2D Programming Guide.
Class Method Details
+ (UIBezierPath) bezierPath
Creates and returns a new UIBezierPath object.
+ (UIBezierPath) bezierPathWithArcCenter(center, radius:radius, startAngle:startAngle, endAngle:endAngle, clockwise:clockwise)
Creates and returns a new UIBezierPath object initialized with an arc of a circle. This method creates an open subpath. The created arc lies on the perimeter of the specified circle. When drawn in the default coordinate system, the start and end angles are based on the unit circle shown in Figure 1. For example, specifying a start angle of 0 radians, an end angle of π radians, and setting the clockwise parameter to YES draws the bottom half of the circle. However, specifying the same start and end angles but setting the clockwise parameter set to NO draws the top half of the circle. Figure 1 Angles in the default coordinate systemAfter calling this method, the current point is set to the point on the arc at the end angle of the circle.
+ (UIBezierPath) bezierPathWithCGPath(CGPath)
Creates and returns a new UIBezierPath object initialized with the contents of a Core Graphics path.
+ (UIBezierPath) bezierPathWithOvalInRect(rect)
Creates and returns a new UIBezierPath object initialized with an oval path inscribed in the specified rectangle This method creates a closed subpath that approximates the oval using a sequence of Bézier curves. The path is created in a clockwise direction (relative to the default coordinate system). If the rect parameter specifies a square, the inscribed path is a circle.
+ (UIBezierPath) bezierPathWithRect(rect)
Creates and returns a new UIBezierPath object initialized with a rectangular path. This method creates a closed subpath by starting at the origin of rect and adding line segments in a clockwise direction (relative to the default coordinate system).
+ (UIBezierPath) bezierPathWithRoundedRect(rect, byRoundingCorners:corners, cornerRadii:cornerRadii)
Creates and returns a new UIBezierPath object initialized with a rounded rectangular path. This method creates a closed subpath, proceeding in a clockwise direction (relative to the default coordinate system) as it creates the necessary line and curve segments.
+ (UIBezierPath) bezierPathWithRoundedRect(rect, cornerRadius:cornerRadius)
Creates and returns a new UIBezierPath object initialized with a rounded rectangular path. This method creates a closed subpath, proceeding in a clockwise direction (relative to the default coordinate system) as it creates the necessary line and curve segments.
Instance Method Details
- (Object) addArcWithCenter(center, radius:radius, startAngle:startAngle, endAngle:endAngle, clockwise:clockwise)
Appends an arc to the receiver’s path. This method adds the specified arc beginning at the current point. The created arc lies on the perimeter of the specified circle. When drawn in the default coordinate system, the start and end angles are based on the unit circle shown in Figure 1. For example, specifying a start angle of 0 radians, an end angle of π radians, and setting the clockwise parameter to YES draws the bottom half of the circle. However, specifying the same start and end angles but setting the clockwise parameter set to NO draws the top half of the circle. After calling this method, the current point is set to the point on the arc at the end angle of the circle.
- (Object) addClip
Intersects the area enclosed by the receiver’s path with the clipping path of the current graphics context and makes the resulting shape the current clipping path. This method modifies the visible drawing area of the current graphics context. After calling it, subsequent drawing operations result in rendered content only if they occur within the fill area of the specified path. Important: If you need to remove the clipping region to perform subsequent drawing operations, you must save the current graphics state (using the CGContextSaveGState function) before calling this method. When you no longer need the clipping region, you can then restore the previous drawing properties and clipping region using the CGContextRestoreGState function.The usesEvenOddFillRule property is used to determine whether the even-odd or non-zero rule is used to determine the area enclosed by the path.
- (Object) addCurveToPoint(endPoint, controlPoint1:controlPoint1, controlPoint2:controlPoint2)
Appends a cubic Bézier curve to the receiver’s path. This method appends a cubic Bézier curve from the current point to the end point specified by the endPoint parameter. The two control points define the curvature of the segment. Figure 2 shows an approximation of a cubic Bézier curve given a set of initial points. The exact curvature of the segment involves a complex mathematical relationship between all of the points and is well documented online. Figure 2 A cubic Bézier curve You must set the path’s current point (using the moveToPoint: method or through the previous creation of a line or curve segment) before you call this method. If the path is empty, this method does nothing. After adding the curve segment, this method updates the current point to the value in point.
- (Object) addLineToPoint(point)
Appends a straight line to the receiver’s path. This method creates a straight line segment starting at the current point and ending at the point specified by the point parameter. After adding the line segment, this method updates the current point to the value in point.You must set the path’s current point (using the moveToPoint: method or through the previous creation of a line or curve segment) before you call this method. If the path is empty, this method does nothing.
- (Object) addQuadCurveToPoint(endPoint, controlPoint:controlPoint)
Appends a quadratic Bézier curve to the receiver’s path. This method appends a quadratic Bézier curve from the current point to the end point specified by the endPoint parameter. The relationships between the current point, control point, and end point are what defines the actual curve. Figure 3 shows some examples of quadratic curves and the approximate curve shape based on some sample points. The exact curvature of the segment involves a complex mathematical relationship between the points and is well documented online. Figure 3 Quadratic curve examplesYou must set the path’s current point (using the moveToPoint: method or through the previous creation of a line or curve segment) before you call this method. If the path is empty, this method does nothing. After adding the curve segment, this method updates the current point to the value in point.
- (Object) appendPath(bezierPath)
Appends the contents of the specified path object to the receiver’s path. This method adds the commands used to create the path in bezierPath 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 bezierPath might still cause that effect.
- (Object) applyTransform(transform)
Transforms all points in the path using the specified affine transform matrix. This method applies the specified transform to the path’s points immediately. The modifications made to the path object are permanent. If you do not want to permanently modify a path object, you should consider applying the transform to a copy.
- (UIBezierPath) bezierPathByReversingPath
Creates and returns a new bezier path object with the reversed contents of the current path. 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.
- (Object) closePath
Closes the most recently added subpath. 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.
- (Boolean) containsPoint(point)
Returns a Boolean value indicating whether the area enclosed by the receiver contains the specified point. The receiver contains the specified point if that point is in a portion of a closed subpath that would normally be painted during a fill operation. This method uses the value of the usesEvenOddFillRule property to determine which parts of the subpath would be filled. A point is not considered to be enclosed by the path if it is inside an open subpath, regardless of whether that area would be painted during a fill operation. Therefore, to determine mouse hits on open paths, you must create a copy of the path object and explicitly close any subpaths (using the closePath method) before calling this method.
- (Object) fill
Paints the region enclosed by the receiver’s path using the current drawing properties. This method fills the path using the current fill color and drawing properties. 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).This method automatically saves the current graphics state prior to drawing and restores that state when it is done, so you do not have to save the graphics state yourself.
- (Object) fillWithBlendMode(blendMode, alpha:alpha)
Paints the region enclosed by the receiver’s path using the specified blend mode and transparency values. This method fills the path using the current fill color and drawing properties (plus the specified blend mode and transparency value). 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).This method automatically saves the current graphics state prior to drawing and restores that state when it is done, so you do not have to save the graphics state yourself.
- (Object) getLineDash(pattern, count:count, phase:phase)
Retrieves the line-stroking pattern for the path. 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 the count parameter to allocate an array of floating-point numbers that you can then pass in the second time.
- (Object) moveToPoint(point)
Moves the receiver’s current point to the specified location. This method implicitly ends the current subpath (if any) and sets the current point to the value in the point parameter. When ending the previous subpath, this method does not actually close the subpath. Therefore, the first and last points of the previous subpath are not connected to each other.For many path operations, you must call this method before issuing any commands that cause a line or curve segment to be drawn.
- (Object) removeAllPoints
Removes all points from the receiver, effectively deleting all subpaths.
- (Object) setLineDash(pattern, count:count, phase:phase)
Sets the line-stroking pattern for the path.
- (Object) stroke
Draws a line along the receiver’s path using the current drawing properties. The drawn line is centered on the path with its sides parallel to the path segment. This method applies the current drawing properties to the rendered path.This method automatically saves the current graphics state prior to drawing and restores that state when it is done, so you do not have to save the graphics state yourself.
- (Object) strokeWithBlendMode(blendMode, alpha:alpha)
Draws a line along the receiver’s path using the specified blend mode and transparency values. The drawn line is centered on the path with its sides parallel to the path segment. This method applies the current stroke color and drawing properties (plus the specified blend mode and transparency value) to the rendered path.This method automatically saves the current graphics state prior to drawing and restores that state when it is done, so you do not have to save the graphics state yourself.