Download the source code for the Favorite Things project.

A Few of My Favorite Things

My kids have been watching The Sound of Music lately, but that’s not what made me decide to use a list of favorite things as the premise of my example code (sorry if that just got a Julie Andrews song stuck in your head. For the rest of you who have no idea what I’m talking about, move along. Nothing to see here). What made me think of it is the fact that your favorite things might need re-ordered from time to time. A list of my favorite things all seem to be Apple products as the example code shows. Yours might be something else. I’ve added a method at the start of this example app to populate the Core Data database with a list of a few of my favorite things (“♫♫…when the dog bites, when the bee stings, when you’re feeling sad ♫♫… ooops, sorry). I first fetch the list and if it’s empty I go ahead and populate the Core Data data store. Here is that code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

- (void)loadFavoriteThingsData;
{
  if ([[fetchedResultsController fetchedObjects] count] > 0)
    return;
 
  NSManagedObject *favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"MacBook Pro" forKey:@"thingName"];
  [favoriteThing setValue:@"A powerful computer that will burn your lap." forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:0] forKey:@"displayOrder"];
 
  favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"iPad" forKey:@"thingName"];
  [favoriteThing setValue:@"That's a really big iPod!" forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:1] forKey:@"displayOrder"];
 
  favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"iPhone" forKey:@"thingName"];
  [favoriteThing setValue:@"A computer that thinks it's a phone." forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:2] forKey:@"displayOrder"];
 
  favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"iPod" forKey:@"thingName"];
  [favoriteThing setValue:@"Also known as the iPad nano." forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:3] forKey:@"displayOrder"];
 
  favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"WWDC Ticket" forKey:@"thingName"];
  [favoriteThing setValue:@"It sold out in eight days this year, you know?" forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:4] forKey:@"displayOrder"];
 
  [managedObjectContext save:nil];
}

Our Core Data database will now be populated with some initial data so we’ll have something to see. Here is what the initial screen looks like:

Display Order Attribute

In order to implement re-ordering, your entity in your Core Data model will need a displayOrder attribute (you can call it whatever you want, but I’ve named mine displayOrder). This is an integer that will keep track of your indexes and is the field you will use to sort your results in the fetch request sort descriptor. Here is what the code looks like to fetch the entities using the displayOrder attribute as the sort descriptor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

- (NSFetchedResultsController *)fetchedResultsController
{
  if (fetchedResultsController) return fetchedResultsController;
 
  NSFetchRequest *fetchRequest = [[NSFetchRequest alloc] init];
  NSEntityDescription *entity = 
               [NSEntityDescription entityForName:@"FavoriteThing" 
                           inManagedObjectContext:managedObjectContext];
 
  [fetchRequest setEntity:entity];
 
  NSSortDescriptor *sortDescriptor = 
              [[NSSortDescriptor alloc] initWithKey:@"displayOrder" 
                                          ascending:YES];
 
  NSArray *sortDescriptors = [[NSArray alloc] 
                              initWithObjects:sortDescriptor, nil];  
  [fetchRequest setSortDescriptors:sortDescriptors];
 
  NSFetchedResultsController *aFetchedResultsController = 
              [[NSFetchedResultsController alloc] initWithFetchRequest:fetchRequest 
                                                  managedObjectContext:managedObjectContext
                                                    sectionNameKeyPath:nil cacheName:@"ThingsCache"];
  aFetchedResultsController.delegate = self;
  [self setFetchedResultsController:aFetchedResultsController];
 
  [aFetchedResultsController release];
  [fetchRequest release];
  [sortDescriptor release];
  [sortDescriptors release];
 
  return fetchedResultsController;
}

Your Core Data entity that you want to re-order should look something like this in the data model editor in Xcode:

Favorites Change

This post is about re-ordering so here is the point. NSFetchedResultsController doesn’t have a built in way to re-order the results, so load them into an NSMutableArray, rearrange them there, and then re-iterate over the items once sorted setting each of their displayOrder field as you go. Then save the managed object context and you’re all re-ordered.

The reason we use an NSMutableArray is because we can insert and remove managed object pointers to/from the array without triggering any changes to the data store. When you make changes to the objects themselves the change is reflected immediately–which is often what we want, but sometimes we don’t as in this case. In Marcus’ Core Data book he points out that you can keep KVO messages from being sent when you want to change a managed object’s attributes by calling -setPrimitiveValue:forKey, but it seemed simpler to me to just re-arrange the objects in an array, and then make the change to each of the object’s displayOrder attribute. Here is the code you use to re-order the results:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

- (void)tableView:(UITableView *)tableView 
moveRowAtIndexPath:(NSIndexPath *)sourceIndexPath 
      toIndexPath:(NSIndexPath *)destinationIndexPath;
{  
  NSMutableArray *things = [[fetchedResultsController fetchedObjects] mutableCopy];
 
  // Grab the item we're moving.
  NSManagedObject *thing = [[self fetchedResultsController] objectAtIndexPath:sourceIndexPath];
 
  // Remove the object we're moving from the array.
  [things removeObject:thing];
  // Now re-insert it at the destination.
  [things insertObject:thing atIndex:[destinationIndexPath row]];
 
  // All of the objects are now in their correct order. Update each
  // object's displayOrder field by iterating through the array.
  int i = 0;
  for (NSManagedObject *mo in things)
  {
    [mo setValue:[NSNumber numberWithInt:i++] forKey:@"displayOrder"];
  }
 
  [things release], things = nil;
 
  [managedObjectContext save:nil];
}

Further Considerations

You may be thinking that if you iterate through every object in your results you’re actually loading them into memory. This is true, but not something to be concerned about for a couple reasons. First, the results were loaded into memory to display in the table view already. Also, in any table view where you are planning to re-order your results, it is highly unlikely that your list of objects will be very long as trying to re-order too many objects would just prove frustrating for your user and your design has just clearly demonstrated the need to be re-designed at that point anyhow.

Finishing Up

There are just a few more points I want to make before we’re done.

The project template I used is just the default navigation template along with Core Data for storage.

In order for the table view to display the detail text, you need to instantiate your UITableViewCells using the UITableViewCellStyleSubtitle constant. Here is the code to do so:

1
2
3
4
5
6
7
8

static NSString *CellIdentifier = @"Cell";
 
UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
if (cell == nil)
{
  cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle 
                                 reuseIdentifier:@"Cell"] autorelease];
}

Finally, remember that you have to implement -canMoveRowAtIndexPath and return YES if you want the re-order control to display:

1
2
3
4

- (BOOL)tableView:(UITableView *)tableView canMoveRowAtIndexPath:(NSIndexPath *)indexPath
{
  return YES;
}

Conclusion

The NSFetchedResulsController in tandem with a simple NSMutableArray works great to provide re-ordering for your table views. Until next time.

Download the source code for the Favorite Things project.

Why are these topics linked?

Generally, there are a few ways to add plug-ins to a Cocoa application.

Scriptable plug-ins

Scriptable plug-ins are probably the easiest to add to an application. They exist in a known location where the application can load them and run them in the appropriate virtual machine. This makes them fairly easy to construct even though the code to run them may be rather complicated.

Publishing a Formal Protocol Plug-ins Interface

This one is a bit more complicated. The developer (you and me) publish a formal protocol that the plug-ins must adhere to. This design works rather well but does not allow us, the application developer, to impart any functionality to the plug-ins easily.

Publishing an Informal Protocol Plug-ins Interface

This is very similar to the formal plug-ins above but a little more tricky. Since the protocol is informal, we have to test for each method that we want to use in the plug-ins before we can use it. Again, it does not make it very easy for us to impart functionality to the plug-ins.

Publishing a Base Class Plug-ins Interface

This is the hardest option I have found so far. Not only do we have to give our plug-ins developers a header file but something to actually compile against. However, with a base class we can easily impart functionality to our plug-ins without the plug-ins developer having to jump through too many hoops.

Creating a base class solution is where frameworks come in. It makes it fairly trivial to hand off a base class to plug-ins developers when we give them a framework. Therefore, we are going to add one class to the plug-ins we wrote previously with the following header:

#import <Cocoa/Cocoa.h>
 
@interface AbstractPlugin : NSObject 
{
 
}
 
- (NSString*)name;
 
- (IBAction)fire:(id)sender;
 
@end

And since I like to make it stupidly easy for people, we are going to use the following implementation of the base “abstract” class:

#import "AbstractPlugin.h"
 
#define kErrFormat @"%s not implemented in subclass %@"
#define kExceptName @"CIMGF"
 
@implementation AbstractPlugin
 
- (NSString*)name;
{
  NSString *reason = [NSString stringWithFormat:kErrFormat, 
    _cmd, [self class]];
  @throw [NSException exceptionWithName:kExceptName 
                                 reason:reason 
                               userInfo:nil];
}
 
- (IBAction)fire:(id)sender;
{
  NSString * reason = [NSString stringWithFormat:kErrFormat, 
    _cmd, [self class]];
  @throw [NSException exceptionWithName:kExceptName 
                                 reason:reason 
                               userInfo:nil];
}
 
@end

For every method that the subclass must override the abstract class will throw an exception if it is not overwritten with a polite message explaining what method in which class is missing.

Building the plug-ins

A plug-ins is effectively just a bundle, like a framework or an application. Inside of the bundle is a Contents directory, MacOS directory (where the binary goes) and a Resources directory.

Xcode has a template for building plug-ins that we can use to get started. For this first plug-ins, we are going to just add it to our existing project as a new target.

This new target is very similar to the Framework target that we built previously. We want to drag it up into the Application’s target so that it is a dependency; this can also be done from the Get Info window. We will also want to add the Framework product as a linked framework in the plug-ins. The end result looks like this.

