The view we’ll be creating is a custom view to display a pie-chart; in the sample app the pie-chart will be drawn from data entered in an NSTableView. The finished application looks like the following:


If you’ve read previous posts on this site, you just might possibly have realized that I’m quite a big fan of Core Data. Unsurprisingly, therefore, the sample application is a Core Data document-based app. Its project and code can be downloaded here: customnsview.zip.

We’ll be looking at binding to an array controller’s ‘arrangedObjects’ key, and also its ’selectionIndexes’ key to enable the user to change which object is selected by clicking in our view. The segments on our pie-chart have both a ‘name’ and a numeric ‘value’ so, in the same way that you can bind a model’s keys to different column tables in an NSTableView, we’ll make it possible to bind a model’s keys to the names and values on the pie-chart. This would allow us to bind, for example, a department’s employees’ ‘fullNames’ and their ’salaries’ to view relative salaries, or in a file-viewing application, ‘fileNames’ and ‘fileSizes’ etc.

Basic Principles

To be able to display our information in the view, the view needs to maintain its own store of the data. We’ll maintain one array of segment names and one array of segment values. When the view is told to display itself, it will sum the values and use the total to determine how big each segment should be relative to the others; the view will then draw each segment using various geometric functions and bezier paths.

Creating our View

We’ll begin by creating a very basic subclass of NSView to which we can add various functionality throughout this article.

The View Subclass

• Begin by creating a new Xcode ‘Cocoa Core Data Document-Based Application’, called ‘CustomNSView’.
• In the new project’s browser, right-click (or control-click) on the Classes group and choose Add -> New File…; in the window that appears, chose the ‘Objective-C NSView Subclass’ and click Next.
• Name the file ‘MyPieChartView.m’ and make sure the ‘Also create “MyPieChartView.h” checkbox is ticked.
• After clicking ‘Finish’ to create the files, open up ‘MyPieChartView.m’ and change the template drawRect: method with the one below; we’ll also override the ‘isFlipped’ method to return YES so that our coordinate system has {0,0} set to the top left of the view:

  - (void)drawRect:(NSRect)rect
  {
  	[[NSColor blackColor] set];
  	NSRectFill([self bounds]);
  }
   
  - (BOOL)isFlipped
  {
  	return YES;
  }

Next we need to add an instance of our view to the Window of our document object.

• Open up MyDocument.xib in Interface Builder and delete the placeholder label from the Window.
• Drag a custom view onto the Window, set it to resize with the window and use the identity inspector to change the class of the view to ‘MyPieChartView’. My interface looks like this:
  

If you build and run the application, you should find that each new document opens a window with our black box view showing.

Adding the Arrays and Bindings

At this point, we need to add a couple of arrays to the view that will hold the names and values of each pie segment.

• Open the MyPieChartView.h header file and add in two NSArrays for the names and values, together with KVC accessors:

  @interface MyPieChartView : NSView
  {
  	NSArray *_segmentNamesArray;
  	NSArray *_segmentValuesArray;
  }
   
  - (NSArray *)segmentNamesArray;
  - (void)setSegmentNamesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentValuesArray;
  - (void)setSegmentValuesArray:(NSArray *)newArray;
   
  @end

• We’ll be allowing other objects to bind to these arrays so we’ll need to add an initialize: method to our view that exposes them for binding. Whenever the arrays change, we need to get the view to redisplay itself so in the setter methods we need to call [self setNeedsDisplayInRect:]. We also need to release the stored arrays when the view is deallocated. In MyPieChartView.m, implement these methods:

  + (void)initialize
  {
  	[self exposeBinding:@"segmentNamesArray"];
  	[self exposeBinding:@"segmentValuesArray"];
  }
   
  - (NSArray *)segmentNamesArray
  {
  	return [[_segmentNamesArray retain] autorelease];
  }
   
  - (void)setSegmentNamesArray:(NSArray *)newArray
  {
  	[self willChangeValueForKey:@"segmentNamesArray"];
  	[_segmentNamesArray release];
  	_segmentNamesArray = [newArray copy];
  	[self didChangeValueForKey:@"segmentNamesArray"];
   
  	[self setNeedsDisplayInRect:[self visibleRect]];
  }
   
  - (NSArray *)segmentValuesArray
  {
  	return [[_segmentValuesArray retain] autorelease];
  }
   
  - (void)setSegmentValuesArray:(NSArray *)newArray
  {
  	[self willChangeValueForKey:@"segmentValuesArray"];
  	[_segmentValuesArray release];
  	_segmentValuesArray = [newArray copy];
  	[self didChangeValueForKey:@"segmentValuesArray"];
   
  	[self setNeedsDisplayInRect:[self visibleRect]];
  }
   
  - (void)dealloc
  {
  	[_segmentNamesArray release];
  	[_segmentValuesArray release];
  	[super dealloc];
  }

With our arrays setup, we need to create a data model and some objects to which we can bind.

The Data Model

For the purposes of this demonstration, we need only a very simple data model together with an NSTableView in the interface to add and remove objects.

• Open MyDocument.xcdatamodel and add a new entity called ‘PieSegment’. Add two attributes, a String and a Decimal, called ‘name’ and ‘amount’ respectively. Give the ‘name’ attribute a default string like ‘new segment’ and ‘amount’ a default value of 0.
• Return to MyDocument.xib in Interface Builder and add a new NSArrayController called ’segmentsArrayController’ for the ‘PieSegment’ entity, that prepares content. Bind its Managed Object Context to the File’s Owner managedObjectContext.
• Add an NSTableView and two buttons to the document window; bind the columns of the table view to the ‘name’ and ‘amount’ path of the segmentsArrayController arrangedObjects key.
• Add a decimal NSNumberFormatter to the ‘amount’ column.
• Connect the buttons to the array controller’s add: and remove: actions and make any other adjustments as you wish. My interface looks like this:
  

Build and Run the application to make sure that the table view and buttons work as expected.

Setting up the Bindings and Displaying the Data

Obviously, nothing is happening yet with our custom NSView since we haven’t bound anything to our names and values arrays, nor have we modified the view’s drawRect: method. We’ll rectify that now:

• Open the MyDocument.h header file and add in IBOutlets for the array controller and view:

  @interface MyDocument : NSPersistentDocument
  {
  	IBOutlet NSArrayController *segmentsArrayController;
  	IBOutlet NSView *pieChartView;
  }
   
  @end

• Connect these outlets to the relevant view and controller in Interface Builder.
• In MyDocument.m, modify the windowControllerDidLoadNib: method so that we bind the view to the array controller:

  - (void)windowControllerDidLoadNib:(NSWindowController *)windowController
  {
  	[super windowControllerDidLoadNib:windowController];
   
  	[pieChartView bind:@"segmentNamesArray" toObject:segmentsArrayController withKeyPath:@"arrangedObjects.name" options:nil];
  	[pieChartView bind:@"segmentValuesArray" toObject:segmentsArrayController withKeyPath:@"arrangedObjects.amount" options:nil];
  }

• In MyPieChartView.m, modify the drawRect: method with some very simple text display code that will just output the two arrays side-by-side:

  - (void)drawRect:(NSRect)rect
  {
  	[[NSColor blackColor] set];
  	NSRectFill([self bounds]);
   
  	NSPoint midPoint = NSMakePoint(NSMidX([self bounds]), NSMidY([self bounds]));
   
  	NSString *namesText = [[self segmentNamesArray] description];
  	NSString *valuesText = [[self segmentValuesArray] description];
   
  	NSDictionary *textAttributes = [NSDictionary dictionaryWithObjectsAndKeys: [NSColor whiteColor], NSForegroundColorAttributeName, [NSFont systemFontOfSize:10], NSFontAttributeName, nil];
   
  	NSSize namesSize = [namesText sizeWithAttributes:textAttributes];
  	NSSize valuesSize = [valuesText sizeWithAttributes:textAttributes];
   
  	NSPoint namesTextPoint = NSMakePoint(midPoint.x - namesSize.width - 2, midPoint.y - (namesSize.height / 2));
  	NSPoint valuesTextPoint = NSMakePoint(midPoint.x + valuesSize.width + 2, midPoint.y - (valuesSize.height / 2));
   
  	[namesText drawAtPoint:namesTextPoint withAttributes:textAttributes];
  	[valuesText drawAtPoint:valuesTextPoint withAttributes:textAttributes];
  }

If you build and run the application, you’ll find that values added to the table view will show up in columns in the pie-chart view:

Displaying the Data as a Pie-Chart

Whilst at this point we have a nicely-bound custom NSView subclass, we still need to use the provided data to display a pie-chart. There are many different ways to go about displaying such a chart; what follows is the path I decided to take. You may have different suggestions, in which case please feel free to make comments. The methods I use to calculate the sizes and shapes of the segments may not be the fastest, or least memory-intensive, but should be fairly easily understood by anyone with basic mathematical and geometric knowledge.

We’ll draw the segments of the ‘pie’ using NSBezierPaths. Since it isn’t only the changing of data that can cause a view to be told to draw itself, we’ll ‘cache’ these paths in an array held by the view, updating them only if the data changes. To make it easy to color each segment we’ll maintain a static class array of colors, generated randomly when needed, such that additional instances of our class can also use the same colors.

Adding Drawing Information to our View

We need to add an array pointer to MyPieChartView that will hold the segment paths. We also need a method to access this paths array, and a method that will regenerate it when necessary. We need a method that will produce a random color, and another method that will supply a color from a static colors array if given a zero-based index, generating it if necessary.

• Change the MyPieChartView.h header file by adding the new array pointer and methods:

  @interface MyPieChartView : NSView
  {
  	NSArray *_segmentNamesArray;
  	NSArray *_segmentValuesArray;
   
  	NSMutableArray *_segmentPathsArray;
  }
   
  - (NSArray *)segmentNamesArray;
  - (void)setSegmentNamesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentValuesArray;
  - (void)setSegmentValuesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentPathsArray;
  - (void)generateDrawingInformation;
   
  - (NSColor *)randomColor;
  - (NSColor *)colorForIndex:(unsigned)index;
   
  @end

• In MyPieChartView.m implement the segmentPathsArray: method and modify the dealloc: method to release the array:

  - (NSArray *)segmentPathsArray
  {
  	return _segmentPathsArray;
  }
   
  - (void)dealloc
  {
  	[_segmentNamesArray release];
  	[_segmentValuesArray release];
   
  	if( _segmentPathsArray )
  		[_segmentPathsArray release];
   
  	[super dealloc];
  }

