Cocoa works with distinct toolbar identifiers to distinguish between multiple different toolbars in one application. The toolbars can be fully customized by the user and changes to a toolbar are synchronized to all toolbars with the same identifier. For example in an application with multiple edit document windows, all these windows would have a toolbar with the same identifier. If a user would change on toolbar, alle currently opened edit windows would synchronize their toolbars to the new changes.

When you want to add a toolbar to your application, make sure, that your controller class has a handle to the window which will hold the toolbar. So you need to define an outlet

IBOutlet NSWindow *window;

and connect this outlet in Interface Builder to the window you want to use for the toolbar. Now you need to initialize the toolbar during the application startup. The best place for this is the awakeFromNib method, because at the time this method is called, all nib-Files are already initialized and our outlets are already connected. If you want to add a toolbar from a NSDocument subclass, you need to do the initialization in windowControllerDidLoadNib:.

Let’s take a look at the toolbar initialization in the awakeFromNib method of our application controller:

- (void)awakeFromNib
{
    // create the toolbar object
    NSToolbar *toolbar = [[NSToolbar alloc] initWithIdentifier:@"MySampleToolbar"];
 
    // set initial toolbar properties
    [toolbar setAllowsUserCustomization:YES];
    [toolbar setAutosavesConfiguration:YES];
    [toolbar setDisplayMode:NSToolbarDisplayModeIconAndLabel];
 
    // set our controller as the toolbar delegate
    [toolbar setDelegate:self];
 
    // attach the toolbar to our window
    [window setToolbar:toolbar];
 
    // clean up
    [toolbar release];
}

The above code is pretty straightforward. We create a new toolbar object, set some basic attributes which enable the user to modify the toolbar contents and set the initial display mode to display both icons and text for the toolbar items. Then we register ourselves as a delegate for the toolbar. All further programming is then done in the delegate methods. After that we add the toolbar to our window, and clean up memory (don’t worry the window object retains our toolbar, so it will not be disposed right away).

When working with toolbars, we need to implement at least delegates for the following actions:

• get a list of all allowed toolbar items
• get a list of all default items which should be displayed in our default toolbar
• get a NSToolbarItem object for a given identifier

Again, similar to the toolbar, the toolbar items are also identified with identifier strings. It is a good practice to define these strings as static variables:

static NSString *SaveToolbarItemIdentifier = @"My Save Toolbar Item";
static NSString *SearchToolbarItemIdentifier = @"My Search Toolbar Item";

The Cocoa framework has a couple of toolbar items predefined, for example NSToolbarSeparatorItemIdentifier or NSToolbarSpaceItemIdentifier.

The first delegate method we implement will return a list of all allowed toolbar items:

- (NSArray *) toolbarAllowedItemIdentifiers: (NSToolbar *) toolbar {
    return [NSArray arrayWithObjects:SaveToolbarItemIdentifier, 
        SearchToolbarItemIdentifier,
        NSToolbarFlexibleSpaceItemIdentifier, 
        NSToolbarSpaceItemIdentifier, 
        NSToolbarSeparatorItemIdentifier, nil];
}

We simply need to return an array with the identifiers of all allowed toolbar items.

The delegate to return a list of default toolbar items looks similar:

- (NSArray *) toolbarDefaultItemIdentifiers: (NSToolbar *)toolbar 
{
    return [NSArray arrayWithObjects:SaveToolbarItemIdentifier,
        NSToolbarFlexibleSpaceItemIdentifier, 
        SearchToolbarItemIdentifier, nil];
}

Our sample toolbar consists of two items, which are separated with a flexible space element which results in the first item being left aligned in the toolbar and the second item being right aligned. The order of the items returned in the array is the display order in the toolbar.

The interesting part is how the toolbar items are created. The toolbar can display two types of items. Simple icon based toolbar items and items which are based on a custom view. With custom view items you can implement search fields, or popup menus or anything else you can imagine. In our example we have a search field which is a custom view item. For this item we have created a new custom view in interface builder and placed an NSSearchField into the view. Our controller has an outlet which is connected to the custom view. The resulting delegate method looks like this:

- (NSToolbarItem *)toolbar:(NSToolbar *)toolbar
     itemForItemIdentifier:(NSString *)itemIdentifier
 willBeInsertedIntoToolbar:(BOOL)flag
{
    NSToolbarItem *toolbarItem = nil;
 
    if ([itemIdentifier isEqualTo:SaveToolbarItemIdentifier]) {
        toolbarItem = [[NSToolbarItem alloc] initWithItemIdentifier:itemIdentifier];
        [toolbarItem setLabel:@"Save"];
        [toolbarItem setPaletteLabel:[toolbarItem label]];
        [toolbarItem setToolTip:@"Save Your Passwords"];
        [toolbarItem setImage:[NSImage imageNamed:@"save.png"]];
        [toolbarItem setTarget:self];
        [toolbarItem setAction:@selector(save:)];
    } else if ([itemIdentifier isEqualTo:SearchToolbarItemIdentifier]) {
        NSRect searchRect = [searchView frame];
        toolbarItem = [[NSToolbarItem alloc] initWithItemIdentifier:itemIdentifier];
        [toolbarItem setLabel:@"Search Passwords"];
        [toolbarItem setPaletteLabel:[toolbarItem label]];
        [toolbarItem setToolTip:@"Search Password Titles"];
        [toolbarItem setView:searchView];
        [toolbarItem setMinSize:searchRect.size];
        [toolbarItem setMaxSize:searchRect.size];
    }
 
    return [toolbarItem autorelease];
}

