Yet Another Learn Cocoa With Me Blog

CoreAudio

2013-01-02T20:28:00.002+00:00

I recently finished reading Learning CoreAudio by Chris Adamson and Kevin Avila, and for anyone looking at working with CoreAudio it is invaluable. Chris and Kevin take you through the complexities of the various CoreAudio APIs in a simple to understand way with a lot of very good examples. It is highly recommended.

It covers from the basics of AudioQueues right down to the lowlevel AudioUnit API, and also covers CoreMIDI and OpenAL on both OSX and iOS.

NSScrollView and CoreLayout

2013-01-02T20:03:00.001+00:00

Recently I've been trying to convert an application to use CoreLayout and one of the problems I ran into was with getting content to correctly fill an NSScrollView.

I have an NSView subclass which lays out its subviews in a vertical list using constraints and while the height of the layout is obviously dependent on the combined height of the subviews (plus spacing) the children don't have any intrinsic width and so are dependent on the width the parent class gave them. Ultimately, this was the width which the NSScrollView gives, but the problem was that the NSScrollView wanted to give them 0 width.

The solution I came up with is to add a constraint to the NSClipView which sits inbetween the NSScrollView and my layout view like so:

[_layout setTranslatesAutoresizingMaskIntoConstraints:NO];
[_scrollView setDocumentView:_layout];

NSClipView *clipView = [_scrollView contentView];
NSDictionary *viewsDict = @{@"layout":_layout};

// Add our new constraint that will fix the sides of _layout
// to the sides of its parent, which in this case is clipView
[clipView addConstraints:[NSLayoutConstraint constraintsWithVisualFormat:@"|[layout]|" options:0 metrics:nil views:viewsDict]];

It was surprisingly easy once I realised that I could add constraints like this. Hopefully this will help some people if they run into issues like this.

Custom cells in NSTableView (Part 1 - The NSCell version)

2011-09-15T01:49:00.000+01:00

Before OSX 10.7 there was only one way of creating a custom cell: to subclass NSCell and do layout and drawing by hand. This is quite an awkward way as you can no longer use Interface Builder to create the layout and is potentially error prone. Then in Lion, the ability was added to use subclasses of NSViews for the cells, which means that they can be designed and laid out in Interface Builder and more complex bindings can be created.

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.

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.

Reading from external controllers with CoreMIDI

2011-08-21T21:40:00.001+01:00

As a relative newcomer to Cocoa and OSX some of Cocoa's frameworks seem very good, some I've looked at are what I expected, but recently I had to do some MIDI work and frankly, CoreMIDI is just weird and confusing. The documentation is limited, to say the least, and really not what I've come to expect from Apple. But I got what I needed done and so this post, more than some others, is to serve two purposes. One, to help me remember what I worked out, and two, maybe it'll help someone else.

I have a few MIDI controllers lying around, and what I wanted to do was to read the MIDI data as the various knobs and faders and buttons are manipulated and have it tell me what was happening.

In CoreMIDI we create input and output ports, and connect them to other ports or endpoints. For our case we want to create an input port, and connect this to the external MIDI controller. When we create an input port we also give it a callback function that will get called when the MIDI controller sends data.

The first step to create an input port is to create a MIDIClient

MIDIClientRef midiClient;

OSStatus result;

result = MIDIClientCreate(CFSTR("MIDI client"), NULL, NULL, &midiClient);

if (result != noErr) {

NSLog(@"Error creating MIDI client: %s - %s",

GetMacOSStatusErrorString(result),

GetMacOSStatusCommentString(result));

return;

}

The first parameter gives the MIDIClient a name and as we're working with CoreFoundation here we use the CFSTR macro. The second and third parameters are for receiving notifications when the MIDI system changes, but we don't care about that here and so just pass NULL. The final parameter is for obtaining our MIDIClientRef. A lot of the CoreMIDI functions return OSStatus to indicate success or failure, and it's a good idea to check there wasn't any errors before continuing. In the following code snippets, I'll leave out the error checking as it's the same as the check above to save space, but it is present in the example code.

Once we have a MIDIClient, we can then create an input port.

MIDIPortRef inputPort;

result = MIDIInputPortCreate(client, CFSTR("Input"), midiInputCallback, NULL, &inputPort);

The first parameter it takes is our MIDIClientRef that we created earlier, and the second is the name of the port. At the end, the final parameter is for obtaining our newly created port. The third and fourth parameters are the callback for whenever there is MIDI data available on the port. The third is the function and the fourth is data that will be passed into that function as context. Here we don't have any context data, but in a more complicated objective C program we would pass usually pass self or some other object. It is in this callback that the MIDI parsing happens. Care needs to be taken as it is also called on a separate, high priority thread, which means that any data access needs to be done in a thread safe manner, and any UI updating needs to be triggered on the main UI thread using performSelectorOnMainThread.

So what does this callback function look like then? Something like this:

static void

midiInputCallback (const MIDIPacketList *list,

void *procRef,

void *srcRef)

{

NSLog(@"midiInputCallback was called");

}

We'll go into detail about what goes into it, and what the various parameters are for later, as first I want to get the rest of the ports hooked up.

So we want to get an endpoint on the external MIDI device and functions such as MIDIGetSource seem perfect for it, but they take an index to where the device is in the system. This is useful when you want to offer a list of devices for the user to choice the device from, but makes things more complicated for us. For this initial example we're going to use MIDIObjectFindByUniqueID but it needs a unique ID. To get this we need a helper program first.

A Brief Interlude

Make a new command line project, I called it MidiLister. Basically it is going to list all the MIDI devices and print their Unique IDs. First we need to add the CoreMIDI framework to it. If you select the MidiLister target, and go to the Build Phases page. Then in the section titled Link Binary With Libraries, click the plus symbol, type coremidi and select it.

Now in the main.m file import CoreMIDI/CoreMIDI.h and add the following code to the main function:

ItemCount numOfDevices = MIDIGetNumberOfDevices();

for (int i = 0; i < numOfDevices; i++) {

MIDIDeviceRef midiDevice = MIDIGetDevice(i);

NSDictionary *midiProperties;

MIDIObjectGetProperties(midiDevice, (CFPropertyListRef *)&midiProperties, YES);

NSLog(@"Midi properties: %d \n %@", i, midiProperties);

}