• Implement the randomColor: and colorForIndex: methods like this:

  - (NSColor *)randomColor
  {
  	float red = (random()%1000)/1000.0;
  	float green = (random()%1000)/1000.0;
  	float blue = (random()%1000)/1000.0;
  	float alpha = (random()%1000)/1000.0;
  	return [NSColor colorWithCalibratedRed:red green:green blue:blue alpha:alpha];
  }
   
  - (NSColor *)colorForIndex:(unsigned)index
  {
  	static NSMutableArray *colorsArray = nil;
   
  	if( colorsArray == nil )
  	{
  		colorsArray = [[NSMutableArray alloc] init];
  	}
   
  	if( index >= [colorsArray count] )
  	{
  		unsigned currentNum = 0;
  		for( currentNum = [colorsArray count]; currentNum <= index; currentNum++ )
  		{
  			[colorsArray addObject:[self randomColor]];
  		}
  	}
   
  	return [colorsArray objectAtIndex:index];
  }

• The generateDrawingInformation: method is quite complicated. It keeps hold of its own pointer to the segmentValuesArray, and uses this to generate the paths array. Here I’m also using #define to set a value for the padding around the pie-chart.

  - (void)generateDrawingInformation
  {
  	// Keep a pointer to the segmentValuesArray
  	NSArray *cachedSegmentValuesArray = [self segmentValuesArray];
   
  	// Get rid of any existing Paths Array
  	if( _segmentPathsArray )
  	{
  		[_segmentPathsArray release];
  		_segmentPathsArray = nil;
  	}
   
  	// If there aren't any values to display, we can exit now
  	if( [cachedSegmentValuesArray count] < 1 )
  		return;
   
  	// Get the sum of the amounts and exit if it is zero
  	float sumOfAmounts = 0;
  	for( NSNumber *eachAmountToSum in cachedSegmentValuesArray )
  		sumOfAmounts += [eachAmountToSum floatValue];
   
  	if( sumOfAmounts == 0 )
  		return;
   
  	_segmentPathsArray = [[NSMutableArray alloc] initWithCapacity:[cachedSegmentValuesArray count]];
   
  #define PADDINGAROUNDGRAPH 20.0
   
  	NSRect viewBounds = [self bounds];
  	NSRect graphRect = NSInsetRect(viewBounds, PADDINGAROUNDGRAPH, PADDINGAROUNDGRAPH);
   
  	// Make the graphRect square and centred
  	if( graphRect.size.width > graphRect.size.height )
  	{
  		double sizeDifference = graphRect.size.width - graphRect.size.height;
  		graphRect.size.width = graphRect.size.height;
  		graphRect.origin.x += (sizeDifference / 2);
  	}
   
  	if( graphRect.size.height > graphRect.size.width )
  	{
  		double sizeDifference = graphRect.size.height - graphRect.size.width;
  		graphRect.size.height = graphRect.size.width;
  		graphRect.origin.y += (sizeDifference / 2);
  	}
   
  	// Calculate how big a 'unit' is
  	float unitSize = (360.0 / sumOfAmounts);
   
  	if( unitSize > 360 )
  		unitSize = 360;
   
  	float radius = graphRect.size.width / 2;
   
  	NSPoint midPoint = NSMakePoint( NSMidX(graphRect), NSMidY(graphRect) );
   
  	// cycle through the segmentValues and create the bezier paths
  	float currentDegree = 0;
  	unsigned currentIndex;
  	for( currentIndex = 0; currentIndex < [cachedSegmentValuesArray count]; currentIndex++ )
  	{
  		NSNumber *eachValue = [cachedSegmentValuesArray objectAtIndex:currentIndex];
   
  		float startDegree = currentDegree;
  		currentDegree += ([eachValue floatValue] * unitSize);
  		float endDegree = currentDegree;
   
  		NSBezierPath *eachSegmentPath = [NSBezierPath bezierPath];
  		[eachSegmentPath moveToPoint:midPoint];
   
  		[eachSegmentPath appendBezierPathWithArcWithCenter:midPoint radius:radius startAngle:startDegree endAngle:endDegree];
  		[eachSegmentPath closePath]; // close path also handles the lines from the midPoint to the start and end of the arc
  		[eachSegmentPath setLineWidth:2.0];
   
  		[_segmentPathsArray addObject:eachSegmentPath];
  	}
  }

• The paths array should be recalculated whenever the bound arrays change, so modify the two setter methods:

  - (void)setSegmentNamesArray:(NSArray *)newArray
  {
  	[self willChangeValueForKey:@"segmentNamesArray"];
  	[_segmentNamesArray release];
  	_segmentNamesArray = [newArray copy];
  	[self didChangeValueForKey:@"segmentNamesArray"];
   
  	[self generateDrawingInformation];
  	[self setNeedsDisplayInRect:[self visibleRect]];
  }
   
  - (void)setSegmentValuesArray:(NSArray *)newArray
  {
  	[self willChangeValueForKey:@"segmentValuesArray"];
  	[_segmentValuesArray release];
  	_segmentValuesArray = [newArray copy];
  	[self didChangeValueForKey:@"segmentValuesArray"];
   
  	[self generateDrawingInformation];
  	[self setNeedsDisplayInRect:[self visibleRect]];
  }

• Finally, we can now replace the drawRect: method so that it displays the paths:

  - (void)drawRect:(NSRect)rect
  {
  	[[NSColor whiteColor] set]; // white background
  	NSRectFill([self bounds]);
   
  	NSArray *pathsArray = [self segmentPathsArray];
  	unsigned count;
  	for( count = 0; count < [pathsArray count]; count++ )
  	{
  		NSBezierPath *eachPath = [pathsArray objectAtIndex:count];
   
  		// fill the path with the drawing color for this index
  		[[self colorForIndex:count] set];
  		[eachPath fill];
   
  		// draw a black border around it
  		[[NSColor blackColor] set];
  		[eachPath stroke];
  	}
  }

When you build and run the project, you’ll find that segments added to the table view with non-zero amounts will show up as a basic, colored pie-chart in the view:

Displaying the Text

So far we haven’t done anything at all with the segment names; we still need to display these on our pie-chart. We’ll maintain an array of dictionaries containing information to display the text. We’ll modify the generateDrawingInformation: method so that it creates this array of dictionaries, and change the drawRect: method to display the text on the pie-chart.

• Open the MyPieChartView.h header file and add in an array for the text information, along with an accessor:

  @interface MyPieChartView : NSView
  {
  	NSArray *_segmentNamesArray;
  	NSArray *_segmentValuesArray;
   
  	NSMutableArray *_segmentPathsArray;
  	NSMutableArray *_segmentTextsArray;
  }
   
  - (NSArray *)segmentNamesArray;
  - (void)setSegmentNamesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentValuesArray;
  - (void)setSegmentValuesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentPathsArray;
  - (NSArray *)segmentTextsArray;
  - (void)generateDrawingInformation;
   
  - (NSColor *)randomColor;
  - (NSColor *)colorForIndex:(unsigned)index;
   
  @end

• Add the accessor method to MyPieChartView.m and change dealloc: to release it:

  - (NSArray *)segmentTextsArray
  {
  	return _segmentTextsArray;
  }
   
  - (void)dealloc
  {
  	[_segmentNamesArray release];
  	[_segmentValuesArray release];
   
  	if( _segmentPathsArray )
  		[_segmentPathsArray release];
   
  	if( _segmentTextsArray )
  		[_segmentTextsArray release];
   
  	[super dealloc];
  }

