NSCollectionView Tutorial for Dummies (Xcode 3.1.3)

Note: I wrote this tutorial since I believe that there are way too few resources on the net covering this topic and I would have been wasting way less time if I had found something like this. Please keep in mind that I’m a ObjC-beginner myself.

Introduction

This tutorial is written in a way that it doesn’t require much knowledge of cocoa/objective-c, but since I’m not explaining most of the code, programming experiences will be helpful to understand what you are doing.

The following things will be covered by this tutorial:

• designing a user interface with buttons and a NSCollectionView
• designing a Subview which should be displayed in the CollectionView
• feeding the CollectionView using an ArrayController
• making the items in the CollectionView selectable

This is what the final application at the end of the tutorial will look like:

Getting Started

Let’s start off by creating a fresh project and opening up the MainMenu.nib. Next drag a Collection View from the Library to the main view. It can be found under Library->Cocoa->Views & Cells->Data Views->Collection View.

Do the same with 2 buttons which you can get from Library->Cocoa->Views & Cells->Buttons. Give them a label(“add” and “remove”) by clicking them twice.

Your window should now look similar to this:

Also we’ll be needing a Window Controller: To add it go to Library->Cocoa->Objects & Controllers->Controllers and drag an Object into the Document Window. While having it selected in the Document Window, go to the Identity tab of the Inspector and change the class name to something like “WindowController”.

Keep it selected and go to File->Write Class Files, accept to save the “WindowController.m” and to create a “WindowController.h”. Now you should be able to see those 2 files in Xcode. Open up the “WindowController.h” which should look like this:

#import < Cocoa /Cocoa.h>

@interface WindowController : /* Specify a superclass (eg: NSObject or NSView) */ {

}

@end

As you can see we’ll have to specify the superclass of our WindowController to do this replace the comment with NSWindowController, save and in the Interface Builder select File->Reload All Class Files.

Setting Up The Bindings

Now that we’re done with the basic interface, let’s connect the controls to our WindowController.

To do this select the WindowController and open the Identity tab in the Inspector.

Here add two class actions(addAction and removeAction) and one class outlet collectionView of the type NSCollectionView as seen on the left.

Finally, go to File->Write Class File and merge the changes.

Our WindowController should now look like this:

WindowController.h

#import < Cocoa /Cocoa.h>

@interface WindowController : NSWindowController {
    IBOutlet NSCollectionView *collectionView;
}
- (IBAction)addAction:(id)sender;
- (IBAction)removeAction:(id)sender;
@end

WindowController.m

#import "WindowController.h"

@implementation WindowController
- (IBAction)addAction:(id)sender {

}

- (IBAction)removeAction:(id)sender {

}
@end

Go back to the Interface Builder and hold the Ctrl-key while “drawing” a line from the add button to the WindowController(in the Document Window).

Release the mouse over the WindowController and select “addAction”. The function addAction is now being called whenever the add button is clicked. Repeat this for the remove button and its corresponding removeAction.

Now we’ll be doing the same just the other way around: Draw a line from the WindowController to the CollectionView and select “collectionView”. Do the same with the background of the window and connect it to “window”. This will make both the window and the CollectionView accessible from our WindowController.

If you would like to see what connections have been made you could right-click for example on the WindowController and should see this:

Designing the NSCollectionViewItem

Next up, we would like to design the interface of an item in our CollectionView. Therefore, go to Xcode and select File->New File->View XIB, name it however you like(f.e. collectionItem) and open it up in Interface Builder.

Make the View a little bit smaller – I chose 150×150(you can set that in the Size tab of the Inspector).

Drag a Label(Library->Cocoa->Views & Cells->Inputs & Values) and a Segmented Control(same place as the Label) onto the view. Change the text of the label to “Joe”, change the number of segments of the Segmented Control(Attributes tab of the Inspector) to ‘2’ and change their labels to “male” and “female”. This it what you should have got:

Setting Up the Bindings of the CollectionViewItem

First change the Class Identity of the File’s Owner(in the Document Window) to “CollectionItem”(in the Identity tab of the Inspector). At the same place add a Class Action “updateGender” and two Class Outlets gender(NSSegmentedControl) and name(NSTextField):

Now you should go to File->Write Class Files. In the “CollectionViewItem.h” you’ll have to specify the superclass of the CollectionItem(remember the WindowController.h?) . This time we want to extend NSCollectionViewItem so you need to put that there instead of the comment:

CollectionItem.h

#import < Cocoa /Cocoa.h>

@interface CollectionItem : NSCollectionViewItem {
    IBOutlet NSSegmentedControl *gender;
    IBOutlet NSTextField *name;
}
- (IBAction)updateGender:(id)sender;
@end

CollectionItem.m

#import "CollectionItem.h"

@implementation CollectionItem
- (IBAction)updateGender:(id)sender {

}
@end

Now all that’s left for us to do in this view is to connect File’s owner with the text field(name) and with the seg-control(gender), the seg-control with the File’s owner(updateGender) and finally the File’s owner with the view itself(view – click in the background).

Make the CollectionItem load its Interface

