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!

Prior to OS X 10.5 if you wanted to convert data from one model version to another, you had to handle the conversion code entirely yourself. With Leopard, however, Apple built in versioning and migration capabilities to make dealing with data migration a great deal easier.

This article looks at how you can support data migration in your Core Data applications. It shows how to handle changes entirely using Data Model versions and Mapping Models, before looking at customizing the process by using custom migration classes.

Data Migration Concepts

When making a change to a data model in Xcode, it’s tempting just to open up the existing model, make that change and save the file. In order to take advantage of versioning, however, you need to have saved the previous version into your project by using a bundle for the managed object models.

A managed object model bundle allows your project to store multiple versions of the same data model, specifying which is the current version. It also allows storage of mapping models; a mapping model translates the old version of the model to the new version by specifying which source entities map to which destination entities, similarly which attributes match and also relationships. It even allows you to specify custom mapping objects that let you run code to fill out information that doesn’t just map straight across.

If you’ve enabled mapping in your application and have the right object and mapping models available, Core Data will handle the conversion transparently to the user when opening pre-existing data stores. A version hash is maintained with each entity; upon opening a persistent store, this version hash is checked against that in the current data model version. If it doesn’t match, previous models are checked until a suitable model is found, along with the mapping to convert the data.

Enabling Data Migration

In order to take advantage of the migration capabilities, you need to change the code that configures the persistent store so that it enables automatic migration. In a Core Data non-document-based application, you typically change the method that returns the persistent store coordinator such that it enables versioning when the coordinator is created by specifying NSMigratePersistentStoresAutomaticallyOption in the options for the addPersistentStoreWithType: method. In a document-based application, the NSPersistentDocument class offers a method configurePersistentStoreCoordinatorForURL: that you can override to set the NSMigratePersistentStoresAutomaticallyOption.

There’s some great sample code in an article written by Marcus Zarra for InformIT available at:
http://www.informit.com/articles/article.aspx?p=1178181&seqNum=7

Marcus demonstrates enabling migration in both document-based and non-document-based Core Data applications. For our demo application, though, we’ll use a document-based application so that it’s easy to make copies of different data versions for the migration demonstration. ***Note that if you use his code for a non-document-based app, there’s a small error in the persistentStoreCoordinator: method that the optionsDictionary mutable dictionary is created but not passed to the relevant addPersistentStoreWithType: method (nil is passed instead) meaning that migration is never enabled. Be sure to replace options:nil with options:optionsDictionary.***

The Demo Project

We’ll start by writing a simple Core Data application with a standard data model. We’ll then create a new version of the model and a mapping model to handle migration of our old data. Finally we’ll change the new version of the model such that it requires some code to migrate the old data; we’ll write two different versions of a subclass of NSEntityMigrationPolicy demonstrating two different ways to handle the migration.

The Basic Core Data Application

The basic application maintains a list of people, storing their full name along with some notes on each person:

• Begin by creating a Core Data document-based application in Xcode.
• Open up the data model and create a ‘Person’ entity with a ‘fullName’ string attribute and a ‘notes’ string attribute.
• Open MyDocument.nib in Interface Builder and add an NSArrayController called ‘People’. Set its Mode to ‘Entity’ and Entity Name to ‘Person’. Tick the ‘Prepares Content’ checkbox. Bind its Managed Object Context to the File’s Owner ‘managedObjectContext’.
• Make the interface look something like this:
  
  Here, I’ve used an NSTableView for the list of people with its one column bound to the fullName key, along with buttons to add and remove new people; there is a text field bound to the selected person’s full name and a text view (rich text disabled) for the notes.
• Build and run the application to make sure it works as it should. Be sure to save a sample data file containing several people so that we have something to reopen later in the tutorial.

Enabling Migration for the Application

To enable migration for a document-based application, you need to override the method configurePersistentStoreCoordinatorForURL: so that it enables the migration option:

• Open MyDocument.m and add the following method which checks to see whether any options are currently set; if not, it creates a mutable newOptions dictionary and enables the NSMigratePersistentStoresAutomaticallyOption. Otherwise it copies the existing dictionary to gain a mutable version before enabling the option and calling the overridden configurePersistentStoreCoordinatorForURL: method, supplying the new dictionary:

  - (BOOL)configurePersistentStoreCoordinatorForURL:(NSURL *)url ofType:(NSString *)fileType modelConfiguration:(NSString *)configuration storeOptions:(NSDictionary *)storeOptions error:(NSError **)error
  {
  	NSMutableDictionary *newOptions;
   
  	if( storeOptions )
  	{
  		newOptions = [storeOptions mutableCopy];
  	}
  	else
  	{
  		newOptions = [[NSMutableDictionary alloc] init];
  	}
   
  	[newOptions setObject:[NSNumber numberWithBool:YES] forKey:NSMigratePersistentStoresAutomaticallyOption];
   
  	BOOL result = [super configurePersistentStoreCoordinatorForURL:url ofType:fileType modelConfiguration:configuration storeOptions:newOptions error:error];
   
  	[newOptions release];
  	return result;
  }

• Build and run the project to make sure everything is still ok. Reopen the data file you created before — hopefully nothing has changed visibly as all we’ve done is enable versioning.

Adding a new Data Model version

We’ll now add a new version of the data model by using Data Model Bundles:

• In your Xcode project browser, click once on the MyDocument.xcdatamodel file to select it.
• Choose the ‘Design -> Data Model -> Add Model Version’ menu command and you’ll see that the MyDocument.xcdatamodel becomes MyDocument.xcdatamodeld with a little triangle to expand its contents.
• Expand the bundle and rename the MyDocument 2.xcdatamodel file to ‘MyDocument1.0.xcdatamodel’ to distinguish between the two data models. You’ll also see that MyDocument.xcdatamodel has a little green tick in its icon to tell you that this is the current model verison.
• Open up the current model MyDocument.xcdatamodel and add a ’salary’ decimal attribute to the Person entity.
• Back in the project browser, right click on the data model bundle and choose ‘Add -> New File…’. Choose the ‘Mapping Model’ template and call the file ‘MyDocument1.0.xcmappingmodel’. You’ll then be asked to choose Source and Destination models; select the MyDocument1.0.xcdatamodel file and choose ‘Set Source Model’; select the MyDocument.xcdatamodel and choose ‘Set Destination Model’.
• When you click Finish, Xcode will generate a Mapping Model to convert the source Person entity to the destination Person entity. It will also try to map attributes for you. If you open the generated mapping model, you’ll see that it has filled out the ‘fullName’ and ‘notes’ property mappings. As it can’t find a previous ’salary’ attribute, the value expression for that property mapping is blank. If you wish, enter ‘0′ for the value expression or just leave it blank.
• Open the MyDocument.nib file in Interface Builder and change it so there is also a bound Salary text field. Drag a suitable NSNumberFormatter onto the field:
  
• Before proceeding further, use the Finder to find the data file that you created earlier and duplicate it so that we have a copy to use later on.
• Build and run the application and try to open your original data file. You’ll find that it opens just fine with the fullName and notes fields containing the data they had before; the salary field will either be blank or set at 0 depending on whether you entered the value expression in the property mapping earlier.
  If you run into any problems, make sure the target tickbox in Xcode is set for the current MyDocument.xcdatamodel but not the other. Otherwise you’ll get a logged problem that your application can’t merge models with two different entities named ‘Person’.

Customizing the Migration Process

Now that we’ve seen how easy it is to migrate data after adding a new attribute, we’ll look at how to customize this behaviour by splitting the old fullName attribute into a firstName and a lastName attribute using a custom entity migration policy. There are several ways to code this functionality and we’ll cover two; the first will copy attributes manually from an old entity instance to a new one whilst the second will use all the available information in the mapping model having changed the expression value for the firstName and lastName attributes at runtime.

Manual copying of data

• Firstly, we’ll change the current MyDocument.xcdatamodel file so that it has two fields for a person’s name. We won’t bother for this tutorial creating a new model version — typically in a release application, you wouldn’t worry about versions that you create during development, only the ones you release to the user. Rename the fullName attribute ‘firstName’ and add a ‘lastName’ string attribute to the Person entity.
• Open MyDocument.nib in Interface Builder and change the interface so that the table view shows two columns (bound to ‘firstName’ and ‘lastName’), change the fullName text field to bind to ‘firstName’ and add a second bound to ‘lastName’.
• Back in Xcode, delete the existing MyDocument1.0.xcmappingmodel and create a new one in the same way as before. You’ll see that Xcode has left the firstName and lastName properties blank as it can’t determine how to make the right mapping.
• Create a new Objective-C class in your Xcode project called ‘PersonMigrationClass’.
• In the header file for that class change the inheritance so that we subclass NSEntityMigrationPolicy.
• Implement the following method which will get called during the migration process. It migrates the Person entity by creating a new managed object in the destination managed object context before manually copying the source entity instance’s attributes into the destination entity’s attributes. Note that at the end of the method we call associateSourceInstance: withDestinationInstance: so that the internal magic can happen ready for subsequent migration steps that set up relationships etc:

  - (BOOL)createDestinationInstancesForSourceInstance:(NSManagedObject *)sInstance entityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error
  {
  	NSManagedObject *newObject = [NSEntityDescription insertNewObjectForEntityForName:[mapping destinationEntityName] inManagedObjectContext:[manager destinationContext]];
   
  	NSArray *nameStrings = [[sInstance valueForKey:@"fullName"] componentsSeparatedByString:@" "];
  	[newObject setValue:[nameStrings objectAtIndex:0] forKey:@"firstName"];
  	[newObject setValue:[nameStrings objectAtIndex:1] forKey:@"lastName"];
   
  	NSString *notes = [sInstance valueForKey:@"notes"];
   
  	[newObject setValue:notes forKey:@"notes"];
   
  	[manager associateSourceInstance:sInstance withDestinationInstance:newObject forEntityMapping:mapping];
   
  	return YES;
  }

• Back in the mapping model, click on the PersonToPerson entity mapping and on the right of the window set the ‘Custom Policy’ to ‘PersonMigrationClass’. You’ll see that the type of mapping changes to ‘Custom’.
• Again, make a copy of the very first data file that you created so that we can use it later. Get rid of the more recent version.
• Build and run the application and open your original data file. Hopefully, you’ll find that the first and last name fields are correctly filled out.

Another way to copy objects

It’s annoying in the previous version that we have to copy across manually the ‘notes’ attribute when we’ve already setup that attribute in the mapping model. Here we’ll implement a method that maps the entity using the mapping model’s attribute mapping, changing only the value expression for the firstName and lastName attributes. We’ll also define a ’sourceVersion’ user info tag so that we can use the same class to handle any future versions of the data model changes:

• Open up the MyDocument1.0.xcmappingmodel and click on the PersonToPerson entity mapping. In the far right of the window, click the ‘User Info’ tab and add a key called ’sourceVersion’ with value ‘1.0′:
  
• Change the implementation in our PersonMigrationClass to the following; this code checks the user info ’sourceVersion’ value and, assuming it is ‘1.0′ cycles through the provided attributeMappings array and sets only the ‘firstName’ and ‘lastName’ mappings. The overridden method is then called to handle all other mapping for us:

  - (BOOL)createDestinationInstancesForSourceInstance:(NSManagedObject *)sInstance entityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error
  {
  	float sourceVersion = [[[mapping userInfo] valueForKey:@"sourceVersion"] floatValue];
   
  	if( sourceVersion == 1.0 ) // need to convert fullName into firstName and lastName strings
  	{
  		NSArray *nameStrings = [[sInstance valueForKey:@"fullName"] componentsSeparatedByString:@" "];
  		NSString *firstName = [nameStrings objectAtIndex:0];
  		NSString *lastName = [nameStrings objectAtIndex:1];
   
  		NSArray *attributeMappings = [mapping attributeMappings];
   
  		int count;
  		for( count = 0; count < [attributeMappings count]; count ++ )
  		{
  			NSPropertyMapping *currentMapping = [attributeMappings objectAtIndex:count];
   
  			if( [[currentMapping name] isEqualToString:@"firstName"] )
  				[currentMapping setValueExpression:[NSExpression expressionForConstantValue:firstName]];
  			else if( [[currentMapping name] isEqualToString:@"lastName"] )
  				[currentMapping setValueExpression:[NSExpression expressionForConstantValue:lastName]];
  		}
  	}
   
  	return [super createDestinationInstancesForSourceInstance:sInstance entityMapping:mapping manager:manager error:error];
  }

• If you build and run the application and then open your original data file, it will again open with the information correctly populated but this time by using the mapping model value expressions for everything other than the two mappings we needed to customize.

Some Considerations

Notice that whilst both the above customization methods work as desired, they are potentially quite expensive in terms of processing. On a large dataset with many entities all using custom mapping in this way, the conversion could take quite a long time. There are also lots of objects floating around in memory that wouldn’t get deallocated until the next cycle through the event loop. You might consider customizing the migration process further by splitting it into multiple passes and using memory allocation pools.

Each window is from one application, and each keeps its own copy of the data; any change made and saved to one will be communicated to the other.

Sample project downloads are available at the end of this article.

The Synchonizing Parts

For an application to be able to synchronize via Sync Services, it needs to provide various bits of information. In the first place, there needs to be a registered Sync Schema that defines the structure of the data available to synchronize. Secondly, each application needs to provide and register a Client Description that defines which of the available data in the sync schema the application will use. Then, of course, there’s the necessary code to handle the synchronization itself.

Synchronization with Core Data

The Sync Schema lists the model objects available to be synchronized. Apple’s Bookmarks schema, for example, lists two entities — the Bookmark entity and the Folder entity, each with attributes for names, urls and parent relationships etc.

Traditionally, a sync schema is created from scratch with entries for the different entities and their attributes, entries for relationships and inverse relationships between entities, entries to allow different types of synchronization, and a whole lot more. Writing such a schema can be a bit daunting; luckily, creating a schema under Core Data is a great deal easier. Provided you define your data model with the Data Modeling Tool in Xcode, you can have most of your schema property list created for you automatically without the need to hand-code all the entities, attributes and relationships.

The Client Description, on the other hand, won’t be written for you, but this is a relatively straightforward property list simply telling Sync Services which entities and attributes your application wishes to synchronize.

Writing code to handle the synchronization typically includes methods that handle pushing and pulling data. You must invoke various methods to start the synchronization process, register your sync schema and client description, deal with changes made in your application and inform Sync Services about these changes, and then handle any changes made by other applications. When using Core Data to handle your underlying data, most of this is handled for you in the NSPersistentStoreCoordinator.

Demo Application 1

Our first project is a version of the ubiquitous Departments and Employees application, this time using a non-document-based application. We’ll start by building a standard Cocoa Core Data application using Xcode. Only after the application is working will we then start adding synchronizing functionality — this way, it’s obvious how easy it is to add synchronizing capabilities to existing applications.

The Basic Project

• Begin by creating a Cocoa Core Data Application (don’t use the Document-based template) and call it ‘DepartmentsAndEmployeesSyncApp’.
• In the Xcode Data Modeler, create a ‘Department’ entity with a ‘name’ string attribute. Create a ‘Person’ entity with ‘firstName’ and ‘lastName’ string attributes, and a ’salary’ decimal attribute. In the Department entity create an ‘employees’ to-many relationship to the Person entity, and create its inverse ‘department’ to-one relationship between Person and Department.
• Open MainMenu.nib in Interface Builder and create an NSArrayController called ‘Departments’. Set its Mode to ‘Entity’ and Entity Name to ‘Department’. Check the ‘Prepares Content’ box. Bind its Managed Object Context to the App Delegate object’s ‘managedObjectContext’.
• Create a second NSArrayController called ‘People’ for the Person entity that also Prepares Content. Bind its Managed Object Context to the App Delegate’s managedObjectContext and its Content Set to the Department controller’s ’selection’ ‘employees’.
• For the user interface, add to the nib file’s Window layout a one-column NSTableView that displays the departments, binding its column Value to the Departments array controller ‘arrangedObjects’ ‘name’ key.
• Add a second NSTableView, this time with three columns, bound to the People array controller ‘firstName’, ‘lastName’ and ’salary’ keys respectively. Drag an NSNumberFormatter onto the salary column.
• Finally add ‘+’ and ‘-’ buttons for both table views that connect to the relevant add: and remove: array controller actions.
• Build and run your application to make sure everything works as it should. Mine looks like this:
  

Nothing particularly impressive here — just the construction of the basic project ready for synchronization implementation. Obviously, we’re using a standard Core Data application rather than a document-based app so that we have only a single known set of data when we come to start synching. Now we’ll move on to define the synch schema.

The Sync Schema

• In Xcode, create another new project. Use the ‘Sync Schema’ template, which for me is listed under ‘Standard Apple Plug-ins’. Call this project ‘DemoEmploymentData’.
• The resultant project contains various files, the most important of which is the ‘Schema.plist’ file. Open this file and you’ll find a demo schema already in there. We can remove most of this as our Entities information will be generated for us from our data model in the DepartmentsAndEmployeesSyncApp project.
• Delete from the opening Entities key down to the closing of the array for that key. You should be left with a DataClasses key and a Name key.
• Under the DataClasses key we define names for the collections of data we are going to be sharing. Since we’re only sharing one type of information (employment data) we will define a single data class. Replace the existing ‘com.mycompany.myschema.dataclass’ string with ‘com.mycompany.DemoEmploymentData’. Sync Services uses reverse DNS syntax to keep track of its information. Note that this key has to be unique across all schemas.
• There is another key under DataClasses called ‘ImagePath’. This might be called ‘Image’ in your schema; if it is, rename it to ‘ImagePath’ to avoid errors later. This path is used to display an icon representing the data class; this might be used, for example, if it’s displayed in the MobileMe System Preferences tab. For this demonstration, we’ll leave it as it is with the standard ‘SyncDataClass.tiff’ image.
• Change the string for the ‘Name’ key to be ‘com.mycompany.DemoEmploymentDataSchema’.
• To make use of the automatic generation functionality, define a new key called ‘ManagedObjectModels’ with an array containing a string pointing to our data model. This is a relative path; assuming you’re going to follow this tutorial through, enter it as:

  <key>ManagedObjectModels</key>
  <array>
  	<string>../../../DepartmentsAndEmployeesSyncApp_DataModel.mom</string>
  </array>

• If you wish, open the Schema.strings file and enter localization information for the schema keys.

The complete schema.plist file should look something like this:

<?xml version="1.0" encoding="ASCII"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 
<!-- Schema.plist -->
<!-- EmployeeData -->
<!-- Created by Tim Isted on 25/07/2008. -->
<!-- Copyright __MyCompanyName__ 2008. All rights reserved. -->
 
<plist version="1.0">
<dict>
	<key>DataClasses</key>
	<array>
		<dict>
			<key>Name</key>
			<string>com.mycompany.DemoEmploymentData</string>
			<key>ImagePath</key>
			<string>SyncDataClass.tiff</string>
		</dict>
	</array>
 
	<key>ManagedObjectModels</key>
	<array>
		<string>../../../DepartmentsAndEmployeesSyncApp_DataModel.mom</string>
	</array>
 
	<key>Name</key>
	<string>com.mycompany.DemoEmploymentDataSchema</string>
</dict>
</plist>

Now we need to include the built schema in our original app project.

• Build the DemoEmploymentData project.
• Return to the DepartmentsAndEmployeeSyncApp. Right-click on the ‘Resources’ group and choose ‘Add -> Existing Files…’.
• Find the DemoEmploymentData project directory and inside that find the ‘build’ directory. Inside there you’ll find a ‘release’ directory containing a directory called ‘DemoEmploymentData.syncschema’. Select this directory and Add it to the project. In the dialog box that appears after this, check the ‘Create Folder References for any added folders’ radio button so that the directory structure is maintained. Once the syncschema is added, your Xcode project’s Groups & Files outline view should look like this:

  

Changes to the Data Model

Now that we’ve defined our data schema by telling it about our data model, we need to make a few changes to the data model so that it will populate the schema properly.

• Open up the data model in Xcode. Click on the Department entity and in the far top right of the window, click the little ’sync’ icon to setup the synchronization settings for the entity. Enter the Data Class as the one we setup earlier in the syncschema ‘com.mycompany.DemoEmploymentData’. Make sure the ‘Synchronize…’ box is ticked as shown:
  
• Click the ‘name’ attribute and check the ‘Identity property’ box. This specifies that the name attribute will be unique and used to track different departments.
• For the person entity, make sure the data class is again ‘com.mycompany.DemoEmploymentData’ and that it should be synchronized. Specify that the ‘firstName’ and ‘lastName’ attributes are Identity properties.

The Client Description

Our final piece of synchronization information is the client description that defines which data in the syncschema we will be synchronizing.

• Right-click on the ‘Resources’ group in the project listing and choose ‘Add -> New File…’. Choose the ‘Sync Client Description’ under ‘Sync Services’ and call the file ‘clientDescription.plist’.
• Under the Entities key, change the first dictionary key to ‘com.mycompany.DemoEmploymentData.Department’.
• The first entry in the following array is a string that must be left as ‘com.apple.syncservices.RecordEntityName’. The subsequent strings define the chosen attributes for the specific entity; change the ‘first name’ string to be just ‘name’. Add another string for the ‘employees’ relationship.
• Add a second entity key called ‘com.mycompany.DemoEmploymentData.Person’ and again add the ‘com.apple.syncservices.RecordEntityName’ string. Also add strings for the ‘firstName’, ‘lastName’, ’salary’ and ‘department’ attributes.

Your finished client description should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 
<!-- clientDescription.plist -->
<!-- DepartmentsAndEmployeesSyncApp -->
<!-- Created by Tim Isted on 25/07/2008. -->
<!-- Copyright 2008 __MyCompanyName__. All rights reserved. -->
 
<plist version="1.0">
<dict>
	<key>DisplayName</key>
	<string>DepartmentsAndEmployeesSyncApp</string>
 
	<key>Entities</key>
	<dict>
		<key>com.mycompany.DemoEmploymentData.Department</key>
		<array>
			<string>com.apple.syncservices.RecordEntityName</string>
			<string>name</string>
			<string>employees</string>
		</array>
 
		<key>com.mycompany.DemoEmploymentData.Person</key>
		<array>
			<string>com.apple.syncservices.RecordEntityName</string>
			<string>firstName</string>
			<string>lastName</string>
			<string>salary</string>
			<string>department</string>
		</array>
	</dict>
 
	<key>Type</key>
	<string>app</string>
</dict>
</plist>

Making our application synchronize

In order to get our application to synchronize its data, we need to make a few modifications to the way the application sets up its persistent store. We also need to change the save action so that whenever data is persisted, it is also synchronized.

• Firstly, we need to add the relevant framework to the project. Expand the Frameworks group in your project browser and right-click on the Linked Frameworks group. Choose ‘Add -> Existing Frameworks…’ and select the ‘SyncServices.framework’.
• Next we’ll modify the application delegate so that it handles both synchronization and the necessary callbacks. Open ‘DepartmentsAndEmployeesSyncApp_AppDelegate.h’. After the #import for Cocoa.h add a line to import the SyncServices header:

  #import <syncServices/SyncServices.h>

• In order to be able to handle the synchronization callbacks, an object must conform to the NSPersistentStoreCoordinatorSyncing protocol. So, change the object interface to be:

  @interface DepartmentsAndEmployeesSyncApp_AppDelegate : NSObject <nspersistentStoreCoordinatorSyncing>

• We’re going to be writing a method that will initiate a sync so add a declaration for it:

  - (void)syncAction:(id)sender;

The Core Data framework handles synchronization through the NSPersistentStoreCoordinator. To support fast synchronization operations, you need to specify a ‘fastsyncstore’ file for the coordinator to maintain.

• Open the DepartmentsAndEmployeesSyncApp_AppDelegate.m files and find the persistentStoreCoordinator: method. We need to change this so that it keeps track of the created NSPersistentStore, and then adds the .fastsyncstore file to it. Rewrite the method so it looks like this:

  - (NSPersistentStoreCoordinator *) persistentStoreCoordinator
  {
  	if (persistentStoreCoordinator != nil) {
  		return persistentStoreCoordinator;
  	}
   
  	NSFileManager *fileManager;
  	NSString *applicationSupportFolder = nil;
  	NSURL *url;
  	NSError *error;
   
  	fileManager = [NSFileManager defaultManager];
  	applicationSupportFolder = [self applicationSupportFolder];
  	if ( ![fileManager fileExistsAtPath:applicationSupportFolder isDirectory:NULL] ) {
  		[fileManager createDirectoryAtPath:applicationSupportFolder attributes:nil];
  	}
   
  	url = [NSURL fileURLWithPath: [applicationSupportFolder stringByAppendingPathComponent: @"DepartmentsAndEmployeesSyncApp.xml"]];
  	persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel: [self managedObjectModel]];
   
  	NSPersistentStore *store = [persistentStoreCoordinator addPersistentStoreWithType:NSXMLStoreType configuration:nil URL:url options:nil error:&error];
   
  	if( store != nil ) {
  		NSURL *fastSyncFileURL = [NSURL fileURLWithPath:[applicationSupportFolder stringByAppendingPathComponent:@"DepartmentsAndEmployeesSyncApp.fastsyncstore"]];
  		[persistentStoreCoordinator setStoresFastSyncDetailsAtURL:fastSyncFileURL forPersistentStore:store];
  	}
  	else {
  		[[NSApplication sharedApplication] presentError:error];
  	}
   
  	return persistentStoreCoordinator;
  }

• We need to write a method that will return an ISyncClient object ready for use in synchronization. Sync Services keeps track of different sync clients by using the unique application bundle identifier. Add the following method at the end of the file. It asks whether such a client exists for our application; if not it creates one, registers the schema and client description before specifying which client types it should synchronize with, displaying an error to the user if something goes wrong:

  - (ISyncClient *)syncClient
  {
  	NSString *clientIdentifier = [[NSBundle mainBundle] bundleIdentifier];
  	NSString *reason = @"unknown error";
  	ISyncClient *client;
   
  	@try {
  		client = [[ISyncManager sharedManager] clientWithIdentifier:clientIdentifier];
  		if( client == nil )
  		{
  			if (![[ISyncManager sharedManager] registerSchemaWithBundlePath:[[NSBundle mainBundle] pathForResource:@"DemoEmploymentData" ofType:@"syncschema"]])
  			{
  				reason = @"error registering the DemoEmploymentData sync schema";
  			}
  			else
  			{
  				client = [[ISyncManager sharedManager] registerClientWithIdentifier:clientIdentifier descriptionFilePath:[[NSBundle mainBundle] pathForResource:@"clientDescription" ofType:@"plist"]];
  				[client setShouldSynchronize:YES withClientsOfType:ISyncClientTypeApplication];
  				[client setShouldSynchronize:YES withClientsOfType:ISyncClientTypeDevice];
  				[client setShouldSynchronize:YES withClientsOfType:ISyncClientTypeServer];
  				[client setShouldSynchronize:YES withClientsOfType:ISyncClientTypePeer];
  			}
  		}
  	}
  	@catch (id exception) {
  		client = nil;
  		reason = [exception reason];
  	}
   
  	if( client == nil ) {
  		NSRunAlertPanel(@"You can not sync your Employee Data.", [NSString stringWithFormat:@"Failed to register the sync client: %@", reason], @"OK", nil, nil);
  	}
   
  	return client;
  }

• Next, implement the syncAction: method to start off the synchronization process by calling the syncWithClient: method on the application’s persistentStoreCoordinator:

  - (void)syncAction:(id)sender
  {
  	NSError *error = nil;
  	ISyncClient *client = [self syncClient];
  	if( client != nil )
  	{
  		[[[self managedObjectContext] persistentStoreCoordinator] syncWithClient:client inBackground:NO handler:self error:&error];
  	}
   
  	if( error != nil )
  	{
  		[[NSApplication sharedApplication] presentError:error];
  	}
  }

• Find the saveAction: method and change it to call our syncAction: method once the managedObjectContext has saved:

  - (IBAction) saveAction:(id)sender {
   
  	NSError *error = nil;
  	if ([[self managedObjectContext] save:&error])
  	{
  		[self syncAction:sender];
  	}
  	else
  	{
  		[[NSApplication sharedApplication] presentError:error];
  	}
  }

• If a synchronization involving our data is triggered by another application, we need to know so that we can update our own application. So, firstly add an applicationDidFinishLaunching: method to set the syncAlertHandler to a selector for a second method that calls saveAction:

  - (void)applicationDidFinishLaunching:(NSNotification *)notification
  {
  	[[self syncClient] setSyncAlertHandler:self selector:@selector(client:mightWantToSyncEntityNames:)];
  	[self syncAction:nil];
  }
   
  - (void)client:(ISyncClient *)client mightWantToSyncEntityNames:(NSArray *)entityNames
  {
  	[self saveAction:self];
  }

• Add an applicationWillTerminate: method that calls saveAction: so that our data is automatically saved and synchronized when the user exits the application:

  - (void)applicationWillTerminate:(NSNotification *)notification
  {
  	[self saveAction:nil];
  }

• Next, add methods that specify which managedObjectContexts should be monitored when synchronizing our persistent store. If a synchronization is triggered outside of the application by another application synching with data in our schema, the managed object contexts listed in the second method will be reloaded to reflect any changes that were made:

  - (NSArray *)managedObjectContextsToMonitorWhenSyncingPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator
  {
  	return [NSArray arrayWithObject:[self managedObjectContext]];
  }
   
  - (NSArray *)managedObjectContextsToReloadAfterSyncingPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator
  {
  	return [NSArray arrayWithObject:[self managedObjectContext]];
  }

• Finally, add methods that get called when an object is pushed or changed during synchronization. These methods allow information contained within the object or change to be modified to suit the way data is stored in our model. For this application, we can simply return the provided object as it stands:

  - (NSDictionary *)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willPushRecord:(NSDictionary *)record forManagedObject:(NSManagedObject *)managedObject inSyncSession:(ISyncSession *)session
  {
  	return record;
  }
   
  - (ISyncChange *)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willApplyChange:(ISyncChange *)change toManagedObject:(NSManagedObject *)managedObject inSyncSession:(ISyncSession *)session
  {
  	return change;
  }

Assuming all has gone to plan, when you build and run the project, you won’t notice very much difference, except that if you previously inputted some data into your application, you’ll probably experience a small delay before it is displayed while the synchronization is setup.

Apple provides a useful development tool called ‘Syncrospector’ that can be used to inspect sync schemas and clients. If you find and launch the tool you should be able to see your new sync schema listed, together with its specified entities. You can also view the sync client details for the DepartmentsAndEmployeesSyncApp application, hopefully displaying successful synchronization of the two entities:

Demo Application 2

Our second project is a simplified employee viewing application that holds the same data as our first but displays it in a slightly different way. We’ll define the client description and setup synching in a similar way to our first project such that the two applications will keep in sync with each other.

• Create a new Core Data Application in Xcode and call it ‘EmployeesListSyncApp’.
• Open the data model and add the same entities as before — Department and Person — with the same attributes and relationships.
• Open MainWindow.nib in Interface Builder and add a single NSArrayController called ‘People’. Set it to Prepare Content from the ‘Person’ entity and bind its Managed Object Context to the application delegate’s ‘managedObjectContext’.
• Open the Window and add an NSTableView. Give it four columns bound to the ‘firstName’, ‘lastName’, ’salary’ and ‘department.name’ keys respectively from the People controller. Drag an NSNumberFormatter onto the Salary column and make the Department column uneditable.

Next we’ll define the client description for this application which is essentially the same as for our first application — namely that it synchronizes the ‘Department’ and ‘Person’ entities along with their various attributes and relationships.

• Add a ‘Sync Client Description’ called ‘clientDescription’ to the Resources group of our project.
• Change the Entities keys to access our DemoEmploymentData entities and attributes.

The finished clientDescription.plist file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 
<!-- clientDescription.plist -->
<!-- EmployeesListSyncApp -->
<!-- Created by Tim Isted on 25/07/2008. -->
<!-- Copyright 2008 __MyCompanyName__. All rights reserved. -->
 
<plist version="1.0">
<dict>
	<key>DisplayName</key>
	<string>EmployeesListSyncApp</string>
 
	<key>Entities</key>
	<dict>
		<key>com.mycompany.DemoEmploymentData.Department</key>
		<array>
			<string>com.apple.syncservices.RecordEntityName</string>
			<string>name</string>
			<string>employees</string>
		</array>
 
		<key>com.mycompany.DemoEmploymentData.Person</key>
		<array>
			<string>com.apple.syncservices.RecordEntityName</string>
			<string>firstName</string>
			<string>lastName</string>
			<string>salary</string>
			<string>department</string>
		</array>
	</dict>
 
	<key>Type</key>
	<string>app</string>
</dict>
</plist>

Now open up the data model again and setup the synchronization for the entities and their attributes as we did in the first application.

• The Data Class for both entities is ‘com.mycompany.DemoEmploymentData’.
• Make the Department ‘name’ attribute and the Person ‘firstName’ and ‘lastName’ attributes into Identity properties.

Finally we can setup the application to synchronize data in a similar way to the first project:

• Add the SyncServices framework to your project Linked Frameworks group.
• #import the SyncServices/SyncServices.h header file into your application delegate header and change the interface to adopt the NSPersistentStoreCoordinatorSyncing protocol.
• Since we’ll be synchronizing this application in the same way as the first, add the same - (void)syncAction:(id)sender; declaration in the header.
• Change the implementation for the persistentStoreCoordinator: so it behaves as before:

  - (NSPersistentStoreCoordinator *) persistentStoreCoordinator
  {
  	if (persistentStoreCoordinator != nil) {
  		return persistentStoreCoordinator;
  	}
   
  	NSFileManager *fileManager;
  	NSString *applicationSupportFolder = nil;
  	NSURL *url;
  	NSError *error;
   
  	fileManager = [NSFileManager defaultManager];
  	applicationSupportFolder = [self applicationSupportFolder];
  	if ( ![fileManager fileExistsAtPath:applicationSupportFolder isDirectory:NULL] ) {
  		[fileManager createDirectoryAtPath:applicationSupportFolder attributes:nil];
  	}
   
  	url = [NSURL fileURLWithPath: [applicationSupportFolder stringByAppendingPathComponent: @"EmployeesListSyncApp.xml"]];
  	persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel: [self managedObjectModel]];
   
  	NSPersistentStore *store = [persistentStoreCoordinator addPersistentStoreWithType:NSXMLStoreType configuration:nil URL:url options:nil error:&error];
   
  	if( store != nil ) {
  		NSURL *fastSyncFileURL = [NSURL fileURLWithPath:[applicationSupportFolder stringByAppendingPathComponent:@"EmployeesListSyncApp.fastsyncstore"]];
  		[persistentStoreCoordinator setStoresFastSyncDetailsAtURL:fastSyncFileURL forPersistentStore:store];
  	}
  	else {
  		[[NSApplication sharedApplication] presentError:error];
  	}
   
  	return persistentStoreCoordinator;
  }

• Add the syncClient: method but this time we only need to register the client description, not the main sync schema:

  - (ISyncClient *)syncClient
  {
  	NSString *clientIdentifier = [[NSBundle mainBundle] bundleIdentifier];
  	NSString *reason = @"unknown error";
  	ISyncClient *client;
   
  	@try {
  		client = [[ISyncManager sharedManager] clientWithIdentifier:clientIdentifier];
  		if( client == nil )
  		{
  			client = [[ISyncManager sharedManager] registerClientWithIdentifier:clientIdentifier descriptionFilePath:[[NSBundle mainBundle] pathForResource:@"clientDescription" ofType:@"plist"]];
  			[client setShouldSynchronize:YES withClientsOfType:ISyncClientTypeApplication];
  			[client setShouldSynchronize:YES withClientsOfType:ISyncClientTypeDevice];
  			[client setShouldSynchronize:YES withClientsOfType:ISyncClientTypeServer];
  			[client setShouldSynchronize:YES withClientsOfType:ISyncClientTypePeer];
  		}
  	}
  	@catch (id exception) {
  		client = nil;
  		reason = [exception reason];
  	}
   
  	if( client == nil ) {
  		NSRunAlertPanel(@"You can not sync your Employee Data.", [NSString stringWithFormat:@"Failed to register the sync client: %@", reason], @"OK", nil, nil);
  	}
   
  	return client;
  }

• Implement the syncAction: method as before:

  - (void)syncAction:(id)sender
  {
  	NSError *error = nil;
  	ISyncClient *client = [self syncClient];
  	if( client != nil )
  	{
  		[[[self managedObjectContext] persistentStoreCoordinator] syncWithClient:client inBackground:NO handler:self error:&error];
  	}
   
  	if( error != nil )
  	{
  		[[NSApplication sharedApplication] presentError:error];
  	}
  }

• Change the saveAction: method to call the syncAction: method:

  - (IBAction) saveAction:(id)sender {
   
  	NSError *error = nil;
  	if ([[self managedObjectContext] save:&error])
  	{
  		[self syncAction:sender];
  	}
  	else
  	{
  		[[NSApplication sharedApplication] presentError:error];
  	}
  }

