Apps like Coda are the de-facto standard for good user-interface design nowadays. You can do a lot with the standard Cocoa controls provided by Apple, but you can’t always get exactly what you want out-of-the-box. For example, the CSS edit section of Coda has a fantastic way of dividing tasks: the animated outline view.

Rather than having a monolithic view that has all the controls grouped with dividing lines; each section, “Text”, “Colors and Background”, “Dimensions”, all exist in their own collapsible view. Clicking the separating bar animatedly expands or collapses the view.

To make one of these views isn’t quite as easy as you first think, and you can quickly go down the wrong road in the design. The super-secret trick is to *not* use Core Animation, or more precisely: ignore the lure of NSViews conformance to the NSAnimatablePropertyContainer protocol. As of Mac OS X 10.5, a few of the properties of a view or window can be animated simply be replacing calls like [view setFrame:newFrame]; with [[view animator] setFrame:newFrame];. This is fine when you have one or two views that you want to move but it’s impossible to coordinate the movements of multiple view using this API. After using Core Animation, one would expect that after a call such as [[view animator] setFrame:newFrame]; requesting the frame from the view would return newFrame. Unfortunatley it returns the original frame of the view. Only when the animation is done, do you get newFrame. Furthermore, just try setting the delegate of the CABasicAnimation object that handles the implicit animation and getting any form of useful information back. You can’t. You’re in for a world of pain if you try.

The solution: use good-ol’ NSViewAnimation. That way you can create all the dictionaries containing the animations for all the views you want to, then instantiate one NSViewAnimation object to handle the lot and set them off at the same time. Simple.

The Animating Outline View

The outline view is made up of a few classes, the TLDisclosureBar, a subclass of the highly-configurable TLGradientView; the TLCollapsibleView which has a TLDisclosureBar and any NSView you like as its subviews. A TLCollapsibleView itself can be used alone, and will animate the collapse/expansion of the NSView subview (which I term the “detail view”).

The fun part comes when TLCollapsibleViews are subviews of a TLAnimatingOutlineView. In this case, the TLAnimatingOutlineView takes over all the animations, simply asking the TLCollapsibleView that the user has selected for the NSDictionary object that describes the collapse/expansion animation. With this information, it constructs the movement animations for all the subviews below the collapsing/expanding view and handles the required change of frame size to accommodate the changing content size. It’s all quite elegant, if I do say so myself.

Not being content with example code, I’ve made sure these classes are real-world useful. This view is integral to BibTeX management in Scribbler so it needs to be good. Some of the relevant parts of the NSOutlineView API are replicated and the delegate of the TLAnimatingOutlineView gets will/did/expand/collapse notifications, along with allowing the delegate to deny/allow animations, too. Each of the TLCollapsibleViews will also ask their detail views if the collapse/expansion is allowed if the TLCollapsibleDetailView protocol is implemented. The TLAnimatingOutlineView itself works when in an NSScrollView.

The code, along with an example project, is hosted on Google Code here. It is distributed under the new BSD license.

So why is is not ESAnimatingOutlineView, why the TL namespace? Well, I’m working on something big, at the same time as writing Scribbler. Start guessing.

Update

I’ve fixed a few bugs in the code, the current version can be checked out of the repository. Fixes include: proper support for hiding subviews of the TLDisclosureBars when the outline view is resized small, a correction to the autoresizing mask of the TLAnimatingOutlineView itself, declaration of keys that the TLCollapsibleView supplies with the animation dictionaries, the delegate of the outline view and subclasses of TLGradientView are no longer unregistered for notifications that client code specifies (i.e. no longer uses [[NSNotifcationCenter defaultCenter] removeObserver:_delegate];).

Well since I no longer work at the NHS I’ve been working really hard on one of the great features of Scribbler, image editing. As something I wanted to put in at the very start, I was really enthusiastic to start using Apple’s Image Kit. It promised developers the chance to do very little work and still have fully-fledged image management, provided by IKImageBrowser (very good) and image editing thanks to IKImageView. Unfortunately, the latter does not live up to the hype. After battling with it for a while and trying to justify to myself that it would suffice for version 1.0 of Scribbler, it was just way too incomplete, buggy, and damn ugly to leave in. I try to work with the idea that if it bugs me, it’s not good enough.

