We need a text field. We need another set of content at the bottom.

All of a sudden, your layout won’t fit on the screen any more. You need it to scroll. That’s no problem, all you need to do is select the root view of the view controller, and choose Embed in… > Scroll View, right?

Oh. That’s not available when you’re dealing with the root view. So how can you do it? How do you make a non-scrolling view controller scrollable?

You don’t drag a scroll view onto the view, so it’s highlighted, then drop it - that will completely replace your view and all of its contents!

You can’t change the class of the root view in the identity inspector to a scroll view - not only does this not work, it also isn’t a good idea, since you still want the root view to be a plain UIView.

You want to go from this:

View -> Contents

To this:

View -> Scrollview -> View -> Contents

You have tons of constraints and outlets linking the contents to the root view, and you don’t want to have to rebuild or reconnect them.

Luckily, there is a way to do it:

• If you’ve used the top or bottom layout guides then you’ll need to re-create those constraints against the top or bottom edges of the container instead. Hold alt after control-dragging to show the container instead of the layout guides in the add constraints menu.
• Make sure that you have a solid line of top-to-bottom and constraints so that the scroll view can work out its content height.
• Select the root view in the document outline, then drag it out of the view controller tree and drop it elsewhere in the scene, after the Exit segue point, for example.
• The view should have maintained the same size, the contents and constraints will all be there, and the outlets will still be connected.
• The view controller will now be missing a root view. Drag in a UIView, which will fill the scene.
• Drag in a scroll view and pin it to all edges of the root view (don’t use the layout guides, this is a very similar principle to the previous article
• Drag your original view back in so it’s a subview of the scroll view. You’ll see some red, don’t worry.
• Pin the original view to all edges of the scroll view. At this point you’ll still have some layout warnings.
• Pin the original view’s width to that of the new root view (hat tip to @calicoding for pointing out that nicer alternative to pinning to the root view’s leading and trailing edges). All of your warnings should now be gone.

You’re done - all of your original content is now safely embedded in a scroll view, with constraints and outlets intact.

It’s a common occurrence. You have some content in a stack view, and you want it to be scrollable. Maybe the content in the stack can change or you want keyboard avoidance or whatever. How do you set that up in a storyboard without either IB moaning at you, or the views not coming out right?

Here’s the view hierarchy you need:

1. The root view of the view controller
2. Your scroll view
3. Your stack view

The scroll view needs to be pinned to the leading and trailing margins, with a space of zero. It should also be pinned to the top and bottom of the root view (not the layout guides - you’ll need to hold alt down while choosing constraints to get this instead).

This will make your scroll view fill the entire scene. If you have a navigation bar or tab bar then it will sort the insets for you if the option “Adjust scroll view insets” is checked against the view controller (it is by default). This will let your content move behind the bars.

At this point your scroll view will have a size, but it won’t have a content size. The content size comes from the constraints between the scroll view and its subviews.

You pin the top, left, bottom and right margins of the stack view to the scroll view. This tells the scroll view to make its content the same size as the stack. This is fine as far as the height goes (for a vertical stack view, the height is derived from the height of the arranged subviews) but it will have no idea about the width, and will be complaining at you.

To solve that, you need to also pin the leading and trailing edges of the stack view to the superview, which will give it something concrete to decide its width against.

So, here’s the summary of what you need (for a vertical stack view):

1. Root view
2. Scroll view, pinned to all edges of the root view (not the layout guides)
3. Stack view, pinned to all edges of the scroll view, and leading and trailing edges pinned to the root view

You’ll need to have content in the stack view for interface builder to cope with all this, too, but that’s about the size of it.

To combine two sets, you use the union method. Consider the following groups of numbers:

let someInts = Set([1, 2, 3])
let someMoreInts = Set([3, 4, 5])
let allTehInts = someInts.union(someMoreInts)

allTehInts will contain 1, 2, 3, 4 and 5. 3 was in both sets, but sets can only contain unique values, so it doesn’t get included.

Which 3 is contained in allTehInts? The one from someInts, or the one from someMoreInts? THE ANSWER WILL SHOCK YOU! Or, confuse you, if you’ve just migrated to Swift 3.

You may well be saying, “I don’t care which one is included. 3 is 3”, and you’d have a point. But in a recent project I was using sets for a slightly more complex purpose.

To relieve the tedium of mapping JSON to Core Data models, there was code that creates a set of default “attribute mappings”, which assume a 1:1 relationship between the entity attribute name and the field name from JSON. For each entity you can then specify additional mappings for when the names don’t match up or you need to use a value transformer. The final set of mappings that gets used is a union of the default mappings and the specialised mappings.

The equality and hash value of the attribute mapping was based solely on the “remote key path” of the mapping - the name of the field in the JSON response. This makes sense, because you don’t want to map the same remote field to multiple attributes.

To demonstrate the principle without getting sidetracked, here is a simplified example using the reliable old Person struct:

struct Person {
    let firstName: String
    let lastName: String
}

extension Person: Equatable {}

func == (lhs:Person, rhs: Person) -> Bool {
    return lhs.firstName == rhs.firstName
}

extension Person: Hashable {
    var hashValue: Int {
        return self.firstName.hashValue
    }
}

The Person has a first and last name, but the uniqueness is measured only on the first name.

Here are three people with unimaginatively similar names:

let person = Person(firstName: "Bob", lastName: "Bobson")
let person2 = Person(firstName: "Bob", lastName: "Jobson")
let person3 = Person(firstName: "Rob", lastName: "Bobson")

Let’s put them into two sets:

let set1 = Set([person, person3])
let set2 = Set([person2])

According to the rules above, person, Bob Bobson, and person2, Bob Jobson, are identical - they have the same first name.

Create a single set which is a union of the two:

let union = set1.union(set2)

In Swift 2.2, person2 gets included in union, and person is dumped. Reverse the order:

let union = set2.union(set1)

person is included in the final set this time. In the project, the final set of mappings was a union of the default and specific mappings, which meant that any specific mappings replaced the defaults.

This behaviour is reversed in Swift 3. Members of the first set are kept when performing a union operation. This means that most of the specific mappings are dropped when performing the union, because there is often a default mapping with the same name.

It was a simple fix to reverse the order of the union, and a slightly longer fix to use update to make the intention of the code completely clear, but it took an awful lot of head-scratching to find out what was happening and why. The Swift 3 documentation is specific about which members will be included in the event of a match, the earlier documentation is not.

In this post I’m going to add the game logic in to the drag and drop action.

My goals are:

• To show a highlighted “drop zone” on the board as the player moves a tile around. The drop zone will show them where the tile can be dropped
• To “snap” the tile into the drop zone if the drag is ended while the tile is in a permissible position
• Otherwise, to snap the tile back to its position at the edge of the board
• Sort out the messy pickup of tiles on a busy board

Where am I?

The tile placing rules work around the Square in the top left of the tile - that’s the place the Board uses to assess if a tile can go in a specific location.

I need to do a lot of extra work in the handlePan(_:) method.

When the TileView is being dragged around, the origin of the view is going to line up with the origin of the top left square in the tile. This can be converted into the coordinate system of the board like so:

let locationOnBoard = boardView.convertPoint(activeTile.bounds.origin, fromView: activeTile)

The convertPoint / rect family of functions trip a lot of people up, mostly because you need to remember that a view’s frame and center are in the superview’s coordinate system, which then needs to be the fromView that you use. It’s my 5th highest voted Stack Overflow answer!. If you use coordinates from the bounds instead, you can convert from the view itself, so it’s a lot simpler.

In the first attempt at this, I just converted the point to a square on the board, checked that, and let the player drop it if it was OK. However, that didn’t play very well - when placing tiles on an almost-full board, it was much nicer for the game to hunt around for nearby locations that could serve as drop zones, otherwise the player is holding a tile almost over a perfectly good location and it isn’t being highlighted as a drop.

At that point the logic got more complicated than I was happy with inside a gesture handler, so I spun it out into a method on Board, which is probably where it should have been the whole time.

It ended up looking like this:

public func allowedDropLocation(tile: Tile, atPoint point: CGPoint, gridSize: CGFloat) -> Square? {
    let potentialSquare = squareAtPoint(point, gridSize: gridSize)
    var allowedDropLocation: Square?
    if canPositionTile(tile, atSquare: potentialSquare) {
        allowedDropLocation = potentialSquare
    } else {
        var distanceToDropPoint = CGFloat.max
        for square in squaresSurrounding(potentialSquare) {
            if canPositionTile(tile, atSquare: square) {
                let origin = pointAtOriginOfSquare(square, gridSize: gridSize)
                let xDistance = origin.x - point.x
                let yDistance = origin.y - point.y
                // No need to sqrt since we're just comparing
                let distance = (xDistance * xDistance) + (yDistance * yDistance)
                if distance < distanceToDropPoint {
                    distanceToDropPoint = distance
                    allowedDropLocation = square
                }
            }
        }
    }
    return allowedDropLocation
}

This did mean I had to import CoreGraphics into Board, making my “pure swift” model object not quite so pure, but honestly, who cares? It feels like the right place for this method to go.

In brief, the method finds the square at the correct location, checks if that’s a permissible drop, if not, it gets a 3x3 grid of squares centred on that square and checks each one of those, picking the one whose centre is closest to the tile’s location.

This could possibly do with some tweaking - obviously it favours placing the tile at the “actual” square even when the drop location is really near the edge:

But I think I’ll play a while and see if it’s a problem.

squareAtPoint is a new function on PlayingGrid that returns a Square given a particular grid size and point:

public func squareAtPoint(point: CGPoint, gridSize: CGFloat) -> Square {
    let row = Int(floor(point.y / gridSize))
    let column = Int(floor(point.x / gridSize))
    return Square(row: row, column: column)
}

Showing the drop zone

The drop zone is going to be the shape of the tile, drawn on the board. I already have a method to get a CGPath out from a grid, so I add a CAShapeLayer to BoardView. Because we’re dealing with locations at the top left of tiles, the anchorPoint of the layer is set to (0, 0), so that I can set its position directly corresponding to the square that I’m planning to drop it on. All of this configuration can be done as part of the property declaration, like this:

private let highlightLayer: CAShapeLayer = {
    $0.anchorPoint = CGPoint(x: 0, y: 0)
    $0.fillColor = UIColor(red: 0.0, green: 1.0, blue: 0.0, alpha: 0.25).CGColor
    $0.strokeColor = UIColor.darkGrayColor().CGColor
    $0.lineWidth = 4.0
    $0.hidden = true
    return $0
}(CAShapeLayer())

I’m a fan of this style - it prevents having a lot of setup code in the initializer of the view.

I add a calculated property to BoardView so the path can be updated:

var dropPath: CGPath? {
    set {
        let origin = highlightLayer.position
        CATransaction.begin()
        CATransaction.setDisableActions(true)
        highlightLayer.path = newValue
        highlightLayer.position = origin
        CATransaction.commit()
    }
    get {
        return highlightLayer.path
    }
}

This is called from the activeTile didSet property observer in the view controller:

boardView.dropPath = activeTile?.tile.pathForSquares(true, gridSize: gridSize)

In the early draft of this code I had a lot of extra state that I was resetting at different points in the gesture handling, until I realised it made more sense just to tie it to the activeTile property.

The last part of showing the drop zone is to place the highlight layer in the correct place and make it visible. This method on BoardView takes care of that:

func showDropPathAtOrigin(origin: CGPoint?) {
    CATransaction.begin()
    CATransaction.setDisableActions(true)
    if let origin = origin {
        highlightLayer.position = origin
        highlightLayer.hidden = false
    } else {
        highlightLayer.hidden = true
    }
    CATransaction.commit()
}

If no point is passed in, the layer is hidden, otherwise it is moved. Notice that here and in the dropPath setter, I’m using a CATransaction to prevent implicit animations happening. Without that code, the path and position changes would be animated, which isn’t the behaviour I’m after.

Back in the gesture handler, I can call the allowedDropLocation method discussed earlier, find the origin of the square, and use that to position or hide the drop layer:

if let allowedDropLocation = board.allowedDropLocation(activeTile.tile, atPoint:locationOnBoard, gridSize: gridSize) {
    let squareOrigin = board.pointAtOriginOfSquare(allowedDropLocation, gridSize: gridSize)
    boardView.showDropPathAtOrigin(squareOrigin)
} else {
    boardView.showDropPathAtOrigin(nil)
}

Dropping the tile

Currently when the player drops a tile, it stays where it is. Now that I know if the tile can fit on the board at its current position, I can take this into account when the gesture ends:

let locationOnBoard = boardView.convertPoint(activeTile.bounds.origin, fromView: activeTile)
let allowedDropLocation = board.allowedDropLocation(activeTile.tile, atPoint:locationOnBoard, gridSize: gridSize)

self.activeTile = nil

if let allowedDropLocation = allowedDropLocation {
    board.positionTile(activeTile.tile, atSquare: allowedDropLocation)
    boardView.addSubviewPreservingLocation(activeTile)
    UIView.animateWithDuration(0.1) {
        activeTile.frame.origin = self.board.pointAtOriginOfSquare(allowedDropLocation, gridSize: self.gridSize)
    }
} else {
    UIView.animateWithDuration(0.25) {
       self.positionTiles()
    }
}

I repeat the logic for confirming the drop location - this seemed better than having a property for the allowed drop location and having to reset it all the time (which is what I originally had). If there’s a valid location, then the tile is added to the board at the correct position, and the tile view is made a subview of the board. I wrote a utility method to move a view to a new superview, whilst keeping the same location on the screen.

There is then a short animation - either to snap the tile into place on the board, or to return it to “home” around the edge. positionTiles is the tile placing code that was in layoutSubviews, which has been moved to its own function.

The activeTile property is set to nil before this happens, because that is used when the tiles are being positioned.

Fixing tile pickup

Tile pickup is currently done by hit testing, which means that the order of subviews drives the tile selection. Each tile is a square much larger than the occupied tiles, as you can see in this screenshot from Reveal (get Reveal, it’s the best):

Each tile is a 5x5 grid of squares. As you can see, the V tile (with the orange background) is almost completely covered by the S tile, with the red background. Most attempts to pick up the V will result in the S being picked up instead.

This is only a problem for tiles placed on the board, so I can override hitTest(_: withEvent:) on BoardView to fix it. I can get the appropriate square using the same method used when handling the pan gesture, see if there’s a tile at that square, and if so, return the appropriate tile view, otherwise use the super implementation:

public override func hitTest(point: CGPoint, withEvent event: UIEvent?) -> UIView? {
    
    let square = board.squareAtPoint(point, gridSize: gridSize)
    if
        let tile = board.tileAtSquare(square),
        let tileView = (tileViews.filter{ $0.tile.shape == tile.shape }).first {
        return tileView
    }
    
    return super.hitTest(point, withEvent: event)
}

To get this work I needed a way to check equality on tiles - this meant adding a property to hold the Shape that the tile was initialized with.

That’s all for this time - the current state of the code is here. The game is now fully working - but it’s not very jazzy. In the next post I’ll be adding some “juice” - little touches to make it more fun.

In this post I’m going to talk about adding gesture recognisers and transferring to a full project.

The limits of playgrounds

This project has come a long way with playgrounds, but there are a few obstacles which make me think it can’t go much further. I made and displayed a view controller within the playground, then decided to change to a full project, because of the following limitations:

• Source code can’t be shared between a standard Xcode project and a playground, so you can’t do “live fiddling” in the playground then build the project, incorporating your changes - unless I’ve missed something.
• Live view rendering in playgrounds doesn’t look quite right - it seems to come out slightly blurry.
• The layout life cycle of a view controller’s view in a playground also didn’t seem to come across all that clearly. I found myself adding code to work around the way the playground was working, which seemed a waste of time.

I created a new single view Xcode project for the iPad, working in landscape mode only, and moved across the model and view files from the playground.

There’s a single view controller which takes a board and tiles property, and has a boardView and set of tileViews based off them. At the moment I’m just setting this up in the app delegate as I want to get the game mechanics working before I worry too much about setup and scoring and so on.

In viewDidLayoutSubviews() I position the tiles evenly around the board. When you start the game, it looks like this:

The code for that is fairly boring and possibly not what I’m going to end up with when this is all over, so I won’t go into detail on that, you can look in the repo if you’re interested.

Gesture recognisers

The main interaction the player will have is to drag tiles around the board. You do this with a pan gesture.

The view controller acts as the pan gesture’s delegate. It isn’t allowed to begin unless it begins at the current location of a tile:

public func gestureRecognizerShouldBegin(gestureRecognizer: UIGestureRecognizer) -> Bool {
    if gestureRecognizer != pan {
        return true
    }
    let location = gestureRecognizer.locationInView(view)
    if let hitTile = view.hitTest(location, withEvent: nil) as? TileView {
        activeTile = hitTile
        return true
    }
    return false
}

When this happens it sets the view controller’s activeTile property, which in turn transitions that tile to the lifted state.

In the handler for the gesture, I move the tile around to follow the movement:

@IBAction func handlePan(sender: UIPanGestureRecognizer) {
    var fingerClearedLocation = sender.locationInView(view)
    fingerClearedLocation.y -= (activeTile?.bounds.height ?? 0.0) * 0.5
    switch sender.state {
    case .Began:
        UIView.animateWithDuration(0.1) { self.activeTile?.center = fingerClearedLocation }
    case .Changed:
        activeTile?.center = fingerClearedLocation
    case .Ended, .Cancelled:
        // TODO: put it down in a permissible place
        activeTile = nil
    default:
        break
    }
}

Another subtlety that you don’t notice in the simulator - when you’re dragging a tile around, your finger is covering most of the tile. In the code above I’m offsetting the location of the gesture so that you can see the whole tile and, more importantly, where it’s going to go.

With the current code, the tile will go wherever the user lets go - none of the rules I spent so long building are being taken into account yet. However, the game is almost playable right now!

The only missing thing is the ability to rotate. The user is going to do this by tapping the screen while they are moving a tile. The tap gesture is handled like this:

@IBAction func handleTap(sender: UITapGestureRecognizer) {
    activeTile?.rotate(true)
}

Nothing happens if there isn’t an active tile.

There are a couple of subtleties to note when using taps together with pans. First, the tap is ignored if a pan is active, unless you implement the following delegate method:

public func gestureRecognizer(gestureRecognizer: UIGestureRecognizer,
 shouldRecognizeSimultaneouslyWithGestureRecognizer otherGestureRecognizer: UIGestureRecognizer) -> Bool {
    return true
}

Second, unless you explicitly set a maximum number of touches on the pan (the default is infinity), the tap is also interpreted as being part of the pan. Since the location of a gesture is the average location of all the touches within that gesture, this means that the tile jumps to between your two fingers when you are panning and touching. Setting the maximum touches to 1 stops this.

As it stands now the game is playable, but with a few problems. These will be addressed in upcoming posts:

• The rule system needs to be incorporated so that the tiles can only be placed on the board where they are allowed to go.
• Picking up tiles that are close to each other seems a little unpredictable, because the entire tile area rather than the populated area is used for touches.
• It might be worth looking at a long press gesture to pick up tiles in this situation, so the user can tell which tile they are going to move when dealing with tiles on the board.

The repo as at the end of this post is at this commit.

Each tile will be represented with a view, and the board will be a view. Placed tiles will be added as subviews of the board, which will simplify the drawing and positioning logic.

Tiles

A TileView is initialised with a Tile model, a grid size (the edge of one of the squares that make up the view) and a colour. I originally had a method in here to create a path from the occupied squares, but moved this out to the PlayingGrid protocol since it ended up also applying to the board.

The tile view has a shape layer derived from this path, and an optional drop shadow (to be shown when the player has “picked up” the tile. It looks like this:

The tile view has a rotate method which will animate a rotation, then update the tile model and redraw after it is done. This keeps the model and view in sync without being too complicated, and it means I don’t have to keep track of the rotated state of any views or the model. It’s possible that won’t work well with the UI (I might want to allow two or three rotations to be performed at once) but it will do for now. I’d rather get something working than overcomplicate before I’m actually at a specific stage in the project. The rotation method currently looks like this:

func rotate(clockwise: Bool) {
    UIView.animateWithDuration(0.1, animations: {
        self.transform = CGAffineTransformMakeRotation(clockwise ? CGFloat(M_PI_2) : CGFloat(-M_PI_2))
        }, completion: { _ in
            self.transform = CGAffineTransformIdentity
            self.tile.rotate(clockwise)
            self.shapeLayer.path = self.tilePath()
    })
}

The lifted property will be toggled when the user picks up or places a tile. It affects the shadow of the shape layer in a property observer:

public var lifted: Bool = false {
    didSet {
        layer.shadowRadius = 5.0
        layer.shadowOffset = .zero
        layer.shadowColor = UIColor.blackColor().CGColor
        layer.shadowOpacity = lifted ? 0.5 : 0.0
    }
}

The Board

A BoardView is initialised with a Board model and a grid size. It contains a shape layer which draws the empty board. This is the same path algorithm that I use for the tile, except the board draws empty squares, and the tile draws occupied squares. At the moment, it doesn’t do anything else.

Making the paths

This is one of those functions that probably be collapsed into a single-liner in Swift, but that’s usually not a path I like to go down. It makes things unreadable and the intermediate steps are invisible as far as debugging is concerned. Who benefits from making code as short as possible?

I went with this in the end. It makes each stage of the process pretty clear. It could perhaps be replaced entirely with a single for..in loop or reduce, but I like the fact that this structure shows several distinct steps. This means that if I decided to do additional things during the building of this path, or if I required just the [CGRect] output, it would be simple to split things out into separate functions.

This is an extension of PlayingGrid:

public func pathForSquares(occupied: Bool, gridSize: CGFloat) -> CGPath {
    
    let squaresForPath = squares().filter { $0.occupied == occupied }
    
    let rects : [CGRect] = squaresForPath.map { square in
        let originX = CGFloat(square.column) * gridSize
        let originY = CGFloat(square.row) * gridSize
        return CGRect(x: originX, y: originY, width: gridSize, height: gridSize)
    }
    
    let path : UIBezierPath = rects.reduce(UIBezierPath()) { path, rect in
        path.appendPath(UIBezierPath(rect: rect))
        return path
    }
    
    return path.CGPath
}

A fast visualisation

I wanted to do a quick check that my board view and tile views were playing nicely with the logic I’d built in the earlier sections. This was a few lines of code to achieve in a playground:

let board = Board(size: .SixByTen)
let boardView = BoardView(board: board, gridSize: 30)
let shapes = (0..<11).map { Shape(rawValue:$0)! }
let tiles = shapes.map { Tile(shape: $0) }
for tile in tiles {
    for square in board.squares() {
        if board.canPositionTile(tile, atSquare: square) {
            board.positionTile(tile, atSquare: square)
            let tileView = TileView(tile: tile,color: randomColor(), gridSize: boardView.gridSize)
            boardView.addSubview(tileView)
            tileView.frame.origin = board.pointAtOriginOfSquare(square, gridSize: boardView.gridSize)
            break
        }
    }
}

Here I am just going through each possible tile and placing it in the first possible square on the board.

Adding the boardView inline shows this:

It’s starting to look real!

The code at the end of this post is at this commit.

The rows property of the board needs to change so that the squares now occupied by the tile are marked as such. Simply updating the relevant positions in the array isn’t going to be good enough, though. The user may pick up a tile again - how will I know which tile it was, and which squares to mark as unoccupied again?

There are many possible solutions to this problem. I decided to do it like this:

• Store the rows configuration of an empty board when the board is initialised
• Create a new struct which holds a tile and its location on the board
• Have a private array of these structs to record placed tiles
• Have a property observer on this array which updates rows by adding all placed tiles onto the empty board.

I toyed with the idea of making rows a calculated variable but that seemed like it would add a lot of processing overhead (the rows property is going to be accessed quite often) without making things much simpler. The only concern with the current model is that if a placed tile is rotated, this will not be reflected in the board’s model. However, a user will not be able to rotate a placed tile - they will have to remove it from the board to do that.

The empty board is just a constant [[Bool]] which is assigned during init. Here is the struct and property:

private struct PlacedTile {
    let square: Square
    let tile: Tile
}

private var placedTiles = [PlacedTile]() {
    didSet {
        updateRows()
    }
}

A property observer on an array is fired whenever an object is added or removed. This is the function that updates the board:

private func updateRows() {
    rows = emptyBoard
    for placedTile in placedTiles {
        let occupiedSquares = placedTile.tile.squares().filter { $0.occupied == true }
        for tileSquare in occupiedSquares {
            let boardLocation = tileSquare.offsetBy(placedTile.square)
            rows[boardLocation.row][boardLocation.column] = true
        }
    }
}

Pretty simple - for each occupied square in a placed tile, mark the relevant board square as occupied.

Now to place or remove a tile:

public func positionTile(tile: Tile, atSquare square: Square) -> Bool {
    if !canPositionTile(tile, atSquare: square) {
        return false
    }
    placedTiles.append(PlacedTile(square: square, tile: tile))
    return true
}

public func removeTile(tile: Tile) -> Tile? {
	if let index = placedTiles.indexOf( { $0.tile === tile } ){
        placedTiles.removeAtIndex(index)
        return tile
    }
    return nil
}

I’m planning to use these return values to inform the UI once I get to that stage.

While thinking about the updated board model and user interaction, it seemed that I was going to need a method to find the tile at a given board square. This will be used when processing touches on the board, and managed to give me some Bonus Swift Features™ to cram into this article after all. I was wondering if I’d get any.

Here’s the method I wrote:

public func tileAtSquare(square: Square) -> Tile? {
	for placedTile in placedTiles {
		let locationInTile = square.offsetBy(-placedTile.square)
		if placedTile.tile.squareWithinGrid(locationInTile) {
			let occupiedSquares = placedTile.tile.squares().filter { $0.occupied == true }
			for tileSquare in occupiedSquares {
				if tileSquare == locationInTile {
					return placedTile.tile
				}
			}
		}
	}
	return nil
}

This translates the board location to a tile location, checks that is anywhere within the tile, then checks if an occupied square in the tile matches up.

The first bonus Swift feature is here: square.offsetBy(-placedTile.square). To translate from a board location to a tile location, I need to do the reverse of the offset function. Rather than define a new function, since I could not think of a non-confusing pair of names for them, I instead defined the unary minus operator to work for a Square:

public prefix func -(square: Square) -> Square {
    return Square(row: -square.row, column: -square.column)
}

I deliberately do not return a Square with an occupied property - anything returned here is for location calculations only, and not part of the board model.

In a similar vein, for the second bonus Swift feature I defined == for Square to ignore the occupied property:

public func ==(left: Square, right: Square) -> Bool {
    return left.row == right.row && left.column == right.column
}

At the end of this stage of the project I have these feelings:

• The model and logic is pretty close to done
• I’m starting to feel itchy about the lack of unit tests. Playgrounds were good for quick visualisations and checks, but I can see some opportunities to refactor and I don’t want to do that without the backup of tests.
• I’m starting to think about the views that are going to be involved - I would like to continue in playgrounds to use Live Views for those quick visualisation wins again.

The next post will either be me migrating into an Xcode project and adding some tests, or creating some views in the playground, or a bit of both. It’d be nice to get a project going but it’s also really good to be looking at things in a live view as you are writing code, and it would be interesting to see how far I can take that.

Here’s the link to the code as of the end of this post.

To solve this problem I ended up creating a SequenceType and GeneratorType, which is the main focus of this part.

To see if a tile can go in a certain position on a board, I need to check each occupied square of the tile’s grid, and each square that matches on the board’s grid, and see if the spaces are all free.

Making a for…in loop

I could (and, indeed, did) do this by having an outer loop of rows and an inner loop of columns, but it felt a bit messy, and part of the point of this project is to look at some of the interesting things Swift permits you to do. A nicer way to work would be to be able to go something like:

for square in tile.squares {
	if square.occupied {
		... check the board at the relevant square
	}
}

The first step is to make a struct which can represent a square on a PlayingGrid:

public struct Square {
    let row: Int
    let column: Int
    let occupied: Bool?
}

occupied is an optional because sometimes I will want to create a Square and use it to query a PlayingGrid.

To allow a for…in loop to work, you need two things: a SequenceType, and a GeneratorType.

The sequence is the thing that is returned from, for example, tile.squares in the code above. Things like arrays also conform to SequenceType, which is how you can do for…in loops on them.

SequenceType has a single function you have to implement. Once you have that function, you can map, reduce, forEach and many others. The function is generate(), and that has to return a GeneratorType.

GeneratorType

GeneratorType is a simple protocol. It has one function to implement, next(), which returns whatever type your sequence is going to be made of. Swift can infer that from the way you declare the function.

In this case the generator is going to be a class, as it will need to hold some mutable state to track the last element that was generated. Here’s the setup:

public class GridSquareGenerator: GeneratorType {
    var currentRow: Int = 0
    var currentColumn: Int = -1
    
    let grid: PlayingGrid
    
    public init(grid: PlayingGrid) {
        self.grid = grid
    }
}

And here is the all-important next() method:

public func next() -> Square? {
    guard currentRow < grid.rows.count else { return nil }
    
    currentColumn += 1
    
    if currentColumn == grid[currentRow].count {
        currentColumn = 0
        currentRow += 1
    }
    if currentRow < grid.rows.count {
        return Square(row: currentRow, column: currentColumn, occupied: grid[currentRow][currentColumn])
    } else {
        return nil
    }
}

This moves along the columns and down the rows, creating and returning the squares. Generators can take many forms, you can even have ones that are theoretically infinite (for example, ones that generate mathematical series). It all depends on the state you track and the implementation of next().

SequenceType

Creating the sequence is simple:

public class GridSquareSequence: SequenceType {
    let grid: PlayingGrid
    
    public init(grid: PlayingGrid) {
        self.grid = grid
    }
    
    public func generate() -> GridSquareGenerator {
        return GridSquareGenerator(grid: grid)
    }
}

To make the sequence of squares of a PlayingGrid accessible, declare it like so:

extension PlayingGrid {
    public func squares() -> GridSquareSequence {
        return GridSquareSequence(grid: self)
    }
}

Placing a tile

With all that mess hidden away inside the PlayingGrid protocol, it is now quite nice to add placement checking logic to the board:

extension Board {
    public func canPositionTile(tile: Tile, atSquare: Square) -> Bool {
        
        for tileSquare in tile.squares() {
            let boardSquare = tileSquare.offsetBy(atSquare)
            if !squareWithinBoard(boardSquare) {
                return false
            }
            if tileSquare.occupied == true && squareOccupied(boardSquare) {
                return false
            }
        }
        return true
    }
}

I added a couple of utility functions to make this more readable, not shown here.

At this point, the blog posts have caught up to where I am in development. So from now on I’ll be giving commit links to the repo for the state at the end of each post. Here’s the first.

In the next post I talk about updating the board’s model when tiles are placed and removed.

The board, like the tiles, can be represented with a two-dimensional array of Bools. Also, like the tiles, it’s going to be nice to be able to view the board as a string and access locations in there via subscripting. Hmmm.

At this point I had three choices.

I could reimplement the same logic in the Board and Tile classes, which is silly. I could make both classes inherit from a superclass, but that didn’t feel right. Instead I decided to create a protocol.

Protocols and default implementations

public protocol PlayingGrid {
    var rows: [[Bool]] { get }
    subscript(row: Int) -> [Bool] { get }
}

The subscript implementation can be done in an extension:

extension PlayingGrid {
    public subscript(row: Int) -> [Bool] {
        get {
            return rows[row]
        }
    }
}

The corresponding code can be removed from the Tile class, which is now declared like so:

public class Tile: PlayingGrid {

I then tried to make a default implementation of the CustomStringConvertible protocol method in an extension:

extension PlayingGrid: CustomStringConvertible {

This gives the error “Extension of protocol cannot have an inheritance clause”. It turns out you can’t do it like this. However, what I wanted is still possible. I had to define the inheritance in the main declaration:

public protocol PlayingGrid: CustomStringConvertible {

Then in the extension, it can be implemented. I rewrote the implementation so it didn’t look so much like robot vomit:

extension Bool {
    var gridCharacter: String {
        return self ? "#" : "_"
    }
}

extension PlayingGrid where Self: CustomStringConvertible {
    public var description: String {
        let descriptions : [String] = rows.map { row in
            row.reduce("") { string, gridValue in
                string + gridValue.gridCharacter 
            }
        }
        return descriptions.joinWithSeparator("\n")
    }
}

I then had to add similar code to make PlayingGrid CustomPlaygroundQuickLookable as well. First, amend the protocol declaration:

public protocol PlayingGrid: CustomStringConvertible, CustomPlaygroundQuickLookable {

Then, amend the constraints on the extension (they need to be in the same extension, because the quick look depends on the description):

extension PlayingGrid where Self: protocol<CustomStringConvertible, CustomPlaygroundQuickLookable> {

(the protocol< > syntax was pointed out to me by the wonderful @jessyMeow)

Within the extension, I used the same implementation of customPlaygroundQuickLook() from Tile, removing the code from that class.

Having done all that to split the shared functionality out from Tile, it was time to create Board.

Making the Board

According to the Wikipedia entry there are four different board sizes which can take all of the tiles with no gaps. It’s not possible to represent this nicely in an enum, because the raw value of an enum can’t be a tuple. Instead, a struct with static values works:

public struct Size {
    let height: Int
    let width: Int
    
    public static let SixByTen = Size(height: 6, width: 10)
    public static let FiveByTwelve = Size(height: 5, width: 12)
    public static let FourByFifteen = Size(height: 4, width: 15)
    public static let ThreeByTwenty = Size(height: 3, width: 20)
}

I use the height dimension first simply because that’s how it is shown in the Wikipedia page and I wanted to use common nomenclature.

The board’s initializer needs to take a Size, now we’ve defined it. To allow for positioning of any type or rotation of tile anywhere in the board, I will add four blocks of padding in each direction around the empty board. That way a tile can be placed anywhere on the “board” with a minimum of one of its squares actually on the playing surface.

This is probably the sort of code that could be written as an unreadable one-liner in Swift, but that’s not how I roll.

public init(size: Size) {
    // Extend by four "occupied" positions in every direction
    let paddingHorizontal = [Bool].init(count: 4, repeatedValue: true)
    let paddingVertical = [Bool].init(count: 8 + size.width, repeatedValue: true)
    let fullPaddingVertical = [[Bool]].init(count: 4, repeatedValue: paddingVertical)
    let emptyRow = [Bool].init(count: size.width, repeatedValue: false)
    rows = fullPaddingVertical
    for _ in 0..<size.height {
        rows += [paddingHorizontal + emptyRow + paddingHorizontal]
    }
    rows += fullPaddingVertical
}

I feel better about the code after these changes. I think its a sensible use of a protocol, I learned lots of things about default implementations and protocol constraints, and the actual Board and Tile implementations are currently very light. In the next part I will start to work on some game logic - placing tiles on the board.

Here are the possible tile shapes and the two common notations for them:

By R. A. Nonenmacher - Own work, GFDL, https://commons.wikimedia.org/w/index.php?curid=4412149

The puzzle consisted of wooden versions of the possible shapes and a six-by-ten frame to fit them in. Although my daughter didn’t manage to solve the puzzle, she displayed extraordinary tenacity and technique, and I’m sure she would have got there given time.

I promised to make her a version of the puzzle to play on her iPad instead. I’ve done a few little projects like this for her (hopefully one day, with her) and thought this one might make an interesting “development diary” type of post. I’ve no doubt made some decisions you disagree with. I’ve no doubt made some decisions I will disagree with, as I move through the project, but that’s the point of this series - code doesn’t spring perfectly formed onto the screen. It’s written, examined, tested and re-written until it’s good enough. I hope to document that process.

Note that I said “good enough”, not “perfect”. You have to ship. I’m also hoping that the double commitments of writing about the process and the fact I promised her will help to drive this project along.

First thing: The tiles

I always like to get the data model and “business rules” defined at the start of a project. UI comes at the end for me, since it is so often driven by data. The first part to tackle was the tiles.

Here are the rules about tiles:

• The tiles can rotate on the z-axis in 90 degree increments.
• The tile has a specific pattern of squares that cannot change, except via rotation
• There are 12 possible tile patterns, only one of each is permitted in the game

Which lead me to these code considerations:

Each Tile in the model represents a real, physical object in the game, and we have the ability to change the internal state of the tile by rotating it. Therefore Tile should be a class, not a struct:

public class Tile {
}

Any possible rotation of the tile can fit into a five-by-five grid, so the tile will contain a two-dimensional matrix of Bool to represent the grid, where true represents the presence of a part of the tile, and false represents the absence:

private (set) public var rows: [[Bool]]

It’s going to be handy to be able to access a particular location using a nice subscript notation, such as tile[1][1]:

public subscript(row: Int) -> [Bool] {
	get {
		return rows[row]
	}
}

true and false don’t look very good when you’re trying to debug or examine your work, so Tile should be CustomStringConvertible so that it can be printed usefully in a playground. Here # will represent a filled space and _ an empty one:

extension Tile: CustomStringConvertible {
    public var description: String {
        let descriptions: [String] = rows.map { $0.reduce("") { $0 + ($1 ? "#" : "_") } }
        return descriptions.joinWithSeparator("\n")
    }
}

The 12 possible tile patterns should be represented by an enum. Tiles should be created with init(shape: O). I want to be able to create these in a loop, so I’m using an integer raw value:

public enum Shapes: Int {
    case O = 0
    case P = 1
    case Q = 2
    case R = 3
    case S = 4
    case T = 5
    case U = 6
    case V = 7
    case W = 8
    case X = 9
    case Y = 10
    case Z = 11
}

To create the two-dimensional array to represent the tiles but also to make the code nice and readable, I decided to do a reversal of the description method and have a [String] calculated variable which could be used to create the tiles:

var stringMap: [String] {
        switch self {
        case O:
            return [
                "__#__",
                "__#__",
                "__#__",
                "__#__",
                "__#__"
            ]
       ...

The initialiser then looks like this:

public init(shape: Shapes) {
    rows = shape.stringMap.map {
        return $0.characters.map { $0 == "#" }
    }
}

And of course, I was going to get this up and running in a playground first. Why on earth not? This meant I could instantly see if I’d screwed anything up:

let tile = Tile(shape: .O)
print(tile)

Printing is a bit tedious, though, and when I add the Tile inline in the playground I get a fairly useless view with an outline list of unlabelled variables. That can be solved by making it CustomPlaygroundQuickLookable:

extension Tile: CustomPlaygroundQuickLookable {
    public func customPlaygroundQuickLook() -> PlaygroundQuickLook {
        return PlaygroundQuickLook(reflecting: description)
    }
}

Now the tile shows up clearly inline in the playground!

The final part to address about tiles was the rotation action. I set about solving this complex problem the way all programmers do - I searched for “Rotate 2D array” on Stack Overflow, which led me here, and then here. Putting this information together gave me a rotation method (transpose was copied wholesale from Abizer’s answer, so not reproduced here):

public func rotate(clockwise: Bool) {  
    if !clockwise {
        reverseRows()
    }
    rows = transpose(rows)
    if clockwise {
        reverseRows()
    }
}
private func reverseRows() {
    rows = rows.map { $0.reverse() }
}

Thanks to the quick looking in the playground it was easy to check that this was working as intended. That was tiles all done. The next part of the series will talk about the board.

Apple’s solution to this is UISplitViewController. On the iPad, this maintains a two-column interface, with a smaller “primary” or “master” view controller on the leading side, and a larger “secondary” or “detail” view controller on the trailing side. On the iPhone, only one view controller is visible. Before multitasking, developers could get away with copy-pasting a delegate method from the template code, maybe checking UIUserInterfaceIdiom in a few places, and the split view would work nicely on both devices without anyone having to think too much. Since multitasking, more thinking is required.

Collapse into now

The split view controller has a Boolean property, collapsed, which indicates which state it is in. The collapsed state is determined from the horizontal size class currently being used:

When a split view controller is born, it assumes it is in a non-collapsed state. When it is added to the window, if running in a .Compact horizontal size class, it collapses. If the user rotates their iPhone 6 Plus or changes multitasking mode in their iPad (or rotates their iPad whilst multitasking, the list of testing scenarios goes on and on…) it can transition between the expanded and collapsed states.

The transition between collapsed and expanded states involves several actors, and requires quite a lot of spelunking through the documentation to understand, so I’ve done that for you. Let’s start with collapsing.

‘Till I Collapse

First, the split view talks to its delegate. It calls primaryViewControllerForCollapsingSplitViewController(_:), which may return a view controller. You would implement this if a completely new view controller was more appropriate to use than the exisiting primary view controller.

After that, the split view controller calls splitViewController(_:collapseSecondaryViewController: ontoPrimaryViewController:) on its delegate. This is the method that’s included in the master-detail sample project. It returns a Boolean.

The split view controller is asking the delegate to do the collapsing for it, and the return value indicates if the delegate has handled the collapse or not. With that in mind, the answer returned means the following:

• true: this tells the split view controller not to do anything with the secondary view controller, because the delegate has handled it. In the template project, it’s “handled” by doing nothing, so the secondary controller is discarded. If you have additional requirements you would use this opportunity to configure the primary controller based on the contents of the secondary controller, perhaps to show an expanded table row for the content that was previously displayed in the secondary controller.
• false: this tells the split view controller that the delegate has not handled the collapse, and the split view controller itself needs to do some work.

Whatever you return from this method, the secondary view controller is going away very soon.

If the method above returns false or is not implemented, then that means the split view controller will attempt to perform the collapse itself.

It does this by calling collapseSecondaryViewController(_:forSplitViewController:) on the primary view controller. This method is implemented by UIViewController but nothing is really done there. UINavigationController overrides this method and will take the secondary view controller and add it to the top of the navigation stack.

Here’s a diagram showing the flow of operations when collapsing:

This can be where things get strange. In the template project, the primary and secondary view controllers are both navigation controllers. After collapse, if you investigate the view controller stack, it looks like this:

• Split View Controller (root)
  • Navigation Controller (primary)
    • Primary Content view controller
    • Navigation Controller (secondary)
      • Secondary Content view controller

This doesn’t seem right to me. If you try to push a navigation controller onto a navigation stack, you get an exception. Why is it allowed in this case? If you ask the secondary content view controller for its navigation controller, you get the secondary one, likewise for the navigation bar, which isn’t even on the screen. Any queries about the navigation stack may reveal unexpected answers. Most things seem to work OK, there must be some private UIKit message passing going on in the background, but if you’re experiencing problems with your adaptive app, the wonky navigation stack is worth looking at.

You can straighten things out, either in the split view delegate:

if let 
  primaryNav = primaryViewController as? UINavigationController,
  secondaryNav = secondaryViewController as? UINavigationController {
    primaryNav.viewControllers = primaryNav.viewControllers + secondaryNav.viewControllers
    return true
}

Or in a navigation controller subclass:

override func collapseSecondaryViewController(secondaryViewController: UIViewController, forSplitViewController splitViewController: UISplitViewController) {
  if let secondaryAsNav = secondaryViewController as? UINavigationController {
    viewControllers = viewControllers + secondaryAsNav.viewControllers
  } else {
    super.collapseSecondaryViewController(secondaryViewController, forSplitViewController: splitViewController)
  }
}

All you’re doing here is taking the view controller stack from the secondary navigation controller, and adding it in to the stack of the primary controller. Note that if you do this, you’re also responsible for splitting the stack on expand, and wrapping the secondary stack in a new navigation controller.

Here’s a representation of what each version looks like:

That’s enough collapsing. Time to look at expanding.

Expand your mind

As with collapsing, first the split view controller talks to its delegate, calling primaryViewControllerForExpandingSplitViewController(_:). This is your opportunity to provide an entirely new view controller to be on the primary side. If this is not implemented or you return nil, the existing primary view controller will be used. If you implemented the corresponding method called during collapse, you probably want to reverse whatever you did there.

To tease apart the primary and secondary view controllers, the splitViewController(_:separateSecondaryViewControllerFromPrimaryViewController:) delegate method is then called. This method returns a UIViewController?; if you return something, it will be the new secondary controller. If you don’t, the split view controller will try to handle the separation itself. If you manually combined navigation stacks in the delegate method when collapsing, you will need to separate them yourself at this point, and create a new navigation controller for the secondary view controller.

If you return nil from this method or do not implement it, the split view controller tries to handle the separation itself by calling separateSecondaryViewControllerForSplitViewController(_:) on the primary view controller. Like the corresponding collapse method, this is implemented as (presumably) a stub on UIViewController. UINavigationController overrides this method and will return the top view controller from its navigation stack. If you recall the discussion in the collapse section, this will be itself a navigation controller, if you’re using the unmodified template code.

Here’s a diagram showing the flow of operations when expanding:

The size (class) of a cow

In normal use the split view controller will pass its own horizontal size class to the secondary view controller, and a horizontal size class of .Compact to the primary view controller.

This means that traitCollectionDidChange will not indicate a change in horizontal size class on the primary view controller when the iPhone 6 Plus is rotated, nor will you be able to use the horizontal size class of the primary view controller to implement platform-specific behaviour.

If you want the primary view controller to hold the same horizontal size class as the split view controller itself for whatever reason, you can implement overrideTraitCollectionForChildViewController(_:) in a split view controller subclass:

override func overrideTraitCollectionForChildViewController(childViewController: UIViewController) -> UITraitCollection? {
    guard let collection = super.overrideTraitCollectionForChildViewController(childViewController) else { return nil }
    let overrideCollection = UITraitCollection(horizontalSizeClass: self.traitCollection.horizontalSizeClass)
    return UITraitCollection(traitsFromCollections: [collection, overrideCollection])
}

Split personality

This post should have clarified your understanding of the expanding and collapsing process that occurs with a split view controller, its delegate and its primary view controller. You should have additional insight into things that might be giving you problems, and some useful leads on how to fix those problems.

Tools and hardware

The simulator seems unreliable at connecting to the phone simulator and the debugger. In this respect it is an accurate simulator.

Installing and debugging on the watch is a painful experience. Communication is over Bluetooth, via a connected phone. Swift watch apps have a minimum footprint of around 7MB due to inclusion of the standard libraries, so installation takes a while, if it works at all. If you’re not interested in debugging, it’s often more reliable to build and install the phone app, then use the Watch app to install the watch app, which is not an easy sentence to read.

You can’t wait for the app to launch, like you can with phones, so debugging the arrival of notifications or startup issues is not possible. That’s a shame, because the arrival of notifications and app startup is a fraught and bug-prone process.

Very often the debugger will fail to attach to the process or claim it has finished running the app. The usual dance of restarts seems to fix this, but the key to success seems to be that you need the “Trust this computer?” dialogue to show up on the watch. After that, you’re usually ok.

Because of the slow communication round trip, breakpoints and debugger commands can take some time to execute. The watch also has chronic logorrhoea, if you look at the devices tab in Xcode, which can make tracking issues by console logging (because you can’t wait for the app to launch…) something of a filtering exercise.

All of this is very hard work on the watch, which is a tiny device not designed for long periods of heavy Bluetooth and screen use. This means the battery will die rather quickly. You could put it on the charger, but then you have to enter the PIN every time to unlock the device. You could remove the PIN, but then goodbye Apple Pay. You could buy a development watch, but there’s no economic incentive to develop a watch app since they come “free” with your iOS app.

Solution? Some sort of developer dock which charges and keeps the device unlocked? Bonus points if it enables direct communication as well.

SDK

WatchKit seems very stuck with the limitations from watchOS 1 - write-only access to most UI elements being the most glaring one. That didn’t seem to present too much of an issue. The following things did trip me up; they’re mentioned in the documentation but perhaps not in big enough writing:

• WCSession messages are always handled on a background thread. If you’re making UI changes in response to them, you have to dispatch to the main thread.
• UI updates are ignored if the interface controller is not active. If you are updating UI in response to messages or network calls or something else you don’t control the timing of, you may need to maintain some separate state and update your UI when that changes, and again when the interface controller activates.
• For navigation-based interfaces there is no non-animated update to the navigation stack, which can make some UI updates jarring.
• Shared user defaults and core data storage disappeared with watchOS 2. You are responsible for shuttling data back and forth using WCSession, which can be quite tiresome.

None of the above are impossible to surmount, except the non-animated navigation stack. Overall the SDK reflects well the limitations of the device, from a capability and UX perspective. I expect improvements for watchOS 3, and will be interested to see what the next generation of devices are like.

Bugs

The major bug encountered was due to app startup in response to a notification being tapped. A lot of time was burnt on this, because the watch app does some interesting things on startup which we assumed were being done wrong, until we realised it was a simple matter of tapping the notification too quickly.

Even if that bug didn’t exist, app launching is painfully slow, and must be the major factor preventing the use of third party apps.

Good things

The best things, by a country mile, are the dynamic notifications. This allows you to build a custom UI to display in response to a notification. Since notifications are undoubtedly the watch’s “killer app”, this had to be good, and it is. The following things would be even nicer:

• Dynamic notifications without the requirement for an actual watch app. 100% of the time I just read a notification and either dismiss it or hit one of the actions (usually to delete an email or like a tweet). I don’t need to open an app on the watch, with all the waiting and the limited UI, and developers of apps that have interesting notifications but no need for a watch app should be able to take advantage.
• Dynamic notifications on iOS. Having seen what’s possible on the watch, showing a bit of text and some buttons seems terribly limited now.

Lessons

Apple say that you should expect interactions with watch apps to be measured in seconds. Assuming they’re not counting the seconds spent waiting for the app to start, this is true. Nobody wants to spend time prodding at a tiny screen whilst holding their arm up awkwardly.

The third party apps I use on the watch are:

• Runkeeper
• Omnifocus (rarely)

I have several more installed, but day-to-day I simply don’t use them. I use lots of notification actions, though.

Your watch app should deliver the absolute minimum useful level of functionality (or, it should not exist - that is a valid choice and correct in most cases!). Think very carefully before adding navigation stacks, master-detail interfaces and the like. They’re not nice to write, and not nice to use.

Start with a single screen. And in most cases, stop right there.

The secret to painless custom transitions is to do a lot of snapshots. In the talk I mentioned some utility methods for making snapshots, but there wasn’t time in the session to cover the details. Instead, I’ve written about them here.

A sensible view controller transition doesn’t move, fade or otherwise manipulate any of the view controller’s views. That way lies madness. The correct way to handle them is:

• Create a canvas view, which fills the container view of the transition context
• Snapshot everything you’re interested in moving
• Move the snapshots around, then animate them to their final positions
• Remove the canvas when you’re done

This has numerous advantages:

• No cleanup code or resetting of view properties
• You can take advantage of autolayout in your view controllers, but move the snapshots around by animating the center property, which makes much more sense when doing transitions and means you don’t need outlets to all your constraints
• Keeps the view controller very loosely coupled to the transition

Making a snapshot from a UIView is simple and fast:

let snapshot = view.snapshotViewAfterScreenUpdates(false)

The resulting view has the same bounds as the original, but has a frame origin at zero, which is usually useless.

For transitions, what is usually required is for the snapshot to be added to the canvas view, at the same position on the screen. This is done with an extension on UIView:

func snapshotView(view: UIView, afterUpdates: Bool) -> UIView {
    let snapshot = view.snapshotViewAfterScreenUpdates(afterUpdates)
    self.addSubview(snapshot)
    snapshot.frame = convertRect(view.bounds, fromView: view)
    return snapshot
}

You call the function like this:

let snapshot = canvas.snapshotView(view, afterUpdates: false)

For an array of views, another method in the extension:

func snapshotViews(views: [UIView], afterUpdates: Bool) -> [UIView] {
    return views.map { snapshotView($0, afterUpdates: afterUpdates) }
}

Snapshotting is so common and so useful when doing transitions, and these extension methods make your transition code much more readable and obvious.

The full source is here:

Nobody’s going to pay you to make a Flickr or Twitter client, which is inconvenient because that’s what most of the online examples seem to use. If you’ve never written code that interacts with a web API before, it’s hard to approach these things with confidence, especially if you’re expected to talk to the developers of that API to work out any issues, and if those APIs are being written and rewritten in parallel with the development of the app.

In this article I’m going to go over the basics of your networking code. I’m going to assume you’re working with an API from this century so we’re talking about JSON and REST¹. If you’re hearing terms like SOAP from your web people then run away.

Structure

You interact with a web API the same way you interact with the web when browsing: via a URL. Here’s one:

https://api.staging.example.com/widgets/details?id=123456

And here’s a breakdown of what each part means, and is called:

• https:// - this is the scheme. For most services this will be https, but sometimes the staging server will run http. This makes it easier to debug and cheaper to run (since you don’t need a certificate and the traffic is unencrypted). The production server should really be running https. As of iOS9, any requests to http endpoints will fail unless you whitelist them as App Transport Security exceptions.
• api.staging.example.com - this is the domain. You’d expect different values here to point to different servers (live, testing etc). When coupled with the scheme it is referred to as the base URL. Usually this value is switched out depending on your build settings, so you can make builds targeting different servers without having to change your code.
• /widgets/ - this is the path. It should be a sensible, human-readable string or strings, separated by / characters, giving you some idea of the part of the API you’re talking to.
• details - this is the endpoint. This describes exactly what you’re asking (or telling) the API - it’s like the method name.
• ?id=123456 - this is the query string. It’s like the parameters of the method that you’re calling.

So the URL above is asking, securely, for the details of the widget with id 123456 from the staging server at example.com. There’s a lot of information in that URL!

GET and POST

You’ll use these two types of requests. Which one is at the discretion of the people writing the web services, but as a general rule, it’s usually GET unless you’re uploading some data, like an image file. It’s possible (though not recommended) for a GET request to be used to update the server, so the distinction isn’t black and white.

Building a URL

You’ve seen all the components of a typical web service URL. How do you go about building them in code? If you’re thinking “stick a bunch of strings together and create an NSURL” then this is exactly the article for you.

Using strings is a bad idea. If you have a format string like ?this=%@&that=%@followed by a comma-delimited list of string variables, that is unreadable, unmaintainable code. Not only that, if your user has entered some of that data you’re going to break the internet² if they’ve entered an ampersand or an equals or one of the several other characters that URLs use for structure rather than content.

There is a nice way to build up a URL. It’s called NSURLComponents. This class breaks down all the various parts of a URL into properties, allowing you to read or assign them one by one. You can get the full URL out at any point:

// Create from base URL
let components = NSURLComponents(string: "http://api.example.com")!
// components.URL is http://api.example.com

//  Add path
components.path = "/widgets/details"
// components.URL is http://api.example.com/widgets/details

// Create query items
let queryItem = NSURLQueryItem(name: "id", value: "123456")
components.queryItems = [queryItem]
// components.URL is http://api.example.com/widgets/details?id=123456

let sillyItem = NSURLQueryItem(name: "escape", value: "?&-=")
components.queryItems = [queryItem, sillyItem]
//components.URL is http://api.example.com/widgets/details?id=123456&escape=?%26-%3D

Making a request

I’m going to be bold here and say that you don’t need to use a third party networking component. The Foundation networking classes are good enough for most purposes since the change to NSURLSession. Any wrappers around this do little more than obscure your knowledge of how those classes are doing their jobs.

I’m not going to go into the full details of how to use NSURLSession here, but this playground code should give you some idea of how simple it is:

import Foundation
import XCPlayground

XCPSetExecutionShouldContinueIndefinitely(true)

let letters = NSURL(string: "http://private-8f863-commandshift.apiary-mock.com/letters")!

let request = NSMutableURLRequest(URL: letters)
let session = NSURLSession.sharedSession()
let task = session.dataTaskWithRequest(request) {
    (data, response, error) in
    
    if let error = error {
        error
        return
    }
    
    guard let response = response as? NSHTTPURLResponse  else { return }
    guard response.statusCode == 200 else {
        print("Status \(response.statusCode) returned")
        return
    }

    guard let data = data else { return }
    do {
        let json = try NSJSONSerialization.JSONObjectWithData(data, options: [])
        json
    } catch _ {
        print("Oops")
    }
    XCPSetExecutionShouldContinueIndefinitely(false)
}

task.resume()

You can substitute any URL (or build one with components) and immediately see the responses you get. I like to follow a four-stage process in these completion handlers:

1. Handle the error parameter: This is returned when something went wrong meaning the connection attempt could not even be made.
2. Handle the response code: Non-20x responses can mean a variety of problems, and how you deal with them depends very much on the needs of your app.
3. Handle server-level errors: Often a completely valid JSON response will contain an error flag or error dictionary. You’ll usually want to build your own error object out of this.
4. Handle the valid JSON: This is the “happy path”. Here you’ll be parsing out model objects and updating your app.

None of this code should be in a view controller, by the way! Your view controllers should, at most, be asking some other object to go fetch stuff, and passing in a completion block with a single error and a single data parameter to be executed when done. But that’s a whole other post.

Tools

The playground code above is a great way to explore a new API - you can quickly change the URL and see results instantly. But it’s a bit of a mess, and you’re changing the same thing over and over again rather than building up a good idea of the responses and calls you are working with. Enter Paw, an indispensable and very nicely done app (no affiliation, I am a happily paying customer) which allows you to build up a set of API calls and tweak them with variables, environments, and view the responses. It will even, with plugins, generate the Objective-C or Swift code just like that shown above.

Maybe your API hasn’t been written yet. You could mess about with locally stored JSON files and proxies and so forth to make up for that, or you could use a service like Apiary which allows you to stand up quick responses to calls - all you have to do when you’re done is switch out the domain. I’m using Apiary for the example above.

The next important thing about writing your networking code is to use unit tests. Having to run through your UI tapping buttons and so on to see if you’ve done your networking right is silly, and you need to stop it. Asynchronous unit tests are a doddle now that XCTestExpectation exists, and since you’re not putting your network code is in a view controller it’s all much more testable.

Once your code is up and running you may have further problems. Maybe the API isn’t ready, or you want to get a specific response, or you just want to see the exact responses coming back at a specific time for a specific request, or you want to see what happens if you get a 404 or an error or a timeout. It’s time for Charles which, a bit like AppCode, is so useful and powerful you can overlook how hideous it looks. (Again, no affiliation, happily paying customer!) Charles can do all of these things and more, by acting as a proxy and showing you all the traffic passing between the iOS simulator, or your device, and the internet (unless that traffic is correctly using certificate pinning and is secure!). You can replace calls with local text files, breakpoint on requests or responses and edit the contents, rewrite data according to your own rules. I probably know how to use about 10% of its power and I’m getting my money’s worth. You know those ridiculous high scores on Game Center? Pretty sure that’s Charles. Not me though, I’m all natural.

Meanwhile, back in reality, you’re working on an app that was first written for iOS4 and each of the dozen developers who’ve had a month to implement or fix things since then have gone in, done their stuff and moved on. Things get complicated. If you’re asked to work on an app, either to bolt more stuff onto it or (hooray!) to do some cleanup, then the very first thing you need to do is work out where you are and what’s going on.

I gave a lightning talk at iOSDevUK this year. I had five minutes to talk, so thought I’d cover the relatively simple(!) topic of how to navigate a massive, new codebase when you’re dropped in as a new developer and asked to fix problems or implement new features, right now. Here are the points I was trying to get across.

What’s on the screen?

It’s fairly simple to see which views are on the screen, thanks to the view debugger in Xcode (when it works) or tools like Reveal.

However, when you’re trying to work out where in the app you need to make changes, what’s often more useful is knowing which view controllers are currently in play. Most of the action in most iOS apps happens, or at least is kicked off, from code that lives in a view controller.

To find out what you’re looking at, you can pause the app in the debugger and type this:

po [[[UIWindow keyWindow]  rootViewController]  _printHierarchy]

This gives you a hierarchical list of the view controllers that are currently on screen, from the bottom up. A navigation controller will have the current stack displayed and any presented or child controllers will be included. If your app is showing child controllers without adding them to the hierarchy, you have another problem to solve.

The above command is quite long so at this point I’d recommend looking at Chisel, a collection of LLDB commands maintained by Facebook. Once you’ve installed Chisel you can type pvc instead, which is much easier.

What happens when I touch this?

The previous developer (don’t we all love to hate the previous developer, even if it was us) may have been “clever” in their use of code. Sometimes it’s not clear at all what happens when a button is tapped. To find out literally everything that ever happens in the app you’re working on, pause in the debugger and type this:

rb . -s MyApp

Replacing MyApp with the name of the current target. This magic incantation creates a regular expression breakpoint, using the rather unspecific regular expression of ., in the shared library known as MyApp. This creates a breakpoint on every method of your app. Every. Method. Of. Your. App. If you have timers or regular network hits, you may not get much use out of this, but otherwise it can really speed up your code navigation.

LLDB will create all of those breakpoints under a single umbrella breakpoint. This may take a while. You’ll want to turn them off again pretty sharpish since it makes actually working in the app quite painful. To do that, type this:

br li -b

This gives you a list of all the current breakpoints. Your regex one will be obvious, and it will have a number. To get rid of it, type this:

br delete X

Where X is the number.

Logjams

That idiot previous developer put hundreds of log statements in the app. Maybe they were a little bit helpful and made them DLog statements so they didn’t log plaintext passwords out to a customer’s device. However you still can’t use logging to find out when things happen (NSLog(@"IN VIEW DID APPEAR!!");) because there’s so much noise in there.

Good.

You shouldn’t be adding log statements for navigation anyway, and neither should that previous developer. You’re creating code changes, which you’ll need to roll back whenever you finally work out what the problem is.

To hide all that noise from the debugger console, look at the bottom of the window. There’s a popup there that says “All Output”. Click that and change it to “Debugger Output”. Now the only things you’ll see in the console are messages from the debugger.

Add a breakpoint in the method you’re interested in. Edit the breakpoint (right-click and choose Edit Breakpoint…). Choose Log Message as the action, and type your navigational info in there. Check Automatically continue…:

Now when you hit that breakpoint, it puts your message out into the clean, uncluttered debug console.

App mapping

You can combine two of the previous tips with a third and you have an instant method of mapping out screen changes in your app.

Create a symbolic breakpoint on -[UIViewController viewDidAppear:]. Add pvc as the debugger action and choose to automatically continue. Now exercise your app - as you move around and show screens, you’ll be shown a continuously up-to-date list of all the view controllers being put on the screen at the same time.

These few simple tips have really helped me when I’ve been dropped in an enemy codebase with no map. I hope they help you too.

I found out a few things that don’t seem to be represented very well in the documentation or the examples floating round online, so here they are.

Image request completion blocks

For .Opportunistic delivery mode requests, which is the option you want when scrolling through an album, the completion block may be fired multiple (usually two) times - the image manager will get a fast, low-quality version, call the completion block, then call it again when it gets a higher quality version.

What’s important to note is that the first completion block can be executed before the request function has returned. This has a few implications.

Async processes kicked off during cell configuration typically run like this:

1. Kick off the request
2. In the completion block, get the cell of interest, and set the relevant property

This setup means that if the async process takes some time to return, and the cell has been reused, the data isn’t assigned to the wrong cell. You normally don’t just capture the cell inside the completion block, then configure it, you’d normally capture the index path, then use that to get the appropriate cell from the table or collection view. If that returns nil, your cell is offscreen.

However, for a completion block that can be executed immediately or after some time, that pattern can’t apply. You need to assign some identifier to the cell before you request the image, then check that identifier is the same when the completion block runs.

Apple’s sample code uses an incrementing integer value which is assigned to the tag of the cell. Normally I wouldn’t touch the .tag property with a bargepole but this use almost makes sense. You could also use a property to hold the index path. You can’t use the request identifier, since the block can be executed before the request identifier has even been returned.

The completion block is also called if the request is cancelled, so if you’re canceling requests while scrolling (which is a good idea), you need to bear that in mind. You can see if the completion block is called for a cancelled request by checking in the info dictionary.

Finally, for reasons unknown, sometimes image requests would simply never return a full sized image. The completion block would be called, there would be nothing amiss in the info dictionary, but the result comes back as nil. I had a single image where this would happen all the time.

Resizing mode

For scrolling through a large library, always use the .Fast resizing mode. You’d think that .Exact combined with opportunistic delivery would be optimal, but I found it made a huge performance difference, for no discernible quality difference, to stick with .Fast.

Caching

PFCachingImageManager is well worth using. For a huge library, you can’t cache everything, and if the user is scrolling super fast then caching doesn’t seem to offer much advantage. It does work very well for caching a few screens-worth of images either side of the current scroll position - with this in place you get high-quality thumbnails very quickly when scrolling to the next page of images.

Ignore caching when scrolling, but update the caches when scrolling stops, was the combination I settled on in the end.

It’s very tempting to optimise for the “scroll like a madman through the entire library” use case, it’s very satisfying seeing those 60fps numbers and thinking of all the super-fast work that’s happening, but it’s only developers and QA engineers that do that in real life!

Change notifications

If you register for library change notifications, be very careful about how you handle them. It appeared to me that change notifications would come through very frequently when using an album built from a fetch request (which was every album in the project). The PHFetchResultChangeDetails object would contain incremental changes, which lead you to believe that there’s only a few updates to deal with, but then I’d see hundreds of indexes in the changedIndexes. Telling the collection view to reload all those cells, as suggested in the documentation, was a performance killer.

I believe that these notifications are sent out when the framework is updating its “optimised storage” of the library, replacing its local caches with larger or smaller versions of the images. If you’re showing an album view with identically sized thumbnail cells then you can safely ignore changes if they apply to cells outside the visible area.

Moves, insertions and deletions seemed more reasonable and handling them as described in the documentation was fine.

Hardware environment

When you’re testing, the phone and the environment make a huge difference. Network access speed and device free space all affect performance. I had the same 10,000-image photo library take between 1.5GB and 5GB, depending on the available space on the device. This means your library is going to be faster on the device with more space, since it doesn’t have to fetch from iCloud as often.

Closing thoughts

The Photos framework is a big improvement over the Assets Library, and it does a great job of dealing with network requests, image resizing and caching for you. It would be amazing if it could also be used to deliver images from partner services like Facebook - there is already OS-level integration with some services, and extending it to Photos would make my job a lot easier!

The two biggest new features, which we used almost everywhere in the app, were collection views and autolayout.

The app was built almost entirely in code, meaning a lot of constraint creation. My autolayout helper category was written to help build it.

Now it’s time for that category, and all the others (and there are loads), to be deprecated.

Any “helper” category or wrapper introduces the following costs versus using the native API:

• Installing and maintaining a dependency
• Learning an additional API or DSL
• Masking the native functionality and therefore obscuring some understanding of how things actually work
• An extra possible source of bugs when things aren’t working
• Vulnerability to changes made by the OS vendor or library maintainer that break your work

If the helper category’s benefits offset these costs, then fine, go ahead. But if they don’t, you should not be using it.

As an example, my category uses left/right instead of leading/trailing. It wasn’t an issue for me (and I had no idea of the significance when I was writing it) since the app wasn’t due to be localised. If your app will be localised for RTL languages, you shouldn’t be using my category.

It’s also now recommended to create constraints first and activate them in a set. My code doesn’t do that. My code doesn’t take layout margins into account either. Do any of the others? I don’t know, and I don’t care, because they are all redundant.

Why did we need layout helpers?

• Interface builder was awful for creating constraints, therefore it was easier in code
• The constraint API was verbose and common tasks took too much boilerplate.

Why don’t we need them any more?

• Interface builder should now be your default option for creating your UI. Seriously. It’s really good now, and I can’t imagine making an adaptive interface using size classes in code.
• Stack views should be your default option for layout anyway.

With these changes alone, you’d be making constraints in code so rarely that the benefits of adding a layout helper aren’t worth it. I haven’t used my own category in the last couple of projects I’ve worked on.

But there’s more. Layout Anchors make many common constraint creation tasks much easier as well.

What now?

Helper categories and wrappers have their place. But don’t use them mindlessly. Learn enough about what they are helping you with to know if you need them, and re-assess at new version releases if they are still relevant and if they are being updated to reflect the state of the art.

Using and understanding the first-party API should always be your preferred option.

Now, excuse me while I go and write a helper library for the new Contacts API.

If you write a bit of code that does something, and elsewhere in your program you need to do the same or a very similar thing, don’t copy and paste the bit of code. Make it accessible from both places, and make the minimum set of changes needed to make it reusable.

“Boilerplate” code refers to code that has to be included regularly and without much alteration to achieve basic functionality. There are plenty of frequent, common operations that require a lot of boilerplate code. The boilerplate code obscures what you actually want to do and makes the program harder to read. A good example is inserting managed objects into a context. For each type of managed object, the code looks almost exactly the same, but different types are involved.

I’m going to discuss some of the boilerplate code encountered in Core Data, and how you can use Swift generics to DRY out some of these operations. First, a few words about generics.

Generics in functions

Generics in functions allow code to be flexible about types at writing time, but strict at compile time. They work by having type tokens for each non-specified type involved in the function. The type tokens can be completely generic, or have protocol restrictions on them. For example, for kicking off a nice web service request, I have this function:

func startRequest<C : WebServiceConfiguration, R : WebServiceResponse>(configuration: C, completion:(response:R?, error:NSError?)->Void)

Don’t panic! Here’s a breakdown:

• startRequest - this is the name of the function
• <C : WebServiceConfiguration, R: WebServiceResponse> - these are the type tokens. Here we have two generic types, C and R. C has to conform to the WebServiceConfiguration protocol, and R has to conform to the WebServiceResponse protocol.
• configuration: C - the first parameter is of type C, which as we’ve noted above must conform to the WebServiceConfiguration protocol.
• completion:(response:R?, error:NSError?)->Void - the second paramater is a closure, which takes an optional R (conforming to WebServiceResponse and an optional error.

The type tokens don’t have to be single letters, though they are in nearly every example I’ve seen. You can use longer terms, but then the whole function definition can get quite long.

You call the function like so:

let loginConfiguration = LoginConfiguration(username: username, password:password)
startRequest(loginConfiguration) {
  (response : LoginResponse?, error) in
  // Do stuff...
}

The compiler can tell from this code that we’re calling startRequest using a LoginConfiguration for the C type token, and a LoginResponse for the R type token. Clever stuff!

startRequest is the only function you ever call when kicking off a web request. There’s no need for a separate function for each API endpoint!

Generics in container types

As well as function arguments, generics are also used for container types - the most common example being the Optional enum, but also Swift’s typed arrays and dictionaries. Those aren’t as interesting for this discussion, though.

Core Data - inserting objects

To insert a new entity in your context, the following code is required:

let person = NSEntityDescription.insertNewObjectForEntityForName("Person", inManagedObjectContext: context) as! Person
person.name = "Bob"
...

Yes, it’s only one line, but it’s quite a long one, there’s a constant string in there, and you need to force cast to a Person because insertNewObject... returns AnyObject.

I find it’s useful to think of how a function might look before I get around to implementing it. For inserting an object, I have the following requirements:

• We need a managed object context
• I don’t want to have to write the class of the inserted object more than once
• It must be obvious what is happening
• No type casting required.

I’d like to do this:

let person = context.insert(Person)

First, get rid of the constant string with an extension on NSManagedObject:

extension NSManagedObject {    
  class var entityName : String {
    let components = NSStringFromClass(self).componentsSeparatedByString(".")
    return components[1]
  }
}

This assumes your entity names always match your class names. The processing is to remove the module name from the start. If you have any entities that don’t follow this rule, you’d have to override this method in the appropriate NSManagedObject subclass.

Now, you can write the following extension for NSManagedObjectContext:

extension NSManagedObjectContext {
    
    func insert<T : NSManagedObject>(entity: T.Type) -> T {
        let entityName = entity.entityName
        return NSEntityDescription.insertNewObjectForEntityForName(entityName, inManagedObjectContext:self) as! T
    }
    
}

There’s a small amount of magic happening here. The type token, T, has a specifier saying that the type used must be a subclass of NSManagedObject. The last line of the function is pretty much the same as the original insert code used above, using the forced cast. But in the function definition, I’m using T.Type, not T. This means the function is expecting the entity parameter to be a type, rather than an instance of an entity.

Generics have allowed me to write a function where I pass in a class, which is guaranteed to return an instance of that class.

As desired, this can be called like this:

let person = context.insert(Person)

But there’s more. To support unit testing or development of an app, it is extremely useful to be able to quickly produce a set of sample data. For example, I’d like to create 10 Person objects like this:

context.createTestObjects(10) {
  (person: Person, index) in
  person.name = "Test Person \(index)"
}

That’s pretty straightforward as well. As an extension on NSManagedObjectContext:

func createTestObjects<T: NSManagedObject>(count : Int, configuration : (object: T, index: Int) -> Void){
  for testNumber in 1...count {
    let object = self.insert(T.self)
    configuration(object: object, index: testNumber)
  }
}

Here, the type is inferred from the parameter list in the configuration closure. In the last app I made this was probably the most useful method in there, allowing me to create a reasonable set of test data almost instantly for unit testing and building the UI.

Core Data - fetching objects

Here’s how you fetch objects from a context:

let request = NSFetchRequest(entityName: "Person")
var error : NSError? = nil
let people = context.executeFetchRequest(request, error: &error) as? [Person]
if let error = error {
  // Better do something about that error...
} else {
  // Do something with all those people....
}

The error checking, while not terribly useful for users of your app, is absolutely essential for you, the developer. But if you have to write all that boilerplate for every fetch request in your app, are you really going to be checking them all?

First of all, there’s that hardcoded string for the entity name. We’ve already solved that problem when inserting objects. The same applies again, in an NSManagedObject extension:

class func fetchRequest() -> NSFetchRequest {
  return NSFetchRequest(entityName:self.entityName)
}

class func fetchRequestWithKey(key: String, ascending: Bool = true) -> NSFetchRequest {
  let request = fetchRequest()
  request.sortDescriptors = [NSSortDescriptor(key: key, ascending: ascending)]
  return request
}

The second version allows you to add some sort descriptors by supplying the key and an ascending flag, which is often useful.

The fetch operation itself can be made generic. The context performs the fetch so you can add the following extension to NSManagedObjectContext:

func fetchAll<T : NSManagedObject>(entity: T.Type, key:String? = nil, ascending:Bool = true) -> [T] {
  let fetchRequest : NSFetchRequest = {
    if let key = key {
      return entity.fetchRequestWithKey(key, ascending: ascending)
    } else {
      return entity.fetchRequest()
    }
  }()
  
  var error : NSError? = nil
  if let results = executeFetchRequest(fetchRequest, error: &error) as? [T] {
    return results
  }
  return [T]()
}

You can call this like so:

let people = context.fetchAll(Person)

Or, for ordering:

let people = context.fetchAll(Person.self, key:"name", ascending:true)

Why it has to be Person.self for the second example I am not sure. If you know why, please tell me!

Summary

• If you find yourself writing the same code, where only the types are different, consider generics.
• Generics are powered by type inference, and the types can be inferred from arguments passed in, the variable a function’s return value is assigned to, or more complex ways such as the parameter list to a block.
• Generics can be useful for reducing boilerplate code, but always bear in mind future readers of your code (including yourself). Don’t make existing APIs unrecognisable and force maintainers to learn a whole new one without good reason.

##How scrollviews work

A UIScrollView is a UIView subclass, so it has a frame which is, just as with any other UIView, the position and size of the scroll view in its superview.

The point of a scrollview is to contain one or more subviews, which are too big to fit inside the scrollview and still be completely visible. These subviews, when laid out and sized in the correct fashion, will fill an area the size of the scroll view’s contentSize. Each subview’s frame will be in the coordinate space of the scroll view’s bounds rectangle.

I’ll use an example to spell that out more clearly.

On an iPhone 5 the screen is 320 points wide. We want a carousel view with horizontal scrolling. Each image in the carousel will be 200 x 200 points. The first image view’s frame origin will be at (0,0) in the scroll view, the second will be at (200,0), the third at (400,0) - before any scrolling happens, this third view will be off the edge of the screen.

When scrolling happens, the frames of these subviews do not change. But as a great man once said, “And yet it moves”. What’s happening?

Scrolling affects the bounds of the scroll view. From the documentation for bounds:

On the screen, the bounds rectangle represents the same visible portion of the view as its frame rectangle. By default, the origin of the bounds rectangle is set to (0, 0) but you can change this value to display different portions of the view.

By changing the origin of the bounds of the scroll view, you display different parts of the content:

• Increasing the origin X moves the content left
• Decreasing the origin X moves the content right
• Increasing the origin Y moves the content up
• Decreasing the origin Y moves the content down

The size of the bounds rectangle remains the same as that of the frame, because the amount you can see is the same.

The subviews in the scroll view don’t know they are being moved. By scrolling, the user is moving a window around on top of the scroll view’s content view.

But of course, it gets more complicated

When scrolling programmatically or asking for the scroll view’s current scrolling position, we don’t work with the bounds origin. There is a contentOffset property instead, which is equivalent to the origin of the bounds rectangle. This is more obvious in intent than addressing the origin of the bounds directly.

Driving such features as pull-to-refresh and transparent navigation bars is the contentInsets property. This takes a UIEdgeInsets value which affects where the “natural” edges of the content are within the scroll view. It’s not immediately obvious what the implications of this property are, but I find it helpful to think of it as a way of setting where the bouncing effect of the scroll view is anchored:

The blue box represents the edges of the scroll view, the red box indicates the content insets.

For example, take a standard app with a navigation bar and a scrollview. The scrollview extends behind the navigation bar and status bar, so the bounds rectangle is the full screen size, but when you pull down the content and release it to bounce, it bounces back to just underneath the navigation bar. This isn’t because the content starts 64 points down from the top of the scroll view, it’s because the scrollview has a contentInsets.top of 64. When the scrollview bounces to the top, it comes to rest with a content offset of -64.0 in the Y direction:

Pull-to-refresh controls work by adding additional values to the top content offset, to hold the scrollview content down while the indicator is showing the activity.

Learning by fiddling about

That is a whole lot of theory, and reading about scroll views isn’t the best way to understand the mechanics of them. I’ve made a demo project which allows you to see and adjust the numbers for a scroll view. I found it very useful when writing this article, hopefully it will aid your understanding as well. The demo project was used to generate the animated screenshot above.

UPDATE: I’ve amended the sample project to also list all the delegate calls that happen when scrolling occurs.

Further reading

objc.io has a great discussion of how scrollviews work. In summary, it all comes down to rectangles (doesn’t everything?). Ole Begemann has also written a fantastic overview.