Cocoa Key Value Bindings: What are the explanations of the various options for Controller Key?

Question

When I bind a control to an NSArrayController using Interface Builder, there are a variety of options under the "Controller Key" field in the bindings inspector.

I understand what "arrangedObjects" is, and I semi-understand what "selection" is, but I'd love to see a really nice explanation of all the options and when to use each one. The list includes: selectionIndexes, selectionIndex, selectedObject, sortDescriptors, etc. I haven't been able to find a good explanation of these options.

I'm having trouble with a button that's bound to target > selection, so I'm hoping a much deeper understanding of these Controller Keys might help me debug my issue.

Thanks!!!

Answer 1

You want the Cocoa Bindings Reference.

Answer 2

The controller key is the key for the (property of the controller object) you're binding to. The model key path is the key path by which the bound object can ask the model objects for more basic objects, such as strings or images, or for other model objects (i.e., drill down into the model).

An example: Let's say you have a Person objects in an array controller, and each Person has a name. You bind a table column to the array controller, controller key arrangedObjects (thereby getting the model objects), model key path name (thereby getting the value objects).

A more complex example: Suppose you have an array controller of Departments. Each Department contains Persons (employees in the department). You can bind your People array controller to the Departments controller, controller key arrangedObjects (getting the Department model objects), model key path @distinctUnionOfObjects.employees (getting the Person model objects), and then bind a table column to the People controller, controller key arrangedObjects, model key path name.

That table would be for people who work for your company; if you have a separate table of prospective employees, you can create Person objects for them, too, and they won't show up in the table of existing employees because they're not in a Department. When you hire them, you'll add them to one or more Departments; then, they'll show up in the People array controller automatically, because that array controller is observing the employees of all of the Departments.

Answer 3

These are tricky to find. They seem to be referenced everywhere by various Cocoa books, and even Apple's docs, but I haven't seen anyone unify an explanation of them into a single location. The answer is, Apple defines them inside the docs for each controller class:

• NSObjectController (doc)
• NSArrayController (doc)
• NSDictionaryController (doc)
• NSTreeController (doc)
• NSUserDefaultsController (doc)

These docs are also useful:

• Cocoa Bindings
• Cocoa Bindings Reference

Inheritance for these "Controller" objects looks like so (this is important to discover where some of the "Controller Key" options come from):

NSController -> NSObjectController
NSController -> NSObjectController -> NSArrayController
NSController -> NSObjectController -> NSArrayController -> NSDictionaryController
NSController -> NSObjectController -> NSTreeController
NSController -> NSUserDefaultsController

// Note:  NSController is an abstract class (don't worry about it).  It inherits from NSObject.

If you find a Controller Key not defined in the docs for a particular class, it's probably defined in its superclass. Below are all the Controller Keys available for each of the above (Xcode 3.2.1, Interface Builder 3.2.1):

// **NSObjectController**
canAdd
canRemove
isEditable
selectedObjects
selection


// **NSArrayController**
arrangedObjects
canAdd
canInsert
canRemove
canSelectNext
canSelectPrevious
filterPredicate
isEditable
selectedObjects
selection
selectionIndex
selectionIndexes
sortDescriptors


// **NSDictionaryController**
arrangedObjects
canAdd
canInsert
canRemove
canSelectNext
canSelectPrevious
filterPredicate
isEditable
selectedObjects
selection
selectionIndex
selectionIndexes
sortDescriptors


// **NSTreeController**
arrangedObjects
canAdd
canAddChild
canInsert
canInsertChild
canRemove
isEditable
selectedObjects
selectedNodes
selection
selectionIndexPath
selectionIndexPaths
sortDescriptors


// **NSUserDefaultsController**
hasUnappliedChanges
values

So, find the one on the list you want, look in the docs for that controller class, and you'll find its definition. If it's not there, it's probably defined in the docs for its superclass (likely NSObjectController).

Answer 4

Have a look at the Interface Builder User Guide, there is a section "Connection and Bindings" with a table 7-1 in which it reads:

Controller Key: An attribute of an NSController object. When binding to an NSController object, you use this field to select the first entry in the key path. The menu associated with this field displays the properties available on the selected controller object as a convenience. You can type the name of the property or simply select it from the provided list.