Image Files

UIImage can read a stored file, so if an image does not need to be created dynamically, but has already been created before your app runs, then drawing may be as simple as providing an image file as a resource inside your app itself. When an image file is to be included inside your app, iOS has a special affinity for PNG files, and you should prefer them whenever possible. (The converse operation, saving image data as an image file, is discussed in Chapter 23.)

A pre-existing image file in your app’s bundle is most commonly obtained in code through the UIImage initializer init(named:), which takes a string and returns a UIImage wrapped in an Optional, in case the image doesn’t exist. This method looks in two places for the image:

Asset catalog

We look in the asset catalog for an image set with the supplied name. The name is case-sensitive.

Top level of app bundle

We look at the top level of the app’s bundle for an image file with the supplied name. The name is case-sensitive and should include the file extension; if it doesn’t, .png is assumed.

When calling init(named:), an asset catalog is searched before the top level of the app’s bundle. If there are multiple asset catalogs, they are all searched, but the search order is indeterminate, so avoid multiple image sets with the same name.

With init(named:), the image data may be cached in memory, and if you ask for the same image by calling init(named:) again later, the cached data may be supplied immediately. Caching is usually good, because decoding the image on disk into usable bitmap data is expensive.

Nevertheless, sometimes caching may not be what you want; if you know you’re just going to fetch the image once and put it into the interface immediately, caching might represent an unnecessary strain on your app’s memory. If so, there’s another way: you can read an image file from your app bundle (not the asset catalog) directly and without caching, by calling init(contentsOfFile:), which expects a pathname string. To obtain that pathname string, you can get a reference to your app’s bundle with Bundle.main, and Bundle then provides instance methods for getting the pathname of a file within the bundle, such as path(forResource:ofType:).

class MyView: UIView {
    var image : UIImage!
    override func traitCollectionDidChange(_ prevtc: UITraitCollection?) {
        super.traitCollectionDidChange(prevtc)
        self.setNeedsDisplay() // causes draw(_:) to be called
    }
    override func draw(_ rect: CGRect) {
        if var im = self.image {
            if let asset = self.image.imageAsset {
                im = asset.image(with:self.traitCollection)
            }
            im.draw(at:.zero)
        }
    }
}

let tcreg = UITraitCollection(verticalSizeClass: .regular)
let tccom = UITraitCollection(verticalSizeClass: .compact)
let moods = UIImageAsset()
let frowney = UIImage(named:"frowney")!
let smiley = UIImage(named:"smiley")!
moods.register(frowney, with: tcreg)
moods.register(smiley, with: tccom)

Image Views

When you want an image to appear in your interface, not inside a button or other interface object but purely as an image, you’ll probably hand it to an image view — a UIImageView — which has the most knowledge and flexibility with regard to displaying images and is intended for this purpose. An image view is the displayer of images par excellence. In code, just set the image as the image view’s image. In the nib editor, drag the image from the Image library onto an image view or set its image through the Image pop-up menu, or drag an image from the Image library directly into a plain UIView to get a UIImageView whose image is that image.

A UIImageView can actually have two images, one assigned to its image property and the other assigned to its highlightedImage property; the value of the UIImageView’s isHighlighted property dictates which of the two is displayed at any given moment. A UIImageView does not automatically highlight itself merely because the user taps it, the way a button does. However, there are certain situations where a UIImageView will respond to the highlighting of its surroundings; within a table view cell, for instance, a UIImageView will show its highlighted image when the cell is highlighted (Chapter 8).

A UIImageView is a UIView, so it can have a background color in addition to its image, it can have an alpha (transparency) value, and so forth (see Chapter 1). An image may have areas that are transparent, and a UIImageView will respect this, so an image of any shape can appear. A UIImageView without a background color is invisible except for its image, so the image simply appears in the interface, without the user being aware that it resides in a rectangular host. A UIImageView without an image and without a background color is invisible, so you could start with an empty UIImageView in the place where you will later need an image and subsequently assign the image in code. You can assign a new image to substitute one image for another, or set the image view’s image property to nil to remove its image.

How a UIImageView draws its image depends upon the setting of its contentMode property (UIView.ContentMode); this property is actually inherited from UIView, and I’ll discuss its more general purpose later in this chapter. .scaleToFill means the image’s width and height are set to the width and height of the view, filling the view completely even if this alters the image’s aspect ratio; .center means the image is drawn centered in the view without altering its size; and so on. Most commonly you’ll use .scaleAspectFit or .scaleAspectFill; they both keep the image’s aspect ratio while filling the image view. The difference is that .scaleAspectFill fills the image view in both dimensions, permitting some of the image to fall outside the image view. The best way to get a feel for the meanings of the various contentMode settings is to experiment with an image view in the nib editor: in the image view’s Attributes inspector, change the Content Mode pop-up menu to see where and how the image draws itself.

You should also pay attention to a UIImageView’s clipsToBounds property; if it is false, its image, even if it is larger than the image view and even if it is not scaled down by the contentMode, may be displayed in its entirety, extending beyond the image view itself.

When creating a UIImageView in code, you can take advantage of a convenience initializer, init(image:). The default contentMode is .scaleToFill, but the image is not initially scaled; rather, the image view itself is sized to match its image. You will still probably need to position the UIImageView correctly in its superview. In this example, I’ll put a picture of the planet Mars in the center of the app’s interface (Figure 2-1; for the CGRect center property, see Appendix B):

let iv = UIImageView(image:UIImage(named:"Mars"))
self.view.addSubview(iv)
iv.center = iv.superview!.bounds.center
iv.frame = iv.frame.integral

Figure 2-1. Mars appears in my interface