Image Loading

Let me start with IKImageView. It loads images ok, although larger images aren’t loaded nicely: they’re drawn incrementally in a really jarring fashion, even if you pass the view a CGImageRef that’s already in memory.  That being said, it does handle quite a few different types of images, so we give it half a point.

Image Editing

The main function of such a view is not for viewing images, but for editing them within the application. Many users want to quickly change an image they’re working with and then get straight back work.  Taking our cues from iPhoto we guess that this editing will take the form of colour adjustments rotating and cropping. If we’re feeling really generous, then we can also include a straightening tool and some zooming (although the latter is relatively superfluous unless we have some sort of pixel-level editing like iPhoto’s red-eye removal or the touch-up tool).

So we’ve put IKImageView in our app, and loaded an image, we then want to change the brightness and contrast, so we double-click on the image and open up the shared instance of the IKImageEditPanel (left).

Compared to iPhoto’s panel (right), this is ridiculously ugly, has no icons, has an Aqua button at the bottom instead of a properly-rendered HUD button.  The biggest issue: it appears off-screen all the freaking time. Can you imagine editing a bunch of images and having to manually drag the panel to where you want it each time you open the damn thing up? No amount of setting the frame of the window or teaching it to autosave it’s position fix this, and even if we could, the first time you run the app it’s at the bottom of the screen with most of it hidden.

Lastly, you just try setting a new image in the view and getting the edit panel to do anything anymore, as far as I can tell -reloadData is a no-op, it neither reloads the data for the panel, nor makes you more attractive. The only way to fix this is to close the panel, and reopen it (and then moving it so you can see the controls).

Rotation

If we want to rotate the image we (in code) select the IKToolModeRotate mode and we get our onscreen compass:

The problem with this is two-fold: click on the image at about 3/4 the way up and the rotation compass is drawn outside the bounds of the view; secondly, the user interaction is all wrong. To rotate you click and hold ok the image and move the mouse around in a manner that’s so hard to control it’s useless. Then think about saving the image after a rotation. The view itself has no concept of a canvas, so we can’t save an angled image on a white background, and we can’t arbitrarily decide to ignore the user’s rotation setting an save an un-rotated image (rock - me - hard place). Basically the tool is broken and doesn’t provide useful functionality to users.

Cropping

Then we have IKToolModeCrop. “Fantastic!” I hear you cry. “No longer will my users have to open up another app to crop an image, and I won’t have to write that code”. You diligently select a region if the image, then call -setCurrentToolMode: and….

Nothing. Nada. Zip.

Reading through the programming guide tells us that Apple have declared the mode and not implemented it (apoordesignersayswhat). So we then have to do it, but can we get the selection rectangle? Of course we can’t! So that nice crop button we made goes to waste, unless you want to subclass, track the mouse, interrupt -drawRect:, apply the crop using core image (note to all that CICrop filter is not a magic bullet), draw a CGImage with the cropped version, then reset the image. No thanks. On it’s own that might be fine, but with all the other rubbish in this class you’re starting to flog a dead horse.

So that’s why IKImageView will *not* be making an appearance in Scribbler, and if you find it in any other apps then… well… I heard that Windows Photo Viewer Deluxe Family Millennium Media Edition is fantastic.

I’ve been putting off writing about Scribbler for a while because it’s really difficult to put into words properly the ideas I want to convey. I’ve become very attached to my little application since its early inception, not only because of the time I’ve spent, but also for how it has helped me find my creative side. The only reason I haven’t put screenshots up yet is because I’ve been talking with a designer about making the icons, and developing the site and brand of Espresso Served Here (need to catch myself each time I write ’severed’). They guys I’ve got to do that part of the app, which is completely beyond me, are really talented and I’m getting very excited about having all the artwork finished. As soon as it is ready, I’ll start posting screenshots.

