One of the great new features of iOS 5 is the addition of the Core Image (CI) framework. This framework has been available for a few years on the Mac, but now its advanced image processing and filtering capabilities are available on the iOS platform as well. One particularly cool new feature available in Core Image, on both iOS 5 and Lion, is its ability to detect faces in an image. Thanks to some recent inspiration from Jon Steinmetz over at Pixel Research Labs I have put together this tutorial showing how to use this great new feature.

Getting Started

The face detection API is surprisingly simple to use. It really boils down to two classes: CIDetector and CIFaceFeature. CIDetector is responsible for performing the analysis of an image and returns a collection of CIFaceFeature objects describing the face(s) found in the image. You begin by creating a new instance of CIDetector using its detectorOfType:context:options class method.

CIDetector *detector =
    [CIDetector detectorOfType:CIDetectorTypeFace context:nil options:options];

CIDetector can currently only be configured to perform face detection so you’ll always pass the string constant CIDetectorTypeFace for the type argument. The context and options arguments are optional, but you will typically provide it an options dictionary describing the accuracy level to use. This can be configured by defining a dictionary with the key CIDetectorAccuracy and a value of either CIDetectorAccuracyLow or CIDetectorAccuracyHigh. The high accuracy algorithm can produce far more accurate results, but takes significantly longer to perform the analysis. Depending on what you need to accomplish you may find the low accuracy setting produces acceptable results.

Analyzing the Image

With a properly configured detector in hand you’re ready to analyze an image. You call the detector’s featuresInImage: method passing it an image to analyze. The Core Image framework doesn’t know anything about UIImage so you can’t directly pass it an image of this type, however, UIKit provides a category on CIImage making it easy to create an instance of CIImage from a UIImage.

UIImage *uiImage = [UIImage imageNamed:@"image_name"];
CIImage *ciImage = [[CIImage alloc] initWithImage:uiImage];
NSArray *features = [detector featuresInImage:ciImage];

The featuresInImage: method will return a collection of CIFaceFeature objects describing the features of the detected faces. Specifically, each instance defines a face rectangle, and points for the left eye, right eye, and mouth. It only defines the center point of each feature so you’d have to perform some additional calculations if you’d need to know the feature’s shape, angle, or relative location.

Visualizing the Results

The following images show examples of the face detection API in action. The images illustrate the differences between the low and high accuracy settings along with the approximate times it took to run the detection. The location of the detected features is not significantly different between the two images, but you’ll notice the high accuracy setting took more that 10x longer to compute on an iPhone 4. It will likely require a fair amount of testing of a representative set of images to determine the appropriate accuracy setting for your app.

CIDetectorAccuracyLow ~253ms on iPhone 4	CIDetectorAccuracyHigh ~ 2810ms on iPhone 4

I have put together a sample app containing images of several iconic faces. Flip through the images and run the analysis to see the face detection in action. You can run the sample on the simulator, but I’d recommend running it on your device so you can get a realistic sense for the performance. Enjoy!

Download iOS 5 Sample App: Faces

When Xcode 4 was released about a year ago it introduced an entirely new Project and File Template syntax. This was initially frustrating to me as the new syntax invalidated all of the custom templates I had written for Xcode 3. However, the new template format has proven to be more flexible and capable and represents an improvement over the old format. Now that Xcode 4.3 is officially available I thought it would be a good time to discuss creating custom file templates. In this post I’ll explain the file template layout, structure, and syntax and then finish up by creating some custom templates to simplify building Singleton objects and generating GHUnit test cases.

Getting Started

The easiest way to become familiar with Xcode’s template format is to study the default templates included with Xcode itself. Unfortunately, Apple doesn’t document the syntax, but a lot can be learned simply by experimenting with the ones already included with Xcode. The repackaging of Xcode 4.3 into a single app bundle makes it a little less obvious where to find these files. They still exist on disk, but instead of finding them under the /Developer folder you’ll find them inside of the Xcode.app bundle itself:

Mac Templates

/Applications/Xcode.app/Contents/Developer/Library/Xcode/Templates/File Templates

iOS Templates

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/File Templates

Open them up and take a look at their content and structure, but I would strongly warn against editing these files. Making an invalid edit to the default templates can render them useless and cause Xcode to crash. Instead, copy any of them you would like to modify into your “user templates” directory. This directory isn’t automatically created so you’ll need to create the following directory if it doesn’t already exist:

~/Library/Developer/Xcode/Templates/File Templates/

Any templates that you modify or create from scratch should be organized into their own specific directory. It’s best to give the directory a meaningful name, such as your company name, so they show up neatly in Xcode. For the remainder of this article it is assumed all file templates I’m creating will exist in a directory called TapHarmonic.

Let’s start to discuss the syntax by breaking down the components of a template.

The Template Container

A template is a collection of files contained within a directory with an .xctemplate extension. This is just an ordinary folder, but the .xctemplate suffix is required for these directories to be recognized as templates by Xcode.

If you examine the contents of the various default templates you’ll typically find the following items:

Before examining the template components in more detail let’s begin by creating a new template directory. Create a new directory called Custom Template.xctemplate. You may want to copy the TemplateIcon.icns from one of the other template directories so it will have an icon in the New File dialog. We’ll begin creating our custom template by starting with its configuration file.

Understanding TemplateInfo.plist

The most important file in the template is TemplateInfo.plist. This is a standard Apple plist describing the behavior of the template. It allows you to define one or more output files to create, provides syntax for creating user input screens, and enables creating custom variables to be used when generating your code. You can edit the contents of this file in Xcode’s plist editor, but my recommendation is to use a standard text editor like TextMate or BBEdit.

There are two distinct sections to this file: the first defines the general template configuration and the second defines the template’s user interface and output variables. I’ll begin by starting with the general keys and values common to all templates:

Armed with the keys and values above, we can begin constructing a simple template with a minimal TemplateInfo.plist.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>AllowedTypes</key>
    <array>
        <string>public.objective-c-source</string>
    </array>
    <key>Description</key>
    <string>A simple template to produce an Objective-C class.</string>
    <key>Kind</key>
    <string>Xcode.IDEKit.TextSubstitutionFileTemplateKind</string>
    <key>MainTemplateFile</key>
    <string>___FILEBASENAME___.m</string>
    <key>Platforms</key>
    <array>
        <string>com.apple.platform.iphoneos</string>
    </array>
</dict>
</plist>

This provides enough configuration for our simple template, but before any actual output can be created we need to add some source files.

Source Files

We want the output from this template to be an Objective-C class. The template’s MainTemplateFile value refers to a file named ___FILEBASENAME___.m. We’ll create this file in our template directory along with its associated header.

//
//  ___FILENAME___
//  ___PROJECTNAME___
//
//  Created by ___FULLUSERNAME___ on ___DATE___.
//  Copyright (c) ___YEAR___ ___ORGANIZATIONNAME___. All rights reserved.
//

@interface ___FILEBASENAMEASIDENTIFIER___ : NSObject

@end

//
//  ___FILENAME___
//  ___PROJECTNAME___
//
//  Created by ___FULLUSERNAME___ on ___DATE___.
//  Copyright (c) ___YEAR___ ___ORGANIZATIONNAME___. All rights reserved.
//

#import "___FILEBASENAME___.h"

@implementation ___FILEBASENAMEASIDENTIFIER___

@end

The source templates have a number of values prefixed and suffixed with triple underscores. These are built-in expansion macros that can be used to provide dynamic values in your output. The following table lists the known macros:

Now that we’ve created our template directory, added its icon, plist, and source files we’re ready to put it into action. Select File > New > File… and you should see the template displayed in the dialog.

This basic template will have no custom user interface. You’ll simply select the template, provide a file name when prompted, select the applicable targets, and press the “Create” button. This level of simplicity works fine for basic templates such as ones generating a protocol or class extension, but Xcode 4 provides some more advanced features to capture user input.

Building the User Interface

Xcode’s template syntax defines an optional “Options” structure used to configure the template’s user interface. The Options key defines an array of dictionary elements that describe the user input components, user interface strings, and custom output variables.

We’ve seen some examples of how to use the built-in expansion macros to merge dynamic data into our template, but how do we take the input from our user interface and map it into our template source? The Identifier defines the variable name we can use in our source template files to reference its associated value. For instance, if your template defines an Identifier called viewColor, you can reference the variable’s value in the source template using either ___VARIABLE_viewColor___ or ___VARIABLE_viewColor:identifier___. The latter form ensures the value is munged to a valid C identifier.

Source File Grouping

In the template we’ve been building so far our source template files reside at the same directory level as the TemplateInfo.plist. It’s important to understand if your input component is a popup, combo, or class, Xcode will look for subdirectories in your .xctemplate file mapping to the values provided by the input element. For instance, if you have a popup element defined in your configuration:

<key>Options</key>
<array>
    <dict>
        <key>Type</key>
        <string>combo</string>
        <key>Values</key>
        <array>
            <string>Red</string>
            <string>Green</string>
            <string>Blue</string>
        </array>
    </dict>
</array>

The template will expect to find your MainTemplateFile under a Red, Green, or Blue directory. If you don’t provide this directory structure the template will either silently fail or will result in an Xcode crash. The need to have several, often subtle, variants of your template source files does result in a fair amount of redundancy, but does provide a convenient way of grouping template contents. Take a look at Apple’s Objective-C class.xctemplate for some concrete examples of how this works.

Creating Custom Templates

You should now have a better understanding of the template syntax and how the default templates are built. We’ve used this knowledge to build a simple, but not particularly useful template. Let’s walk through a couple more practical examples.

Creating a Custom Singleton Template

It would be nice to build a file template that simplifies the creation of a new Singleton object. There are a number of different approaches you could take when developing a Singleton, but I’ll define this template in terms of two different Singleton styles: Traditional and Grand Central Dispatch (CGD)-style. For the record, that latter is what you should choose when developing for iOS 4 and above.

This template should prompt us for the name of the class we want to create and provide a pop up menu for us to select the Singleton style. Additionally, it would be helpful if it could remember our last used style option.

We’ll begin by creating a new directory called Singleton class.xctemplate. Since our user interface will contain a popup selector we’ll additionally need to create two subdirectories corresponding to the popup’s values. Both the GCD and Traditional subdirectories will contain a a ___FILEBASENAME___.h and ___FILEBASENAME___.m file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>AllowedTypes</key>
    <array>
        <string>public.objective-c-source</string>
        <string>public.objective-c-plus-plus-source</string>
    </array>
    <key>Description</key>
    <string>A Singleton class.</string>
    <key>Kind</key>
    <string>Xcode.IDEKit.TextSubstitutionFileTemplateKind</string>
    <key>MainTemplateFile</key>
    <string>___FILEBASENAME___.m</string>
    <key>Options</key>
    <array>
        <dict>
            <key>Description</key>
            <string>The name of the Singleton class to create</string>
            <key>Identifier</key>
            <string>productName</string>
            <key>Name</key>
            <string>Class Name</string>
            <key>NotPersisted</key>
            <true/>
            <key>Required</key>
            <true/>
            <key>Type</key>
            <string>text</string>
        </dict>
        <dict>
            <key>Identifier</key>
            <string>singletonStyle</string>
            <key>Name</key>
            <string>Singleton Style</string>
            <key>Description</key>
            <string>The style of Singleton to create.</string>
            <key>Type</key>
            <string>popup</string>
            <key>Default</key>
            <string>GCD</string>
            <key>Values</key>
            <array>
                <string>GCD</string>
                <string>Traditional</string>
            </array>
        </dict>
    </array>
    <key>Platforms</key>
    <array>
        <string>com.apple.platform.iphoneos</string>
    </array>
    <key>Summary</key>
    <string>A Singleton class.</string>
</dict>
</plist>

I won’t describe all the source files, but will show the template file for the GCD-style implementation.

#import "___FILEBASENAME___.h"

@implementation ___FILEBASENAMEASIDENTIFIER___

+ (id)shared___FILEBASENAMEASIDENTIFIER___ {
    static dispatch_once_t predicate;
    static ___FILEBASENAMEASIDENTIFIER___ *instance = nil;
    dispatch_once(&predicate, ^{instance = [[self alloc] init];});
    return instance;
}

@end

Running this template will provide us with the following user interface and output:

#import "UserManager.h"

@implementation UserManager

+ (id)sharedUserManager {
    static dispatch_once_t predicate;
    static UserManager *instance = nil;
    dispatch_once(&predicate, ^{ instance = [[self alloc] init]; });
    return instance;
}

@end

Creating a Custom GHUnit Test Case Template

Xcode includes some basic unit testing support built on OCUnit. Although its support for unit testing continues to improve I’ve never been a big fan of its built-in functionality. Instead, I greatly prefer using the open source framework called GHUnit. GHUnit better conforms to other XUnit testing frameworks and definitely provides a more comprehensive solution.