• Finally add the other callback methods:

  - (void)applicationDidFinishLaunching:(NSNotification *)notification
  {
  	[[self syncClient] setSyncAlertHandler:self selector:@selector(client:mightWantToSyncEntityNames:)];
  	[self syncAction:nil];
  }
   
  - (void)client:(ISyncClient *)client mightWantToSyncEntityNames:(NSArray *)entityNames
  {
  	[self saveAction:self];
  }
   
  - (void)applicationWillTerminate:(NSNotification *)notification
  {
  	[self saveAction:nil];
  }
   
  - (NSArray *)managedObjectContextsToMonitorWhenSyncingPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator
  {
  	return [NSArray arrayWithObject:[self managedObjectContext]];
  }
   
  - (NSArray *)managedObjectContextsToReloadAfterSyncingPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator
  {
  	return [NSArray arrayWithObject:[self managedObjectContext]];
  }
   
  - (NSDictionary *)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willPushRecord:(NSDictionary *)record forManagedObject:(NSManagedObject *)managedObject inSyncSession:(ISyncSession *)session
  {
  	return record;
  }
   
  - (ISyncChange *)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willApplyChange:(ISyncChange *)change toManagedObject:(NSManagedObject *)managedObject inSyncSession:(ISyncSession *)session
  {
  	return change;
  }

If you build and run this second application, you’ll find that any data you might have input into the first application is automatically displayed by this one. Notice how the Department relationship is pulled across and correctly displayed.

Try changing the name or salary of one of the people in either application. Once you save or exit the program, you’ll find that the other application automatically updates the display (and its underlying data) accordingly. Create a new person in the first application; once you save, the second application will then display that new person too.

Sample Project Downloads

The sample projects are available in one file (136kb) here: coredatasyncserv.zip.

Once you have downloaded the file, decompress it and you’ll find three projects inside. The first two need to be built in a specific order as one requires the build release of the other:

1. Open and build the DemoEmploymentData project.
2. Open the DepartmentsAndEmployeesSyncApp project and check that the references to the DemoEmploymentData.syncschema are valid (ie they’re not displayed in red text). If they are not valid, delete the references and follow the instructions earlier in the article about adding the syncschema into your project. Once the references are valid, build and run the first application.
3. Finally, open the EmployeesListSyncApp project and build/run it. There are no references to worry about inside this one!

If you run into problems, please let me know.

Again, this article takes the previous CoreDataMultiWin application (in its third incarnation with multiple windows, multiple managed object contexts and table view double clicks) as its basis. This time, the interface for the application should end up looking like this:

- Edit – The example project for this post is available to download from here: coredatamultiwin4.zip.

Store some additional data to display

Before we go into the code to show the cell and its values, let’s make a change to the data model so that we have a little more information to display.

Open MyDocument.xcdatamodel in Xcode and add a third string attribute to the Person entity called ’salary’. Note that in a real-world app, you’d most likely want to use a number attribute rather than a string here and perform all sorts of validation in the interface to check input; since we’re using this attribute only for this demonstration, however, we’ll leave it as a string so that the user can type in anything they want.

Now that we’ve sorted out the model, we need to change the interface accordingly.

Open the PersonWindow.nib Window in Interface Builder and add a labelled text field for the salary so it looks like this:

Bind the Value of the new text field to the Person ’selection’ ’salary’ model key path.

Next open AddEmployeeWindow.nib in Interface Builder and make the window look like this:

Again, bind the Value of the new text field to the New Employee ’selection’ ’salary’.

We need to make a change to the AddEmployeeController code in order that the salary value is copied across contexts so open up the AddEmployeeController.m file. Assuming you made the change to use a dictionary of keys for copying the new employee object as suggested in the article on multiple managed object contexts, simply change the line that makes the employeeKeys array to the following:

NSArray *employeeKeys = [[NSArray alloc] initWithObjects:@"firstName", @"lastName", @"department", @"salary", nil];

It’s as simple as adding in the additional key to this array to make our new salary attribute work.

Build and run the application to check that the salary attribute is copied across from the Add Employee window to the main window (you’ll need to open a display window for an employee to check the value).

A custom table view cell

Now that we’ve got some very slightly more interesting data stored, let’s create a custom table view cell to display it.

Create a new Cocoa class called EmployeeTableCell and change EmployeeTableCell.h so that our object inherits from NSCell rather than NSObject:

@interface EmployeeTableCell : NSCell {
 
}
 
@end

Now open EmployeeTableCell.m and implement a method drawWithFrame: inView: that will be called to display the custom cell:

- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView
{
	NSPoint textPoint;
 
	NSString *helloString = @"Hello!";
 
	textPoint.x = cellFrame.origin.x + 1;
	textPoint.y = cellFrame.origin.y;
 
	NSDictionary *textAttributes = [NSDictionary dictionaryWithObjectsAndKeys: [NSColor blackColor], NSForegroundColorAttributeName, [NSFont systemFontOfSize:13], NSFontAttributeName, nil];
	[helloString drawAtPoint:textPoint withAttributes:textAttributes];
}

This method just displays the text “Hello!” inside the cell so that we can test our custom table cell is working.

Now we need to tell our table view to use the custom cell so open up MyDocument.h and add an IBOutlet for an NSTableColumn:

IBOutlet NSTableColumn *peopleTableColumn;

Open MyDocument.nib and connect this Interface Builder outlet to the first column in the people table view.

Back in Xcode, open MyDocument.m and #import the EmployeeTableCell.h header file. Find the windowControllerDidLoadNib: method and add the following after the call to super:

EmployeeTableCell *infoCell = [[EmployeeTableCell alloc] init];
[peopleTableColumn setDataCell:infoCell];

Here we allocate a single instance of our new EmployeeTableCell class and tell the table view column to use this cell to display its data.

If you build and run the application you’ll find that instead of displaying the firstName in the column, our Hello! message is now displayed.

Return now to the EmployeeTableCell.m file and change the drawWithFrame: inView: method to the following:

- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView
{
	NSString *firstNameString = [self objectValue];
 
	NSPoint textPoint;
 
	textPoint.x = cellFrame.origin.x + 1;
	textPoint.y = cellFrame.origin.y;
 
	NSDictionary *textAttributes = [NSDictionary dictionaryWithObjectsAndKeys: [NSColor blackColor], NSForegroundColorAttributeName, [NSFont systemFontOfSize:13], NSFontAttributeName, nil];
	[firstNameString drawAtPoint:textPoint withAttributes:textAttributes];
}

This code pulls the firstName value from the object represented by the cell and then displays it instead of the Hello! string.

Again, build and run the application and you will see the first and last names displayed in the columns as they were originally but this time the first name is displayed for us by our custom cell.

Getting multiple values to a cell

Since we find out the string to display by getting the cell’s objectValue, in order to receive multiple values we obviously need to have the objectValue somehow return an array, dictionary or some such structure of information rather than just the one string. For this example, we’re going to generate a dictionary of Person information which we then pass to the cell.