It was writing my MSc thesis that gave me the desire to write a new LaTeX editor. I decided that I needed an app that understands how people work with large documents. Specifically, people work on projects. Each of these projects can contain many source files: LaTeX source itself, images, BibTeX files and PDFs; and Scribbler knows how to handle them all. You organise your project in Scribbler just like you’d organise your iTunes or iPhoto library, while Scribbler takes care of files on your hard drive. You can make new LaTeX and BibTeX files within Scribbler itself, or simply drag-and-drop a file from any other program to add it to your project.

When writing, having Scribbler keep track of your project soon shows its advantages over keeping each document separate. To include an image in your LaTeX source, just drop it on the text and Scribbler will write the code for you. You no longer need to care where the image file is in the filesystem, why should you?

Another plus to this approach comes when writing labels and citations. As Scribbler looks after your project it knows all the \label{} keys you’ve written and will suggest them for you when you type \ref{} (for the LaTeX-uninitiated, that makes cross-referencing very, very easy). The same works for all your citations.

One of the things I always found myself doing when writing in LaTeX was editing my images so I decided to add some image-editing functionality for common tasks. Scribbler allows you to re-colour, crop, rotate and apply filters to your images, so you only need to open up Pixelmator or Photoshop when you really need to.

I’m really looking forward to showing off Scribbler to you all, and when you use it I’m sure you’ll agree that creating beautiful LaTeX documents can be done in a beautiful environment. After all, one of the reasons we all use LaTeX is because we care about how things look. I’m working really hard on some features that will blow you away, and I’ll keep-on making it better.

You may have seen the articles Cathy Shive and I wrote on her blog about NSViewController and how to get it working well in your apps. Well now you can hear us talk about it! Scotty of the Mac Developer Network kindly had us both on for an episode of Late Night Cocoa, which you can download from iTunes here. It’ll be on the MacDevNet site too.

I talked about my preferences window system, I’ll have to wait a few weeks until I can put it up here with a sample app. Work will let up in August and I’ll have time to iron out a few bugs.

Thanks again to Scotty for having me on the episode, it was awesome!

I’m slowly getting everything ready to get espresso served here off the ground.  Part of that has been talking to a couple of graphic designers about site design and icon design.  After all, I’m a programmer and I can’t draw for the life of me.  Photoshop to me is an app that just puts loads of stuff all over my system.

Hopefully sometime in August things will start to take shape.

Apple introduced new scrollers in iTunes 7 and then moved on to give us the HUD, which many developers want their own scrollers for too. In Leopard, many of us thought that these would come in a nice, shiny box; but as they didn’t we’re all forced to roll our own. The common method is to draw all the components in Photoshop and then make a composite image when subclassing, but now with NSGradient and some nice additions to NSBezierPath all these have become quite easy to do, even for those with little artistic ability.

My first attempt was to do all of this using NSAffineTransforms, but without being able to mirror a bezier path, or define the the centre of rotation of a path or NSRect it becomes a loathsome task of tweaking and it just never quite works. So all the elements are drawn separately in this example, which is more code, but turned out to be far easier to code.

The important point to realise when subclassing NSScroller is that Apple’s documentation is out of date and some of the methods that we immediately assume we can subclass aren’t called. You can read the details in this thread on the cocoa-dev mailing list. You end up having to also implement -drawRect: and calling these documented (but unused) methods yourself.

The NSScroller consists first of the NSScrollerKnobSlot, the track on which the NSScrollerKnob itself lies. There are 2 (normally) buttons: in the vertical case the up arrow defined as the NSScrollerDecrementLine and the down arrow is the NSScrollerIncrementLine. I’ve implemented a method that checks to see which configuration the user has the scrollbars in, whether they are at the top and bottom or both together at the bottom. It does this by examining the AppleScrollBarVariant key in the global user defaults. If this (AFAICT undocumented) key changes then it calculated which configuration the user has selected. So when using these scrollers, the user can switch the configuration in System Preferences and the change can be seen. In the mode with both together at the bottom of the bar, there is also a top ‘socket’ that’s drawn.

