MacResearch

Author: Drew McCormack
Website: http://www.maccoremac.com

In the last two tutorials we have covered the underlying technologies that make Cocoa Bindings possible: Key-Value Coding (KVC), and Key-Value Observing (KVO). The former allows you to access attributes using strings to identify them, and the latter allows you to observe when an attribute changes in your code. Today, we are going to show how these technologies are put to use in Cocoa Bindings, to keep the model and view layers in synch.

Cocoa Bindings

Cocoa Bindings, or Bindings for short, is primarily a controller layer technology. In fact, when Apple was first developing it, they even called it the Controller Layer. Basically, it is a set of classes that manage certain types of model objects, and keep the views in synch with the model data. For example, the NSArrayController class manages an array of objects: it can be used to add and remove objects, to sort them, and to select them. You could bind a table view to an NSArrayController to fill it with data. If the user edited the table view, the NSArrayController would automatically propagate the changes to the model layer and update the array of objects represented by the table. And if the array was changed programmatically, the NSArrayController would see this using KVO, and update the table view appropriately.

An important concept in Cocoa Bindings is that of a binding. A binding is a relationship defined by a key path. Bindings are usually defined in view classes; they indicate a relationship between what is displayed in the view, and the data contained in the model objects.

For example, an NSTableColumn, which is the class that represents a single column of data in a table view, has a binding called ‘value’. You bind ‘value’ by assigning it a controller object and a key-path in Interface Builder (or programmatically). Setting the controller to AtomsController, and the key path to atoms.mass, for example, would mean that the table column would show the mass of all the atoms in the atoms array belonging to the AtomsController object. If the atoms array changed, or any atomic mass was modified, the AtomsController would see this and update the table column appropriately.

Bindings can take some time to grok, because most programmers are used to defining relationships between objects using pointers. Usually, one object has a pointer to another and can thereby send it messages. A binding, on the other hand, doesn’t refer to a particular object, but to whatever object or objects happen to be associated with a particular key path at a given time. Think of it like a file system: The key path is like a directory path; in the same way you can say ‘Give me all the files in the Desktop folder, and inform me if anything changes there’, with bindings you can say ‘Give me all the masses of the Atom objects in the atoms array, and inform me if anything changes’. There is no hard-coded pointer between the view and the atoms, just a path through the object graph.

Bindings in Unitary

To make things more concrete, let’s update the Unitary application to use Cocoa Bindings, rather than the older outlet/target/action approach. To follow along, download the Unitary project as we last left it.

First, open the project in Xcode by double clicking the Unitary.xcodeproj file. In the Groups & Files list on the left, open the Classes group, and click on the UnitaryController.h file. The file source should appear in the editor on the right. (You may need to drag the split up from the bottom of the right pane to see the editor.) Replace the code there with the following:

#import <Cocoa/Cocoa.h>

@class Conversion;

@interface UnitaryController : NSObject {
    NSArray                          *conversions;
    Conversion                       *selectedConversion;
    double                           firstValue;
    double                           secondValue;
}

-(NSArray *)conversions;
-(void)setConversions:(NSArray *)newConversions;

-(Conversion *)selectedConversion;
-(void)setSelectedConversion:(Conversion *)newSelectedConversion;

-(double)firstValue;
-(void)setFirstValue:(double)newFirstValue;

-(double)secondValue;
-(void)setSecondValue:(double)newSecondValue;

@end

In many ways, this interface is simpler than the one we had before. It basically consists of a few instance variables, all of which were carried over from the previous version of the class, and accessor methods for each. Note that there are no outlets or actions here, or indeed any references to view objects at all. The previous version of the class had instance variables for each of the text fields in the interface, in order to update them and retrieve user-entered data. Because we are now using bindings, this is not necessary anymore: when the text fields are modified by the user, the accessor methods above will be called automatically.

Bindings in Interface Builder

