NSOutlineView Part 2: Making the outlineView useful

a) Proof of concept:
The simplest form of the ‘add/insert’ function is

@IBAction func addItem(_ sender: AnyObject) {
if let selectedItem = sourceList.item(atRow: sourceList.selectedRow) as? SourceListItem
selectedItem.children.append(Animal(name: "New Animal"))
sourceList.reloadItem(selectedItem, reloadChildren: true)
}
}

This is not production code: it only inserts instances of ‘Animal’, regardless of the position, and it manipulates the object’s children array directly.

Since this is a very long and complex post already, I will skip any further temporary steps – where I grab an object and directly insert or remove an item from its child array – and only document the final, refactored version of my code, which does not access properties directly, but uses public accessor methods (as usual, for the sake of clarity, I am not setting access levels in my sample code.)

There is no single algorithm that will work for every use case of NSOutlineView. Things to keep in mind are

– are there items/levels that will always be ‘leaf’ objects and never accept an insertion attempt?
Each item needs to know whether it should insert objects. Ideally, this gets checked in selectionHasChanged so that users are not given the option to insert new objects

– will users be able to create new top level items?
insertion needs to be handled for -1; in which case a new top level object will be inserted to dataSource.allKingdoms

– do you want a ‘group’/folder class of items?
If you allow multiple selection, one of the more common use cases is to insert the folder as child of the selected items’ parent, and the items themselves as children of the folder.

– does the outline view contain more than one class of item? In this case, ‘add/insert’ need to create the appropriate objects
Each class know what items it will accept for its ‘children’ array.

b) Deletions provide a different challenge of equal magnitude. Here the main question is

– does deleting an object delete all of its children?
If that isn’t the case, the new position of the children needs to be determined. (If you close a department, do you fire all its staff and managers, or do you find other positions for them? Both are possible.)

We’ll handle this case eventually in a third part of this tutorial. For now, we’ll delete an item and all of its children.

The model setup will get long and very, complex. My goal was to create a template solution that I can can adapt to other projects with minimal changes. This means that I occasionally have duplicate code (eg handling all cases in a switch statement rather than only the one I am interested in). I am also adapting a belts-and-braces approach in places: I disable the ‘remove’ button when no item is selected, but I am still handling ‘remove item’ for row -1.

4) helper enums

a) childClass: This is an enum that is extremely project-specific: you need to provide a case and an instantiated object for each type of item you want to appear in your source list.

enum ChildClass {
case kingdom
case animalClass
case animal

var newInstance: SourceListItem{
switch self {
case .kingdom:
return Kingdom(name: "New Kingdom")
case .animalClass:
return AnimalClass(name: "New AnimalClass")
case .animal:
return Animal(name: "New Animal")
}
}
}

b) ChildType: This determines what the ‘add’ behaviour of each class – and potentially, each instance – will be. Here, I am setting these once for each class; but a childType variable will allow you to assign different childClasses to objects of the same class (the AnimalClass ‘Fish’ should provide only ‘Fish’ rather than ‘Animal’ instances) as well as calculating nesting levels and stopping users from creating hierarchies that run too deep for the purposes of your application.

enum ChildType {
case none
case sibling(class: ChildClass)
case child(class: ChildClass)
}

5) amend the SourceListItem protocol:

protocol SourceListItem: class {
var name: String {get set }
var icon: NSImage? {get set}

func addSourceListItem(parent: SourceListItem?) -> SourceListItem?
func appendChild(item: SourceListItem)
func insertChild(item: SourceListItem, afterItem: SourceListItem)
func removeSourceListItem(item: SourceListItem)
}

6) Fulfill those promises and make all three classes – Kingdom, AnimalClass and Animal – conform to the protocol again

a) Add the childType variable. This is application architecture: you determine the behaviour of your class, whether will add anything, and whether it will add children or siblings. (This is the reason we pass the parent into the add function)

Kingdom: var childType: ChildType = .child(class: .animalClass)
AnimalClass: var childType: ChildType = .child(class: .animal)
Animal: var childType: ChildType = .sibling(class: .animal)

Our CompositeDataSource does not have to conform to the SourceListItem protocol – this would make no sense – but it still benefits from having its child class set:

var childClass: ChildClass = .kingdom

b) For the datasource, the add and remove functions are straightforward:
Add:
func addTopLevelItem() -> SourceListItem{
let newTopLevelItem = childClass.newInstance
allChildren.append(newTopLevelItem)
return newTopLevelItem
}

Returning a reference to the newly-added item makes it easier to select it later.

For my convenience, I am handling the question of whether the dataSource should add children or not in the main ViewController class with

var shouldAddTopLevel: Bool = true

A different (better?) implementation would move this responsibility to the datasource, which instead of varChildClass would have a varChildType, which could be set to .none or .child(class: SourceListItem), with an add function that acts accordingly.

Remove:
func removeTopLevelItem(item: SourceListItem){
allChildren = allChildren.filter() {$0 !== item}
}

When a kingdom gets deleted, everything in that kingdom gets deleted.

c) add the helper functions to all three classes

