MacResearch

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

Last time we started a new app called Spectra, which could read in CSV data, present it in a table, allow the data to be edited, and save it out again in CSV format. In this tutorial, we are going to extend Spectra so that it can represent data graphically, using the SM2DGraphView framework, which is open-source software provided by Snowmint Creative Solutions LLC. (We will cover some other plotting frameworks in the near future, but SM2DGraphView is relatively simple to use and is well-documented, so it is a good place to start.) When all is said and done, we will have an app that can open and save CSV documents, supports viewing and editing of tabulated data, presents a graph of the data, and can even print the graph. Not bad for less than 200 lines of code.

Introducing SM2DGraphView

SM2DGraphView is a framework that has been around for many years, and has been used in a number of Cocoa applications, including 4Peaks from Mekentosj. Though it’s developed by a commercial firm, they have made it available under an open-source license, so you can use it in your own creations.

Before we can use SM2DGraphView in Spectra, we need to download and install it. Go to the SM2DGraphView web site and click the download link at the top of the page. You should end up with a disk image. Open it, and drag the SM2DGraphView.framework directory from the 10.4 Min folder to the ~/Library/Frameworks folder on your hard disk. We will also need the Interface Builder (IB) palette provided, so drag SM2DGraphView.palette from the 10.4 Min folder to the /Developer/Palettes folder on your hard disk. (If the folder doesn’t exist, just create it first.)

Including SM2DGraphView in Spectra

To add the SM2DGraphView framework to the Spectra project, begin by opening the Xcode project created last time. (You can download it here.) Then follow this procedure:

1. Open the Frameworks group in the Groups & Files source list on the left, and select the Linked Frameworks group.
2. Choose Project > Add to Project…
3. Navigate to ~/Library/Frameworks/SM2DGraphView.framework and select it. Click Add.
4. In the sheet that appears, select ‘Default’ as the Reference Type, and make sure the Spectra target is checked.
5. Click the Add button.

Now we need to add a new build phase that will copy the SM2DGraphView framework into the application bundle when it is built. If you don’t do this, and you distribute the app, SM2DGraphView will not be on the user’s computer, and your app won’t run.

1. Open the Targets group in Groups & Files, and open the Spectra target by clicking the disclosure triangle.
2. Right click on the Spectra target, and select Add > New Build Phase > New Copy Files Build Phase
3. An Info panel will come up. Choose Frameworks in the Destination popup. Close the panel.
4. Open the Frameworks and Linked Frameworks groups in Groups & Files, and drag the SM2DGraphView.framework into the newly created Copy Files build phase under the Spectra Target.

Interface Building

With the framework integrated into our Xcode project, we can turn to the Spectra interface. Double click the MyDocument.nib file in the Resources group of Groups & Files, and then make these changes:

1. Select the window instance in MyDocument.nib, and uncheck ‘Has texture’ in the Inspector. (To bring up the Inspector, use Command-Shift-I.)
2. Double click the Window instance in the MyDocument.nib window, and select the Add button.
3. In the Inspector, change the button’s type to ‘Small Square Button’.
4. Repeat for the Remove button.
5. Resize the table in the document window so that it only occupies the bottom third of the space.
6. With the the table selected, choose ‘Size’ from the popup button in the Inspector, and click the vertical inner spring to make it rigid (ie, straight), and the top outer spring to make it flexible (ie, curly).

The changes in (6) mean that the table will not resize vertically when the window resizes. Instead, we will have the graph resize with the window. (An alternative solution would be to use a split view.)

Last time we included Add and Remove buttons to alter the rows in the table. This time around, we will add a button, for refreshing the data displayed by the graph.

1. Drag a glassy button from the top-left of the Cocoa-Controls palette (2nd from left) to the bottom-right of the document window.
2. In the Inspector, choose Attributes from the popup button, and set the Type popup to ‘Small Square Button’.
3. Double click the button and change the title to ‘Refresh’.
4. With the button selected, choose ‘Size’ in the Inspector, and click on the top and left outside springs to make them curly. (This will cause the button to stick to the right and bottom of the window.)

Formatting Numbers

When we setup our table last time, we didn’t make any assumptions about what sort of data would be represented. In fact, you can enter any string in the Spectra table from the last tutorial.

In reality, we only want to be able to enter decimal numbers in the table. We can prevent arbitrary strings being entered by assigning an NSNumberFormatter to each column of the table view; this has the added bonus that whenever we retrieve data from the table, it will be returned in NSNumber instances, rather than just NSString objects.

To add formatters to the table:

1. Open the Cocoa-Text palette, which is 3rd from the left.
2. Drag a number formatter from the bottom-left of the palette onto the Energy table column. (The formatter icon has a dollar sign on it.)
3. In the Inspector, make sure the Attributes pane is visible, and choose the fourth format from the top of the list (see screenshot below).
4. Repeat these steps for the Intensity column.

Adding the Graph

Now we need a place to put the graph. We will add an NSBox to the upper two thirds of the window, and drop the graph view in it. The box is only for aesthetic purposes: it darkens the background a bit, and makes the graph look less out of place.

1. Drag a box from the Cocoa-Containers palette, sixth from left. (If the palettes window is not visible, choose Tools > Palettes > Show Palettes.)
2. In the Inspector, make sure the Attributes pane is selected, and uncheck the ‘Show Title’ checkbox.
3. Resize the NSBox: Make it wider than the window, and place it so that it extends beyond the sides so that you don’t see the rounded corners. You might find it easier to temporarily make the window bigger while you are resizing the box.
4. With the box selected, choose ‘Size’ from the Inspector popup button, and click on the two inner resizing springs to make them both curly.

To add the graph view to the box, proceed as follows:

1. Select the SM2DGraphView palette (last) in the Palettes window.
2. Double click the NSBox added earlier to make its content editable.
3. Drag the graph in the top-left of the palette onto the box.
4. Resize the graph to fit.

To test that the sizing behavior of the interface is all in order, choose File > Test Interface. To quit the test, use Command-Q.

Connecting up the Interface

The elements of the interface are all in place, but nothing is connected up yet. Let’s remedy that. We will need to define a few new actions and outlets, and then use the usual control-click and drag technique to connect it all up.

Let’s start with the graph view. We want to make the PointsArrayController instance act as the delegate and data source for the graph view.

1. Control-click and drag from the SM2DGraphView to the PointsArrayController instance in the MyDocument.nib window.
2. In the Inspector, choose the ‘delegate’ outlet, and click Connect.
3. Choose the ‘dataSource’ outlet, and click Connect.

There will need to be some talking between the MyDocument instance, and the PointsArrayController instance. Here’s how to facilitate that:

1. Click on the Classes tab of the MyDocument.nib window, and navigate to NSObject > NSDocument > MyDocument.
2. Select the MyDocument class, and bring up the Inspector.
3. Select ‘Attributes’ in the Inspector popup button, and click the Outlet tab.
4. Click the Add button in the Inspector, and enter ‘pointsArrayController’ as the name of the new outlet.
5. Repeat this for the PointsArrayController class, adding the outlets ‘document’ and ‘graphView’.
6. Click the Instances tab in the MyDocument.nib window.
7. Control-click and drag from the PointsArrayController instance to File’s Owner — which is the MyDocument instance — select the ‘document’ outlet in the Inspector, and click Connect.
8. Connect the ‘graphView’ outlet of PointsArrayController to the SM2DGraphView in the document window.
9. Connect the ‘pointsArrayController’ outlet in File’s Owner to the PointsArrayController instance.

To finish this part, we need to add a couple of actions to PointsArrayController, and connect them up:

1. Double click the PointsArrayController instance, which should take you to the class Inspector.
2. Click the Actions tab in the Inspector.
3. Add the action refreshGraph: by clicking the Add button and entering the new action.
4. Select the Instances tab in the MyDocument.nib window.
5. Control-click and drag from the Refresh button to the PointsArrayController instance, and connect it to the refreshGraph: action.

Save your changes, and return to Xcode to add the special source.

The MyDocument class

We’ll begin with the MyDocument class. Much of the source code is the same as it was in the last tutorial, but I am including all of it here. Enter the following into MyDocument.h.

#import <Cocoa/Cocoa.h>
#import "PointsArrayController.h"

@interface MyDocument : NSDocument
{
    NSArray *points;
    IBOutlet PointsArrayController *pointsArrayController;
}

-(NSArray *)points;
-(void)setPoints:(NSArray *)newPoints;

@end

The class implementation, in MyDocument.m, should look like this:

#import "MyDocument.h"

@implementation MyDocument


#pragma mark -
#pragma mark Init and Dealloc
- (id)init
{
    self = [super init];
    if (self) {
        [self setPoints:[NSArray array]];
    }
    return self;
}


#pragma mark -
#pragma mark Accessors
-(NSArray *)points {
    return points;
}

-(void)setPoints:(NSArray *)newPoints {
    [newPoints retain];
    [points release];
    points = newPoints;
}


#pragma mark -
#pragma mark Nib loading
- (NSString *)windowNibName
{
    return @"MyDocument";
}

- (void)windowControllerDidLoadNib:(NSWindowController *) aController
{
    [super windowControllerDidLoadNib:aController];
}


#pragma mark -
#pragma mark Reading and Writing
- (BOOL)writeToURL:(NSURL *)absoluteURL ofType:(NSString *)typeName error:(NSError **)outError
{
    NSMutableString *csvString = [NSMutableString string];
    NSEnumerator *pointEnum = [points objectEnumerator];
    id point;
    while ( point = [pointEnum nextObject] ) {
        NSNumber *energy = [point valueForKey:@"energy"];
        NSNumber *intensity = [point valueForKey:@"intensity"];
        [csvString appendString:[NSString stringWithFormat:@"%@,%@\n", energy, intensity]];
    }
    return [csvString writeToURL:absoluteURL atomically:NO encoding:NSUTF8StringEncoding error:outError];
}

- (BOOL)readFromURL:(NSURL *)absoluteURL ofType:(NSString *)typeName error:(NSError **)outError 
{
    NSString *fileString = [NSString stringWithContentsOfURL:absoluteURL 
        encoding:NSUTF8StringEncoding error:outError];
    if ( nil == fileString ) return NO;
    NSScanner *scanner = [NSScanner scannerWithString:fileString];
    [scanner setCharactersToBeSkipped:[NSCharacterSet characterSetWithCharactersInString:@"\n, "]];
    NSMutableArray *newPoints = [NSMutableArray array];
    float energy, intensity;
    while ( [scanner scanFloat:&energy] && [scanner scanFloat:&intensity] ) {
        [newPoints addObject:
            [NSMutableDictionary dictionaryWithObjectsAndKeys:
                [NSNumber numberWithFloat:energy], @"energy",
                [NSNumber numberWithFloat:intensity], @"intensity",
                nil]];
    }
    [self setPoints:newPoints];
    return YES;
}


#pragma mark -
#pragma mark Printing
-(IBAction)printDocument:(id)sender {
    [pointsArrayController printGraph:self];
}

@end

This code is virtually unchanged from last time. There is one new method, printDocument:, which is used for printing the graph, but the rest of the class is as it was last time. We’ll discuss the printDocument: method — and how it gets invoked — a bit later.

The PointsArrayController class

The PointsArrayController class has changed much more than MyDocument. It includes the code necessary to fill the SM2DGraphView with data. Here is the PointsArrayController.h file:

#import <Cocoa/Cocoa.h>
#import <SM2DGraphView/SM2DGraphView.h>

@interface PointsArrayController : NSArrayController {
    IBOutlet SM2DGraphView *graphView;
}

-(IBAction)refreshGraph:(id)sender;
-(IBAction)printGraph:(id)sender;

@end

The PointsArrayController class includes the graphView outlet defined earlier in IB, as well as the refreshGraph: action that we connected the Refresh button to. The printGraph: method gets called from the printDocument: method in MyDocument.m.

Most of the new code this week finds its way into PointsArrayController.m:

#import "PointsArrayController.h"

@implementation PointsArrayController

#pragma mark -
#pragma mark New Object Creation
-(id)newObject 
{
    return [[NSMutableDictionary dictionaryWithObjectsAndKeys:
        [NSNumber numberWithFloat:0.0], @"energy",
        [NSNumber numberWithFloat:0.0], @"intensity",
        nil] retain];
}


#pragma mark -
#pragma mark Actions
-(IBAction)refreshGraph:(id)sender 
{
    [graphView refreshDisplay:self];
}

-(IBAction)printGraph:(id)sender
{
    [graphView print:self];
}


#pragma mark -
#pragma mark Graph View Data Source Methods
-(unsigned int)numberOfLinesInTwoDGraphView:(SM2DGraphView *)inGraphView
{
    return 1;
}

-(NSArray *)twoDGraphView:(SM2DGraphView *)inGraphView dataForLineIndex:(unsigned int)inLineIndex
{
    NSArray *points = [self arrangedObjects];
    NSMutableArray *xyStrings = [NSMutableArray arrayWithCapacity:[points count]];
    NSEnumerator *pointEnum = [points objectEnumerator];
    id point;
    while ( point = [pointEnum nextObject] ) {
        NSPoint xyPoint = NSMakePoint([[point valueForKey:@"energy"] floatValue], 
                                      [[point valueForKey:@"intensity"] floatValue]);
        [xyStrings addObject:NSStringFromPoint(xyPoint)];
    }
    return xyStrings;
}

-(double)twoDGraphView:(SM2DGraphView *)theGraphView maximumValueForLineIndex:(unsigned int)lineIndex
               forAxis:(SM2DGraphAxisEnum)axis
{
    NSArray *values;
    if ( axis == kSM2DGraph_Axis_X ) 
        values = [self valueForKeyPath:@"arrangedObjects.energy"];
    else 
        values = [self valueForKeyPath:@"arrangedObjects.intensity"];
    if ( [values count] == 0 ) return 1.0;
    NSNumber *maxValue = [[values sortedArrayUsingSelector:@selector(compare:)] lastObject];
    return [maxValue doubleValue];
}