Although you can bind things together programmatically, usually you will do it in Interface Builder. Open the MainMenu.nib file in the Resources group by double clicking it. Now drag the UnitaryController.h file from Xcode onto the MainMenu.nib window in Interface Builder, and click the Replace button when prompted. This informs IB of the changes we have made in UnitaryController.h.

Now we need to bind the various controls in the Unitary window to the UnitaryController instance:

• Double click the Window instance in the MainMenu.nib window to open it.
• Select the text field next to the Celsius label.
• Bring up the inspector by pressing Command-Shift-I.
• Choose Bindings from the popup button at the top of the inspector.
• Click on the disclosure triangle for the ‘value’ binding.
• In the ‘Bind to’ popup, choose the UnitaryController.
• For the ‘Model Key Path’, enter ‘firstValue’. You should notice the Bind checkbox get checked.

The procedure above is basically the same for setting all bindings in Interface Builder. You select a control, open the Bindings tab in the inspector, choose a binding, set the controller, and set the key path. There are many other options there, but we don’t need to worry about them at this juncture in time.

Repeat this procedure for the text field next to the ‘Fahrenheit’ label, but use the key path ‘secondValue’ instead.

Now we need to bind the labels themselves, so that they change based on the selected conversion. Click on the Celsius label to select it. In the Bindings tab of the inspector, choose the UnitaryController and set the key path to ‘selectedConversion.firstUnitName’. This says that the label will be given by the firstUnitName attribute of whichever Conversion object is selected at the time. Bind the Fahrenheit label to the key path ‘selectedConversion.secondUnitName’.

The only thing left to bind is the popup button used to select the conversion. Binding a popup button is a bit more involved, because you have to set bindings for the list of values the popup contains, as well as for the selection.

• Select the popup button and open the Bindings tab in the inspector.
• Open the ‘content’ binding. Choose the UnitaryController controller, and enter ‘conversions’ for the Model Key Path.
• Close the ‘content’ binding, and open the ‘contentObjects’ binding. Bind that exactly as for the ‘content’ binding.
• Lastly, bind the ‘selectedObject’ binding to the key path ‘selectedConversion’ of the UnitaryController controller.

You are now finished with IB. Save your changes, and return to Xcode.

Implementing the Controller

The final step is to write the implementation of the UnitaryController class. Replace the existing content of the UnitaryController.m file with the following source code:

#import "UnitaryController.h"
#import "Conversion.h"
#import "TemperatureConversion.h"
#import "EnergyConversion.h"

@implementation UnitaryController

-(void)awakeFromNib {        
    // Create conversion objects
    Conversion *temperatureConversion = [[TemperatureConversion alloc] init];
    Conversion *energyConversion = [[EnergyConversion alloc] init];
    conversions = [[NSArray arrayWithObjects:temperatureConversion, energyConversion, nil] retain];
    [temperatureConversion release];
    [energyConversion release];
    [self setConversions:conversions];
    [self setSelectedConversion:[conversions objectAtIndex:0]];
}

-(void)dealloc {
    [conversions release];
    [selectedConversion release];
    [super dealloc];
}

-(NSArray *)conversions {
    return conversions;
}

-(void)setConversions:(NSArray *)newConversions {
    [newConversions retain];
    [conversions release];
    conversions = newConversions;
}

-(Conversion *)selectedConversion {
    return selectedConversion;
}

-(void)setSelectedConversion:(Conversion *)newSelectedConversion {
    [newSelectedConversion retain];
    [selectedConversion release];
    selectedConversion = newSelectedConversion;
    [self setFirstValue:firstValue];  // Sync the values
}

-(double)firstValue {
    return firstValue;
}

-(void)setFirstValue:(double)newFirstValue {
    firstValue = newFirstValue;

    // Update second value
    [self willChangeValueForKey:@"secondValue"];
    secondValue = [selectedConversion secondValueForFirstValue:firstValue];
    [self didChangeValueForKey:@"secondValue"];
}

-(double)secondValue {
    return secondValue;
}

-(void)setSecondValue:(double)newSecondValue {
    secondValue = newSecondValue;

    // Update first value
    [self willChangeValueForKey:@"firstValue"];
    firstValue = [selectedConversion firstValueForSecondValue:secondValue];
    [self didChangeValueForKey:@"firstValue"];
}

@end

This may seem like quite a bit of code, but bear in mind that most of it is made up of accessor methods. The implementation begins with the awakeFromNib method, which sets up and stores the Conversion objects, just as before:

-(void)awakeFromNib {        
    // Create conversion objects
    Conversion *temperatureConversion = [[TemperatureConversion alloc] init];
    Conversion *energyConversion = [[EnergyConversion alloc] init];
    conversions = [[NSArray arrayWithObjects:temperatureConversion, energyConversion, nil] retain];
    [temperatureConversion release];
    [energyConversion release];
    [self setConversions:conversions];
    [self setSelectedConversion:[conversions objectAtIndex:0]];
}

Previously, this method would make a number of calls to view objects, but in the new version of the class, there are no view objects. The awakeFromNib simply initializes the data in the model layer. Through the magic of bindings, this will cause the views to be initialized automatically, because they will observe the changes via KVO.

The accessor methods hold a couple of surprises. The setSelectedConversion: method, for example, looks like this:

-(void)setSelectedConversion:(Conversion *)newSelectedConversion {
    [newSelectedConversion retain];
    [selectedConversion release];
    selectedConversion = newSelectedConversion;
    [self setFirstValue:firstValue];  // Sync the values
}

This is all standard, except for the last line. Because the selected conversion is being changed, we need to make sure that the conversion values are updated appropriately. The setFirstValue: call at the end achieves this, because the code of setFirstValue: updates the secondValue attribute to make the model data consistent.

-(void)setFirstValue:(double)newFirstValue {
    firstValue = newFirstValue;

    // Update second value
    [self willChangeValueForKey:@"secondValue"];
    secondValue = [selectedConversion secondValueForFirstValue:firstValue];
    [self didChangeValueForKey:@"secondValue"];
}

The second half of this method uses the selected conversion to update secondValue so that it is consistent with the new value of firstValue. The setSecondValue is the mirror image of setFirstValue.

One thing that might have you puzzled is the invocations of willChangeValueForKey: and didChangeValueForKey:. These are NSObject methods, and form part of the KVO infrastructure. These methods, when called in this way, allow you to update attributes directly without breaking KVO. Normally, KVO works when an accessor method is called; if you use standard accessors, you get KVO for free. But if you need to update an attribute without calling an accessor, you can still do it, but you have to handle the KVO notifications manually in your code, as shown here. If you didn’t do this, the text field bound to secondValue would not update properly, because the KVO notifications would not fire.

That’s all there is to the new UnitaryController class — pretty straightforward. The beauty of Bindings is that there is no reference in any of this code to any view at all; all relationships between model and view are defined in IB. All we have to do in our controller is supply KVC-conforming accessor methods, and make sure that our data remains in a valid state. Bindings takes care of keeping the model and view in synch.

You can now build and run the application in Xcode. Try entering a few values and change the selected conversion, to see how things update. We have managed to maintain the same behavior as the previous version, and get rid of a lot of code that was used to update and retrieve data from the user interface.

One last thing before concluding: In this example, our controller class, UnitaryController, is a subclass of NSObject. In a real Cocoa application, it would be more common to make UnitaryController a subclass of NSArrayController, which is ready built for managing an arrays of objects. Because this was a simple example, and could be handled without NSArrayController, I decided not to complicate things by including it, but you should at least be aware of this fact. In the weeks and months to come, we will meet NSArrayController many times, and you can learn more about it then.

Conclusions

That’s it for our simple introduction to Bindings. You can download the completed source code here. It can take a while to sink in, but be patient. As we move forward in the series, we will make more and more use of Bindings, and add more complex controls like table views. As you go, bindings will start to make more sense, and eventually become second nature.