What does Cocoa binding's NSHandlesContentAsCompoundValueBindingOption do exactly?

Question

When binding an NSArrayController's contentArray to an NSUserDefaultsController, you have to check the "Handles Content As Compound Value" checkbox on the binding. This has become conventional wisdom, but what does the option actually do?

I wrote a small test app and could observe that with the option turned on, the whole contentArray is passed to the binding source's setValue:forKey: whenever you edit a property of an element in the array. When the option is off, only the element object itself is modified and the binding source is not notified.

This explains why the option is needed to make NSUserDefaultsController work (otherwise it wouldn't notice that you had edited something in the array and never save the change). But it doesn't explain who is doing what differently exactly. Is the array controller taking charge of this option and writing back the content array when it observes a change? If so, how does it relate to the stated purpose of the option which is to "use a reversible value transformer to translate [...] compound values temporarily into smaller pieces"?

Answer 1

The message flow is explained here pretty well: http://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CocoaBindings/Concepts/MessageFlow.html#//apple_ref/doc/uid/TP40002149-186285

Here's my attempt to answer:

1. The original content object specified by the contentObject, contentArray or contentSet binding is retrieved from the NSUserDefaultsController using valueForKeyPath:
2. That content object is transformed using the value transformer's transformedValue: method
3. The new value from the user is inserted into the transformed content object
4. The content object is inverse transformed using inverseTransformedValue:
5. The new, inverse transformed content object is set as the new content object and passed to the NSUserDefaultsController using setValue:forKeyPath: