Cocoa Design Patterns: Bindings and Controllers

This chapter is from the book

Cocoa Design Patterns

Learn More Buy

This chapter is from the book

This chapter is from the book 

Cocoa Design Patterns

Learn More Buy

Collaboration of Patterns Within Bindings and Controllers

Once the behavior of binding has been explained, programmers commonly want to know how bindings work. Although bindings are an advanced topic, there's really no magic. Interface Builder sends -(void)bind:(NSString *)binding toObject:(id)observableController withKeyPath:(NSString *)keyPath options:(NSDictionary *)options messages when it establishes bindings, and you can send the same messages to establish bindings programmatically.

Key Value Coding and Key Value Observing technologies underlie bindings. Key Value Coding is briefly described in Chapter 19 and again in Chapter 30, "Core Data Models." It is a variation of the Associative Storage pattern, which lets you access the properties of objects as if every object were a simple dictionary of key/value pairs. See Apple's conceptual documentation for Key Value Coding at http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/KeyValueCoding.html. Key Value Observing is a variation of the Notification pattern from Chapter 14, "Notifications." Key Value Observing monitors the values of object properties on behalf of other objects that are interested observers. The underlying implementation of Key Value Observing is somewhat different from the Notification pattern, but in essence, Key Value Observing serves the same function: Register to receive messages when something of interest happens. Apple's conceptual documentation for Key Value Observing is at http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html.

Key Value Observing is implemented by the NSKeyValueObserving informal protocol, which adds methods to NSObject from which almost all Cocoa objects inherit. Hidden deep behind the scenes, Cocoa maintains a collection of some kind that lists all of the objects that currently observe other objects' properties. Apple is deliberately vague about the specific implementation of that collection because it wants to preserve the flexibility to change the implementation in the future. You add an object to the list of objects that observe a property by calling NSKeyValueObserving's -addObserver:forKeyPath:options:context: method. To remove an observer from the list, use NSKeyValueObserving's -removeObserver:forKeyPath:.

What Happens in -bind:toObject:withKeyPath:options:?

Sending the -bind:toObject:withKeyPath:options: message to an object creates a bi-directional set of Key Value Observing associations. Somewhere inside Apple's -(void)bind:(NSString *)binding toObject:(id)observableController withKeyPath:(NSString *)keyPath options:(NSDictionary *)options implementation, the following code or something similar is executed:

[self addObserver:observableController forKeyPath:binding
   options:(NSKeyValueObservingOptionNew|NSKeyValueObservingOptionOld)
   context:nil];

[observableController addObserver:self forKeyPath:keyPath
   options:(NSKeyValueObservingOptionNew|NSKeyValueObservingOptionOld)
   context:nil];

There isn't much more involved with the establishment of bindings. Apple documents the available options at http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/Protocols/NSKeyValueBindingCreation_Protocol/Reference/Reference.html. If a key path has multiple '.' separated properties, -bind:toObject:withKeyPath:options: adds observers for all of the individual properties in the path as needed. You can get information about existing bindings via the -(NSDictionary *)infoForBinding:(NSString *)binding method. Sending the -(void)unbind:(NSString *)binding message results in corresponding calls to NSKeyValueObserving's -(void)removeObserver:(NSObject *)anObserver forKeyPath:(NSString *)keyPath method.

Given that bindings are a relatively thin veneer on Key Value Observing, the magic of bindings resides within Key Value Observing.

How Does Key Value Observing Detect Changes to Observed Properties so That Observing Objects Can Be Notified?

The answer is that changes to observed properties need to be bracketed by calls to -(void)willChangeValueForKey:(NSString *)key and -(void)didChangeValueForKey:(NSString *)key. If you write your own code to programmatically modify the values of observed properties, you may need to explicitly call -willChangeValueForKey: and -didChangeValueForKey: like the following method that sets the "counter" property without calling an appropriate Accessor method:

- (void)incrementCounterByInt:(int)anIncrement {
[self willChangeValueForKey:@"counter"];
counter = counter + anIncrement;
[self didChangeValueForKey:@"counter"];
}

Inside NSObject's default implementation of the NSKeyValueObserving informal protocol, -willChangeValueForKey: and -didChangeValueForKey: are implemented to send messages to registered observers before and after the property value changes.

It's not necessary to explicitly call -willChangeValueForKey: and -didChangeValueForKey: within correctly named Accessor methods. When you use Objective-C 2.0's @synthesize directive to generate Accessor method implementations, the details are handled for you. Even if you hand-write Accessor methods, Cocoa provides automatic support for Key Value Observing through a little bit of Objective-C runtime manipulation briefly described at http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueObserving/Concepts/KVOImplementation.html. At runtime, Cocoa is able to replace your implementation of each Accessor method with a version that first calls -willChangeValueForKey:, then calls your implementation, and finally calls -didChangeValueForKey:.

When Key Value Coding's -(void)setValue:(id)value forKey:(NSString *)key or -(void)setValue:(id)value forKeyPath:(NSString *)keyPath methods are used to modify an observed property, the appropriate Accessor methods (if any) are called, and the Accessor methods take care of calling -willChangeValueForKey: and -didChangeValueForKey:. If there aren't any available Accessor methods, -setValue:forKey: and -setValue:forKeyPath: call -willChangeValueForKey: and -didChangeValueForKey: directly. In summary, you only need to explicitly call -willChangeValueForKey: and -didChangeValueForKey: if you change the value of an observed property without using Key Value Coding and without using an appropriately named Accessor method.

What Message Is Sent to Notify Registered Observers When an Observed Property's Value Is Changed?

By default, the -didChangeValueForKey: method sends the - (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context message to all registered observers after an observed property changes value. You can configure the -willChangeValueForKey: method to send notification before each change if you specify the NSKeyValueObservingOptionPrior option in the options: argument used to register an observer. The options: argument also governs whether the change notification includes only the previous value, only the new value, or both the old and new values.

Most Cocoa View subsystem classes already implement -observeValueForKeyPath: ofObject:change:context:. You need to implement that method in your custom View objects if you want them to work correctly with bindings. You may also need to implement -observeValueForKeyPath:ofObject:change:context: in model objects if you want to perform special logic whenever observed properties change. Unfortunately, implementing -observeValueForKeyPath:ofObject:change:context: is one of the least elegant aspects of using Cocoa.

You almost invariably have to implement -observeValueForKeyPath:ofObject:change:context: by using string comparisons to determine what logic to invoke based on which key path changed. The following code is a trivial example implementation of -observeValueForKeyPath:ofObject:change:context::

- (void)observeValueForKeyPath:(NSString *)keyPath
   ofObject:(id)object change:(NSDictionary *)change
   context:(void *)context
{
   if ([keyPath isEqualToString:@"floatValue"]) {
      NSNumber   *newValue = [change
         objectForKey:NSKeyValueChangeNewKey];
      if(0.0 > [newValue floatValue]) {
         // Perform special logic for negative values here
      }
      [self setNeedsDisplay:YES];
   }

   // be sure to call the super implementation
   [super observeValueForKeyPath:keyPath
      ofObject:object change:change
      context:context];
}

The need to perform explicit string comparisons like [keyPath isEqualToString: @"floatValue"] in -observeValueForKeyPath:ofObject:change:context: is inelegant. It's easy to imagine an implementation of -observeValueForKeyPath: ofObject:change:context: that has to perform hundreds of string comparisons after every observed property change to control application logic. Objective-C selectors and the Perform Selector pattern from Chapter 9 exist to make string comparisons in branch logic unnecessary. It's unfortunate that Apple didn't take advantage of the pre-existing patterns like NSNotification and the use of selectors when implementing Key Value Observing.

One way to make -observeValueForKeyPath:ofObject:change:context: a little bit more elegant is to use key path strings as notification names as follows:

- (void)observeValueForKeyPath:(NSString *)keyPath
   ofObject:(id)object change:(NSDictionary *)changeDictionary
   context:(void *)context
{
   // copy the change dictionary and add the context to it
   NSMutableDictionary  *infoDictionary = [NSMutableDictionary
      dictionaryWithDictionary:changeDictionary];
   [infoDictionary setObject:context forKey:@"MYBindingContext"];

   // post a notification to interested observers using the key path as
   // the notification name
   [[NSNotificationCenter defaultCenter] postNotificationName:keyPath
      object:object userInfo:infoDictionary];

   // be sure to call the super implementation
   [super observeValueForKeyPath:keyPath
      ofObject:object change:change
      context:context];
}

If you use the approach of converting Key Value Observation notifications into NSNotifications, you can have any number of observers that each register a different selector for the same key path. Unfortunately, the NSNotification approach has problems of its own. Using key path strings as notification names is not ideal because key paths are specified in Interface Builder and must be duplicated exactly in your code that registers for notifications. A simple change in Interface Builder could necessitate changes to notification code in multiple disparate places within your application. The compiler can't detect errors in the key path strings, so you must test at runtime to detect key path errors. Nevertheless, NSNotificationCenter provides at least one way to circumvent the use of explicit string comparisons in your own code.