• Now modify the generateDrawingInformation: method so that it stores necessary information in this texts array. We draw each segment arc using two ‘half’ arcs rather than one in order to find out the midpoint from which we decide where to put the text. We also check to see in which ‘quarter’ of the pie-chart view that midpoint falls and offset it by a #defined TEXTPADDING value accordingly, also making sure that the resultant point doesn’t fall outside of the view’s bounds:

  - (void)generateDrawingInformation
  {
  	// Keep pointers to the segmentValuesArray and segmentNamesArray
  	NSArray *cachedSegmentValuesArray = [self segmentValuesArray];
  	NSArray *cachedSegmentNamesArray = [self segmentNamesArray];
   
  	// Get rid of any existing Paths Array
  	if( _segmentPathsArray )
  	{
  		[_segmentPathsArray release];
  		_segmentPathsArray = nil;
  	}
   
  	// Get rid of any existing Texts Array
  	if( _segmentTextsArray )
  	{
  		[_segmentTextsArray release];
  		_segmentTextsArray = nil;
  	}
   
  	// If there aren't any values to display, we can exit now
  	if( [cachedSegmentValuesArray count] < 1 )
  		return;
   
  	// Get the sum of the amounts and exit if it is zero
  	float sumOfAmounts = 0;
  	for( NSNumber *eachAmountToSum in cachedSegmentValuesArray )
  		sumOfAmounts += [eachAmountToSum floatValue];
   
  	if( sumOfAmounts == 0 )
  		return;
   
  	_segmentPathsArray = [[NSMutableArray alloc] initWithCapacity:[cachedSegmentValuesArray count]];
  	_segmentTextsArray = [[NSMutableArray alloc] initWithCapacity:[cachedSegmentValuesArray count]];
   
  #define PADDINGAROUNDGRAPH 20.0
  #define TEXTPADDING 5.0
   
  	NSRect viewBounds = [self bounds];
  	NSRect graphRect = NSInsetRect(viewBounds, PADDINGAROUNDGRAPH, PADDINGAROUNDGRAPH);
   
  	// Make the graphRect square and centred
  	if( graphRect.size.width > graphRect.size.height )
  	{
  		double sizeDifference = graphRect.size.width - graphRect.size.height;
  		graphRect.size.width = graphRect.size.height;
  		graphRect.origin.x += (sizeDifference / 2);
  	}
   
  	if( graphRect.size.height > graphRect.size.width )
  	{
  		double sizeDifference = graphRect.size.height - graphRect.size.width;
  		graphRect.size.height = graphRect.size.width;
  		graphRect.origin.y += (sizeDifference / 2);
  	}
   
  	// get NSRects for the different quarters of the pie-chart
  	NSRect topLeftRect, topRightRect;
  	NSDivideRect(viewBounds, &topLeftRect, &topRightRect, (viewBounds.size.width / 2), NSMinXEdge );
  	NSRect bottomLeftRect, bottomRightRect;
  	NSDivideRect(topLeftRect, &topLeftRect, &bottomLeftRect, (viewBounds.size.height / 2), NSMinYEdge );
  	NSDivideRect(topRightRect, &topRightRect, &bottomRightRect, (viewBounds.size.height / 2), NSMinYEdge );
   
  	// Calculate how big a 'unit' is
  	float unitSize = (360.0 / sumOfAmounts);
   
  	if( unitSize > 360 )
  		unitSize = 360;
   
  	float radius = graphRect.size.width / 2;
   
  	NSPoint midPoint = NSMakePoint( NSMidX(graphRect), NSMidY(graphRect) );
   
  	// Set the text attributes to be used for each textual display
  	NSDictionary *textAttributes = [NSDictionary dictionaryWithObjectsAndKeys: [NSColor whiteColor], NSBackgroundColorAttributeName, [NSColor blackColor], NSForegroundColorAttributeName, [NSFont systemFontOfSize:12], NSFontAttributeName, nil];
   
  	// cycle through the segmentValues and create the bezier paths
  	// Also add the text details (note we expect the texts' indexes to tie up with the values' indexes)
  	float currentDegree = 0;
  	unsigned currentIndex;
  	for( currentIndex = 0; currentIndex < [cachedSegmentValuesArray count]; currentIndex++ )
  	{
  		NSNumber *eachValue = [cachedSegmentValuesArray objectAtIndex:currentIndex];
   
  		float startDegree = currentDegree;
  		currentDegree += ([eachValue floatValue] * unitSize);
  		float endDegree = currentDegree;
  		float midDegree = startDegree + ((endDegree - startDegree) / 2);
   
  		NSBezierPath *eachSegmentPath = [NSBezierPath bezierPath];
  		[eachSegmentPath moveToPoint:midPoint];
   
  		[eachSegmentPath appendBezierPathWithArcWithCenter:midPoint radius:radius startAngle:startDegree endAngle:midDegree clockwise:NO];
   
  		NSPoint textPoint = [eachSegmentPath currentPoint];
   
  		[eachSegmentPath appendBezierPathWithArcWithCenter:midPoint radius:radius startAngle:midDegree endAngle:endDegree clockwise:NO];
   
  		[eachSegmentPath closePath]; // close path also handles the lines from the midPoint to the start and end of the arc
  		[eachSegmentPath setLineWidth:2.0];
   
  		[_segmentPathsArray addObject:eachSegmentPath];
   
  		// Get the text to be displayed, if it exists, and see how big it is
  		NSString *eachText = @"";
  		if( [cachedSegmentNamesArray count] > currentIndex )
  			eachText = [cachedSegmentNamesArray objectAtIndex:currentIndex];
   
  		NSSize textSize = [eachText sizeWithAttributes:textAttributes];
   
  		// Offset it by TEXTPADDING in direction suitable for whichever quarter of the view it is in
  		if( NSPointInRect(textPoint, topLeftRect) )
  		{
  			textPoint.y -= (textSize.height + TEXTPADDING);
  			textPoint.x -= (textSize.width + TEXTPADDING);
  		}
  		else if( NSPointInRect(textPoint, topRightRect) )
  		{
  			textPoint.y -= (textSize.height + TEXTPADDING);
  			textPoint.x += TEXTPADDING;
  		}
  		else if( NSPointInRect(textPoint, bottomLeftRect) )
  		{
  			textPoint.y += TEXTPADDING;
  			textPoint.x -= (textSize.width + TEXTPADDING);
  		}
  		else if( NSPointInRect(textPoint, bottomRightRect) )
  		{
  			textPoint.y += TEXTPADDING;
  			textPoint.x += TEXTPADDING;
  		}
   
  		// Make sure the point isn't outside the view's bounds
  		if( textPoint.x < viewBounds.origin.x )
  			textPoint.x = viewBounds.origin.x;
   
  		if( (textPoint.x + textSize.width) > (viewBounds.origin.x + viewBounds.size.width) )
  			textPoint.x = viewBounds.origin.x + viewBounds.size.width - textSize.width;
   
  		if( textPoint.y < viewBounds.origin.y )
  			textPoint.y = viewBounds.origin.y;
   
  		if( (textPoint.y + textSize.height) > (viewBounds.origin.y + viewBounds.size.height) )
  			textPoint.y = viewBounds.origin.y + viewBounds.size.height - textSize.height;
   
  		// Finally add the details as a dictionary to our segmentTextsArray.
  		// We include here the textAttributes lest we decide later to e.g. color the texts the same color as the segment fill
  		[_segmentTextsArray addObject:[NSDictionary dictionaryWithObjectsAndKeys:[NSNumber numberWithFloat:textPoint.x], @"textPointX", [NSNumber numberWithFloat:textPoint.y], @"textPointY", eachText, @"text", textAttributes, @"textAttributes", nil]];
  	}
  }

• Modify the drawRect: method to display the text:

  - (void)drawRect:(NSRect)rect
  {
  	[[NSColor whiteColor] set]; // white background
  	NSRectFill([self bounds]);
   
  	NSArray *pathsArray = [self segmentPathsArray];
  	unsigned count;
  	for( count = 0; count < [pathsArray count]; count++ )
  	{
  		NSBezierPath *eachPath = [pathsArray objectAtIndex:count];
   
  		// fill the path with the drawing color for this index
  		[[self colorForIndex:count] set];
  		[eachPath fill];
   
  		// draw a black border around it
  		[[NSColor blackColor] set];
  		[eachPath stroke];
  	}
   
  	NSArray *textsArray = [self segmentTextsArray];
   
  	for( count = 0; count < [textsArray count]; count++ )
  	{
  		NSDictionary *eachTextDictionary = [textsArray objectAtIndex:count];
  		NSPoint textPoint = NSMakePoint( [[eachTextDictionary valueForKey:@"textPointX"] floatValue], [[eachTextDictionary valueForKey:@"textPointY"] floatValue] );
   
  		NSDictionary *textAttributes = [eachTextDictionary valueForKey:@"textAttributes"];
   
  		NSString *text = [eachTextDictionary valueForKey:@"text"];
  		[text drawAtPoint:textPoint withAttributes:textAttributes];
  	}
  }

The view should now display text on the chart:

Indicating the Selected Segment(s)

In order to display which segment is selected, we need to bind to the array controller’s ’selectionIndexes’; the view needs to keep its own local copy of these indexes, and expose binding for them:

• Add an NSIndexSet for the selectionIndexes to the MyPieChartView.h header file, along with a getter and setter:

  @interface MyPieChartView : NSView
  {
  	NSArray *_segmentNamesArray;
  	NSArray *_segmentValuesArray;
   
  	NSMutableArray *_segmentPathsArray;
  	NSMutableArray *_segmentTextsArray;
   
  	NSIndexSet *_selectionIndexes;
  }
   
  - (NSArray *)segmentNamesArray;
  - (void)setSegmentNamesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentValuesArray;
  - (void)setSegmentValuesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentPathsArray;
  - (NSArray *)segmentTextsArray;
  - (void)generateDrawingInformation;
   
  - (NSColor *)randomColor;
  - (NSColor *)colorForIndex:(unsigned)index;
   
  - (NSIndexSet *)selectionIndexes;
  - (void)setSelectionIndexes:(NSIndexSet *)newIndexes;
   
  @end

• Implement these accessor methods and expose the binding:

  - (NSIndexSet *)selectionIndexes
  {
      return [[_selectionIndexes retain] autorelease];
  }
   
  - (void)setSelectionIndexes:(NSIndexSet *)newIndexes
  {
  	if ((_selectionIndexes != newIndexes) && (![_selectionIndexes isEqualToIndexSet:newIndexes]))
  	{
  		[self willChangeValueForKey:@"selectionIndexes"];
  		[_selectionIndexes release];
  		_selectionIndexes = [newIndexes copy];
  		[self didChangeValueForKey:@"selectionIndexes"];
   
  		[self generateDrawingInformation];
  		[self setNeedsDisplayInRect:[self visibleRect]];
  	}
  }
   
  + (void)initialize
  {
  	[self exposeBinding:@"segmentNamesArray"];
  	[self exposeBinding:@"segmentValuesArray"];
  	[self exposeBinding:@"selectionIndexes"];
  }

• In MyDocument.m, bind the selectionIndexes to the array controller:

  - (void)windowControllerDidLoadNib:(NSWindowController *)windowController
  {
  	[super windowControllerDidLoadNib:windowController];
   
  	[pieChartView bind:@"segmentNamesArray" toObject:segmentsArrayController withKeyPath:@"arrangedObjects.name" options:nil];
  	[pieChartView bind:@"segmentValuesArray" toObject:segmentsArrayController withKeyPath:@"arrangedObjects.amount" options:nil];
  	[pieChartView bind:@"selectionIndexes" toObject:segmentsArrayController withKeyPath:@"selectionIndexes" options:nil];
  }

