NSOutlineView Part1: Setting up an outlineView.

a) Create an outlet for it in the main ViewController

@IBOutlet weak var sourceList: NSOutlineView!

b) while you’re at it, declare that the ViewController will conform to NSOutlineViewDelegate and set it as the outlineView’s delegate in IB.

c) The cells already have identifiers: HeaderCell for the allCaps header cell, DataCell for the icon-and-label child cell. We’ll be using three types here here (Apple’s Interface Guidelines say ‘Avoid displaying more than two levels of hierarchy in a source list.’) In this example we’ll be using headers (Animal Kingdoms) and two levels of content (AnimalClass and Animal), so the first thing to do is to drag another NSTableCellView – this time, with a label only – into the outline view. I’ve set the labels on mine to use Optima as a font.

Set the identifiers to HeaderCell, IconCell and PlainCell respectively.

2) Set up the DataSource. Objects conforming to the NSOutlineViewDataSource protocol need to inherit from NSObject (if you don’t, you will get A LOT of errors telling you you need to conform to Equatable, Hashable, and thirteen further errors – they all go away if you make NSObject your DataSource’s superclass).

a) class CategoryDataSource: NSObject, NSOutlineViewDataSource {

var allKingdoms : [Kingdom] = [] }

This is going to be the content array. For this example, we will manually construct the contents in the NSOutlineViewDelegate (the main ViewController).

b) While you’re at it, go to IB, drag an object into the ViewController’s scene and set its class to CategoryDataSource; connect the OutlineView’s ‘dataSource’ outlet to that object. Also create an outlet for the dataSource in the main ViewController:

@IBOutlet var dataSource: CategoryDataSource!

At this point, you’ve got the outlineView hooked up to delegate and dataSource, and while neither of these classes actually conform to the protocol yet, you’re on your way.

2) Proof of concept: Single level.

There are three methods that need to be implemented in the NSOutlineViewDataSource. A fourth method is mentioned in older tutorials, but this seems to be mainly used by cell-based OutlineViews, and since they’ve been nearly-deprecated since 10.7, I’ve decided to leave it out for now. It does not seem to _do anything_ – the outlineView works perfectly fine without, though Apple’s documentation says you must implement this method if you are not providing the data for the outline view using Cocoa bindings.Unless I learn otherwise, I will leave this out. (I also struggle to understand what I am supposed to return here. I have seen examples that simply log which object is current, which seems to suggest the method was optional all along.)

func outlineView(_ outlineView: NSOutlineView, objectValueFor tableColumn: NSTableColumn?, byItem item: Any?) -> Any? {
//code goes here
}

So we ignore that one.

a) Create a Kingdom class

class Kingdom {

init(name: String){
self.name = name
}
}

b) In the datasource, set allKingdoms to

var allKingdoms : [Kingdom] = (Kingdom(name: "Plants"), Kingdom(name: "Animals"), Kingdom(name: "Fungi")]

and implement a terrible implementation for the following three methods:

func outlineView(_ outlineView: NSOutlineView, isItemExpandable item: Any) -> Bool {
return no
}

The top level – here, kingdoms – it not a child of any item, but we still need to say how many top level items there are, and return an item for the index value.

func outlineView(_ outlineView: NSOutlineView, numberOfChildrenOfItem item: Any?) -> Int {
return allKingdoms.count
}

func outlineView(_ outlineView: NSOutlineView, child index: Int, ofItem item: Any?) -> Any {
return allKingdoms[index] }

c) In the delegate (main ViewController), provide terrible implementations for the two necessary methods:

func outlineView(_ outlineView: NSOutlineView, isGroupItem item: Any) -> Bool {
return true
}

func outlineView(_ outlineView: NSOutlineView, viewFor tableColumn: NSTableColumn?, item: Any) -> NSView? {
sourceListCell = outlineView.make(withIdentifier: "HeaderCell", owner: self) as! NSTableCellView
sourceListCell.textField?.stringValue = item.name
return sourceListCell
}

They’re all group items (they’re all at the top level), and they’re all displayed in HeaderCells.

d) Build and run.

This is a good start. For the next part, we complicate everything. A lot.

3) Set up Data Structure

a) Create a class Animal, and a class AnimalClass.

b) Create a SourceListItem protocol. We want to be able to display many different items in our SourceList, including – as in the example before – custom ‘groups’ (folder icon), which allow us to split large sibling groups into more managable categories. So instead of creating endless switch statements (is this a Kingdom, an AnimalClass, an Animal, a Group folder, or something completely unrelated like a tag or a note or whatever else you might wish to display), we create a SourceListItem protocol that all classes you wish to display must conform to, and an easily expandable SourceListItemType enum to track the kinds of items we want to display.

protocol SourceListItem {

}

This should be fairly self-explanatory.

c) Create the SourceListType enum. The types are linked to how I want to display the item, rather than its content.

enum SourceListItemType {
case header
case plain
case icon
}

d) make the three model classes conform to SourceListItem.

class Kingdom: SourceListItem {

init(name: String){
self.name = name
}
var itemType: SourceListItemType = .header
}

Configure AnimalClass and Animal in the same manner, only that, for the purpose of this example, AnimalClass is a .plain and Animal an .icon itemType. (Alternatively, you could check whether icon is nil). You could also override the setter for children if you don’t want an element to ever have children of its own and disregard any attempt to set them.

d) change the dataSource methods:

var allKingdoms : [SourceListItem] = []

func outlineView(_ outlineView: NSOutlineView, isItemExpandable item: Any) -> Bool {
if let item = item as? SourceListItem{
return item.isExpandable
} else {
return false
}
}

func outlineView(_ outlineView: NSOutlineView, child index: Int, ofItem item: Any?) -> Any {
if let item = item as? SourceListItem{
return item.children[index] } else {
return allKingdoms[index] }
}

AllKingdoms can only ever contain elements that conform to our SourceListItem protocol, and we can easily find out whether items are expandable and how many children they have.

e) change the delegate methods:

func outlineView(_ outlineView: NSOutlineView, isGroupItem item: Any) -> Bool {
if let item = item as? SourceListItem {
if item.itemType == .header{
return true
} else {
return false
}
}
return false
}

.header type items are group items (which get displayed with the HeaderCell).

func outlineView(_ outlineView: NSOutlineView, viewFor tableColumn: NSTableColumn?, item: Any) -> NSView? {

}
return nil
}

This isn’t best practice – I am setting the values of a view at creation here, when it would be better to set each NSTableCellView’s represented object and either bind to that in IB or subclass them and have the cell itself display its represented object, but for now, it will do.

f) add two (or more, if you want) images to your asset catalogue: here I’ve used ‘blackbird’ and ‘bee’.

g) create the data in viewDidLoad:

override func viewDidLoad() {
super.viewDidLoad()

}