What happens to the size of an existing UIImageView when you assign a new image to it depends on whether the image view is using autolayout. Under autolayout, the size of the image becomes the image view’s intrinsicContentSize, so the image view adopts the image’s size unless other constraints prevent.

An image view automatically acquires its alignmentRectInsets (see Chapter 1) from its image’s alignmentRectInsets. If you’re going to be aligning the image view to some other object using autolayout, you can attach appropriate alignmentRectInsets to the image that the image view will display, and the image view will do the right thing. To do so in code, derive a new image by calling the original image’s withAlignmentRectInsets(_:) method; alternatively, you can set an image’s alignmentRectInsets in the asset catalog (use the four Alignment fields).

Resizable Images

Certain interface contexts require an image that can be coherently resized to any desired proportions. A custom image that serves as the track of a slider or progress view (Chapter 13) must be able to fill a space of any length. Such an image is called a resizable image.

To make a resizable image in code, start with a normal image and call its resizableImage(withCapInsets:resizingMode:) method. The capInsets: argument is a UIEdgeInsets, whose components represent distances inward from the edges of the image. In a context larger than the image, a resizable image can behave in one of two ways, depending on the resizingMode: value (UIImage.ResizingMode):

.tile

The interior rectangle of the inset area is tiled (repeated) in the interior; each edge is formed by tiling the corresponding edge rectangle outside the inset area. The four corner rectangles outside the inset area are drawn unchanged.

.stretch

The interior rectangle of the inset area is stretched once to fill the interior; each edge is formed by stretching the corresponding edge rectangle outside the inset area once. The four corner rectangles outside the inset area are drawn unchanged.

In these examples, assume that self.iv is a UIImageView with absolute height and width (so that it won’t adopt the size of its image) and with a contentMode of .scaleToFill (so that the image will exhibit resizing behavior). First, I’ll illustrate tiling an entire image (Figure 2-2); note that the capInsets: is .zero, meaning no insets at all:

let mars = UIImage(named:"Mars")!
let marsTiled =
    mars.resizableImage(withCapInsets:.zero, resizingMode: .tile)
self.iv.image = marsTiled

Figure 2-2. Tiling the entire image of Mars

Now we’ll tile the interior of the image, changing the capInsets: argument from the previous code (Figure 2-3):

let marsTiled = mars.resizableImage(withCapInsets:
    UIEdgeInsets(
        top: mars.size.height / 4.0,
        left: mars.size.width / 4.0,
        bottom: mars.size.height / 4.0,
        right: mars.size.width / 4.0
    ), resizingMode: .tile)

Figure 2-3. Tiling the interior of Mars

Next, I’ll illustrate stretching. We’ll start by changing just the resizingMode: from the previous code (Figure 2-4):

let marsTiled = mars.resizableImage(withCapInsets:
    UIEdgeInsets(
        top: mars.size.height / 4.0,
        left: mars.size.width / 4.0,
        bottom: mars.size.height / 4.0,
        right: mars.size.width / 4.0
    ), resizingMode: .stretch)

Figure 2-4. Stretching the interior of Mars

A common stretching strategy is to make almost half the original image serve as a cap inset, leaving just a tiny rectangle in the center that must stretch to fill the entire interior of the resulting image (Figure 2-5):

let marsTiled = mars.resizableImage(withCapInsets:
    UIEdgeInsets(
        top: mars.size.height / 2.0 - 1,
        left: mars.size.width / 2.0 - 1,
        bottom: mars.size.height / 2.0 - 1,
        right: mars.size.width / 2.0 - 1
    ), resizingMode: .stretch)

Figure 2-5. Stretching a few pixels at the interior of Mars

In the preceding example, if the image view’s contentMode is .scaleAspectFill, and if the image view’s clipsToBounds is true, we get a sort of gradient effect, because the top and bottom of the stretched image are outside the image view and aren’t drawn (Figure 2-6).

Figure 2-6. Mars, stretched and clipped

Alternatively, you can configure a resizable image in the asset catalog. It is often the case that a particular image will be used in your app chiefly as a resizable image, and always with the same capInsets: and resizingMode:, so it makes sense to configure this image once rather than having to repeat the same code.

To configure an image in an asset catalog as a resizable image, select the image and, in the Slicing section of the Attributes inspector, change the Slices pop-up menu to Horizontal, Vertical, or Horizontal and Vertical. When you do this, additional interface appears. You can specify the resizingMode with the Center pop-up menu. You can work numerically, or click Show Slicing at the lower right of the canvas and work graphically.

This feature is even more powerful than resizableImage(withCapInsets:resizingMode:). It lets you specify the end caps separately from the tiled or stretched region, with the rest of the image being sliced out. In Figure 2-7, the dark areas at the top left, top right, bottom left, and bottom right will be drawn as is; the narrow bands will be stretched, and the small rectangle at the top center will be stretched to fill most of the interior; but the rest of the image, the large central area covered by a sort of gauze curtain, will be omitted entirely. The result is shown in Figure 2-8.

Figure 2-7. Mars, sliced in the asset catalog

Figure 2-8. Mars, sliced and stretched

Transparency Masks

Certain interface contexts, such as buttons and button-like interface objects, want to treat an image as a transparency mask, also known as a template. This means that the image color values are ignored, and only the transparency (alpha) values of each pixel matter. The image shown on the screen is formed by combining the image’s transparency values with a single tint color.

The way an image will be treated is a property of the image, its renderingMode. This property is read-only; to change it in code, start with an image and generate a new image with a different rendering mode, by calling its withRenderingMode(_:) method.

The rendering mode values (UIImage.RenderingMode) are:

• .automatic

• .alwaysOriginal

• .alwaysTemplate

The default is .automatic, which means that the image is drawn normally except in those particular contexts that want to treat it as a transparency mask. With the other two rendering mode values, you can force an image to be drawn normally, even in a context that would usually treat it as a transparency mask, or you can force an image to be treated as a transparency mask, even in a context that would otherwise treat it normally.

To accompany this feature, iOS gives every UIView a tintColor, which will be used to tint any template images it contains. Moreover, this tintColor by default is inherited down the view hierarchy, and indeed throughout the entire app, starting with the window (Chapter 1). Assigning your app’s main window a tint color is probably one of the few changes you’ll make to the window; otherwise, your app adopts the system’s blue tint color. (Alternatively, if you’re using a main storyboard, set the Global Tint color in the File inspector.) Individual views can be assigned their own tint color, which is inherited by their subviews. Figure 2-9 shows two buttons displaying the same background image, one in normal rendering mode, the other in template rendering mode, in an app whose window tint color is red. (I’ll say more about template images and tintColor in Chapter 13.)

Figure 2-9. One image in two rendering modes

You can assign an image a rendering mode in the asset catalog. Select the image set in the asset catalog, and use the Render As pop-up menu in the Attributes inspector to set the rendering mode to Default (.automatic), Original Image (.alwaysOriginal), or Template Image (.alwaysTemplate). This is an excellent approach whenever you have an image that you will use primarily in a specific rendering mode, because it saves you from having to remember to set that rendering mode in code every time you fetch the image. Instead, any time you call init(named:), this image arrives with the rendering mode already set.

The symbol images, in general, have no color of their own, so in effect they are always template images. New in iOS 14, however, about 150 of the symbol images are multicolor images. (The other symbol images are called monochrome.) Multicolor symbols images possess inherent colors of their own. Some have a single color; most of them have two. In a template environment, such as a button, if you apply the .alwaysOriginal rendering mode to a multicolor symbol image, its inherent colors will appear.

Starting in iOS 13, a tint color can be applied to a UIImage directly; call withTintColor(_:) or withTintColor(_:renderingMode:). This is useful particularly when you want to draw a symbol image or a template image in a context where there is no inherited tint color (such as a graphics context). Nonetheless, I find the behavior of these methods rather weird:

Original images become template images

If you apply withTintColor to an ordinary image, it is then treated as a template image — even if you also set the rendering mode to .alwaysOriginal.

Template images may ignore the assigned tint color

If you apply withTintColor(_:) to a template image — because it’s a symbol image, or because you said .alwaysTemplate, or because we’re in a context that treats an image as a transparency mask — then if you assign it into an view with a tintColor of its own, the tint color you specify is ignored! The view’s tint color wins. If you want the tint color you specify to be obeyed, you must also set the rendering mode to .alwaysOriginal.

For example, the following code specifically sets a symbol image’s tint color to red; nevertheless, what appears on the screen is a blue symbol image (because the default image view tintColor is blue):

let im = UIImage(systemName:"circle.fill")?.withTintColor(.red)
let iv = UIImageView(image:im)
self.view.addSubview(iv)

To get a red symbol image, you have to say this:

let im = UIImage(systemName:"circle.fill")?.withTintColor(.red,
    renderingMode: .alwaysOriginal) // *
let iv = UIImageView(image:im)
self.view.addSubview(iv)

(Applying a tint color directly to a multicolor symbol image turns it monochrome, even if you also apply the .alwaysOriginal rendering mode.)

Reversible Images

The entire interface is automatically reversed when your app runs on a system for which your app is localized if the system language is right-to-left. In general, this probably won’t affect your images. The runtime assumes that you don’t want images to be reversed when the interface is reversed, so its default behavior is to leave them alone.

Nevertheless, you might want an image to be reversed when the interface is reversed. Suppose you’ve drawn an arrow pointing in the direction from which new interface will arrive when the user taps a button. If the button pushes a view controller onto a navigation interface, that direction is from the right on a left-to-right system, but from the left on a right-to-left system. This image has directional meaning within the app’s own interface; it needs to flip horizontally when the interface is reversed.

To make this possible in code, call the image’s imageFlippedForRightToLeftLayoutDirection method and use the resulting image in your interface. On a left-to-right system, the normal image will be used; on a right-to-left system, a reversed variant of the image will be created and used automatically. You can override this behavior, even if the image is reversible, for a particular UIView displaying the image, such as a UIImageView, by setting that view’s semanticContentAttribute to prevent mirroring.

You can make the same determination for an image in the asset catalog using the Direction pop-up menu (choose one of the Mirrors options). Moreover, the layout direction (as I mentioned in Chapter 1) is a trait, so you can have pairs of images to be used under left-to-right or right-to-left layout. The easy way to configure such pairs is to choose Both in the asset catalog’s Direction pop-up menu; now there are left-to-right and right-to-left image slots where you can place your images. Alternatively, you can register the paired images with a UIImageAsset in code, as I demonstrated earlier in this chapter.

You can also force an image to be flipped horizontally without regard to layout direction or semantic content attribute by calling its withHorizontallyFlippedOrientation method.

Drawing on Demand

There are four ways of drawing on demand, and I’ll start with those. First, I’ll implement a UIView subclass’s draw(_:), using UIKit to draw into the current context, which Cocoa has already prepared for me:

override func draw(_ rect: CGRect) {
    let p = UIBezierPath(ovalIn: CGRect(0,0,100,100))
    UIColor.blue.setFill()
    p.fill()
}

Now I’ll do the same thing with Core Graphics; this will require that I first get a reference to the current context:

override func draw(_ rect: CGRect) {
    let con = UIGraphicsGetCurrentContext()!
    con.addEllipse(in:CGRect(0,0,100,100))
    con.setFillColor(UIColor.blue.cgColor)
    con.fillPath()
}