Creating a new GHUnit test case can be a little tedious. Without a file template the process usually goes something like this:

1. Create an Objective-C class under my UnitTest target.
2. Copy the @interface section from the header file and paste it into the implementation file and then delete the header file.
3. Import the class I’m going to test.
4. Stub out the the setUp and tearDown methods.
5. Stub out a test method.

Whew! That’s a lot of work before you can even write a single line of test code! This level of impedance will almost certainly dissuade you from writing many unit tests. Luckily we can greatly simplify this process by creating a custom file template.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>AllowedTypes</key>
        <array>
            <string>public.objective-c-source</string>
        </array>
        <key>DefaultCompletionName</key>
        <string>Test</string>
        <key>Description</key>
        <string>A GHUnit Test Case</string>
        <key>Kind</key>
        <string>Xcode.IDEKit.TextSubstitutionFileTemplateKind</string>
        <key>MainTemplateFile</key>
        <string>___FILEBASENAME___.m</string>
        <key>Platforms</key>
        <array>
            <string>com.apple.platform.iphoneos</string>
        </array>
        <key>Options</key>
        <array>
            <dict>
                <key>Default</key>
                <string/>
                <key>Description</key>
                <string>What would you like to test?</string>
                <key>Identifier</key>
                <string>cutClass</string>
                <key>Name</key>
                <string>Test case for</string>
                <key>Required</key>
                <true/>
                <key>NotPersisted</key>
                <true/>
                <key>Type</key>
                <string>text</string>
            </dict>
            <dict>
                <key>Default</key>
                <string>___VARIABLE_cutClass:identifier___Test</string>
                <key>Identifier</key>
                <string>productName</string>
                <key>Type</key>
                <string>static</string>
            </dict>
        </array>

        <key>Summary</key>
        <string>A GHUnit Test Case</string>
    </dict>
</plist>

The source looks like:

#import "___VARIABLE_cutClass:identifier___.h"

@interface ___FILEBASENAMEASIDENTIFIER___ : GHTestCase
@end

@implementation ___FILEBASENAMEASIDENTIFIER___

- (void)setUp {

}

- (void)tearDown {

}

- (void)testMethod {
	// Implement test case
}

@end

Running this template will provide us with the following user interface and output the test case for a User class:

#import "User.h"

@interface UserTest : GHTestCase
@end

@implementation UserTest

- (void)setUp {

}

- (void)tearDown {

}

- (void)testMethod {
    // Implement test case
}

@end

Conclusion

Hopefully this post provided a helpful explanation of the syntax to create custom File Templates in Xcode 4. Even if you don’t find the need to build custom templates from scratch I highly recommend modifying Apple’s default templates to better suit your needs. A little bit of automation can go a long way in improving your development processes and accelerating your development cycles.

Download: Custom File Templates

As I was preparing to post the QuartzDemos project on GitHub I decided to modernize the project and covert it to use Automatic Reference Counting (ARC). Overall this was fairly easy to do despite some of the slightly confusing rules related to bridging between Objective-C objects and Core Foundation types. Everything was looking good on the Simulator, but decided I should give it a quick once over on the device. I expected everything to work fine so I launched my first demo and crash! Hmm… probably just a debugger anomaly. So I fired it up again and crash! The debugging begins…

I quickly found the cause of the crashes was due to the way I was converting between UIColor and CGColor types. There were many places where I was using UIColor to produce a CGColorRef, e.g.:

// Define Colors
CGColorRef startColor = [UIColor colorWithRed:1.000 green:0.969 blue:0.165 alpha:1.000].CGColor;
CGColorRef endColor = [UIColor colorWithRed:1.000 green:0.400 blue:0.165 alpha:1.000].CGColor;
NSArray *colors = [NSArray arrayWithObjects:(__bridge id)startColor, (__bridge id)endColor, nil];

// Create Gradient
CGGradientRef gradient = CGGradientCreateWithColors(colorSpace, (__bridge CFArrayRef) colors, locations);

This code worked fine in a manual memory management case as the UIColor instance gets added to the current autorelease pool which means you can count on it being around for the duration of the current run loop. However, that behavior is changed when using ARC. As UIColor is not being assigned anywhere the compiler assumes it’s not needed and immediately disposes of it. I was originally planning to go into more detail about why this is happening but noticed a tweet this morning that Mark Dalrymple, from The Big Nerd Ranch, beat me to the punch. Since Mark already did the heavy lifting, I’ll refer you to his post for the details. Instead, I’ll cut to the chase and explain how to fix this scenario.