Once we have the target set up, it is time to add some code. Plug-ins needs to have either a main class defined or a main nib defined. It is this definition that helps determine how to launch the bundle. In our case, we will want to define a main class which will be explained below. To define a main class (or nib), we need to look at the properties tab of the target.

The next step is to create the main class for our plug-ins. Since we are using a base class design for our plug-ins, our main class must extend the AbstractPlugin class and it needs to import the framework directly in the header. For our example, our plug-ins is going to display a new window on the screen, therefore the header must also include a NSWindow attribute and since we want to programmatically close the window, a -closeWindow: IBAction.

#import <Cocoa/Cocoa.h>
#import <Example/Example.h>
 
@interface PluginMainClass : AbstractPlugin 
{
  IBOutlet NSWindow *mainWindow;
}
 
- (IBAction)closeWindow:(id)sender;
 
@end

Note that we are importing the framework which contains the AbstractPlugin super class we built earlier.

Once we have the main class defined it is time to build the user interface to go along with this plug-ins. It is not a requirement that plug-ins have a user interface, they can be pure code instead. However for the sake of completeness, we are going to add one for this example.

The structure of the plug-ins nib is simple. The file owner is the PluginMainClass we wrote previously and there is one window which we bind to the file owner.

The window is also equally simple, just one button that binds back to the file owner’s -closeWindow: method.

The last step is to add a copy phase to our application. Like the framework copy phase we built last time, this is a “Copy Files” build phase and we need to configure it to copy files to the “PlugIns” directory. This is another top level directory next to Resources and Frameworks. Once the build phase is added, drag the plug-ins product into that build phase.

With the window and the main class built we can compile the plug-ins and make sure everything is ready for inclusion into our application. Once the app is built, we should see a copy of the plug-ins inside of the application bundle. Now it is time to dynamically load the bundle.

The flow of loading bundles dynamically is as follows:

1. Find the paths of the bundles.
2. Instantiate NSBundle objects for the paths.
3. Execute the -load method on the bundle.
4. Retrieve the principal class from the bundle.
5. Instantiate an object from the principal class.

And the code for this is as follows:

- (NSArray*)loadPlugins
{
  NSBundle *main = [NSBundle mainBundle];
  NSArray *all = [main pathsForResourcesOfType:@"bundle" 
                                   inDirectory:@"../PlugIns"]];
 
  NSMutableArray *availablePlugins = [NSMutableArray array];
 
  id plugin = nil;
  NSBundle *pluginBundle = nil;
 
  for (NSString *path in all) {
    pluginBundle = [NSBundle bundleWithPath:path];
    [pluginBundle load];
 
    Class prinClass = [pluginBundle principalClass];
    if (![prinClass isSubclassOfClass:[AbstractPlugin class]]) {
      continue;
    }
 
    plugin = [[prinClass alloc] init];
    [availablePlugins addObject:plugin];
    [plugin release], plugin = nil;
    pluginBundle = nil;
  }
  return availablePlugins;
}

In this new method that we have added to the AppDelegate we first get a reference to the main bundle and we then request a path for every file in the PlugIns directory that has an extension of bundle. With that array in hand we then start to loop over the array and construct a new NSBundle for each path. Once the bundle is constructed we ask for it to load. After the load, we grab its principal class, check to make sure we can use it, and construct an object from it.

Since we want to have a list of the loaded plug-ins, we throw this new object into an array that will be returned back from the method. Once this method is complete we now have every plug-ins dynamically loaded and ready to use. So lets use them!

We really want to call this method before the application has finished loading, therefore we need to add an -init method to our AppDelegate and load the plug-ins there. This will guarantee that they are loaded before the UI with some obvious benefits.

- (id)init
{
  if (![super init]) return nil;
 
  [self setPlugins:[self loadPlugins]];
 
  return self;
}

Here are we calling our new -loadPlugins method and setting the returned array into a ivar. This ivar will then be used by our UI once it loads to display a list of the plug-ins.

The main window has a pop up button with a list of the plug-ins using their inherited -name method for display. When the run button is clicked, our application will find out which plug-ins were selected via the NSArrayController and call the inherited -run: method on the plug-ins with predictable results.

Conclusion

For clarity we did leave a few things out of this project. For example, there is no code for unloading the plug-ins nor do we search the Application Support directory for user added plug-ins. However these are easy to add based on the code that was included.

I should also note that we used the default extension for these plug-ins. I would recommend changing this extension to something unique to your application and add that extension (or UTI) to your main application as an accepted file type. See previous articles here on CIMGF to see how to do each of those.

Example Project

Getting two technologies to work together can be a challenge especially when the bridges between the two are not necessarily clearly laid out in documentation. As I pointed out Apple provides some excellent sample code to help you along, but there is no hand-holding approach to any of it. I actually appreciate that having come from the Windows world as it seems that there all you get sometimes is hand-holding where Microsoft doesn’t trust you, the developer to figure things out and really own what you’re doing. But I digress (wouldn’t be a CIMGF post if I didn’t dig on MS a bit).

Like peanut butter and chocolate, what you get when you put together QuickTime and OpenGL is something greater than either of them left on their own (ok, this is subjective. Not everyone likes peanut butter and chocolate together, but again, I digress).

If you read the Core Video Programming Guide from Apple, you see they provide the reasons for using Core Video:

CoreVideo is necessary only if you want to manipulate individual video frames. For example, the following types of video processing would require CoreVideo:

• Color correction or other filtering, such as provided by Core Image filters
• Physical transforms of the video images (such as warping, or mapping on to a surface)
• Adding video to an OpenGL scene
• Adding additional information to frames, such as a visible timecode
• Compositing multiple video streams

If all you need to do is display a movie, you should simply use either a QTMovieView or, if you want to stick with the Core Animation route, use a QTMovieLayer. They both function similarly, however, the view provides a lot of features that you won’t have to implement in the UI yourself such as a scrubber or play/pause buttons. Plus the view is very fast and efficient. I’m in the process of exploring performance differences between the two, but I will save my comments about that for another post.

For our example code we are most interested in the third point above–adding video to an OpenGL scene. It seems that new QuickTime developers often want to know how to manipulate movie images before displaying them. Often this leads them to pursue adding sub-views to the movie view which can become a big mess. Because we are using OpenGL, doing other drawing on the scene is very fast. I won’t kid you. OpenGL is a pain. I don’t know anybody who loves it, but everybody respects it because of its raw speed.

Point number five above–compositing multiple video streams–is also interesting. While I won’t be covering it in this post, I will say that it makes a world of difference performance wise if you composite the movies into a OpenGL scene. If you’ve ever tried to run multiple videos simultaneously in two different views or layers, it can get pretty herky jerky. You can see why it is necessary to use OpenGL instead.

The OpenGL QuickTime Two Step

Ok, it actually will take more than two steps, however, when you are working with Core Animation layers things get a whole lot easier than they are for rendering a movie in an NSOpenGLView. Here is what you get for free, as the kids say.

• You don’t have to set up the OpenGL context. It is already available for you to send your OpenGL calls to.
• The viewport for display is already configured
• You don’t need to set up a display link callback

What took over 400 lines of code when rendering a QuickTime movie with no filters to an NSOpengGLView now only takes around 150 lines. Any time you can reduce code to something simpler, it makes life easier. It also makes it much easier to grok, in my opinion.

There really are two primary steps you take when using a CAOpenGLLayer. First you check to see if you should draw. Then, depending upon the answer, drawInCGLContext gets called or doesn’t. Really thats it. Determining whether or not you should draw depends upon what you are trying to do. In our case, we only want to draw if all of the following are true:

• The movie is actually playing back
• The visual context for the movie has been initialized
• The visual context has a new image ready to be rendered

If all of these are true, then our call to canDrawInCGLContext returns YES. Here is the code I use to check these contraints in canDrawInCGLContext:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

- (BOOL)canDrawInCGLContext:(CGLContextObj)glContext 
                pixelFormat:(CGLPixelFormatObj)pixelFormat 
               forLayerTime:(CFTimeInterval)timeInterval 
                displayTime:(const CVTimeStamp *)timeStamp
{ 
    // There is no point in trying to draw anything if our
    // movie is not playing.
    if( [movie rate] <= 0.0 )
        return NO;
 
    if( !qtVisualContext )
    {
        // If our visual context for our QTMovie has not been set up
        // we initialize it now
        [self setupVisualContext:glContext withPixelFormat:pixelFormat];
    }
 
    // Check to see if a new frame (image) is ready to be draw at
    // the time specified.
    if(QTVisualContextIsNewImageAvailable(qtVisualContext,timeStamp))
    {
        // Release the previous frame
        CVOpenGLTextureRelease(currentFrame);
 
        // Copy the current frame into our image buffer
        QTVisualContextCopyImageForTime(qtVisualContext,
                                        NULL,
                                        timeStamp,
                                        &currentFrame);
 
        // Returns the texture coordinates for the part of the image that should be displayed
        CVOpenGLTextureGetCleanTexCoords(
                            currentFrame, 
                            lowerLeft, 
                            lowerRight, 
                            upperRight, upperLeft);
        return YES;
    }
 
    return NO;
}

The call to setup the visual context is where we are associating the QuickTime movie itself with a QTVisualContextRef object which is what OpenGL needs to draw the current frame. We will then use this object to load image data into a CVImageBufferRef which can be used for rendering with OpenGL. Here is the code to set up the visual context.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

