Size, Count, Spacing, and Insets

As you construct a compositional layout, you must specify the size of a section’s group, the size of an item in the group, and the count of items per group. These are the most important determinants of how the cells will be laid out in the section; further refinements are provided through various spacing and inset properties.

Size is specified using the NSCollectionLayoutSize initializer init(widthDimension:heightDimension:). A dimension is an NSCollectionLayoutDimension, which has four class methods:

absolute

A definite number of points.

fractionalWidth

fractionalHeight

A proportion, between 0 and 1, of the container. For an item, the container is the group. For a group, the container is the collection view bounds. These are just numbers, so it is legal for the heightDimension: to be a fractionalWidth and vice versa.

estimated

A number of points, but you are inviting the layout engine to measure cells using internal autolayout constraints to determine the actual value. A common situation is that one dimension of a size is fixed while the other is estimated.

A group is instantiated using the horizontal or vertical class method. You supply parameters in two different ways:

horizontal(layoutSize:subitems:)

vertical(layoutSize:subitems:)

The group repeats one or more item types, as many per group as will fit. Suppose the subitems: consists of two item types, one wide and one narrow; then the layout will alternate wide item with narrow item, filling a group before going on to the next group.

horizontal(layoutSize:subitem:count:)

vertical(layoutSize:subitem:count:)

The group repeats a single item type, a fixed number of times per group. The items will be equally sized, possibly overriding the item’s own size in that dimension. For instance, you can specify that there should be exactly three equally sized items per group.

Apple’s own examples illustrate some basic combinations of item size, group size, and item count; these are all vertically scrolling collection views, so a group is a row:

• The item has width dimension fractional width 1 and height dimension fractional height 1. The group has width dimension fractional width 1 and height dimension absolute 44, and the subitems: initializer is used.

  So each row is as wide as the collection view and 44 points tall, with one item per row, filling the row. It looks rather like a table view.

• Like the previous layout, but the group’s subitem:count: initializer is used with a count: of 2.

  So there are exactly two cells per row and they have equal widths; the item’s layoutSize: width dimension is effectively ignored.

• The item has width dimension fractional width 0.2 and height dimension fractional height 1. The group has width dimension 1 and height dimension fractional width 0.2, and the subitems: initializer is used.

  So an item’s width is one-fifth the width of the collection view, and a row’s height is that same value — and an item’s height fills it, resulting in a grid of square cells, five per row.

Further size refinements are applied through spacing and insets properties of the item, group, and section:

Item edgeSpacing

An NSLayoutEdgeSpacing object with leading:, top:, trailing:, and bottom: parameters. A parameter is either nil or an NSCollectionLayoutSpacing object, instantiated through a class function, either flexible or fixed. For instance, in a vertically scrolling layout whose group uses the subitems: initializer, if there is room for only one cell per group, then a leading: and trailing: spacing of .flexible(0) will center the cell horizontally.

Group interItemSpacing

The distance between items within the group. This is also an NSCollectionLayoutSpacing, so it can be flexible, causing the items to be spaced out equally and justified at both extremes.

Section interGroupSpacing

A CGFloat determining absolutely the distance between rows (or columns) in the section.

Layout interSectionSpacing

A CGFloat. A property, not of the layout itself, but of its configuration, a UICollectionViewCompositionalLayoutConfiguration (a value class). The configuration is also how you specify the layout’s scrollDirection; the default is .vertical, so if that’s what you want, and if you don’t need to set the section spacing, you might not need a layout configuration.

Item, group, or section contentInsets

An NSDirectionalEdgeInsets (Chapter 1). Content insets are applied after the sizing and layout have been worked out. In Apple’s example of a grid with 5 square cells per row, if a positive contentInsets is applied to the item, there are still five cells per row, each in a square area, but a cell itself is inset within that square area. (Any contentInsets along an estimated dimension are ignored.)

You now know almost enough to achieve the layout shown in Figure 9-1 as a compositional layout! I haven’t talked yet about section headers, and the first section’s single item needs to be wider than all other items; but if we concentrate on just the items of the remaining sections, we can construct the layout like this:

private static func prepareLayout() -> UICollectionViewLayout {
    let itemSize = NSCollectionLayoutSize(
        widthDimension: .absolute(70),
        heightDimension: .fractionalHeight(1))
    let item = NSCollectionLayoutItem(layoutSize: itemSize)
    let groupSize = NSCollectionLayoutSize(
        widthDimension: .fractionalWidth(1),
        heightDimension: .absolute(45))
    let group = NSCollectionLayoutGroup.horizontal(
        layoutSize: groupSize, subitems: [item])
    group.interItemSpacing = .flexible(10)
    group.contentInsets = NSDirectionalEdgeInsets(
        top: 0, leading: 20, bottom: 0, trailing: 20)
    let section = NSCollectionLayoutSection(group: group)
    let vSpace = CGFloat(10)
    section.contentInsets = NSDirectionalEdgeInsets(
        top: vSpace, leading: 0, bottom: vSpace, trailing: 0)
    section.interGroupSpacing = vSpace
    let layout = UICollectionViewCompositionalLayout(section: section)
    return layout
}

