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.

In this article we will discuss the latest iteration of my Prefix.pch file. As with anything I post, it is available for you to use as you see fit.

The File

For those who don’t want to read the entire post, here is the file:

1
2
3
4
5
6
7
8
9
10
11
12

#ifdef DEBUG
  #define DLog(...) NSLog(@"%s %@", __PRETTY_FUNCTION__, [NSString stringWithFormat:__VA_ARGS__])
  #define ALog(...) [[NSAssertionHandler currentHandler] handleFailureInFunction:[NSString stringWithCString:__PRETTY_FUNCTION__ encoding:NSUTF8StringEncoding] file:[NSString stringWithCString:__FILE__ encoding:NSUTF8StringEncoding] lineNumber:__LINE__ description:__VA_ARGS__]
#else
  #define DLog(...) do { } while (0)
  #ifndef NS_BLOCK_ASSERTIONS
    #define NS_BLOCK_ASSERTIONS
  #endif
  #define ALog(...) NSLog(@"%s %@", __PRETTY_FUNCTION__, [NSString stringWithFormat:__VA_ARGS__])
#endif
 
#define ZAssert(condition, ...) do { if (!(condition)) { ALog(__VA_ARGS__); }} while(0)

This does not replace the Prefix.pch that comes with your project but it does go at the top of every project that I work on. The rest of this post we will review what this does.

#ifdef DEBUG

I normally run my code in one of two modes. Either I am writing and testing the code or I am compiling it to hand over to QA, a user or Apple (btw I consider all three of those to be synonymous when it comes to builds). Therefore the first line is a switch to see if we are in debug mode. I set this value in the build settings of my project. If you look under the “Preprocessor Macros” section you can set the DEBUG definition there.

#define DLog(...)

This is the most used macro I have in my Prefix.pch file. This is simply NSLog as we know it and love it. However I automatically prepend the included macro __PRETTY_FUNCTION__ so that any log statement that comes out will declare where it is being called from. Personally I hate having to track down which “Fix Me” just spit out to the Console.

The nice thing about DLog over NSLog is that in the other branch this is a no-op that will be removed by the compiler. Therefore when I do a client build they won’t see the debug statements nor will their build be slowed down by any potential conditional logic around the debug statements.

#define ALog(...)

While I do not use this one very often I do like this one an awful lot. When I am in DEBUG mode it will throw an NSAssertion when it gets hit. This is similar to a common line of code that I see:

1

NSAssert(NO, @"It failed");

or if you want to see the variables:

1

NSAssert2(NO, @"It failed. Value1: %i Value2: %i", value1, value2);

My version does not have the condition before hand and can take any number of parameters.

1

ALog(@"It failed. Value1: %i Value2: %i", value1, value2);

In addition, when the DEBUG flag is not set, this assertion turns into a NSLog which remains visible. This allows me to have “This will never happen” calls in my code that will explode when I hit them but will be more polite if a user hits them but not so polite that I am left wondering what happened. They won’t intentionally crash the application but they will leave a fingerprint in the output from the application so that I can discover what happened.

NS_BLOCK_ASSERTIONS

I am of the school of thought that believes you should never throw an assertion in production code. If your code cannot handle that part of your app being hit and survive in some form or another then it is not production ready. Simple as that. Therefore I turn them off in production builds.

However, some other people who write libraries that I depend upon also feel this way. Therefore I need to check to see if it is already defined so that I can avoid a warning about resetting it. Since I have warnings set as errors in my code this is needed.

#define ZAssert(condition, ...)

The final gem in this collection is ZAssert. This is my personal favorite and it lets me clean up my code very nicely. First, ZAssert is a condition check. If you pass the check nothing happens. If you fail the check, bad things happen. This is just like NSAssert except for one big difference. When you turn off assertions, NSAssert goes away completely. This is not what I want to happen in my code. Instead, when assertions are turned off, I want a failure of this check to turn into an NSLog. That is what ZAssert does for us. In this way, we can clean up our code very nicely. Picture this very common block of code:

1
2
3
4
5
6

NSError *error = nil;
 
if (![managedObjectContext save:&error]) {
  NSLog(@"My save failed: %@\n%@", [error localizedDescription], [error userInfo]);
  abort();
}

That is a LOT of code just to perform a save! Blocks of code like this are very common in Objective-C. Unfortunately we can’t roll this up into a NSAssert because the entire line of code will disappear when we turn them off.

With ZAssert it gets a lot cleaner:

1
2

NSError *error = nil;
ZAssert(![managedObjectContext save:&error], @"My save failed: %@\n%@", [error localizedDescription], [error userInfo]);

Because ZAssert survives when NS_BLOCK_ASSERTIONS is set and simply mutates, we can inline the save directly and make the code a lot easier to read.

Wrap Up

I am sure this code will evolve. When it has changed significantly I will do an updated post. If anyone else has some nice tips for the Prefix.pch then please share them as we all benefit.

Acknowledgements

First I would like to recognize Fraser Hess who did the original post and showed me what we can do with macros.

Second I would like to point out that the NSAssert line of code above is borrowed heavily from BareBones software. They figured out how to generate an assertion without actually using the NSAssert macros.

A situation that I believe we are going to be seeing more and more often is one where application developers are writing multiple “versions” of their applications to be used on the desktop, their iPhone and now the iPad.

Because of that situation, it is becoming even more important that we write as much portable code as possible. Fortunately, our model can be completely portable between the two platforms.

NSImage vs UIImage

The primary issue with creating a portable model and model objects is images. Now, if the images are stored on disk and only referenced in your Core Data model, then you don’t have an issue. Since you are storing the images on disk in a portable format (png, jpeg, etc.) then they will port right over to all of the platforms you are targeting.

But what happens when you are working with small images that should be stored within Core Data? Simple right, just use a transformable data type and stick the image right in there.

Unfortunately that fails in the portability department.

The issue is that on the desktop you are storing a serialized version of the NSImage instance and on the other devices you are storing an instance of UIImage. Two different data structures that are incompatible. So what is the right answer?

Store the images in a portable format even in Core Data.

But that is hard right?

Fortunately if we create concrete subclasses of any entity that needs to store images it is a small amount of code and some conditional compiling.

MyEntityWithAnImage.h

1
2
3
4
5
6
7
8
9
10
11
12

 
@interface MyEntityWithAnImage : NSManagedObject
{
}
 
#ifdef IPHONEOS_DEPLOYMENT_TARGET
@property (nonatomic, retain) UIImage *image;
#else
@property (nonatomic, retain) NSImage *image;
#endif
 
@end

In the header we declare the same property and the use some conditional compiling to determine which definition should be used. On the desktop the property image will return an NSImage and on the other platforms it will return a UIImage. But how do we work this magic?

MyEntityWithAnImage.m

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

#ifdef IPHONEOS_DEPLOYMENT_TARGET
 
