In this article we'll look at the old NSCell based way and in a future article we'll look at the new 10.7 way and the other things that can be done with it. Our application will eventually look something like this, with each cell holding an image and two lines of text:
We'll start a new Cocoa application project in XCode and create a new class that derives from NSTextFieldCell. In our interface definition we'll add iVars for the second row of text and the image. The first row of text is handled by the NSTextField parent class.
@interface CustomCell : NSTextFieldCell {
@private
NSImage *image;
NSString *subtitle;
}
@property (readwrite, retain) NSImage *image;
@property (readwrite, copy) NSString *subtitle;
@end
Nothing too odd there. In the implementation we synthesize the iVars like normal, and don't need anything in the init method. The reference documentation for NSCell says that when subclassing it we need to implement four initialiser functions, init, initWithCoder:, initTextCell: and initImageCell: but we're subclassing NSTextFieldCell which takes care of that for us. One thing we do need to implement however is copyWithZone: as NSTableView likes to copy cells around.
- (id)copyWithZone:(NSZone *)zone
{
CustomCell *cell = [super copyWithZone:zone];
if (cell == nil) {
return nil;
}
// Clear the image and subtitle as they won't be retained
cell->image = nil;
cell->subtitle = nil;
[cell setImage:[self image]];
[cell setSubtitle:[self subtitle]];
return cell;
}
When the cell is copied, the subtitle NSString and the NSImage will be copied with it however they won't be correctly retained. Therefore we need to set them to nil directly, before setting them because if we just called setImage: or setSubtitle: nothing would happen as we would be setting the same memory addresses. Similarly we need to access the values directly with -> for if we called [cell setImage:nil] the first thing it would do would be to release the old value which didn't have a matching retain and so would lead to a zombie object somewhere down the line.
The other method that we have to implement is drawInteriorWithFrame:inView:. This is where we do our drawing, one piece at a time. The most complicated part of this is working out where each bit goes. We will look at the functions that calculate the appropriate bounds further on below, first lets look at the drawing code.
- (void)drawInteriorWithFrame:(NSRect)cellFrame inView:(NSView *)controlView
{
NSRect imageRect = [self imageRectForBounds:cellFrame];
if (image) {
[image drawInRect:imageRect
fromRect:NSZeroRect
operation:NSCompositeSourceOver
fraction:1.0
respectFlipped:YES
hints:nil];
} else {
NSBezierPath *path = [NSBezierPath bezierPathWithRect:imageRect];
[[NSColor grayColor] set];
[path fill];
}
NSRect titleRect = [self titleRectForBounds:cellFrame];
NSAttributedString *aTitle = [self attributedStringValue];
if ([aTitle length] > 0) {
[aTitle drawInRect:titleRect];
}
NSRect subtitleRect = [self subtitleRectForBounds:cellFrame forTitleBounds:titleRect];
NSAttributedString *aSubtitle = [self attributedSubtitleValue];
if ([aSubtitle length] > 0) {
[aSubtitle drawInRect:subtitleRect];
}
}
First off we draw the image, if it exists, or a grey square if it doesn't. The method to get the image's bounds is quite simple.
#define BORDER_SIZE 5
#define IMAGE_SIZE 64
- (NSRect)imageRectForBounds:(NSRect)bounds
{
NSRect imageRect = bounds;
imageRect.origin.x += BORDER_SIZE;
imageRect.origin.y += BORDER_SIZE;
imageRect.size.width = IMAGE_SIZE;
imageRect.size.height = IMAGE_SIZE;
return imageRect;
}
You'll notice that we don't clip imageRect to the bounds that are passed in. To do so would complicate the drawing of the image, because we want the image to always be drawn at 64x64, so if we clip the image rectangle, we need to also work out what part of the image needs drawn into that rectangle. There is nothing complicated in this method, we simply set the origin of the image to be BORDER_SIZE pixels away from the cell's bounds and set the size of the image to IMAGE_SIZE.
Next in the drawing method we work out where the first line of text is going to go:
- (NSRect)titleRectForBounds:(NSRect)bounds
{
NSRect titleRect = bounds;
titleRect.origin.x += IMAGE_SIZE + (BORDER_SIZE * 2);
titleRect.origin.y += BORDER_SIZE;
NSAttributedString *title = [self attributedStringValue];
if (title) {
titleRect.size = [title size];
} else {
titleRect.size = NSZeroSize;
}
CGFloat maxX = NSMaxX(bounds);
CGFloat maxWidth = maxX - NSMinX(titleRect);
if (maxWidth < 0) {
maxWidth = 0;
}
titleRect.size.width = MIN(NSWidth(titleRect), maxWidth);
return titleRect;
}
This method is slightly more complicated as this time we do need to clip the text bounds to the cell bounds and we need to limit the text width to the amount of space that is left in the cell after the image has been taken into consideration.
Finally we layout the second line of text. It needs the same clipping as the first line, but it also needs to know the bounds of the first line so that it can calculate it's origin correctly.
- (NSRect)subtitleRectForBounds:(NSRect)bounds forTitleBounds:(NSRect)titleBounds
{
NSRect subtitleRect = bounds;
if (!subtitle) {
return NSZeroRect;
}
subtitleRect.origin.x = NSMinX(titleBounds);
subtitleRect.origin.y = NSMaxY(titleBounds) + BORDER_SIZE;
CGFloat amountPast = NSMaxX(subtitleRect) - NSMaxX(bounds);
if (amountPast > 0) {
subtitleRect.size.width -= amountPast;
}
return subtitleRect;
}
The only other method that is missing is the attributedSubtitleValue method, which allows us to have the text of the second line drawn in a shade of grey.
- (NSAttributedString *)attributedSubtitleValue
{
NSAttributedString *astr = nil;
if (subtitle) {
NSColor *textColour = [self isHighlighted] ? [NSColor lightGrayColor] : [NSColor grayColor];
NSDictionary *attrs = [NSDictionary dictionaryWithObjectsAndKeys:textColour,
NSForegroundColorAttributeName, nil];
astr = [[[NSAttributedString alloc] initWithString:subtitle attributes:attrs] autorelease];
}
return astr;
}
And that is our cell. Now we need to connect it up so that the NSTableView will display it instead of the default text cell. In our simple application, we have dragged an NSTableView into the window, turned off headers and set the number of columns to 1.
To tell Cocoa to display our custom cell select the cell in the NSTableView and in the Class section of the Identify Inspector enter the name of the cell class. Make sure you've selected the cell, to select it you will need to click a few times on the NSTableView. The first click will select the scrollview, the second will select the NSTableView, 3rd will select the column, then another click on the cell will select it.
One final thing we need to do is to set the size of the row. If we were using Lion's NSView mode for our NSTableView cells, then it would be possible for the NSTableView to calculate the size automatically, but as we are using the old fashioned NSCell mode we need to set it explicitly. This is set in the Size Inspector by selecting the NSTableView. For our example the height of the NSCell is the height of the image plus two borders, which works out as 74.
If you look closely you'll see that the model item needs to implement the NSCopying protocol. This is because we will be returning the item as the object for the cell, and somewhere in the depths of Cocoa this will be copied. To copy the item though, we'll just create a new one:
In the application delegate we need to create the model, creating an NSMutableArray in the init method and filling it with our model items.
To tell Cocoa to display our custom cell select the cell in the NSTableView and in the Class section of the Identify Inspector enter the name of the cell class. Make sure you've selected the cell, to select it you will need to click a few times on the NSTableView. The first click will select the scrollview, the second will select the NSTableView, 3rd will select the column, then another click on the cell will select it.
One final thing we need to do is to set the size of the row. If we were using Lion's NSView mode for our NSTableView cells, then it would be possible for the NSTableView to calculate the size automatically, but as we are using the old fashioned NSCell mode we need to set it explicitly. This is set in the Size Inspector by selecting the NSTableView. For our example the height of the NSCell is the height of the image plus two borders, which works out as 74.
We need a model object to display the tableview:
@interface CellInfo : NSObject <NSCopying> {
@private
NSString *title;
NSString *subtitle;
NSImage *image;
}
@property (readwrite, retain) NSString *title;
@property (readwrite, retain) NSString *subtitle;
@property (readwrite, retain) NSImage *image;
- (id)initWithTitle:(NSString *)_title subtitle:(NSString *)_subtitle image:(NSImage *)_image;
@end
If you look closely you'll see that the model item needs to implement the NSCopying protocol. This is because we will be returning the item as the object for the cell, and somewhere in the depths of Cocoa this will be copied. To copy the item though, we'll just create a new one:
- (id)copyWithZone:(NSZone *)zone
{
CellInfo *cellInfo = [[CellInfo alloc] initWithTitle:[self title]
subtitle:[self subtitle]
image:[self image]];
return cellInfo;
}
In the application delegate we need to create the model, creating an NSMutableArray in the init method and filling it with our model items.
cellInfos = [[NSMutableArray alloc] init];
for (int i = 0; i < 10; i++) {
CellInfo *ci = [[CellInfo alloc] initWithTitle:@"Custom Cell"
subtitle:[NSString stringWithFormat:@"Row number %d", i + 1]
image:[NSImage imageNamed:NSImageNameApplicationIcon]];
[cellInfos addObject:ci];
[ci release];
}
The application delegate should needs to implement the NSTableViewDataSource and NSTableViewDelegate protocols.
@interface CustomCellAppDelegate : NSObject <NSApplicationDelegate, NSTableViewDataSource, NSTableViewDelegate>
There are a number of different ways to get the data into the view, but for this example we will use the NSTableViewDataSource. We could use bindings but bindings only allow one value to be set on a cell whereas we need three so we would still need to use the data source protocol for the other two.
At a minimum for NSTableViewDataSource we need to implement two methods; numberOfRowsInTableView: and tableView:objectViewForTableColumn:row:
- (NSInteger)numberOfRowsInTableView:(NSTableView *)tableView
{
return [cellInfos count];
}
- (id)tableView:(NSTableView *)tableView
objectValueForTableColumn:(NSTableColumn *)tableColumn
row:(NSInteger)row
{
return [cellInfos objectAtIndex:row];
}
But this doesn't set the values on the cell. For this we need to implement an NSTableViewDelegate method; tableView:willDisplayCell:forTableColumn:row:. This method gives us the cell that is going to be displayed, and tells us what row it is, so we can get the object from the model and set the appropriate values on the cell.
- (void)tableView:(NSTableView *)tableView
willDisplayCell:(id)cell
forTableColumn:(NSTableColumn *)tableColumn
row:(NSInteger)row
{
CellInfo *info = [cellInfos objectAtIndex:row];
CustomCell *cCell = (CustomCell *)cell;
[cCell setImage:[info image]];
[cCell setTitle:[info title]];
[cCell setSubtitle:[info subtitle]];
}
Now finally we just need to set the application delegate as the dataSource and delegate for the NSTableView in Interface Builder by ctrl-dragging from the NSTableView onto the application delegate object twice. The first time selecting dataSource, and the second time selecting delegate.
And there you have it, a custom NSCell for NSTableViews. In the future we'll look at the Lion NSView version of this, and see the extra things that it can do for us.