- (void)setupVisualContext:(CGLContextObj)glContext 
           withPixelFormat:(CGLPixelFormatObj)pixelFormat;
{
    OSStatus			    error;
 
    NSDictionary	    *attributes = nil;
    attributes = [NSDictionary dictionaryWithObjectsAndKeys:
                  [NSDictionary dictionaryWithObjectsAndKeys:
                   [NSNumber numberWithFloat:[self frame].size.width],
                   kQTVisualContextTargetDimensions_WidthKey,
                   [NSNumber numberWithFloat:[self frame].size.height],
                   kQTVisualContextTargetDimensions_HeightKey, nil], 
                  kQTVisualContextTargetDimensionsKey, 
                  [NSDictionary dictionaryWithObjectsAndKeys:
                   [NSNumber numberWithFloat:[self frame].size.width], 
                   kCVPixelBufferWidthKey, 
                   [NSNumber numberWithFloat:[self frame].size.height], 
                   kCVPixelBufferHeightKey, nil], 
                  kQTVisualContextPixelBufferAttributesKey,
                  nil];
 
    // Create our quicktimee visual context
    error = QTOpenGLTextureContextCreate(NULL,
                                         glContext,
                                         pixelFormat,
                                         (CFDictionaryRef)attributes,
                                         &qtVisualContext);
 
    // Associate it with our movie.
    SetMovieVisualContext([movie quickTimeMovie],qtVisualContext);
}

Next we check to see if there is an image ready using:

1

if(QTVisualContextIsNewImageAvailable(qtVisualContext,timeStamp))

And then we copy the image to our CVImageBufferRef with:

1
2
3
4
5

// Copy the current frame into our image buffer
QTVisualContextCopyImageForTime(qtVisualContext,
                                NULL,
                                timeStamp,
                                &currentFrame);

Now it’s all a matter of rendering the frame for the current time stamp.

But Wait! What TimeStamp?

If you asked this question, then you are a very astute reader. In order to obtain the next image, we simply passed the CVTimeStamp parameter, timeStamp to our call to QTVisualContextCopyImageForTime. But how do we even have a timestamp? Isn’t that something we need to get from a display link? If you’re asking what is a display link at this point, take a look at the Core Video Programming Guide which states:

To simplify synchronization of video with a display’s refresh rate, Core Video provides a special timer called a display link. The display link runs as a separate high priority thread, which is not affected by interactions within your application process. In the past, synchronizing your video frames with the display’s refresh rate was often a problem, especially if you also had audio. You could only make simple guesses for when to output a frame (by using a timer, for example), which didn’t take into account possible latency from user interactions, CPU loading, window compositing and so on. The Core Video display link can make intelligent estimates for when a frame needs to be output, based on display type and latencies.

I will provide a more complete answer to the question in the future as I am still studying it myself, however, I will mention that a display link callback is unnecessary in this context as the CAOpenGLLayer is providing this for us. The timestamp field is all we need in order to get the current frame assuming that the movie is playing back.

Drawing The Frame

There is a special group of people who really get OpenGL. I salute all of you to whom this applies. You are amazing. I, however, only write as much of it as necessary and you’ll see that most of the code I have here is simply a copy and paste from sample code I got from Apple. I am starting to understand it more and more, however, it makes my brain hurt. Here is my drawing code for when a frame is ready to be rendered.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

- (void)drawInCGLContext:(CGLContextObj)glContext 
             pixelFormat:(CGLPixelFormatObj)pixelFormat 
            forLayerTime:(CFTimeInterval)interval 
             displayTime:(const CVTimeStamp *)timeStamp
{
    NSRect    bounds = NSRectFromCGRect([self bounds]);
 
    GLfloat 	minX, minY, maxX, maxY;        
 
    minX = NSMinX(bounds);
    minY = NSMinY(bounds);
    maxX = NSMaxX(bounds);
    maxY = NSMaxY(bounds);
 
    glMatrixMode(GL_MODELVIEW);
    glLoadIdentity();
    glMatrixMode(GL_PROJECTION);
    glLoadIdentity();
    glOrtho( minX, maxX, minY, maxY, -1.0, 1.0);
 
    glClearColor(0.0, 0.0, 0.0, 0.0);	     
    glClear(GL_COLOR_BUFFER_BIT);
 
    CGRect imageRect = [self frame];
    // Enable target for the current frame
    glEnable(CVOpenGLTextureGetTarget(currentFrame));
    // Bind to the current frame
    // This tells OpenGL which texture we are wanting 
    // to draw so that when we make our glTexCord and 
    // glVertex calls, our current frame gets drawn
    // to the context.
    glBindTexture(CVOpenGLTextureGetTarget(currentFrame), 
                  CVOpenGLTextureGetName(currentFrame));
    glMatrixMode(GL_TEXTURE);
    glLoadIdentity();
    glColor4f(1.0, 1.0, 1.0, 1.0);
    glBegin(GL_QUADS);
 
    // Draw the quads
    glTexCoord2f(upperLeft[0], upperLeft[1]);
    glVertex2f  (imageRect.origin.x, 
                 imageRect.origin.y + imageRect.size.height);
    glTexCoord2f(upperRight[0], upperRight[1]);
    glVertex2f  (imageRect.origin.x + imageRect.size.width, 
                 imageRect.origin.y + imageRect.size.height);
    glTexCoord2f(lowerRight[0], lowerRight[1]);
    glVertex2f  (imageRect.origin.x + imageRect.size.width, 
                 imageRect.origin.y);
    glTexCoord2f(lowerLeft[0], lowerLeft[1]);
    glVertex2f  (imageRect.origin.x, imageRect.origin.y);
 
    glEnd();
 
    // This CAOpenGLLayer is responsible to flush
    // the OpenGL context so we call super
    [super drawInCGLContext:glContext 
                pixelFormat:pixelFormat 
               forLayerTime:interval 
                displayTime:timeStamp];
 
    // Task the context
    QTVisualContextTask(qtVisualContext);
 
}

If you’re not familiar with OpenGL it would help you to know that it’s all about the current state. What does this mean? Well, simply put, it means that the call you are making right now, applies to whatever state the context is in. These two calls are what are the most important for our purposes.

1
2
3

glEnable(CVOpenGLTextureGetTarget(currentFrame));
glBindTexture(CVOpenGLTextureGetTarget(currentFrame), 
                  CVOpenGLTextureGetName(currentFrame));

With these two calls we have told OpenGL which texture to use. Now, every subsequent call applies to this texture until the state is changed to something else. So now, when we set a color or draw a quad, it applies to the texture that has been set here.

Conclusion

I love both of these technologies, QuickTime and OpenGL. They are so powerful. It’s harnessing the power that’s the trick. I’ve got some other ideas for some related posts that I plan to cover in the weeks to come, but this was a real breakthrough for me. With the help of John Clayton, Jean-Daniel Dupas, and David Duncan on the cocoa-dev list, I was able to get the sample code put together for this post. Feel free to ask questions in the comments. I will do my best to answer, but I’m still pretty new to these technologies. Write some code yourself and have fun. This is really exciting stuff. Until next time.

About The Demo Code

John Clayton has some issues getting the code to work on his Mac Pro. I successfully ran it on my MacBook Pro, and the family iMac without any issues. Anyhow, we’re not sure what the problem is, so if you do run into trouble, let me know. Maybe we can figure it out. Meanwhile we’re investigating it as we have time.

Update: John Clayton figured it out. Apparently the visual context needs to be reset because the pixel format is not correct on the first run. We just reset the visual context now in the call to -copyCGLContextForPixelFormat and everything seems happy. The demo code has been updated to reflect the change.

Quicktime CAOpenGLLayer Demo

If you are using Core Data in a Leopard application then Sync Services is so trivial that you should be syncing if it makes sense. In this article we are going to cover syncing in a non-Core Data situation as that is quite a bit more complex.

If you have read the Sync Services documentation then you know it is complex. Let me dispel an illusion right away. It is hard. It is not poor documentation, syncing is very hard and very few people get it right. Take a look at Omnifocus to see an example of a company thinking it is easy and losing data. Therefore if you are expecting this subject to be trivial you will be disappointed.

In this example we will be syncing with the bookmarks schema and displaying them in a simple outline view. The outline view itself will be editable and those edits can be synced back. Not terribly useful but provides a very simple example.

Sync Services Setup

There are a few different ways to implement sync services inside of your application. You can set up a sync client and handle everything manually just like we did in Tiger but to be honest, unless you need Tiger compatibility, I would not use that approach again. The option we are going to use in this article is new to Leopard and that will be employing a ISyncDriver. The driver is basically a default sync client that handle some of the mess for us. To create the driver, we need to pass it a data source:

syncDriver = [[ISyncSessionDriver sessionDriverWithDataSource:self] retain];
[syncDriver setDelegate:self];
 
[self setPreferredSyncMode:ISyncSessionDriverModeFast];
 
SEL syncSEL = @selector(client:willSyncEntityNames:);
[[syncDriver client] setSyncAlertHandler:self selector:syncSEL];
 
[syncDriver sync];

In our example application, we are going to hold on to a reference to the syncDriver object so that we can request syncs whenever it is appropriate. To be a data source for the ISyncSessionDriver class, the object needs to implement the protocol ISyncSessionDriverDataSource. While this protocol has a few optional methods, pretty much all of the methods in the protocol are required. In the example application for this article, the application’s delegate is also the data source and the delegate. I would not recommend this for a production application as it makes the application delegate pretty big; it is sufficient for this example.

Once the syncDriver has been initialized, I want to request a sync immediately on start up. This makes sure that the application is dealing with fresh data as opposed to something that may have changed while the application was not running¹. Just before I call [syncDriver sync] though I do want to flag my object as the handler for sync alerts. This is a callback method used by the sync engine to tell my application that a sync is occurring on data that I care about and it gives me the opportunity to be apart of that sync. Once I have set myself up as a receiver for those alerts it is time to perform the first sync.

There are essentially three phases when your application is going to perform a sync. Two of those phases our application will have a direct involvement with. The first phase, called the push phase, is where we send our data to the Truth. The Truth is a database that lives on each Mac and keeps track of all the data that is being synced. The Truth handles all merging of data and each application can request a copy of data from it.

Push

