Leopard Sample: A Bound NSCollectionView

Leopard introduces a bunch of amazingly powerful new controls, but one of my favorite new controls is the NSCollectionView. This control works a lot like the FlowLayoutPanel if you're familiar with Windows Presentation Foundation (WPF). It essentially is a layout container responsible for laying out a collection of subviews. You can either manually create the subview collection, or you can set the content array of the NSCollectionView. This is a really powerful option because if you can set the content array, you can also bind it. For this demo, I've bound the content array of the NSCollectionView to an array controller. If you follow along (or if you cheat and just download the code), you'll notice that the NSCollectionView subviews automatically request Core Animation layers. This means that, by default, new items fade in as they are added, but you can change that transition using the animations tab of the inspector.

To get started, just create a new Cocoa application. The first thing you do after creating the new Cocoa application is edit the project settings and set Garbage Collection to Required. Why you ask? Well, as a .NET developer, I have taken a blood oath to never write unmanaged code. If I violate this blood oath, I'm fairly certain that it will rip a hole in the fabric of space-time from which none of us will escape. So yeah, make sure GC is Required. The Cocoa application we're building is called MonsterCompendium. Rather than doing some contrived Hello World app, this app forms the basis of an app that a pen-and-paper DM might use to keep track of monsters. Obviously it's ridiculously oversimplified, but you get the idea.

I'm going to assume that you've done some Cocoa programming before (mostly because I don't have enough space to write the tutorial in a single blog post... maybe I should do a screencast?). Create yourself a new class called AppController and give it a method called newMonster and then make sure that you've got a "plus" button on your main window that invokes newMonster. Create a new class called KHMonster (feel free to change the initials so they match your name... or keep my initials if you really like them...). The source code to KHMonster.h and KHMonster.m is listed below. Take special note of the new property syntax and the fact that I've not written any retain/release code:

 #import <Cocoa/Cocoa.h>

@interface KHMonster : NSObject 

{

    NSString *trueName;

int armorClass;

int attackRating;

}

@property(copy, readwrite) NSString *trueName;

@property int armorClass;

@property int attackRating;

@end

And here's the implementation (.m) code:

 #import "KHMonster.h"

@implementation KHMonster

@synthesize trueName;

@synthesize armorClass;

@synthesize attackRating;

@end

With that out of the way, you can drag a new NSCollectionView onto your main window. Once you do this, you should notice that you get some extra goodies in your MainMenu.nib tray: an instance called Collection View Item and an NSView that represents the template for a single item within the collection. When you double click the NSView, define an interface that will be bound to a single instance of KHMonster. To do that, you need to set the value of your text fields to be bound to the Collection View Item (this is a special instance that acts like a proxy) with the model root path of : representedObject.trueName. representedObject is a property that points to the object being represented by that particular instance of the collection view item and trueName is a property on the KHMonster class.

In case you're curious, here's the code to the newMonster: method on the AppController class:

#import "AppController.h"

#import "KHMonster.h"

@implementation AppController

- (IBAction)newMonster:(id)sender

{

KHMonster *newMonster = [[KHMonster alloc] init];

newMonster.trueName = [NSString stringWithString:@"New Monster"];

newMonster.attackRating = 12;

newMonster.armorClass = 30;

[monsterArray addObject:newMonster];

}

@end 

Note that I've got an array controller that is serving up instances of the KHMonster class. My AppController instance has an IBOutlet called monsterArray that I've rigged up through Interface Builder to allow the app controller to refer to the array controller as in the preceding code.

Finally, after all the code is together and all the bindings are rigged up, I can run the application. In the screenshot below, you can see me editing a borderless bold text field that contains the monster's name (bound to representedObject.trueName) and a couple labels and some text fields with number formatters in them to allow them to be bound to integers properly. 

And in the next screenshot you see the collection view after editing a couple more items. The reason this is important is to show you that I'm not editing the same thing, but that I am actually working with individual elements within an array. 

If you're familiar with Cocoa, then you know that this sample is only a few minutes worth of work away from being able to run against a local Core Data data source instead of the manual array controller of KHMonster objects.

I highly recommend you download the full sample and then go through the blog post again to see how the sample was created. Once you get the hang of using the NSCollectionView, you'll start to wonder how you ever lived without it. The keys to remember are:

• If you are going to turn on Garbage Collection, you have to do it for every build config such as Debug and Release. The change will not automatically propagate from your debug config to your release config.
• Remember representedObject. It is your friend. It's better than your friend, except it doesn't buy you beer. Since your friend probably doesn't buy you beer anyway, representedObject is definitely better than your friend.

tags: cocoa  bindings  nscollectionview  leopard  apple  mac  osx  

links: digg this    del.icio.us    technorati    reddit