We're getting all the MIDI devices that the system knows about, and printing out their properties. If you build, run it, and look at the output somewhere in the output will be the MIDI device you want to use, and it will print something like this

entities = (

{

destinations = (

{

uniqueID = "-2123048758";

}

);

embedded = 0;

maxSysExSpeed = 3125;

name = LPD8;

sources = (

{

uniqueID = 1759718006;

}

);

uniqueID = "-2133248137";

}

);

image = "/Library/Audio/MIDI Devices/Generic/Images/USBInterface.tiff";

manufacturer = "AKAI professional LLC";

model = LPD8;

name = LPD8;

There may be a lot of devices and there are quite a lot of unique IDs for each device, each entity has a one and the device has one of its own. Which one do we want? Well, if you look through the output for something related to the MIDI controller you want to use. I knew that the model name for my controller was the Akai LPD8, and in this case we're wanting to receive data from the controller, so we want to use a source entity. This device only has one source, and its UniqueID is 1759718006. It will probably be different on your machine and for your controllers. Write the UniqueID down, and go back to the original project.

Now that we can use MIDIObjectFindByUniqueID to get the endpoint to use with this.

MIDIObjectRef endPoint;

MIDIObjectType foundObj;

result = MIDIObjectFindByUniqueID(1759718006, &endPoint, &foundObj);

Obviously in the above code, you should replace the uniqueID with the one for your device. We don't actually care about the foundObj, what we're interested in is the endPoint parameter and once we have that, we can link the input port that we created earlier to this endpoint.

result = MIDIPortConnectSource(inputPort, endPoint, NULL);

This function is quite straight forward, it connects the port that we created earlier (inputPort) to the end point that we got from our device (endPoint) and the last parameter is for some context data. Finally by adding a CFRunLoop so that any input events will be processed we will see that our callback is triggered whenever you do something on the MIDI controller.

CFRunLoopRun();

Processing MIDI Events

Now that we have a program that can read MIDI events, we need to work out what the MIDI data is actually telling us. Unfortunately CoreMIDI is only used for configuring, sending and receiving MIDI data, it doesn't have anything to help with creating or parsing that MIDI data. Luckily the upside is that MIDI is a very simple protocol and there are various places online that describe it (without you needing to spend big bucks on the official MIDI spec). CoreMIDI passes the data to our callback function in a MIDIPacketList. Remember this was our callback function's protocol:

static void

midiInputCallback (const MIDIPacketList *list,

void *procRef,

void *srcRef)

The MIDIPacketList parameter contains all the data related to the control change, and the two void * parameters are two pieces of context data. The first (procRef) is the context data that was set when the port was created via MIDIInputPortCreate, the second (srcRef) is the context data that was set when the port was connected to the endpoint with MIDIPortConnectSource.

To process a MIDIPacketList we iterate through the list, processing the MIDIPackets that are contained in it. A MIDIPacket contains at least one complete MIDI message, except for Sysex messages which can be spread over multiple packets.