After realizing the cause of the problem implementing a solution was fairly straightforward. I converted the code above to the following:

// Define Colors
UIColor *startColor = [UIColor colorWithRed:1.000 green:0.969 blue:0.165 alpha:1.000];
UIColor *endColor = [UIColor colorWithRed:1.000 green:0.400 blue:0.165 alpha:1.000];
NSArray *colors =
    [NSArray arrayWithObjects:(__bridge id)startColor.CGColor, (__bridge id) endColor.CGColor, nil];

CGGradientRef gradient = CGGradientCreateWithColors(colorSpace, (__bridge CFArrayRef) colors, locations);

Instead of defining the start and end colors as CGColorRef I define them as UIColor references and defer getting their underlying Core Graphics equivalent until it’s actually needed. This has the effect of extending the lifetime of the UIColor instances long enough to resolve the problem I was running into.

For more examples of this solution in action I’ll refer you to the QuartzDemos project on GitHub.

A couple of weeks ago I gave a presentation entitled “Drawing with Quartz on iOS” to the Minnesota CocoaHeads group. We had a big crowd that night and I hope you all enjoyed it. The slide deck is available on SlideShare and the QuartzDemos project is available on Github.

Quartz is an essential API for Mac and iOS developers to know, but I don’t believe it is widely understood. There are many useful resources on the Internets, Ray Wenderlich’s and Andy Finnell’s sites immediately come to mind, but the information on the topic is largely scattered. I’m hoping this presentation and sample project help to consolidate some of this information and make it easier for developers to learn the framework.

Feel free to reach out if you have any questions or comments.

I occasionally come across the need to grab the contents of a view as an image. This is often the result of needing to perform some non-stock, animated transition between views, but there are a variety of reasons why this might be useful. Thanks to the Core Animation framework’s CALayer class, this is easy to do.

All UIView instances have an underlying instance of a CALayer. The layer is responsible for rendering the view’s contents and performing any view-related animations. CALayer defines a method called renderInContext: which allows you to render the layer, and its sublayers, into a given graphics context:

UIGraphicsContext context = // some graphics context
[viewToCapture.layer renderInContext:context];

Before you can access any layer-specific APIs, you’ll need to make sure you’re linking against the QuartzCore framework. Xcode’s default templates don’t link against this framework so you’ll need to select Target Name > Build Phases > Link Binary With Libraries and select QuartzCore.framework.

Additionally, you’ll need to add the following import to your code wherever you are calling the layer’s properties or methods:

#import <QuartzCore/QuartzCore.h>

With the necessary project configuration out of the way, the next question is where do we get a graphics context into which we can render the view’s content? This can be created using UIKit’s UIGraphicsBeginImageContextWithOptions function which will create a new bitmap-based graphics context for us.

UIGraphicsBeginImageContextWithOptions(CGSize size, BOOL opaque, CGFloat scale);

This function takes a CGSize (you view’s size), a BOOL indicating if your view is opaque, and a CGFloat specifying the scaling factor. If you’re rendering a fully opaque, rectangular view you can pass YES for the opaque argument so the alpha channel can be discarded from the context.

Now that we’ve created a graphics context we can use the UIGraphicsGetCurrentContext() and UIGraphicsGetImageFromCurrentImageContext() functions to get reference to this new context and retrieve the rendered image data from it. Finally, we’ll want to call the UIGraphicsEndImageContext() function to clean up this context and remove it from the stack. Putting all this together we end up with the following:

// Render the views layer contents into the current Graphics context
CGSize viewSize = viewToCapture.bounds.size;
UIGraphicsBeginImageContextWithOptions(viewSize, NO, 1.0);
[viewToCapture.layer renderInContext:UIGraphicsGetCurrentContext()];
// Read the UIImage object
UIImage *image = UIGraphicsGetImageFromCurrentImageContext();
UIGraphicsEndImageContext();

To see this code in action I’ve put together a simple demo app. You can tap on Archer, Lana, or the background to capture the contents of the view and write the image to your Photo Library.

Note: Before running the demo be sure to open the “Photos” app on the Simulator so it can initialize its database or the images won’t be written. Enjoy!