At this point we need to make a custom NSManagedObject subclass for our Person entity so that we can generate the necessary dictionary of information on demand when the cell requires it.

Open the data model again and add to the Person entity an Undefined, Transient attribute called ‘personDictionary’. Set the class of the Person entity to PersonObject rather than NSManagedObject.

With the Person entity selected in the data model, make a new file in Xcode and selected the ‘Managed Object Class’ template in the ‘Design’ category. Click ‘Next’ to get to the ‘Managed Object Class Generation’ screen and make sure the Person entity is ticked along with the Generate accessors checkbox at the bottom of the screen. Deselect the ‘Generate Obj-C 2.0 Properties’:

Click ‘Finish’ and you’ll be greeted with an automatically-generated PersonObject.h file with declarations for the setters and getters.

Remove the setter for the personDictionary attribute and replace the UNKNOWN_TYPE with an NSDictionary pointer. Also add a class method employeeKeys so that your PersonObject declarations look like this:

@interface PersonObject :  NSManagedObject
{
}
 
+ (NSArray *)employeeKeys;
- (NSDictionary *)personDictionary;
 
- (NSString *)salary;
- (void)setSalary:(NSString *)value;
 
- (NSString *)firstName;
- (void)setFirstName:(NSString *)value;
 
- (NSString *)lastName;
- (void)setLastName:(NSString *)value;
 
- (NSManagedObject *)department;
- (void)setDepartment:(NSManagedObject *)value;
 
@end

Now open up PersonObject.m and again remove the setPersonDictionary: setter from the implementations.

We’ll implement the employeeKeys method to return the keys of the employee data (like the array we used in previous articles when copying managed objects from one context to another).

+ (NSArray *)employeeKeys
{
	static NSArray *employeeKeys = nil;
 
	if( employeeKeys == nil )
		employeeKeys = [[NSArray alloc] initWithObjects:@"firstName", @"lastName", @"department", @"salary", nil];
 
	return employeeKeys;
}

This class method maintains a static array of keys that can be used by other methods to build a dictionary.

Next change the getter method’s UNKNOWN_TYPE again and implement it like this:

- (NSDictionary *)personDictionary
{
    return [self dictionaryWithValuesForKeys:[[self class] employeeKeys]];
}

This very simple method simply returns a dictionary filled with the required keys and values.

Back in Interface Builder, change the binding for the table column to the ‘personDictionary’ key instead of the ‘firstName’ key.

Now that we’ve changed the object provided to the table column, we need to make changes to our custom cell to collect the data properly. Open EmployeeTableCell.m and change the method to the following:

- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView
{
	NSDictionary *cellValues = [self objectValue];
 
	NSPoint textPoint;
 
	NSString *firstNameString = [cellValues valueForKey:@"firstName"];
 
	textPoint.x = cellFrame.origin.x + 1;
	textPoint.y = cellFrame.origin.y;
 
	NSDictionary *textAttributes = [NSDictionary dictionaryWithObjectsAndKeys: [NSColor blackColor], NSForegroundColorAttributeName, [NSFont systemFontOfSize:13], NSFontAttributeName, nil];
	[firstNameString drawAtPoint:textPoint withAttributes:textAttributes];
}

Now the firstName attribute is pulled from the dictionary and displayed as before.

Build and run the application to make sure all works as expected.

Now that we have the potential to display multiple values in the cell, return to Interface Builder and change the MyDocument.nib main Window so that there is only our custom cell table column in the table view, resized to fill the table. Change the title of the column to “Employees”. Check the ‘Alternating Rows’ checkbox for the table view and set its row height to 50:

Back in Xcode change our custom cell drawWithFrame: inView: method to the following:

- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView
{
	NSDictionary *cellValues = [self objectValue];
 
	NSPoint textPoint;
 
	NSString *nameString = [cellValues valueForKey:@"firstName"];
	nameString = [nameString stringByAppendingFormat:@" %@", [cellValues valueForKey:@"lastName"]];
 
	NSString *salaryString = [cellValues valueForKey:@"salary"];
	NSString *departmentString = [NSString stringWithFormat:@"Department: %@", [[cellValues valueForKey:@"department"] valueForKey:@"name"]];
 
	textPoint.x = cellFrame.origin.x + 1;
	textPoint.y = cellFrame.origin.y;
 
	NSMutableDictionary *textAttributes = [NSMutableDictionary dictionaryWithObjectsAndKeys: [NSColor blackColor], NSForegroundColorAttributeName, [NSFont systemFontOfSize:13], NSFontAttributeName, nil];
	[nameString drawAtPoint:textPoint withAttributes:textAttributes];
 
	textPoint.y = cellFrame.origin.y + 18;
 
	[textAttributes setValue:[NSFont systemFontOfSize:15] forKey:NSFontAttributeName];
	[salaryString drawAtPoint:textPoint withAttributes:textAttributes];
 
	textPoint.y = cellFrame.origin.y + 36;
	[textAttributes setValue:[NSFont systemFontOfSize:11] forKey:NSFontAttributeName];
	[textAttributes setValue:[NSColor grayColor] forKey:NSForegroundColorAttributeName];
	[departmentString drawAtPoint:textPoint withAttributes:textAttributes];
}

This code builds and displays a nameString using the firstName and lastName keys from the dictionary. It also displays the salary and shows that we are able to display the department “name” from a managed object value for the key “department”.

Build and run the application to make sure the display works. You will, however, notice that if you open an employee window and change the salary, the main window doesn’t automatically update the employee cell. This is because the binding mechanism does not know what values affect the values in the personDictionary.

To fix this problem, add the following method to PersonObject.m:

+ (NSSet *)keyPathsForValuesAffectingPersonDictionary
{
	return [NSSet setWithObjects:@"firstName", @"lastName", @"department", @"salary", nil];
}

The Key-Value Coding mechanism allows for a class method that asks which values affect a dependent key such as our personDictionary; the name of the method must follow the format ‘keyPathsForValuesAffecting…’ with the attribute name starting with an initial capital letter.

If you now build and run the application, whenever a relevant attribute is changed in a Person Window, anything bound to the personDictionary key is told that the values have changed and here the cell in the main document window automatically updates to display the correct information.

Error Checking

None of the code here checks for potential errors. You’ll discover, for example, that creating a new employee and leaving the salary field blank will crash the application. You could fix this by making it a required field, or by using validation, or just by having any code that expects a salary value check that it hasn’t received a nil string. This goes for all the attributes in this example!