A MIDI message consists of a status byte, and then fixed number of bytes, depending on the message (apart from SysEx messages again but we'll ignore them for now). The high bits of the status byte tell us the message type, and the low bits tell us the channel number. So, for example, the status 0x83 tells us that a Note Off message was received from channel 4 (in MIDI messages the channels are numbered from 0-F, but in MIDI terminology they are numbered from 1-16, so 3 is really the fourth channel).

To find out the length of each message, http://home.roadrunner.com/~jgglatt/tech/midispec.htm is a pretty good guide. Looking at the 0x83 message again, we can see that Note Off has 2 bytes of data afterwards. This way we can iterate over the data contained in the MIDIPacket finding all the messages and acting on them.

As mentioned above, the exception to all this is the SysEx message. This message starts with 0xF0 (SysEx Start) and all the following data until the message 0xF7 (SysEx End) is part of the SysEx message. This means it could be over multiple MIDIPackets, but all the data for a SysEx message will not be spread over multiple MIDIPacketLists. Also, if there is a SysEx message in a MIDIPacket there will not be any other messages in that MIDIPacket. This simplifies processing SysEx messages considerably.

Here is an example of how you could process some MIDI messages in the midiInputCallback function. I'm not claiming this is perfect ands there's probably lots of places where it could be improved. If you know an improvement or spot an error, feel free to leave a comment.

#define SYSEX_LENGTH 1024

We define a maximum length for a SysEx message.

void midiInputCallback (const MIDIPacketList *list,

void *procRef,

void *srcRef)

{

bool continueSysEx = false;

UInt16 nBytes;

const MIDIPacket *packet = &list->packet[0];

We get the first MIDIPacket in the list. Although we use ->packet[0] to get the first packet, the other packets are not accessed by ->packet[1], [2] etc. We need to use MIDIPacketNext, as you'll notice at the end of the function.

unsigned char sysExMessage[SYSEX_LENGTH];

unsigned int sysExLength = 0;

This is just a buffer for collecting the SysEx messages.

We start by going through all of the MIDIPackets in the MIDIPacketList

for (unsigned int i = 0; i < list->numPackets; i++) {

nBytes = packet->length;

We want to check if we're gathering a SysEx message that is spread over many MIDIPackets. If it is, then we need to copy the data into the message buffer.

// Check if this is the end of a continued SysEx message

if (continueSysEx) {

unsigned int lengthToCopy = MIN (nBytes, SYSEX_LENGTH - sysExLength);

// Copy the message into our SysEx message buffer,

// making sure not to overrun the buffer

memcpy(sysExMessage + sysExLength, packet->data, lengthToCopy);

sysExLength += lengthToCopy;

Now we've copied the data, we check if the last byte is the SysEx End message.

// Check if the last byte is SysEx End.

continueSysEx = (packet->data[nBytes - 1] == 0xF7);

If we've finished the message, or if we've filled the buffer then we have a complete SysEx message to process. Here we're not doing anything with it, but in a proper application we'd pass it to whatever acts on the MIDI messages.

if (!continueSysEx || sysExLength == SYSEX_LENGTH) {

// We would process the SysEx message here, as it is we're just ignoring it

sysExLength = 0;

}

} else {

If we weren't continuing a SysEx message then we need to iterate over all the bytes in the MIDIPacket parsing the messages that are contained in it.

UInt16 iByte, size;

iByte = 0;

while (iByte < nBytes) {

size = 0;

// First byte should be status

unsigned char status = packet->data[iByte];

if (status < 0xC0) {

size = 3;

} else if (status < 0xE0) {

size = 2;

} else if (status < 0xF0) {

size = 3;

} else if (status == 0xF0) {

// MIDI SysEx then we copy the rest of the message into the SysEx message buffer

unsigned int lengthLeftInMessage = nBytes - iByte;

unsigned int lengthToCopy = MIN (lengthLeftInMessage, SYSEX_LENGTH);

memcpy(sysExMessage + sysExLength, packet->data, lengthToCopy);

sysExLength += lengthToCopy;

size = 0;

iByte = nBytes;

// Check whether the message at the end is the end of the SysEx

continueSysEx = (packet->data[nBytes - 1] != 0xF7);

} else if (status < 0xF3) {

size = 3;

} else if (status == 0xF3) {

size = 2;

} else {

size = 1;

}

unsigned char messageType = status & 0xF0;

unsigned char messageChannel = status & 0xF;

Now we know the size of each message, what type it is, and what channel it was received on and we can pass it off to something that will parse it. For this example, here is some code that just prints the message and the values. Ideally this would happen on a low priority thread so that it doesn't block the thread that receives the MIDI messages, but for this example it doesn't matter too much.

switch (status & 0xF0) {

case 0x80:

NSLog(@"Note off: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);

break;

case 0x90:

NSLog(@"Note on: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);

break;

case 0xA0:

NSLog(@"Aftertouch: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);

break;

case 0xB0:

NSLog(@"Control message: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);

break;

case 0xC0:

NSLog(@"Program change: %d", packet->data[iByte + 1]);

break;

case 0xD0:

NSLog(@"Change aftertouch: %d", packet->data[iByte + 1]);

break;

case 0xE0:

NSLog(@"Pitch wheel: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);

break;

default:

NSLog(@"Some other message");

break;

}

iByte += size;

}

As mentioned above, to get the next MIDIPacket you need to use MIDIPacketNext.

packet = MIDIPacketNext(packet);

}

And thats how you read data from a MIDI controller. Hopefully this is useful to some people.

Apple documentation for CoreMIDI - https://developer.apple.com/library/mac/#documentation/MusicAudio/Reference/CACoreMIDIRef/MIDIServices/

Laying out interfaces automatically with Corelayout Part 2 - Layout Format Language

2011-08-13T14:24:00.001+01:00

In the last post on Corelayout we looked at how you can set up autolayout with the Interface Builder. There are times, however, when the layout needs to be done by hand in the code and in Cocoa there is a layout format language that aims to simplify the process of creating constraints.

This language looks something like "|-20-[button]-20-|". The superview is marked by the pipe symbol '|' and this string tells the Corelayout system that a control called button is placed 20 pixels away from the left and right edges of the superview. To set the vertical layout, the layout string should start with "v:". More complicated constraints can be added to the string as well by adding the rules inside parentheses: "|-20-[button(<=350)]-20-|" will restrict the button width to <= 350 pixels.

Lets make a simple example. First, we'll need a function to create a button

- (NSView *)buttonWithLabel:(NSString *)title

{

NSButton *button = [[[NSButtonalloc] init] autorelease];

[button setBezelStyle:NSRoundedBezelStyle];

[button setTitle:title];

[button setTranslatesAutoresizingMaskIntoConstraints:NO];

return button;

}

Notice that we do not specify a size for the button via initWithFrame: we're just going to leave the button to figure out its own size for itself. This is called its 'intrinsic size'. For a button, its intrinsic height is just enough to display it's child control, you don't normally want a button to be higher than its child control needs to be so we say that it "strongly hugs' it's content vertically, but the intrinsic width of a button can really be anything, so long as it is larger than its content width. In this case we say that it "weakly hugs" it's content horizontally.

The other thing to notice is the call to setTranslatesAutoresizingMaskIntoConstraints:. This call tells Cocoa to ignore the autoresizing mask when working out the constraints as the autoresizing mask may produce a conflicting constraint and we're going to be doing all the constraints ourselves.

As this is a very simple example, the rest of the code is going to go into the applicationDidFinishLaunching: method of the application delegate and it will set up a simple window with 2 buttons in it.

First, we create the buttons and add them to the parent window

NSView *button = [self buttonWithLabel:@"Test button"];

NSView *button2 = [self buttonWithLabel:@"Hello button"];

NSView *view = [window contentView];

[view addSubview:button];

[view addSubview:button2];

The constraints system takes a dictionary so that it can link controls named in the format string to controls. The names in the format string are used as the keys in this dictionary and the function NSDictionaryOfVariableBindings is useful here. It takes a list of objects and creates a dictionary with those objects with the variable names as keys.

NSDictionary *views = NSDictionaryOfVariableBindings(button, button2);

will create a dictionary with the key @"button" that points to the object button, and a key @"button2" which points to the object button2.

Finally we just need to add the constraints to the superview:

[view addConstraints:[NSLayoutConstraint constraintsWithVisualFormat:@"|-20-[button]-[button2]-20-|"

options:NSLayoutFormatAlignAllBaseline

metrics:nil

views:views]];

[view addConstraints:[NSLayoutConstraint constraintsWithVisualFormat:@"V:|-[button]-55-|"

options:0

metrics:nil

views:views]];

The first constraint sets the horizontal layout, and it says that the control called 'button' is to be placed 20 pixels away from the left hand edge of the superview (which in this case is the contentview of the window), and there should be spacing the size of the default Cocoa spacing between it and 'button2', which should in turn be placed 20 pixels away from the right hand edge of the superview. The options parameter says that all the controls should be aligned along their baselines. The final two parameters; metrics and views, are dictionaries that were mentioned above, to allow the layout system to match values in the format string to real controls. We will look at what the metrics parameter does later on.

The next constraint is the vertical one, and it says that 'button' should be placed the Cocoa default spacing away from the top edge of the window, and 55 pixels away from the bottom edge. We don't need to provide any contraints for button2's vertical placement as it has been aligned with the baseline of 'button'.

And that is all that you need to layout a simple window with resizing controls, next we'll look at some more complicated layout strings.

As in the example in the first article, when you resize the window one of the buttons resizes while the other remains fixed in width. To fix this we need to add an equal width constraint to the format string. If you change the format string for the horizontal constraint to "|-20-[button(==button2)]-[button2]-20-|" and recompile it, you will see that when you expand the window, the two button widths match. And, as in the first article, we can control that the first button will stop expanding at 350pixels, with the second button continuing to expand by setting another constraint to the format string and setting the priority: "|-20-[button(==button2@20,<=350)]-[button2]-20-|"

So, as you can see, we can add as many constraints as we need, separated by commas, in parentheses after the identifier. We can also add constraints to the spacings. For an example, lets make the vertical layout have an expandable space between 20 and 50pixels in size before the buttons. To do this, set the vertical constraint layout to:

"V:|-(>=20,<=50)-[button]-55-|"

We skipped over the metrics parameter earlier, but it works similarly to the views parameter. If you pass in a dictionary that maps a metric name to an NSNumber then that name can be used in place of a number. If we created a metrics dictionary like so:

NSNumber *topHeight = [NSNumber numberWithFloat:55.0];

NSDictionary *metrics = NSDictionaryOfVariableBindings(topHeight);

and passed it into the constraintsWithVisualFormat:options:metrics:views method then we can write a format string that refers to topHeight: "V:|-topHeight-[button]-55-|". When the format string is parsed, the key topHeight will be looked up in the metrics dictionary, and the NSNumber will be used instead. As NSNumbers are immutable, it isn't possible to change what a metric represents.

All in all though, the visual format language seems like an interesting way to describe the layout of an interface, and will certainly make laying out interfaces by hand easier for me at least, as I never really liked having to sit down and work out the frame sizes for all the controls before writing the code. I'm sure I've not covered everything, and there's more to discover about Corelayout as I go.

Apple's Auto Layout guide: http://developer.apple.com/library/mac/#documentation/UserExperience/Conceptual/AutolayoutPG/Articles/Introduction.html

NSCollectionView Redux

2011-08-09T23:11:00.002+01:00

In the previous post on NSCollectionView I was unable to build the NSCollectionViewItem's NSView in Interface Builder so I built it by hand. Thanks to a post on Stack Overflow (http://stackoverflow.com/questions/6866798/binding-to-nscollectionviewitem-crashes-xcode/6961261#6961261) I was shown how to do it. So here it is in a fuller example.

Starting with the same data item we had the last time:

@interface Item : NSObject {
NSString *title;
NSInteger option;
}

@property (readwrite, copy) NSString *title;
@property (readwrite) NSInteger option;

- (id)initWithTitle:(NSString *)_title option:(NSInteger)_option;
@end

And creating a model in the application delegate in a similar way

- (id)init

{

self = [super init];

items = [[NSMutableArray alloc] init];

int i;

for (i = 0; i < 20; i++) {

Item *item = [[Item alloc] initWithTitle:@"test" option:i];

[items addObject:item];

}

return self;

}

In the MainMenu.xib when we drag an NSCollectionView into the window, it creates the NSCollectionViewItem and NSView automatically. This time, we only want to delete the NSView as we are going to create a new one.

Create a new file, select View from the User Interface category and name it what you will. In this view we can design our item.

In this nib file, set the class type of the File's Owner to NSCollectionViewItem. This allows us to bind controls to the representedObject property of NSCollectionViewItem.

I bound the value of the label to representedObject.option and the value of the NSTextField to representedObject.title.

NSCollectionViewItem has a view outlet and this is used whenever it is asked which view is the main view. We need to set this by control dragging from the File's Owner placeholder to the Custom View object, and selecting view.

The final thing we need to do is to tell the NSCollectionViewItem which nibfile to load whenever it needs to create a new view. In the MainMenu.xib file, select the Collection View Item and display the Attributes Inspector. In the Nib Name dropdown either type or select the name of the custom View's nibfile.

Just before we build and run, we need to tell the NSCollectionView where to get its data from. Add an NSArrayController to the MainMenu.xib, and bind the content property of the NSCollectionView to the arrangedObjects property of the NSArrayController.

and bind the content array property of the NSArrayController to the model that we created in the application delegate.

Now if you build and run, the collection view should display the custom item:

It is good to know how to do this now, as doing it by hand felt clunky and awkward, especially to make a nice UI.

Links to the other parts of the NSViewController articles
Part 1:- http://comelearncocoawithme.blogspot.com/2011/07/nsviewcontrollers.html
Part 2:- http://comelearncocoawithme.blogspot.com/2011/07/nsviewcontrollers-part-2.html
Part 3:- http://comelearncocoawithme.blogspot.com/2011/08/nsviewcontrollers-part-3.html

Laying out interfaces automatically with Corelayout Part 1

2011-08-07T23:11:00.001+01:00

I come from a GTK background on Linux, so I was surprised to find that Cocoa is a statically laid out UI. GTK has the concept of layout containers and boxes into which you insert controls and tell the box how you want them to be laid out and what to do when the size of the box changes. While it is confusing at first, it very quickly becomes a powerful way to layout a user interface that resizes perfectly when the window or the control size changes. Cocoa has the concept of struts and springs that allow some degree of control over resizing, but it does not give the programmer as much power over window resizing and doesn't handle control resizing at all.

However, the Gtk box model is not perfect, and one of the areas it doesn't work so well is allowing controls to be moved around which complicates animating interfaces which is one area that Cocoa interfaces do very well. So to get around both these problems Apple have added CoreLayout to Lion. Corelayout allows the programmer to add contraints to the interface and describe the relationship between controls and views via these constraints. It is similar to the constraints system used in CoreAnimation but gives the programmer even more control in describing what happens when views change sizes.

Constraints can be created in Interface Builder or in code, however the support in Interface Builder still seems somewhat buggy unfortunately with annoying behaviours and the occasional stack trace dialog. Hopefully future versions will be more stable, the feature seems like it was only added relatively recently to Interface Builder, so save often. We'll first look at how to create constraints in IB, and then move on to creating them by hand in code.

The first thing that needs to be done is to turn on constraints for the nib file. To do this, select the nib file so that the interface builder appears, then click on the file inspector button on the righthand side pane. Then you need to check the option marked "Use Auto Layout".

A warning may come up informing you that you can only run this program on 10.7, but you know that, so just dismiss it.

To demonstrate constraints I just put some simple controls into a window, and drag them until they snap to the blue constraints lines at the edges of the window. These are automatic constraints that are fixed at the correct Cocoa spaces and when the control is snapped to one, it automatically gets constrained. So we expand the second text field to the right until it snaps to the blue constraint line, just the way we did when we created a layout in Cocoa previously, the difference is that now, with CoreLayout turned on, the control is now automatically constrained to always be at that guide line. If we expand the window, the control will move, or expand so that the right hand edge is always the same distance from the window edge.

In the left hand column, under Objects a new object has been added to the hierarchy: "Constraints". If you expand it then you see all the constraints that are present. Ones with a purple icon are automatic constraints, user-added constraints have a blue icon. The default ones for this interface are

We have two vertical spaces, one for each text field that dictates how far the top of the text field is away from the top of the window. We have a horizontal space constraining the left edge of the left text field to the left edge of the window, one doing the same for the right edge of the right text field, and we also have one making the space between the two text field constant as well.

If you select a control, you can see the constraints that act upon it, drawn as lines around it:

and if you select a constraint, then the control (or controls) that are affected by the constraint are highlighted in yellow, and the appropriate constraint line is given a drop shadow to stand out:

There is one final constraint that dictates that the width of the first text field will always be fixed. This means that as the window is expanded in width, the first text field will not expand, but the second will. If you want to test it out, build it and run it, and you can see for yourself. But maybe this default setting is not what you want. Maybe you want both the text fields to expand equally.

Adding Custom Constraints

To do this, you need to add a custom constraint. Select both the text fields, and in Editor->Pin menu select "Widths Equally". If you now look at the constraints list you'll see that the "Width (213)" constraint has been replaced with a "Equal Widths" constraint with a blue icon, and if you select that constraint both text fields turn yellow and the width constraint lines now have an = in a circle on them. Now if you run the program and expand the window, both the fields will expand to fill the space.

But maybe instead of always being equal, you want them to be equal until the left one is 350 pixels wide, and then the right field will keep expanding. So lets add a width constraint to the left hand field. Select it, and in the Editor->Pin menu select "Width". This will add a second user constraint to the field, that says its width must be equal to 213 (or whatever the default width you set). We are able to change the type of the constraint, choosing between equal to, less than or equal to, and more than or equal to. We do this by selecting the constraint and bringing up the Attributes Inspector. If we set the Relation dropdown to "Less than or equal" and set the constant to 350.

(While doing this, you might find that XCode unselects the constraint and reorders the constraints list every time you try to change something. This is quite annoying, but just select the constraint again and continue.)

Now, what happens when you build and run it? If you expand the window, both the text fields will expand until they are 350 pixels wide but then you won't be able to expand the window any more. This is because our two constraints say that the first text field must be less than 350 pixels wide, and that both text fields must be equal width. How can we fix this?

Well, the constraints system has the idea of priority and by default constraints are set to 1,000 which means "Must be fulfilled". If we were to lower one of the priorities to be an optional constraint then it wouldn't need to be fulfilled if it can't be.

So which one should be lowered? Well, the constraint we want to break is the equal width one as we always want the first text field to be less than 350 pixels in width. Set the priority of the "Equal widths" constraint to about 500 and rebuild. Also notice than when a constraint is not "Must be fulfilled" the constraint line becomes broken with dashes.

Now when you build and run, if you expand the window the text fields will remain equal width until the first is 350 and then only the second one will expand.

That's a basic guide to auto layout in Interface Builder. In the next part we'll look at creating constraints in code using the Visual Format Language

Other articles on Corelayout
Part 2:- http://comelearncocoawithme.blogspot.com/2011/08/laying-out-interfaces-automatically_13.html

NSViewControllers part 3 - NSCollectionView

2011-08-02T20:18:00.001+01:00

Previously we looked at NSViewControllers and what they're used for in Appkit. One of the others places they are used is under the hood of NSCollectionView. NSCollectionView is a view that can display a collection of arbitrary views, hooked up to a model. NSCollectionView has a helper class, called NSCollectionViewItem, which it uses to create the necessary views for displaying. Does that sound familiar? Initially, NSCollectionViewItem was a subclass of NSObject, but when NSViewController was added in 10.6, NSCollectionViewItem had most of the same methods as NSViewController, so the class hierarchy was changed to make NSCollectionViewItem a subclass of NSViewController instead, and all of its methods were deprecated.

In writing the code for this article, I came across what appears to be a bug in XCode 4.1, which means that you cannot use XCode's interface designer to bind the data to the views, which is the correct way to do it. In this article, I'm going to be creating the child views manually as that appears to be the only way to get access to the controls in the view.

So let us begin at a look at what can be done with NSCollectionView.

Creating an NSCollectionView by hand

First we will need a model to display in the NSCollectionView. We'll create some simple data objects for the model, with a title string and an integer.

@interface Item: NSObject {
NSString *title;
NSInteger option;
}

@property (readwrite, copy) NSString *title;
@property (readwrite) NSInteger option;

- (id)initWithTitle:(NSString *)_title option:(NSInteger)_option;

@end

There's nothing surprising in the Item.m implementation of this object so if you want to see it, you can look at the project file at the end.

Now we have our data item, we need to create a model. In the application delegate, we create an NSMutableArray which will act as our model, and an NSArrayController which will be the controller in the MVC pattern. In this project, I'm actually going to create the array controller in the nib file, and assign it to an outlet in the application delegate. This will allow us to bind to it in the interface designer slightly easier.

The model was created in a very simple manner for testing purposes, in the init method of the application delegate

items = [[NSMutableArray alloc] init];
for (i = 1; i <= 20; i++) {
[items addObject:[[Item alloc] initWithTitle:[NSString stringWithFormat:@"Item %d", i] option:(i - 1) % 4]];
}

I designed a simple interface and all it has is a NSCollectionView. Once you add an NSCollectionView to a window, XCode automatically adds an NSCollectionViewItem and an new NSView as well. These are going to be the view controller and the view that represents each item in our data model.

Setting up the bindings so that the NSCollectionView can find the data in the model. Firstly we need to tell the NSArrayController where to get its content. We bind the Array controller's contentArray property to the NSMutableArray property of the Application Delegate. I called this property items and so in the bindings panel of the NSArrayController I set it to bind to Application Delegate and the Model Key Path is set to items.

Next we bind the content property of the NSCollectionView to the NSArrayController's arrangedObjects property. Now the NSCollectionView can see the contents of the NSMutableArray through the NSCollectionView.

NSCollectionViewItem is a subclass of NSViewController, and it has a property called representedObject. When each NSCollectionViewItem is created, this property is set to the object in the model that the NSCollectionViewItem represents. Under normal circumstances we could add controls to the NSView that XCode added for us, and then bind their values to the appropriate property on this representedObject property. For example, if we wanted to bind to the title property that our Item class has, we would select the NSCollectionViewItem as the binding source, and the model key value would be representedObject.title. However, this is what the bug in XCode prevents us from doing, so we need to carry this all out by hand. To do this, we must subclass the objects we want to use and override certain methods.

The first subclass we need is one for the NSCollectionView itself. NSCollectionView has a method
-(NSCollectionViewItem *)newItemForRepresentedObject:(id)object which is called whenever the collection view needs to display a new object. So we create our subclass (MyCollectionView I called it) and in the interface designer we set the class of the NSCollectionView to be an instance of it in the Identity Inspector.

Then we need to override newItemForRepresentedObject: so that we can do the required binding. We allow the parent class to create the NSCollectionViewItem for us, after which we can do whatever we require with it.

- (NSCollectionViewItem *)newItemForRepresentedObject:(id)object
{
// Let the parent class create the item
NSCollectionViewItem *item = [super newItemForRepresentedObject:object];
// Now we need the view so we can create bindings between it and the object.

NSView *view = [item view];

[view bind:@"title" toObject:object withKeyPath:@"title" options:nil];
[view bind:@"option" toObject:object withKeyPath:@"option" options:nil];

return item;
}

The bind:toObject:withKeyPath:options: message is binding the title property on the created view to the same property on the object that it represents. Obviously we need to create a subclass for the view, which we'll call ItemView.

As we couldn't create the view in XCode we need to create the view by hand in the initWithCoder: method. We also need to add properties for the title and option bindings that we want to display from our model item. We use the initWithCoder: method instead of initWithFrame: because the view is still being defined in the nib file, we're just filling in some other bits.

- (id)initWithCoder:(NSCoder *)aDecoder
{
self = [super initWithCoder:aDecoder];

NSRect frame = [self frame];
float controlHeight = (frame.size.height - 30) / 2;

segmentedControl = [[NSSegmentedControl alloc] initWithFrame:NSMakeRect(10.0, 10.0, frame.size.width - 20, controlHeight)];
[segmentedControl setSegmentCount:4];

NSInteger i;
for (i = 0; i < 4; i++) {
[segmentedControl setLabel:[NSString stringWithFormat:@"Option %d", i]
forSegment:i];
}

[self addSubview:segmentedControl];
titleField = [[NSTextField alloc] initWithFrame:NSMakeRect(10.0, controlHeight + 15, frame.size.width - 20, controlHeight)];
[titleField setEditable:NO];
[titleField setBordered:NO];
[titleField setDrawsBackground:NO];

[self addSubview:titleField];

return self;
}

We create a segmented control to display the option property and a text field to display the title property. Then we need to update the controls whenever the property changes which we can do in the set methods:

- (void)setTitle:(NSString *)_title
{
if (_title == title) {
return;
}

[title release];
title = [_title copy];

[titleField setStringValue:title];
}

- (void)setOption:(NSInteger)_option
{
if (option == _option) {
return;
}

option = _option;
[segmentedControl setSelectedSegment:option];
}

These are just standard setter functions, except they update the controls.

Finally for this section, we need to tell XCode that the class of the NSView is actually our ItemView by setting it in the Custom Class section of the Identify Inspector.

The size of the ItemView is also set in the nib file, so if you want to specify a size thats where to do it.

Handling Selection In NSCollectionView

NSCollectionViewItem had a selected property, but as of 10.7 this has been deprecated so any new code shouldn't use it. This makes handling selections slightly more awkward but it is still possible.

The first thing to do is to make the NSCollectionView selectable in the Attributes Inspector

and to bind the NSCollectionView's Selection Indexes to the selectionIndexes property on the array controller

This means that other controls can use the array controller to listen to changes in the selection. As an example, we'll add an NSTextField which will display the selected item's title without any code needing to be written.

Add the NSTextField to the main window. Then in the Bindings Inspector we need to bind the value property of the NSTextField to the Items Controller. The controller key is selection and the Model Path Key is title.

If you build this now and select an item, the title of the selected item will appear in the text field, but the item doesn't look like it is selected. This is because we need to tell the item that it is selected, and we need to draw the NSView differently when it is selected.

To our ItemView class we add a selected property and when the property is changed we tell our view to redraw itself.

- (void)setSelected:(BOOL)_selected

{

if (_selected == selected) {

return;

}

selected = _selected;

[self setNeedsDisplay:YES];

}

We can override the drawRect: method of our view to draw the background in the selected colour when the item is selected.

- (void)drawRect:(NSRect)dirtyRect

{

if (selected) {

[[NSColor selectedControlColor] set];

NSRectFill(dirtyRect);

}

Finally, to complete this, we need to tell the items when they are or are not selected. Initially I thought about doing this with Key Value Observing (KVO) on the selectedIndexes property of the array controller. The problem with this is that allow the KVO notifications are called correctly when the selection changes the changes dictionary is always empty. So I approached this from a different way. I'm not sure this is as "correct" as the KVO method would have been but it still works.

To do it, I override the setSelectionIndexes: method of MyCollectionView, which is called every time the selection changes as well. NSCollectionView has the method itemAtIndex: which we use to get the item for the selection. We also need to store the selected row so that we know which row to unselect when it is changed.

- (void)setSelectionIndexes:(NSIndexSet *)indexes

{

[super setSelectionIndexes:indexes];

NSCollectionViewItem *item = [self itemAtIndex:currentSelection];

ItemView *view = (ItemView *)[item view];

[view setSelected:NO];

item = [self itemAtIndex:[indexes firstIndex]];

view = (ItemView *)[item view];

[view setSelected:YES];

currentSelection = [indexes firstIndex];

}

Now when we compile and run it we should see that the item is clearly selected.

I think thats a fairly comprehensive look at NSCollectionView and friends, there's bound to be other things and hopefully Apple will get the binding bug fixed in the next version of XCode so using it won't be such a hassle.

(Code for the project can be found at http://www.mediafire.com/?n29lgi9wl22dsgf)

References:

NSArrayController docs - http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/Classes/NSArrayController_Class/Reference/Reference.html

NSCollectionView docs - http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/NSCollectionView_Class/Introduction/Introduction.html

NSCollectionViewItem docs - http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/NSCollectionViewItem_Class/Introduction/Introduction.html#//apple_ref/doc/c_ref/NSCollectionViewItem

Links to the other parts of the NSViewController articles
Part 1:- http://comelearncocoawithme.blogspot.com/2011/07/nsviewcontrollers.html
Part 2:- http://comelearncocoawithme.blogspot.com/2011/07/nsviewcontrollers-part-2.html
Part 4:- http://comelearncocoawithme.blogspot.com/2011/08/nscollectionview-redux.html

NSViewControllers (Part 2)

2011-07-21T23:54:00.001+01:00

Following on from the last post which was really the setting up of an NSViewController and we used it to switch views in and out of the window. And really we didn't need very much code to do it. This time we're going to subclass the NSViewController to set some properties in them.

When you create a subclass (using File->New->New File, or apple+N) and you tell Xcode that the parent class is NSViewController it also creates a nib file for that controller. As I was following on from the previous project, I already had the two nib files, so I deleted the newly created ones. Then in the TestView1.xib and TestView2.xib files I had to change the class of the File's Owner to our new NSViewController subclasses (which in my case were TestView1Controller and TestView2Controller) in the Identity Inspector pane on the right. Remember that we also created two NSViewControllers in the MainMenu nib file, so we need to tell Xcode that it should use our new subclasses for those as well. Again just set that in the Identity Inspector pane. Compiling and running showed that everything worked as it did before.

One of the properties that an NSViewController has is a title for the view. This is designed to be displayed somewhere in the UI. I'm going to put it in the title of the NSBox for want of anywhere else to put it. First we need to set the title for each of the controllers.

In the TestView1Controller.m file Xcode has already given us the initWithNibName:bundle: method and that seems like the best place to put it. But if we put code into there we discover that it never gets called. This is because when an object is created from the nib file a different init message is sent: initWithCoder:. We can either put the code in this method or into the awakeFromNib method.

- (id)initWithCoder:(NSCoder *)aDecoder
{
self = [super initWithCoder:aDecoder];
[self setTitle:@"Test view 2"];

return self;
}

Obviously because this is an init method we need to call up to the superclass. Or if we put it into awakeWithNib then all we need is to set the title.

- (void)awakeFromNib
{
[self setTitle:@"Test View 1"];
}

Finally all we need to do is to set the box title. Back in the action methods we just need to send the setTitle: message to the box like so.

- (IBAction)switchView1:(id)sender
{
NSView *view = [testView1Controller view];

[box setContentView:view];
[box setTitle:[testView1Controller title]];
}

Now, if you compile&run the box displays the title that was set in the view controller.
(code for this project available to download http://www.mediafire.com/?h0810n5s808c0u5 Again with the mediafire, fingers crossed...)

We can also set the title with bindings. If we add an NSViewController iVar to the ViewControllerExampleAppDelegate called currentController, then in the bindings inspector pane in Interface Builder we can bind the NSBox's title property to the ViewControllerExampleAppDelegate with keypath being currentController.title. All we have to do to set the box's title is to set currentController to the NSViewController we want displayed. In the new example, I've refactored the duplicated code in the action methods into a method of its own, and now it all looks like this.

- (void)setController:(NSViewController *)controller

{

NSView *view = [controller view];

[box setContentView:view];

[self setCurrentController:controller];

}

- (void)awakeFromNib

{

[self setController:testView1Controller];

}

- (IBAction)switchView1:(id)sender

{

[self setController:testView1Controller];

}

- (IBAction)switchView2:(id)sender

{

[self setController:testView2Controller];

}

I had hoped that we could have set the box's contentView via bindings as well, but apparently not.

(code for example 3 available here: http://www.mediafire.com/?k797b2y2uuqjz6c )

There's still some more things to look at on NSViewControllers, I'm working out how to bind things inside the view (if thats possible, I think it is) and I want to look at how NSCollectionView uses view controllers.

Links to the other parts of the NSViewController articles
Part 1:- http://comelearncocoawithme.blogspot.com/2011/07/nsviewcontrollers.html
Part 3:- http://comelearncocoawithme.blogspot.com/2011/08/nsviewcontrollers-part-3.html
Part 4:- http://comelearncocoawithme.blogspot.com/2011/08/nscollectionview-redux.html

NSViewControllers (Part 1)

2011-07-21T01:26:00.002+01:00

I seem to see a lot of people asking questions about NSViewControllers on Stack Overflow and I wondered about them as well for a quite some time. They are being used more frequently in newer API on Cocoa, and you can't program for iOS without them.

There are a few functions the NSViewController allows you to do:

Create new views on the fly
Provide a title for the view for displaying in a tab or popup menu
Enable you to bind to a value in the view, before the view is actually created.

Lets look at each one of these separately.

Creating a view on the fly is used quite a lot, think of a complex application like iTunes. The left hand column has a list of different options and when you select one, it shows a different view in the right hand side of the window. Now I have no idea how iTunes does it, but this is the one of the UI designs that NSViewController is designed to help with.

NSViewController has a method - (NSView *)view which creates a view and returns it. The simplest use of NSViewController is like so

NSViewController *viewController = [[NSViewController alloc] initWithNibName:@"customView" bundle:nil];
NSView *view = [viewController view];

[parentView addSubview:view];

This simply creates a new NSViewController and tells it that the definition for the NSView is found in the customView.nib (or customView.xib) file in the main bundle. Then it creates a new NSView and puts that view into parentView. But really, using NSViewController in this way doesn't really add much over just creating the view directly. Where NSViewController is really useful is when you need to create the views on the fly. Lets assume, for the sake of argument, that iTunes does use NSViewController. When you're looking at the Music view you may not want the Movies view loaded into memory. NSViewController does this by not creating the view until you call -(NSView *)view or -(void)loadView. This allows you to create the view controller and hook things up to it, without having the view loaded and taking up memory until it's needed. Lets look at a more full example.

In our application delegate (called ViewControllerExample1AppDelegate in the example project), we have some iVars that get filled from the MainWindow.nib.

@interface ViewControllerExample1AppDelegate : NSObject <NSApplicationDelegate> {
@private
NSWindow *window;
NSBox *box;
NSViewController *testView1Controller;
NSViewController *testView2Controller;
}

@property (assign) IBOutlet NSWindow *window;
@property (assign) IBOutlet NSBox *box;
@property (assign) IBOutlet NSViewController *testView1Controller;
@property (assign) IBOutlet NSViewController *testView2Controller;

- (IBAction)switchView1:(id)sender;
- (IBAction)switchView2:(id)sender;

In the MainWindow.nib we've created a window with 2 NSButtons, and an empty NSBox. The two buttons are hooked up to the switchView1 and switchView2 methods and we'll look at what they do later on. The NSBox is connected to the box iVar. In the nibfile we've created two NSViewControllers and connected them to the appropriate iVars. The ultimate aim for this is that clicking on the first button will switch the view contained in the NSBox to the view from the first view controller, and the second button with switch it to the second view controller's view. A simple but common UI pattern.

We also need to create two nib files that the NSViewControllers use to generate their views. I just did this by creating a new file, selecting UI in the type column, and selecting View in the type. That gives a nib file that only has an NSView in it, and I just dragged whatever controls I wanted in the view. After these nib files have been created, we need to tell the NSViewControllers what nib file to do, and to do that you just need to set the Nib Name property on the NSViewController.

Whenever NSViewController is sent the loadView or the view message, it creates the view from the nib file and it sets the File's Owner object to the receiver, which is our NSViewController and this it uses the File's Owner object's view outlet to find out what NSView should be returned. This means that we have to connect it up in our nib files. The first part of this process is to set the type of the File's Owner object. By default it is of type NSObject, which isn't very useful for us, so in Interface Builder we change the class type property by selecting the File's Owner object, and in the inspector pane's Identity Inspector changing where it says the class is NSObject to NSViewController. Now if we try to ctrl-drag from the File's Owner placeholder object to the NSView, it will allow us to set that as the view outlet.

Finally, all we need to do is to make the buttons switch the views and that simply means creating the view and setting it in the box. We do this in the switchView1 and switchView2 actions, which look like this:

- (IBAction)switchView1:(id)sender
{
NSView *view = [testView1Controller view];

[box setContentView:view];
}

- (IBAction)switchView2:(id)sender
{
NSView *view = [testView2Controller view];

[box setContentView:view];
}

The controllers are simply asked for their views, and the NSBox is told to show it. The returned view is set to be autoreleased, so if you want to keep it around then you need to send it the retain message. In this instance the setContentView message sent to box does the retaining for us so when the content view is replaced the old view is released.

We can make the program slightly more complete by displaying a box when it initially starts by doing the same thing in the awakeFromNib message sent to the application delegate.

- (void)awakeFromNib
{
NSView *view = [testView2Controller view];

[box setContentView:view];
}

I'll look into the other things you can do with NSViewController in the next part as this seems to be getting quite long.

The project for this example can be downloaded from http://www.mediafire.com/?c3n3wob0sdppp9l (sorry its on Mediafire, hopefully it won't be taken down)
Apple's NSViewController documentation for Cocoa: http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/NSViewController_Class/Introduction/Introduction.html

Links to the other parts of the NSViewController articles
Part 2:- http://comelearncocoawithme.blogspot.com/2011/07/nsviewcontrollers-part-2.html
Part 3:- http://comelearncocoawithme.blogspot.com/2011/08/nsviewcontrollers-part-3.html
Part 4:- http://comelearncocoawithme.blogspot.com/2011/08/nscollectionview-redux.html

An Introduction

2011-07-13T21:23:00.000+01:00

Everyone seems to start one of these blogs when they're learning Cocoa, so I thought I'd start one too. Partly it'll help me to remember what I've worked out, maybe it'll help someone else too.

I've been programming in C/C++ on Unix for about 13 years now and I thought I'd expand my skill set. As such its unlikely that this blog will cover much about learning objective C or C and I'll probably take knowledge of those things as assumed. Maybe not, I've not written anything yet so who knows.

Recently I've been playing around with Controllers, ArrayControllers, ObjectControllers and ViewControllers, so I think I'll start with something like that. I also have an interest in audio and MIDI and graphics programming, maybe something will come from that.

Some books that I can recommend that I've found useful are two from Big Nerd Ranch:
* iOS Programming: The Big Nerd Ranch Guide (2nd Edition) (Big Nerd Ranch Guides)
* Cocoa® Programming for Mac® OS X (3rd Edition)

Two very good tutorial style books that get the reader up to speed on beginning to program iOS and Cocoa, starting with explaining the basics of Objective C and using the developer tools Apple provide.

* Core Animation for Mac OS X and the iPhone: Creating Compelling Dynamic User Interfaces (Pragmatic Programmers)

This book on Core Animation is quite good as a reference and introduction to Core Animation concepts, but it isn't a tutorial book and assumes quite a high level of knowledge of Objective C and Cocoa technologies.

* Programming with Quartz: 2D and PDF Graphics in Mac OS X (The Morgan Kaufmann Series in Computer Graphics)

Programming with Quartz is a huge guide and reference to drawing with Quartz. I'd say its essential if you're planning on doing any custom drawing in your applications.