Download Demo

My Core Animation Demos projects was previously available on Github under my personal account, but I have since moved it to my business account. The new location of of the CA demos is:

https://github.com/tapharmonic/Core-Animation-Demos

I haven’t made any major changes to code at this point, however, I did start an ARC branch to house my ongoing ARC changes.

The Factory pattern is a frequently used creational pattern to help abstract the creation of an object from its clients. Although there are a few specializations of this pattern I’ll focus on the most commonly used approach and then look at how we can leverage the Objective-C Runtime to make this solution more robust.

Let’s begin by creating a simple command-line app that creates Animal objects and gets them to speak on command. The various animal objects will all inherit from the abstract Animal class.

@interface Animal : NSObject {
}

- (void)speak;
- (NSString *)key;

@end

@implementation Animal

- (void)speak {
    NSAssert(NO, @"The 'speak' method must be implemented by subclass.");
}

- (NSString *)key {
    // Animal instances will be 'keyed' by their lower case class name
    // Overly simplistic, but will suffice for now
    return [NSStringFromClass([self class]) lowercaseString];
}

@end

With the abstract base class complete let’s create a couple concrete Animal implementations:

@implementation Cat
- (void)speak {
    NSLog(@"Meow, Meow...");
}
@end

@implementation Dog
- (void)speak {
    NSLog(@"Bark, Bark...");
}
@end

Our Cat & Dog objects are ready to go so let’s integrate them into our app and get them to speak.

int main (int argc, const char * argv[]) {

    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

    Animal *cat = [[Cat alloc] init];
    [cat speak];
    [cat release];

    Animal *dog = [[Dog alloc] init];
    [dog speak];
    [dog release];

    [pool drain];
    return 0;
}

Running this app will produce the following console output:

Meow, Meow...
Bark, Bark...

This works as we’d expect, but the main problem with using the Cat and Dog classes this way is coupling. Even though we’ve defined our variables as abstract Animal types we’re still coupled to the specific subtypes. This means we can’t modify our Animal types or evolve their creation without impacting our client code. This may seem like a trivial matter in this example, but these design decisions can have major impacts on real-world applications. Let’s avoid some of the potential ripple effects by introducing a factory.

Creating Animals

We’ll begin by moving the object creation responsibilities from our client to a new object called AnimalFactory. This factory, as you may have guessed, will be responsible for creating and vending instances of Animal. A simple, but common implementation of this could be defined as follows:

@implementation AnimalFactory

+ (AnimalFactory *)factory {
    return [[[[self class] alloc] init] autorelease];
}

- (Animal *)animalForKey:(NSString *)animalKey {
    Animal *animal = nil;
    if ([animalKey isEqualToString:@"dog"]) {
        animal = [[Dog alloc] init];
    } else if ([animalKey isEqualToString:@"cat"]) {
        animal = [[Cat alloc] init];
    } else {
        NSAssert(NO, @"No Animal found for key:'%@'", animalKey);
    }
    return [animal autorelease];
}

@end

The AnimalFactory will determine which instance to create based on the argument passed to the animalForKey: method. It creates the appropriate instance and returns an autoreleased version of it to the client. To use this new factory in our client we can make the following changes:

AnimalFactory *factory = [AnimalFactory factory];

[[factory animalForKey:@"cat"] speak];
[[factory animalForKey:@"dog"] speak];

If you were to run this example again you would see the same output as before, but the introduction of this factory has helped us resolve two specific limitations in our previous implementation:

1. The client is no longer coupled to a particular instance of Animal. As our requirements change the factory can return alternate instances (FatCat, HotDog, etc.) without impacting our client code.
2. The client is no longer in the business of object creation which means how an animal is instantiated is no longer its concern. Additionally, by returning an autoreleased instance we don’t unnecessarily force memory management responsibilities onto the client.

One outstanding problem we have is with the factory itself. Although the client is better decoupled from the specific types and their creation, the factory itself is not. Every time we add a new animal to the app we additionally have to make modifications to the factory.

[Informercial Guy Voice]  There’s got to be a better way!

Enter the Objective-C Runtime

Objective-C is a dynamic language where many decisions are deferred until runtime. This deferment allows for some of the more interesting capabilities of the language and is made possible through the Objective-C Runtime. Although you can successfully use Objective-C without having much awareness of the runtime, understanding how to interact with it can open up some interesting new possibilities.