• We also need to modify the generateDrawingInformation: method to offset the selected segment (and its text) by a #defined amount:

  - (void)generateDrawingInformation
  {
  	// Keep pointers to the segmentValuesArray and segmentNamesArray
  	NSArray *cachedSegmentValuesArray = [self segmentValuesArray];
  	NSArray *cachedSegmentNamesArray = [self segmentNamesArray];
   
  	// Get rid of any existing Paths Array
  	if( _segmentPathsArray )
  	{
  		[_segmentPathsArray release];
  		_segmentPathsArray = nil;
  	}
   
  	// Get rid of any existing Texts Array
  	if( _segmentTextsArray )
  	{
  		[_segmentTextsArray release];
  		_segmentTextsArray = nil;
  	}
   
  	// If there aren't any values to display, we can exit now
  	if( [cachedSegmentValuesArray count] < 1 )
  		return;
   
  	// Get the sum of the amounts and exit if it is zero
  	float sumOfAmounts = 0;
  	for( NSNumber *eachAmountToSum in cachedSegmentValuesArray )
  		sumOfAmounts += [eachAmountToSum floatValue];
   
  	if( sumOfAmounts == 0 )
  		return;
   
  	_segmentPathsArray = [[NSMutableArray alloc] initWithCapacity:[cachedSegmentValuesArray count]];
  	_segmentTextsArray = [[NSMutableArray alloc] initWithCapacity:[cachedSegmentValuesArray count]];
   
  	NSIndexSet *selectionIndexes = [self selectionIndexes];
  	BOOL shouldOffsetSelectedSegment = ([selectionIndexes count] > 0) ? YES : NO;
   
  #define PADDINGAROUNDGRAPH 20.0
  #define TEXTPADDING 5.0
  #define SELECTEDSEGMENTOFFSET 5.0
   
  	NSRect viewBounds = [self bounds];
  	NSRect graphRect = NSInsetRect(viewBounds, PADDINGAROUNDGRAPH, PADDINGAROUNDGRAPH);
   
  	// Make the graphRect square and centred
  	if( graphRect.size.width > graphRect.size.height )
  	{
  		double sizeDifference = graphRect.size.width - graphRect.size.height;
  		graphRect.size.width = graphRect.size.height;
  		graphRect.origin.x += (sizeDifference / 2);
  	}
   
  	if( graphRect.size.height > graphRect.size.width )
  	{
  		double sizeDifference = graphRect.size.height - graphRect.size.width;
  		graphRect.size.height = graphRect.size.width;
  		graphRect.origin.y += (sizeDifference / 2);
  	}
   
  	// get NSRects for the different quarters of the pie-chart
  	NSRect topLeftRect, topRightRect;
  	NSDivideRect(viewBounds, &topLeftRect, &topRightRect, (viewBounds.size.width / 2), NSMinXEdge );
  	NSRect bottomLeftRect, bottomRightRect;
  	NSDivideRect(topLeftRect, &topLeftRect, &bottomLeftRect, (viewBounds.size.height / 2), NSMinYEdge );
  	NSDivideRect(topRightRect, &topRightRect, &bottomRightRect, (viewBounds.size.height / 2), NSMinYEdge );
   
  	// Calculate how big a 'unit' is
  	float unitSize = (360.0 / sumOfAmounts);
   
  	if( unitSize > 360 )
  		unitSize = 360;
   
  	float radius = graphRect.size.width / 2;
   
  	NSPoint midPoint = NSMakePoint( NSMidX(graphRect), NSMidY(graphRect) );
   
  	// Set the text attributes to be used for each textual display
  	NSDictionary *textAttributes = [NSDictionary dictionaryWithObjectsAndKeys: [NSColor whiteColor], NSBackgroundColorAttributeName, [NSColor blackColor], NSForegroundColorAttributeName, [NSFont systemFontOfSize:12], NSFontAttributeName, nil];
   
  	// cycle through the segmentValues and create the bezier paths
  	// Also add the text details (note we expect the texts' indexes to tie up with the values' indexes)
  	float currentDegree = 0;
  	unsigned currentIndex;
  	for( currentIndex = 0; currentIndex < [cachedSegmentValuesArray count]; currentIndex++ )
  	{
  		NSNumber *eachValue = [cachedSegmentValuesArray objectAtIndex:currentIndex];
   
  		float startDegree = currentDegree;
  		currentDegree += ([eachValue floatValue] * unitSize);
  		float endDegree = currentDegree;
  		float midDegree = startDegree + ((endDegree - startDegree) / 2);
   
  		NSBezierPath *eachSegmentPath = [NSBezierPath bezierPath];
  		[eachSegmentPath moveToPoint:midPoint];
   
  		[eachSegmentPath appendBezierPathWithArcWithCenter:midPoint radius:radius startAngle:startDegree endAngle:midDegree clockwise:NO];
   
  		NSPoint textPoint = [eachSegmentPath currentPoint];
   
  		[eachSegmentPath appendBezierPathWithArcWithCenter:midPoint radius:radius startAngle:midDegree endAngle:endDegree clockwise:NO];
   
  		[eachSegmentPath closePath]; // close path also handles the lines from the midPoint to the start and end of the arc
  		[eachSegmentPath setLineWidth:2.0];
   
  		// Check to see whether we should offset this segment if it's currently selected in the array controller
  		if( shouldOffsetSelectedSegment && [selectionIndexes containsIndex:currentIndex] )
  		{
  			float differenceRatio = (SELECTEDSEGMENTOFFSET / radius) + (SELECTEDSEGMENTOFFSET / (endDegree - startDegree));
   
  			float diffY = (textPoint.y - midPoint.y) * differenceRatio;
  			float diffX = (textPoint.x - midPoint.x) * differenceRatio;
   
  			NSAffineTransform *transform = [NSAffineTransform transform];
   
  			[transform translateXBy:diffX yBy:diffY];
  			[eachSegmentPath transformUsingAffineTransform: transform];
   
  			textPoint = [transform transformPoint:textPoint];
  		}
   
  		[_segmentPathsArray addObject:eachSegmentPath];
   
  		// Get the text to be displayed, if it exists, and see how big it is
  		NSString *eachText = @"";
  		if( [cachedSegmentNamesArray count] > currentIndex )
  			eachText = [cachedSegmentNamesArray objectAtIndex:currentIndex];
   
  		NSSize textSize = [eachText sizeWithAttributes:textAttributes];
   
  		// Offset it by TEXTPADDING in direction suitable for whichever quarter of the view it is in
  		if( NSPointInRect(textPoint, topLeftRect) )
  		{
  			textPoint.y -= (textSize.height + TEXTPADDING);
  			textPoint.x -= (textSize.width + TEXTPADDING);
  		}
  		else if( NSPointInRect(textPoint, topRightRect) )
  		{
  			textPoint.y -= (textSize.height + TEXTPADDING);
  			textPoint.x += TEXTPADDING;
  		}
  		else if( NSPointInRect(textPoint, bottomLeftRect) )
  		{
  			textPoint.y += TEXTPADDING;
  			textPoint.x -= (textSize.width + TEXTPADDING);
  		}
  		else if( NSPointInRect(textPoint, bottomRightRect) )
  		{
  			textPoint.y += TEXTPADDING;
  			textPoint.x += TEXTPADDING;
  		}
   
  		// Make sure the point isn't outside the view's bounds
  		if( textPoint.x < viewBounds.origin.x )
  			textPoint.x = viewBounds.origin.x;
   
  		if( (textPoint.x + textSize.width) > (viewBounds.origin.x + viewBounds.size.width) )
  			textPoint.x = viewBounds.origin.x + viewBounds.size.width - textSize.width;
   
  		if( textPoint.y < viewBounds.origin.y )
  			textPoint.y = viewBounds.origin.y;
   
  		if( (textPoint.y + textSize.height) > (viewBounds.origin.y + viewBounds.size.height) )
  			textPoint.y = viewBounds.origin.y + viewBounds.size.height - textSize.height;
   
  		// Finally add the details as a dictionary to our segmentTextsArray.
  		// We include here the textAttributes lest we decide later to e.g. color the texts the same color as the segment fill
  		[_segmentTextsArray addObject:[NSDictionary dictionaryWithObjectsAndKeys:[NSNumber numberWithFloat:textPoint.x], @"textPointX", [NSNumber numberWithFloat:textPoint.y], @"textPointY", eachText, @"text", textAttributes, @"textAttributes", nil]];
  	}
  }

• We’ll also modify the drawRect: method so that it fills selected segments with blue rather than the usual colour:

  - (void)drawRect:(NSRect)rect
  {
  	[[NSColor whiteColor] set]; // white background
  	NSRectFill([self bounds]);
   
  	NSArray *pathsArray = [self segmentPathsArray];
  	unsigned count;
  	for( count = 0; count < [pathsArray count]; count++ )
  	{
  		NSBezierPath *eachPath = [pathsArray objectAtIndex:count];
   
  		// fill the path with the drawing color for this index unless it's selected
  		if( [[self selectionIndexes] containsIndex:count] )
  			[[NSColor blueColor] set];
  		else
  			[[self colorForIndex:count] set];
   
  		[eachPath fill];
   
  		// draw a black border around it
  		[[NSColor blackColor] set];
  		[eachPath stroke];
  	}
   
  	NSArray *textsArray = [self segmentTextsArray];
   
  	for( count = 0; count < [textsArray count]; count++ )
  	{
  		NSDictionary *eachTextDictionary = [textsArray objectAtIndex:count];
  		NSPoint textPoint = NSMakePoint( [[eachTextDictionary valueForKey:@"textPointX"] floatValue], [[eachTextDictionary valueForKey:@"textPointY"] floatValue] );
   
  		NSDictionary *textAttributes = [eachTextDictionary valueForKey:@"textAttributes"];
   
  		NSString *text = [eachTextDictionary valueForKey:@"text"];
  		[text drawAtPoint:textPoint withAttributes:textAttributes];
  	}
  }

Now the view should display the selected segment as desired, updating when the user clicks on a different line in the table view:

If you wish, go into Interface Builder and change the selection type of the table view to ‘Multiple’. You should find that you can shift-click multiple items in the table view and they will show as desired in the chart view.

Resizing Issues

Since we cache the array of segment paths, only updating it when the arrays of data are changed, you might have noticed that the view doesn’t behave very well when we resize it. Assuming you set the view to resize with its window, whilst the white background will enlarge, the actual paths won’t change. This is easy to rectify:

• Simply check in the drawRect: method whether we are in the middle of a ‘liveResize’ and, if so, update the drawing information arrays:

  - (void)drawRect:(NSRect)rect
  {
  	[[NSColor whiteColor] set]; // white background
  	NSRectFill([self bounds]);
   
  	if( [self inLiveResize] )
  	{
  		[self generateDrawingInformation];
  	}
   
  	NSArray *pathsArray = [self segmentPathsArray];
  	unsigned count;
  	for( count = 0; count < [pathsArray count]; count++ )
  	{
  		NSBezierPath *eachPath = [pathsArray objectAtIndex:count];
   
  		// fill the path with the drawing color for this index unless it's selected
  		if( [[self selectionIndexes] containsIndex:count] )
  			[[NSColor blueColor] set];
  		else
  			[[self colorForIndex:count] set];
   
  		[eachPath fill];
   
  		// draw a black border around it
  		[[NSColor blackColor] set];
  		[eachPath stroke];
  	}
   
  	NSArray *textsArray = [self segmentTextsArray];
   
  	for( count = 0; count < [textsArray count]; count++ )
  	{
  		NSDictionary *eachTextDictionary = [textsArray objectAtIndex:count];
  		NSPoint textPoint = NSMakePoint( [[eachTextDictionary valueForKey:@"textPointX"] floatValue], [[eachTextDictionary valueForKey:@"textPointY"] floatValue] );
   
  		NSDictionary *textAttributes = [eachTextDictionary valueForKey:@"textAttributes"];
   
  		NSString *text = [eachTextDictionary valueForKey:@"text"];
  		[text drawAtPoint:textPoint withAttributes:textAttributes];
  	}
  }

The view will now ‘live resize’ itself as would be expected.

Changing the Selection Indexes when the user clicks a Segment

We have already set up the view to display a segment ’selected’ in the table view, but it would be nice if the user could also click on a segment to select it. Given that we store an array of segment paths inside the view, it should be pretty easy to ‘hit-test’ each path to determine which segment was clicked.

• To receive clicks in our view, we need to override the acceptsFirstResponder: method for our view to return YES so add the following to MyPieChartView.m:

  - (BOOL)acceptsFirstResponder
  {
  	return YES;
  }

• Next we’ll implement a method to determine which segment was clicked so add the method declaration to MyPieChartView.h:

  - (int)objectIndexForPoint:(NSPoint)thePoint;

• And implement it in MyPieChartView.m:

  - (int)objectIndexForPoint:(NSPoint)thePoint
  {
  	NSArray *cachedPathsArray = [self segmentPathsArray];
   
  	int count;
  	for( count = 0; count < [cachedPathsArray count]; count++ )
  	{
  		NSBezierPath *eachPath = [cachedPathsArray objectAtIndex:count];
   
  		if( [eachPath containsPoint:thePoint ] )
  		{
  			return count;
  		}
  	}
   
  	// if control reaches here, no segment contained the point so return -1
  	return -1;
  }