For every toolbar item you need to the set its label, a palette label and a tooltip message. For simple toolbar items, you also need to define an icon image and an action method which will be called when the item is clicked.

The setup of custom view items is a little bit different. First we read the size of the custom view. This is used to set a fixed size for the toolbar item. We do not specify a custom action, because the NSSearchField is connected to an action method itself. But whether you need to define an action method for a custom view item, depends on your view.

That’s it for the basics of toolbar programming in Cocoa. If you want to dive deeper into this topic, I recommend to read the document Toolbar Programming Topics for Cocoa.

If you want to dive into the details of Cocoa memory management, I recommend you read the Memory management Programming Guide For Cocoa from Apple. For me it was the main source of information about this topic.

The retain cycle

Cocoa objects use an Attribute called retainCount which keeps track how many other objects claim ownership to it. Whenever you want to keep a reference to an object you send it the retain message, which will increase its retainCount. When you don’t need the reference any more you send a release message and the count will decrease. Once the retainCount drops to 0, the object will be disposed and the memory freed.

The most important rule you have to remember is:

Whenever you create an object via methods that contain alloc, new and copy in their name, or you increase the retainCount via retain you need to release that object in the same context.

For example let’s take a look at the following method:

+ (void)doSomething
{
    id *myObject = [[SomeObject alloc] init];
 
    // do something with the object
 
    [myObject release];
}

We are creating a method variable pointing to a freshly created object. The variable will be disposed when we exit the method, therefore we need to make sure to release the object it is pointing to before exiting the method.

The same principal applies to instance variables of a class. Here you need to make sure that you release all the instance variables this class might have created, before disposing the class object. This is usually done in the dealloc method of the class.

When working with instance variables you should follow the best practice to access the variables only through their accessor methods. That way you can ensure a transparent handling of the release and retain operations. Let’s take a look at a typical setter method:

- (void)setName:(NSString *)aName
{
    aName = [aName copy];
    [name release];
    name = aName;
}

So the setter first creates a new copy of the object, then releases the old object and last it will store the reference to the new object in the instance variable. The order of the operations is especially importing. Because if we would first release the old object, and the new object would be a pointer to the old object, we would loose our data.

Now that the setter always allocates a new object, we need to make sure to release it when the class is destroyed:

- (void)dealloc
{
    [name release];
    [super dealloc];
}

We don’t have to worry about the name object being nil, because Objective-C can send messages to nil-objects without generating null-Pointer exceptions or crashing.

Autorelease objects

So naturally the next question is: How do we return objects we have created inside a method when we have to release them before we exit the method?

This is the domain of the autorelease objects. Instead of sending an object the release message, you could send it the autorelease message, which will mark that object for later deletion. So, the retainCount will be reduced, but the object will not be disposed and we can use it in the code that called our method.

So how does this work? Basically it adds the object to a so called autorelease pool. This pool is initialized automatically every time an event cycle is triggered (for example via a MouseDown event). During the event cycle, all autorelease objects will be added to that pool and they will be disposed once the event cycle has finished. This means that you don’t have to worry about retaining an autorelease object as long as you use it only during a single user action. You only need to retain it if you want to store it between user actions.

If you stick to the convention to access your instance variables via the getter and setter methods, you do not need to worry about working with autoreleased objects, because the setter methods would automatically retain the object. That’s a best practice which really helps keep your code clear.

Besides the automatic autorelease pools, you can also create your own pool by creating a new instance of the object NSAutoreleasePool. The creation of your own autoreleass pool is mandatory in the following cases:

• You are writing a command line tool
• You are spawning a new thread

There is another use for custom pools. When you are working with a lot of autorelease objects inside a loop statement, this will lead to all those objects being stored in the pool until the event loop finishes. It is much more efficient to release the memory at the end of each loop cycle. In that case we would create a autorelease pool inside the loop:

for (i = 0; i < 1000; i++) {
    NSAutoReleasePool *myPool = [[NSAutoReleasePool alloc] init];
 
    NSString *someVariable = [NSString stringWithString:@"Some text"];
 
    // do some more stuff with lots of autorelease objects
 
    [myPool release];
}

In the above example, all the autorelease objects which have been created inside the loop, will be disposed of as soon as we release the pool object. This is a very powerful concept to keep your memory consumption low.

Note on collections

Collection objects retain the objects which are stored in the collection. You can release them once you added them to the collection, but keep in mind, that once the collection object is released, it will also release all objects stored in that collection.