-(double)twoDGraphView:(SM2DGraphView *)theGraphView minimumValueForLineIndex:(unsigned int)lineIndex
               forAxis:(SM2DGraphAxisEnum)axis
{
    NSArray *values;
    if ( axis == kSM2DGraph_Axis_X ) 
        values = [self valueForKeyPath:@"arrangedObjects.energy"];
    else 
        values = [self valueForKeyPath:@"arrangedObjects.intensity"];
    if ( [values count] == 0 ) return 0.0;
    NSNumber *minValue = [[values sortedArrayUsingSelector:@selector(compare:)] objectAtIndex:0];
    return [minValue doubleValue];
}

@end

The refreshGraph: action just invokes refreshDisplay: on the SM2DGraphView object, and, analogously, printGraph: just forwards the print request onto the SM2DGraphView instance via the print: method. The rest of the class is more involved, and is discussed more below.

You should now be able to build Spectra, and run it. Click the Build and Go toolbar button, and give it a try. You can download and build the source code if you haven’t got the patience to type it over. You can also download some sample data, unzip it, and open it in Spectra.

Data Sources

The SM2DGraphView class is based on a common Cocoa design pattern in which data is supplied via a callback mechanism by an object called the data source. This pattern is used, for example, by NSTableView (when not using Cocoa Bindings). The idea is that the view class (eg, NSTableView or SM2DGraphView) holds a pointer to a data source object; the data source object implements certain methods that supply data to the view when requested.

We connected the dataSource outlet of the SM2DGraphView in IB, and the data source methods are defined in PointsArrayController.m above. In particular, the methods numberOfLinesInTwoDGraphView:, twoDGraphView:dataForLineIndex:, twoDGraphView:maximumValueForLineIndex:, and twoDGraphView:maximumValueForLineIndex: are used to tell the SM2DGraphView how many plot lines there are on the graph, what data points are in each plot, and the range of each axis. There are others too, but they are not used in this case.

The numberOfLinesInTwoDGraphView: tells the graph how many plot lines should be included. In this case, we just want a single spectrum, so 1 is returned. twoDGraphView:dataForLineIndex: returns an array of strings holding the (x,y) points in the plot. The implementation of the method just loops over the points data array, and packs the values into strings for use by the graph view.

The last two methods are used by the graph view to determine the range of each axis. In this case, we just want to find the maximum and minimum x and y values in the data set, and use those to define the axis range. The implementations above use an NSArray method, sortedArrayUsingSelector:, to sort the data, and then return either the first or last value in the array as the minimum or maximum value. This is far from optimal, but adequate for such a simple application.

The Responder Chain and First Responder

There is still one aspect of Spectra that remains to be discussed in any detail: printing. Printing works via the so-called Responder Chain. This is a chain of objects that changes dynamically as an application runs. A message is sent along the chain until an object is found that understands what to do with it. The printDocument: message is one such example.

You’ll notice that we never actually connected up the Print… menu item. It was already connected to the First Responder in IB, and the printDocument: action in particular. First Responder is actually not a real object at all; it is actually a proxy for the responder chain. At any given time, the responder chain usually begins at a view in the active window, and then works its way up through the ancestor views to the window itself. After that it goes to the window controller, and eventually to the document and application.

We put a printDocument: method in the MyDocument class. When the user selects the Print… menu item, a printDocument: message is sent along the responder chain. It starts in the views, but because none of them have a printDocument: method, it continues along the chain. The NSWindow doesn’t have printDocument: either. Eventually the message gets to the MyDocument object of the active document, which does understand the message, and processes it. The request to print is passed on to the PointsArrayController instance, which in turn asks the SM2DGraphView to print itself.

The responder chain is not only used to handle printing, but is used for many aspects of Cocoa app design, including event handling (eg, key presses, mouse clicks). It often seems as if parts of a Cocoa app work by magic; in such cases, you can bet that the responder chain is playing a role. It’s also another example of how powerful dynamic languages like Objective-C can be: implementing a responder chain in a statically-typed language is not nearly as elegant.

Conclusions

Having built a graphing app in less than 200 lines of code, I think we can conclude that SM2DGraphView is a useful framework. There are some aspects of the framework’s design that don’t sit well with me. For example, it uses the data source pattern not only for plot data, but also for setting attributes like color and plotting symbol. But minor idiosyncrasies aside, it is a solid, well-documented, and reasonably complete framework. Next time we’ll take a look at a couple of alternatives to SM2DGraphView, and highlight strengths and weaknesses of each. Until then, don’t lose the plot. (You got this far, so you can at least grant me one bad pun.)