Here’s how that compositional layout mimics the flow layout shown in Figure 9-1:

Flow behavior

The compositional layout lays out its rows like a flow layout, because:

• The group uses the subitems: initializer, meaning that a row consists of as many cells as will fit.

• The group uses .flexible interitem spacing, which causes the cells to be justified at the leading and trailing edges with equal spacing between them.

Cell size

In the flow layout, we set an itemSize of CGSize(70,45). In the compositional layout, the same effect is achieved like this:

• An item has width dimension absolute 70 and height dimension fractional height 1.

• The group has width dimension fractional width 1 and height dimension absolute 45.

Margins

The flow layout has a sectionInset with a UIEdgeInsets value (10.0,20.0,10.0,20.0). In the compositional layout:

• Horizontally, each group has leading and trailing margins.

• Vertically, each section has top and bottom margins along with spacing between the rows.

Supplementary Items

In a compositional layout, supplementary items come in two main categories:

NSCollectionLayoutSupplementaryItem

An item or group’s supplementaryItems. An item’s supplementary items must be declared in the item initializer; a group has a settable supplementaryItems property.

The initializer is init(layoutSize:elementKind:containerAnchor:itemAnchor:):

• The elementKind: is an arbitrary string.

• The anchors are NSCollectionLayoutAnchor objects; the item anchor is optional. An anchor has edges (an NSDirectionalRectEdge) along with an optional absoluteOffset or fractionalOffset, which is a CGPoint. An NSDirectionalRectEdge is an option set consisting of .top, .trailing, .leading, and .bottom.

A supplementary item also has a zIndex for front-to-back layering. Apple’s example of an item’s supplementary item has edges [.top, .trailing] and a fractionalOffset of CGPoint(x:0.5,y:-0.5); that’s a badge centered at the top right corner.

NSCollectionLayoutBoundarySupplementaryItem

An NSCollectionLayoutSupplementaryItem subclass. Can be applied to a section or a layout:

• A section has a settable boundarySupplementaryItems property.

• For a layout, its configuration has a boundarySupplementaryItems property.

A boundary supplementary item has an alignment which is an NSRectAlignment, along with a possible absoluteOffset. The NSRectAlignment is an enum specifying a single edge or corner: .top, .topLeading, .leading, and so on; a header in a vertically scrolling layout would be attached to the section’s .top. If the supplementary item’s extendsBoundary is true (the default), it lies outside what would otherwise be the layout size of its container. There is also a pinToVisibleBounds property so that a section header or footer can behave like a table header or footer.

We are now ready to add section headers to the Latin LessonListController example! As we construct the section, we insert these lines:

let headerSize = NSCollectionLayoutSize(
    widthDimension: .fractionalWidth(1),
    heightDimension: .absolute(40))
let header = NSCollectionLayoutBoundarySupplementaryItem(
    layoutSize: headerSize, elementKind: "header", alignment: .top)
section.boundarySupplementaryItems = [header]

I’ve used an arbitrary elementKind: string "header". Its significance is that I use the same string to register the reusable view class with the collection view:

self.collectionView.register(
    UICollectionReusableView.self,
    forSupplementaryViewOfKind: "header",
    withReuseIdentifier:self.headerID)

Our implementation of collectionView(_:viewForSupplementaryElementOfKind:at:) is called, and section headers now appear in the layout! Our compositional layout now looks almost identical to the original flow layout in Figure 9-1. Only the first section is wrong; I’ll deal with that now.

Multiple Section Layouts

In the layout shown in Figure 9-1, the first section needs to be special. It should have no section header, and its single cell needs to be wider than the subsequent cells. With a flow layout, we took care of these differences with two UICollectionViewDelegateFlowLayout methods. With a compositional layout, we handle section differences by changing the layout initialization slightly. Currently, we have this:

let itemSize = NSCollectionLayoutSize( // ...
// ...
let section = NSCollectionLayoutSection(group: group)
// ...
let layout = UICollectionViewCompositionalLayout(section: section)
return layout

We change it to this:

let layout = UICollectionViewCompositionalLayout { index, env in
    let itemSize = NSCollectionLayoutSize( // ...
    // ...
    let section = NSCollectionLayoutSection(group: group)
    // ...
    return section
}
return layout

Instead of the UICollectionViewCompositionalLayout initializer init(section:), we are now using init(sectionProvider:). The parameter is a section provider function that is called for each section. Each time, it is fed the index number of that section, and returns the section. So the section we construct can differ depending on the index number! The starred comments mark the lines where we behave differently; if this is the first section, an item is 150 points wide instead of 70 points wide, and we don’t attach the header:

let layout = UICollectionViewCompositionalLayout { index, env in
    let itemSize = NSCollectionLayoutSize(
        widthDimension: .absolute(index == 0 ? 150 : 70), // *
        heightDimension: .fractionalHeight(1))
    // ...
    let section = NSCollectionLayoutSection(group: group)
    // ...
    let header = NSCollectionLayoutBoundarySupplementaryItem(
        layoutSize: headerSize, elementKind: "header", alignment: .top)
    if index != 0 { // *
        section.boundarySupplementaryItems = [header]
    }
    return section
}
return layout

The second parameter in the section provider function (env) is an NSCollectionLayoutEnvironment object, a value class consisting of two properties:

container

An NSCollectionLayoutContainer telling us the contentSize and contentInsets of the overall layout.

traitCollection

The current UITraitCollection for this view.

The section provider function is also called whenever the layout environment changes. Using the environment object, you can make your layout differ depending on the size or orientation of the view. Apple’s example is a grid of cells that has five cells per row, unless the view is wider than a certain amount — in which case it has ten cells per row.

Other Compositional Layout Features

This section describes some further compositional layout features.

Manual cell layout

So far, we’ve been sizing our cells (items) by initializing a group with the .horizontal or .vertical class functions and giving an item a layoutSize. But there’s another way. You initialize the group with the .custom class function. You supply an item provider function: it receives an NSCollectionLayoutEnvironment (whose container reports the content size and content insets of this group), and returns an array of NSCollectionLayoutGroupCustomItem objects. This is a value class consisting of a frame and an optional zIndex. You are now in complete charge of how many cells this group contains and what their frames should be.

In this example, the height of each cell in the row is a little smaller than that of the preceding cell; a new row starts when there are too many cells or the cell height becomes vanishingly small (Figure 9-2):

Figure 9-2. Manual cell layout

let group = NSCollectionLayoutGroup.custom(layoutSize: sz) { env in
    var items = [NSCollectionLayoutGroupCustomItem]()
    let w = CGFloat(40)
    var frame = CGRect(0, 0, w, env.container.contentSize.height)
    while true {
        items.append(NSCollectionLayoutGroupCustomItem(frame: frame))
        frame.origin.x += w + 10
        frame.size.height -= 6; frame.origin.y += 3
        if frame.size.height < 20 {
            return items
        }
        if frame.maxX > env.container.contentSize.width {
            return items
        }
    }
}

Nested groups

A group is an item (NSCollectionLayoutGroup is a subclass of NSCollectionLayoutItem). This means that a group can contain a group. A nested group can have a different orientation (horizontal or vertical) from its container group.

In this example, the section’s group is a horizontal group composed of two vertical groups of two items. The result is that items are clumped into blocks of four, in the order upper left, lower left, upper right, lower right (Figure 9-3):

Figure 9-3. Nested groups

let itemSize = NSCollectionLayoutSize(
    widthDimension: .fractionalWidth(1),
    heightDimension: .fractionalHeight(0.5))
let item = NSCollectionLayoutItem(layoutSize: itemSize)
let vgroupSize = NSCollectionLayoutSize(
    widthDimension: .fractionalWidth(0.48),
    heightDimension: .absolute(60))
let vgroup = NSCollectionLayoutGroup.vertical(
    layoutSize: vgroupSize, subitems: [item])
let hgroupSize = NSCollectionLayoutSize(
    widthDimension: .fractionalWidth(1),
    heightDimension: .absolute(60))
let hgroup = NSCollectionLayoutGroup.horizontal(
    layoutSize: hgroupSize, subitems: [vgroup])
hgroup.interItemSpacing = .flexible(1)
let section = NSCollectionLayoutSection(group: hgroup)

Diffable Data Source Construction

To illustrate, I’ll create a simple collection view (with a flow layout) based on the Three Big Questions; then I’ll convert it to use a diffable data source. This will be a collection view version of the table view displaying the names of the U.S. states in sections, and the conversion will be exactly parallel to what I did in “Populating a Diffable Data Source”.

First I’ll construct the Three Big Questions version of my collection view. The data model initially will be our familiar array of Section objects:

struct Section {
    var sectionName : String
    var itemData : [String]
}
var sections : [Section]()

I’ll also declare instance property constants for our registration identifiers, as usual:

let cellID = "Cell"
let headerID = "Header"

When the view loads (viewDidLoad), we parse the text file of state names into the self.sections array as usual:

let s = try! String(
    contentsOfFile: Bundle.main.path(
        forResource: "states", ofType: "txt")!)
let states = s.components(separatedBy:"
")
let d = Dictionary(grouping: states) {String($0.prefix(1))}
self.sections = Array(d).sorted {$0.key < $1.key}.map {
    Section(sectionName: $0.key, itemData: $0.value)
}

We register our cell and header types; our cell is a UICollectionViewCell subclass called Cell, designed in a nib called Cell.xib, with a lab outlet to a UILabel:

self.collectionView.register(UINib(nibName:"Cell", bundle:nil),
    forCellWithReuseIdentifier: self.cellID)
self.collectionView.register(UICollectionReusableView.self,
    forSupplementaryViewOfKind:UICollectionView.elementKindSectionHeader,
    withReuseIdentifier: self.headerID)

We also configure the flow layout (I won’t bother showing that code). Now for the data source methods. Here are the Three Big Questions:

override func numberOfSections(
    in collectionView: UICollectionView) -> Int {
        return self.sections.count
}
override func collectionView(_ collectionView: UICollectionView,
    numberOfItemsInSection section: Int) -> Int {
        return self.sections[section].itemData.count
}
override func collectionView(_ collectionView: UICollectionView,
    cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(
            withReuseIdentifier: self.cellID, for: indexPath) as! Cell
        // ...
        cell.lab.text =
            self.sections[indexPath.section].itemData[indexPath.row]
        return cell
}

And here’s how we provide the header views:

override func collectionView(_ collectionView: UICollectionView,
    viewForSupplementaryElementOfKind kind: String,
    at indexPath: IndexPath) -> UICollectionReusableView {
        let v = collectionView.dequeueReusableSupplementaryView(
            ofKind: kind, withReuseIdentifier: self.headerID, for: indexPath)
        if v.subviews.count == 0 {
            let lab = UILabel()
            v.addSubview(lab)
            // ...
        }
        let lab = v.subviews[0] as! UILabel
        lab.text = self.sections[indexPath.section].sectionName
        return v
}

That’s a working collection view; now I’ll convert it to use a diffable data source.

We start by deleting the Section struct and the sections instance property:

// this is gone!
// struct Section {
//     var sectionName : String
//     var itemData : [String]
// }
// var sections : [Section]()

Instead, we now have a diffable data source instance property. I’ll make this an implicitly unwrapped Optional, automatically initialized to nil:

var datasource : UICollectionViewDiffableDataSource<String,String>!

In viewDidLoad, we do things in a definite order — registration, instantiation, and population:

// registration 
self.collectionView.register(UINib(nibName:"Cell", bundle:nil),
    forCellWithReuseIdentifier: self.cellID)
self.collectionView.register(UICollectionReusableView.self,
    forSupplementaryViewOfKind:UICollectionView.elementKindSectionHeader,
    withReuseIdentifier: self.headerID)
// instantiation 
self.datasource = UICollectionViewDiffableDataSource<String,String>(
    collectionView:self.collectionView) { cv,ip,s in
        return self.makeCell(cv,ip,s) // *
}
self.datasource.supplementaryViewProvider = { cv,kind,ip in
    return self.makeSupplementaryView(cv,kind,ip) // *
}
// population 
// ... parse the data into `sections` ...
var snap = NSDiffableDataSourceSnapshot<String,String>()
for section in sections {
    snap.appendSections([section.0])
    snap.appendItems(section.1)
}
self.datasource.apply(snap, animatingDifferences: false)

We register our cell and supplementary view.

We instantiate the diffable data source and configure it with two functions, one for producing cells, and one for producing supplementary views. I’ve coded speculatively, postponing the actual code of those functions by moving them into instance methods.

We populate the diffable data source with data. This part is identical to how we populated the table view diffable data source with the same data.

Now I’ll write the two functions from step 2, which I called makeCell and makeSupplementaryView. These are effectively the same as what we were already doing in our data source methods!

makeCell replaces collectionView(_:cellForItemAt:), and does the same thing, except that we receive the actual data from the diffable data source:

func makeCell(_ collectionView:UICollectionView,
    _ indexPath:IndexPath, _ s:String) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(
            withReuseIdentifier: self.cellID, for: indexPath) as! Cell
        // ...
        cell.lab.text = s // *
        return cell
}

makeSupplementaryView replaces collectionView(_:viewForSupplementaryElementOfKind:at:), and does the same thing, except that we look up the data in the diffable data source:

func makeSupplementaryView(_ collectionView:UICollectionView,
    _ kind:String, _ indexPath:IndexPath) -> UICollectionReusableView {
        let v = collectionView.dequeueReusableSupplementaryView(
            ofKind: kind, withReuseIdentifier: self.headerID, for: indexPath)
        if v.subviews.count == 0 {
            let lab = UILabel()
            v.addSubview(lab)
            // ...
        }
        let lab = v.subviews[0] as! UILabel
        let snap = self.datasource.snapshot() // *
        lab.text = snap.sectionIdentifiers[indexPath.section] // *
        return v
}

Registration Objects

New in iOS 14, we can effectively skip the first step, the registration of the cell and supplementary view. Actually, we don’t so much skip it as combine it with the data source’s cell provider and supplementary view provider functions. This is just a bit of syntactic sugar, really, but it has the advantage of neatening up the rather tedious sequence of steps by which a diffable data source is configured — plus it lets us eliminate the reuse identifier constants that we’ve been maintaining.

To demonstrate, I’ll rewrite the preceding example a bit more. We start by deleting the reuse identifiers:

// this is gone!
// let cellID = "Cell"
// let headerID = "Header"

In step one, instead of calling self.collectionView.register, we create two registration objects. These are generic types with rather long names, so to save space later I’ll declare a couple of type aliases:

typealias CellReg = UICollectionView.CellRegistration
typealias SuppReg = UICollectionView.SupplementaryRegistration

The registration types are generic over the view type and the data source’s item type. If we are registering a nib, we need to pass it in the initializer as well. The initializer takes a function, which is where we configure the cell view or supplementary item view. Note that we do not need to return the view! We are passed the view as a parameter, by reference:

let cellReg = CellReg<Cell, String>(
    cellNib: UINib(nibName:"Cell", bundle:nil)) { [weak self]
        cell, ip, s in self?.configureCell(cell, ip, s) // *
}
let headReg = SuppReg<UICollectionReusableView> (
    elementKind: UICollectionView.elementKindSectionHeader) { [weak self]
        v, kind, ip in self?.configureHeader(v, kind, ip) // *
}

(As usual, I’ve coded speculatively; I’ll write configureCell and configureHeader later.) In step two, in our data source’s cell provider and supplementary view provider functions, when I dequeue, I call a method, new in iOS 14, that has Configured in its name — and I immediately return the result:

self.datasource = UICollectionViewDiffableDataSource<String,String>(
    collectionView:self.collectionView) { cv,ip,s in
        cv.dequeueConfiguredReusableCell(using: cellReg, for: ip, item: s)
}
self.datasource.supplementaryViewProvider = { cv,kind,ip in
    cv.dequeueConfiguredReusableSupplementary(using: headReg, for: ip)
}

Let’s pause for a moment to appreciate what’s just happened. Consider the cell provider function. We call dequeueConfiguredReusableCell, supplying as the first parameter the cell registration object cellReg that we declared a moment before. The runtime looks at the cell registration object and dequeues the cell for us. In this case, it discovers that the cell is to come from a nib; so if there is no existing cell among the pile of reusable cells, it loads the nib to instantiate the cell. It then passes the cell down into the body of the function we supplied to the cell registration initializer, and all we have to do is configure it.

How do we do that? The same way as before! The only difference is that our configureCell and configureHeader methods receive the actual view and configure it; they don’t need to return anything:

func configureCell(_ cell:Cell,
    _ indexPath:IndexPath, _ s:String) {
        // ...
        cell.lab.text = s
}
func configureHeader(_ v:UICollectionReusableView,
    _ kind:String, _ indexPath:IndexPath) {
        // ...
        lab.text = snap.sectionIdentifiers[indexPath.section]
}

Section Snapshots

New in iOS 14, a UICollectionView’s diffable data source’s snapshot can refer to a single section of the diffable data source. Instead of (or alongside) NSDiffableDataSourceSnapshot, you can use NSDiffableDataSourceSectionSnapshot:

Obtaining a section snapshot

To obtain a section snapshot from the diffable data source, call snapshot(for:); the parameter is the section identifier.

Applying a section snapshot

To apply a section snapshot to the diffable data source, call apply(_:to:animatingDifferences:completion:) The second parameter is the section identifier; if the section doesn’t exist, it is created.

Section snapshots allow you to construct a multisection diffable data source in a somewhat cleaner way. That’s useful especially when the model data itself comes from different sources for different sections, but we can illustrate well enough just by using our U.S. states data source once again. Previously, we were saying this:

var snap = NSDiffableDataSourceSnapshot<String,String>()
for section in sections {
    snap.appendSections([section.0])
    snap.appendItems(section.1)
}
self.datasource.apply(snap, animatingDifferences: false)

Now we can rewrite it like this:

for section in sections {
    var snap = NSDiffableDataSourceSectionSnapshot<String>()
    snap.append(section.1)
    datasource.apply(snap, to: section.0, animatingDifferences: false)
}

Also, unlike normal data source snapshots, a section snapshot permits its items to be arranged hierarchically, so that you can implement an outline interface. I’ll demonstrate that in a moment.

Selecting Cells

A collection view has a notion of cell selection, similar to a table view:

• A collection view has allowsSelection and allowsMultipleSelection properties; if these are not false, the user can tap a cell to select it.

• A collection view has an indexPathsForSelectedItems property, along with methods for selecting and deselecting an item.

• A cell has an isSelected property and a selectedBackgroundView property.

• The delegate has a full complement of should and did methods for highlighting and unhighlighting, selecting and deselecting. When the user taps to select a cell, the cell highlights, unhighlights, and selects (though the user is unaware of this, as a highlighted cell and a selected cell look the same).

• Starting in iOS 13, the delegate also has three multipleSelectionInteraction methods for when the user pans with two fingers to perform multiple selection; unlike a table view, a collection view has no notion of edit mode to complicate matters. You can permit multiple selection by gesture even if the collection view’s allowsMultipleSelection is false.

As with a table view, you can indicate selection visually with subviews that respond to highlighting and the selectedBackgroundView property. Earlier in this chapter, I configured a cell containing a label like this:

lab.highlightedTextColor = .white
cell.backgroundColor = .myPaler
let v = UIView()
v.backgroundColor = UIColor.blue.withAlphaComponent(0.8)
cell.selectedBackgroundView = v

Deleting Cells

In general, collection views don’t provide any standard interface for allowing the user to delete cells. You are free to display a UICollectionViewController’s editButtonItem, and when the user taps it, the collection view controller’s setEditing(_:animated:) is called; but the interface does not automatically change in response, and neither a collection view nor a collection view cell has an isEditing property; providing interface that lets the user express a desire to delete a cell is left completely up to you. For instance, you might have a Delete button that appears in every cell when the view controller’s isEditing is true, parallel to the Minus editing control of a table view cell.

A collection view list, on the other hand, behaves like a table view: its cells have state, and it does respond automatically when the collection view controller’s setEditing(_:animated:) is called. If you give a list cell a delete accessory (a Minus button), then by default that accessory will appear automatically when the cell is in editing mode — and when the user taps it, the trailing swipe actions will appear. A delete accessory plus a Delete trailing swipe action is a standard interface for letting the user ask to delete a cell.

How should you respond to the user asking to delete a cell? With a Three Big Questions data source, you have to alter the data, being careful about the order of operations, and then call performBatchUpdates to remove items and sections from the collection view with deleteItems(at:) and deleteSections(_:).

Deleting cells is a lot simpler if you’re using a diffable data source: you just manipulate a snapshot and apply it. Earlier, I made a collection view list where the “table” cells have a Delete trailing swipe action; the user taps Delete, and we respond by calling our own delete(at:) method. Now let’s write that method:

func delete(at ip: IndexPath) {
    var snap = self.datasource.snapshot()
    if let ident = self.datasource.itemIdentifier(for: ip) {
        snap.deleteItems([ident])
    }
    self.datasource.apply(snap)
}

Here’s another example. Imagine a full-fledged collection view where the user has selected multiple cells and has tapped a Delete button; I want to respond by deleting the selected cells, along with any sections that are now empty. Unsurprisingly, the code for doing that is almost exactly the same as what we developed earlier for doing this in a table view (“Changing a Diffable Data Source”):

guard let sel = self.collectionView.indexPathsForSelectedItems,
    sel.count > 0 else {return}
let rowids = sel.map {
    self.datasource.itemIdentifier(for: $0)
}.compactMap {$0}
var snap = self.datasource.snapshot()
snap.deleteWithSections(rowids) // implemented in an extension
self.datasource.apply(snap)

Menu Handling

Menu handling is completely parallel to a table view, using the context menu interface based on UIMenu and UIAction. Here’s some code that lets the user long press a cell to produce a Copy menu item; as usual, I have a collection view displaying U.S. state names, and the name of the long pressed cell’s state is copied to the clipboard if the user taps Copy:

override func collectionView(_ collectionView: UICollectionView,
    contextMenuConfigurationForItemAt indexPath: IndexPath,
    point: CGPoint) -> UIContextMenuConfiguration? {
        let config = UIContextMenuConfiguration(
            identifier:nil, previewProvider: nil) { _ in
                let action = UIAction(title: "Copy") { _ in
                    let d = self.datasource
                    if let state = d.itemIdentifier(for: indexPath) {
                        UIPasteboard.general.string = state
                        print("copied", state)
                    }
                }
                let menu = UIMenu(title: "", children: [action])
                return menu
            }
        return config
}

Rearranging Cells

You can permit the user to rearrange cells by dragging them. If you’re using a collection view controller, it supplies a gesture recognizer ready to respond to the user’s long press gesture followed by a drag. (This is incompatible with a menu, because the menu long press gesture recognizer recognizes first.)

To permit the drag to proceed, you implement two data source methods:

collectionView(_:canMoveItemAt:)

Return true to allow this item to be moved.

collectionView(_:moveItemAt:to:)

The item has been moved to a new index path. Update the data model, and reload cells as needed.

You can also limit where the user can drag with this delegate method:

collectionView(_:targetIndexPathForMoveFromItemAt:toProposedIndexPath:)

Return either the proposed index path or some other index path. To prevent the drag entirely, return the original index path (the second parameter).

If you’re using a diffable data source, dealing with user rearrangement of cells was extremely tricky in iOS 13. You had to implement the data source methods, and the implementation was difficult to get right. New in iOS 14, it’s trivial: do nothing! Do not implement the data source methods. The data source responds automatically; the user rearranges cells, and the data source is rearranged to match.

New in iOS 14, if you need an event related to the user rearranging cells, use the data source’s reorderingHandlers property; this is a ReorderingHandlers struct consisting of properties that are functions you can set:

• canReorderItem

• willReorder

• didReorder

You must supply a canReorderItem function, even if it always just returns true; otherwise, user reordering of cells will not be possible.

By the time you receive didReorder, the data inside the diffable data source has already been reordered. The purpose of this method is just in case you are also storing your model data somewhere else and you need to update it. The parameter is an NSDiffableDataSourceTransaction (new in iOS 14) that you can use to work out what happened.

Even if you’re using a diffable data source, you can still use the delegate method. In this example, the delegate method prevents the move if the drag crosses a section boundary:

override func collectionView(_ collectionView: UICollectionView,
    targetIndexPathForMoveFromItemAt orig: IndexPath,
    toProposedIndexPath prop: IndexPath) -> IndexPath {
        if orig.section != prop.section {
            return orig
        }
        return prop
}

If you prefer to provide your own gesture recognizer, then if you’re using a collection view controller, set its installsStandardGestureForInteractiveMovement to false. Your gesture recognizer action method will need to call these collection view methods to keep the collection view apprised of what’s happening (and the data source and delegate methods will then be called appropriately):

• beginInteractiveMovementForItem(at:)

• updateInteractiveMovementTargetPosition(_:)

• endInteractiveMovement

• cancelInteractiveMovement

Tweaking a Layout

Both UICollectionViewFlowLayout and UICollectionViewCompositionalLayout constitute powerful starting points, so it may be that all you need is to tweak what they already do. To illustrate, I’ll use an example from a WWDC 2012 video.

Suppose we have a horizontally scrolling collection view as wide as the screen and 128 points tall. Centered vertically in this collection view is a horizontal series of single square cells 75 points on a side, spaced fairly well apart. About three cells fit on the screen; the user can scroll horizontally to see more cells.

Our goal is to modify the behavior of the collection view such that as the user scrolls horizontally, the currently central cell is emphasized. As a cell approaches the horizontal center of the screen, it grows, and as it moves away from the horizontal center, it returns to its normal size. This sort of interface is commonly referred to as a carousel (Figure 9-4).

Figure 9-4. A carousel layout

lay.itemSize = CGSize(width: 75, height: 75)
lay.minimumLineSpacing = 65

override func layoutAttributesForElements(in rect: CGRect)
    -> [UICollectionViewLayoutAttributes]? {
        guard let cv = self.collectionView else { return nil }
        let r = CGRect(origin:cv.contentOffset, size:cv.bounds.size)
        let arr = super.layoutAttributesForElements(in: rect)!
        return arr.map { atts in
            let atts = atts.copy() as! UICollectionViewLayoutAttributes
            if atts.representedElementCategory == .cell {
                if atts.frame.intersects(r) {
                    let d = abs(r.midX - atts.center.x)
                    let act = CGFloat(70)
                    let nd = d/act
                    if d < act {
                        let scale = 1 + 0.5*(1-(abs(nd)))
                        let t = CATransform3DMakeScale(scale,scale,1)
                        atts.transform3D = t
                    }
                }
            }
            return atts
        }
}

override func shouldInvalidateLayout(
    forBoundsChange newBounds: CGRect) -> Bool {
        return true
}

let itemSize = NSCollectionLayoutSize(
    widthDimension: .fractionalWidth(1),
    heightDimension: .absolute(75))
let item = NSCollectionLayoutItem(layoutSize: itemSize)
item.edgeSpacing = NSCollectionLayoutEdgeSpacing(
    leading: nil, top: .flexible(0),
    trailing: nil, bottom: .flexible(0))
let groupSize = NSCollectionLayoutSize(
    widthDimension: .absolute(75),
    heightDimension: .fractionalHeight(1))
let group = NSCollectionLayoutGroup.vertical(
    layoutSize: groupSize, subitems: [item])
let section = NSCollectionLayoutSection(group: group)
section.interGroupSpacing = 65
section.contentInsets = NSDirectionalEdgeInsets(
    top: 0, leading: 75, bottom: 0, trailing: 75)
section.visibleItemsInvalidationHandler = { items, offset, env in
    let r = CGRect(origin:offset, size:env.container.contentSize)
    let cells = items.filter {$0.representedElementCategory == .cell}
    for item in cells {
        let d = abs(r.midX - item.center.x)
        let act = CGFloat(70)
        let nd = d/act
        if d < act {
            let scale = 1 + 0.5*(1-(abs(nd)))
            let t = CATransform3DMakeScale(scale,scale,1)
            item.transform3D = t
        }
    }
}
let config = UICollectionViewCompositionalLayoutConfiguration()
config.scrollDirection = .horizontal
let layout = UICollectionViewCompositionalLayout(
    section: section, configuration:config)

Collection View Layout Subclass

For total freedom, you can subclass UICollectionViewLayout itself. The WWDC 2012 videos demonstrate a UICollectionViewLayout subclass that arranges its cells in a circle; the WWDC 2013 videos demonstrate a UICollectionViewLayout subclass that piles its cells into a single stack in the center of the collection view, like a deck of cards seen from above. For my example, I’ll write a simple collection view layout that ignores sections and presents all cells as a plain grid of squares. This is unnecessary now that compositional layouts exist, but it demonstrates nicely the basics of writing a layout from scratch.

In my UICollectionViewLayout subclass, called MyLayout, the big questions I will need to answer are collectionViewContentSize and layoutAttributesForElements(in:). To answer them, I’ll calculate the entire layout of my grid beforehand. The prepare method is the perfect place to do this; it is called every time something about the collection view or its data changes. I’ll calculate the grid of cells and express their positions as an array of UICollectionViewLayoutAttributes objects; I’ll store that information in a property self.atts, which is a dictionary keyed by index path so that I can retrieve a given layout attributes object by its index path quickly. I’ll also store the size of the grid in a property self.sz:

override func prepare() {
    let sections = self.collectionView.numberOfSections
    // work out cell size based on bounds size
    let sz = self.collectionView!.bounds.size
    let width = sz.width
    let shortside = (width/100).rounded(.down)
    let side = width/shortside
    // generate attributes for all cells
    var (x,y) = (0,0)
    var atts = [UICollectionViewLayoutAttributes]()
    for i in 0 ..< sections {
        let jj = self.collectionView!.numberOfItems(inSection:i)
        for j in 0 ..< jj {
            let att = UICollectionViewLayoutAttributes(
                forCellWith: IndexPath(item:j, section:i))
            att.frame = CGRect(CGFloat(x)*side,CGFloat(y)*side,side,side)
            atts += [att]
            x += 1
            if CGFloat(x) >= shortside {
                x = 0; y += 1
            }
        }
    }
    for att in atts {
        self.atts[att.indexPath] = att
    }
    let fluff = (x == 0) ? 0 : 1
    self.sz = CGSize(width, CGFloat(y+fluff) * side)
}

It is now trivial to implement collectionViewContentSize, layoutAttributesForElements(in:), and layoutAttributesForItem(at:). I’ll just fetch the requested information from the sz or atts property:

override var collectionViewContentSize : CGSize {
    return self.sz
}
override func layoutAttributesForElements(in rect: CGRect)
    -> [UICollectionViewLayoutAttributes]? {
        return Array(self.atts.values)
}
override func layoutAttributesForItem(at indexPath: IndexPath)
    -> UICollectionViewLayoutAttributes? {
        return self.atts[indexPath]
}

Finally, I want to implement shouldInvalidateLayout(forBoundsChange:) to return true, so that if the interface is rotated, my prepare method will be called again to recalculate the grid. There’s a potential source of inefficiency here, though: the user scrolling the collection view counts as a bounds change as well. Therefore, I return false unless the bounds size has changed:

var oldBoundsSize = CGSize.zero
override func shouldInvalidateLayout(forBoundsChange newBounds: CGRect)
    -> Bool {
        let ok = newBounds.size != self.oldBoundsSize
        if ok {
            self.oldBoundsSize = newBounds.size
        }
        return ok
}

Decoration Views

A decoration view is a third type of collection view subview, on a par with cells and supplementary views. The difference is that it is implemented entirely by the collection view layout. You register a decoration view class (or nib) with the layout — not with the collection view. A collection view will faithfully draw a decoration view imposed by the collection view layout, but none of the methods and properties of a collection view, its data source, or its delegate involve decoration views. There is no support for letting the user select a decoration view or reposition a decoration view. There aren’t even any collection view methods for finding out what decoration views exist or where they are located.

A flow layout comes with no built-in support for adding a decoration view, but a compositional layout does. It is of class NSCollectionLayoutDecorationItem (an NSCollectionLayoutItem subclass), and represents just one kind of decoration, a background behind a section. So there’s a single class function, background, which takes an elementKind, and you set the section’s decorationItems. There must be a corresponding UICollectionReusableView (or a nib containing such a view) registered with the layout.

As a simple example, I’ll put a pale blue background behind each section of a compositional layout. Here’s my view class:

class Deco : UICollectionReusableView {
    override init(frame: CGRect) {
        super.init(frame: frame)
        self.backgroundColor = UIColor.blue.withAlphaComponent(0.1)
    }
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}

Here’s how I register that class with the layout when I configure the collection view:

let layout = self.createLayout()
layout.register(Deco.self, forDecorationViewOfKind: "background")
self.collectionView.collectionViewLayout = layout

And here’s how the decoration view is added to the section (in createLayout):

let deco = NSCollectionLayoutDecorationItem.background(
    elementKind: "background")
deco.contentInsets = NSDirectionalEdgeInsets(
    top: 5, leading: 5, bottom: 5, trailing: 5)
section.decorationItems = [deco]

You can also implement a decoration view in a layout subclass that you write, and you are free to define any desired mechanism for allowing a user of this collection view layout to customize your decoration views. You implement layoutAttributesForDecorationView(ofKind:at:) to return a UICollectionViewLayoutAttributes object that positions the UICollectionReusableView. To construct this object, you call init(forDecorationViewOfKind:with:) and configure its properties. Finally, you implement layoutAttributesForElements(in:) such that the result of layoutAttributesForDecorationView(ofKind:at:) is included in the returned array.