func insertChild(item: SourceListItem, afterItem: SourceListItem){
if let index = children.index(where: {$0 === afterItem }) {
children.insert(item, at: index + 1)
} else {
appendChild(item: item)
}
}

Array does have an index(of:) property. For this to work, your items need to be equatable (eg, inherit from NSObject). Since that isn’t the case here, we’re checking for identity. (For more about indices and arrays, see this post.)
There’s a slight defensiveness about this code – for this to have gotten this far, the index for our item in its parent should definitely exist, but I’d rather handle the failure gracefully even if I don’t expect it to ever happen than not at all.

func appendChild(item: SourceListItem){
children.append(item)
}

d) Add the add function to all three classes.

func addSourceListItem(parent: SourceListItem?) -> SourceListItem?{

switch childType {
case .none:
print("No children allowed - handle more gracefully")
return nil
case .child(let className):
let newItem = className.newInstance
appendChild(item: newItem)
return newItem
case .sibling(let siblingClass):
if let parent = parent{
let newItem = siblingClass.newInstance
parent.insertChild(item: newItem, afterItem: self)
return newItem
} else {
return nil
}
}
}

This function is identical in all three classes, even though in this example I am never changing the childType, and thus don’t need to handle the other two cases.

e) add the remove function to all three classes.

func removeSourceListItem(item: SourceListItem){
children = children.filter(){ $0 !== item }
}

This function removes the item in question and all of its children. For the current data structure, this makes sense because I should not be able to delete the plant kingdom and relocate all its contents to ‘Fungi’. For other uses – we remove the department but all of its members are still employed by us – there will need to be additional, custom implementations.

My suggestion would be to create a ‘FolderItem’ protocol inheriting from SourceListItem which then handles all of the logic involved with this, but that is a topic for another post.

7)

a) set up an ‘add’ button and a ‘remove’ button in IB, create outlets for both of them and link them to an addItem and removeItem IBAction respectively.

b) create a function to handle the button states.

func setButtonState(){
if sourceList.selectedRow == -1{
if shouldAddTopLevel == true {
removeBtn.isEnabled = false
addBtn.isEnabled = true
} else {
removeBtn.isEnabled = false
addBtn.isEnabled = false
}
} else if let selectedItem = sourceList.item(atRow: sourceList.selectedRow) as? SourceListItem{
switch selectedItem.childType {
case .none:
removeBtn.isEnabled = true
addBtn.isEnabled = false
default:
removeBtn.isEnabled = true
addBtn.isEnabled = true

} else {
removeBtn.isEnabled = true
addBtn.isEnabled = true
}
}

The logic here is a little ugly, but we need to handle three main cases:

– no items are selected (whether or not we insert a new top level item depends on app settings)
– the selected item does not allow insertion of either children or siblings
– everything else

(To test this, you should temporarily change the ‘childType’ property of either a class or an individual item in your app to .none; right now all of them allow either children or siblings).

Add setButtonState() to the end of viewDidLoad so we start with the correct configuration.

c) Since we’re not doing anything with multiple selection in this iteration of our app, the next function is very straightforward:

func outlineViewSelectionDidChange(_ notification: Notification) {
setButtonState()
}

Every time the selection changes, we enable or disable the appropriate buttons.

8) Implement Add and Remove in the ViewController

a) Adding items:

@IBAction func addItem(_ sender: AnyObject) {
if sourceList.selectedRow == -1, shouldAddTopLevel == true {

return

We’ve configured the button so that it won’t _be_ enabled unless these conditions are true, but someone might still call this in code. Better safe than sorry.

The dance with the indexSet containing a single index is necessary since OutlineView does not have a ‘selectRowIndex’ or ‘selectItem’ method.

} else{

let newItemIndex = IndexSet(integer: sourceList.row(forItem: newItem))
sourceList.selectRowIndexes(newItemIndex, byExtendingSelection: false)
sourceList.scrollRowToVisible(sourceList.row(forItem: newItem))
}
}
}

parent needs to remain optional because kingdoms have new items, too. reloadItem(parent, reloadChildren: true) is safe to call since the first parameter is of type Any?

Like the insertion of a new kingdom above, this selects the new item (so you can rename it more easily) and scrolls to it.

b) removing items:

@IBAction func removeItem(_ sender: AnyObject) {
guard sourceList.selectedRow != -1 else {
print("Remove button should be disabled, so this should never be called.")
return
}
if let selectedItem = sourceList.item(atRow: sourceList.selectedRow) as? SourceListItem{
if selectedItem.itemType == .header {
dataSource.removeTopLevelItem(item: selectedItem)
sourceList.reloadData()
setButtonState()
} else {

if let parent = sourceList.parent(forItem: sourceList.item(atRow: sourceList.selectedRow)) as? SourceListItem {
parent.removeSourceListItem(item: selectedItem)
sourceList.reloadItem(parent)
setButtonState()
let newItemIndex = IndexSet(integer: sourceList.row(forItem: parent))
sourceList.selectRowIndexes(newItemIndex, byExtendingSelection: false)
}
}
}
}