AppleCGContext - UBogun/Xojo-iosLib GitHub Wiki

Inherits from AppleCFObject
Memory leak check: not yet done
Status: fairly advanced, pattern, clip, colorspace, transform and conversion methods missing. Text is mostly deprecated

A CGContext is a graphics class that is used by iOS to draw 2D image on screen. It is exactly what you get addressing the Graphics property of a Xojo iOS control during its paint event. This is because UIView objects push their graphics context to the context stack before drawing into it. If you need to create a different context, you must use one of the other constructors.

While the Xojo iOSGraphics methods give you convenience features to draw graphical shapes in one call (which you still can use furtherone because the CGontextRef is being forwarded transparently to an iOSGraphics object; no subclass needed), you will find many methods that give you more control over the context objects: Usually you start a path or subpath, place the currentpoint and then add one or several graphical shapes, often close the path and then stroke, fill, or strokefill it. In case you are using these functions, please keep in mind you have to create a currentpoint (and a subpath) first with the MoveToPoint method.

Most of the features included here can be accessed with Xojo data types and methods via the iOSGraphics extension module. Please note that Quartz uses a matrix beginning with 0 at the bottom. I have not checked the convenience methods for their alignment with Xojo's coordinate system. If you encounter problems, please let me know. A method for inversing the coordinate system is included in the DrawTiledImage iOSGraphics extension module method.
In general, if you perform a lot of drawing it would be wise to create one instance of AppleCGContext inside your draw routine and address it directly. Or you could risk conversions summming up, reducing your draw performance.

##Constructors Constructor (Context As iOSGraphics): Creates a new AppleCGContext object from a graphics object.

##Properties AllowFontSmoothing As Boolean: If possible and if the fonts are anti-aliased, font will be smoothed when this property is set to true as well as ShouldSmoothFonts.

AllowFontSubpixelPositioning As Boolean: Changes the ability to position fonts based on subpixels in cooperation with ShouldSubpixelPositionFonts.

AllowFontSubpixelQuantization As Boolean: Toggles Font subpixel quantization if ShouldSubpixelQuantizeFonts is True.

BlendMode As CGBlendMode: Lets you choose between a variety of options to blend the context to its background.

CurrentPoint As NSPoint: The current point of the path. If used as setter, this property calls the MoveToPoint method.

Flatness As Double: Controls how accurately curved paths are rendered. Setting the flatness value to less than 1.0 renders highly accurate curves, but lengthens rendering times.

InterpolationQuality As CGInterpolationQuality: Lets you change the interpolation quality of the context.

LineCap As CGLineCap: Lets you choose between butt, round and square line caps for vector graphics drawn into the context.

LineJoin As CGLineJoin: Lets you choose between miter, round and bevel line joins for vector graphics drawn into the context.

MiterLimit As Double: Sets the miter limit for the joins of connected lines.

PathBoundingBox As Xojo.core.Rect (read-only): The smallest rectangle surrounding the current path.

PathIsEmpty As Boolean (read-only): True if the current path has no subpath.

PatternPhase As NSSize: Sets the pattern phase of the context, which has the effect of temporarily changing the pattern matrix of any pattern you draw. Setting this value to 2,3 has the effect of moving the start of pattern cell tiling to the point (2,3) in default user space before drawing.

ShouldSmoothFonts As Boolean: Works together with AllowFontSmoothing to enable font smoothing for the appropriate fonts.

ShouldSubpixelPositionFonts As Boolean: Works together with AllowFontSubpixelPositioning to enable font subpixel positioning for the appropriate fonts.

ShouldSubpixelQuantizeFonts As Boolean: Works together with AllowFontSubpixelQuantize to enable font subpixel positioning for the appropriate fonts.

TextDrawingMode As CGTextDrawingMode: Lets you change the way text is drawn.

##Methods AddArc (x as double, y as double, radius as double, startAngle as Double, EndAngle As Double, ClockWise As boolean): Adds an arc of a circle to the current path, possibly preceded by a straight line segment. X and Y define the center of the arc, radius is the arc's radius in user coordinates, both angles the angles of starting- and aendpount of the arc in radians and clockwise determining the drawing direction.

AddArcToPoint (x1 as double, y1 as double, x2 as double, y2 as double, radius as double): Adds an arc defined by two tangent control points and a radius to the current path.

AddCurveToPoint (cp1x as double, cp1y as double, cp2x as double, cp2y as double, x as double, y as double): Adds a Bezièr curve defined by two control points and the endpoint.

AddEllipse (Rect As NSSRect): Adds an ellipse that fits into the rectangle bounds.

AddLines (Points() as NSPoint, opt. Count As UInteger = 0): Adds Lines defined as an Array Of NSPoint to the current path. Count limits the addition to count array entries.

AddLineToPoint (x as Double, y As Double): Adds a line from the current path endpoint to the new point and sets the current endpoint of the path to the new point.

AddPath (Path As AppleCGPath): Adds a previously created path.

AddQuadCurveToPoint (cpx as double, cpy as double, x as double, y as double): Appends a quadratic Bézier curve from the current point, using a control point and an end point you specify.

AddRect (Rect As NSRect): Adds a rectangle.

AddRects (Rects as AppleArray of NSRect, opt. Count As UInteger = 0): Adds rectangles defined as an Array Of NSRect to the current path. Count limits the addition to count array entries.

BeginPath(): Creates a new empty path in the graphics context. A context can hold only one path. If it already contains one, the old path is disregarded.

ClearRect (Rect As NSRect): Paints a transparent rectangle, effectively clearing its area.

ClosePath(): Closes and terminates the current subpath.

CopyPath() As AppleCGPath: Returns the context’s path object as a sole CGPath.

DrawPath (DrawingMode AS CGPathDrawingMode): Draws the current path with there respective drawing mode and clears the context's current path.

DrawLinearGradient (Gradient As applecgGradient, StartPoint As NSPoint, EndPoint As NSPoint, opt. DrawBeforeStart As Boolean = false, opt. DrawAfterEnd As Boolean = false): Draws a prepared linear gradient from startpoint to endpoint and extends it before startpoint or after endpoint if the boolean values are true.

DrawLinearGradient (Colors() As Color, StartPoint As NSPoint, EndPoint As NSPoint, opt. DrawBeforeStart As Boolean = false, opt. DrawAfterEnd As Boolean = false): Convenience method for the last method, creating a gradient with equal distances on the fly.

DrawLinearGradient (Colors() As Color, Locations() As Double, StartPoint As NSPoint, EndPoint As NSPoint, opt. DrawBeforeStart As Boolean = false, opt. DrawAfterEnd As Boolean = false): Convenience method for the last method, creating a gradient with equal distances on the fly. Extends the gradient creating by a locations() array ranging from 0 to 1 for the distribution of the color stops. Should contain the same number of values as the colors array.

DrawRadialGradient (Gradient As applecgGradient, StartCenter As NSPoint, StartRadius As Double, EndCenter As NSPoint, EndRadius As Double, DrawBeforeStart As Boolean = false, DrawAfterEnd As Boolean = false): Draws a radial gradient starting from StartCenter with StartRadius to EndCenter/Endradius. Like the Linear Gradient, there are two convenience methods:

DrawRadialGradient (Colors() As Color, StartCenter As NSPoint, StartRadius As Double, EndCenter As NSPoint, EndRadius As Double, DrawBeforeStart As Boolean = false, DrawAfterEnd As Boolean = false): See above.

DrawRadialGradient (Colors() As Color, Locations() As Double, StartCenter As NSPoint, StartRadius As Double, EndCenter As NSPoint, EndRadius As Double, DrawBeforeStart As Boolean = false, DrawAfterEnd As Boolean = false): See above.

FillPath (opt. EvenOdd As Boolean = False): Draws the current path as filled path and clears the context's current path. Uses the even-odd-rule if EvenOdd is True.

FillRects (Rects() As NSRect, opt. count As UInteger = 0): Fills an array of rects with the current fillcolor and clears the path.

Flush(): Forces all pending drawing operations in a window context to be rendered immediately to the destination device.

MoveToPoint (x as Double, y as Double): Begins a new subpath at the point you specify.

PathContainsPoint (Point as NSPoint, .opt._ mode as CGPathDrawingMode = CGPathDrawingMode.Fill) As Boolean: True if the current path under the drawingmode rules contains the coordinates of point.

RemoveShadow(): Removes a shadow from the context.

ReplacePathWithStrokedPath(): Replaces the current path by a stroked version of it.

RestoreGraphicsState(): Resets the context's graphics stack to the state before the last SaveGraphicsState command.

SaveGraphicsState(): Pushes a copy of the Context to the graphics stack.

SetLineDash (Phase As Double, Lengths As AppleArray, opt. count as UInteger = 0): Sets a pattern for dashed lines drawn in the context.
Phase specifies how far into the dash pattern the line starts, in units of the user space. For example, passing a value of 3 means the line is drawn with the dash pattern starting at three units from its beginning.
Lengths is an array of values that specify the lengths of the painted segments and unpainted segments, respectively, of the dash pattern—or NIL for no dash pattern.
Count is an optional value with which you can limit the dashes to the number passed. It must therefore not be higher than Lengths.count.

SetLineDash (Phase As Double, Lengths() As double, opt. count as UInteger = 0): A convenience method of the last one to which you can pass a Xojo array of Doubles.

SetShadow (XOffset as Double, YOffset as double, Blur as double, opt. ShadowColor as Color/AppleCGColor): Adds a shadow to the context with the given offset values as blur radius. If no color is defined, Black with 1/3 alpha value is drawn.

StrokeRect (Rect As NSRect, Width As Double): Paints a rectangular path with the specified width.

Synchronize(): Marks a window context for update. Like Window.Invalidate.

##Shared Properties CurrentContext As AppleCGContext (read-only): Should be identical to the iOSGraphics object.