• We also need to implement a mouseUp: method that will be called when the user has clicked on a segment. Expected behavior varies depending on whether the user is holding down a modifier key at the time the segment was clicked; holding down the command key should either add or remove the clicked segment to the current selection; holding down the shift key and clicking should select a range of segments between the existing selection and the clicked segment:

  - (void)mouseUp:(NSEvent *)theEvent
  {
  	int index = [self objectIndexForPoint:[self convertPoint:[theEvent locationInWindow] fromView:nil]];
   
  	NSMutableIndexSet *newSelectionIndexes = [[self selectionIndexes] mutableCopy];
   
  	if ( [theEvent modifierFlags] & NSCommandKeyMask )
  	{
  		// Add or remove the clicked segment
  		if ( [newSelectionIndexes containsIndex:index] )
  		{
  			[newSelectionIndexes removeIndex:index];
  		}
  		else
  		{
  			[newSelectionIndexes addIndex:index];
  		}
  	}
  	else if ( [theEvent modifierFlags] & NSShiftKeyMask )
  	{
  		// Add range to selection
  		if ([newSelectionIndexes count] == 0)
  		{
  			[newSelectionIndexes addIndex:index];
  		}
  		else
  		{
  			unsigned int origin = (index < [newSelectionIndexes lastIndex]) ? index :[newSelectionIndexes lastIndex];
  			unsigned int length = (index < [newSelectionIndexes lastIndex]) ? [newSelectionIndexes lastIndex] - index : index - [newSelectionIndexes lastIndex];
   
  			length++;
  			[newSelectionIndexes addIndexesInRange:NSMakeRange(origin, length)];
  		}
  	}
  	else // the user just clicked without modifier keys so simply select the segment
  	{
  		[newSelectionIndexes removeAllIndexes];
  		if( index >= 0 )
  			[newSelectionIndexes addIndex:index];
  	}
   
  	[self setSelectionIndexes:newSelectionIndexes];
  	[newSelectionIndexes release];
  }

• Finally we need to bind the selectionIndexes of our view to the selectionIndexes of the array controller so that it updates the table view as well. Add this last binding in MyDocument.m:

  - (void)windowControllerDidLoadNib:(NSWindowController *)windowController
  {
  	[super windowControllerDidLoadNib:windowController];
   
  	[pieChartView bind:@"segmentNamesArray" toObject:segmentsArrayController withKeyPath:@"arrangedObjects.name" options:nil];
  	[pieChartView bind:@"segmentValuesArray" toObject:segmentsArrayController withKeyPath:@"arrangedObjects.amount" options:nil];
  	[pieChartView bind:@"selectionIndexes" toObject:segmentsArrayController withKeyPath:@"selectionIndexes" options:nil];
  	[segmentsArrayController bind:@"selectionIndexes" toObject:pieChartView withKeyPath:@"selectionIndexes" options:nil];
  }

When the user clicks on a segment in our chart view, that segment should become selected and also change the selection in the table view; modifier keys should also affect the way that segments become selected.

One Last Binding

Just in case you haven’t had enough bindings yet, we’ll add one final feature to the view – the ability to rotate the chart, perhaps so the user can better fit the related text or place one segment in the middle etc.

• We’ll start by adding a ‘rotationAmount’ attribute to our view, along with the necessary accessors in MyPieChartView.h:

  @interface MyPieChartView : NSView
  {
  	NSArray *_segmentNamesArray;
  	NSArray *_segmentValuesArray;
   
  	NSMutableArray *_segmentPathsArray;
  	NSMutableArray *_segmentTextsArray;
   
  	NSIndexSet *_selectionIndexes;
   
  	float _rotationAmount;
  }
   
  - (NSArray *)segmentNamesArray;
  - (void)setSegmentNamesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentValuesArray;
  - (void)setSegmentValuesArray:(NSArray *)newArray;
   
  - (NSArray *)segmentPathsArray;
  - (NSArray *)segmentTextsArray;
  - (void)generateDrawingInformation;
   
  - (NSColor *)randomColor;
  - (NSColor *)colorForIndex:(unsigned)index;
   
  - (NSIndexSet *)selectionIndexes;
  - (void)setSelectionIndexes:(NSIndexSet *)newIndexes;
   
  - (int)objectIndexForPoint:(NSPoint)thePoint;
   
  - (void)setRotationAmount:(NSNumber *)value;
  - (NSNumber *)rotationAmount;
   
  @end

• Expose the binding for the rotationAmount attribute and add the accessor methods to MyPieChartView.m:

  + (void)initialize
  {
  	[self exposeBinding:@"segmentNamesArray"];
  	[self exposeBinding:@"segmentValuesArray"];
  	[self exposeBinding:@"selectionIndexes"];
  	[self exposeBinding:@"rotationAmount"];
  }
   
  - (void)setRotationAmount:(NSNumber *)value
  {
  	if( [value floatValue] != _rotationAmount )
  	{
  		[self willChangeValueForKey:@"rotationAmount"];
  		_rotationAmount = [value floatValue];
  		[self didChangeValueForKey:@"rotationAmount"];
   
  		[self generateDrawingInformation];
  		[self setNeedsDisplayInRect:[self visibleRect]];
  	}
  }
   
  - (NSNumber *)rotationAmount
  {
  	return [NSNumber numberWithFloat:_rotationAmount];
  }

• To make use of the rotation amount, we simply need to modify our drawing code to set the ‘currentDegree’ to the rotation amount so find and change this in generateDrawingInformation::

  	// cycle through the segmentValues and create the bezier paths
  	// Also add the text details (note we expect the texts' indexes to tie up with the values' indexes)
  	float currentDegree = [[self rotationAmount] floatValue];
  	unsigned currentIndex;

• Next we need to have a control to rotate the graph so open up MyDocument.xib in InterfaceBuilder and add a horizontal slider control; set its minimum and maximum values to 0.0 and 360.0, and its current value to 0.0; tick the ‘Continuous’ box in the inspector. My interface looks like this:
  
• Back in Xcode, add an IBOutlet for the new slider to MyDocument.h:

  @interface MyDocument : NSPersistentDocument
  {
  	IBOutlet NSArrayController *segmentsArrayController;
  	IBOutlet NSView *pieChartView;
  	IBOutlet NSSlider *sliderRotationControl;
  }
   
  @end

• Connect the outlet to the control in Interface Builder.
• In MyDocument.m, bind the rotation control’s value to the rotationAmount on the chart view:

  - (void)windowControllerDidLoadNib:(NSWindowController *)windowController
  {
  	[super windowControllerDidLoadNib:windowController];
   
  	[pieChartView bind:@"segmentNamesArray" toObject:segmentsArrayController withKeyPath:@"arrangedObjects.name" options:nil];
  	[pieChartView bind:@"segmentValuesArray" toObject:segmentsArrayController withKeyPath:@"arrangedObjects.amount" options:nil];
  	[pieChartView bind:@"selectionIndexes" toObject:segmentsArrayController withKeyPath:@"selectionIndexes" options:nil];
  	[segmentsArrayController bind:@"selectionIndexes" toObject:pieChartView withKeyPath:@"selectionIndexes" options:nil];
  	[sliderRotationControl bind:@"value" toObject:pieChartView withKeyPath:@"rotationAmount" options:nil];
  }

That’s It!

At this point you should have a pretty functional, bindable pie-chart view. For such a view it would make sense to create an Interface Builder palette so that the bindings can be setup visually in Interface Builder rather having to do it programmatically; this may well be a topic for a future post!

If you are someone who happily binds Array Controllers and View objects together using Interface Builder but have always wondered discretely exactly how the magic behind the scenes happens, or if you just don’t quite comprehend the difference between ‘KVC’ and ‘KVO’ (or perhaps can never quite remember what they stand for…), this article might help you out. In it, I’ll attempt to demonstrate a ‘faux-bindings’ methodology that connects a value from one object with a value from another object, but without using the actual Apple Cocoa Bindings technology. The bare-bones of how the ‘faux binding’ works will be there for all to see; while the internal workings of Cocoa Bindings are a little different, this will hopefully at least show you what, how and why certain things are required for the real Cocoa Bindings to work successfully.

Basic Principles

The simple premise of our ‘faux-bindings’ technology is that we link two objects together such that when a certain value changes in the first, the other changes its linked value to match. One way to accomplish this would be to have the objects (A and B) maintain links to each other such that when object A’s value changes, A can call a method on object B to update B’s value. This is all very well for two simple objects working in one direction but if you have multiple objects all bound together, each with a link to all the others, things can quickly become complicated, leak memory all over the place, and be difficult to maintain.

Notifications

Notifications are another wonderful, often underused, technology that allow communication between objects without those objects knowing anything about each other. Using a Notification Center, objects (e.g. objects B and C) can request notifications when specified types of messages are posted by other objects (e.g. object A). So, when object A decides to post a message, the notification center looks at the list of objects who want to receive such messages, and goes and tells those objects B and C that object A posted a notification. If object A is later released from memory but B and C are still listening for notifications, it doesn’t matter — they maintain no direct link to object A so they simply go on waiting without receiving anything. Similarly, if object C is released before object A posts a notification, again it doesn’t matter — A has no knowledge or worry about who receives the notifications as they go through a third party, a notification center.

To post a notification, an object can simply do this:

	[[NSNotificationCenter defaultCenter] postNotificationName:@"helloIChanged" object:self];

This tells the default notification center (helpfully already created ready for you to use so you don’t need to worry about it) to distribute the ‘helloIChanged’ notification to anyone who listens for it.

To specify that you want to listen for such a notification, you can do this:

	[[NSNotificationCenter defaultCenter] addObserver:self
	                                         selector:@selector(receivedNotification:)
	                                             name:@"helloIChanged"
	                                           object:nil];

This code tells the notification center that you want to receive all ‘helloIChanged’ notifications, and when such a notification is received, your receivedNotification: method should be called. The object parameter of this method allows you to specify that you only want to receive notifications from a single object instance rather than from any object. If you wished, you could say “name:nil” but instead limit your interest to a specific object so that any notification posted by that object (e.g. @”helloIChanged” or @”helloSomethingElseHappened”) would cause the notification centre to call your receivedNotification: method.

The Sample Project

We’re going to create a very simple sample project for this article. If you wish to download some sample code for our Faux Binding, you can do so from here: fauxbindings.zip.

• In Xcode, create a new ‘Cocoa Application’ project called ‘FauxBindings’.
• Right-click on the ‘Classes’ group and Add -> New File… to add a basic Objective-C class file called “BindController.m”; make sure the ‘Also create “BindController.h”‘ box is ticked, and click Finish. If you don’t have a two-button mouse, read ‘right-click’ as ‘CTRL-click’ throughout this article.
• We are going to need an IBOutlet for an NSTextField and a NSString object. We’re also going to need an IBAction method to display the string using NSLog(). So, make your BindController.h file look like this:

  #import <cocoa/Cocoa.h>
   
   
  @interface BindController : NSObject {
   
  	IBOutlet NSTextField *theTextField;
   
  	NSString *theString;
  }
   
  - (IBAction)showTheStringInLog:(id)sender;
   
  @end