It would be nice if our AnimalFactory could automatically find and dispense all instances of Animal without us having to continuously modify the factory. Thanks to the runtime, it can.

Automagic Factories

Let’s begin by creating a utility class called RuntimeUtils containing a method to allow us to dynamically find all instances of a particular type. This method will be implemented as follows:

+ (NSArray *)classStringsForClassesOfType:(Class)filterType {

    int numClasses = 0, newNumClasses = objc_getClassList(NULL, 0);
    Class *classList = NULL;

    while (numClasses < newNumClasses) {
        numClasses = newNumClasses;
        classList = realloc(classList, sizeof(Class) * numClasses);
        newNumClasses = objc_getClassList(classList, numClasses);
    }

    NSMutableArray *classesArray = [NSMutableArray array];

    for (int i = 0; i < numClasses; i++) {
        Class superClass = classList[i];
        do {
            // recursively walk the inheritance hierarchy
            superClass = class_getSuperclass(superClass);
            if (superClass == filterType) {
                [classesArray addObject:NSStringFromClass(classList[i])];
                break;
            }
        } while (superClass);
    }

    free(classList);

    return classesArray;
}

This method makes use of two functions defined in <objc/runtime.h>:

1. objc_getClassList - This function returns a list of all classes registered with the app. We'll loop through this list and then filter its results.
2. class_getSuperclass - Returns the superclass of a class. We recursively walk the inheritance hierarchy of each class to determine if it's a descendant of Animal. If so, we add its class string to our array.

With our RuntimeUtils class now ready, let's go back and revisit the implementation of our factory object.

Implementing the Magic

We'll change the implementation of our factory class to leverage this new RuntimeUtils class. We'll start by implementing the init method.

- (id)init {
  if ((self = [super init])) {
    NSArray *animalClassStrings = [RuntimeUtils classStringsForClassesOfType:[Animal class]];
    animals = [[NSMutableDictionary alloc] initWithCapacity:[animalClassStrings count]];
      for (id classString in animalClassStrings) {
        Class animClass = NSClassFromString(classString);
        Animal *animal = [[animClass alloc] init];
        [animals setObject:animal forKey:[animal key]];
        [animal release];
      }
    }
  return self;
}

Our init implementation starts by finding all the class strings for the classes extending Animal. We iterate through the results creating an instance of each class and storing its pointer in the animals dictionary. With the init method complete let's modify the animalForKey: method.

- (Animal *)animalForKey:(NSString *)animalKey {
    Animal *animal = [animals objectForKey:animalKey];
    NSAssert(animal, @"No animal found.  Invalid 'animalType' specified?");
    return animal;
}

We now have a greatly simplified animalForKey: method. Gone are the if/else or switch statements you'd typically see in a factory method. Instead, we have a simple, generic execution path regardless of the number of animals we add to the application.

To see the benefits of our revamped AnimalFactory, let's make a couple additions to our animal kingdom.

@implementation Monkey
- (void)speak {
    NSLog(@"Ooo, Ooo, Eee, Eee");
}
@end

@implementation Bird
- (void)speak {
    NSLog(@"Tweet, tweet");
}
@end

We can go back to our client code and make the following changes:

[[factory animalForKey:@"dog"] speak];
[[factory animalForKey:@"cat"] speak];
[[factory animalForKey:@"monkey"] speak];
[[factory animalForKey:@"bird"] speak];

If you run the application again you'll see the new Monkey and Bird instances were automatically registered with the factory without any additional changes! Winning!

Conclusion

Although this was clearly a contrived example, it hopefully illustrates how leveraging the Objective-C Runtime can result in significantly more flexible factory objects. Some simple modifications could be made to this approach to provide for lazy instantiation or handle more complex object creation. In a future post I'll provide a more concrete example of how this strategy can be put to good use in a real-world application.

Resources

Sample Code

Objective-C Runtime Reference

Understanding the Objective-C Runtime

This past week I gave a presentation on Core Animation to the Minnesota CocoaHeads user group. Core Animation is a truly amazing framework and is really the magic ingredient in the iOS user experience. Understanding how to effectively use it can allow you to add new levels of realism and interactivity to your apps.

As part of the presentation I prepared a number of examples ranging from image effects to 3D animations (OK, 2 1/2 D animations). If you’re interested in taking a look you can find the demo on github and the slides are available here.