In the first phase of a sync, we push our data to the Truth. Since this example application does not retain any data this will be very quick. The first part of this push, our application needs to list all of the data objects it knows about for each entity type. The method that handles this is -recordsForEntityName: moreComing: error:. This method returns a dictionary of all the data for a specific entity name.

In that NSDictionary, the key is the unique identifier for that record which is provided by the Truth. The object is another NSDictionary with the properties of the object contained within. In our example application, this method is implemented as follows:

-(NSDictionary*)recordsForEntityName:(NSString*)entityName 
                          moreComing:(BOOL*)moreComing 
                               error:(NSError**)outError
{
	NSMutableDictionary *dict = [NSMutableDictionary dictionary];
 
  for (NSString *recordID in [[self recordLookup] allKeys]) {
    id object = [self objectForRecordIdentifier:recordID];
    NSString *objectEntityName = [[object class] entityName];
    if (![objectEntityName isEqualToString:entityName]) {
      continue;
    }
    [dict setValue:[object fullRecord] forKey:recordID];
  }
 
  *moreComing = NO;
  return dict;
}

The more coming flag is used when an application wants to send the data in batches. If it is set to YES then the method will be called repeatedly with the same entityName until a NO is received. NOTE:This method is normally only called on the first sync.

Once our application had told the Truth about all of the data it knows about, the next part of the push phase is to send any changes that have occurred since the last sync. This is handled in one of two methods. If our application can accurately describe each property that has changed then the -changesForEntityName: moreComing: error: method can be used. If, however, we only know that an object has changed but not which specific properties, then the -changedRecordsForEntityName:moreComing:error: method would be used. The former method is easier on the sync since it does not need to resolve that information itself. In our implementation we will be using the latter implementation to make our lives easier.

-(NSDictionary*)changedRecordsForEntityName:(NSString*)entityName 
                                 moreComing:(BOOL*)moreComing 
                                      error:(NSError**)outError
{
  NSMutableDictionary *dict = [NSMutableDictionary dictionary];
  for (NSString *key in [[self recordLookup] allKeys]) {
    id object = [[self recordLookup] objectForKey:key];
    if (![object updated]) continue;
    if (![[object entityName] isEqualToString:entityName]) continue;
    [dict setObject:[object fullRecord] forKey:key];
  }
  return dict;
}

Here we are looping through all of our objects (we store them in a NSDictionary as well to make life easier in the demo) and if an object has the right entity name as well as being flagged as updated we send its data back. Again, we can set the moreComing flag to YES if we need to handle the data in batches.

Mingle

Once we have pushed our data and our changes up to the server and all of the other participants of this sync session have done the same, the Truth mingles the data. It will do its best to merge everything and if it fails it will ask the user to decide which change is the correct one.

Clients have no participation in this phase of the sync session. Once the mingle is complete the next phase is started automatically by the ISyncSessionDriver.

Push

Once the data has been mingled, the Truth will then inform each client of any changes that have taken place. It is expected that each client will accept these changes and store them in their local data stores. The method that is called is -applyChange:forEntityName:remappedRecordIdentifier:formattedRecord:error:. This method will be called for each entity that has changed as a result of the mingle so it needs to be as efficient as possible.

When this method is called, a ISyncChange object is passed in. This object contains all of the information about the change that needs to be performed. The first thing that needs to be looked at is what type of change it is. A change can be a new record, deleting an existing record or updating a record. Our implementation of this method is as follows:

-(ISyncSessionDriverChangeResult)applyChange:(ISyncChange*)change 
                                forEntityName:(NSString*)entityName 
                     remappedRecordIdentifier:(NSString**)outRecordIdentifier 
                              formattedRecord:(NSDictionary**)outRecord 
                                        error:(NSError**)err
{
  NSDictionary *errDict = nil;
  id record = nil;
  switch ([change type]) {
    case ISyncChangeTypeDelete:
      [[self recordLookup] removeObjectForKey:[change recordIdentifier]];
      return ISyncSessionDriverChangeAccepted;
    case ISyncChangeTypeAdd:
      if ([entityName isEqualToString:[FolderEntity entityName]]) {
        record = [[FolderEntity alloc] init];
      } else if ([entityName isEqualToString:[BookmarkEntity entityName]]) {
        record = [[BookmarkEntity alloc] init];
      } else {
        errDict = [NSDictionary dictionaryWithObject:@"Unknown type"
                                              forKey:NSLocalizedDescriptionKey];
        *err = [NSError errorWithDomain:@"CIMGF" code:8002 userInfo:errDict];
        return ISyncSessionDriverChangeError;
      }
      [record setRecordIdentifier:[change recordIdentifier]];
      [[self recordLookup] setObject:record forKey:[change recordIdentifier]];
      break;
    case ISyncChangeTypeModify:
      record = [[self recordLookup] objectForKey:[change recordIdentifier]];
      break;
    default:
      errDict = [NSDictionary dictionaryWithObject:@"Unknown type"
                                            forKey:NSLocalizedDescriptionKey];
      *err = [NSError errorWithDomain:@"CIMGF" code:8001 userInfo:errDict];
      return ISyncSessionDriverChangeError;
  }
  for (NSDictionary *changeDict in [change changes]) {
    NSString *action = [changeDict valueForKey:ISyncChangePropertyActionKey];
    NSString *name = [changeDict valueForKey:ISyncChangePropertyNameKey];
    if ([name isEqualToString:kRecordEntityName]) {
      continue;
    }
    if ([action isEqualToString:ISyncChangePropertyClear]) {
      [record setNilValueForKey:name];
      continue;
    }
    id value = [changeDict valueForKey:ISyncChangePropertyValueKey];
    [record setValue:value forKey:name];
  }
  [record setUpdated:NO];
  return ISyncSessionDriverChangeAccepted;
}

In this method we use a switch to determine what type of change that it is. If it is a delete we remove the record from our global store and return happy. If it is an add then we create a new empty object and set the recordIdentifier. Lastly, if it is a change we retrieve the record from our global store.

Once the object that is going to be changed has been referenced we loop through the changes which are stored in an array inside of the ISyncChange object. Each object in the array is a dictionary containing up three values. The first value has a key of ISyncChangePropertyActionKey and the value can either be ISyncChangePropertySet or ISyncChangePropertyClear. If it is a clear then we are to set the property to nil. Otherwise we change the property to the value stored under key ISyncChangePropertyValueKey. The name of the property is stored under the key ISyncChangePropertyNameKey. If our properties use the same name as the sync objects they represent (and in our case they do) then this step is performed in a loop using KVC to update each property.

Once we have updated the object we return ISyncSessionDriverChangeAccepted to let the sync engine know that everything is happy. We could have returned ISyncSessionDriverChangeIgnored or ISyncSessionDriverChangeRejected if we did not accept the change for some reason. In either of those cases the object and its changes would not be sent to us again unless it changed in the future. Lastly, if there is a problem, we can return ISyncSessionDriverChangeError if there was an error. If we return that, however, the sync engine expects us to populate the NSError pointer before returning.

There are two other pointers that get passed in that should be mentioned. The first one, called outRecordIdentifier in this example is used in the case where we do not want to use the recordIdentifier being passed to us. Perhaps we have our own internal schema or we want to reference this record by another identifier. If we set this pointer then the Truth will remember that change and use the new identifier in the future when talking to us. It will not use this new identifier when talking to anyone else though. This is useful when syncing with a database that uses something other than a guid for uniqueness. The second one, called outRecord in this example, is used to update the object. Perhaps we had a field on new records or change a field; in either case those changes can be sent back to the Truth via this pointer.

Other Data Source methods

That is the major points of a sync. We of course have a lot more flexibility to cover edge cases and we can make changes at any step in the process via the delegate methods but those are the points of contact for passing data back and forth. Other than those complicated touch points, there are a few other methods that need to be implemented to make a sync work. Those methods are more administrative and far less complicated.

• clientIdentifier
  This is the unique string that identifies this client to the Truth. I like to use the bundle identifier here just to make things simple.
• schemaBundleURLs
  This method returns an array of NSURL objects. Each NSURL object points to a schema either on disk or on the net that describes the data to be stored in the Truth. If we are creating a new set of data then we would need to generate a schema (and there is a template in Xcode for that purpose). If not then we need to reference the existing schema.
• entityNamesToSync
  It is not necessary to sync every entity in a schema (although in our case we do since there are only two). If we only care about a subset of the data then we can request to sync only those entities we care about. In any case we pass back an array of strings here to let the sync engine know which entities we care about.
• preferredSyncModeForEntityName
  A fast sync is always the goal. However if we need to refresh an object or perform a slow sync (useful when a large amount of data has changed or we lost our copy of the data) then this is the method that determines it. This method will be called once for each entity we want to sync.
• clientDescriptionURL
  The client description is a plist file that describes this client to the sync engine. For example, the icon used in dialogs is defined in this plist along with the human readable name of the sync client, etc. Also in this plist we define what properties of each entity we want synced. If we only want a subset of the entities we can control that here.

Conclusion

I would not be at all surprised if that was as clear as mud. The sync services framework is complicated, no doubt about that. That complication has a purpose though, it is incredibility powerful as well. Now that I have scratched the surface in this article I will be adding other articles to explain some of the more complicated aspects such as adding properties to an existing schema, mid-sync data changing and more.

If a part of this is unclear, please post a comment and I will update it to help clarify. I would also recommend downloading the example application that is attached as I find the code much easier to understand.

1. There is an option to have a helper tool that sync services will run when your application is not running but that is beyond the scope of this article.

Let us now assume that we have a requirement to parse an xml document quickly and without loading the entire tree into memory in a object structure. In a situation like this libxml comes in handy. Unfortunately it is quite a bit more complicated than calling alloc init on NSXMLDocument.