The scrollbars also support horizontal scrolling, and I found that instantiating the vertical scroller without a frame works fine, but the only way to get a horizontal scroller is by using -initWithFrame:. I can only assume that apple are doing something under-the-hood for horizontal ones.

The final hiccup comes when you can to support the last 20% of users that use the scrollbar variant with both buttons at both ends. This is done in terminal and thankfully requires a restart of any program in which you want it to take effect. Problems come when trying to support this case when you want to know which button has been hit so you can draw it highlighted. The documented stuff from apple returns the same value whether the decrement line one end or the other is clicked! Making this impossible without tracking the mouse yourself, and I haven’t had the time to fix that. If I were using a program that didn’t respect my settings (I’m looking at you General Electric), then I’d get angry, so I included an NSScrollView subclass that checks for this case and just uses Apple’s scrollers if the user has selected it.

I think they’re pretty close to the iTunes ones, but mine are resoution-independent, but only Apple can give the perfect solution. You can download the XCode (3.1) project and sample app (10.5-only) here.

Hi all,

Just thought I’d let you know that you can now reach this website at www.espresso-served-here.com. I’m going to slowly be making changes to the site as I develop the brand for my software company. All previous links around the web to http://jonathandann.wordpress.com will still work though.

Jon

Having recently taken the plunge into Core Data I decided it was time to rip out all the model code from my current application and replace it with a Core Data version. After about a day I had my app up and running again but with one huge problem, the content of my NSOutlineView always appeared in a random order. Such is the problem with Core Data that NSManagedObjects store their to-many relationships in an NSSet, not an NSArray, which is unordered. So when your NSTreeController tries to display its data it appears in a random order.

This is not nice, imagine if the playlists in your iTunes library always changed their order? It gets even worse if your user wants to use drag and drop. In this case they decide the order, and they’d probably want it to stay that way.

The question of how to do this comes up so many times, along with the question of how to use multiple classes for nodes in the tree. Well, here’s your answer, and I’ve made a sample Xcode project to demonstrate. (alt link)

The Model

The model I’ve set up has a single abstract entity called TreeNode which has a boolean isLeaf attribute, an NSString *displayName, and an NSNumber *sortIndex (which is the one of the main reasons I’m writing this). It also has a to-many children relationship that has an inverse to-one parent relationship. Then there are two other entities: Group and Leaf both of which inherit from TreeNode. The Group entity has a few other boolean attributes that make writing an NSOutlineView delegate class really simple. The Leaf doesn’t have any of its own attributes yet, that’s for you guys to ponder.

The Tree Controller
The tree controller is our custom ESTreeController class. It is set up in the nib and has only 2 bindings, those of the @"managedObjectContext" and the @"sortDescriptors". It’s (obviously) operating in entity mode which is set to our abstract entity of TreeNode, and the children and leaf keypaths are set to attributes of the model: the oh-so-inventively named, children and isLeaf.

The Outline View
The outline view is also a subclass of NSOutlineView, but only to support expanded-state saving. The NSTableColumn in the view has only a single binding: the @"value" binding is bound to the tree controller’s @"arrangedObjects.displayName".

The rest of the UI only exists for demonstration purposes (so yeah its ugly), so we can see which ESTreeController method is invoked by the class’ standard actions.

The Sort Index
The @"sortIndex" attribute is the key to keeping the tree sorted, and it’s persistent allowing the sort to be maintained across sessions. It is simply an unsigned integer. Not having to apply a unique value to each node in the tree makes this a whole lot easier, nodes only require to have a unique number that defines their location within their own group. All we have to do is keep the sort index as the last index of the corresponding NSTreeNode’s index path.

There are 3 places this must be updated: on insertion, removal and movement. Functionality for this is provided by a single method -updateSortOrderOfModelObjects, which takes the last index of the tree node’s index path and sets it as the sort index of the representedObject. Simple. We make sure this is done correctly by overriding:

- (void)insertObject:(id)object atArrangedObjectIndexPath:(NSIndexPath *)indexPath;
- (void)insertObjects:(NSArray *)objects atArrangedObjectIndexPaths:(NSArray *)indexPaths;
- (void)removeObjectAtArrangedObjectIndexPath:(NSIndexPath *)indexPath;
- (void)removeObjectsAtArrangedObjectIndexPaths:(NSArray *)indexPaths;
- (void)moveNode:(NSTreeNode *)node toIndexPath:(NSIndexPath *)indexPath;
- (void)moveNodes:(NSArray *)nodes toIndexPath:(NSIndexPath *)startingIndexPath;

The tree controller is then bound to an NSSortDescriptor with keypath @"sortIndex".

Points To Note
NSTreeController’s -add:, -addChild:, -insert:, -insertChild: and remove: all call the plural forms of the above methods, and proceed to try and add a TreeNode entity to the tree. This can cause problems in the outline view’s delegate as this expects either Leaf or Group entities (try them in the sample project!), overriding these is usually necessary, which is what’s done with the -newLeaf: and -newGroup: actions.

The project also includes a bunch of categories that make life so much easier when working with NSIndexPath, NSTreeController and NSTreeNode.

Drag and Drop

-outlineView:writeItems: toPasteboard:
Write the index paths of the dragged items to the pasteboard as NSData objects.

-outlineView:validateDrop:proposedItem:proposedChildIndex:
Determine if the drop location is valid, not allowing drops on a leaf node (for the case of iTunes playlists being allowed to do this wouldn’t make sense), or if one of the dragged nodes is a group and the proposed location is on of its own descendants.

-outlineView:acceptDrop:item:childIndex:
Accept the drop and move the nodes for the dragged index paths. The edge case is is when dropping on the root of the tree. In this case the proposed parent of the drop location is nil and generating the index path for insertion therefore returns nil. We check for a nil parent and create a blank NSIndexPath if this is the case.

Summary
With the (relatively small) amount of code we have an NSOutlineView powered by Core Data and NSTreeController with some great features:
1) Drag and drop!
2) Persistent state saving!
3) Multiple entities in the tree (extend ad infinitum)
4) Sorting!
5) Some indispensable categories that make these classes so much easier to use (-treeNodeForObject: is great).

Download the Xcode project (requires Mac OS X 10.5)

Update
I’ve realised that there is some repeated code in the extensions, for my own work I’ve replaced the implementation of -flattenedContent with this:
- (NSArray *)flattenedContent;
{
return [[self flattenedNodes] valueForKey:@”representedObject”];
}

There are also these I’ve found useful:
- (void)setSelectedNode:(NSTreeNode *)node;
{
[self setSelectionIndexPath:[node indexPath]];
}

- (void)setSelectedObject:(id)object;
{
[self setSelectedNode:[self treeNodeForObject:object]];
}

- (NSIndexPath *)indexPathToObject:(id)object;
{
return [[self treeNodeForObject:object] indexPath];
}

I recently did a post on NSViewController with Cathy Shive, and I realised today that the post was link to on the MacDevNet (Thanks Scotty!). I’m actually feeling like a developer for once.

Welcome all, nice to see you. Sit down, have a cup of coffee (espresso is served here), and I’ll write some more in a bit.

A common UI concept in Mac development is that of the source list, which everybody knows from iTunes, iPhoto, etc. To do this, NSTreeController can come in particular handy, although it can come with a bit of a headache as the API is somewhat lacking and a proper model is essential to making this easy to use.  I’m going to go over the solution that’s worked for me.

The starting point is the design of the model, we’ll begin by constructing a ‘node’ class that will represent a single item in our tree.  A node will need a few properties to work with the tree controller well.  The first is a ‘children’ property that’ll be an NSMutableArray intended to hold a series of our nodes.  The second is a BOOL, ‘isLeaf’ that we’ll toggle depending on whether we want the node to have the possibility of children or not.  Think of leaves as files and the opposite (I’ll call them groups) as folders, if you like.