Next, I’ll implement a CALayer delegate’s draw(_:in:). In this case, we’re handed a reference to a context, but it isn’t the current context. So I have to make it the current context in order to use UIKit (and I must remember to stop making it the current context when I’m done drawing):

override func draw(_ layer: CALayer, in con: CGContext) {
    UIGraphicsPushContext(con)
    let p = UIBezierPath(ovalIn: CGRect(0,0,100,100))
    UIColor.blue.setFill()
    p.fill()
    UIGraphicsPopContext()
}

To use Core Graphics in a CALayer delegate’s draw(_:in:), I simply keep referring to the context I was handed:

override func draw(_ layer: CALayer, in con: CGContext) {
    con.addEllipse(in:CGRect(0,0,100,100))
    con.setFillColor(UIColor.blue.cgColor)
    con.fillPath()
}

Drawing a UIImage

Now I’ll make a UIImage of a blue circle. We can do this at any time (we don’t need to wait for some particular method to be called) and in any class (we don’t need to be in a UIView subclass).

To construct a UIImage in code, use a UIGraphicsImageRenderer. The basic technique is to create the renderer and call its image method to obtain the UIImage, handing it a function containing your drawing instructions.

In this example, I draw my image using UIKit:

let r = UIGraphicsImageRenderer(size:CGSize(100,100))
let im = r.image { _ in
    let p = UIBezierPath(ovalIn: CGRect(0,0,100,100))
    UIColor.blue.setFill()
    p.fill()
}
// im is the blue circle image, do something with it here ...

And here’s the same thing using Core Graphics:

let r = UIGraphicsImageRenderer(size:CGSize(100,100))
let im = r.image { _ in
    let con = UIGraphicsGetCurrentContext()!
    con.addEllipse(in:CGRect(0,0,100,100))
    con.setFillColor(UIColor.blue.cgColor)
    con.fillPath()
}
// im is the blue circle image, do something with it here ...

In those examples, we’re calling UIGraphicsImageRenderer’s init(size:) and accepting its default configuration, which is usually what’s wanted. To configure the image context further, call the UIGraphicsImageRendererFormat class method default, configure the format through its properties, and pass it to UIGraphicsImageRenderer’s init(size:format:). Those properties are:

opaque

By default, false; the image context is transparent. If true, the image context is opaque and has a black background, and the resulting image has no transparency.

scale

By default, the same as the scale of the main screen, UIScreen.main.scale. This means that the resolution of the resulting image will be correct for the device we’re running on.

preferredRange

The color gamut. Your choices are (UIGraphicsImageRendererFormat.Range):

• .standard

• .extended

• .automatic (same as .extended if we’re running on a device that supports “wide color”)

A single parameter (ignored in the preceding examples) arrives into the UIGraphicsImageRenderer’s image function. It’s a UIGraphicsImageRendererContext. This provides access to the configuring UIGraphicsImageRendererFormat (its format). It also lets you obtain the graphics context (its cgContext); you can alternatively get this by calling UIGraphicsGetCurrentContext, and the preceding code does so, for consistency with the other ways of drawing. In addition, the UIGraphicsImageRendererContext can hand you a copy of the image as drawn up to this point (its currentImage); also, it implements a few basic drawing commands of its own.

Graphics Context Settings

As you draw in a graphics context, the drawing obeys the context’s current settings. For this reason, the procedure is always to configure the context’s settings first, and then draw. To draw a red line and then a blue line, you would first set the context’s line color to red, and draw the first line; then you’d set the context’s line color to blue, and draw the second line. To the eye, it appears that the redness and blueness are properties of the individual lines, but in fact, at the time you draw each line, line color is a feature of the entire graphics context.

A graphics context has, at every moment, a state, which is the sum total of all its current settings; the way a piece of drawing looks is the result of what the graphics context’s state was at the moment that piece of drawing was performed. To help you manipulate entire states, the graphics context provides a stack for holding states. Every time you call saveGState, the context pushes the current state onto the stack; every time you call restoreGState, the context retrieves the state from the top of the stack (the state that was most recently pushed) and sets itself to that state. A common pattern is:

1. Call saveGState.

2. Manipulate the context’s settings, changing its state.

3. Draw.

4. Call restoreGState to restore the state and the settings to what they were before you manipulated them.

You do not have to do this before every manipulation of a context’s settings, because settings don’t necessarily conflict with one another or with past settings. You can set the context’s line color to red and then later to blue without any difficulty. But in certain situations you do want your manipulation of settings to be undoable, and I’ll point out several such situations later in this chapter.

Many of the settings that constitute a graphics context’s state, and that determine the behavior and appearance of drawing performed at that moment, are similar to those of any drawing application. Here are some of them, along with some of the commands that determine them (and some UIKit properties and methods that call them):

Line thickness and dash style

setLineWidth(_:), setLineDash(phase:lengths:)
UIBezierPath lineWidth, setLineDash(_:count:phase:)

Line end-cap style and join style

setLineCap(_:), setLineJoin(_:), setMiterLimit(_:)
UIBezierPath lineCapStyle, lineJoinStyle, miterLimit

Line color or pattern

setStrokeColor(_:), setStrokePattern(_:colorComponents:)
UIColor setStroke

Fill color or pattern

setFillColor(_:), setFillPattern(_:colorComponents:)
UIColor setFill

Shadow

setShadow(offset:blur:color:)

Overall transparency and compositing

setAlpha(_:), setBlendMode(_:)

Anti-aliasing

setShouldAntialias(_:)

Additional settings include:

Clipping area

Drawing outside the clipping area is not physically drawn.