libxml is a C library that is included with all current releases of OS X. With this library we can quickly read in a document, scrape the information we need out of that document and avoid loading the entire tree into memory at once. In addition, libxml (and more specifically xmlReader) does this very quickly, far faster than NSXMLDocument which is very useful when you have a lower end CPU. In this project we are going to create a simple application that reads in an xml file containing a list of people, their names and their ages. For the purposes of demonstration we are going to load that data into an array of NSDictionary objects and display it in a standard Cocoa window.

The raw XML file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <person>
    <name>John Doe</name>
    <age>14</age>
  </person>
  <person>
    <name>Mary Doe</name>
    <age>14</age>
  </person>
  <person>
    <name>John Smith</name>
    <age>14</age>
  </person>
</root>

Besides being a C library, another difference in the way that we are going to read in this xml file is that the reading is iterative. For each element in the xml file we will be looping over the reader. Therefore, unlike our old friend NSXMLDocument, we will have to actually walk the file one element at a time and evaluate those elements as we receive them. In the xml file listed above, we would first read in the opening root tag, then the opening person tag, the opening name tag, the first name, etc. until we were done with the file.

To accomplish our goal, I created a new Xcode project which can be downloaded below. In this Xcode project, I added the libxml “framework” to the project by right clicking on the target, clicking on the add button, narrowing the focus to libraries and selecting the libxml2.dylib file.

This will link libxml to our project at compile time. However, unlike an Objective-C framework, we do not get access to its headers for free. Therefore the next step is to add the header to our search path. To do so, open the target’s properties and select the build tab. Narrow its focus to “header” and select the header search path entry.

Double click on this row and add /usr/include/libxml to the list of paths. NOTE: Some people have had issues with this path and if you do then you will need to find another copy of these headers in your Xcode installation directory.

Once this is done, we will be able to compile against this library with no errors or warnings. Next, after we add an application delegate and wire it up in our xib file, we need to import libxml in our AppDelegate.h. While we are in here we are going to add a reference for our records array that we will be loading the data into.

#import <Cocoa/Cocoa.h>
#include <libxml/xmlreader.h>
 
@interface AppDelegate : NSObject {
  NSArray *_records;
}
 
@property (retain) NSArray *records;
 
@end

Since xmlReader is so quick, our data set is so small and this is a demonstration only, we are going to read the xml file directly as the application starts. BE WARNED: for a production application THIS IS A BAD IDEA^tm. Fortunately I can get away with a lot in demos. :-)

The first thing we need to do in the -applicationDidFinishLaunching: method is to load the xml data and initialize the xml reader.

  NSString *path = [[NSBundle mainBundle] pathForResource:@"xmlExample" ofType:@"xml"];
  NSData *xmlData = [NSData dataWithContentsOfFile:path];
  xmlTextReaderPtr reader = xmlReaderForMemory([xmlData bytes], 
                                               [xmlData length], 
                                               [path UTF8String], nil, 
    (XML_PARSE_NOBLANKS | XML_PARSE_NOCDATA | XML_PARSE_NOERROR | XML_PARSE_NOWARNING));
  if (!reader) {
    NSLog(@"Failed to load xmlreader");
    return;
  }