Everytime we add a new CollectionItem to the CollectionView a new subinterface has to be loaded(the collectionItem.xib). To do this we’ll have to add the copyWithZone method to our CollectionItem:

CollectionItem.h

#import < Cocoa /Cocoa.h>

@interface CollectionItem : NSCollectionViewItem {
    IBOutlet NSSegmentedControl *gender;
    IBOutlet NSTextField *name;
}
- (IBAction)updateGender:(id)sender;
- (id)copyWithZone:(NSZone *)zone;
@end

CollectionItem.m

#import "CollectionItem.h"

@implementation CollectionItem
- (IBAction)updateGender:(id)sender {

}

-(id)copyWithZone:(NSZone *)zone
{
	id result = [super copyWithZone:zone];

	[NSBundle loadNibNamed:@"collectionItem" owner:result];

	return result;
}
@end

Where @”collectionItem” refers to the name of the “collectionItem.xib”.

Adding an ArrayController

To be able to feed the CollectionView with items we’ll need to add an ArrayController.
To do that go to our MainMenu.xib in Interface Builder and drag an ArrayController(Library->Cocoa->Objects & Controllers->Controllers) to the Document Window.

This might also be a good moment to change the Class Identity of the Collection View Item(which has been automatically created when we added the NSCollectionView)  from NSCollectionViewItem to “CollectionItem”.

In Xcode open the WindowController.h and add the outlet arrayController, the mutableArray collection and the property collection:

WindowController.h

#import < Cocoa /Cocoa.h>

@interface WindowController : NSWindowController {
    IBOutlet NSCollectionView *collectionView;
	IBOutlet NSArrayController *arrayController;

	NSMutableArray* collection;
}
- (IBAction)addAction:(id)sender;
- (IBAction)removeAction:(id)sender;

- (void) awakeFromNib;

@property (copy) NSArray* collection;

@end

In the CollectionItem.m the method awakeFromNib needs to implemented and a synthesize statement needs to be added:

WindowController.m

#import "WindowController.h"

@implementation WindowController

@synthesize collection;

- (IBAction)addAction:(id)sender {

}

- (IBAction)removeAction:(id)sender {

}

- (void) awakeFromNib {

	collection = [[NSMutableArray alloc] init];
	NSSize size = NSMakeSize(150, 150);
	[collectionView setMinItemSize:size];
	[collectionView setMaxItemSize:size];
}

@end

Save and switch to the Interface Builder where you should reload the class files(File->Reload All Class Files).
Select the ArrayController and in the Bindings Pane of the Inspector and under “Content Array” set “Bind to:” to “Window Controller” and the “Model Key Path” to controller(as we named the property earlier).

Hold Ctrl and draw a line from the WindowController to the ArrayController and bind it to “arrayController”.
We’re almost done all that’s left to do is to connect the CollectionView to the Array:
Click on the CollectionView multiple times and make sure it really is the CollectionView and not the ScrollView surrounding it. Go to the Bindings tab and bind “Content” to the ArrayController with arrangedObjects as the “Controller Key”. Also bind “Selection Indexes” to the ArrayController with the “Controller Key” set to “selectionIndexes”.

Finally: Adding items to the CollectionView

The time has come to implement the addAction in the WindowController and take our application for a test run.

Open up the WindowController.m in Xcode and copy over the body of the addAction method:

- (IBAction)addAction:(id)sender {
	int index = [[arrayController arrayController ">arrangedObjects] count];
	[arrayController insertObject: [NSDictionary dictionaryWithObjectsAndKeys:@"Jon", @"Name", @"Male", @"Gender",nil] atArrangedObjectIndex:index];
}

- (IBAction)removeAction:(id)sender {
 	int index = [[arrayController arrangedObjects] count];
	if ( index > 0) {
		index--;
		[arrayController removeObjectAtArrangedObjectIndex:index];
	}
}

Now you can finally start and play with it. Even though it doesn’t do much yet, I hope you can already see how much potential and how many use cases the CollectionView actually has. At least that’s what I thought when I played around with it for the first time.

Just for you to check if you did everything the way I described it(at least how I tried to):

Enuf with the Joes

Now we want to have other names than Joe.

We’ll start by adding a new class(File->New File->Objective-C class) and name it “Person.m”:

Person.h

#import < Cocoa /Cocoa.h>

@interface Person : NSObject {

}

+ (NSString*)getRandomMaleName;
+ (NSString*)getRandomFemaleName;
+ (NSString*)getRandomGender;

@end

Person.m

#import "Person.h"
#include < stdlib .h>

@implementation Person

+ (NSString*)getRandomMaleName {
	NSMutableArray *names = [NSMutableArray NSMutableArray ">arrayWithObjects:@"Jon", @"Steve", @"Benjamin", @"Chris", @"Andre", @"Tom", @"Paul", @"Peter", @"Ron", @"Robert", @"Matthew", @"Max", @"Alex", @"Sebastian", nil];

	int randIndex = arc4random() % [names count];
	return [names objectAtIndex:randIndex];
}

+ (NSString*)getRandomFemaleName {
	NSMutableArray *names = [NSMutableArray arrayWithObjects:@"Abbey", @"Alice", @"Cindy", @"Chrissy", @"Gina", @"Hannah", @"Lena", @"Lilli", @"Linda", @"Monica", @"Nadine", @"Nancy", @"Theresa", @"Tiffany", nil];

	int randIndex = arc4random() % [names count];
	return [names objectAtIndex:randIndex];
}

+ (NSString*)getRandomGender {
	NSMutableArray *genders = [NSMutableArray arrayWithObjects:@"male", @"female", nil];

	int randIndex = arc4random() % [genders count];
	return [genders objectAtIndex:randIndex];
}

@end

The class Person offers 3 static methods:

• getRandomMaleName: randomly returns a male’s first name
• getRandomFemaleName: randomly returns a female’s first name
• getRandomGender: randomly returns either @”male” or @”female”

Now we can slightly modify the addAction in the WindowController.m to generate a random name for a random gender when adding the item:

Add the following line at the top of the file:

#import "Person.h"

Add copy over the body of the addAction method:

- (IBAction)addAction:(id)sender {
	int index = [[arrayController arrayController ">arrangedObjects] count];
	NSString *gender = [Person getRandomGender];
	NSString *name;

	if ([gender isEqualToString:@"male"]) {
		name = [Person getRandomMaleName];
	} else {
		name = [Person getRandomFemaleName];
	}

	[arrayController	insertObject: [NSDictionary dictionaryWithObjectsAndKeys:
										name,		@"Name",
										gender,		@"Gender",
										nil]
						atArrangedObjectIndex:index];
}

But our CollectionItem doesn’t use the supplied informations yet, so we’ll add the method setRepresentedObject in CollectionItem. Also we’ll implement the updateGender method which gets called whenever you click on the segmented control:

CollectionItem.h

#import < Cocoa/ Cocoa.h>

@interface CollectionItem : NSCollectionViewItem {
    IBOutlet NSSegmentedControl *gender;
    IBOutlet NSTextField *name;
}
- (IBAction)updateGender:(id)sender;
- (id)copyWithZone:(NSZone *)zone;
- (void)setRepresentedObject:(id)object;

@end

CollectionItem.h

#import "CollectionItem.h"
#import "Person.h"

@implementation CollectionItem
- (IBAction)updateGender:(id)sender {
	NSString *newName;
    switch ([gender	selectedSegment]) {
		case 0:
			NSString ">newName = [Person getRandomMaleName];
			break;
		default:
			newName = [Person getRandomFemaleName];
			break;
	}

	[name setStringValue:newName];
}

-(id)copyWithZone:(NSZone *)zone
{
	id result = [super copyWithZone:zone];

	[NSBundle loadNibNamed:@"collectionItem" owner:result];

	return result;
}

- (void)setRepresentedObject:(id)object {
	[super setRepresentedObject:	object];

	if (object == nil)
		return;

	NSDictionary* data	= (NSDictionary*) [self representedObject];
	NSString* newName	= (NSString*)[data valueForKey:@"Name"];
	NSString* newGender	= (NSString*)[data valueForKey:@"Gender"];

	[name setStringValue:newName];

	if ([newGender isEqualToString:@"male"]) {
		[gender setSelectedSegment:0];
	} else {
		[gender setSelectedSegment:1];
	}
}

@end

You can now compile & run the application.

Making the Items Selectable

To make the items selectable open the main interface(mainMenu.xib) in Interface Builder and while having the CollectionView selected go to the Attributes tab and enable “Selectable”.

Now our items are selectable, but we don’t see when they are yet. We’ll have to change the background color when an item is being selected.

Here’s how:  Open the collectionItem.xib and select the View in the Document Window. Change its Class Identity(Identity tab) to NSBox.

Next add those two functions to the CollectionItem.m:

- (void)setSelected:(BOOL)flag {
	[super setSelected:	flag];

	NSBox *view	= (NSBox*) [self view];
	NSColor *color;
	NSColor *lineColor;

	if (flag) {
		color		= [NSColor selectedControlColor];
		lineColor	= [NSColor blackColor];
	} else {
		color		= [NSColor controlBackgroundColor];
		lineColor	= [NSColor controlBackgroundColor];
	}

	[view setBorderColor:lineColor];
	[view setFillColor:color];
}

- (void) awakeFromNib {
	NSBox *view	= (NSBox*) [self view];
	[view setTitlePosition:NSNoTitle];
	[view setBoxType:NSBoxCustom];
	[view setCornerRadius:8.0];
	[view setBorderType:NSLineBorder];
}

That’s it!

BTW: You can also use the arrow keys.

Conclusion

That’s all I wanted to show in this tutorial. I hope you enjoyed it, even though the final app doesn’t do anything useful. It’s main purpose was to show how the NSCollectionView works and what can be done with it. The cool thing about the CollectionView is that you can dynamically create a set of views that can be customized for its purpose and create a nice user experience.

The final source code can be downloaded here.

One last thing: If you want to know what item is currently selected use [collectionView selectionIndexes] which returns a NSIndexSet.

Feel free to leave suggestions or the like in the comments.