Transform (or “CTM,” for “current transform matrix”)

Changes how points that you specify in subsequent drawing commands are mapped onto the physical space of the canvas.

Many of these settings will be illustrated by examples later in this chapter.

Paths and Shapes

By issuing a series of instructions for moving an imaginary pen, you construct a path, tracing it out from point to point. You must first tell the pen where to position itself, setting the current point; after that, you issue commands telling the pen how to trace out each subsequent piece of the path, one by one. Each new piece of the path starts by default at the current point; its end becomes the new current point.

A path can be compound, meaning that it consists of multiple independent pieces. A single path might consist of two separate closed shapes: say, a rectangle and a circle. When you call move(to:) in the middle of constructing a path, you pick up the imaginary pen and move it to a new location without tracing a segment, preparing to start an independent piece of the same path.

If you’re worried, as you begin to trace out a path, that there might be an existing path and that your new path might be seen as a compound part of that existing path, you can call beginPath to specify that this is a different path; many of Apple’s examples do this, but in practice I usually do not find it necessary.

Here are some path-drawing commands you’re likely to give:

Position the current point

move(to:)

Trace a line

addLine(to:), addLines(between:)

Trace a rectangle

addRect(_:), addRects(_:)

Trace an ellipse or circle

addEllipse(in:)

Trace an arc

addArc(tangent1End:tangent2End:radius:)

Trace a Bezier curve with one or two control points

addQuadCurve(to:control:), addCurveTo(to:control1:control2:)

Close the current path

closePath. This appends a line from the last point of the path to the first point. There’s no need to do this if you’re about to fill the path, since it’s done for you.

Note that a path, in and of itself, does not constitute drawing! First you provide a path; then you draw. Drawing can mean stroking the path or filling the path, or both. Again, this should be a familiar notion from certain drawing applications. The important thing is that stroking or filling a path clears the path. That path is now gone and we’re ready to begin constructing a new path if desired:

Stroke or fill the current path (and clear the path)

strokePath, fillPath(using:), drawPath. Use drawPath if you want both to fill and to stroke the path in a single command, because if you merely stroke it first with strokePath, the path is cleared and you can no longer fill it. There are also some convenience functions that create a path from a CGRect or similar and stroke or fill it, in a single move:

• stroke(_:), strokeLineSegments(between:)

• fill(_:)

• strokeEllipse(in:)

• fillEllipse(in:)

If a path needs to be reused or shared, you can encapsulate it as a CGPath. Like CGContext, CGPath and its mutable partner CGMutablePath are treated as class types under “renamification,” and the global C functions that manipulate them are treated as methods. You can copy the graphics context’s current path using the CGContext path method, or you can create a new CGMutablePath and construct the path using various functions, such as move(to:transform:) and addLine(to:transform:), that parallel the CGContext path-construction functions. Also, there are ways to create a path based on simple geometry or on an existing path:

• init(rect:transform:)

• init(ellipseIn:transform:)

• init(roundedRect:cornerWidth:cornerHeight:transform:)

• copy(strokingWithWidth:lineCap:lineJoin:miterLimit:transform:)

• copy(dashingWithPhase:lengths:transform:)

• copy(using:) (takes a pointer to a CGAffineTransform)

To illustrate the typical use of path-drawing commands, I’ll generate the up-pointing arrow shown in Figure 2-17. This might not be the best way to create the arrow, and I’m deliberately avoiding use of the convenience functions, but it’s clear and shows a nice basic variety of typical commands:

// obtain the current graphics context
let con = UIGraphicsGetCurrentContext()!
// draw a black (by default) vertical line, the shaft of the arrow
con.move(to:CGPoint(100, 100))
con.addLine(to:CGPoint(100, 19))
con.setLineWidth(20)
con.strokePath()
// draw a red triangle, the point of the arrow
con.setFillColor(UIColor.red.cgColor)
con.move(to:CGPoint(80, 25))
con.addLine(to:CGPoint(100, 0))
con.addLine(to:CGPoint(120, 25))
con.fillPath()
// snip a triangle out of the shaft by drawing in Clear blend mode
con.move(to:CGPoint(90, 101))
con.addLine(to:CGPoint(100, 90))
con.addLine(to:CGPoint(110, 101))
con.setBlendMode(.clear)
con.fillPath()

Figure 2-17. A simple path drawing

The UIKit class UIBezierPath is actually a wrapper for CGPath; the wrapped path is its cgPath property. It provides methods parallel to the CGContext and CGPath functions for constructing a path, such as:

• init(rect:)

• init(ovalIn:)

• init(roundedRect:cornerRadius:)

• move(to:)

• addLine(to:)

• addArc(withCenter:radius:startAngle:endAngle:clockwise:)

• addQuadCurve(to:controlPoint:)

• addCurve(to:controlPoint1:controlPoint2:)

• close

When you call the UIBezierPath instance methods fill or stroke or fill(with:alpha:) or stroke(with:alpha:), the current graphics context settings are saved, the wrapped CGPath is made the current graphics context’s path and stroked or filled, and the current graphics context settings are restored.

Using UIBezierPath together with UIColor, we could rewrite our arrow-drawing routine entirely with UIKit methods:

let p = UIBezierPath()
// shaft
p.move(to:CGPoint(100,100))
p.addLine(to:CGPoint(100, 19))
p.lineWidth = 20
p.stroke()
// point
UIColor.red.set()
p.removeAllPoints()
p.move(to:CGPoint(80,25))
p.addLine(to:CGPoint(100, 0))
p.addLine(to:CGPoint(120, 25))
p.fill()
// snip
p.removeAllPoints()
p.move(to:CGPoint(90,101))
p.addLine(to:CGPoint(100, 90))
p.addLine(to:CGPoint(110, 101))
p.fill(with:.clear, alpha:1.0)