In this section, again for demonstration purposes, we are reading in the included xml file into an NSData object. Normally we would be retrieving this data from an NSURLConnection or some other external source. Once the data is loaded, we pass the raw bytes off to the C function xmlReaderForMemory(). This function will return a pointer reference to our xmlReader. This reader is now ready to walk, one way and one time, through our xml file. Now we need to declare some local variables to store our state information while we walk the xml file.

  NSString *currentTagName = nil;
  NSDictionary *currentPerson = nil;
  NSString *currentTagValue = nil;
  NSMutableArray *people = [NSMutableArray array];
  while (true) {
    if (!xmlTextReaderRead(reader)) break;
    switch (xmlTextReaderNodeType(reader)) {

Since this xml file is very simple we do not need to hold onto a lot of state information. Basically when we hit a person tag we will create a new person dictionary and then every time we hit a text node we will store that text node’s value into the dictionary along with the tag name. Finally we will store each of those person dictionaries into an array.

Once our variables are declared and initialized it is time to start walking the xml file. Since we do not know how long it is going to be we will simply loop until we hit the end. Therefore we have a while(true) to start the loop. The first thing we do inside of the loop is to tell the reader to read the next element. If that returns back a 0 we are done with the file and break. If it returns back a positive value then we know the reader has advanced to the next node. Since the node types are stored as integer values, we can use a switch statement to quickly sort them as we are looping. The xmlTextReaderNodeType() function will return that type integer.

For our purposes, we really only care about two of the node types, opening tags and text values. For a more complex xml file we would watch for more information but fortunately we are working in a controlled environment. The tags we are going to watch for are XML_READER_TYPE_ELEMENT and XML_READER_TYPE_TEXT.

When we hit an element we will grab its name, store it temporarily and check to see if it is a person, if it isn’t then we loop. If it is then we create a person and add it to our array.

When we hit a text node then we want to stick it in the current person object. Since we previously stored the name of this element (remember, an element and its text value are two separate nodes), we can grab the value of the text and store it in the dictionary.

Any other type of node is ignored and we continue on the default: tag of the switch.

case XML_READER_TYPE_ELEMENT:
  //We are starting an element
  temp =  (char*)xmlTextReaderConstName(reader);
  currentTagName = [NSString stringWithCString:temp 
                                      encoding:NSUTF8StringEncoding];
  if ([currentTagName isEqualToString:@"person"]) {
    currentPerson = [NSMutableDictionary dictionary];
    [people addObject:currentPerson];
  } 
  continue;
case XML_READER_TYPE_TEXT:
  //The current tag has a text value, stick it into the current person
  temp = (char*)xmlTextReaderConstValue(reader);
  currentTagValue = [NSString stringWithCString:temp 
                                       encoding:NSUTF8StringEncoding];
  if (!currentPerson) return;
  [currentPerson setValue:currentTagValue forKey:currentTagName];
  currentTagValue = nil;
  currentTagName = nil;
default: continue;

Since we check for the completion of the file a the beginning of the loop that is all that we need to do for this example. Once the while loop exits we pass the array to -setRecords: and we are done. Cocoa bindings will take care of the rest for us.

NSError Tutorial

Feel free to read on as this will provide good legacy information. Just note that setting a custom icon for a folder is not as hard as this post would make it seem.

Poking A Stick At It

If you haven’t yet realized in your programming career that often the best and sometimes only way to figure something out is to ‘poke a stick at it’ then it’s probably time you started. I’m not sure where this reference comes from, but it seems apropo. Maybe it’s a cave man thing? You’re not sure what something is, so you poke a stick at it and see what happens.

Different from cave men, though, my proverbial/virtual stick is Terminal.app. If you look inside an iMovie HD project file, which contains folders with custom icons, using Terminal.app you’ll see a listing that looks something like this.

drwxr-xr-x@  6 mlong  staff   204 Mar 17 18:00 Cache
-rw-r--r--@  1 mlong  staff  1677 Mar  7 17:22 Makin Guacamole.iMovieProj
-rw-r--r--@  1 mlong  staff   895 Mar  7 17:19 Makin Guacamole~.iMovieProj
drwxr-xr-x@  4 mlong  staff   136 Mar 17 18:00 Media
drwxr-xr-x@  5 mlong  staff   170 Mar  7 17:22 Shared Movies

This is a list from a time lapse movie I made of myself making guacamole. You can watch it here if you’re so inclined. Notice that there are special attributes on each of the files and folders as indicated by the at (@) symbol. You can see what’s going on with a particular directory by using the mdls command. Try it on one of the folders, say Media for example. and you’ll get a listing like this.

bash: mlong$ mdls Media
kMDItemFSContentChangeDate = 2008-03-17 18:00:49 -0600
kMDItemFSCreationDate      = 2008-03-07 17:19:34 -0700
kMDItemFSCreatorCode       = ""
kMDItemFSFinderFlags       = 1024
kMDItemFSHasCustomIcon     = 1
kMDItemFSInvisible         = 0
kMDItemFSIsExtensionHidden = 0
kMDItemFSIsStationery      = 0
kMDItemFSLabel             = 0
kMDItemFSName              = "Media"
kMDItemFSNodeCount         = 2
kMDItemFSOwnerGroupID      = 20
kMDItemFSOwnerUserID       = 501
kMDItemFSSize              = (null)
kMDItemFSTypeCode          = ""

Notice that the attribute called kMDItemFSHasCustomIcon is set to 1. If you now cd into the Media directory and run ls -al. You’ll see something like the following.

bash: mlong$ ls -al
total 31480
drwxr-xr-x@ 4 mlong  staff       136 Mar 17 18:00 .
drwxr-xr-x@ 7 mlong  staff       238 Mar  7 17:22 ..
-rw-r--r--@ 1 mlong  staff         0 Mar 17 18:00 Icon?
-rw-r--r--@ 1 mlong  staff  16056849 Mar  7 17:20 Makin Guacamole 01.mov

See that little 0 byte file called Icon?. This is what is telling the Finder about the custom icon being used.

The next step now that I knew that there was actually a way to specify a custom icon was to do a Google search to see if anyone had provided code to use. It was pretty sparse, but I was able to find something useful which is what this post is really about. A company called Shiny Frog based in Italy posted some open-source code that demonstrates how to set custom folder icons among other things. You can download their entire open-source code base here. I’ve leveraged only the folder icon setting code for this blog post.

Coding It Up

Here are the two projects for this post: Set Custom Icon Project (Procedural Code) Set Custom Icon Project (OO Code)

In the end, this post is not so much a tutorial as it is a showcase of the code. The code that it takes to change a folder icon is fairly lengthy. I have broken it out into two projects here. In the first, I broke out the code from the class that it was in when I downloaded it from Shiny Frog and put it into a procedural format. The second uses the classes as they’re found in the Shiny Frog code. Here is the code for the procedural way in its entirety. I’ve left all of the original comments from Shiny Frog in the code.

Note: If you want to simply use the code as classes, stick around for the next section in this post as I explain how you can just use what Shiny Frog provided.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278

- (void)setIcon:(NSString*)iconFilepath forDirectory:(NSString*)directoryPath;
{
 
    FSRef ref;
    OSStatus result;
    IconFamilyHandle hIconFamily;
 
    CFURLRef urlRef;
    Boolean gotFSRef;
 
    // Create a CFURL with the specified POSIX path.
    urlRef = CFURLCreateWithFileSystemPath( kCFAllocatorDefault,
                                           (CFStringRef) iconFilepath,
                                           kCFURLPOSIXPathStyle,
                                           FALSE /* isDirectory */ );
    if (urlRef == NULL)
    {
        NSLog(@"** Couldn't make a CFURLRef for the file." );
        return;
    }
 
    // Try to create an FSRef from the URL.  (If the specified file doesn't exist, this
    // function will return false, but if we've reached this code we've already insured
    // that the file exists.)
    gotFSRef = CFURLGetFSRef( urlRef, &ref );
    CFRelease( urlRef );
 
    if (!gotFSRef)
    {
        NSLog(@"** Couldn't get an FSRef for the file.\n" );
        return;
    }
    result = ReadIconFromFSRef( &ref, &hIconFamily );
 
    [self setAsCustomIconForDirectory:directoryPath familyHandle:hIconFamily];
 
}
 
- (BOOL) setAsCustomIconForDirectory:(NSString*)path familyHandle:(IconFamilyHandle)hIconFam;
{
    NSFileManager *fm = [NSFileManager defaultManager];
    BOOL isDir;
    BOOL exists;
    NSString *iconrPath;
    FSRef targetFolderFSRef, iconrFSRef;
    SInt16 file;
    OSErr result;
    struct HFSUniStr255 filename;
    struct FSCatalogInfo catInfo;
    Handle hExistingCustomIcon;
    IconFamilyHandle hIconFamily;
    Handle hIconFamilyCopy;
 
    hIconFamily = hIconFam;
 
    // Confirm that "path" exists and specifies a directory.
    exists = [fm fileExistsAtPath:path isDirectory:&isDir];
    if( !isDir || !exists )
        return NO;
 
    // Get an FSRef for the folder.
 
    CFURLRef urlRef;
    Boolean gotFSRef;
 
 
    // Create a CFURL with the specified POSIX path.
    urlRef = CFURLCreateWithFileSystemPath( kCFAllocatorDefault,
                                           (CFStringRef) path,
                                           kCFURLPOSIXPathStyle,
                                           FALSE /* isDirectory */ );
    if (urlRef == NULL)
    {
        NSLog(@"** Couldn't make a CFURLRef for the file." );
        return NO;
    }
 
    // Try to create an FSRef from the URL.  (If the specified file doesn't exist, this
    // function will return false, but if we've reached this code we've already insured
    // that the file exists.)
    gotFSRef = CFURLGetFSRef( urlRef, &targetFolderFSRef );
    CFRelease( urlRef );
 
    if (!gotFSRef)
    {
        NSLog(@"** Couldn't get an FSRef for the file." );
        return NO;
    }
 
 
 
    // Remove and re-create any existing "Icon\r" file in the directory, and get an FSRef for it.
    iconrPath = [path stringByAppendingPathComponent:@"Icon\r"];
    if( [fm fileExistsAtPath:iconrPath] )
    {
        if( ![fm removeFileAtPath:iconrPath handler:nil] )
            return NO;
    }
 
    if (![@"" writeToFile:iconrPath atomically:YES])
    {
        return NO;
    }
 
 
 
 
 
    // Create a CFURL with the specified POSIX path.
    urlRef = CFURLCreateWithFileSystemPath( kCFAllocatorDefault,
                                           (CFStringRef) iconrPath,
                                           kCFURLPOSIXPathStyle,
                                           FALSE /* isDirectory */ );
    if (urlRef == NULL)
    {
        NSLog(@"** Couldn't make a CFURLRef for the file." );
        return NO;
    }
 
    // Try to create an FSRef from the URL.  (If the specified file doesn't exist, this
    // function will return false, but if we've reached this code we've already insured
    // that the file exists.)
    gotFSRef = CFURLGetFSRef( urlRef, &iconrFSRef );
    CFRelease( urlRef );
 
    if (!gotFSRef)
    {
        NSLog(@"** Couldn't get an FSRef for the file.\n" );
        return NO;
    }
 
 
 
 
 
    // Get type and creator information for the Icon file.
    result = FSGetCatalogInfo(
                              &iconrFSRef,
                              kFSCatInfoFinderInfo,
                              &catInfo,
                              /*outName*/ NULL,
                              /*fsSpec*/ NULL,
                              /*parentRef*/ NULL );
    if( result == fnfErr ) {
        // The file doesn't exist. Prepare to create it.
 
        struct FileInfo *finderInfo = (struct FileInfo *)catInfo.finderInfo;
 
        // These are the file type and creator given to Icon files created by
        // the Finder.
        finderInfo->fileType = 'icon';
        finderInfo->fileCreator = 'MACS';
 
        // Icon files should be invisible.
        finderInfo->finderFlags = kIsInvisible;
 
        // Because the inited flag is not set in finderFlags above, the Finder
        // will ignore the location, unless it's in the 'magic rectangle' of
        // { -24,000, -24,000, -16,000, -16,000 } (technote TB42).
        // So we need to make sure to set this to zero anyway, so that the
        // Finder will position it automatically. If the user makes the Icon
        // file visible for any reason, we don't want it to be positioned in an
        // exotic corner of the window.
        finderInfo->location.h = finderInfo->location.v = 0;
 
        // Standard reserved-field practice.
        finderInfo->reservedField = 0;
 
        // Modified by Matteo Rattotti on: Wed Dec  5 14:56:52 2007
        // the catalog must be set
        FSSetCatalogInfo (&iconrFSRef, kFSCatInfoFinderInfo, &catInfo);
 
    } else {
		if( result != noErr ){
			return NO;
		}
		else{ // Modified by Matteo Rattotti on: Wed Dec  5 14:56:52 2007
			// File already exist, so we only need to set the flag we want (invisib, etc...)
			struct FileInfo *finderInfo = (struct FileInfo *)catInfo.finderInfo;
 
			// File type
			finderInfo->fileType = 'icon';
			finderInfo->fileCreator = 'MACS';
 
			// Icon files should be invisible.
			finderInfo->finderFlags = kIsInvisible;
			finderInfo->location.h = finderInfo->location.v = 0;
 
			// Standard reserved-field practice.
			finderInfo->reservedField = 0;
 
			FSSetCatalogInfo (&iconrFSRef, kFSCatInfoFinderInfo, &catInfo);
		}
	}
 
    // Get the filename, to be applied to the Icon file.
    filename.length = [@"Icon\r" length];
    [@"Icon\r" getCharacters:filename.unicode];
 
    // Make sure the file has a resource fork that we can open.  (Although
    // this sounds like it would clobber an existing resource fork, the Carbon
    // Resource Manager docs for this function say that's not the case.)
    FSCreateResFile(
                    &targetFolderFSRef,
                    filename.length,
                    filename.unicode,
                    kFSCatInfoFinderInfo,
                    &catInfo,
                    &iconrFSRef,
                    /*newSpec*/ NULL);
    result = ResError();
    if (!(result == noErr || result == dupFNErr))
        return NO;
 
    // Open the file's resource fork.
    file = FSOpenResFile( &iconrFSRef, fsRdWrPerm );
    if (file == -1)
        return NO;
 
    // Make a copy of the icon family data to pass to AddResource().
    // (AddResource() takes ownership of the handle we pass in; after the
    // CloseResFile() call its master pointer will be set to 0xffffffff.
    // We want to keep the icon family data, so we make a copy.)
    // HandToHand() returns the handle of the copy in hIconFamily.
    hIconFamilyCopy = (Handle) hIconFamily;
    result = HandToHand( &hIconFamilyCopy );
    if (result != noErr) {
        CloseResFile( file );
        return NO;
    }
 
    // Remove the file's existing kCustomIconResource of type kIconFamilyType
    // (if any).
    hExistingCustomIcon = GetResource( kIconFamilyType, kCustomIconResource );
    if( hExistingCustomIcon )
        RemoveResource( hExistingCustomIcon );
 
    // Now add our icon family as the file's new custom icon.
    AddResource( (Handle)hIconFamilyCopy, kIconFamilyType,
                kCustomIconResource, "\p");
 
    if (ResError() != noErr) {
        CloseResFile( file );
        return NO;
    }
 
    // Close the file's resource fork, flushing the resource map and new icon
    // data out to disk.
    CloseResFile( file );
    if (ResError() != noErr)
        return NO;
 
    result = FSGetCatalogInfo( &targetFolderFSRef,
                              kFSCatInfoFinderInfo,
                              &catInfo,
                              /*outName*/ NULL,
                              /*fsSpec*/ NULL,
                              /*parentRef*/ NULL);
    if( result != noErr )
        return NO;
 
    // Tell the Finder that the folder now has a custom icon.
    ((struct FolderInfo *)catInfo.finderInfo)->finderFlags = ( ((struct FolderInfo *)catInfo.finderInfo)->finderFlags | kHasCustomIcon ) & ~kHasBeenInited;
 
    result = FSSetCatalogInfo( &targetFolderFSRef,
                              kFSCatInfoFinderInfo,
                              &catInfo);
    if( result != noErr )
        return NO;
 
    // Notify the system that the target directory has changed, to give Finder
    // the chance to find out about its new custom icon.
    result = FNNotify( &targetFolderFSRef, kFNDirectoryModifiedMessage, kNilOptions );
    if (result != noErr)
        return NO;
 
    return YES;
}

Nearly 280 Lines of code later and here we are. I’m sure there is a group of people out there who don’t care about the internals of how this works and would like to just use the code. In fact I would wager that that’s probably the majority. Here’s all you need if that’s you. Just drop in the files NSString+CarbonFSRefCreation.m, NSString+CarbonFSRefCreation.h, IconFamily.m and IconFamily.h from the Shiny Frog project into your project and you can then change a folder icon with these few lines of code:

1
2

IconFamily *fam = [IconFamily iconFamilyWithContentsOfFile:[icnsFilepath stringValue]];
[fam setAsCustomIconForDirectory:[dirPath stringValue]];

That’s a lot easier to read and use obviously. I recommend the object oriented approach as it keeps things much cleaner. And as Shiny Frog has released this code under a standard MIT license which allows you to do pretty much whatever you like as long as you maintain the copyright information, you could take the two classes here and create your own framework that you can then just link in whenever you need it.

Conclusion

When I searched for code online to figure out how to achieve setting a custom icon for folders it looked pretty slim. Had I needed to track down all of the steps myself it would have, obviously, taken much longer to figure out, but thanks the Shiny Frog, I was able to find the code to do exactly what I wanted. I’m hopeful that this blog post will hit the search engines and make it easier for folks to find as this seems like a fairly important thing to know how to do. Until next time.

As memory serves the only time I’ve used version control in a meaningful way the system I was using was Visual SourceSafe from Microsoft. I know. Blech! It’s awful! I’ve pulled code from many a CVS or Subversion repository, but I’ve never really used them in the way they are intended to be used. Now, thanks to Marcus, I realize that version control isn’t just about versioning any more. It’s a whole methodology/ideology that makes better programmers. Here is what I mean.

Branching Inspires Wild Experimentation

Have you ever been so far down a path in your code that you just think, though you probably should, there is no way you would take a chance to re-factor due to looming deadlines or even just a simple fear that you might mess up so badly you couldn’t recover? Well, fear no more! Git provides such a simple way to create a branch of your code in which you can experiment, you won’t even give it a second thought. I won’t go into the whole setup and how to get going with Git as this is done very well elsewhere including a previous post from Marcus. I just want to point out how easy it is to branch with a single command. In Terminal.app, cd to the directory of a project you have under Git source control and enter the following command.

bash$ git branch experimental

bash$ git checkout experimental

bash$ git checkout master

bash$ git checkout master
bash$ git merge experimental

If you found, conversely, that your ideas were purely delusional–a characteristic of your over-achieving sense of hubris–you can blow them away by simply typing:

bash$ git branch -d experimental

Now the idea is just a bad memory and not something you ever need worry about (or mention to your programming peers) again. Your code on the master branch is still as it was when you first started the branch. Hallelujah!

Note: The word ‘experimental’ I’ve used in these command line examples is simply a tag. You can call your branch whatever you like. Call it ‘hubris’ if you like. Depending on your personality, this may be more appropriate.

The chance to experiment so easily and without fear will make you a better programmer. You will venture into areas that you would have never tried before and will likely become more bold in what you’re willing to attempt. This can only be a good thing in the long run.

Collaboration

The Tutorial introduction to git provides a good example of how to collaborate when multiple people are working on the same computer, but where Git’s real power comes in is in its ability to enable collaboration. If you’re familiar with extreme programming or pair programming then you are already aware of how collaboration will make you a better programmer. The learning curve for developing applications for the Macintosh for me has been significantly leveled as Marcus has shown me how to do things in the context of real code. You can learn things in many different ways, but sharing code has got to be one of the strongest means of gaining deeper understanding. This can only make you a better programmer.

While not a direct feature of Git itself, you can share your repository over the many file sharing web applications out there. Marcus and I use Dropbox for our projects that we collaborate on. Here are the steps you take to collaborate remotely using Git and Dropbox.

1. Sign up and install Dropbox from http://www.getdropbox.com.
   
   This will create a folder in your home directory under ~/Dropbox.
2. Have the person you want to collaborate with do the same and then create a shared folder that both of you can access through the Dropbox web interface.
   
   
3. From the project directory of the project you want to share, type:

   bash$ git clone --bare . ~/Dropbox/Shared/MySharedProject.git
   

   Note: Keep in mind that I’m assuming you already have this project under Git version control. If not you first need to run init like so in the root of your project directory.

   bash$ git init
   

   The –bare keyword we used in the clone command means that we simply want to create a directory that contains the contents of the .git directory in your project directory and not the actual workspace. The .git directory contains all of your code and changes to everything you need is there–it’s just not the actual workspace where xcode works from.
4. Create a remote (alias) for the newly cloned project by typing:

   bash$ git remote add sharedproject ~/Dropbox/Shared/MySharedProject.git
   



5. Now you can push any code changes from your working directory to the cloned directory, which, since it is in your Dropbox will automatically be uploaded to the drop box and downloaded by any other computers you have that can access Dropbox. First you need to commit any changes in your working directory with the following command.

   bash$ git commit -a -m "Commit message"
   

   Then you need to push the changes to the remote with the following.

   bash$ git push sharedproject master
   

   This pushes your changes to the cloned repository which is in your Dropbox directory. As soon as you do this, you should see the Dropbox icon in your menu bar change to the ‘synchronizing’ icon. If your change is small, it will only change for a split second so you’ll have to watch it closely to see that happen.

Once your files are committed and have been pushed to your cloned repository, you can now pull the project from another computer. I’m assuming you have Git and Dropbox set up on the second computer. Here are the steps you take to get the code into Git.

1. In Terminal.app on your other computer, create a new directory where you want your project to be stored with a working directory. Now run the following command.

   bash$ git clone ~/Dropbox/Shared/MySharedProject.git
   

   Notice that we didn’t use the –bare keyword this time. This is because we want our cloned copy to also setup a working directory since we’ll be accessing it from xcode on the second computer as well.
2. Now create a remote (alias) to reference the project like you did on the other computer using the following.

   bash$ git remote add sharedproject ~/Dropbox/Shared/MySharedProject.git
   

   Note: This step is optional as your clone will do this automatically. The difference, however, is that the clone will create a remote called ‘origin’ by default where you can name it whatever you want (sharedproject in the example) if you do run it.

3. Now you can pull the code at any time with the following command.

   bash$ git pull sharedproject master
   

   You won’t need to do that at this point as your code is fresh from the clone, however, should you make any changes on the originating computer that have been pushed, you could now pull those changes from this secondary computer.

If you now make changes to the code on the second computer, you can use the exact same command you used on the first computer to push the changes. First commit the changes with:

bash$ git commit -a -m "Commit message"

bash$ git push sharedproject master

And now you’re up to date. The changes are ready to be downloaded from the first computer.

The Urge To Merge

Nothing like sexual inuendo (urge to merge, hint hint, wink wink) on a site called ‘Cocoa is my Girlfriend’ to get a geek going, but that’s not what I mean. Settle down. Take it easy…

In the end, Git’s greatest feature is its ability to merge code changes.

There are times when you have fairly complex code merges that are necessary and systems such as CVS or SVN (Subversion) will simply choke and give up leaving the messy merging process to your weak manual merging skills. This is a shame and not necessary any more as it is rare for Git to be unable to successfully merge code. Again, this probably its biggest strength. When you don’t have to worry about merging your code, you can do whatever you like in your branch with little fear that merging in your changes are going to conflict with someone else’s. This merging power comes from Git’s unique philosophy of source code management which sees changes as individual code additions and deletions rather than complete file changes.

Conclusion

There will remain naysayers who have “always done it this way” and will remain in the realm of central repositories for version control. However, if you can think outside of tradition and see the power that comes from a good source control system, you will become a better programmer. I will submit that simply starting to use any version control when you haven’t before will make you a better programmer, however, using Git for your version control system, will make it infinitely easier to become so.

The Responder Chain

The handling of NSError objects follows the responder chain with regard to consuming and manipulating the NSError object. At any level in the responder chain the error can be displayed and/or handled and thereby consumed. If the current object in the responder chain does not handle it (which is common), then it is passed up until it finally reaches the NSApplication object. When it is received by the NSApplication object, that is when the default dialog is presented to the user.

However, that default dialog is not very friendly. There are no options, very little information, and generally nothing that can be done. Fortunately, there are ways to customize this presentation and give the user choices.

Handling an NSError

To help make this clearer, I am going to demonstrate how to handle an NSError before I demonstrate how to customize the NSError for handling. To get Cococa to give a user more information and to give the user choices, a few more keys need to be added into the NSError object. The proper place to add these additional keys is discussed below.

• NSLocalizedRecoverySuggestionErrorKey This key stores a localized string that will be displayed in the “info” portion of the alert window/sheet that is displayed to the user. This string is meant to display suggestive information to the user to make their choice easier. An example would be “Do you want to try again?”


• NSRecoveryAttempterErrorKey This key points to an object that is to receive the answer to the recovery question. For example, if you have a dialog that has the options “Abort” and “Try Again”, this object would receive the answer to that question. The exact method is discussed below.


• NSLocalizedRecoveryOptionsErrorKey This key points to an array of strings that are the localized button titles which are displayed to the user. To follow the examples above, this key would store an array with two strings: “Try Again” and “Abort”.

The recovery attempt object is very similar to a delegate of the NSError responder chain. When the dialog is presented the recovery attempt object will receive a call once the user makes a choice. Depending on the type of alert (modal vs. sheet), two different methods can be called:

1
2
3
4
5
6
7
8

- (BOOL)attemptRecoveryFromError:(NSError*)error 
                     optionIndex:(NSUInteger)recoveryOptionIndex;
 
- (void)attemptRecoveryFromError:(NSError*)error 
                     optionIndex:(NSUInteger)recoveryOptionIndex 
                        delegate:(id)delegate 
              didRecoverSelector:(SEL)didRecoverSelector 
                     contextInfo:(void*)contextInfo;

The first method returns a BOOL to let the caller know whether or not the error was successfully handled. The second method expects the delegate object to be called. The delegate method should be similar to:

1
2

- (void)didPresentErrorWithRecovery:(BOOL)didRecover 
                        contextInfo:(void*)contextInfo;

With the BOOL parameter describing whether or not recovery was successful and the contextInfo being the same object passed in.

Customing the NSError

When the developer is the one who creates the error message, it is pretty easy to prepare it for handling right at creation. However, when the creation point of the NSError is either not the appropriate place to set it up for handling or is in someone else’s code, there are other chances to update the error with handling information.

If you want to capture an NSError and inject the handler information discussed above, then you need to implement a method that will be called as part of the responder chain. If you want to intercept the error at some point before the NSApplication’s delegate, then the following method needs to be implemented:

1

- (NSError*)willPresentError:(NSError*)error;

However, if you want to manipulate the error at the Application delegate the following method is appropriate:

1
2

- (NSError*)application:(NSApplication*)app 
       willPresentError:(NSError*)error;

In this method, you can either return the NSError object that is being passed in, or you can create a new NSError object and return it. In either case, the error chain will use whatever object is returned from this method.

Conclusion

With these methods, it is possible to drastically improve the handling and presentation of errors. With these methods, errors can be reduced to simple decisions for the user to resolve rather than application crashing events.

I have attached the project from the previous NSError article. In addition, that project has been updated to utilize the methods described in this entry.

NSError Tutorial

When a call is made on an object through Key Value Coding such as [self valueForKey:@"someKey"], numerous attempts are made to resolve the call. First, the method someKey is looked for. If that is not found then the iVar someKey is looked for. If neither of those are found, then one last attempt is made before presenting an error. That last attempt is a call to the method -(id)valueForUndefinedKey:. If that method is not implemented then an NSUndefinedKeyException is raised.

valueForUndefinedKey: is designed so that when you request a value from an object using -(id)valueForKey: the object has a last chance to respond to that request before an error occurs. This has many benefits and I have included two examples of those benefits in this post–Core Data Parameters and Data Formatting.

Core Data Parameters

One of the ways in which I use this method is by making a singleton object that responds to parameter requests. This allows any part of the application to ask the singleton for parameters and get them back in a clean block of code rather than having to build an NSFetchRequest each time a parameter is needed. This allows others parts of the application to make simple calls like:

NSString *companyName = [[Company shared] valueForKey:kCompanyName];

and avoid messy calls like this:

1
2
3
4
5
6
7
8
9
10

NSString *companyName = nil;
 
NSFetchRequest *request = [[[NSFetchRequest alloc] init] autorelease];
 
[request setEntity:[NSEntityDescription entityForName:@"Parameter" inManagedObjectContext:managedObjectContext]]];
[request setPredicate:[NSPredicate predicateWithFormat:@"name == %@", kCompanyName]];
 
NSError *error = nil;
companyName = [[managedObjectContext executeFetchRequest:request error:&error] lastObject];
NSAssert(error == nil, ([NSString stringWithFormat:@"Error requesting parameter: %@\n%@", kCompanyName, error]));

Worse is when I want to set a parameter value:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

id parameter;
 
NSFetchRequest *request = [[[NSFetchRequest alloc] init] autorelease];
[request setEntity:[NSEntityDescription entityForName:@"Parameter" inManagedObjectContext:managedObjectContext]];
[request setPredicate:[NSPredicate predicateWithFormat:@"name == %@", key]];
 
parameter = [[managedObjectContext executeFetchRequest:request error:&error] lastObject];
NSAssert(error == nil, ([NSString stringWithFormat:@"Error getting parameter %@:%@", key, error]));
if (!parameter) {
    parameter = [NSEntityDescription insertNewObjectForEntityForName:@"Parameter" inManagedObjectContext:managedObjectContext];
    [parameter setValue:key forKey:@"name"];
}
 
if ([value isKindOfClass:[NSNumber class]]) {
    [parameter setValue:[value stringValue] forKey:@"value"];
} else if ([value isKindOfClass:[NSDate class]]) {
    [parameter setValue:[value description] forKey:@"value"];
} else {
    [parameter setValue:value forKey:@"value"];
}

As you can see, after the 5th or 6th time of plugging that block of code in just to get a parameter out of the Core Data store — it gets old. Therefore, I turned to KVC/KVO.

Not: These parameters are different from using NSUserDefaults. NSUserDefaults are great for application level parameters. However, if you need to store document level parameters then NSUserDefaults is the wrong place.

Instead of writing tons of code to access the Core Data Stack, parameter access can be centralized in a singleton. That singleton can then be exposed to the entire application and any portion of the application can then request or set parameters. The parameters are then read and set via the valueForUndefinedKey: and setValue:forUndefinedKey: methods as shown:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

- (id)valueForUndefinedKey:(NSString *)key;
{
    NSFetchRequest *request = [[[NSFetchRequest alloc] init] autorelease];
    [request setEntity:[NSEntityDescription entityForName:@"Parameter" inManagedObjectContext:managedObjectContext]]];
    [request setPredicate:[NSPredicate predicateWithFormat:@"name == %@", key]];
 
    NSError *error = nil;
 
    NSManagedObject *parameter = [[managedObjectContext executeFetchRequest:request error:&error] lastObject];
    NSAssert(error == nil, ([NSString stringWithFormat:@"Error requesting parameter: %@\n%@", key, error]));
    return [parameter valueForKey:@"value"];
}
 
- (void)setValue:(id)value forUndefinedKey:(NSString *)key 
{
    [self willChangeValueForKey:key];
 
    NSFetchRequest *request = [[[NSFetchRequest alloc] init] autorelease];
 
    [request setEntity:[NSEntityDescription entityForName:@"Parameter" inManagedObjectContext:managedObjectContext]];
    [request setPredicate:[NSPredicate predicateWithFormat:@"name == %@", key]];
    NSError *error = nil;
 
    NSManagedObject *parameter = [[managedObjectContext executeFetchRequest:request error:&error] lastObject];
    NSAssert(error == nil, ([NSString stringWithFormat:@"Error getting parameter %@:%@", key, error])];
    if (!parameter) {
        parameter = [NSEntityDescription insertNewObjectForEntityForName:@"Parameter" inManagedObjectContext:managedObjectContext];
        [parameter setValue:key forKey:@"name"];
    }
    if ([value isKindOfClass:[NSNumber class]]) {
        [parameter setValue:[value stringValue] forKey:@"value"];
    } else if ([value isKindOfClass:[NSDate class]]) {
        [parameter setValue:[value description] forKey:@"value"];
    } else {
        [parameter setValue:value forKey:@"value"];
    }
    [self didChangeValueForKey:key];
}

As you can see this code is pretty much identical to the blocks listed above. However, now it is only in one place in the code and not littered around the entire application. In addition, if I ever decide to move the location where parameters are stored, I only have to alter that code once. By using the valueForUndefinedKey: method, I can avoid having to alter the code every time I want to store another parameter. Lastly, since the parameter key is considered a value on the singleton object, I can observe it and receive notifications when it changes. This allows me to hook IB bindings directly to the singleton.