Here’s how the code will look:

@interface ESNode : NSObject  {
 @protected
 ESNode *_parent;
 NSString *_nodeName;
 NSMutableArray *_children;
 BOOL _isLeaf;
}
@property(copy) NSString *nodeName;
@property(copy) NSMutableArray *children;
@property(assign) ESNode *parent;
@property(assign) BOOL isLeaf;

The problem is that objective-c 2.0 properties don’t have a mutableCopy keyword, so we’ll have to add the accessors ourselves, the isLeaf setter will do some magic too.

@synthesize nodeName = _nodeName;
@synthesize parent = _parent;
@dynamic isLeaf;
@dynamic children;

- (void)setIsLeaf:(BOOL)flag;
{
 _isLeaf = flag;
 if (_isLeaf)
 	self.children = [NSMutableArray arrayWithObject:self];
 else
 	self.children = [NSMutableArray array];
}
- (BOOL)isLeaf;
{
 return _isLeaf;
}

- (NSMutableArray *)children;
{
 return _children;
}

- (void)setChildren:(NSMutableArray *)newChildren;
{
 if (_children == newChildren)
 	return;
 [_children release];
 _children = [newChildren mutableCopy];
}

- (NSUInteger)countOfChildren;
{
 if (self.isLeaf)
 	return 0;
 return [self.children count];
}

- (void)insertObject:(id)object inChildrenAtIndex:(NSUInteger)index;
{
 if (self.isLeaf)
 	return;
 [self.children insertObject:object atIndex:index];
}

- (void)removeObjectFromChildrenAtIndex:(NSUInteger)index;
{
 if (self.isLeaf)
 	return;
 [self.children removeObjectAtIndex:index];
}

- (id)objectInChildrenAtIndex:(NSUInteger)index;
{
 if (self.isLeaf)
 	return nil;
 return [self.children objectAtIndex:index];
}

- (void)replaceObjectInChildrenAtIndex:(NSUInteger)index withObject:(id)object;
{
 if (self.isLeaf)
 	return;
 [self.children replaceObjectAtIndex:index withObject:object];
}

So we have a typical mutable array accessor and all the indexed accessors that allow you to place nodes anywhere in the children array. If you need to see more about why these are good to put in, then read the documentation on Key-Value Coding.  We’ve also included a ‘parent’ property that is non-retained so all nodes can know about their parent object and a ‘nodeName’ which I commonly use to identify my nodes in the tree.  The ‘isLeaf’ accessor will create either an empty mutable array ready for some children nodes or an array containing ’self’ if ’self’ has isLeaf set to YES.  The only caveat here is is you adopt the NSCopying or NSCoding protocols then you have to set isLeaf before setting the children array.

In the implementation of our ESNode class we’ll include a few useful methods for searching and filtering the tree:

- (NSArray *)descendants;
{
 NSMutableArray *descendantsArray = [NSMutableArray array];

for (ESNode *node in self.children) {
 	[descendantsArray addObject:node];
 	if (!node.isLeaf)
 		[descendantsArray addObjectsFromArray:[node descendants]];
 }

return [[descendantsArray copy] autorelease]; // return immutable
}

- (NSArray *)leafDescendants;
{
 NSMutableArray *leafsArray = [NSMutableArray array];

for (ESNode *node in self.children) {
 	if (node.isLeaf)
 		[leafsArray addObject:node];
 	else
 		[leafsArray addObjectsFromArray:[node leafDescendants]];
 }

return [[leafsArray copy] autorelease]; // return immutable
}

- (NSArray *)groupDescendants;
{
 NSMutableArray *groupsArray = [NSMutableArray array];

for (ESNode *node in self.children) {
 	if (!node.isLeaf) {
 		[groupsArray addObject:node];
 		[groupsArray addObject:[node groupDescendants]];
 	}
 }

return [[groupsArray copy] autorelease]; // return immutable
}

These allow us to get any of our node objects and construct an array of their descendants down to the bottom of the tree.  The final methods are our -init, -copyWithZone:, -initWithCoder: and -encodeWithCoder:

- (id)init;
{
 if (![super init])
 	return nil;
 self.nodeName = [NSString stringWithString:@"untitled"];
 self.isLeaf = NO; // this will also set the children array to [NSArray array].
 self.parent = nil;
 return self;
}

- (id)initGroup;
{
 return [self init];
}

- (id)initLeaf;
{
 if (![self init])
 	return nil;
 self.isLeaf = YES; // this will set the children array to an NSArray containing self.
 return self;
}

- (id)copyWithZone:(NSZone *)zone;
{
 ESNode *copy = [[[self class] allocWithZone:zone] init];
 if (!copy)
 	return nil;
 copy.nodeName = self.nodeName;
 copy.isLeaf = self.isLeaf;
 if (!self.isLeaf)
 	copy.children = self.children;
 return copy;
}

- (NSArray *)keysForEncoding;
{
 return [NSArray arrayWithObjects:@"isLeaf",@"children",@"parent",nil];
}

-(id)initWithCoder:(NSCoder *)coder;
{
 if (![self init])
 	return nil;

for (NSString *key in self.keysForEncoding) {
 	[self setValue:[coder decodeObjectForKey:key] forKey:key];
 }

return self;
}

- (void)encodeWithCoder:(NSCoder *)coder;
{
 for (NSString *key in self.keysForEncoding)
 	[coder encodeObject:[self valueForKey:key] forKey:key];
}

- (void)setNilValueForKey:(NSString *)key;
{
 if ([key isEqualToString:@"isLeaf"])
 	self.isLeaf = NO;
 else
 	[super setNilValueForKey:key];
}

The nice thing about doing your NSCoding in this way is that concrete subclasses of ESNode can simply implement a single method to adopt NSCoding:

- (NSArray *)keysForEncoding;
{
 return [[super keysForEncoding] arrayByAddingObjectsFromArray:[NSArray arrayWithObjects:@"key1",@"key2",@"key3",nil]];
}

Ok, so we have our node class and now we can use it with NSTreeController.  In your AppController class (this may be anything, for example an NSDocument subclass) create an NSMutableArray instance variable and call it treeContent. This array will hold instances of our ESNodes (or a subclass of ESNode if you want to extend it).

In the next part I’m assuming you’re used to Interface Builder and your app controller is either the File’s Owner of your nib, or is instantiated in the nib. Create an instance of NSTreeController in Interface Builder and bind the @”contentArray” to the keypath to the ‘treeContent’ array.  This tree controller will be powering an NSOutlineView.  Click through on your NSOutlineView instance until you can edit the bindings for the NSTableColumn and bind the @”value” of the table column in the outline view to the tree controller’s @”arrangedObjects” controller key with the keypath @”nodeName”. You’ll also have to set the tree controller’s children keypath to @”children” and the leaf keypath to @”isLeaf”.

In the -init method of the class that contains your treeContent array, create a bunch of ESNodes and fill the tree, set some children and whatnot and all of this will appear in your NSOutlineView when you run the program.

So once your tree is created, whether by you in the -init method or by your user at runtime, you’ll most likely want to search through the tree from time to time. In your app controller you can generate a ‘flat’ version of the tree with the following method:

- (NSArray *)discreteProjectContent;
{
 NSMutableArray *discreteProjectContent = [NSMutableArray array];
 for (ESSourceNode *item in self.projectContent) {
 	[discreteProjectContent addObject:item];
 	if (!item.isLeaf)
 		[discreteProjectContent addObjectsFromArray:[item descendants]];
 }
 return [[discreteProjectContent copy] autorelease]; // return immutable
}

Try it out. You get all the nodes in the tree in one long array, you can then search through the array for the item you want, for example by nodeName, and get a pointer to any item in the tree.

For really great additions to NSTreeController I point you in the direction of Wil Shipley’s blog, which has a great few NSTreeController extensions. When used in conjunction with the code above, you can get a pointer to an item in the tree and call his -indexPathToObject: method and you can then select any object in the tree.