There’s no savings of code here over calling Core Graphics functions, so your choice of Core Graphics or UIKit is a matter of taste.

Clipping

A path can be used to mask out areas, protecting them from future drawing. This is called clipping. By default, a graphics context’s clipping region is the entire graphics context, meaning that you can draw anywhere within the context.

The clipping area is a feature of the context as a whole, and any new clipping area is applied by intersecting it with the existing clipping area. To restore your clipping area to the default, call resetClip.

To illustrate, I’ll rewrite the code that generated our original arrow (Figure 2-17) to use clipping instead of a blend mode to “punch out” the triangular notch in the tail of the arrow. This is a little tricky, because what we want to clip to is not the region inside the triangle but the region outside it. To express this, we’ll use a compound path consisting of more than one closed area — the triangle, and the drawing area as a whole (which we can obtain as the context’s boundingBoxOfClipPath).

Both when filling a compound path and when using it to express a clipping region, the system follows one of two rules:

Winding rule

The fill or clipping area is denoted by an alternation in the direction (clockwise or counterclockwise) of the path demarcating each region.

Even-odd rule (EO)

The fill or clipping area is denoted by a simple count of the paths demarcating each region.

Our situation is extremely simple, so it’s easier to use the even-odd rule:

// obtain the current graphics context
let con = UIGraphicsGetCurrentContext()!
// punch triangular hole in context clipping region
con.move(to:CGPoint(90, 100))
con.addLine(to:CGPoint(100, 90))
con.addLine(to:CGPoint(110, 100))
con.closePath()
con.addRect(con.boundingBoxOfClipPath)
con.clip(using:.evenOdd)
// draw the vertical line
con.move(to:CGPoint(100, 100))
con.addLine(to:CGPoint(100, 19))
con.setLineWidth(20)
con.strokePath()
// draw the red triangle, the point of the arrow
con.setFillColor(UIColor.red.cgColor)
con.move(to:CGPoint(80, 25))
con.addLine(to:CGPoint(100, 0))
con.addLine(to:CGPoint(120, 25))
con.fillPath()

The UIBezierPath clipping commands are usesEvenOddFillRule and addClip.

Gradients

Gradients can range from the simple to the complex. A simple gradient (which is all I’ll describe here) is determined by a color at one endpoint along with a color at the other endpoint, plus (optionally) colors at intermediate points; the gradient is then painted either linearly between two points or radially between two circles. You can’t use a gradient as a path’s fill color, but you can restrict a gradient to a path’s shape by clipping, which will sometimes be good enough.

To illustrate, I’ll redraw our arrow, using a linear gradient as the “shaft” of the arrow (Figure 2-18):

// obtain the current graphics context
let con = UIGraphicsGetCurrentContext()!
// punch triangular hole in context clipping region
con.move(to:CGPoint(10, 100))
con.addLine(to:CGPoint(20, 90))
con.addLine(to:CGPoint(30, 100))
con.closePath()
con.addRect(con.boundingBoxOfClipPath)
con.clip(using: .evenOdd)
// draw the vertical line, add its shape to the clipping region
con.move(to:CGPoint(20, 100))
con.addLine(to:CGPoint(20, 19))
con.setLineWidth(20)
con.replacePathWithStrokedPath()
con.clip()
// draw the gradient
let locs : [CGFloat] = [ 0.0, 0.5, 1.0 ]
let colors : [CGFloat] = [
    0.8, 0.4, // starting color, transparent light gray
    0.1, 0.5, // intermediate color, darker less transparent gray
    0.8, 0.4, // ending color, transparent light gray
]
let sp = CGColorSpaceCreateDeviceGray()
let grad = CGGradient(
    colorSpace:sp, colorComponents: colors, locations: locs, count: 3)!
con.drawLinearGradient(grad,
    start: CGPoint(89,0), end: CGPoint(111,0), options:[])
con.resetClip() // done clipping
// draw the red triangle, the point of the arrow
con.setFillColor(UIColor.red.cgColor)
con.move(to:CGPoint(80, 25))
con.addLine(to:CGPoint(100, 0))
con.addLine(to:CGPoint(120, 25))
con.fillPath()

Figure 2-18. Drawing with a gradient

The call to replacePathWithStrokedPath pretends to stroke the current path, using the current line width and other line-related context state settings, but then creates a new path representing the outside of that stroked path. Instead of a thick line we now have a rectangular region that we can use as the clip region.

We then create the gradient and paint it. The procedure is verbose but simple; everything is boilerplate. We describe the gradient as an array of locations on the continuum between one endpoint (0.0) and the other endpoint (1.0), along with the color components of the colors corresponding to each location; in this case, I want the gradient to be lighter at the edges and darker in the middle, so I use three locations, with the dark one at 0.5. We must also supply a color space; this will tell the gradient how to interpret our color components. Finally, we create the gradient and paint it into place.

(See also the discussion of gradient CIFilters earlier in this chapter. For yet another way to create a simple gradient, see the discussion of CAGradientLayer in the next chapter.)

Colors and Patterns

A color is a CGColor. CGColor is not difficult to work with, and can be converted to and from a UIColor through UIColor’s init(cgColor:) and its cgColor property.

When the user interface style (light or dark mode) changes, your draw(_:) override is called and UITraitCollection.current is set for you, so any dynamic UIColors you use while drawing will be correct for the current interface style. But there’s no such thing as a dynamic CGColor, so if you’re using CGColor in some other situation, you might need to trigger a redraw manually. For an example, see “Interface Style”.

A pattern is also a kind of color. You can create a pattern color and stroke or fill with it. The simplest way is to draw a minimal tile of the pattern into a UIImage and create the color by calling UIColor’s init(patternImage:). To illustrate, I’ll create a pattern of horizontal stripes and use it to paint the point of the arrow instead of a solid red color (Figure 2-19):

// create the pattern image tile
let r = UIGraphicsImageRenderer(size:CGSize(4,4))
let stripes = r.image { ctx in
    let imcon = ctx.cgContext
    imcon.setFillColor(UIColor.red.cgColor)
    imcon.fill(CGRect(0,0,4,4))
    imcon.setFillColor(UIColor.blue.cgColor)
    imcon.fill(CGRect(0,0,4,2))
}
// paint the point of the arrow with it
let stripesPattern = UIColor(patternImage:stripes)
stripesPattern.setFill()
let p = UIBezierPath()
p.move(to:CGPoint(80,25))
p.addLine(to:CGPoint(100,0))
p.addLine(to:CGPoint(120,25))
p.fill()

Figure 2-19. A patterned fill

The Core Graphics equivalent, CGPattern, is considerably more powerful, but also much more elaborate:

con.saveGState()
let sp2 = CGColorSpace(patternBaseSpace:nil)!
con.setFillColorSpace(sp2)
let drawStripes : CGPatternDrawPatternCallback = { _, con in
    con.setFillColor(UIColor.red.cgColor)
    con.fill(CGRect(0,0,4,4))
    con.setFillColor(UIColor.blue.cgColor)
    con.fill(CGRect(0,0,4,2))
}
var callbacks = CGPatternCallbacks(
    version: 0, drawPattern: drawStripes, releaseInfo: nil)
let patt = CGPattern(info:nil, bounds: CGRect(0,0,4,4),
    matrix: .identity,
    xStep: 4, yStep: 4,
    tiling: .constantSpacingMinimalDistortion,
    isColored: true, callbacks: &callbacks)!
var alph : CGFloat = 1.0
con.setFillPattern(patt, colorComponents: &alph)
con.move(to:CGPoint(80, 25))
con.addLine(to:CGPoint(100, 0))
con.addLine(to:CGPoint(120, 25))
con.fillPath()
con.restoreGState()

To understand that code, it helps to read it backward. Everything revolves around the creation of patt using the CGPattern initializer. A pattern is a drawing in a rectangular “cell”; we have to state both the size of the cell (bounds:) and the spacing between origin points of cells (xStep:, yStep:). In this case, the cell is 4×4, and every cell exactly touches its neighbors both horizontally and vertically. We have to supply a transform to be applied to the cell (matrix:); in this case, we’re not doing anything with this transform, so we supply the identity transform. We supply a tiling rule (tiling:). We have to state whether this is a color pattern or a stencil pattern; it’s a color pattern, so isColored: is true. And we have to supply a pointer to a callback function that actually draws the pattern into its cell (callbacks:).

Except that that’s not what we have to supply as the callbacks: argument. What we actually have to supply here is a pointer to a CGPatternCallbacks struct. This struct consists of a version: whose value is fixed at 0, along with pointers to two functions, the drawPattern: to draw the pattern into its cell, and the releaseInfo: called when the pattern is released. We’re not specifying the second function here; it is for memory management, and we don’t need it in this simple example.

As you can see, the actual pattern-drawing function (drawStripes) is very simple. The only tricky issue is that it must agree with the CGPattern as to the size of a cell, or the pattern won’t come out the way you expect. We know in this case that the cell is 4×4. So we fill it with red, and then fill its lower half with blue. When these cells are tiled touching each other horizontally and vertically, we get the stripes that you see in Figure 2-19.

Having generated the CGPattern, we call the context’s setFillPattern; instead of setting a fill color, we’re setting a fill pattern, to be used the next time we fill a path (in this case, the triangular arrowhead). The colorComponents: parameter is a pointer to a CGFloat, so we have to set up the CGFloat itself beforehand.

The only thing left to explain is the first three lines of our code. It turns out that before you can call setFillPattern with a colored pattern, you have to set the context’s fill color space to a pattern color space. If you neglect to do this, you’ll get an error when you call setFillPattern. This means that the code as presented has left the graphics context in an undesirable state, with its fill color space set to a pattern color space. This would cause trouble if we were later to try to set the fill color to a normal color. The solution is to wrap the code in calls to saveGState and restoreGState.

You may have observed in Figure 2-19 that the stripes do not fit neatly inside the triangle of the arrowhead: the bottommost stripe is something like half a blue stripe. This is because a pattern is positioned not with respect to the shape you are filling (or stroking), but with respect to the graphics context as a whole. We could shift the pattern position by calling setPatternPhase before drawing.

Graphics Context Transforms

Just as a UIView can have a transform, so can a graphics context. Applying a transform to a graphics context has no effect on the drawing that’s already in it; like other graphics context settings, it affects only the drawing that takes place after it is applied, altering the way the coordinates you provide are mapped onto the graphics context’s area. A graphics context’s transform is called its CTM, for “current transform matrix.”

It is quite usual to take full advantage of a graphics context’s CTM to save yourself from performing even simple calculations. You can multiply the current transform by any CGAffineTransform using concatCTM; there are also convenience functions for applying a translate, scale, or rotate transform to the current transform.

The base transform for a graphics context is already set for you when you obtain the context; that’s how the system is able to map context drawing coordinates onto screen coordinates. Whatever transforms you apply are applied to the current transform, so the base transform remains in effect and drawing continues to work. You can return to the base transform after applying your own transforms by wrapping your code in calls to saveGState and restoreGState.

