KVO/Bindings docs don't mention that it will set view properties

Number:rdar://6588723 Date Originated:2009-02-15T0109-0800
Status:Open Resolved:
Product:Documentation Product Version:2007-05-22
Classification:Enhancement Reproducible:Not Applicable
The programming guides for KVO[1] and Cocoa Bindings[2] do not mention that Bindings will set the bound property of a view using its accessors. Instead, they claim that the programmer must implement KVO's observe method and change the bound property himself.

Bindings' behavior of setting the property for me is a very handy feature, which I make use of in CPU Usage[3]. I was surprised to find that the documentation doesn't directly mention it—I had thought it was supported behavior. I would not be surprised if other developers are also relying on this behavior.

I submit that it is the obvious behavior, and that those who don't want it should indeed override the observe method, and that you should codify it by explicitly stating it in the documentation.

The closest reference I can find is in the Cocoa Bindings Programming Topics (http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaBindings/Concepts/HowDoBindingsWork.html#//apple_ref/doc/uid/20002373-204283):

### Model-Initiated Updates

Recall again that the joystick was bound to the controller with the following method:

	[joystick bind:@"angle" toObject:GraphicController withKeyPath:@"selection.shadowAngle" options:options];

From the perspective of model-initiated updates the method can be interpreted as follows:

- `toObject: GraphicController`
  If the GraphicController’s
- `withKeyPath:@"selection.shadowAngle"`
  selection.shadowAngle changes
- `bind:@"angle"`
  update whatever is associated with the exposed angle key
- `options:options`
  using the options specified (for example, using a value transformer).

Notice the third list item: “update whatever is associated with the exposed angle key”. I can interpret this to mean that the property-assignment behavior I'm seeing is supported, but that doesn't quite match up with earlier statements that I must implement the observe method, nor with the code example that follows this list in the same section.

[1]: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueObserving/
[2]: http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaBindings/
[3]: http://boredzo.org/cpuusage/hg/ — see PRHGradientView, which exposes its gradient property as a binding but does not override the observe method. I suggest that you add an NSLog statement to setGradient:, then run the app; you will see that the binding does, indeed, send one of my views the setGradient: message when you change the gradient colors in the Preferences window.

07-Mar-2009 11:31 AM Peter Hosey:
I finally found a statement in the docs that seems to confirm that you can simply implement a KVC-/KVO-compliant property and have the Right Thing happen:

> NSView subclasses can expose additional key-value-coding/key-value-observing compliant properties as bindings by calling the class method exposeBinding: for each of the properties. 
— http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/Protocols/NSKeyValueBindingCreation_Protocol/Reference/Reference.html

I'm not sure why the feature is only for NSView subclasses, if indeed it is. I haven't tried it with classes that aren't NSViews.

My request stands: A clear and explicit statement of the any-KVC/KVO-compliant-property-can-be-a-binding-with-only-an-exposeBinding:-message feature should exist in the Bindings programming guide as well.


Please note: Reports posted here will not necessarily be seen by Apple. All problems should be submitted at bugreport.apple.com before they are posted here. Please only post information for Radars that you have filed yourself, and please do not include Apple confidential information in your posts. Thank you!