- (void)setImage:(UIImage*)image
{
  [self willChangeValueForKey:@"image"];
 
  NSData *data = UIImagePNGRepresentation(image);
  [myManagedObject setImage:data];
  [self setPrimitiveValue:data forKey:@"image"];
  [self didChangeValueForKey:@"image"];
}
 
- (UIImage*)image
{
  [self willAccessValueForKey:@"image"];
  UIImage *image = [UIImage imageWithData:[self primitiveValueForKey:@"image"];
  [self didAccessValueForKey:@"image"];
  return image;
}
 
#else
 
- (void)setImage:(NSImage*)image
{
  [self willChangeValueForKey:@"image"];
  NSBitmapImageRep *bits = [[image representations] objectAtIndex: 0];
 
  NSData *data = [bits representationUsingType:NSPNGFileType properties:nil];
  [myManagedObject setImage:data];
  [self setPrimitiveValue:data forKey:@"image"];
  [self didChangeValueForKey:@"image"];
}
 
- (NSImage*)image
{
  [self willAccessValueForKey:@"image"];
  NSImage *image = [[NSImage alloc] initWithData:[self primitiveValueForKey:@"image"]];
  [self didAccessValueForKey:@"image"];
  return [image autorelease];
}
 
#endif
 
@end

Here we are overriding the dynamic accessors and implementing our own. We are fully KVO compliant and notify when we are accessing or changing the image value.

In the desktop version we grab the bitmap image representation and then get the PNG representation of it and store that representation into Core Data as NSData.

In the Cocoa Touch version we are using the C function which returns the PNG representation of the UIImage instance directly. We are again storing that as NSData into our image property.

In both cases the getter reverses the process by loading the NSData back into the appropriate image instance.

Wrap Up

This makes the code external to our NSManagedObject completely unaware of the actual data storage and they just know that they are getting back the object they need to work with.

BTW, if anyone knows of another pre-processor variable that I should be using for this instead of IPHONEOS_DEPLOYMENT_TARGET please let me know. I am not 100% confident that IPHONEOS_DEPLOYMENT_TARGET is the best variable to be testing against.

Do you like this idea, hate it? Tell me in person at NSConferenceUSA! Tickets are still available and it will be great to see you there.

If that is too soon then please catch me at 360 iDev in April!

Specifically this article walks through using the NSFetchedResultsController and some best practices in its use. The magazine is available for free on their website, The Pragmatic Bookshelf.

The issue, however, is that the dSYM file must match the binary exactly^[1]. I have not even had luck with pulling the code out of version control and compiling a second time to get the files to match up. Therefore, we need to store these dSYM files for every build that gets handed off to someone else. For Cocoa Touch development this means every ad hoc build and every release build. This can be a pain.

To solve this problem I wrote a script that is added as the last build phase of all my iPhone projects. The script will move the dSYM bundle into the project directory in a directory cleverly called “dSYM”. In addition the script will check the bundle into git (after confirming the project is maintained in a git repository) and commit just that bundle. Also, since the file is always named the same thing, it renames the file using the current date and time so that no two bundles have the same file name.

Failure checks

The first thing the script does is determine if it should run.

if [ "$BUILD_STYLE" == "Debug" ]; then
  echo "Skipping debug"
  exit 0;
fi

The first part of the script checks to see if the build style is Debug. Since all debug builds run just on the developer’s device and still contain the debug symbols, they can be safely ignored.

if [ "$EFFECTIVE_PLATFORM_NAME" == "-iphonesimulator" ]; then
  echo "Skipping simulator build"
  exit 0;
fi

The second step is to check to see if the build is against the simulator. Again, we have no interest in storing the symbol files for these builds.

Move the file

Since the location of the file is determined at build time and can vary from developer to developer (as well as machine to machine) I use the environmental variables that are part of the build.

SRC_PATH=${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}
RELATIVE_DEST_PATH=dSYM/${EXECUTABLE_NAME}.$(date +%Y%m%d%H%M%S).app.dSYM
DEST_PATH=${PROJECT_DIR}/${RELATIVE_DEST_PATH}
echo "moving ${SRC_PATH} to ${DEST_PATH}"


mv "${SRC_PATH}" "${DEST_PATH}"

The next step is to build up the paths of where the file is currently and where we are going to move it to. I like to store these in variables so that I can print them out to the console in case something goes wrong.

Commit it to version control

Every project is part of version control right? (RIGHT?)

if [ -f ".git/config" ]; then
  git add "${RELATIVE_DEST_PATH}"
  git commit -m "Added dSYM file for ${BUILD_STYLE} build" \
      "${RELATIVE_DEST_PATH}"
fi

The final part only occurs if the project is part of a git repository. If it is then the bundle is added to git and then just that bundle is committed with a simple message.

Conclusion

Although I have recently been having issues getting symbolicatecrash to work properly, eventually either I or someone else will get it working again and at that time these files will be invaluable in tracking down crashes.

The final script is attached. I normally add the file to the project and then have a script phase that just calls this script file.

Move_dSYM_To_Storage.sh.zip

There’s an Apple approved and supported method for limiting architectures to Mac OS X versions. Here’s how to limit 32/64-bit Intel apps to only run 64-bit Intel on 10.6.0 and later.

Open your application’s Info.plist in a text editor and add the following before the final </dict>

1
2
3
4
5

<key>LSMinimumSystemVersionByArchitecture</key>
<dict>
    <key>x86_64</key>
    <string>10.6.0</string>
</dict>

That’s it!

Docs for LSMinimumSystemVersionByArchitecture

One of the Core Animation layers available as of Snow Leopard and iPhone OS 3.0, CAShapeLayer provides some interesting attributes that are animatable. The CAShapeLayer enables you to create a layer that renders any arbitrary shape you specify using a path, a CGPathRef. It also enables you to specify a stroke pattern for the stroke that outlines the shape. A stroke is optional, but if you do specify one you may also determine the pattern for it. I do point this part out in the book in Chapter 10, by the way. You use the method, -setLineDashPattern which takes an NSArray of integers. These integers specify painted segments verses unpainted segments. What this means is that if you specify 10, 5 in your array, for example, you will see 10 units of painted segment and 5 units unpainted. Notice I use the term units as opposed to pixels. This is due to the fact that we are to start getting used to the idea of resolution independence. Pixels don’t matter in the same way any more.

The pattern example I used is very simple. You could easily specify something much more complex, say 10, 72, 55, 2, 146, etc. for example. This would mean 10 painted units, followed by 72 unpainted units, followed by 55 painted units, followed by 2 unpainted units, followed by 146 painted units–on and on. You get the picture.

Now for the part I didn’t mention in the book. You can animate this stroke pattern. If you’ve ever used any drawing program you realize that when a rectangular area of the image is in a seleted mode, a dashed pattern stroke outlines that area and the pattern will move like marching ants. To achieve this effect manually actually takes quite a bit of effort, but is quite trivial when done with Core Animation.

What makes it so is another little property of the CAShaperLayer called lineDashPhase. This property specifies the phase of the stroke pattern. The default is zero. Animate this property to see the marching ants effect. If you want the animation to loop perfectly, set the toValue in the animation to the sum of all of the values specified in the lineDashPattern array. The code to animate the lineDashPhase should look something like the following:

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

- (IBAction)toggleMarching:(id)sender;
{
    if ([shapeLayer animationForKey:@"linePhase"])
        [shapeLayer removeAnimationForKey:@"linePhase"];
    else {
        CABasicAnimation *dashAnimation;
        dashAnimation = [CABasicAnimation 
                         animationWithKeyPath:@"lineDashPhase"];
 
        [dashAnimation setFromValue:[NSNumber numberWithFloat:0.0f]];
        [dashAnimation setToValue:[NSNumber numberWithFloat:15.0f]];
        [dashAnimation setDuration:0.75f];
        [dashAnimation setRepeatCount:10000];
 
        [shapeLayer addAnimation:dashAnimation forKey:@"linePhase"];
 
    }
}

This is the code we would use to animate a stroke pattern of 10, 5. Notice the sum of those two is 15, which is what the call to setToValue takes in the sample code for the animation. This is important. If the phase doesn’t match the stroke pattern, the animation will jerk back to the starting position. We want the animation to be smooth and seamless.

We set up our CAShaperLayer using the following 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

- (void)viewDidLoad {
    [super viewDidLoad];
 
    // Create the shape layer
    shapeLayer = [CAShapeLayer layer];
    CGRect shapeRect = CGRectMake(0.0f, 0.0f, 200.0f, 100.0f);
    [shapeLayer setBounds:shapeRect];
    [shapeLayer setPosition:CGPointMake(160.0f, 140.0f)];
    [shapeLayer setFillColor:[[UIColor clearColor] CGColor]];
    [shapeLayer setStrokeColor:[[UIColor blackColor] CGColor]];
    [shapeLayer setLineWidth:1.0f];
    [shapeLayer setLineJoin:kCALineJoinRound];
    [shapeLayer setLineDashPattern:
     [NSArray arrayWithObjects:[NSNumber numberWithInt:10], 
      [NSNumber numberWithInt:5], 
      nil]];
 
 
    // Setup the path
    CGMutablePathRef path = CGPathCreateMutable();
    CGPathAddRect(path, NULL, shapeRect);
    [shapeLayer setPath:path];
    CGPathRelease(path);
 
    // Set the layer's contents
    [shapeLayer setContents:(id)[[UIImage imageNamed:@"balloon.jpg"] CGImage]];
 
    [[[self view] layer] addSublayer:shapeLayer];
 
}

Set the fill color to clear color so we can see through the shape. Set the line width to 1.0. Set the line join to be rounded. Then create the lineDashPattern. Next we create a path that matches the rectangle of our layer as to outline it correctly.

Finally we set the contents of the shape layer to a CGImageRef of the image we load from the bundle called balloon.jpg.

Once we connect the button in Interface Builder to the action called -toggleMarching, we can start and stop the marching ants animation.

Conclusion

The marching ants effect has limited use, but this example code demonstrates once again how Core Animation really simplifies a lot of visual tasks that would have at one time taken a lot more code to achieve. If there is anything I’ve learned while researching and writing the book it’s that Core Animation should be the go-to technology for a vast majority of visualizations on OS X and the iPhone. I find many questions related to the visual aspects of programming for both platforms on Stack Overflow have a very elegant answer in Core Animation. Other solutions exist, but they are often much more cumbersome. Until next time.

Marching Ants Demo Project

1

UpdateSystemActivity(OverallAct);

The docs explain that you fire this every 30 seconds. On the surface, this looks like a hack and well, I don’t need a Carbon C call for that, I can fake a mouse event every 30 seconds.

This is out for good anyway, given that it doesn’t compile on Snow Leopard on x86_64. Carbon 64-bit will never arrive.

Turns out that the modern way to disable sleep uses IOKit. Apple has a doc for that too. Here is Listing 2:

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

#import <IOKit/pwr_mgt/IOPMLib.h>
 
...
// kIOPMAssertionTypeNoDisplaySleep prevents display sleep,
// kIOPMAssertionTypeNoIdleSleep prevents idle sleep
 
IOPMAssertionID assertionID;
IOReturn success = IOPMAssertionCreate(kIOPMAssertionTypeNoDisplaySleep, 
                                    kIOPMAssertionLevelOn, &assertionID); 
if (success == kIOReturnSuccess)
{
 
    //Add the work you need to do without 
    //  the system sleeping here.
 
    success = IOPMAssertionRelease(assertionID);
    //The system will be able to sleep again. 
}

With any sample code that I’m gonna try to use in my apps, I take the time to understand what’s going on, and to read the docs for that with which I’m not familiar. (Don’t you? That’s fine, just throw someone else’s potential garbage in your app. I’m sure it won’t bite until you least expect it.)

I’m getting back an IOPMAssertionID, so I proceed to look that up in the XCode documentation viewer. And there’s nothing to be found. A look in IOPMLib.h tells me it’s a 32-bit unsigned integer and therefore not very interesting.

So, I move on to look up IOPMAssertionCreate() to find that it was introduced in Leopard only to be deprecated in Snow Leopard in favor of IOPMAssertionCreateWithName(). IOPMAssertionCreateWithName() has an extra parameter over IOPMAssertionCreate(), and it’s a name as you might imagine. I don’t care for having deprecated calls in my code so IOPMAssertionCreateWithName() it is. Caveat: IOPMAssertionCreateWithName() is not publicly available in Leopard, so either use IOPMAssertionCreate() in Xcode3.1/Leopard or compile in XCode 3.2/Snow Leopard and IOPMAssertionCreateWithName() will work when run on Leopard.

The sample code from Apple lists two assertion types that you can use: kIOPMAssertionTypeNoDisplaySleep that prevents display sleep, and kIOPMAssertionTypeNoIdleSleep that prevents idle sleep.

My testing indicates that kIOPMAssertionTypeNoDisplaySleep actually prevents both display and idle sleep. The intended use case for this is clearly along the lines of playing a movie or running a presentation.

kIOPMAssertionTypeNoIdleSleep will still allow the display to sleep, but the Mac never sleeps unless it runs out of battery power. Use cases for this fall into the category of ‘computations that may not finish before the computer sleeps’, such as bouncing an mixed audio/video file to disk or rendering a 3D image, etc.

Here is an example project that allows you to test both behaviors. Note: The project uses IOPMAssertionCreate() and not IOPMAssertionCreateWithName() in order to compile on both Leopard and Snow Leopard.

In keeping with good practice, I have filed bug reports with Apple for pieces of the documentation that I see as missing.

First add the following to the <AppName>_Prefix.pch file in your Xcode project:

1
2
3
4
5
6

#ifdef DEBUG
#    define DLog(...) NSLog(__VA_ARGS__)
#else
#    define DLog(...) /* */
#endif
#define ALog(...) NSLog(__VA_ARGS__)

Right-click on your target and click Get Info. Select the Build tab. Make sure Configuration is set to Debug. Add -DDEBUG to the Other C Flags of your target.

And that’s about it. When you want to log only in debug builds use DLog(). In release builds DLog() will be compiled as an empty comment. Otherwise use ALog() for logging in both debug and release builds. (A as in always.)

I like this approach for a few reasons:

1. Some approaches comment out all NSLog() statements when compiled. This approach lets me keep some logging if I want.
2. Using ALog() and DLog(), I make a conscious choice about which builds I’m going to log in.
3. There is very little setup.
4. There is no overhead. Because DLog() is defined as NSLog(), executing DLog() is no different than executing NSLog()

If you’d like to replace NSLog with DLog in your source files, here’s a quick sed command that you can run in Terminal: $ sed -i ".bak" 's/NSLog/DLog/' *.m FYI, this will make a backup of each of the .m files whether it changed them or not.

Logging Sample Application

Add the following to iTunesFilter_AppDelegate.h:

IBOutlet NSSearchField *searchField;
IBOutlet NSArrayController *songArrayController;

and

- (IBAction)filterSongs:(id)sender;

With those changes I can go into Interface Builder and wire up the NSSearchField to searchField and my NSArrayController to songArrayController. I also make the action of the NSSearchField, filterSongs:.

I have one more change and that is to make the Action of the NSSearchField “Sent on End Editing”

All we need now is to add the code for -filterSongs to iTunesFilter_AppDelegate.m:

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

- (IBAction)filterSongs:(id)sender {
NSMutableString *searchText = [NSMutableString stringWithString:[searchField stringValue]];
 
// Remove extraenous whitespace
while ([searchText rangeOfString:@"Â  "].location != NSNotFound) {
    [searchText replaceOccurrencesOfString:@"Â  " withString:@" " options:0 range:NSMakeRange(0, [searchText length])];
}
 
//Remove leading space
if ([searchText length] != 0) [searchText replaceOccurrencesOfString:@" " withString:@"" options:0 range:NSMakeRange(0,1)];
 
//Remove trailing space
if ([searchText length] != 0) [searchText replaceOccurrencesOfString:@" " withString:@"" options:0 range:NSMakeRange([searchText length]-1, 1)];
 
if ([searchText length] == 0) {
    [songArrayController setFilterPredicate:nil];
    return;
}
 
NSArray *searchTerms = [searchText componentsSeparatedByString:@" "];
 
if ([searchTerms count] == 1) {
    NSPredicate *p = [NSPredicate predicateWithFormat:@"(name contains[cd] %@) OR (album contains[cd] %@) OR (artist contains[cd] %@)", searchText, searchText, searchText];
    [songArrayController setFilterPredicate:p];
} else {
    NSMutableArray *subPredicates = [[NSMutableArray alloc] init];
    for (NSString *term in searchTerms) {
        NSPredicate *p = [NSPredicate predicateWithFormat:@"(name contains[cd] %@) OR (album contains[cd] %@) OR (artist contains[cd] %@)", term, term, term];
        [subPredicates addObject:p];
    }
    NSPredicate *cp = [NSCompoundPredicate andPredicateWithSubpredicates:subPredicates];
 
    [songArrayController setFilterPredicate:cp];
}
}

Here’s how it works: After we remove extra whitespace in the string, we breakdown the string into each word (-componentsSeparatedByString:). Then we build an NSPredicate for each word in the string, before the real magic happens by combining these together using NSCompoundPredicate andPredicateWithSubpredicates:

In the end I get a predicate that looks like this: ((name contains[cd] yesterday) or (artist contains[cd] yesterday) or (album contains[cd] yesterday)) and ((name contains[cd] beatles) or (artist contains[cd] beatles) or (album contains[cd] beatles))

iTunesFilter Sample Application

1. Press Command-Shift-N and select Tab Bar Application in the iPhone OS | Application templates. Click Choose…
2. Provide a name for the project. I chose “Tab Test”
3. Click Save

The first thing you’ll notice is that the template has generated two classes for us. One called FirstViewController, which is used to control the first view (ya think?). The other is called Tab_TestAppDelegate which is our application delegate–the entry point and main controller class for our application.

Take a look at the stub code generated in the FirstViewController. It is commented out for the most part, but you’ll notice that there is a method in there that gives us what we want for allowing different orientations for our application. In particular, we are interested in -shouldAutorotateToInterfaceOrientation. Uncomment that code and have it simply return YES. This setting will enable the controller to support all orientations.

1
2
3
4
5

// Override to allow orientations other than the default portrait orientation.
- (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation {
    // Return YES for supported orientations
    return YES;
}

This should cause our view to change orientation when the device is turned. Build and run the application using the simulator. Once the simulator has loaded the application, select Hardware | Rotate Left. You will notice that while the device did rotate, the view did not. Why is this?

All Or None

Remember that the default tab bar application template creates a tab bar component with two views. While we have explicitly told the FirstViewController object to allow all orientations, we have not done so with our second view. The way the tab bar controller works is that if any of the view controllers have a limitation on the orientation of the view, then all views are constrained by the same limitation.

What this means is that all view controllers must override the call to -shouldAutorotateToInterfaceOrientation to return the appropriate setting–YES to allow all. In our default tab bar app, we have not assigned the second view to a controller because we have not defined one, so where is it getting its controller from? Well, the answer is found in interface builder. If you double-click MainWindow.xib in the Resources group of the Xcode project, Interface Builder will load. Click on the tab for the first view in the main window, and then select the Identity tab in the Inspector, you’ll see what is going on.

FirstViewController

Notice in the first view Class field, it is set to FirstViewController. Take a close look now at our second view by clicking the second tab.

SecondView Controller

Notice that the class we’re using here is the base UIViewController class. This is our view’s controller. It only provides the base functionality–which is to say it doesn’t provide a whole lot. Furthermore it implements the default functionality. The default setting for the orientation of a view controller is portrait only. In other words, only derivative classes are going to be able to override -shouldAutorotateToInterfaceOrientation and set it to something other than the default.

If you want your application to be able to support more than the default portrait orientation, all of your tab views must have their own view controller that overrides -shouldAutorotateToInterfaceOrientation

Conclusion

The iPhone is a fun and interesting computing platform. It is very powerful, but it has a lot of nuances that make it fairly different from what you may be used to on OS X. The trick is to remember the principles you’ve already learned in Cocoa, MVC in particular, and you should be able to deal with the nuances and make them submit to your own will. Until next time.

Differentiating Keypath From Key

Each core animation layer contains a dictionary that enables you to add and remove animations based on a key that you define. I created a layer-backed view that receives mouse clicks and animates the position of the layer toward that mouse click.

1
2
3
4
5
6
7
8
9
10
11

- (void)mouseDown:(NSEvent*)event;
{
    CABasicAnimation *animation = [CABasicAnimation animationWithKeyPath:@"position"];
    [animation setDelegate:self];
    [animation setFromValue:[NSValue valueWithPoint:previousValue]];
    previousValue = NSMakePoint([event locationInWindow].x, [event locationInWindow].y);
    [animation setToValue:[NSValue valueWithPoint:previousValue]];
    [animation setDuration:2.0];
 
    [objectLayer addAnimation:animation forKey:@"follow"];
}

Notice that when I create the animation, I am creating it with a keypath–in this case position. The keypath is different from the key by which we store the animation in the animations dictionary contained by the layer. In the sample code I add the animation to the dictionary using a key called “follow”. This could be any string that is meaningful to keep track of the animation in question. Consider it a tag.

I only make this distinction because I’ve seen some confusion about the difference between the two. To summarize, the keypath specifies which layer property you want to animate while the key is the key by which you will store, recall, and delete an animation from the animation dictionary contained by the layer.

Adding The Animation, Again

In the code above, you’ll also notice that we are adding the animation to the layer for the same key each time we receive a -mouseDown. If we are setting a new object in the dictionary each time, then how are we able to keep track of whether or not the animation finished?

By setting a delegate for the animation, we can be notified when animation has been removed from the animations dictionary. We implement the -animationDidStop:finished delegate.

1
2
3
4

- (void)animationDidStop:(CAAnimation *)theAnimation finished:(BOOL)flag
{
    NSLog(@"Animation interrupted: %@", (!flag)?@"Yes" : @"No");
}

There are several things going on here. When we call [objectLayer addAnimation:animation forKey:@"follow"]; in our -mouseDown code, the animation that was there previously, if there was one, is replaced by the new one. If the user clicked on the screen before the animation completed, the animation is removed and the delegate -animationDidStop gets called. If instead of clicking the mouse again before the current animation is finished, you just let it finish, the animation is also removed from the dictionary because this is the default behavior for an animation. If you don’t specify [animation setRemovedOnCompletion:NO] explicitly, the animation will be removed.

Changing Direction While In Flight

When the view receives a click the basic animation is re-created and added to the layer for the key “follow” again. The fromValue field needs set again, but if you click another spot on the view before the animation finishes, what value do you set it to? If you set it to the previous value, it will simply animate from the previous location which won’t look right. You want it to change direction rather than starting from the previous start location.

If instead of using a basic animation in our example code we had simply opted to use the animator proxy, calling -setPosition on the layer would do this for us. The problem is that we want to be able to demonstrate the -animationDidStop delegate which we can’t do with the animator proxy. So how do we provide this functionality of changing direction in flight?

Look no further than the presentationLayer which is accessible through our layer object. We can obtain the last location of our “position” parameter by first getting the presentationLayer and getting the position from it instead. We’ve modified our -mouseDown event to reflect this change.

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

- (void)mouseDown:(NSEvent*)event;
{
  CABasicAnimation *animation = 
          [CABasicAnimation animationWithKeyPath:@"position"];
  [animation setDelegate:self];
 
  // Get the presentationLayer
  CALayer *p = (CALayer*)[objectLayer presentationLayer];
  CGPoint position = [p position];
  NSValue *prevVal = [NSValue valueWithPoint:
                      NSPointFromCGPoint(position)];
 
  [animation setFromValue:prevVal];
 
  [animation setToValue:[NSValue valueWithPoint:[event locationInWindow]]];
  [animation setDuration:2.0];
  [animation setRemovedOnCompletion:NO];
 
  [objectLayer addAnimation:animation forKey:@"follow"];
}

Now, when we click in our view, the animation changes directions from its current location in the animation. The presentationLayer provides you with current values of whatever field you are currently animating. If a value is not being animated, you will get the same value as what is in the main layer.

Conclusion

It’s very handy to have a way to know when an animation is completed. You simply set your app delegate to be your animation’s delegate and when the animation completes, -animationDidStop:finished gets called conveying through the finished flag whether the animation was interrupted or not. To get our in flight values when the animation hasn’t completed, we simply look at the presentationLayer. These features of Core Animation are very powerful. Given the choice I would like to see the presentationLayer values become KVO compliant as this would let you monitor changes in real time, but being able to read the current value at any given time is a great capability in its own right. It’s very cool technology. Until next time.

Follow Me Demo Project

While new Cocoa programmers will find it a great help to getting started quickly with Core Data, the book also covers some really interesting and advanced topics such as data versioning and migration, Spotlight/Quick Look integration, Sync Services, and multi-threading. You can really see Marcus’ command of the subject shine in these chapters which are already available in the beta.

Give Marcus some feedback on the book as it progresses. It’s going to be a great reference for any Cocoa Developer looking to harness the power of Core Data.

$21.00 for the beta PDF $41.35 for the beta PDF plus hard copy when it’s released in March.

Mad props to Marcus. Congratulations!

The Slider Value

We connect a slider to an IBAction in xcode that will get called continuously as we have checked the checkbox called ‘Continuous’ in Interface Builder. We can read the slider value and apply it to our animation that we use to rotate the layer. In interface builder, we have specified a minimum value of -180, a maximum value of 180 and a current value (our starting value) of 0 on the slide control. When the slider is moved, the rotation updates as does the value of our text layer.

While it is coincidental that the demo application sort of looks like a pumpkin, it seems appropriate considering the time of year.

Layer Rotate

Rotation Animation

Rotating a layer is very simple. You just need to create an animation with “transform.rotation.z” as your keypath and then you can set from and to values that the animation will rotate between. We simply keep track of the last value we rotated (previousValue in the code) to and use this as our from value in the next change to the slider.

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

- (CAAnimation*)rotateAnimation;
{
  CABasicAnimation * animation;
  animation = [CABasicAnimation 
               animationWithKeyPath:@"transform.rotation.z"];
 
  [animation setFromValue:DegreesToNumber(previousValue)];
  [animation setToValue:DegreesToNumber([slider floatValue])];
 
  [animation setRemovedOnCompletion:NO];
  [animation setFillMode:kCAFillModeForwards];
 
  previousValue = [slider floatValue];
 
  return animation;
}

When our -sliderChange function gets called when the user moves the slider, we add the animation to the layer again using the key “rotate”. This is done first in our -awakeFromNib call and then in the -sliderChange call.

1
2
3
4
5
6

- (IBAction)sliderChange:(id)sender;
{
  [degreesTextLayer setString:[NSString stringWithFormat:@"%f", [slider floatValue]]];
  [needleLayer addAnimation:[self rotateAnimation] forKey:@"rotate"];
  [needleLayer setNeedsDisplay];
}

You will notice that we call -setNeedsDisplay on the layer. This is necessary as we have implemented the delegate method -drawLayer:inContext. We use this method to draw the vertical and horizontal black lines that intersect in the center of the circle layer.

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

- (void)drawLayer:(CALayer *)layer inContext:(CGContextRef)context;
{
  if( layer == needleLayer )
  {
      CGMutablePathRef path = CGPathCreateMutable();
 
      CGPathMoveToPoint(path,NULL, [view bounds].size.width/2.0, 0.0);
      CGPathAddLineToPoint(path, NULL, [view bounds].size.width/2.0, [view bounds].size.height);
 
      CGPathMoveToPoint(path,NULL, 0.0, [view bounds].size.height/2.0);
      CGPathAddLineToPoint(path, NULL, [view bounds].size.width, [view bounds].size.height/2.0);
 
      CGColorRef black =
              CGColorCreateGenericRGB(0.0, 0.0, 0.0, 1.0);
      CGContextSetStrokeColorWithColor(context, black);
      CFRelease(black);
 
      CGContextBeginPath(context);
      CGContextAddPath(context, path);
 
      CGContextSetLineWidth(context, 3.0);
 
      CGContextStrokePath(context);
 
      CFRelease(path);
 
  }  
}

Retaining The Rotation Position

There are two parameters of an animation that must be set otherwise the layer transform will just revert back to the original rotation. These two lines of code in our animation creation code ensure that what you see remains sticky when the value is changed.

[animation setRemovedOnCompletion:NO];
[animation setFillMode:kCAFillModeForwards];

Now, when the slider moves, the vertical and horizontal lines will stay in the correct rotation position. If you comment those two lines of code out in the demo project, you will see that while the rotation layer animates, it jumps right back to its original rotation as soon as the animation completes.

Conclusion

You will likely find many uses for this type of control. You could of course control the rotation based upon some other value or control other than a slider, but this code demonstrates how simple it is to rotate a layer based upon user input. Until next time.

Layer Rotate Demo Project

1
2
3
4
5
6
7

[[window contentView] setWantsLayer:YES];
[qcView setWantsLayer:YES];
 
CATextLayer *text = [CATextLayer layer];
[text setString:@"hello World"];
[text setFrame:NSRectToCGRect([qcView frame])];
[[qcView layer] addSublayer:text];

This code would allow the text layer to show up, however, the Quartz Composition was gone and all I got was a gray window with the “hello World” text on it.

Two Heads Better Than One

This is what I love about NSCoder Night. You get some Cocoa geeks together and the collective wisdom starts this synergy where we can bounce things off each other and a solution emerges.

Chad, in the mean time, had been searching the web for some examples and at about the time I started to wonder if there was a Core Animation specific layer for Quartz Compositions, he said, “QCCompositionLayer”. Marcus and I were both at that point thinking, “ah, I should have thought of that since there are Core Animation layers to do everything else media related.”

I then went to town slinging some code and here is what I came up with:

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

- (void)awakeFromNib;
{
  [[window contentView] setWantsLayer:YES];
 
  QCCompositionLayer *layer = [[QCCompositionLayer alloc] 
            initWithFile:@"/Developer/Examples/Quartz Composer/Plugins/OpticalFlow/Teapotii.qtz"];
 
  [layer setFrame:NSRectToCGRect([[window contentView] frame])];
 
  CATextLayer *text = [CATextLayer layer];
  [text setString:@"hello World"];
  [text setFrame:NSRectToCGRect([[window contentView] frame])];
  [ayer addSublayer:text];
 
  [[[window contentView] layer] addSublayer:layer];    
}

I got rid of the QCView altogether and just added the Quartz Composer layer to the sublayers of the window’s content view. The Quartz Composition in a QCCompositionLayer begins to play automatically, so really this code is all there is to it. And notice that the text overlay works as well. You could really add anything you wanted in a Core Animation layer at this point.

Your Own Composition

If you’re anything like me this will whet your appetite for playing with some very cool technology. I decided to create my own Quartz Composition and include that in the demo project. The demo composition takes the vide input of your iSight camera and applies the image to each side of a cube. It then rotates the cube. Creating the composition was pretty easy with a cursory reading of Apple’s Quartz Composer User Guide. It’s quite helpful.

You can take a look at the Quartz Composition in Quartz Composer. The demo application has two .qtz files in it. You can just double click either of those from the Finder to see what I did. The one I’m using in the demo app is the one called “VideoCub.qtz”. You can switch it in the code to see the other one as well, which is a quad of four iSight inputs.

VideoCube QC Editor

Quartz Composer Layer

You can see I added a CATextLayer to the QCCompositionLayer which displays the words, “hello World”. I also applied a Gaussian blur filter to the whole thing so you can see how easy it is to add filters as well. Here is all of the code needed to make this work.

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)awakeFromNib;
{
    [[window contentView] setWantsLayer:YES];
 
    NSString *path = [[NSBundle mainBundle] 
                      pathForResource:@"VideoCube" 
                      ofType:@"qtz"];
 
    QCCompositionLayer *layer = 
        [[QCCompositionLayer alloc] initWithFile:path];
 
    [layer setFrame:NSRectToCGRect([[window contentView] frame])];
 
    CATextLayer *text = [CATextLayer layer];
    [text setString:@"hello World"];
    [text setFrame:NSRectToCGRect([[window contentView] frame])];
    [layer addSublayer:text];
 
    CIFilter *blurFilter = 
    [CIFilter filterWithName:@"CIGaussianBlur"];
 
    [blurFilter setDefaults];
    [blurFilter setValue:[NSNumber numberWithFloat:2.0] 
                  forKey:@"inputRadius"];
    [blurFilter setName:@"blur"];
 
    [layer setFilters:[NSArray arrayWithObject:blurFilter]];
 
 
    [[[window contentView] layer] addSublayer:layer];
}

What’s even more exciting to me is that if you know a bit of OpenGL, you can do all kinds of other manipulations of the image since QCCompositionLayer inherits from CAOpenGLLayer. Take a close look at -drawInCGLContext in the CAOpenGLLayer API docs. There is a ton of great potential there.

Conclusion

The conclusion is that Quartz Compositions are very cool and they are now even cooler since you can work with them in Core Animation. Take a look a the Quartz Composer guide and start building your own compositions that you can easily incorporate into your Core Animation based applications. Until next time.

Quartz Composition Layer Demo 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

A Cocoa framework is another project type in Xcode. The end result is a bundle, similar to an application bundle. Inside of this bundle is the compiled code you wrote and any headers that you want exposed. The headers are important. Without them, just like any other piece of Objective-C code, it is very hard to code against.

Building a Framework in Xcode

Building a framework within Xcode is straight-forward. There is already a project template specifically for Cocoa frameworks so that is where we will start.

Once the framework is build, the rest of the code development is almost identical to an application bundle. C, C++ and Objective-C files can be included along with nibs, xibs, images and just about anything else we would stick into an application bundle. When the code is complied, the end result is also a bundle, again very similar to an application. The bundle structure, however, is a bit different and will be discussed in detail below.

Care must be given to the headers that we write and that we expose as part of that framework. In general, we really only want to expose the headers that users of the framework are going to interact with. If a header is completely internal to the framework then do not plan on exposing it. In addition, it is a good idea to have a wrapper header that users can import and gain references to all of the public headers. Since a framework will undoubtably contain more than one class file, how do we roll all of that up into one header? One solution I have seen is to create a separate header file and copy all of the interfaces into it. Unfortunately that solution can become unwieldy very quickly. My preferred solution is to build a “wrapper” header file that imports all of the headers that you want exposed. This is demonstrated in Code Sample 1.

Code Sample 1: Example.h

#import "ExampleOne.h"
#import "ExampleTwo.h"

Once the framework is built but before we distribute it, there are a few tweaks we need to deal with. First, we need to declare which headers are public and which are project. There is also an option for private but honestly I cannot see the logic behind them. If we flag a header as private it gets included in the resulting framework in a directory called “PrivateHeaders”. However, if we flag a header as “project” then it is correctly not included in the framework. Public headers are naturally included in the framework under the Headers directory.

Which headers should be included

<

p>For some headers, the answer to that question is easy. However, there are some gotchas that need to be planned around. If an object is referenced in one of the public headers then its header must also be public. Therefore if we want an object to be private/hidden/internal then we need to make sure there are no public references to it anywhere in any of the exposed headers. For example, if we had a an internal object called InternalObject and we referenced it in our header, the header for InternalObject would need to be public. See See Image 2.

<

p>However, if the reference is an id instead, we can keep the InternalObject private and its header un-exposed. See Image 3.

On thing to note is that in both cases, the AbstractExample is public even though we do not want anyone extending it. Because both ExampleOne and ExampleTwo are subclasses of AbstractExample its header must therefore be included in the framework. To make this a little confusing, this is NOT the case if the application and the framework both exist in the same project! If we look at the included project (called Example), and turn AbstractExample to project, everything will work just fine. However, if we take that compiled framework and use it in the second included project (called Test), it will fail. Therefore depending on how we are going to use the framework, superclasses will probably need to be included.

Using the framework

Now that we have our framework built, how do we use it? There are three places we can put this framework. We can make it system accessible, user accessible or application accessible.

System Accessible

System accessible frameworks are just like the frameworks that come with OS X. They can be imported into any application. For this magic to work, however, they need to be installed in a system level folder; specifically /Library/Frameworks. Go ahed and look in that directory now. If your system is anything like mine it is empty. Why? Because system level frameworks require root access to be installed and therefore require privilege escalation to get them there. Generally this is a BAD IDEA and there are few frameworks that follow this path.

User Accessible

User accessible frameworks are very similar to System accessible frameworks. However they are stored in a user writable location instead; ~/Library/Frameworks. Go ahead and look for this directory also. Chances are the directory itself does not even exist. This is safer than a system accessible framework and if we have a framework that is going to be used by multiple applications then this might be a logical place for it. But both user accessible frameworks and system frameworks have the same technical challenge discussed below.

Application Accessible

Outside of Apple this is the most common usage of a framework. It is bundled with the application and only the application can access it. Both of the other locations for frameworks have one issue; how do you get them there? The answer? You include them with the application of course! However, if you have to include them with the application (and you will need to include them with EVERY application that uses them) then what exactly is the point of putting them somewhere else? This is one of the main reasons that System and User accessible frameworks really don’t have a point; again outside of Apple.

Setting the installation directory

Since it only really makes sense to have our framework be application accessible, we need to tell it that when we build it. While this is not important for an application that has the framework included in its build cycle, if we want our application to be used by other applications, it becomes critical. When an application links to a framework, it needs to know where the final resting place of that framework is going to be. The default for the framework template is ~/Library/Frameworks. Clearly this needs to change.

To get a framework to acknowledge that it will be used inside of an application, we have to set the installation directory to a relative path. That relative path is:

@executable_path/../Frameworks

Once we have the installation directory set, it is time to include it in our application.

Setting up the targets for our application

Looking in the Example project, there are two targets, one for the framework and one for the application. Opening the application’s target we can see that the framework is a dependency of the application. This will insure that the framework will be built whenever we build the application. In addition, the framework is also in the “Link Binary With Libraries” build phase so that our application can build against it.

There are also two new build steps for this application that are directly related to the framework. First, is a Copy Frameworks phase. This was added using the Project -> New Build Phase -> New Copy Files Build Phase. I then renamed it to Copy Frameworks for clarity. Selecting Show Info on the Copy Frameworks build phase will show that its directory is set to “Frameworks”. This will create a Frameworks directory inside of our application build and copy our framework into it. This is how we distribute a framework with the application.

<

p>The other additional build phase is called “Clean Framework Headers” and is a script build phase. The purpose behind this phase is to delete all of the header files out of the application bundle once everything is finished. Why? Because they are not needed at runtime and there is no point in distributing them. When we distribute the framework on its own we definitely need to leave them but for the included framework they are just wasted bits. Therefore the script removes them as the final build phase for the application only. See Code Sample 2.

echo "build path ${TARGET_BUILD_DIR}"
cd ${TARGET_BUILD_DIR}/${FULL_PRODUCT_NAME}/Contents/Frameworks 
rm -rf */Headers 
rm -rf */Versions/*/Headers 
rm -rf */Versions/*/PrivateHeaders 
rm -rf */Versions/*/Resources/*/Contents/Headers

Framework Structure

<

p>For the curious, the internal structure of a framework is similar to an application. There is a compiled binary and a Resources directory that contains all of the xib, nibs, etc. There is also a Headers directory (and in some cases a PrivateHeaders directory) that contains all of the exposed header files. Where things chance is that a framework is versionable. The actual headers, resources and binary are actually stored in the Versions/${VERSION} subdirectory. From that directory there are sym-links up to the root directory of the bundle and also to the Versions/Current subdirectory.

${compiled_binary} -> Versions/Current/Example
Headers -> Versions/Current/Headers
Resources -> Versions/Current/Resources
Versions/A/${compiled_binary}
Versions/A/Headers
Versions/A/Resources
Versions/Current -> A

The purpose of this is to allow multiple versions of a framework to be stored within one bundle. However it is unlikely you will ever see more than one version in a bundle. It is a manual process to combine the versions and each version has to be kept in its own xcode project and merged by hand. In addition, since it really only makes sense to have frameworks inside of application bundles, it does not make much sense to have multiple versions of the framework. Nevertheless the functionality is there for those pesky edge cases.

Conclusion

Frameworks definitely have their place. They are very useful when writing a plugin architecture, etc. However, since they only make sense to include them in an application, unless you are sharing the framework or doing plugins, chances are it is better to just include the source code and be done with it.

Example Project

Test Project

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.

Microsoft’s new technology called LINQ, which stands for Language Integrated Query provides a way for developers to massage data collections using a SQL-like syntax that is built right into the language. You can perform simple data queries like this.

1
2
3
4
5
6
7
8
9
10
11
12

List products = GetProductList();
 
var soldOutProducts =
    from p in products
    where p.UnitsInStock == 0
    select p;
 
Console.WriteLine("Sold out products:");
foreach (var product in soldOutProducts)
{
    Console.WriteLine("{0} is sold out!", product.ProductName);
}

Notice how it has a very SQL like syntax. It’s actually very powerful and robust. There are a lot of capabilities. Take a look at the 101 LINQ Samples page if you would like to see more examples. What’s most interesting to me though is that the ideas behind this technology are not new.

If you’re new to Cocoa, you’ve probably heard of key-value coding and have probably even worked through some examples of its use without really understanding it. While the usage is different between the two, these technologies provide similar capabilities. Objective-C just had them first.

Key Paths Rule

Since OS X, the first version, key paths have been an integral part of data access and manipulation. Given an array or dictionary of objects you can filter your data down to a more specific data set. Your array doesn’t need to know anything about your data objects within the array or dictionary as the fields can be accessed by name. Have you ever seen syntax like this in Objective-C and wondered what it is?

1

NSArray *lastNames = [customers valueForKeyPath:@"lastName"];

Say you have declared a Customer class like this:

1
2
3
4
5

@interface Customer : NSObject {
    NSString *firstName;
    NSString *lastName;
    NSString *emailAddress;
}

You declare some of the customer objects and add them to an array.

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

Customer *bob = [[Customer alloc] init];
[bob setValue:@"Bob" forKey:@"firstName"];
[bob setValue:@"Smith" forKey:@"lastName"];
[bob setValue:@"bob@somedomain.com" forKey:@"emailAddress"];
 
Customer *carol = [[Customer alloc] init];
[carol setValue:@"Carol" forKey:@"firstName"];
[carol setValue:@"Jones" forKey:@"lastName"];
[carol setValue:@"carol@somedomain.com" forKey:@"emailAddress"];
 
Customer *wilma = [[Customer alloc] init];
[wilma setValue:@"Wilma" forKey:@"firstName"];
[wilma setValue:@"Baker" forKey:@"lastName"];
[wilma setValue:@"wilma@somedomain.com" forKey:@"emailAddress"];
 
customers = [[[NSMutableArray alloc] initWithObjects:bob, carol, wilma, nil] retain];

Note: I could declare some field accessors for the Customer object which would allow you to get and set field values, but since this post is largely about key-value coding, I figured it would makes sense to demonstrate the full key-value coding way. There is no concept of private variable in Objective-C, so we can simply call - setValue: forKey: to set our fields.

So if you recall this code from above:

1

NSArray *lastNames = [customers valueForKeyPath:@"lastName"];

you can see that once -valueForKeyPath gets called on the customers array, the NSArray lastNames would now contain a list of all of the last names in the customers array.

(
    Smith,
    Jones,
    Baker
)

Ok, so that might only be slightly helpful, but keep in mind that you can filter this way as many times on the same array or a filtered array as you need to–not to mention that this capability has been around in OS X since 10.0. That’s right–ten dot oh; the first version of OS X. By time OS X 10.4 Tiger came around in 2005, this capability had improved significantly. Objective-C now had a way to use set and array operators that allow you to filter your results further and more efficiently.

Set and Array Operators

You can find all of the details that you might need to take advantage of these key path operators in the Key Value Coding Programming Guide. Read it. It’s very helpful and comprehensive. In essence what these operators provide is a way to get a count, sum, average, max, min, distinct arrays, and arrays of joined arrays based on simple key path syntax.

Say you were interested in the average string length of the email addresses of all of your customers (not terribly useful, but oh so demonstrative). You could get that using this call.

1

[customers valueForKeyPath:@"@avg.emailAddress.length"];

Keep in mind that the length field is not some special syntax but rather simply a key-value coding compliant variable in an NSString object which is what emailAddress is.

The result of the code above returns the average email string length as an NSNumber. In my example code from above, this returns 19 for the NSNumber value.

But Wait! There’s More! NSPredicate

If you need to filter your array even further, you can do this simply by using an NSPredicate. Scott Stevenson has a short and sweet blog post that demonstrates clearly how to use an NSPredicate on an array at his Theocacao: Using NSPredicate to Filter an NSArray. I’ll make his code conform to our example code here.

1
2
3
4
5

NSPredicate *predicate;
predicate = [NSPredicate predicateWithFormat:@"emailAddress.length > 18"];
NSArray  *longEmailAddresses = [customers filteredArrayUsingPredicate:predicate]; 
 
NSLog(@"Email Addresses Longer Than 18 Chars: %@", longEmailAddresses);

The array longEmailAddresses now contains two Customer objects for the two customers who have email address string lengths greater than 18 characters.

But really that’s just the beginning. You can find all you need to know about Predicates in the Predicate Programming Guide at the Apple Developer site. You’ll see that you can combine the set and array operator syntax with an NSPredicate to get pretty much any type of data query filter you can imagine. As an example, say you want to get an array of all of the customers who’s email addresses use the same domain name. The code would go like this.

1

predicate = [NSPredicate predicateWithFormat:@"emailAddress endswith '@somedomain.com'"];

This will return all of our customer objects in the array because they all have the same domain name, however, if you change one of the email addresses, say for Carol.

1

[carol setValue:@"carol@otherdomain.com" forKey:@"emailAddress"];

you will notice that the array will now only contain the two customer objects who’s domain names are somedomain.com.

So What About LINQ

LINQ is actually very interesting technology. It allows you to run these types of inline queries on different types of data sets including XML and SQL databases. To ask the question “which is better” is really just an invitation to argue, so I won’t claim that the Cocoa is necessarily better. It has, however, been around longer and has provided these capabilities since the early days. So the point is that if you’ve seen this “new-fangled technology” from Microsoft and are wondering if you can do the same in Cocoa, the answer is a resounding yes. Data filtering as part of the language is cool technology, but it is most certainly not a Microsoft invention. All props to Anders Hejlsberg, the creator of C# and LINQ. He’s an amazing engineer and has brought a lot of great insight to Microsoft on behalf of developers. If you have to develop applications on Windows, be thankful for this guy. Without him, things would be a lot worse.

If you are, however, free to code in Cocoa, then embrace the key-value coding methodology. It’s very powerful and gives you flexibility that helps you to reduce the amount of code you need to write.

Conclusion

As a Objective-C/Cocoa developer, you need to get your key-value coding game on. It’s a very powerful component of the language and once you understand it, you’ll be able to not only utilize it where its available in the API, but you’ll be able to put it to use in your own objects. Until next time.