Date Formatting

While I do not have an axe to grind against dates in Cocoa, in my opinion the formatters could use some work. Localizing dates directly in Interface Builder (along with currency formatters) is a hit or miss situation. For the display of dates, I simply gave up. I can get the localizers to work just fine in code and I can manually set the formatters for display but there is an easier way to do it.

As part of my modified Core Data Stack, I have a parent class that subclasses NSManagedObject. All of my objects then extend this subclass. This (super/sub)class allows me to load in some interesting things such as overriding the valueForUndefinedKey: method. In this case, however, I am doing some trickery on the key itself.

As an example, most of my data objects have a value called ‘createDate’ that is set in the awakeFromInsert method. This attribute is stored in Core Data as an NSDate. To get around the issues with the date formatters in InterfaceBuilder, I overrode the valueForUndefinedKey: method in the ZDSManagedObject as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

static NSString* const kZDSLocalDateStringSuffix = @"LocalString";
static NSString* const kZDSLocalDateTimeStringSuffix = @"LocalDTString";
 
- (id)valueForUndefinedKey:(NSString *)key
{
    if ([key hasSuffix:kZDSLocalDateStringSuffix]) {
        id value = [self valueForKey:[key substringToIndex:[key rangeOfString:kZDSLocalDateStringSuffix].location]];
        if (!value) return [super valueForUndefinedKey:key];
        if ([value isKindOfClass:[NSDate class]]) {
            return [[AppDelegate shortDateFormatter] stringFromDate:value];
        }
        return [super valueForUndefinedKey:key];
    }
    if ([key hasSuffix:kZDSLocalDateTimeStringSuffix]) {
        id value = [self valueForKey:[key substringToIndex:[key rangeOfString:kZDSLocalDateTimeStringSuffix].location]];
        if (!value) [super valueForUndefinedKey:key];
        if ([value isKindOfClass:[NSDate class]]) {
            return [[AppDelegate shortDateTimeFormatter] stringFromDate:value];
        }
        return [super valueForUndefinedKey:key];
    }
    return [super valueForUndefinedKey:key];
}

With this code in place, I can set the createDate binding in Interface Builder to createDateLocalString and the field will be populated with the create date formatted properly for the locale. I can also set the binding to createDateLocalDTString and receive the date and time formatted properly for the locale.

Conclusion

There is a lot more than can be done with Key Value Coding and Observing and the undefinedKey methods. These two examples are just a start of what can be done to easily and cleanly roll up code that is reused frequently.