• Next open MainMenu.nib in Xcode and open up the ‘Window’ object. Add an NSTextField and an NSButton called ‘Log theString’ so that it looks something like this:
  
  Not the most exciting window ever created but functional enough for this demonstration.
• From the Interface Builder Library tool drag out an NSObject (that’s the blue cube thing) into your MainMenu.nib window. Click this object and in the Inspector, use the Identity tab to specify that the object’s class is BindController. By adding a BindController object in this way to our nib file, an instance of the BindController class will be created when the nib is loaded; there is no other code anywhere in the project that does a [[BindController alloc] init] etc. It’s all handled for you.
• Next right-click on the cube and connect its theTextField outlet to our text field in the window, and connect the showTheStringInLog: method to the “Log theString” button:
  
• Return now to Xcode and open up the BindController.m class file. We need to add the code for the showTheStringInLog: method so write that now:

  #import "BindController.h"
   
   
  @implementation BindController
   
  - (IBAction)showTheStringInLog:(id)sender
  {
  	NSLog(@"Value of theString is: %@", theString);
  }
   
  @end

• Make sure the Console window is open (listed under the ‘Run’ menu, or CMD-SHIFT-R) and then build and run your application. Press the button. No surprises here, you’ll see that the “Value of theString is: (null)” because we haven’t set theString to anything yet.

Establishing a Link

Now we need to setup a FauxBind: method that can be used to link a specified value of one object to a specified value on another. We’ll use it to link the stringValue on the text field to our BindController’s theString object. We need to call this method when the application first loads so that the faux bindings are ready for the user input.

• Go back to Interface Builder and click on the Application object in the nib file. Use the Connections Inspector panel to connect the ‘delegate’ outlet to the Bind Controller object. This will allow our object to respond to the ‘awakeFromNib’ method that is called when the application has loaded the nib file into memory.
• Open BindController.h in Xcode and add two objects to the controller – we’ll need an originatingObject and a destinationObject, together with two strings for that hold the names of the values to which we’ll be binding. Also add a FauxBind: method that will set up our faux binding between those objects. Finally, we’ll be using notifications so declare a method to be called when a notification is received:

  #import <cocoa/Cocoa.h>
   
   
  @interface BindController : NSObject {
   
  	IBOutlet NSTextField *theTextField;
   
  	NSString *theString;
   
  	id originatingObject;
  	NSString *originatingValueName;
  	id destinationObject;
  	NSString *destinationValueName;
  }
   
  - (IBAction)showTheStringInLog:(id)sender;
   
  - (void)FauxBindObject:(id)destObject valueName:(NSString *)destValueName toObject:(id)origObject valueName:(NSString *)origValueName;
   
  - (void)receivedNotification:(NSNotification *)notification;
   
  @end

• Next open BindController.m and add an awakeFromNib: method after the showTheStringInLog: method. This method says we’re going to bind a value called “theString” in our own object, to a value called “stringValue” on theTextField:

  - (void)awakeFromNib
  {
  	[self FauxBindObject:self valueName:@"theString" toObject:theTextField valueName:@"stringValue"];
  }

• We can also write the first steps of this faux bind method. Initially, let’s just see what notifications are being posted by theTextField and log them to the console:

  - (void)FauxBindObject:(id)destObject valueName:(NSString *)destValueName toObject:(id)origObject valueName:(NSString *)origValueName
  {
  	[[NSNotificationCenter defaultCenter] addObserver:self
  	                                         selector:@selector(receivedNotification:)
  	                                             name:nil
  	                                           object:origObject];
   
  	originatingObject = origObject;
  	originatingValueName = origValueName;
  	destinationObject = destObject;
  	destinationValueName = destValueName;
  }

• And, of course, we need to code the receivedNotification: method that is called when a notification is received; here we’ll simply log the whole notification to the console so that we can examine its contents:

  - (void)receivedNotification:(NSNotification *)notification
  {
  	NSLog(@"Received a notification: %@", notification);
  }

• Again, make sure the console is visible, then build and run the application.

When you click, type and tab out of the text field, you’ll see a whole string of messages sent to the console, indicating a whole chain of notifications. You’ll see an NSControlTextDidBeginEditingNotification at the start, then an NSControlTextDidChangeNotification sent every time the text changed, then (assuming you pressed tab or enter to commit the text field), you’ll see an NSControlTextDidEndEditingNotification.

We want our theString value to change when the text field value is committed by the user pressing tab or enter so:

• Change the FauxBindObject: method to listen only for NSControlTextDidEndEditingNotifications:

  - (void)FauxBindObject:(id)destObject valueName:(NSString *)destValueName toObject:(id)origObject valueName:(NSString *)origValueName
  {
  	[[NSNotificationCenter defaultCenter] addObserver:self
  	                                         selector:@selector(receivedNotification:)
  	                                             name:NSControlTextDidEndEditingNotification
  	                                           object:origObject];
   
  	originatingObject = origObject;
  	originatingValueName = origValueName;
  	destinationObject = destObject;
  	destinationValueName = destValueName;
  }

• This time when you build and run, you’ll see that we only receive a notification when the text field commits editing on return or tab.

Having found out when the originating object changes, we need to be able to obtain the value of that object before updating the value of the destination object.

A Note about Selectors

Feel free to skip this part but it might be helpful to know a little about method calls in Objective-C. An in-depth discussion about the way that Objective-C handles such method calls between objects is outside the scope of this article. But, if you are comfortable with bog-standard C or C++, you will know all about functions. Functions look something like this FunctionName( variable1, variable2). When you call a method in Objective-C with code like this: [self doSomethingWith:anObject], the compiler is actually translating this method call into a call to the objc_msgSend() function. This function takes arguments that specify which ‘object’ is receiving the method call, and a ’selector’ which specifies the name of a method that is being called.

A discussion of how selectors work is again outside the scope of this article but hold in your mind that the messaging function finds out which methods you’re calling (and the calls to those methods) at runtime. This means your code can also refer to methods ‘indirectly’ by using selectors, perhaps in order to find out information about them. We used a selector earlier in our call to register for notifications, saying that our ‘receivedNotification:’ method should be called. There is a method on any NSObject subclass called ‘respondsToSelector:’ which makes it possible to find out whether an object responds to a particular selector (aka method). So, let’s assume for now that the Notification Center will ask our object to make sure it can actually receive the method call we specified. It is then also possible to actually call a method using a selector with the ‘performSelector:’ NSObject method. This functionality is all provided to any object that subclasses NSObject.

Thinking about the Notification Center example, it might do the following when it needs to tell our object that a notification was received:

	if( [object respondsToSelector:@selector(receivedNotification:)] )
	{
		// then actually call the selector
		[object performSelector:@selector(receivedNotification:) withObject:theNotification];
	}

Lastly, you can use a function NSSelectorFromString() to get hold of a selector from a string specifying its name, so the code above could also be written:

	if( [object respondsToSelector:NSSelectorFromString(@"receivedNotification")] )
	{
		// then actually call the selector
		[object performSelector:NSSelectorFromString(@"receivedNotification") withObject:theNotification];
	}

For more information on messaging and selectors, see: Apple Developer Connection: How Messaging Works.

With our short discussion of selectors out of the way, we can now start writing the code to handle accessing and setting our bound values.

Getters and Setters

Our receivedNotification: method is being called now whenever our originating object changes. We can modify that method so that it tries to find out the specified value of the object. To get the value, we need to call a suitable method on the originating object that will return to us that current value. The most sensible name for such a method would be a method with the same name as the name of the value — in other words, if an object has a ’someValue’ internal value, you could call:

	id theValue = [object someValue];

to find out that value.

On this assumption then, our method needs to find out whether our originating object responds to a method with the name of the originating value name and, if so, call that method to acquire the current value.

• Open BindController.m in Xcode and modify your receivedNotification: method to look like the following:

  - (void)receivedNotification:(NSNotification *)notification
  {
  	NSLog(@"Received a notification that an object changed");
   
  	if( [notification object] == originatingObject )
  	{
  		NSLog(@"Originating Value to fetch is: %@", originatingValueName);
   
  		// see if there is a method to fetch this value name
  		NSString *getterMethodName = originatingValueName;
  		id fetchedValue = nil;
  		NSLog(@"Originating Method to test is: %@", getterMethodName);
   
  		if( [originatingObject respondsToSelector:NSSelectorFromString(getterMethodName)] )
  		{
  			NSLog(@"Originating Object responds to: %@", getterMethodName);
  			fetchedValue = [originatingObject performSelector:NSSelectorFromString(getterMethodName)];
  			NSLog(@"Fetched value is: %@", fetchedValue);
  		}
  		else
  		{
  			NSLog(@"Originating Object is not KVC compliant for the value: %@", originatingValueName);
  			return;
  		}
  	}
  }

If you examine this code, you’ll see that we are first of all checking to make sure that the notification we are receiving has come from the object in which we are interested. We then look at the string containing the name of the value we want, and ask our originating object whether it responds to a method with the name of that value. Assuming it does, we fetch the value by calling that method.

Build and run the project and type something in the text field before pressing tab or enter. You’ll see in the console log all the various steps above and if everything goes to plan, you should see something like:

2008-08-27 14:33:26.756 FauxBindings[2411:10b] Received a notification that an object changed
2008-08-27 14:33:26.761 FauxBindings[2411:10b] Originating Value to fetch is: stringValue
2008-08-27 14:33:26.785 FauxBindings[2411:10b] Originating Method to test is: stringValue
2008-08-27 14:33:26.805 FauxBindings[2411:10b] Originating Object responds to: stringValue
2008-08-27 14:33:26.823 FauxBindings[2411:10b] Fetched value is: something

KVC Compliance

You’ll notice in the above code that if an object doesn’t respond to our suspected getter method name, we log a message to the console that the object isn’t KVC compliant for that value. To test this, change the call in the awakeFromNib: method to something like this:

- (void)awakeFromNib
{
	[self FauxBindObject:self valueName:@"theString" toObject:theTextField valueName:@"anUnknownValue"];
}

When you run the application and modify the text field, you’ll see that the object doesn’t respond to a method called ‘anUnknownValue‘ and so we can’t acquire that value.

KVC stands for Key-Value-Coding; what this means is that an object provides suitably named methods to access its values. In the above example, we ask our theTextField for the value named “anUnknownValue”. This ‘value name’ is also referred to as a ‘key’ so it would be best to say:

“We ask our theTextField object for the value of its “anUnknownValue” key”

For an object to be KVC-compliant for a particular key, it must provide methods to access the value of the key that can be worked out given the name of that key. This generally means that a ‘getter’ method is given the same name as the name of the key (as in “stringValue”). There are other possibilities too; it might make sense for a Boolean (true/false) value called “onWatchList” to be accessed using an accessor “isOnWatchList” and in full-blown Cocoa bindings, there are various options you can use when naming accessor methods. For the purposes of this article, however, we won’t include checking for those other options in our FauxBind: method.

The other half of KVC-compliance is that an object provide a suitably-named ’setter’ method, i.e. a method to set the value of its key. Although there are again various options, this generally means that you put the word ’set’ at the front of the name of the key and correct the capitalization such that for a value “stringValue”, the setter would be “setStringValue”.

With this knowledge, we can go about changing the receivedNotifiction: method to try and set the value of the key on the destination object using a KVC setter method.

• If you changed the “stringValue” key above to “anUnknownValue” etc then change it back now:

  	[self FauxBindObject:self valueName:@"theString" toObject:theTextField valueName:@"stringValue"];

• Modify the receivedNotification: method to the following:

  - (void)receivedNotification:(NSNotification *)notification
  {
  	NSLog(@"Received a notification that an object changed");
   
  	if( [notification object] == originatingObject )
  	{
  		NSLog(@"Key to fetch is: %@", originatingValueName);
   
  		// see if there is a method to fetch this value name
  		NSString *getterMethodName = originatingValueName;
  		id fetchedValue = nil;
  		NSLog(@"Originating Method to test is: %@", getterMethodName);
   
  		if( [originatingObject respondsToSelector:NSSelectorFromString(getterMethodName)] )
  		{
  			NSLog(@"Originating Object responds to: %@", getterMethodName);
  			fetchedValue = [originatingObject performSelector:NSSelectorFromString(getterMethodName)];
  			NSLog(@"Fetched value for key is: %@", fetchedValue);
  		}
  		else
  		{
  			NSLog(@"Originating Object is not KVC compliant for the key: %@", originatingValueName);
  			return;
  		}
   
   
  		NSLog(@"\n");
   
  		NSLog(@"Destination's Key to change is: %@", destinationValueName);
   
  		// see if there is a method to change this value name
  		NSString *setterMethodNameFirstCharacter = [destinationValueName substringToIndex:1];
  		NSString *setterMethodName = [NSString stringWithFormat:@"set%@%@:", [setterMethodNameFirstCharacter capitalizedString], [destinationValueName substringFromIndex:1]];
   
  		NSLog(@"Destination Method to test is: %@", setterMethodName);
   
  		if( [destinationObject respondsToSelector:NSSelectorFromString(setterMethodName)] )
  		{
  			NSLog(@"Destination Object responds to: %@", setterMethodName);
   
  			[destinationObject performSelector:NSSelectorFromString(setterMethodName) withObject:fetchedValue];
  		}
  		else
  		{
  			NSLog(@"Destination Object is not KVC complicant for the value: %@", destinationValueName);
  		}
  	}
  }

The additional code above now uses various NSString methods to get a suitable setter method name string by putting the word “set” on the front of the key name, which in turn has had its first letter capitalized.

If you run the application now, you’ll see the following:

2008-08-27 15:09:30.464 FauxBindings[2587:10b] Received a notification that an object changed
2008-08-27 15:09:30.467 FauxBindings[2587:10b] Key to fetch is: stringValue
2008-08-27 15:09:30.482 FauxBindings[2587:10b] Originating Method to test is: stringValue
2008-08-27 15:09:30.494 FauxBindings[2587:10b] Originating Object responds to: stringValue
2008-08-27 15:09:30.498 FauxBindings[2587:10b] Fetched value for key is: something
2008-08-27 15:09:30.499 FauxBindings[2587:10b]
2008-08-27 15:09:30.502 FauxBindings[2587:10b] Destination's Key to change is: theString
2008-08-27 15:09:30.503 FauxBindings[2587:10b] Destination Method to test is: setTheString:
2008-08-27 15:09:30.504 FauxBindings[2587:10b] Destination Object is not KVC complicant for the value: theString

The method is trying to set the value for the ‘theString’ key but fails because our BindController object isn’t KVC compliant for the ‘theString’ key — which is because we haven’t implemented a ’setTheString’ method in our BindController object. Let’s do that now:

• In BindController.h, add a method declaration for the ’setTheString’ method:

  #import <cocoa/Cocoa.h>
   
   
  @interface BindController : NSObject {
   
  	IBOutlet NSTextField *theTextField;
   
  	NSString *theString;
   
  	id originatingObject;
  	NSString *originatingValueName;
  	id destinationObject;
  	NSString *destinationValueName;
  }
   
  - (IBAction)showTheStringInLog:(id)sender;
   
  - (void)FauxBindObject:(id)destObject valueName:(NSString *)destValueName toObject:(id)origObject valueName:(NSString *)origValueName;
   
  - (void)receivedNotification:(NSNotification *)notification;
   
  - (void)setTheString:(NSString *)value;
   
  @end

• Implement this method in BindController.m with the following code:

  - (void)setTheString:(NSString *)value
  {
  	NSLog(@"Setting theString to value: %@", value);
  	theString = value;
  }

Now when you run the application, press the ‘Log theString’ button before doing anything else, then type something in the text box and press enter, then press the ‘Log theString’ button again. If all has gone to plan, you’ll have seen the following in the Console:

2008-08-27 15:20:41.207 FauxBindings[2652:10b] Value of theString is: (null)
2008-08-27 15:20:44.022 FauxBindings[2652:10b] Received a notification that an object changed
2008-08-27 15:20:44.023 FauxBindings[2652:10b] Key to fetch is: stringValue
2008-08-27 15:20:44.034 FauxBindings[2652:10b] Originating Method to test is: stringValue
2008-08-27 15:20:44.040 FauxBindings[2652:10b] Originating Object responds to: stringValue
2008-08-27 15:20:44.045 FauxBindings[2652:10b] Fetched value for key is: something
2008-08-27 15:20:44.064 FauxBindings[2652:10b]
2008-08-27 15:20:44.070 FauxBindings[2652:10b] Destination's Key to change is: theString
2008-08-27 15:20:44.074 FauxBindings[2652:10b] Destination Method to test is: setTheString:
2008-08-27 15:20:44.085 FauxBindings[2652:10b] Destination Object responds to: setTheString:
2008-08-27 15:20:44.086 FauxBindings[2652:10b] Setting theString to value: something
2008-08-27 15:20:45.222 FauxBindings[2652:10b] Value of theString is: something

Finally, we have a working binding between our text field’s stringValue key and our BindController object’s theString key. When the text field posts the notification that its value has changed, the value of our theString key is updated to match the new stringValue value.

Reversing the Process

Let’s see if we can get this working the other way around. In other words, can we get our theTextField object to update its stringValue when our BindController object’s theString is changed?

• First of all, change the awakeFromNib: method so that the binding happens the other way around:

  - (void)awakeFromNib
  {
  	[self FauxBindObject:theTextField valueName:@"stringValue" toObject:self valueName:@"theString"];
  }

• Next, we’ll change the user interface so that we can specify a value for theString and see what happens. Open up BindController.h and add another IBOutlet for an NSTextField. Also add a method to be called to set theString to the value of the text field:

  #import <cocoa/Cocoa.h>
   
   
  @interface BindController : NSObject {
   
  	IBOutlet NSTextField *theTextField;
  	IBOutlet NSTextField *secondTextField;
   
  	NSString *theString;
   
  	id originatingObject;
  	NSString *originatingValueName;
  	id destinationObject;
  	NSString *destinationValueName;
  }
   
  - (IBAction)showTheStringInLog:(id)sender;
   
  - (void)FauxBindObject:(id)destObject valueName:(NSString *)destValueName toObject:(id)origObject valueName:(NSString *)origValueName;
   
  - (void)receivedNotification:(NSNotification *)notification;
   
  - (void)setTheString:(NSString *)value;
   
  - (IBAction)modifyTheStringToValueOfTextField:(id)sender;
   
  @end

• Open MainMenu.nib in Interface Builder and add a second text field along with a second button, and connect these to the new outlet and action. My interface looks like this:
  
• Return to Xcode and open BindController.m, adding in the implementation for the modifyTheStringToValueOfTextField: method:

  - (IBAction)modifyTheStringToValueOfTextField:(id)sender
  {
  	[self setTheString:[secondTextField stringValue]];
  }

Notice that we set the value of ‘theString’ using the KVC setter method and not directly. Why we do this will become clear in a minute…

If at this point you build and run the application, you’ll find that nothing happens at all when you enter text in the second field and click the button other than a console log that theString was set to a new value. Why doesn’t the supposedly-bound text field update to match the new value of theString? Because no notification is ever sent that its value changed.

• Change the setTheString: method to the following:

  - (void)setTheString:(NSString *)value
  {
  	NSLog(@"Setting theString to value: %@", value);
  	theString = value;
  	[[NSNotificationCenter defaultCenter] postNotificationName:NSControlTextDidEndEditingNotification object:self];
  }

Now, when you type something in the second text field (and press enter to commit it), then click the button, our notification method tries to obtain the new value of theString but complains that our BindController object is not KVC compliant for theString:

2008-08-27 15:48:19.487 FauxBindings[2869:10b] Setting theString to value: something
2008-08-27 15:48:19.494 FauxBindings[2869:10b] Received a notification that an object changed
2008-08-27 15:48:19.514 FauxBindings[2869:10b] Key to fetch is: theString
2008-08-27 15:48:19.521 FauxBindings[2869:10b] Originating Method to test is: theString
2008-08-27 15:48:19.523 FauxBindings[2869:10b] Originating Object is not KVC compliant for the key: theString

Why? Because there is no getter method defined in the BindController object.

• Open BindController.h and add a declaration for the getter method underneath its setter declaration:

  - (NSString *)theString;

• Implement this method in BindController.m thus:

  - (NSString *)theString
  {
  	return theString;
  }

This time when you run the application, you should find that everything functions as expected. Type something in the second field, press enter and then press the button. The first text field updates its content to match.

This is where the KVO comes from — standing for Key-Value-Observing. For an object to allow Observation of its Key Values, its setter methods must announce when they are changing a particular value so that notifications can be picked up and changes propagated.

One more Check

Just one final way to demonstrate that this functionality works is to modify the awakeFromNib: method to connect the two text fields directly.

• Modify awakeFromNib: to this:

  - (void)awakeFromNib
  {
  	[self FauxBindObject:secondTextField valueName:@"stringValue" toObject:theTextField valueName:@"stringValue"];
  }

This time, if you type something in the first text field and press enter, the second text field will change its value; note that there is no BindController theString value changing here, it’s only the two text fields. If you want the first text field to update when the second changes too, you would have to initiate that binding separately.