Here’s an example. We have hitherto been drawing our upward-pointing arrow with code that knows how to place that arrow at only one location: the top left of its rectangle is hard-coded at (80,0). This is silly. It makes the code hard to understand, as well as inflexible and difficult to reuse. Surely the sensible thing would be to draw the arrow at (0,0), by subtracting 80 from all the x-values in our existing code. Now it is easy to draw the arrow at any position, simply by applying a translate transform beforehand, mapping (0,0) to the desired top-left corner of the arrow. To draw it at (80,0), we would say:

con.translateBy(x:80, y:0)
// now draw the arrow at (0,0)

A rotate transform is particularly useful, allowing you to draw in a rotated orientation without any nasty trigonometry. It’s a bit tricky because the point around which the rotation takes place is the origin. This is rarely what you want, so you have to apply a translate transform first, to map the origin to the point around which you really want to rotate. But then, after rotating, in order to figure out where to draw, you will probably have to reverse your translate transform.

To illustrate, here’s code to draw our arrow repeatedly at several angles, pivoting around the end of its tail (Figure 2-20). Since the arrow will be drawn multiple times, I’ll start by encapsulating the drawing of the arrow as a UIImage. This is not merely to reduce repetition and make drawing more efficient; it’s also because we want the entire arrow to pivot, including the pattern stripes, and this is the simplest way to achieve that:

lazy var arrow : UIImage = {
    let r = UIGraphicsImageRenderer(size:CGSize(40,100))
    return r.image { _ in
        self.arrowImage()
    }
}()
func arrowImage () {
    // obtain the current graphics context
    let con = UIGraphicsGetCurrentContext()!
    // draw the arrow into the graphics context
    // draw it at (0,0)! adjust all x-values by subtracting 80
    // ... actual code omitted ...
}

In our draw(_:) implementation, we draw the arrow image multiple times:

override func draw(_ rect: CGRect) {
    let con = UIGraphicsGetCurrentContext()!
    self.arrow.draw(at:CGPoint(0,0))
    for _ in 0..<3 {
        con.translateBy(x: 20, y: 100)
        con.rotate(by: 30 * .pi/180.0)
        con.translateBy(x: -20, y: -100)
        self.arrow.draw(at:CGPoint(0,0))
    }
}

Figure 2-20. Drawing rotated

Shadows

To add a shadow to a drawing, give the context a shadow value before drawing. The shadow position is expressed as a CGSize, where the positive direction for both values indicates down and to the right. The blur value is an open-ended positive number; Apple doesn’t explain how the scale works, but experimentation shows that 12 is nice and blurry, 99 is so blurry as to be shapeless, and higher values become problematic.

Figure 2-21 shows the result of the same code that generated Figure 2-20, except that before we start drawing the arrow repeatedly, we give the context a shadow:

let con = UIGraphicsGetCurrentContext()!
con.setShadow(offset: CGSize(7, 7), blur: 12)
self.arrow.draw(at:CGPoint(0,0))
// ... and so on

Figure 2-21. Drawing with a shadow

It may not be evident from Figure 2-21, but we are adding a shadow each time we draw. This means the arrows are able to cast shadows on one another. Suppose, instead, that we want all the arrows to cast a single shadow collectively. The way to achieve this is with a transparency layer; this is basically a subcontext that accumulates all drawing and then adds the shadow. Our code for drawing the shadowed arrows now looks like this:

let con = UIGraphicsGetCurrentContext()!
con.setShadow(offset: CGSize(7, 7), blur: 12)
con.beginTransparencyLayer(auxiliaryInfo: nil)
self.arrow.draw(at:CGPoint(0,0))
for _ in 0..<3 {
    con.translateBy(x: 20, y: 100)
    con.rotate(by: 30 * .pi/180.0)
    con.translateBy(x: -20, y: -100)
    self.arrow.draw(at:CGPoint(0,0))
}
con.endTransparencyLayer()

Erasing

The CGContext clear(_:) function erases all existing drawing in a CGRect; combined with clipping, it can erase an area of any shape. The result can “punch a hole” through all existing drawing.

The behavior of clear(_:) depends on whether the context is transparent or opaque. This is particularly obvious and intuitive when drawing into an image context. If the image context is transparent, clear(_:) erases to transparent; otherwise it erases to black.

When drawing directly into a view, if the view’s background color is nil or a color with even a tiny bit of transparency, the result of clear(_:) will appear to be transparent, punching a hole right through the view including its background color; if the background color is completely opaque, the result of clear(_:) will be black. This is because the view’s background color determines whether the view’s graphics context is transparent or opaque, so this is essentially the same behavior that I described in the preceding paragraph.

Figure 2-22 illustrates; the blue square on the left has been partly cut away to black, while the blue square on the right has been partly cut away to transparency. Yet these are instances of the same UIView subclass, drawn with exactly the same code! The UIView subclass’s draw(_:) looks like this:

let con = UIGraphicsGetCurrentContext()!
con.setFillColor(UIColor.blue.cgColor)
con.fill(rect)
con.clear(CGRect(0,0,30,30))

Figure 2-22. The very strange behavior of the clear function

The difference between the views in Figure 2-22 is that the backgroundColor of the first view is solid red with an alpha of 1, while the backgroundColor of the second view is solid red with an alpha of 0.99. This difference is imperceptible to the eye — not to mention that the red color never appears, as it is covered with a blue fill! Nevertheless, it completely changes the effect of clear(_:).

If you find this as confusing as I do, the simplest solution may be to drop down to the level of the view’s layer and set its isOpaque property after setting the view’s background color:

self.backgroundColor = .red
self.layer.isOpaque = false

That gives you a final and dependable say on the behavior of clear(_:). If layer.isOpaque is false, clear(_:) erases to transparency; if it is true, it erases to black.