Starting to Replace Code

Assuming that an object is KVC-compliant (remember, that’s when it has suitably named accessors), you can access a named value (key) from that object by using the method valueForKey: and set it using setValue:forKey:. These methods perform all the necessary magic to find out if an object has KVC accessors and, assuming they do, call them to access the values.

• We can simplify our receivedNotification: method somewhat by changing it to the following:

  - (void)receivedNotification:(NSNotification *)notification
  {
  	NSLog(@"Received a notification that an object changed");
   
  	if( [notification object] == originatingObject )
  	{
  		NSLog(@"Key to fetch is: %@", originatingValueName);
   
  		id fetchedValue = [originatingObject valueForKey:originatingValueName];
   
  		NSLog(@"Destination's Key to change is: %@", destinationValueName);
   
  		[destinationObject setValue:fetchedValue forKey:destinationValueName];
  	}
  }

If you run using this code, you’ll see that everything happens as before, only we’re using the valueForKey: and setValue:forKey: methods instead of our previous logic.

Proper KVO

You’ll remember that earlier we ‘faked’ an NSControlTextDidEndEditing notification to force our demonstration to work when our theString key was modified — whilst not being problematic in this particular demonstration, it’s not good practice to post notifications that aren’t legitimate. It would be better in this case to post a “theStringValueDidChange” notification that is more suitably named (and, if you did this, you’d obviously also need to change the notification registration code to specify the new notification type that the object was hoping to receive).

For information on naming conventions for notifications (and other things), see: Apple Developer Connection : Naming Instance Variables and Data Types.

In a real bindings scenario, you use two methods willChangeValueForKey: and didChangeValueForKey: to tell the bindings mechanism that suitable notifications should be sent out. Our setTheString: method should really look like this:

- (void)setTheString:(NSString *)value
{
	[self willChangeValueForKey:@"theString"];
	NSLog(@"Setting theString to value: %@", value);
	theString = value;
	[self didChangeValueForKey:@"theString"];
}

Again, these methods are available to any subclass of NSObject.

When writing Core Data NSManagedObject subclasses, you’ll find that you also need to use willAccessValueForKey: and didAccessValueForKey: in your getter accessor methods — these inform the managed object that it needs to fetch the relevant data from the store if necessary.

Real Bindings

Now that we know what’s going on behind the scenes, let’s change our sample application to use real bindings rather than our faux bindings.

• First off, our BindController object now doesn’t need to do anything about notifications so we can remove the methods that handle them. We’ll also take out the second text field and button methods. Change the BindController.h file to the following:

  #import <cocoa/Cocoa.h>
   
   
  @interface BindController : NSObject {
   
  	IBOutlet NSTextField *theTextField;
   
  	NSString *theString;
  }
   
  - (IBAction)showTheStringInLog:(id)sender;
   
  - (void)setTheString:(NSString *)value;
  - (NSString *)theString;
   
  @end

• In Interface Builder, remove the second text field and button from the Window.
• We also need to remove the unused methods from BindController.m and modify our awakeFromNib: method to use proper Cocoa Bindings. Change the file to the following:

  #import "BindController.h"
   
   
  @implementation BindController
   
  - (IBAction)showTheStringInLog:(id)sender
  {
  	NSLog(@"Value of theString is: %@", theString);
  }
   
  - (void)awakeFromNib
  {
  	[theTextField bind:@"value" toObject:self withKeyPath:@"theString" options:nil];
  }
   
  - (void)setTheString:(NSString *)value
  {
  	[self willChangeValueForKey:@"theString"];
  	NSLog(@"Setting theString to value: %@", value);
  	theString = value;
  	[self didChangeValueForKey:@"theString"];
  }
   
  - (NSString *)theString
  {
  	return theString;
  }
   
  @end

In the awakeFromNib: method, we bind the text field’s value to our theString key. All the magic is handled for us and the application behaves as expected — typing text in the text field and pressing enter will update theString.

To be able to do this the other way around using Cocoa Bindings (i.e. change the value of the text field when theString changes), you need to make a further modification.

• Change the BindController.m file to the following:

  #import "BindController.h"
   
   
  @implementation BindController
   
  + (void)initialize
  {
  	[self exposeBinding:@"theString"];
  }
   
  - (IBAction)showTheStringInLog:(id)sender
  {
  	NSLog(@"Value of theString is: %@", theString);
  }
   
  - (void)awakeFromNib
  {
  	[self bind:@"theString" toObject:theTextField withKeyPath:@"stringValue" options:nil];
  }
   
  - (void)setTheString:(NSString *)value
  {
  	[self willChangeValueForKey:@"theString"];
  	NSLog(@"Setting theString to value: %@", value);
  	theString = value;
  	[self didChangeValueForKey:@"theString"];
  }
   
  - (NSString *)theString
  {
  	return theString;
  }
   
  @end

You’ll notice that there is also now an ‘initialize’ class method. If you’re not sure what this means, a class method is one that is called on a class rather than an instance of that class and is designated as such with a ‘+’ in front of the method declaration rather than a ‘-’. The + (void)initialize method can be called like this:

	[BindController initialize];

whereas - (void)awakeFromNib, for example, must be called on an instance of the object like this:

	BindController *bcInstance = [[BindController alloc] init];
	[bcInstance awakeFromNib];

(and yes, there’s a memory leak just in that little code snippet — “if you’re alloc-initing, you should be releasing” [or "auto-releasing"...])

The +initialize method is called before any instances of our object are used in code so that features of the class are known for the future; here we’re exposing the fact that our BindController object has a bindable key called ‘theString’.

In the awakeFromNib: method, we then actually bind this bindable key to the stringValue key on our text field.

If you build and run the application with the binding set up this way round, obviously you’ll find that changing the value of the text field doesn’t have any effect on our theString key. But, remember earlier in this article that when our theString attribute hadn’t yet been initialized to any value, the ‘Log theString’ button would cause a ‘Value of theString is: (null)’ to be displayed. This time, however, if you click the button, you’ll find that it outputs ‘Value of theString is: ‘ with a blank string (@”" in object terms) as the value (and indeed, outputs this to the console when you first run the application). You might like to philosophize to yourself about where that comes from…

Things to Note

There are a few further points worth noting from all this:

• You could bind to the BindController ‘theString’ key from another object rather than in the BindController’s awakeFromNib: method since its binding is ‘exposed’. For example:

  	NSTextField *someTextField = //get a text field from somewhere
  	BindController *bcInstance = [[BindController alloc] init];
   
  	[someTextField bind:@"stringValue" toObject:bcInstance withKeyPath:@"theString" options:nil];

• The name of the attribute that holds a value does not need to be the same as the key for that value. It is common practice to follow a different naming convention for attributes that are in the interface for the class rather than attributes allocated inside methods, one example being to put an underscore character on the front of class attributes. Storage of the value for our theString key could be done like this:

  - (void)setTheString:(NSString *)value
  {
  	[self willChangeValueForKey:@"theString"];
  	NSLog(@"Setting theString to value: %@", value);
  	_theString = value;
  	[self didChangeValueForKey:@"theString"];
  }
   
  - (NSString *)theString
  {
  	return _theString;
  }

• There are various other features in KVC and KVO that I haven’t discussed here such as if one key’s value depends on another key’s value, you can specify using another class method of the form keyPathsForValuesAffecting... such that if that depended-upon value changes, the Bindings mechanism will automatically notify objects bound to your dependent key of the change. Consider the following example where there is a second string key value exposed to which objects can bind called “dependentString”. It simply returns a modified version of theString so if an object is bound to that and theString changes, they need to be told so that they can request the new version of dependentString, all of which is accomplished quite simply, like this:

  - (void)setTheString:(NSString *)value
  {
  	[self willChangeValueForKey:@"theString"];
  	NSLog(@"Setting theString to value: %@", value);
  	_theString = value;
  	[self didChangeValueForKey:@"theString"];
  }
   
  - (NSString *)theString
  {
  	return _theString;
  }
   
  - (NSString *)dependentString
  {
  	return [[self theString] stringByAppendingString:@" Plus Something Else"];
  }
  // note dependentString has no setter
   
  + (NSSet *)keyPathsForValuesAffectingDependentString
  {
  	return [NSSet setWithObject:@"theString"];
  }

• There are also various validation methods that, if they exist, can be called automatically to make sure that a value is suitable before allowing it to be set for a particular key. See Apple Developer Connection : KVC Key-Value Validation for more details but here is a small example:

  - (BOOL)validateTheString:(id *)valueRef error:(NSError **)outError
  {
      // Insert custom validation logic here.
      return YES; // YES if is valid, NO otherwise
  }

• It’s worth noting that if an object doesn’t appear to be KVC-compliant for a particular value, the system will call the ‘valueForUndefinedKey:’ method on an object which, on NSObject, raises an exception (and thus halts program execution). You can override this method, if you wish, to prevent exceptions being raised and to provide some sort of ‘default’ value if such a thing is meaningful.
• There is also a very useful ‘dictionaryWithValuesForKeys:’ method which will build an NSDictionary containing the specified keys and their respective values — useful if you need to access, persist or copy several values and don’t want to call ‘valueForKey:’ etc on each one. The equally useful setter equivalent of this is ’setValuesForKeysWithDictionary:’ which does exactly what it sounds like.

The End

I hope that this article has been of some use and/or interest if you’ve made it this far. Obviously I haven’t talked here about KVC compliance for accessing arrays, sets and scalar values etc but these aren’t at all complicated, provided the fundamental ideas are understood. It is also worth thinking about whether accessor methods should retain and release their values under traditional memory management.

Finally, since most accessor methods follow standard formats (i.e. broadcast that you’re changing a value, change the value, broadcast that you’ve changed the value) it’s possible to automate the process of accessor creation, most notably using Objective-C 2.0 properties. Using @property and @synthesize are both powerful features of the language for all sorts of reasons although many developers remain unconvinced of their usefulness. Using Objective-C properties offers faster (in terms of processing cycles) access to an object’s keys than either using traditional accessors, or (even slower) using valueForKey: etc. But, because of the need for terms used to specify how a @property is @synthesized, it is easy to pick the wrong words (e.g. atomic, retain, copy, readwrite etc) and not be able to work out why a particular KVC procedure or Bindings technique is crashing. Use of Objective-C 2.0 code also means your application won’t run on anything earlier than Mac OS X 10.5 Leopard.

Should you be interested in reading more about views on Objective-C 2.0 properties, take a look at: Matt Gallagher — In defense of Objective-C 2.0 Properties.

This post contains links to various other posts that attack properties, and also clarifies their purpose, notably, “not to provide auto-generated getter and setter methods” (although this is certainly one side effect of their use!).

As always, all comments are welcomed either as Blog post comments below or by email.

Happy Binding!