Cocoa with Love

HashValue: an object for holding MD5 and SHA hashes

2009-07-06T03:41:00.001-07:00

Hash values are small, convenient values that you can generate from larger blocks of data for easy indexing, sorting and tracking. The traditional approach for generating MD5 and SHA hashes on Unix platforms to is to use command-line programs like openssl and md5. Apple provide easier approaches in the CommonCrypto library: here's how to use it, along with an NSValue subclass to wrap the result for interoperability with other Cocoa classes.

Introduction to hashes

A hash value is a small, convenient number used to track or sort an arbitrary block of data.

A real-world example of a hash value is the initial letter in a word. You can use the initial letter of a word to lookup that word in a dictionary. If two words have different starting letters, they cannot be equal but if two words have the same starting letter, that doesn't guarantee they are the same.

For fast searching, you can immediately see the problem with only using an initial letter: if all you had to look up a word was its initial letter, you'd still have thousands of words to go through that all start with the same letter. You could use the first four letters but some combinations will be rare (like "aard") but others will contain hundreds of matches (like "stra").

In computing, we rarely ever use the first values in a block of data to track that block of data. Starting values of blocks of data are too often the same or similar — especially in the common case where we are sorting data that already has traits in common.

Instead, we use hash functions that use relatively complex mathematics to generate values from the source data that are well spread, even for source data that is nearly identical. Fortunately, you don't need to know the underlying mathematics, all you need to know is that a hash value can be used to:

check if two blocks of data are the same
sort data into hash tables
checksum data (make certain your data hasn't changed)

Though these are the main purposes for which you should use hashes, MD5 and SHA hashes were actually developed for cryptography, not basic data handling. Nevertheless, for encryption and password handling in your own applications, I recommend using the Keychain (Security.framework) rather than manually using cryptographic hashes.

Generating an MD5

MD5 is one of the most common hash functions. While it is no longer considered safe for security, its use as a checksum is very common.

The traditional Unix approach is to use the md5 program on the command-line:

matt$ md5 -s "Some data value."
MD5 ("Some data value.") = db7116c8634ad7fe3bd90bee94274ee0

The 32 character hexadecimal string is a human readable representation of the 16 byte output of the MD5 function.

On the Mac and iPhone, we can generate this value as follows:

#import <CommonCrypto/CommonDigest.h>

char input[] = "Some data value.";
char result[16];
CC_MD5(input, strlen(input), result);

However, we frequently want the human-readable hexadecimal string. The following will produce an identical ouput to the previous command-line invocation:

printf("MD5 (\"%s\") = %02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x\n",
    input,
    result[0], result[1], result[2], result[3], 
    result[4], result[5], result[6], result[7],
    result[8], result[9], result[10], result[11],
    result[12], result[13], result[14], result[15]);

Producing other kinds of hash works in the same way. e.g. For SHA256, use CC_SHA256 instead of CC_MD5 and increase the size of the result to 20 from 16.

The HashValue class

Since hash values are frequently used to track blocks of data in a program, it would be nice to have an Objective-C class that wraps the hash values so we can use them in NSDictionary objects as keys for our data.

If we consider a hash value simply as a small C struct, i.e:

typedef struct
{
    char value[CC_MD5_DIGEST_LENGTH];
} HashValueMD5Hash;

typedef struct
{
    char value[CC_SHA256_DIGEST_LENGTH];
} HashValueShaHash;

then the easiest way to make it a fully fledged Objective-C object is to create an NSValue from it:

char input[] = "Some data value.";
HashValueMD5Hash result;
CC_MD5(input, strlen(input), &result);

NSValue *myHashValue = [NSValue valueWithBytes:&result objCType:@encode(HashValueMD5Hash)];

That's an okay solution but if you're generating a lot of hashes in your program, it would be good to have a class that:

has an optimized construction method that can generate the hash directly from NSData
abstracts away the C struct so you can deal exclusively with the Objective-C objects
overrides the description method to easily generate human-readable strings

So I wrote the HashValue class.

@interface HashValue : NSObject <NSCoding, NSCopying>
{
    unsigned char value[HASH_VALUE_STORAGE_SIZE];
    HashValueType type;
}

- (id)initMD5HashWithBytes:(const void *)bytes length:(NSUInteger)length;
+ (HashValue *)md5HashWithData:(NSData *)data;
- (id)initSha256HashWithBytes:(const void *)bytes length:(NSUInteger)length;
+ (HashValue *)sha256HashWithData:(NSData *)data;

- (const void *)value;
- (HashValueType)type;

@end

Despite being a class that wraps a value, there's no explicit reason to make it a subclass of NSValue. Since subclassing NSValue has inherent difficulties (you need to carefully override a lot of inherited methods) I've made the class a basic subclass of NSObject.

The init method implementations are fairly simple:

- (id)initMD5HashWithBytes:(const void *)bytes length:(NSUInteger)length
{
    self = [super init];
    if (self != nil)
    {
        CC_MD5(bytes, length, value);
        type = HASH_VALUE_MD5_TYPE;
    }
    return self;
}

The description method is overridden to provide the human-readable hexadecimal string:

- (NSString *)description
{
    NSInteger byteLength;
    if (type == HASH_VALUE_MD5_TYPE)
    {
        byteLength = sizeof(HashValueMD5Hash);
    }
    else if (type == HASH_VALUE_SHA_TYPE)
    {
        byteLength = sizeof(HashValueShaHash);
    }

    NSMutableString *stringValue =
        [NSMutableString stringWithCapacity:byteLength * 2];
    NSInteger i;
    for (i = 0; i < byteLength; i++)
    {
        [stringValue appendFormat:@"%02x", value[i]];
    }
    
    return stringValue;
}

Most of the other methods in the class are basic accessors or NSCopying, NSCoding and NSObject methods. The copying methods in particular are essential so that the object can be used as a key in an NSDictionary.

I will highlight one other method:

- (NSUInteger)hash
{
    return *((NSUInteger *)value);
}

You may wonder why it's necessary to have a hash method on a class that is itself a hash value. Hash methods in Cocoa are used for the same indexing and sorting tasks I identified above: sorting and finding objects in NSSet and NSDictionary. In Cocoa the default hash method calculates its hash value from the memory address of the object. Because we have overridden isEqual: to compare the object's internal value, we also need to override the hash method to also reflect this change. This is a basic requirement of hashes — equal objects must return the same hash value (imagine the confusion if two identically spelled words were sorted to different locations in a dictionary).

It may seem a little odd to simply return the first few bytes of the value as our new hash (after I explained that the first few bytes is rarely the best hash) but this case is an exception to the rule: our data is already "well-spread" and every bit in our hash is as well-spread as the next.

Conclusion

You can download the HashValue class as a .zip file (2kB)

Hash values are used everywhere. Git uses SHA1 to track file changes in its repository, BitTorrent uses MD5s to identify torrents and many download programs use hashes to checksum downloaded data.

The CommonCrypto library (part of Foundation on the Mac and iPhone through libSystem) makes generating common hash functions very simple.

As with all data manipulation, I think a nice Cocoa class around the data makes it easier to use. I have only added MD5 and SHA256 to this particular implementation but it should be very simple to add other CommonCrypto hashes to the class should you require them.

Custom views in Interface Builder using IBPlugins

2009-07-02T02:23:00.001-07:00

If you have custom views configured in code, it can be time consuming to configure them for each instance and make them look right in context. To make the process smoother, you can create Interface Builder plugins and configure your objects in Interface Builder. While the Xcode documentation explains how to do this, it is long, thorough and confusing. Here is the simplified set of steps that I use to create Interface Builder plugins quickly.

Introduction

Apple do have extensive documentation on Interface Builder Plugin creation. However, their documentation is thorough enough that may be overwhelming the first time you want to write an Interface Builder plugin.

I also find the workflow in Apple's IBPluginGuide very different to my typical workflow. I think this is because I normally just want an existing class to show up in Interface Builder so I can tweak one or two attributes — the processes for creating a redistributable library of components is more than I need.

So I was inspired to write this post: a shorter, workflow-optimised version of the same process described in the IBPluginGuide — using Interface Builder to configure a custom button.

A custom buttom

Consider the button in the following window:

A big, drab, gray button. Maybe gray is an acceptable default but it doesn't really match this window. This post will make it easy to adjust this color in Interface Builder.

The large gray button here uses a custom button cell which draws the button using the Gloss Gradient from one of my earlier posts. The drawing code is:

- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView
{
    NSBezierPath *roundRectPath =
        [NSBezierPath
            bezierPathWithRoundedRect:NSInsetRect(cellFrame, 2, 2)
            xRadius:5
            yRadius:5];

    NSGraphicsContext *graphicsContext = [NSGraphicsContext currentContext];
    [graphicsContext saveGraphicsState];
    [roundRectPath addClip];

    DrawGlossGradient(
        [graphicsContext graphicsPort],
        self.buttonColor, // <-- this determines the color of the button
        cellFrame);

    if ([self isHighlighted])
    {
        [[NSColor colorWithCalibratedRed:0.0 green:0.15 blue:0.35 alpha:0.5]
            set];
        [roundRectPath fill];
    }
    [graphicsContext restoreGraphicsState];

    [[NSColor lightGrayColor] set];
    [roundRectPath setLineWidth:2.0];
    [roundRectPath stroke];

    [self drawInteriorWithFrame:cellFrame inView:controlView];
}

This is all fine except that the color of the button is determined by the self.buttonColor property and if we have to choose this in code (continually changing the value, fixing, continuing, refreshing and repeating) it could get very time consuming.

A better solution would be to edit the button's color in Interface Builder. That way, we will be able to use color sliders to update the button drawn in the complete context of the window, in real-time.

Creating the IBPlugin project

My process normally starts by creating a custom view component. In this case, I have already created a class named CustomButtonCell in the project for my main application (AppWithButton). After creating the class, I have decided it would be a good idea to have an Interface Builder Plug-In.

A quick point about class requirements: every property we want to configure in Interface Builder must be encoded and decoded for the object using implementations of the NSCoder protocol methods initWithCoder: and encodedWithCoder: overrides. Download the project linked below to see how this is done.

1. Create and name the project

"Interface Builder Plug-In" is a project template in Xcode. In the New Project window, it's in the "Mac OS X -> Standard Apple Plug-ins" section.

An important point to consider is the name for the project — it should not be the same as the custom view component (in this case, CustomButtonCell) because the template will create a class with the name and it can't conflict with the existing view component.

I chose "ButtonPlugin" and saved the new project in the folder for my existing AppWithButton project.

2. Make the new project use the existing CustomButtonCell

Delete the default files and insert our own

The template creates a custom view in the ButtonPlugin project. I never use this (since I want to use my existing view). So I delete the ButtonPluginView.m, ButtonPluginView.h references and files.

I add my CustomButtonCell.m and CustomButtonCell.h files to the ButtonPlugin project but I don't copy or move the files — I leave the files at their current locations in AppWithButton project but drag them into the ButtonPlugin's Source Tree.

Make certain these new files get built

You need to check that the CustomButtonCell.m is added to the Compile Sources build phase of the ButtonPluginFramework Target and the CustomButtonCell.h is added to the Copy Headers build phase of the ButtonPluginFramework. Neither should appear in the ButtonPlugin target.

Then, select the "CustomButtonCell.h" file from the "Copy Headers" build phase and in the Detail View, change the "Role" from "Project" to "Public". This is a pretty obscure thing to do. I normally don't have the Detail View visible — if you don't know which view is the Detail View, it's time to learn because there is no other way to change this value in Xcode.

Change the Role of the "CustomButtonCell.h" to "public" in the Detail View

Rename the file ButtonPluginViewIntegration.m to CustomButtonCellIntegration.m and replace every occurrence of ButtonPluginView in this file to CustomButtonCell.

3. Prepare all the other files in the project

Make the following file changes:

Find the ButtonPluginView.classdescription and rename this file to CustomButtonCell.classdecription (same as our custom cell).
In the contents of this file, change the ClassName to match the actual class name CustomButtonCell and change the SuperClass to be NSButtonCell (again, matching the actual super class for our custom button cell).
In ButtonPlugin.m (the top level class in the ButtonPlugin project), set the bundle identifier to something appropriate. I used com.mattgallagher.ButtonPlugin — this needs to be unique among Interface Builder plugins, so you pick an appropriate value each time.
Set the bundle identifier in the Info.plist and the ButtonPlugin-Info.plist to the same com.mattgallagher.ButtonPlugin value.

4. Configure the display of the button cell for the Interface Builder Library panel

Open the ButtonPluginLibrary.nib. This file contains the "Library Object Template" view (an instance of IBLibraryObjectTemplate). You can find it in the "Library Objects" view at the top level.

Delete the library template that doesn't apply

The Library Object Template will contain a "Template" and an "Example" square. The "Template" version is for NSView subclasses but our CustomButtonCell needs to be embedded in another object (an NSButton) so we will use the "Example" square — so delete the "Template" square.

Set our custom class in the library template

If you click on the button in the "Example" square then click again, it will select the NSButtonCell inside the button (these clicks should be slower than a double-click, since a double-click will edit the text of the NSButton instead of selecting the NSButtonCell inside). With the NSButtonCell selected:

Type Command-6 to select the correct inspector panel.
Enter the custom class name in the "Class" field of the inspector — in our case, we need this to be CustomButtonCell.
Set the button cell class for the NSButton to the right of the "Example" box in the same way.

Select the Library Object Template (ButtonPluginLibrary.nib window -> Library Objects -> Library Object Template) and:

Type Command-1 to select the correct inspector panel.
Fill in the "Label", "Summary" and "Description" for your Library Object as you choose. I like to delete the Path and leave it blank but you can add a path if you want to categorize your custom classes.

5. Configure the Interface Builder Inspector panel

Back in the ButtonPlugin project again, open the ButtonPluginInspector.xib.

Set all the controls in the Inspector panel how we want them

I deleted everything in the "Inspector View" window except 1 label and the NSColorWell. I moved these controls to the top of the view and then made the view 35 pixels high.

Connect the controls so they act on our object

To make the color selector do something, I used bindings. Select the NSColorWell and:

Type Command-4 to select the correct inspector panel.
Under the "Value" subheading, bind to File's Owner (make sure the checkbox is selected too).
Set the Model Key Path to inspectedObjectsController.selection.buttonColor.

This binding needs one other change to work. Back in the ButtonPlugin project, open the CustomButtonCellIntegration.m file. Change the [[keyPaths objectForKey:IBAttributeKeyPaths... line to:

[[keyPaths objectForKey:IBAttributeKeyPaths]
    addObjectsFromArray:[NSArray arrayWithObjects:@"buttonColor", nil]];

This tells Interface Builder to track and monitor the buttonColor property on the CustomButtonCell class. It does not actually perform the value changing (the binding we established will change the value directly) but it will make certain that this value will be tracked for undos and can be edited correctly.

Using the IBPlugin

At this point, you can run the ButtonPlugin project and it will launch Interface Builder with the plugin visible. The only problem is that the plugin won't be visible if you launch Interface Builder in any other way.

Build Settings

The following steps will make the ButtonPlugin project build the ButtonPlugin.framework and ButtonPlugin.ibplugin and install it in your Library.

Double click the ButtonPlugin project item in the ButtonPlugin project Source Tree to edit the project settings. Select the "Build" tab, then choose "Configuration: All Configurations". Then make the following changes:

Set the "Deployment Location" checkbox to checked.
Set the "Installation Build Products Location" to "$(HOME)/Library/Frameworks".
Set the "Installation Directory" to "/".

Double-click the "ButtonPlugin" target in the Source Tree to edit that target's settings. Select the "Build" tab, then choose "Configuration: All Configurations". Then make the following change:

Set the "Installation Directory" to "/ButtonPlugin.framework/Resources.

And now it's installed

With these changes made, build and run the ButtonPlugin project and it will install the ButtonPlugin.framework in your ~/Library/Frameworks directory and load it in Interface Builder. From now until you remove the framework from your library, it will remain in Interface Builder and you can use it at any time.

I realize that this configures the app to install the "Debug" build in the user's library, over the top of the "Release" build (if the Release build is already built) but this is really just for local use, so I don't really care. If you do care, you might not want to apply these settings to all configurations. For me: this is faster to implement and easier to manage.

Integration with the original AppWithButton project

After setting up the Interface Builder plugin, instance of CustomButtonCell in your existing .xib and .nib files will not instantly update. You'll probably need to create new versions of the cell by dragging them out from the Library.

In this example, I have chosen to not link the original AppWithButton project with the ButtonPlugin.framework. This is because I don't want to distribute either the framework or the plugin — they are both for my purposes only.

If you wanted to link them, you could remove the CustomButtonCell.m and CustomButtonCell.h files from the original project and replace them with the ButtonPlugin.framework. According to the Xcode documentation, this arrangement would allow you to avoid installing the ButtonPlugin.framework in your ~/Library/Frameworks directory (Interface Builder would automatically find the plugin for any .nib or .xib file in the project). That's a nice idea but it has never worked for me, so I never bother.

Set a build dependency to keep ButtonPlugin up-to-date

Instead, I like to drag the ButtonPlugin.xcodeproj file into the AppWithButton Source Tree and edit the AppWithButton target, go to the "General" tab and add the ButtonPlugin.xcodeproj as a Direct Dependency.

The reason for this is that if I change the CustomButtonCell class and rebuild, it will automatically rebuild the Interface Builder plugin accordingly (you need to restart Interface Builder to see the changes).

The AppWithButton window in Interface Builder, adjusting the color of the button in real-time.

Conclusion

You can download the complete AppWithButton project zip file (including the ButtonPlugin project) (385kB).

It takes quite a few steps to set up an Interface Builder plugin. Fortunately, they're all simple, if a little menial.

Notice how little code was actually written though: bindings and Objective-C 2.0 properties make this whole process considerably easier — there is no actual code written to set the buttonColor (except in the NSCoder method implementations) since the bindings do it all for us.

Once you're practiced at making plugins in this way, the effort to create one may be justified, even just to tweak simple properties like this.

Do I know how to do this for Cocoa Touch classes for iPhone development? No. I imagine it's possible but you'd need to completely change the IBPlugin project from the template and I've never tried.

Verifying that a string contains an email address using NSPredicate

2009-06-23T05:33:00.001-07:00

To celebrate the official release of iPhone OS 3.0 this week, I will show you how to verify that an NSString contains a syntactically valid email address using NSPredicate — a class that joins the iPhone SDK 3.0 as part of the Core Data additions. This code will work on Mac OS X too since, as with the rest of Core Data, NSPredicate has been part of Mac OS X since 10.4 (Tiger).

Before I begin...

I gave an interview to Anthony Agius of MacTalk.com.au this week. You can download the MP3 from their website. I'm hesitant to listen to my own voice but I think I talked about what it's like to be an independent Mac/iPhone developer in Melbourne, Australia.

Back to predicates

In programming, a predicate is a condition that returns true or false if the object it processes has the properties that the predicate describes. The key difference between a predicate and a regular boolean expression is that a predicate only considers the properties of one object, where a boolean expression may consider multiple, unrelated objects.

Many programmers are familiar with predicates as used in SQL database queries. For example a query to extract the complete row from the "people" database table for every person named "John Smith" might look like this in SQL:

SELECT * FROM people WHERE firstname = 'John' AND lastname = 'Smith'

Everything after the "WHERE" is the predicate — it looks at properties of the row only and is either true (the row will be extracted) or false (the row will be ignored).

Using NSPredicate to evaluate predicates

In Cocoa, NSPredicate works in much the same way as the "WHERE" clause of SQL. The main reason that NSPredicate is being brought to the iPhone is that NSPredicate fulfils the same role in Core Data that "WHERE" clauses fulfil in SQL — to allow the persistent store to fetch objects that satisfy specific criteria.

Imagine we had an NSDictionary created using the following method:

- (NSDictionary *)personRowWithFirstname:(NSString *)aFirstname
    lastname:(NSString *)aLastname
{
    return
        [NSDictionary dictionaryWithObjectsAndKeys:
            aFirstname, @"firstname",
            aLastname, @"lastname",
        nil];
}

we could test if a given row created by this method matched the predicate "firstname = 'John' AND lastname = 'Smith'" with the following:

// given an NSDictionary created used the above method named "row"...
NSPredicate *johnSmithPredicate =
    [NSPredicate predicateWithFormat:@"firstname = 'John' AND lastname = 'Smith'"];
BOOL rowMatchesPredicate = [johnSmithPredicate evaluateWithObject:row];

The string format used to construct an NSPredicate in Cocoa is very similar to the syntax of the "WHERE" clause in SQL. You can also construct this NSPredicate in code by building it from two NSComparisonPredicates and an NSCompoundPredicate.

A more common use of NSPredicate is filtering — extracting rows that match an NSPredicate from a larger collection:

// given an NSArray of rows named "rows" and the above "johnSmithPredicate"...
NSArray *rowsMatchingPredicate = [rows filteredArrayUsingPredicate:johnSmithPredicate];

This is then more like an SQL query where we have selected matching rows from the larger table of data.

Note: NSPredicate handles filtering only. If you'd like to replicate SQL's "ORDER BY" clause, you can apply NSSortDescriptor as a separate step.

Verifying an email address

The "LIKE" comparison operator in NSPredicate (NSLikePredicateOperatorType) is commonly used as a convenient means of testing if an NSString matches a Regular Expression. It's advantage over full libraries with greater options and replacement capability is that it is already in Cocoa — no libraries, no linkage, no hassle.

To test if an NSString matches a regular expression, we can use the following code:

NSPredicate *regExPredicate =
    [NSPredicate predicateWithFormat:@"SELF MATCHES %@", regularExpressionString];
BOOL myStringMatchesRegEx = [regExPredicate evaluateWithObject:myString];

The only question that remains is: what is a regular expression that can be used to verify that an NSString contains a syntactically valid email address?

NSString *emailRegEx =
    @"(?:[a-z0-9!#$%\\&'*+/=?\\^_`{|}~-]+(?:\\.[a-z0-9!#$%\\&'*+/=?\\^_`{|}"
    @"~-]+)*|\"(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21\\x23-\\x5b\\x5d-\\"
    @"x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])*\")@(?:(?:[a-z0-9](?:[a-"
    @"z0-9-]*[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\\[(?:(?:25[0-5"
    @"]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-"
    @"9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21"
    @"-\\x5a\\x53-\\x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])+)\\])";

This regular expression is adapted from a version at regular-expressions.info and is a complete verification of RFC 2822.

This adaptation involved escaping all backslashes with another backslash (otherwise the NSString will try to interpret them before they are used in the Regular Expression) and escaping the ampersands (&) so it isn't interpreted as a Unicode escape sequence and caret (^) characters because — actually I have no idea why except that the expression wouldn't parse without it.

The linked regular-expressions.info page recommends using slightly different regular expressions that force the top-level domain to be a country code or a known top-level domain. With the number of top-level domains due to increase in the near future, I'm not sure this is a good constraint to impose — since this check isn't intended to verify that the provided domain name is valid.

Since this regular expression NSString is so long, I've split it over 7 lines. This is an underused feature in Standard C languages — if you split a string into pieces but put nothing except whitespace between the pieces, the compiler will treat it as one continuous string. You don't need to write an extremely long string on a single long line.

Conclusion

Just a few lines of code this week but I thought it would be good to draw attention to one of the minor additions making its way to the iPhone in SDK 3.0. I use NSPredicate all the time on Mac OS to perform searches, extract subarrays and perform quick Regular Expression tests. Without it, the only alternatives on the iPhone were methodical array iterations and manual comparisons in code.

Revisiting an old post: Streaming and playing an MP3 stream

2009-06-17T00:39:00.001-07:00

Given the attention it received and the number of bugs I know it contained, I wanted to revisit an old post of mine: Streaming and playing an MP3 stream. In this post, I'll talk about the problems the original contained, how I fixed those problems and I'll present the updated result.

Introduction

Last September, I wrote a post titled "Streaming and playing an MP3 stream". The post was largely an experiment — I just wanted to see if I could play a streaming MP3 by quickly adapting Apple's AudioFileStreamExample to accept an HTTP data stream.

Unexpectedly, the post became one of my most popular. The attention quickly revealed the limitations in my approach:

The blend of Objective-C and C was muddled and led to a situation where neither were being used cleanly.
The boolean flags I copied from the original example were a bad way to describe the playback state and lots of situations were not covered by these flags.
Sending notifications to the user-interface on a thread that isn't the main thread causes problems.
The extra thread I added (the download thread) was never thread-safe.

I've finally decided to take the time to present a solution to these issues and present an approach which is a little more robust and a little easier to extend if needed.

You can download the complete AudioStreamer project as a zip file (around 110kB) which contains Xcode projects for both iPhone and Mac OS. You can also browse the source code repository.

Limited scope

One point should be clarified before I continue: this class is intended for streaming audio. By streaming, I don't simply mean "an audio file transferred over HTTP". Instead, I mean a continuous HTTP source without an end that continues indefinitely (like a radio station, not a single song).

Yes, this class will handle fixed-length files transferred over HTTP but it is not ideal for the task.

This class does not handle:

Buffering of data to a file
Seeking within downloaded data
Feedback about the total length of the file
Parsing of ID3 metadata

These things often can't be done on streaming data, so this class doesn't try. See the "Adding other functionality" section for hints about how the class could be reorganised to handle some of these features.

Taking code out of C functions

Since I had borrowed the AudioFileStream and AudioQueue callback functions from Apple's example, they were Standard C.

My first change was to make these 6 callback functions (7 including the CFReadStream callback) little more than wrappers around Objective-C methods:

void MyPacketsProc(
    void *inClientData,
    UInt32 inNumberBytes,
    UInt32 inNumberPackets,
    const void *inInputData,
    AudioStreamPacketDescription *inPacketDescriptions)
{
    // this is called by audio file stream when it finds packets of audio
    AudioStreamer* streamer = (AudioStreamer *)inClientData;
    [streamer
        handleAudioPackets:inInputData
        numberBytes:inNumberBytes
        numberPackets:inNumberPackets
        packetDescriptions:inPacketDescriptions];
}

At a compiled code level, this is a step backwards: all I've done is slowed the program down by an extra Objective-C message send.

Technically, a C function that takes a "context" pointer (like the inClientData pointer here) is not significantly different to a method. What a method does is makes data hiding and data abstracted actions easier. Within a method, you can easily access the instance variables of an object and you don't need to explicitly pass context into each function.

This is the cliché argument in favor of object-orientation — but it isn't why I reorganized these functions and methods.

The honest reason why I did it is aesthetics: it is easier to read a class that is implemented using Objective-C methods alone — it's more consistent. I chose to move towards an Objective-C aesthetic and away from the Standard C aesthetic of the CoreAudio sample code to promote consistent formatting, consistent means of accessing state variables, consistent ways of invoking methods and consistent ways of synchronizing access to the class.

Describing state

With the majority of code now inside the class, I was in a better position to start handling changes through methods rather than direct member access.

My original approach to state came from Apple's original example. This example had just one piece of state: a bool named finished (which indicated that the run loop should exit).

The problem with this flag is how simple it is. It is unable to distinguish between the following:

End of file, normal automatic stop.
The user has asked the AudioStreamer to stop but the AudioQueue thread has not yet responded.
An error has occurred before the AudioQueue thread is created and we must exit.
We are stopping the AudioQueue for temporary reasons (clearing it, changing device, seeking to a new point) but we don't want the loop to stop.

For Apple's example, there was no problem: the first case was the only one that ever occurred.

As a hasty solution, I had added started and failed flags but these really only covered the first and third case adequately.

In the end, I realized that the AudioStreamer needed much more descriptive state where every combination of progress within each thread had a different position:

typedef enum
{
    AS_INITIALIZED = 0,
    AS_STARTING_FILE_THREAD,
    AS_WAITING_FOR_DATA,
    AS_WAITING_FOR_QUEUE_TO_START,
    AS_PLAYING,
    AS_BUFFERING,
    AS_STOPPING,
    AS_STOPPED,
    AS_PAUSED
} AudioStreamerState;

and when stopping, one of the following values would also be needed:

typedef enum
{
    AS_NO_STOP = 0,
    AS_STOPPING_EOF,
    AS_STOPPING_USER_ACTION,
    AS_STOPPING_ERROR,
    AS_STOPPING_TEMPORARILY
} AudioStreamerStopReason;

In this way, the state always describes where every thread is and the stop reason explains why a transition is occurring.

Combining this with an error code that replaces the old failed flag, I now have a complete desription of the state.

By cleaning up the state of the object, I was able to make the object capable of state transitions that weren't previously possible including pausing/unpausing and returning to the AS_INITIALIZED state after a stop (instead of requiring that the class be released after stopping).

Notifications

In the old version of the project the only way for the user-interface to follow the playback state was to observe the isPlaying property on the object which reflected the kAudioQueueProperty_IsRunning property of the AudioQueue.

This observing was handled through KeyValueObserving. I'm a big fan of KeyValueObserving for its simplicity and ubiquity but this was not the correct place to use it.

KeyValueObserving always invokes the observer methods in the same thread as the change. Since all changes in AudioStreamer happen in secondary threads, this means that the observer methods were getting invoked in secondary threads.

Why is this bad? A minor drawback is simply the unexpectedness for the observer but the biggest reason was that the sole purpose of observing this property was to update the user-interface and the user-interface on the iPhone cannot be updated from any thread except the main thread. Even on the Mac, performing updates off the main thread can have unexpected and glitchy results.

The solution is to retain the NSNotificationCenter of the thread that first calls start on the object and use this center to send messages as follows:

NSNotification *notification =
    [NSNotification
        notificationWithName:ASStatusChangedNotification
        object:self];
[notificationCenter
    performSelector:@selector(postNotification:)
    onThread:[NSThread mainThread]
    withObject:notification
    waitUntilDone:NO];

Don't invoke postNotification: directly from the secondary thread as, like most methods, it is not thread safe and it could be in use from the main thread.

Thread safety

Despite adding an extra thread on top of Apple's AudioFileStreamExample, I never really spent any time thinking about thread safety — a reckless approach to stability. In my defence Apple's example wasn't exactly cautious with its threads and would quit while the AudioQueue's thread was still playing the last buffer.

The most efficient approach to threading is to carefully enter @synchronized (or NSLock or pthread_mutex_lock) in a tight region around any use of a shared variable.

Unfortunately for the AudioStreamer class, almost everything in the class is shared. Instead, I decided to go for the decidedly less efficient approach of running almost everything in the class within a @synchronized section, emerging only at points when control must be yielded to other threads.

The drawback is that the code rarely runs simultaneously on multiple threads (although threading here is for blocking and I/O, not for multi-threaded performance reasons so that's not a probem). The advantage with this heavy-handed locking approach is that the only threading condition that may cause problems are deadlocks.

When do deadlocks occurs? Only when you're waiting for another thread to do something while you're inside the synchronized section needed by that other thread. The simple solution: never wait for another thread inside a synchronized section.

AudioStreamer has three situations where 1 thread waits for another:

The run loop (the AudioFileStream thread waits for any kind of control communication from the main thread or playback finished notification from the AudioQueue thread).
The enqueueBuffer method (AudioFileStream thread waits for the AudioQueue thread to free up a buffer).
Synchronous AudioQueueStop invocations (waits for the AudioQueue to release all buffers).

The first two points are easy: perform these actions (any any method invocation which invokes them) outside of the @synchronized section.

The final point is harder: the synchronous stop must be performed inside the @synchronized section to prevent multiple AudioQueueStop actions occurring at once. To address this, the release of buffers by the AudioQueue (in handleBufferCompleteForQueue:buffer:) must perform its work without entering the @synchronized section (although it's allowed to use the queueBuffersMutex as normal since that isn't used by anything else during a synchronous stop).

Of course, every time the @sychronized section is re-entered, a check must be performed to see if "control communication" has occurred (the class checks this by invoking the isFinishing method and exiting if it returns YES).

Adding other functionality

Get metadata

The easiest source of metadata comes from the HTTP headers. Inside the handleReadFromStream:eventType: method, use CFReadStreamCopyProperty to copy the kCFStreamPropertyHTTPResponseHeader property from the CFReadStreamRef, then you can use CFHTTPMessageCopyAllHeaderFields to copy the header fields out of the response. For many streaming audio servers, the stream name is one of these fields.

The considerably harder source of metadata are the ID3 tags. ID3v1 is always at the end of the file (so is useless when streaming). ID3v2 is located at the start so may be more accessible.

I've never read the ID3 tags but I suspect that if you cache the first few hundred kilobytes of the file somewhere as it loads, open that cache with AudioFileOpenWithCallbacks and then read the kAudioFilePropertyID3Tag with AudioFileGetProperty you may be able to read the ID3 data (if it exists). Like I said though: I've never actually done this so I don't know for certain that it would work.

Stream fixed-length files

The biggest variation you may want to make to the class is to download fixed-length files, rather than streaming audio.

To handle this, the best approach is to remove the download from the class entirely. Download elsewhere and when "enough" (an amount you should determine on your own) of the file is downloaded, start a variation of the class that plays by streaming from a file on disk.

To adapt the class for streaming from a file on disk, remove the CFHTTPMessageRef and CFReadStreamRef code from openFileStream and replace it with NSFileHandle code that uses waitForDataInBackgroundAndNotify to asynchronously stream the file in the same way that CFReadStreamRef streamed the network data.

Once you're streaming from a file, you'll probably want to permit seeking within the file. I've already put hooks within the file to seek (set the seekNeeded flag to true and set the seekTime to the time in seconds to which you want to seek) — however, the mechanics of seeking within the file would be dependent on how you access the file.

Incidentally, the AudioFileStreamSeek function seems completely broken. If you can't get it to work (as I couldn't) just seek to a new point in the file, set discontinuous to true and let AudioFileStream deal with it.

Handling data interruptions

At the moment, if the AudioQueue has no more buffers to play, the state will transition to AS_BUFFERING. At this point, no specific action is taken to resolve this situation — it assumes that the network will eventually resume and requeue enough buffers.

I actually expect there will be cases where this action is insufficient — you may need to ensure that the AudioQueue is paused until enough buffers are filled before resuming or even restart the download entirely. I haven't experimented much since it is easiest with streaming audio just to stop and start new.

Incidentally, if you're curious to know how many audio buffers are in use at any given time, uncomment the NSLog line in the handleBufferCompleteForQueue:buffer: method. This will log how many 1 kilobyte audio buffers are queued waiting for playback (when the queue reaches zero, the AudioStreamer enters the AS_BUFFERING state).

Conclusion

You can download the complete AudioStreamer project as a zip file (around 110kB) which contains Xcode projects for both iPhone and Mac OS. You can also browse the source code repository.

The functionality of this new version has not changed greatly — my purposed was to present a version that is more stable and tolerant of unexpected situations, rather than add new features.

As before, the AudioStreamer class should work on Mac OS X 10.5 and on the iPhone (SDK 2.0 and greater).

The source repository is hosted on github so you can browse, fork or track updates as you choose. I will likely update again in future (I can't imagine I've written this much code without causing more problems) and this way, you can see the changes I've made.

I hope this post has shown you a number of problems that can happen when code is written hastily. This doesn't mean you should always avoid hastily written code (timeliness and proof of concepts are important) but it does mean you should be practised at refactoring code and not simply slap poor fixes onto code that doesn't cleanly solve a problem in the first place.

Method names in Objective-C

2009-06-10T03:32:00.001-07:00

Compared to other languages, method names in Objective-C are weird. They're long, they're wordy, they include names for the parameters and they seem to repeat information you can get elsewhere. Despite these apparent negatives, Objective-C method naming can save you time and effort. I'll show you how methods are named so that you can predict them without documentation and understand how methods work and how they use their parameters from their names alone.

Introduction: Objective-C is an ugly duckling

Along with square-brackets and its largely Apple-exclusive nature, method names are one of the most commonly decried parts of Objective-C. I've seen them criticized for being:

Long and wordy
Repetitious or redundant
Filled with names for each parameter
Camel-case

While every one of these points is true, none of them is really a negative — although camel-case is a subjective, aesthetic point and I'll ignore it since I'll only consider the structural aspects of method naming conventions in this post.

Objective-C methods names are some of the most predictable, regular, self-descriptive methods in any C-derivative language — and it is these points that allow it to be so. Of course, these benefits are lost unless you know the conventions well enough to understand and predict them.

Background: naming conventions in other C-like languages

To help you understand the reasoning behind Objective-C's method names, I'll start by describing how methods and functions are named in C. I'm starting with C because Objective-C's method naming is, in some respects, an extension of C's naming style, adapted to overcome the limitations.

Standard C's naming style

Yes, Standard C does have some implicit naming conventions. Many standard C functions are composed of three parts:

An indication of the data type acted upon
The action
A description of the secondary object

We can see examples of these in these functions:

sscanf - "s" (acts upon a char *), "scan" (extract character data from the string), "f" (format string is the secondary object)
fprintf - "f" (acts upon a FILE), "print" (outputs character data to the file), "f" (format string is the secondary object)
strlen - "str" (acts upon a char *), "len" (compute the length). No secondary object.
fesetround - "fe" (acts upon the "floating point environment"), "set" (changes a state value), "round" (a new rounding value is the secondary object).

Standard C's naming style fails

For these methods, this style works well. The problem is that components are so short (often single letters) that it is difficult to know for certain to what they refer. Many of the methods in math.h show these limitations:

lround - "l" (no longer an "acts upon", this first part now indicates "returns a long"), "round" (round to the nearest integer). No description of the primary parameter — you are expected to assume a double.
acosl - The "l" in this case is the primary parameter and means long double whereas it meant long in the lround method above. The "a" here is not a prefix, it is part of the action component.

This is where naming styles in C break down — while math.h does have naming conventions, they are all its own. You can learn the tricks of math.h but they are unique to that library, not a standard that applies to all functions.

Beyond these issues C, suffers from a broader lack of adherence to any convention, let alone a consistent one. Most functions are really just a 4 to 6 character description of the action performed. While this may be all that is required at a technical level, it makes it almost impossible to know how to use functions like system, raise, atexit or even malloc for the first time without reading the documentation.

Other languages

Few other languages have a distinct approach to method structure. The overriding convention in the main languages I use (C++, C#, Java) is simply a short verb plus possible modifier.

Some languages do have their own aesthetics (for example, the C++ Standard Library uses terse underscore delimited words) but this doesn't represent a structural convention.

The reason why these languages have abandoned the three part style of Standard C functions is that:

The data type acted upon is now the object upon which the method is invoked, removing the need to explain this part.
Parameter overloading means that a description of any parameter needs to be vague (since the parameter itself may be used inconsistently).

So methods end up being little more than a verb plus an optional modifier term.

The result is that methods with subtle actions or that use their parameters in specific ways can only be used by thoroughly examining the documentation.

Method naming conventions in Objective-C

Objective-C aims to be substantially more self-documenting than its peers. The intent is that all methods in all classes should be able to follow the same set of rules so that subtleties of behavior are easy to see and understand — even when you are new to the class.

This aim combines with the named parameters in Objective-C to produce methods which are quite distinct compared to other languages.

Given the lack of convention in other languages and the unusual nature of Objective-C's named parameters, it's no so surprising that method names in Objective-C are confronting to new Objective-C programmers.

Structure of an Objective-C method name

Objective-C methods are composed of a few different components. I'll list the components here, examples follow:

If there is a return value, the method should begin with the property name of the return value (for accessor methods), or the class of the return value (for factory methods).
A verb describing either an action that changes the state of the receiver or a secondary action the receiver may take. Methods that don't result in a change of state to the receiver often omit this part.
A noun if the first verb acts on a direct object (for example a property of the receiver) and that property is not explicit in the name of the first parameter.
If the primary parameter is an indirect object to the main verb of the method, then a preposition (i.e. "by", "with", "from") is used. This preposition partly serves to indicate the manner in which the parameter is used but mostly serves to make the sentence more legible.
If a preposition was used and the first verb doesn't apply to the primary parameter or isn't present then another verb describing direct action involving the primary parameter may be used.
A noun description (often a class or class-like noun) of the primary parameter, if this is not explicit in one of the verbs.
Subsequent parameter names are noun descriptions of those parameters. Prepositions, conjunctions or secondary verbs may precede the name of a subsequent parameter but only where the subsequent parameter is of critical importance to the method. These extra terms are a way to highlight importance of secondary parameters. In some rarer cases secondary parameter names may be a preposition without a noun to indicate a source or destination.

In addition, an Objective-C method should be maximally readable — its reading should flow like a sentence and abbreviations should be avoided except where they are universally known (and even then, abbreviations to syllables rather than single letters are preferred).

That's a lot to consider. Fortunately, most components are only relevant to specific kinds of method.

Applying the naming convention to property accessors

length

This method is shows the typical form of a getter method for a property or calculated value. Only the first component of the method name applies.

The biggest point to note with respect to other languages is that getter methods don't use the verb "get" because no explicit action or state change is required to extract this property (implicit actions or actions taken for internal reasons should not be communicated through the method name).

encodedLength

This method shows a variant length method where a modifier is used to describe the length. We put the modifier before the property name because a structure like lengthWhenEncoded gets too close to lengthForEncoding: which would be used if the encoding was passed in as a parameter.

sharedApplication

Singleton accessors (like this accessor for the global UIApplication object) and other global data accessors take exactly the form as instance accessors. A description of the return value ("Application" in this case) plus an adjective to disambiguate it (in this case, disambiguation is required because a class name on its own is expected to be a factory method — see below). The term "shared" is used by convention to identify singletons.

doubleValue

This method has the same structure as the previous method but shows how the returned class is sometimes the modifier when used in conjunction with an abstract property like "value".

isEditable

This method is actually an exception to the conventional rules. The verb "is" shouldn't be there — verbs are normally reserved for describing state change or secondary action.

I guess that this style for accessors that return a BOOL developed to make the method read more like a sentence. You could also argue that "is" is a passive verb so it isn't indicating an action.

setLength:

The setter method is not composed in the same way as the getter. With no return value, the first part is a verb describing the action: "set".

The second part, "Length" may be considered to the direct object of the verb component (i.e. the internal property). In this case, it is also the name of the first parameter. Since they communicate the same information, only one is used.

Setter methods with prepositions before the first parameter like setValueUsingDouble: and setValueUsingNumber: are rarely used, even though they may seem like a good way to unambiguously set a property like "value" using different data types. Instead, the property itself is normally give a different name (i.e. setDoubleValue: or setNumberValue:). In this way, there is only ever one setter for a given property (although properties may contain dependencies).

Applying the naming convention to factory methods

string

This NSString method returns an empty string. It takes exactly the same format as a getter method, except that you invoke it on a class object, not an instance and it doesn't include a property name.

It may seem like this method is providing redundant information — we already know that a factory method for a class will return an instance of the same class — but identifying the return type here has two purposes:

factory method are identified precisely because they start with the class' name
it maintains consistency (always describe the return value when it is the purpose of the method)

A quick follow up to that second point though: the return value only needs to be described when it is the purpose of the method. BOOL values returned as an error indicator and other cases where the return value is a secondary effect (like autorelease which returns the receiver) do not need to describe the return value.

stringWithString:

The parameter here is named "String", indicating that it is an instance of NSString with no other constraints. The correct way to read this method is that it creates a new string in the simplest way possible from its string parameter — i.e. a copy of the string.

The preposition here is of little semantic purpose except to make the method name read like a sentence. The choice of preposition is simply: whatever is most appropriate if you read it like a sentence. For this reason class factory methods normally use "With" but instance factory methods normally use "By" because it implies some involvement of the receivers data (like stringByAppendingString:).

The NSArray method isEqualToArray shows a state interrogation with a preposition but again, the preposition is chosen simply to make the method name read like a sentence.

Applying the naming convention to action methods

release

This is an example of a simple action method: a verb describing how the method changes state or performs secondary actions.

addObject:

Again, a very simple method: verb plus a noun describing the first parameter (any "Object").

addObserver:forKeyPath:options:context:

The important addition to see here is the use of the preposition "for" in front of the second parameter. Yes, "KeyPath" is the indirect object of the method's verb "add" but the real purpose here is to highlight the importance of this parameter — pointing out that this parameter is more important than parameters which follow.

To explain this, consider that the method is not addObject:forKeyPath:usingOptions:andContext: — the options and context are really peripheral parameters whereas keyPath is an important consideration, despite being the second parameter.

This method can be compared to the very similar NSNotificationCenter method addObserver:selector:name:object:. In the case of the NSNotificationCenter method, name: is the corresponding parameter to forKeyPath: and yet no preposition is used (it is not forName:). This reflects the fact that the name parameter is optional (can be nil).

However you should not infer that lack of preposition means "optional" — far from it. Instead, the correct meaning is preposition means more important than other secondary parameters. The selector: parameter of the addObserver:selector:name:object: method is mandatory but is given no special status in the method. It is necessary for routing the notification but much of the time will simply reflect the notifications it observes (i.e. @selector(windowWillCloseNotification:)).

A small exception: delegate methods

windowDidChangeScreen:

This method begins with the name of a class but it is not a factory method nor a method which returns a mutated version of the receiver. It is actually a delegate method and delegate methods don't really follow any of the conventions.

If it were following the conventional standard its name would be receiveWindowDidChangeScreenNotification:. You could argue that delegate methods are passive — the delegate isn't being asked to perform an action, it is being told that something else performed an action — so omitting a verb is permissible. For my part, the break with convention makes me sad inside.

Further confusing things, the first parameter of the delegate method is rarely identified by the closest noun. Instead the first parameter is either the object sending the notification or it is a notification object (which will contain the sender). In the example above, the closest noun is "screen" but the first parameter is an NSNotification. In the case of applicationOpenUntitledFile: the closest noun is "File" but the parameter is the NSApplication object that sent the message.

Summary

In describing method formats, I've repeated myself quite a few times. The reality is that Objective-C uses one method naming convention almost everywhere.

Objective-C method names are very regular. So regular that you should be able to predict the names for methods without checking the documentation — start typing the method name as you guess it, then autocomplete. More than simply predicting the name, you can normally predict how parameters are used, so again you avoid documentation and know what you need.

Looking at the criticisms levelled at Objective-C method names that I listed at the start:

Long and wordy

Yes, Objective-C methods are made to read like sentences. They contain prepositions (something almost never seen in other languages), they contain type of the return parameter, they use full words instead of abbreviations.

The purpose is to make the method as quick to read as possible.

This is a good trade to make since you will read a method many times but only type it once (with code completion, less than once).

Xcode will suggest code completion automatically. Hit return at any time to pick the completion it offers. Hit the Code Sense Completion key (F5 by default) and it will present a popup list of matching options. Control-/ will step through the parameters so you can fill them in.

Repetitious or redundant

While methods like +[UIApplication sharedApplication] may seem redundant, the reality is that +[UIApplication shared] would have a different meaning (it would be an accessor for the static class property named "shared") and +[UIApplication singleton] by omitting a class name fails to communicate that the method also works as a factory method on the first invocation — repeating the class name has meaning, it is not redundant.

Filled with names for each parameter

Yes they are but these names makes it much easier to determine what each parameter is and allows metadata like importance to be conveyed.

Camel-case

Yes. The choice over underscore delimited words is largely aesthetic. Although the choice over Pascal-case (same as camel-case but where the first letter of the first word is uppercase not lowercase) is because uppercase initial letters are reserved for names with global scope — like class names, function names and global constants.

Conclusion

Few other languages have conventions that are as rigourously applied as those in Objective-C. Conventions are annoying to learn — as they may seem arbitrary and unnecessary at first glance — but once learned, they are regular and predictable with few surprises. When trying to get the computer to obey, that's good.

Base64 encoding options on the Mac and iPhone

2009-06-03T15:35:00.001-07:00

On Unix platforms, a common approach for Base64 encoding is to use libcrypto (the OpenSSL library). However, like most C libraries, you need to wrap it to integrate with Objective-C data types (like NSData and NSString) and it isn't available on the iPhone. I'll show you how to handle base64 encoding/decoding with OpenSSL and without so you can handle the Mac and iPhone equally.

Introduction

Base64 is an encoding for transferring binary data in 7-bit text. Originally used in email, it is also used for binary encoding data in HTML files. Another common use for Base64 is in HTTP Basic Access Authentication where it is used to transfer login details (which might not be printable characters).

The key library for handling Base64 on the Mac is normally libcrypto (the OpenSSL library), so it's a little disappointing that libcrypto isn't available on the iPhone.

Using OpenSSL

Via the command line

On the Mac, you can handle simple encoding tasks like base64 encoding with OpenSSL on the command line:

echo "Base64 encode this text." | openssl enc -base64

gives the encoding result:

QmFzZTY0IGVuY29kZSB0aGlzIHRleHQuCg==

The reverse is handled in the following manner:

echo "QmFzZTY0IGVuY29kZSB0aGlzIHRleHQuCg==" | openssl enc -d -base64

giving

Base64 encode this text.

In code

As you'd expect, doing the same work in code takes a little more typing. First, we're using a library, so we need to include it (in your Project's Build Settings under Other Linker Flags add the flag -lcrypto). Once that's done, you should be able to use the following method in a category on NSData:

#include <openssl/bio.h>
#include <openssl/evp.h>

- (NSString *)base64EncodedString
{
    // Construct an OpenSSL context
    BIO *context = BIO_new(BIO_s_mem());

    // Tell the context to encode base64
    BIO *command = BIO_new(BIO_f_base64());
    context = BIO_push(command, context);

    // Encode all the data
    BIO_write(context, [self bytes], [self length]);
    BIO_flush(context);

    // Get the data out of the context
    char *outputBuffer;
    long outputLength = BIO_get_mem_data(context, &outputBuffer);
    NSString *encodedString = [NSString
        stringWithCString:outputBuffer
        length:outputLength];

    BIO_free_all(context);

    return encodedString;
}

To handle a Base64 encode.

By default, encodedString will have newlines every 64 characters. If needed, you can disable the inclusion of newlines by adding the following line before the BIO_write:

BIO_set_flags(context, BIO_FLAGS_BASE64_NO_NL);

Tthe "BIO" system (I think it stands for buffered I/O) is not very symmetric so the code for decoding is quite different:

+ (NSData *)dataByDase64DecodingString:(NSString *)decode
{
    decode = [decode stringByAppendingString:@"\n"];
    NSData *data = [decode dataUsingEncoding:NSASCIIStringEncoding];
    
    // Construct an OpenSSL context
    BIO *command = BIO_new(BIO_f_base64());
    BIO *context = BIO_new_mem_buf((void *)[data bytes], [data length]);
        
    // Tell the context to encode base64
    context = BIO_push(command, context);

    // Encode all the data
    NSMutableData *outputData = [NSMutableData alloc];
    
    #define BUFFSIZE 256
    int len;
    char inbuf[BUFFSIZE];
    while ((len = BIO_read(context, inbuf, BUFFSIZE)) > 0)
    {
        [outputData appendBytes:inbuf length:len];
    }

    BIO_free_all(context);
    [data self]; // extend GC lifetime of data to here

    return outputData;
}

An interesting point to note at the top of this function: I add an extra newline to the start of the string. This is because if you have not disabled newlines and the string does not contain at least 1 newline, BIO_read will fail.

Handling Base64 on the iPhone

Using libcrypto isn't possible by default on the iPhone — the library isn't there. You could probably build libcrypto.a and link it statically against your app but that can be difficult to set up and would require that you notify Apple that your app contains encryption.

Normally, it is better to avoid libcrypto on the iPhone. The other functions that libcrypto handles can be found elsewhere:

md5 — use the CommonCrypto implementation CC_MD5
sha — use the CommonCrypto implementation CC_SHA
Public/Private Key Encryption/Decryption — use the SecKeyEncrypt/SecKeyDecrypt functions in the Security framework

You can find the documentation for the Security Framework by performing a standard Xcode API lookup. For some reason though, the CommonCrypto functions only appear in a full-text search.

The Base64 functionality of OpenSSL doesn't have an accessible equivalent on the iPhone, even though NSURLConnection, CFHTTPMessageRef and WebKit must all have access to an implementation — whatever they use is not accessible.

Encoding Base64

Fortunately, Base64 is a fairly simple encoding. At its heart, it looks like this:

static unsigned char base64EncodeLookup[65] =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";

//
// Inner loop: turn 3 bytes into 4 base64 characters
//
outputBuffer[j++] = base64EncodeLookup[(inputBuffer[i] & 0xFC) >> 2];
outputBuffer[j++] = base64EncodeLookup[((inputBuffer[i] & 0x03) << 4)
    | ((inputBuffer[i + 1] & 0xF0) >> 4)];
outputBuffer[j++] = base64EncodeLookup[((inputBuffer[i + 1] & 0x0F) << 2)
    | ((inputBuffer[i + 2] & 0xC0) >> 6)];
outputBuffer[j++] = base64EncodeLookup[inputBuffer[i + 2] & 0x3F];

This might be a little ugly to look at if you're not use to seeing bitmasks and bitshifts but it is only a couple lines. It does little more than the comment states: it turns 3 bytes into 4 chars, with the specific chars specified by the base64EncodeLookup mapping.

Of course, while this code handles the center of the main loop, there's almost a hundred lines total in the complete implementation that I wrote.

As part of keeping the function optimal, I wanted to keep the conditionals out of the inner loop (making vectorizing easier). I succeeded and there are no conditionals in the inner loop but this means that there are a few tail conditions to handle in the epilogue.

I also wanted to calculate the exact size that would be required for the output buffer, so it can be allocated once with no waste, but this too occupies a few lines worth of space.

Decoding Base64

Decoding works similarly to encoding, except that in decoding we are reducing 4 characters down to 3 bytes instead of vice versa:

//
// Store the 6 bits from each of the 4 characters as 3 bytes
//
outputBuffer[j] = (accumulated[0] << 2) | (accumulated[1] >> 4);
outputBuffer[j + 1] = (accumulated[1] << 4) | (accumulated[2] >> 2);
outputBuffer[j + 2] = (accumulated[2] << 6) | accumulated[3];

More interesting than the code in this case is the lookup table that each of these accumulated bytes passes through before being used here:

//
// Definition for "masked-out" areas of the base64DecodeLookup mapping
//
#define xx 65

//
// Mapping from ASCII character to 6 bit pattern.
//
static unsigned char base64DecodeLookup[256] =
{
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 62, xx, xx, xx, 63, 
    52, 53, 54, 55, 56, 57, 58, 59, 60, 61, xx, xx, xx, xx, xx, xx, 
    xx,  0,  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, xx, xx, xx, xx, xx, 
    xx, 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, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
    xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, 
};

The "xx"s in this table are just a #define of 65 (i.e. outside the valid range of Base64) but they provide an interesting visual representation of the 6-bits that each Base64 character can occupy within the 8-bit byte.

I was unable to remove all of the conditionals from the inner loop of the decode side and keep the "skip over invalid characters" requirement.

This "skip over invalid characters" stage (where characters are accumulated until 4 valid characters are found) is handled by the following loop (which immediately preceeds the previous "store the 6 bits from each of the 4 characters as 3 bytes" code):

//
// Accumulate 4 valid characters (ignore everything else)
//
unsigned char accumulated[BASE64_UNIT_SIZE];
size_t accumulateIndex = 0;
while (i < length)
{
    unsigned char decode = base64DecodeLookup[inputBuffer[i++]];
    if (decode != xx)
    {
        accumulated[accumulateIndex] = decode;
        accumulateIndex++;
        
        if (accumulateIndex == BASE64_UNIT_SIZE)
        {
            break;
        }
    }
}

This is the only part which makes the decode stage sub-optimal. If you had Base64 input data with no newlines and no other characters requiring skipping, I think you could remove this section entirely so that the inner loop of the decode function could be vectorizable.

Conclusion

Download the NSData+Base64 class and header (4kB).

In this post, I've shown you how to use the default command-line and library options for Base64 handling on Mac OS X. I've also shown you the approach I use for Base64 encoding and decoding on the iPhone.

The libcrypto libraries (when available) are not as tight and simple as custom code for the task but do have the advantage that the pipeline for feeding data into them is more configurable.

I'm certainly not the only one to present C libraries for Base64 encoding that will work on the iPhone but the approach I've used should be efficient (especially the internal implementations in the C-functions) and it should drop into a Cocoa project on the iPhone very easily.

Simple methods for date formatting and transcoding

2009-05-25T23:15:00.001-07:00

There is no single-line method for converting between formatting date strings and date objects in Cocoa — the API opts for flexibility rather than simplicity. Unfortunately, this combines with documentation that omits, misdirects and occasionally misinforms, making NSDateFormatter one of the more confusing classes for new Cocoa programmers. In this post, I'll try to address some of the documentation issues and I'll present some methods that will turn NSDate into a formatted string or convert between date strings in a single method.

Default, locale-based date formatting

Before I get into date formatting strings (which is the real purpose of this post) I will quickly show you how to get a string from an NSDate:

NSDate *date = [NSDate date];
NSDateFormatter *dateFormatter = [[[NSDateFormatter alloc] init] autorelease];
[dateFormatter setDateStyle:NSDateFormatterLongStyle];
NSString *dateString = [dateFormatter stringFromDate:date];

This code formats the string according to the user's preferences set in the International General Settings (iPhone) or System Preferences (Mac OS X).

Personally, I think this is verbose for such a common activity and normally use a category method on NSDate to reduce it:

@implementation NSDate (FormattedStrings)
- (NSString *)dateStringWithStyle:(NSDateFormatterStyle)style
{
    NSDateFormatter *dateFormatter = [[[NSDateFormatter alloc] init] autorelease];
    [dateFormatter setDateStyle:style];
    return [dateFormatter stringFromDate:self];
}
@end

This reduces the first code sample to:

 NSString *dateString = [[NSDate date] dateStringWithStyle:NSDateFormatterLongStyle];

If you need time strings instead of date strings, create a timeStringWithStyle: method by replacing the setDateStyle: invocation with setTimeStyle:.

I have read rants by other Objective-C programmers who hate seeing projects with hundreds of small categories for every little task.

Frankly, I've never understood the objection. In fact, I think lots of small categories used to choose the settings you prefer on top of common interfaces is essential for establishing consistent aesthetics for your program — your entire program will have the same style and you can easily update the aesthetic for the whole program by editing a single location.

An example would be to replace this dateStringWithStyle: method with a dateStringWithProjectStyle method that returns the appropriately configured string for use throughout your program. One of your projects might use NSDateFormatterLongStyle and the next might use a totally customized format (as I'll describe in the next sections) but you as a programmer can still invoke dateStringWithProjectStyle everywhere you need a string from an NSDate.

Date formatting documentation issues

At its heart, NSDateFormatter is very simple to use and yet it repeatedly baffles new users. I don't think this is really the fault of the API as much as the history behind it and the effect that it has had on the documentation.

Despite NSDateFormatterBehavior10_4 being the only date formatting you should ever use and the only style that should exist in the documentation, Apple's documentation has the following quirks:

The actual syntax for NSDateFormatterBehavior10_4 is never given in the documentation and you can easily miss the links to Unicode Standard (tr35) which describe it.
A majority of the pages in the date formatting documentation seem concerned with the old NSDateFormatterBehavior10_0 style formatter behavior even though this is functionally deprecated.
The documentation for defaultFormatterBehavior claims NSDateFormatterBehavior10_0 is the default style but it is actually NSDateFormatterBehavior10_4 in Leopard and iPhoneSDK2.0.

Then, if you've been skimming through the documentation getting confused by the different styles, you may overlook one line at the top of the NSDateFormatter API reference page:

iPhone OS Note: iPhone OS supports only the modern 10.4+ behavior. 10.0-style methods and format strings are not available on iPhone OS.

All that documentation in the iPhone SDK concerned with the old NSDateFormatterBehavior10_0 style is completely meaningless — you can't use NSDateFormatterBehavior10_0 at all on the iPhone.

Adding to the iPhone frustration, NSDateFormatterBehavior10_0 will work in the simulator, causing headaches when code suddenly stops working on the device.

On Mac OS X, even though you can use NSDateFormatterBehavior10_0, it is deprecated for all practical purposes so you probably shouldn't. Annoyingly, since the documentation still claims NSDateFormatterBehavior10_0 is the default, you should explicitly set the formatter behavior to NSDateFormatterBehavior10_4 to remain safe — at least until the documented default is updated to formally match the actual default.

I don't mean to be cruel to Apple — documentation is difficult, time consuming and annoying — but I suspect these quirks in the documentation and behavior are responsible for a lot of confusion.

Date formatting syntax

Setting a date formatting string looks like this:

NSDate *date = [NSDate date];
NSDateFormatter *dateFormatter = [[[NSDateFormatter alloc] init] autorelease];
[dateFormatter setFormatterBehavior:NSDateFormatterBehavior10_4];
[dateFormatter setDateFormat:@"dd MMM, yyyy"];
NSString *dateString = [dateFormatter stringFromDate:date];

This will create a string of the format "26 May, 2009". The arrangement of data in this string is determined by the format string passed to the setDateFormat: method.

A quick summary of the date formatting options useable in this format string:

Character	Matches/Outputs	Multiples
y	Year	1, 2 or 4 'y's will show the value, 2 digit zero-padded value or 4 digit zero-padded value respectively
M	Month	1, 2, 3, 4 or 5 'M's will show the value, 2 digit zero-padded value, short name, long name or initial letter months
d	Day of Month	1 or 2 'd's will show the value or 2 digit zero-padded value representation respectively.
e	Weekday	1, 2, 3, 4 or 5 'e's will show the value weekday number, 2 digit zero-padded value weekday number, short name, long name or initial letter respectively. Weekday numbers starts on Monday. Use uppercase 'E' for weekday numbers starting on Sunday.
a	AM or PM	No repeat supported
h	Hour	1 or 2 'h's will show the value or 2 digit zero-padded value representation respectively. Use uppercase for 24 hour time.
m	Minute	1 or 2 'm's will show the value or 2 digit zero-padded value representation respectively.
s	Second	1 or 2 's's will show the value or 2 digit zero-padded value representation respectively.
z	Timezone	1, 2, 3 or 4 'z's will show short acronym, short name, long acronym, long name respectively. Use uppercase to show GMT offset instead of name — 1 or 2 digit zero-padded values shows GMT or RFC 822 respectively.

Case is important — using the wrong case can cause parsing to fail. Use lowercase by default for all values except Month.

Alphabetic and numeric characters should be enclosed in single quotes (asterisk character) if you want them to pass through the parser as literal characters. A double asterisk will pass through as a single asterisk (self escaping). Most other punctuation and spaces will go through as normal except backslash which works like a normal C-string escape character to handle tabs, newlines and other special characters.

For the complete specification, including the more obscure options that I haven't bothered to list, see Unicode Standard (tr35).

Date string transcoding

The date formatting options can also be used to parse strings. With parsing and output formatting, we can create a date string transcoder method in a category on NSDateFormatter:

+ (NSString *)dateStringFromString:(NSString *)sourceString
    sourceFormat:(NSString *)sourceFormat
    destinationFormat:(NSString *)destinationFormat
{
    NSDateFormatter *dateFormatter = [[[NSDateFormatter alloc] init] autorelease];
    [dateFormatter setFormatterBehavior:NSDateFormatterBehavior10_4];
    [dateFormatter setDateFormat:sourceFormat];
    NSDate *date = [dateFormatter dateFromString:sourceString];
    [dateFormatter setDateFormat:destinationFormat];
    return [dateFormatter stringFromDate:date];
}

We can use this method to convert one date string (for example "2007-08-11T19:30:00Z") into another ("7:30:00PM on August 11, 2007") in the following manner:

NSString *inputDateString = @"2007-08-11T19:30:00Z";
NSString *outputDateString = [NSDateFormatter
    dateStringFromString:inputDateString
    sourceFormat:@"yyyy-MM-dd'T'HH:mm:ss'Z'"
    destinationFormat:@"h:mm:ssa 'on' MMMM d, yyyy"];

Calendar stuff

The NSDateFormatter class is just for parsing and formatting strings. You shouldn't use it to build dates from their components or to decompose dates into components. For that task, use NSCalendar. It's a little outside the scope of this post but since I know it will come up, here's how to set an NSDate to the 26th of May, 2009 using NSCalendar:

NSDateComponents *components = [[[NSDateComponents alloc] init] autorelease];
[components setDay:26];
[components setMonth:5];
[components setYear:2009];
NSCalendar *gregorian =
    [[[NSCalendar alloc] initWithCalendarIdentifier:NSGregorianCalendar] autorelease];
NSDate *date = [gregorian dateFromComponents:components];

To get the components from a date, use:

unsigned unitFlags = NSYearCalendarUnit | NSMonthCalendarUnit |  NSDayCalendarUnit;
NSDate *date = [NSDate date];
NSCalendar *gregorian =
    [[[NSCalendar alloc] initWithCalendarIdentifier:NSGregorianCalendar] autorelease];
NSDateComponents *components = [gregorian components:unitFlags fromDate:date];

Conclusion

As I've said a few times now, the actual API for date formatting in Cocoa is simple. The only reason why I consider it a topic worthy of a post is that I still see at least one question a week on StackOverflow and other forums asking why NSDateFormatter is failing in their code and the answer is normally because their code confuses the formatting behaviors, uses the wrong format specifiers or has otherwise misunderstood the required steps.

I hope what I've presented clears up these issues. Date formatting should be simple enough that you can write it once and never worry about it again.

Intercepting status bar touches on the iPhone

2009-05-19T22:10:00.001-07:00

You can configure your iPhone applications so that a touch in the status bar will scroll a UIScrollView to the top. I'll show you how you can intercept this touch event to use status bar touches for other purposes. The sample application will show a hidden drawer that slides out from the status bar when you tap it.

Touches in the status bar

A lesser known user-interface feature on the iPhone is that touches in the status bar will usually scroll the main UIScrollView to the top, providing a quick way to scroll to the top of long documents.

This will work in your application when exactly one UIScrollView returns YES for the scrollsToTop property (YES is the default). If more than one UIScrollView returns YES for this property (or the UIScrollView's delegate returns NO from scrollViewWillScrollToTop:) the scroll to top functionality will be disabled.

That's the ordinary functionality but how do we achieve different functionality?

The HiddenDrawer sample appliction

These screenshots show the HiddenDrawer sample application. When the status bar is tapped on the left, the hidden drawer animates out from under the status bar, resulting in the state shown on the right.

Stealing status bar touch events

The trickiest part of the sample application is detecting a touch in the status bar.

By implementing a custom setContentOffset:animated: method on a UITableView and setting a breakpoint in that method, you can see in the debugger stack that the UIApplication sendEvent: method is invoked for status bar touches, so that's where we'll begin.

CustomApplication

Overriding UIApplication is extremely rare so I'll explain how to make it work. Once you create the subclass of UIApplication you need to tell the program to use that subclass. In Cocoa Senior (Mac OS X) you specify application subclasses in the Info.plist file. In Cocoa Touch, you specify custom application subclasses by name in the UIApplicationMain function in the main.m file:

int retVal = UIApplicationMain(argc, argv, @"CustomApplication", nil);

sendEvent:

The only method override we need in CustomApplication is sendEvent:. The difficult part is then working out from the UIEvent which events are status bar touch events — unfortunately, the allTouches method returns an empty array for status bar touches.

Instead, we delve into the secret GSEvent.

I previously accessed GSEvent in my post Synthesizing a touch event on the iPhone. In that post, I created a PublicEvent class and a fake GSEventProxy class to access the required fields. This time, I'm going to use a different approach and jump straight to the data I need.

- (void)sendEvent:(UIEvent *)anEvent
{
    #define GS_EVENT_TYPE_OFFSET 2
    #define GS_EVENT_X_OFFSET 6
    #define GS_EVENT_Y_OFFSET 7
    #define STATUS_BAR_TOUCH_DOWN 1015
    
    // Traverse from the UIEvent to the GSEvent to the type
    int *eventMemory = (int *)[anEvent performSelector:@selector(_gsEvent)];
    int eventType = eventMemory[GS_EVENT_TYPE_OFFSET];

    // Look for status bar touches by event type
    if (eventType == STATUS_BAR_TOUCH_DOWN)
    {
        // The next 6 lines aren't essential but if you want to know where the
       // touch coordinates live, here they are: 
        int xMemory = eventMemory[GS_EVENT_X_OFFSET];
        int yMemory = eventMemory[GS_EVENT_Y_OFFSET];

        typedef union {int intValue; float floatValue;} Int2Float;
        float x = ((Int2Float)xMemory).floatValue;
        float y = ((Int2Float)yMemory).floatValue;

        NSLog(@"Status bar down at %f, %f", x, y);
        
        // Send a message to the delegate to handle the action
        [(HiddenDrawerAppDelegate *)self.delegate toggleDrawer];
    }
    else
    {
        [super sendEvent:anEvent];
    }
}

You may be curious to know where the OFFSET values come from. The answer is that I spent a while staring at the raw memory values in the GSEvent object while deliberately causing status bar and other touch events — nothing fancier than that. It's tricky and unreliable. If it works at all in iPhoneSDK3.0, it'll be pure luck.

I also use a union here. This is because I step through memory as ints and in C, a basic cast from int to float causes a value conversion (I want a reinterpret, not a value conversion).

I also chose to suppress status bar touch events going through to the UITableView by the normal route. If you want to re-enable this behavior, you can take the [super sendEvent:anEvent]; line out of the else block and put it in the main method body.

Animating the drawer

The sendEvent: implementation above invokes the toggleDrawer method on the application's delegate.

All that's required is to animate the drawer's view in and push the table's view down:

drawerController = [[HiddenDrawerViewController alloc] init];

// Position the drawer below the status bar
CGRect drawerFrame = drawerController.view.frame;
CGRect statusBarFrame = [[UIApplication sharedApplication] statusBarFrame];
drawerFrame.origin.x = statusBarFrame.origin.x;
drawerFrame.size.width = statusBarFrame.size.width;
drawerFrame.origin.y = statusBarFrame.origin.y + statusBarFrame.size.height;

// For the animation, move the drawer up by its own height.
drawerFrame.origin.y -= drawerFrame.size.height;

// Place the drawer and add it to the window
drawerController.view.frame = drawerFrame;
[window addSubview:drawerController.view];

// Start the animation
[UIView beginAnimations:nil context:nil];

// Move the table down
CGRect tableFrame = viewController.view.frame;
tableFrame.origin.y += drawerFrame.size.height;
viewController.view.frame = tableFrame;

// Move the drawer down
drawerFrame.origin.y += drawerFrame.size.height;
drawerController.view.frame = drawerFrame;

// Commit the animation
[UIView commitAnimations];

If you download the whole project, you'll see that there's also an animate up and remove branch that gets run if the drawerController already exists.

Conclusion

You can download the HiddenDrawer sample project (30kB) to see the whole application in action.

A hidden drawer under the status bar isn't necessarily something that every iPhone application should have but the obscure, secretive nature of it appeals to me.

The approach of determining which UIEvent we want by the type field in the GSEvent is a little precarious. Apple are free to change the structure of GSEvent at any time, which could cause your application to misbehave or crash so this type of code would need to be tested on each iPhone OS release to ensure that it still works.

Variable argument lists in Cocoa

2009-05-10T20:05:00.001-07:00

This week I'll talk about methods that take variable numbers of arguments, also known as variadic methods. I'll show you the Objective-C syntax and implementation, give a quick rundown of the ways that Cocoa classes provide variable argument support and I'll also show you a way to fake va_list parameters to handle Cocoa's variadic method equivalents at runtime.

Variable arguments basics

Passing a variable number of arguments to a method is a convenient way to handle a list of variables that are in scope at compile time.

The Objective-C language handles variable arguments in the same way that Standard C does. Normally, you will encounter variable argument lists in one of two forms: "Format strings" or "Nil terminated lists".

Format strings

The traditional example for variable arguments are format strings. Format strings contain a number of "placeholders" (escape sequences starting with a "%" sign) that are replaced with data from variables when the format string and the variable arguments are passed to the method.

NSString *myString = [NSString stringWithFormat:
    @"Number %d, String: %@, Float: %g", 123, @"SomeString", 34.5];

This method is declared as follows:

+ (id)stringWithFormat:(NSString *)format, ...;

The "..." is the variable argument.

This method declares a first parameter but everything else is "variable". This does not mean optional. Instead, it means that a number of extra parameters will be required. Exactly what number and their types depends on how the method works.

The documented behavior for stringWithFormat:, is that it scans the format string and requires 1 variable argument for every escape sequence (in this case there are 3) and the type must match the specifier for each escape sequence (in this case, "d", "@" and "g" specify int, id and float/double).

Nil terminated lists

The other common type of variable argument list method is one that takes a list of objects terminated by nil.

In Cocoa, these are commonly used for constructing collection objects.

NSArray *myArray = [NSArray arrayWithObjects:@"One", @"Two", @"Three", nil];

The documented rule for this type of method is that the last argument must be nil.

Getting argument numbers wrong

The details of "Format strings" and "Nil terminated lists" reveal the difficulty with variable argument lists in Objective-C: knowing how many arguments exist — i.e. when to stop reading arguments.

Objective-C, like C, does not have a runtime argument count, nor does it pass runtime argument types. So the number and types of arguments must be determined by some other policy. In the case of these two examples, the argument count is, respectively: the number of escape sequences in the "Format string" or the number of arguments before the first nil. For "format strings" the types are determined by the escape sequences, for "Nil terminated" lists, the arguments are always pointers.

The penalty for getting variable argument list wrong can be severe: the compiler won't typically notice a problem and your code will crash or behave very strangely at runtime. The important lesson to learn is that you should only use variable arguments in a situation where the policy for numbers and types of arguments is very clear.

You can improve the compiler verification of variable argument lists by using the -Wformat compiler flag in GCC. See below for more about how this works.

Implementing variable arguments for your own methods

Lets look at the implementation for the example class:

@interface StringContainer : NSObject
{
    NSString *contents;
}
@end

Imagine we wanted a method that would set the contents string this class contains by concatenating a variable argument list of strings together.

In this case, we will use the nil terminated approach — the list of strings to concatenate will end with a nil, so we know when to stop reading.

The declaration for the method looks like this:

- (void)setContentByAppendingStrings:(NSString *)firstString, ...
    NS_REQUIRES_NIL_TERMINATION;

The NS_REQUIRES_NIL_TERMINATION part is a macro that tells the compiler that invocations of this method must include a nil-terminated list of arguments. Failure to nil-terminate the list will result in a compiler warning if -Wformat is enabled.

Annoyingly, -Wformat is not enabled by default. Double annoyingly, it is named "Typecheck Calls to printf/scanf" in the "GCC 4.0 Warnings" section of the "Build Settings" in Xcode, even though this setting affects the NS_REQUIRES_NIL_TERMINATION macro which is used commonly throughout all of Cocoa — far beyond printf and scanf.

The implementation of this method is as follows:

- (void)setContentByAppendingStrings:(NSString *)firstArg, ...
{
    NSMutableString *newContentString = [NSMutableString string];
    va_list args;
    va_start(args, firstArg);
    for (NSString *arg = firstArg; arg != nil; arg = va_arg(args, NSString*))
    {
        [newContentString appendString:arg];
    }
    va_end(args);
    
    [contents autorelease];
    contents = [newContentString retain];
}

The va_list, va_start, va_arg and va_end are all standard C syntax for handling variable arguments. To describe them simply:

va_list - A pointer to a list of variable arguments.
va_start - Initializes a va_list to point to the first argument after the argument specified.
va_arg - Fetches the next argument out of the list. You must specify the type of the argument (so that va_arg knows how many bytes to extract).
va_end - Releases any memory held by the va_list data structure.

Generally speaking, you can use this for loop for any variable argument situation where your arguments are all the same type. Other cases are a bit trickier but far less common — I'm sure you can work out how they would work if needed.

va_list in Cocoa

A number of classes in Cocoa have methods that take variable numbers of arguments. In most cases, these classes will also have an equivalent method that takes a va_list.

We can see an example of these va_list equivalents by looking at NSString. NSString declares the class method stringWithFormat:... (which takes a variable number of arguments) and NSString also declares the instance method initWithFormat:arguments: (where the arguments parameter is a va_list) which handles the equivalent behavior of stringWithFormat:....

These va_list methods are used in the situation where your class defines a method with a variable argument list and you need to pass those variable arguments into the Cocoa method. For example, if the StringContainer class listed above declared the method:

- (void)setContentsWithFormat:(NSString *)formatString, ...;

The implementation of this method would be as follows:

- (void)setContentsWithFormat:(NSString *)formatString, ...
{
    [contents autorelease];

    va_list args;
    va_start(args, formatString);
    contents = [[NSString alloc] initWithFormat:formatString arguments:args];
    va_end(args);
}

The va_list parameter allows us to pass our own variable argument list to the Cocoa method so that the Cocoa method can handle the arguments.

Creating a fake va_list

The va_list methods in Cocoa are helpful if you actually have a variable argument list.

There is another situation you many encounter though: you want to use a method like -[NSString initWithFormat:arguments:] using a runtime generated array of arguments. There is no NSString format method that takes an NSArray of arguments, so how could we handle a format string at runtime?

The answer lies in how va_list works. While GCC makes it very clear that va_list is "platform specific", the reality is that on Mac and iPhone Objective-C platforms, it is simply a byte buffer containing the arguments. In fact, if you've ever used an ABI inspection tool (like class-dump-x) on a method taking a variable argument list, you'll see that it is simply a char *.

To show how we can use this knowledge, consider the following method on the StringContainer class:

- (void)setContentsWithFormat:(NSString *)formatString arguments:(NSArray *)arguments;

If we assume that all of the variable arguments required fro the formatString are objects, then we can implement this method as follows:

- (void)setContentsWithFormat:(NSString *)formatString arguments:(NSArray *)arguments
{
    [contents autorelease];

    char *argList = (char *)malloc(sizeof(NSString *) * [arguments count]);
    [arguments getObjects:(id *)argList];
    
    contents = [[NSString alloc] initWithFormat:formatString arguments:argList];
    
    free(argList);
}

What I've done here is simply copied the NSArray to a C-style byte buffer and then passed that buffer to the initWithFormat:arguments: method.

If your arguments are not all Objective-C objects, you'd need to take greater care to assemble the byte buffer but the principles would be the same.

Some variadic notes

NSInvcation incompatibility

NSInvocation does not support variadic methods. I'm not sure why this is — maybe NSInvocation wants to avoid making assumptions about va_list, maybe it is because NSMethodSignature can't describe the storage requirements of variable arguments for NSInvocation or maybe the Cocoa developers have families and just wanted to go home early.

Variadic macros

You can also write variadic macros, much like variadic methods, by using the ##__VA_ARGS__ placeholder in your macros. See the macros near the bottom of my post titled Supersequent Implementation for an example of how this works. As discussed briefly in that article, the version of GCC used for iPhone development handles variadic macros slightly differently, so pay attention to the differences when targetting the iPhone platform.

Conclusion

Variadic methods require a degree more care than regular methods because variable argument lists have no "introspection" (you cannot ask for the number and type of arguments) — so their usage relies on documentation and implicit agreements between the sender and receiver.

In your own code, variadic methods should be used sparingly — passing variables in an NSArray or NSDictionary is safer (if slightly slower and syntactically more verbose) due to the fact that these classes do offer introspection.

When the implicit sender/receiver agreement is clear, variadic methods work well. They certainly make creating instances of NSArray, NSSet, NSDictionary easier and they are the only way to create a formatted NSString in a single invocation.

Invoking other processes in Cocoa

2009-05-04T19:37:00.001-07:00

Invoking other processes is a good way to handle some low-level tasks on the Mac. I'll show you some simple ways to invoke processes and parse their outputs in Cocoa apps as well as some advanced tricks like running a process with administrator privileges.

The Sample Application: Open File Killer

Have you ever tried to empty the Trash, only to be told that some process has one of the files open so Trash can't delete it now?

This week's sample application solves that problem. Drag a file onto Open File Killer and it will tell you all the processes that have the file open and lets you kill them if needed.

How Open File Killer works

This program invokes two other processes to perform its work:

lsof - to find the processes that have the specified file open
sh - run with administrator privileges to send a SIGKILL to processes

Be careful when using the "Kill process" button — arbitrarily killing system processes can be dangerous to data and system stability so use with caution.

Starting another process with NSTask

You can launch other applications using NSWorkspace's launchApplication: and they will appear as though you launched them from the Finder. To run processes that are not applications, you will typically use NSTask instead.

NSTask does provide the convenience method launchedTaskWithLaunchPath:arguments: to launch another process in one line, however this method does not allow access to the launched task's standard output, which we'll need to get results from lsof.

Reading output from NSTask requires setting up NSPipes and reading from the NSFileHandle for each pipe. Since all this can be a bit verbose, we'll create a reusable method with the following prototype:

+ (NSString *)stringByLaunchingPath:(NSString *)processPath
    withArguments:(NSArray *)arguments
    error:(NSError **)error

This is similar to launchedTaskWithLaunchPath:arguments: but returns the standard out as a string and returns standard error in the userInfo property of the NSError under the key @"standardError".

Excluding the error handling parts, the implementation of this method is as follows:

NSTask *task = [[[NSTask alloc] init] autorelease];

[task setLaunchPath:processPath];
[task setArguments:arguments];
[task setStandardOutput:[NSPipe pipe]];
[task setStandardError:[NSPipe pipe]];

TaskOutputReader *outputReader = [[TaskOutputReader alloc] initWithTask:task];

NSString *outputString = nil;
NSString *errorString = nil;

[outputReader launchTaskAndRunSynchronous];

outputString =
    [[[NSString alloc]
        initWithData:[outputReader standardOutputData]
        encoding:NSUTF8StringEncoding]
    autorelease];
errorString =
    [[[NSString alloc]
        initWithData:[outputReader standardErrorData]
        encoding:NSUTF8StringEncoding]
    autorelease];

[outputReader release];

The TaskOutputReader is a simple class that invokes launch on the task and runs the current NSRunLoop, reading from the standardOut and standardError of the task until the task terminates.

The strangest part to me is the NSPipe part — NSPipe is an opaque class (you can't do anything directly to it) that only works with NSTask and allows you to subsequently invoke fileHandleForReading/fileHandleForWriting. To me, it really seems as though NSPipe shouldn't exist at all and any Unix-level pipes and file descriptors should be created on demand when you invoke standardOutput.

Anyway, that's why I always use a convenience method to wrap it all up. The only reason why you shouldn't use a convenience method like this is if you want progressive output updates (like line-by-line log file output) or two-way communication (command and response) since you can't simply block a return to the calling function these cases.

Parsing text

So we can use the stringByLaunchingPath:withArguments:error: method to launch lsof and pass the path of the file.

The result from lsof looks something like this:

COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF    NODE NAME
Preview 78180 matt  txt    REG   14,2    52889 1233935 /Users/matt/Downloads/002dfwtw.jpg

We need to parse this result and extract the information that is useful to us: the first two columns of the second row. I know, there are arguments to lsof that will produce more "computer-readable" output but when done right, parsing this output should be easier than reading man-page documentation.

The base Cocoa classes do no really handle sophisticated text parsing on their own. There is no regular expression library by default (get yourself a copy of OgreKit or RegexKit to do that) and while NSString has a few manipulation methods, many of the chop, split, tokenize and line-at-a-time handling functions and operators that are common in scripting languages, do not appear in Cocoa.

You can guess at the reason behind some of these decisions. I would suggest that you're not supposed to store structured data in pure text strings in a language with sophisticated real data structures, so Cocoa doesn't try to make it easier for you.

Another reason would be that C-based languages are more about giving you the basic building blocks to make efficient solutions over any domain, not about giving you already-domain-specific pre-canned solutions. AppKit/UIKit are obvious exceptions where complete, domain-specific solutions are given but in those cases, the solution domain for "application framework" is already fixed (Mac OS X/iPhone), so they are not really narrowing the potential solutions.

The result though, is that any project requiring text handling will likely need to implement a few simple text handling methods. You can get quite practised at using the "basic building blocks" to write small parser methods to handle data that comes from plain text sources like lsof's output.

- (NSArray *)arrayBySeparatingIntoParagraphs
{
    NSUInteger length = [self length];
    NSUInteger paraStart = 0;
    NSUInteger paraEnd = 0;
    NSUInteger contentsEnd = 0;
    NSMutableArray *array = [NSMutableArray array];
    NSRange currentRange;
    while (paraEnd < length)
    {
        [self
            getParagraphStart:¶Start
            end:¶End
            contentsEnd:&contentsEnd
            forRange:NSMakeRange(paraEnd, 0)];
        currentRange = NSMakeRange(paraStart, contentsEnd - paraStart);
        [array addObject:[self substringWithRange:currentRange]];
    }
    return array;
}

You might ask about this function: "Why not just use the existing componentsSeparatedByString: and pass @"\n" as the string?"

The answer is largely because it is recommended that you don't assume \n is the paragraph separator in case the paragraph separator is a Windows line-feed (\r\n) or an old Mac OS 9 carriage return (\r). Okay, irrelevant here but this method can be used anywhere where you need to break an NSString into paragraphs.

Also, if you needed to optimize your code, getParagraphStart:end:contentsEnd:forRange: allows you to parse each line inside the loop, avoiding the need to create the array of lines at all. This is something that the upcoming "blocks" feature of Objective-C will make much easier since you'll be able to pass the block for the inside of the loop as a parameter to the method.

You might also be curious about the difference between a "paragraph" and a "line", especially since the method getLineStart:end:contentsEnd:forRange: also exists. The difference is minor — lines also break on the rarely seen Unicode line-break character (sometimes used to represent HTML's <br>). In this case, it doesn't really matter.

- (NSArray *)tokensSeparatedByCharactersInSet:(NSCharacterSet *)separator
{
    NSScanner *scanner = [NSScanner scannerWithString:self];
    NSMutableArray *array = [NSMutableArray array];
    while (![scanner isAtEnd])
    {
        [scanner scanCharactersFromSet:separator intoString:nil];

        NSString *component;
        if ([scanner scanUpToCharactersFromSet:separator intoString:&component])
        {
            [array addObject:component];
        }
    }
    return array;
}

This method extracts runs of characters not in the separator character set from runs of characters that are. It differs from componentsSeparatedByCharactersInSet: because it treats runs of separator characters as single elements and never outputs empty tokens.

If we pass [NSCharacterSet whitespaceCharacterSet] into this method, it will break the string up by blocks of whitespace, allowing us to extract the columns of text from a row of the lsof output (where the rows are extracted using the arrayBySeparatingIntoParagraphs method).

This method isn't used in the sample app anymore. It didn't handle application names with spaces in them. I've replaced it with an approach that extracts the columns from the lsof output by character index using substringWithRange: and then uses the stringByTrimmingCharactersInSet: method to remove whitespace from the end. I'll leave the method in the post — it is still useful, just not in this case.

In this way we can parse the output of lsof and get the names and process IDs of any process that has a given file path open.

Running with elevated privileges

For killing tasks, I wanted to run with administrator privileges, so that any process could be killed.

To make the design as consistent as possible, I created a method that would invoke a process with different privileges that looked as much like the NSTask method as possible:

+ (NSString *)stringByLaunchingPath:(NSString *)processPath
    withArguments:(NSArray *)arguments
    authorization:(SFAuthorization *)authorization
    error:(NSError **)error

This method then works the same as the previous method except it requires an SFAuthorization object and it will not return standard error in the NSError object.

Creating the authorization object is quite simple:

authorization = [SFAuthorization authorization];
BOOL result =
    [authorization
        obtainWithRights:NULL
        flags:kAuthorizationFlagExtendRights
        environment:NULL
        authorizedRights:NULL
if (!result)
{
    NSLog(@"SFAuthorization error: %@", [error localizedDescription]); 
    return;
}

This is an authorization object for launching another process with administrator rights (kAuthorizationFlagExtendRights) and no other options set. When used, this will prompt the user for an administrator password.

Running the administrator rights process is then handled with:

OSErr processError =
    AuthorizationExecuteWithPrivileges(
        [authorization authorizationRef],
        [processPath UTF8String],
        kAuthorizationFlagDefaults,
        (char *const *)argv,
        &processOutput);

The C-style argv array is a bit annoying to create from an Objective-C NSArray of NSStrings and using fread to read the output from processOutput is also a pain but once the input and output data wrangling is done, this can work as simply as the NSTask-based invocation.

Warning: running with elevated privileges is dangerous. Don't do this casually in your code, think about it first. And as a user of programs, don't enter your administrator password unless you trust the program you're running (be careful of potential malware and trojans).

Other things that make an application

The application in this week's post contains a number of features that aren't relevant to this post but are interesting and useful nevertheless. These include:

Drag and drop of files onto the view using draggingEntered:, draggingExited: and performDragOperation: to handle the drag and drawing a highlighting rect to indicate drag focus using NSSetFocusRingStyle and bezierPathWithRect:. See the FileDragReceivingView that I've set as the contentView of the window.
Opening files from the Finder/Dock without NSDocument using the NSApplication delegate method application:openFiles: and an "any" DocumentType listed in the Info.plist file.

And oh, how I miss NSArrayController and bindings on NSTableView when I'm working on the iPhone. They make populating a table of results so much easier.

Conclusion

You can download the complete Open File Killer project (70kB).

The default process-launching and string-handling in Cocoa are not heavily geared towards command-line shell style invocation and handling but it doesn't take much to create a few wrapper methods that will make this a lot easier.

Mac OS X has lots of standard in/out based executables: POSIX, BSD, Mac OS X Admin Tools, Developer Tools and any number of open source tools that you might load through package managers or other means. That's a lot of functionality available to your program and, when done right, using these tools should be as simple as invoking a method on a class.

The sample application shows this in action. The code in KillerController is more verbose than an equivalent application in a scripting language might be but verbose compared to another language does not equal worse. The Objective-C code is not significantly more complex than a typical scripting language performing the same tasks (the verbosity is mostly word and operator length plus formatting, not extra operators and commands), yet it is fast, handles errors gracefully and integrates smoothly into the user-interface.

Easy custom UITableView drawing

2009-04-28T00:09:00.001-07:00

It is really easy to customize your UITableViews. I'll show you how to completely customize the appearance of UITableViews without overriding or subclassing and without the need for any tricky hackery.

Make my table pretty

The core of most iPhone applications is the UITableView. To make your iPhone application stand out, the simplest way is to make your UITableView look good.

Customizing your UITableView can be really easy. You don't need custom drawing code. You don't need subclasses of anything. Cocoa Touch provides all the drawing capability you need, all you have to do is use the right classes in the right ways and provide the layout.

The sample application

The approach I'll show you will turn the table on the left into the table on the right:

Left: a default UITableView with three rows. Right: the same table view after customization.

How to fail at UITableView customizing

Coming from Mac OS X made it harder for me — UITableView needs to be customized in a very particular way and structurally, it is very different to Mac OS X's NSTableView and NSCell drawing.

The following are all really bad ways to customize a table (even though you can make it work):

Subclassing UITableView to customize drawing
Subclassing UITableViewCell to customize drawing
Creating your own array of UITableViewCells and returning these instead of using dequeueReusableCellWithIdentifier:

That last point is only peripherally related to drawing but it will significantly slow your drawing down. Don't do it.

If you have ever done any of these things, you're making it hard on yourself.

How to succeed at UITableView customizing

There are only a few points to understand related to table drawing.

First: the UITableView does not itself draw anything except the background. To customize the background of a UITableView, all you need to do is set its backgroundColor to [UIColor clearColor] and you can draw your own background in a view behind the UITableView.

Second: The tableHeaderView (and the table footer and section headers and footers) need not be just a title. You can insert your own view, with its own subviews in the table header, giving layout and custom drawing freedom.

Third: UITableViewCell is composed of 5 different subviews. Customizing the right subview is the secret to good UITableViewCell drawing. The subviews are:

backgroundView — the entire background of the row (including what looks like the UITableView's background in UITableViewStyleGrouped style tables.
selectedBackgroundView — replaces the backgroundView when the row is selected.
image — a customizable image (not actually a subview) at the left of the cell.
accessoryView — a customizable view at the right of the cell.
contentView — a customizable view between the image and the accessoryView (technically, it extends behind the image).

You can customize any of these (except image which must be a UIImage) using your own custom drawn views.

However, since the pixel size of the table never changes, it is often easiest just to use UIImageViews for each of them. Then you can take highly complex views drawn in separate programs, cut them into the 5 necessary pieces and let the automatic caching of UIImage's named image cache manage your memory for you.

There is an argument against drawing your views in code and that is that the iPhone's drawing is not nearly as fast as Mac OS X. Operations like gradients and multiple overlapped components can really tax the iPhone.

Custom drawing code is a good choice for simple and flat colour drawing. In most other cases — as in this post — I recommend you use UIImageView to draw your views in a table.

Implementation

With all custom drawing handled by UIImageView, that still leaves some work to do. You must handle all layout and configuring of views.

Configuration of the UITableView and layout of the table header

As an example of what that means, have a look at the viewDidLoad method for this post:

- (void)viewDidLoad
{
    //
    // Change the properties of the imageView and tableView (these could be set
    // in interface builder instead).
    //
    tableView.separatorStyle = UITableViewCellSeparatorStyleNone;
    tableView.rowHeight = 100;
    tableView.backgroundColor = [UIColor clearColor];
    imageView.image = [UIImage imageNamed:@"gradientBackground.png"];
    
    //
    // Create a header view. Wrap it in a container to allow us to position
    // it better.
    //
    UIView *containerView =
        [[[UIView alloc]
            initWithFrame:CGRectMake(0, 0, 300, 60)]
        autorelease];
    UILabel *headerLabel =
        [[[UILabel alloc]
            initWithFrame:CGRectMake(10, 20, 300, 40)]
        autorelease];
    headerLabel.text = NSLocalizedString(@"Header for the table", @"");
    headerLabel.textColor = [UIColor whiteColor];
    headerLabel.shadowColor = [UIColor blackColor];
    headerLabel.shadowOffset = CGSizeMake(0, 1);
    headerLabel.font = [UIFont boldSystemFontOfSize:22];
    headerLabel.backgroundColor = [UIColor clearColor];
    [containerView addSubview:headerLabel];
    self.tableView.tableHeaderView = containerView;
}

This method handles the configuration of the tableView (setting the backgroundColor, rowHeight and sets an image behind the table) but also creates its own layout for the table header.

The layout of the header here is for the table's header view. You can include a custom header for every table section by implementing the UITableViewDelegate method tableView:viewForHeaderInSection:. There are equivalent properties and methods for the table and section footers.

It is possible to handle this type of layout in Interface Builder and load the XIB files for this type of layout. Sadly though, on the iPhone, reading loading lots of views from XIB files is slow (I suspect this is due to slow reading from the Flash memory) and doesn't always allow configuration of every property.

For this reason, I normally sketch my views in Interface Builder and then manually recreate the same thing in code. That's what I've done here: picking coordinates for the headerLabel that looks balanced in the view.

Cell backgrounds

The cell background needs to incorporate the tops and bottoms of table "sections". For this reason, the backgroundView and selectedBackgroundView normally need to be set on a row-by-row basis.

In your tableView:cellForRowAtIndexPath: method where you are configuring the cell for a given row, this code will handle that behavior:

UIImage *rowBackground;
UIImage *selectionBackground;
NSInteger sectionRows = [aTableView numberOfRowsInSection:[indexPath section]];
NSInteger row = [indexPath row];
if (row == 0 && row == sectionRows - 1)
{
    rowBackground = [UIImage imageNamed:@"topAndBottomRow.png"];
    selectionBackground = [UIImage imageNamed:@"topAndBottomRowSelected.png"];
}
else if (row == 0)
{
    rowBackground = [UIImage imageNamed:@"topRow.png"];
    selectionBackground = [UIImage imageNamed:@"topRowSelected.png"];
}
else if (row == sectionRows - 1)
{
    rowBackground = [UIImage imageNamed:@"bottomRow.png"];
    selectionBackground = [UIImage imageNamed:@"bottomRowSelected.png"];
}
else
{
    rowBackground = [UIImage imageNamed:@"middleRow.png"];
    selectionBackground = [UIImage imageNamed:@"middleRowSelected.png"];
}
((UIImageView *)cell.backgroundView).image = rowBackground;
((UIImageView *)cell.selectedBackgroundView).image = selectionBackground;

Layout within the contentView

Layout of elements within the contentView need only be set on construction of the contentView (not on a row-by-row basis).

Sadly, laying out UILabels in the contentView (like the "Cell at row X." and "Some other infomation." lables in this example) is a little verbose.

The following code is run immediately after the allocation of the UITableViewCell to position the "Cell at row X." label:

const CGFloat LABEL_HEIGHT = 20;
UIImage *image = [UIImage imageNamed:@"imageA.png"];

//
// Create the label for the top row of text
//
topLabel =
    [[[UILabel alloc]
        initWithFrame:
            CGRectMake(
                image.size.width + 2.0 * cell.indentationWidth,
                0.5 * (aTableView.rowHeight - 2 * LABEL_HEIGHT),
                aTableView.bounds.size.width -
                    image.size.width - 4.0 * cell.indentationWidth
                        - indicatorImage.size.width,
                LABEL_HEIGHT)]
    autorelease];
[cell.contentView addSubview:topLabel];

//
// Configure the properties for the text that are the same on every row
//
topLabel.tag = TOP_LABEL_TAG;
topLabel.backgroundColor = [UIColor clearColor];
topLabel.textColor = [UIColor colorWithRed:0.25 green:0.0 blue:0.0 alpha:1.0];
topLabel.highlightedTextColor = [UIColor colorWithRed:1.0 green:1.0 blue:0.9 alpha:1.0];
topLabel.font = [UIFont systemFontOfSize:[UIFont labelFontSize]];

//
// Create a background image view.
//
cell.backgroundView = [[[UIImageView alloc] init] autorelease];
cell.selectedBackgroundView = [[[UIImageView alloc] init] autorelease];

In my mind, it seems like there should be a more efficient way to do this. I hold out the possibility that there is.

This code spends most of its time working out where the label should be placed. It needs to go right of the image, left of the accessoryView, middle of the row but above the "Some other information." label.

Other adornments

The accessoryView is just a UIImageView. The cell.image is set as a property. These are extremely simple additions but they make the table cells far more impactful.

Conclusion

You can download the EasyCustomTable project as a zip file (60kb).

The code includes a #define at the top that allows you to toggle the custom drawing on and off.

None of this is particularly revolutionary (it is all in the iPhone documentation) but it is still easy to miss the properties and methods that make it easy.

This does require custom images. If you've never drawn anything, now is a good time to learn inkscape (it's free and very good for the price). You could also use Adobe Illustrator but if you have that much money, pay an artist to draw it for you.

Layout of the content in code is probably the weakest part of the approach I've presented. To make it easier, you can pre-layout everything in Interface Builder and copy the layout into code. For complicated layouts, you could even try using nib2objc to convert your XIB files to code automatically (although I've never done this, I'm just mentioning nib2objc because the idea is so cool).

What does it mean when you assign [super init] to self?

2009-04-18T21:13:00.001-07:00

One of the strangest pieces of common syntax in Objective-C is the line self = [super init];. Without any explanation, this arrangement raises a few questions. Does this line set the self value for the instance? Is self just a variable like any other? If so, why have it at all? I'll address each of these questions and show how the compiler converts uses of self and method invocations.

Converting a method invocation

The first step to understanding the self parameter is to look at how the compiler converts a standard method invocation.

When you type the following:

MyClass *myObject = [[MyClass alloc] initWithString:@"someString"];

The compiler converts this into function calls that look like this:

class myClass = objc_getClass("MyClass");
SEL allocSelector = @selector(alloc);
MyClass *myObject1 = objc_msgSend(myClass, allocSelector);

SEL initSelector = @selector(initWithString:);
MyClass *myObject2 = objc_msgSend(myObject1, initSelector, @"someString");

The compiler has slightly more efficient means of getting the class and SEL values but if you look at assembly code, you will see objc_msgSend calls for every method invocation.

So what is "self"?

Every method that you declare has two hidden parameters: self and _cmd.

The following method:

- (id)initWithString:(NSString *)aString;

is converted by the compiler to the following function call:

id initWithString(id self, SEL _cmd, NSString *aString);

The reality is that self is simply a hidden parameter on every method. Like any other parameter, it receives its value from the function invocation.

Yes, _cmd is also a hidden parameter on every method that you can access if you choose. In reality, there are few uses for the _cmd parameter except in obscure cases.

You can experiment with this by eliminating objc_msgSend and invoking the function for a method directly. Instead of calling:

[myObject someMethodWithParameter:someValue];

You can reach your method implementation directly by recreating the work done by objc_msgSend.

SEL methodSelector = @selector(someMethodWithParameter:);
IMP someMethodFunction = class_getMethodImplementation([myObject class], methodSelector);
someMethodFunction(myObject, methodSelector, someValue);

The only reason why self has a value on the inside of the someMethodWithParameter: implementation is because the pointer myObject is passed as the first parameter into someMethodFunction. If you pass a different value as this first parameter, then self will have a different value on the inside of the method.

If you pass a value of a different class, you have a good chance of crashing the program. The following section explains why.

Why have a "self" parameter at all?

A method needs to know what data to act upon. The self parameter tells the class the data to act upon and so is essential to object oriented programming.

This statement may seem a little strange, since you can easily implement a method without using the self parameter by name. The reality is that the compiler uses the self parameter to resolve any reference to an instance variable inside a method.

If you had a class defined like this:

@interface MyClass : NSObject
{
    NSInteger value;
}
- (void)setValueToZero;
@end

then the method:

- (void)setValueToZero
{
    value = 0;
}

is converted by the compiler into:

void setValueToZero(id self, SEL _cmd)
{
    self->value = 0;
}

So self is essential for accessing any instance variables, even if you never literally type "self".

So does self already have a value when init is called?

If you remember back at the start, I said that the initWithString: part of a typical [[MyClass alloc] initWithString:@"someString"] invocation is converted into an objc_msgSend call:

MyClass *myObject2 = objc_msgSend(myObject1, initSelector, @"someString");

So by the time we get to the inside of the method, self already has a value; its value is myObject1 (i.e. the allocated object, as returned from the [MyClass alloc] call. This is essential because without it, the super invocation wouldn't be possible — the self value is used by the compiler to send the invocation:

[super init];

becomes:

objc_msgSendSuper(self, @selector(init));

Yes, self already has a value when your initializer starts. In fact, it is almost guaranteed to be the correct, final value.

So why assign the value returned from [super init] to self?

Looking at a typical initializer method:

- (id)initWithString:(NSString *)aString
{
    self = [super init];
    if (self)
    {
        instanceString = [aString retain];
    }
    return self;
}

Why do we assign [super init] to self here?

The textbook reason is because [super init] is permitted to do one of three things:

Return its own receiver (the self pointer doesn't change) with inherited instance values initialized.
Return a different object with inherited instance values initialized.
Return nil, indicating failure.

In the first case, the assignment has no effect on self and the instanceString is set on in the original object (the line instanceString = [aString retain]; could have been the first line of the method and the result would be the same).

In the third case, the initialization has failed. self is set to nil, no further action is taken and nil is returned.

The rationale for assigning to self is associated with the second case: if the returned object is different, we want the:

        instanceString = [aString retain];

which gets converted to

        self->instanceString = [aString retain];

to act on the correct value, so we have to change the value of self to point to this new object.

It's almost never required to initialize self

So the rationale for assigning to self is that the [super init] could return a different object and should initialize that different object instead of the old (likely invalid) object.

The question to consider is then: when would [super init] return a different object?

The answer is that it will return different objects in one of the following situations:

Singleton object (always returns the singleton instead of any subsequent allocation)
Other unique objects ([NSNumber numberWithInteger:0] always returns the global "zero" object)
Class clusters substitute private subclasses when you initialize an instance of the superclass.
Classes which choose to reallocate the same (or compatible) class based on parameters passed into the initializer.

In all but the final case, continuing to initialize the returned object if it changes is a mistake — the returned object is already completely initialized and isn't necessary related to your class anymore.

So the list of three things that [super init] is permitted to return can now be expanded to four by splitting the "Return a different object" point into two:

Return its own receiver (the self pointer doesn't change) with inherited instance values initialized.
Return an object of the same class, requiring further initialization.
Return a different object that is already completely initialized.
Return nil, indicating failure.

In this list, we now have two cases (2 and 3) which are incompatible. The typical "assign [super init] to self" initializer handles cases 1, 2 and 4.

An init approach to handle cases 1, 3 and 4 would actually be:

- (id)initWithString:(NSString *)aString
{
    id result = [super init];
    if (self == result)
    {
        instanceString = [aString retain];
    }
    return result;
}

So class clusters, singletons and unique objects all use case 3, putting dozens of Cocoa classes in this category. I'm only aware of NSManagedObject that uses case 2. Curiously then, while case 3 is overwhelmingly more common, initializers that support 1, 2 and 4 but are incompatible with case 3 have become the standard.

Conclusion

Update: I have rewritten this conclusion to reflect the fact that I'm not actually suggesting you should stop using "assign [super init] to self" initializers. Thank you to everyone who invented creative ways to tell me I was wrong about this implication.

You don't need to assign [super init] to self to make most classes work. In some obscure cases, it is actually the wrong thing to do.

So why do we continue to assign to self? It's the traditional template for an initializer, and although it's wrong in some cases, it is right in other cases which have been written to expect this approach.

Further to this is the consideration that class clusters and other classes likely to return unrelated or different, fully initialized objects from their init methods are not supposed to be subclassed in a normal way — making code which favors them less relevant.

The number of cases where super returns an unrelated object are so small that they can easily be dealt with on a case-by-case basis — a class will normally make it very clear when its initializers might return something other than the receiver or nil.

Showing a "Loading..." message over the iPhone keyboard

2009-04-12T23:34:00.001-07:00

The "Text" (SMS) application on the iPhone uses a custom, semi-transparent view to show its "Sending..." message over the keyboard. I'll show you a simple class that can display semi-transparent loading messages and how you can display messages over the keyboard.

Introduction

"Loading..." messages

When waiting for data loaded from the internet, many iPhone applications use a mostly black, semi-transparent view to block the display. Most use a basic "spinner" (UIActivityIndicatorView) to reassure the user that the application is still running, frequently accompanied by "Loading..." text.

Despite the prevalence of this type of loading message, it is not a standard control and must be constructed manually.

Finding the keyboard

Apple give no methods to locate the keyboard or even the current first responder in an iPhone application. I'll show you how you can find both.

The sample application

The sample LoadingView application in this post can display the following two types of loading window:

A full-window loading message and a keyboard-only loading message.

The sample application doesn't actually load anything. The "Refresh" button displays the full-window loading message for 5 seconds and the text field lets you enter some text and hit "Send" to see the keyboard-only loading message for 5 seconds.

Displaying a loading view

A loading view is not the most complicated piece of custom user-interface but there are a handful of common behaviors it should implement so it is a good idea to have a reusable class for the purpose.

The behaviors in my loading view include:

Always fill the whole view that it blocks (even though it looks inset on all sides for aesthetic reasons).
Fade in and fade out when added and removed.
Semi-transparent, allowing the unloaded view to show through.
Autoresizeable so that a portrait to landscape rotation during loading won't disrupt the display.
Displays a centered status message and activity indicator.

To ensure that these behaviors are applied to the view on construction, I use a loadingViewInView: method instead of a normal constructor. This method constructs, adds to superview and handles the fade animation all at once.

+ (id)loadingViewInView:(UIView *)aSuperview
{
    LoadingView *loadingView =
        [[[LoadingView alloc] initWithFrame:[aSuperview bounds]] autorelease];
    if (!loadingView)
    {
        return nil;
    }
    
    loadingView.opaque = NO;
    loadingView.autoresizingMask =
        UIViewAutoresizingFlexibleWidth |
        UIViewAutoresizingFlexibleHeight;
    [aSuperview addSubview:loadingView];

    // Code to create and configure the label and activity view goes here.
    // Download the sample project to see it.

    // Set up the fade-in animation
    CATransition *animation = [CATransition animation];
    [animation setType:kCATransitionFade];
    [[aSuperview layer] addAnimation:animation forKey:@"layerAnimation"];
    
    return loadingView;
}

All that's required to make it look semi-transparent is a custom drawing method.

- (void)drawRect:(CGRect)rect
{
    rect.size.height -= 1;
    rect.size.width -= 1;
    
    const CGFloat RECT_PADDING = 8.0;
    rect = CGRectInset(rect, RECT_PADDING, RECT_PADDING);
    
    const CGFloat ROUND_RECT_CORNER_RADIUS = 5.0;
    CGPathRef roundRectPath =
        NewPathWithRoundRect(rect, ROUND_RECT_CORNER_RADIUS);
    
    CGContextRef context = UIGraphicsGetCurrentContext();

    const CGFloat BACKGROUND_OPACITY = 0.85;
    CGContextSetRGBFillColor(context, 0, 0, 0, BACKGROUND_OPACITY);
    CGContextAddPath(context, roundRectPath);
    CGContextFillPath(context);

    const CGFloat STROKE_OPACITY = 0.25;
    CGContextSetRGBStrokeColor(context, 1, 1, 1, STROKE_OPACITY);
    CGContextAddPath(context, roundRectPath);
    CGContextStrokePath(context);

    CGPathRelease(roundRectPath);
}

Round Rects are Everywhere!

I continue to find it strange that Apple don't provide a function to draw a round rectangle in one line. They do provide the (more flexible) CGPathAddArcToPoint function but it lacks the simplicity of a single line function to handle the common case. Download the project and see how the implementation of NewPathWithRoundRect creates round rects using the CGPathAddArcToPoint function if you don't know how to draw round rects on the iPhone.

The absence of a round rectangle function is particularly strange given the anecdote that Andy Hertzfeld relates on folklore.org and in his excellent book Revolution in the Valley. In this anecdote, Steve Jobs drags Bill Atkinson on a walk around the block with Steve pointing out how everything is made of round rects until Bill relents and agrees to put the RoundRect function into Quickdraw.

Round rectangles continue to be everywhere on the iPhone — maybe more so than on the Mac in 1984. It's a good idea to use a function like NewPathWithRoundRect in your own code.

Finding the keyboard

The keyboard on the iPhone is an instance of UIKeyboard (a private class) in its own UIWindow (actually, it may share the window with the UIAutoCorrectInlineView).

You can find the UIKeyboard with a simple search.

@implementation UIApplication (KeyboardView)

- (UIView *)keyboardView
{
    NSArray *windows = [self windows];
    for (UIWindow *window in [windows reverseObjectEnumerator])
    {
        for (UIView *view in [window subviews])
        {
            if (!strcmp(object_getClassName(view), "UIKeyboard"))
            {
                return view;
            }
        }
    }
    
    return nil;
}

@end

The keyboard itself is a series of nested views which eventually reach the underlying functionality for the keys:

UIKeyboard

UIKeyboardImpl

UIKeyboardLayoutQWERTY

UIKeyboardSublayout

UIImageView
UIKeyboardSpaceKeyView
UIKeyboardReturnKeyView

Interestingly, the keys for the main part of the keyboard are all a single image. This arrangement probably explains why the "space" and "return" keys behave more like regular buttons than the other keys.

For the sample application, since the implementation of LoadingView will size the loading view to cover its immediate superview, passing the keyboard view fetched in this manner will create the keyboard-only loading view shown above.

If you wanted to show a full-window LoadingView that also covers the keyboard, you could pass the keyboard view's superview to the loadingViewInView: but you might want to add an extra 20 pixels padding at the top in this case, since the superview (the window) extends underneath the status bar at the top of the window.

Finding the firstResponder

While it isn't required for the sample project, I thought I'd mention how to fetch a related piece of information: the firstResponder in an iPhone application.

On the iPhone firstResponder is the view which has the current keyboard focus (or nil if no view is focussed).

This is an important piece of information, so it's strange that Apple didn't choose to provide a public method to access it. Curiously, there is a method, firstResponder, on UIWindow which returns this value but it isn't public. This will work:

UIView *firstResponder =
    [[UIApplication sharedApplication]
        keyWindow]
            performSelector:@selector(firstResponder)];

Conclusion

You can see all this code and more in the sample project for this post: LoadingView.zip (129kB)

Displaying a loading view is not a very difficult task (lots of people write their own) but implementing all of the different expected behaviors is time consuming — the implementation in this post is at least 65 lines of code, depending on how you count it — so keeping a resusable implementation can save a lot of time.

Finding the keyboard and finding the current first responder on the iPhone are harder to work out since the API is hidden, and it requires a little investigative work.

Putting it all together, you could easily recreate Apple's "Sending..." progress view used in the Text program.

8 Confusing Objective-C Warnings and Errors

2009-04-05T18:42:00.001-07:00

Objective-C's unique syntax results in unique ways of making mistakes. In this post, I look at the compiler warnings and errors GCC outputs when you make mistakes or potential mistakes in your Objective-C syntax and show you how to fix them.

Every warning is an error

Objective-C lets a lot of potentially fatal problems related to method invocations go through as warnings. This is because the method lookup system is dynamic and from the compiler's perspective you could provide a resolution at runtime.

To make this overly permissive situation in Objective-C safer, you should treat every warning as a potentially fatal error. This means that you should turn on GCC_TREAT_WARNINGS_AS_ERRORS (-Werror) in your build settings so you can catch these problems and fix them instead of letting your program run until it crashes at runtime.

Every warning has an approach to eliminate the warning. These warning-less approaches invariably represent better design. I'll let you know how to fix each of the warnings/errors listed here.

1. Improperly nested method brackets

/path/file.m:15: error: syntax error before 'autorelease'

(where autorelease could be the first word in any method) or

/path/file.m:15: error: syntax error before ';' token

These are the only syntax errors I'm going to include in this list — my reason for including them is that, despite the obvious nature of the problem and its high occurrence rate, GCC presents the errors in a non-descript way that doesn't reveal the underlying problem.

The first error is "you are missing an opening bracket somewhere before this". The second error is "you are missing a closing bracket immediately before the semi-colon".

It would be great if GCC gave an error like "unmatched bracket" and pointed to the unmatched bracket. Apple are hinting that future clang-based compilers may do this but for now, you get one of these terse errors.

2. Trying to use a forward class

/path/file.m:22: warning: receiver 'Test' is a forward class and corresponding @interface may not exist

This is a simple error but many people (especially those accustomed to other languages that don't have separate declaration and implementation) find it confusing because they may not be certain what a "forward class" is.

I'd like to take this opportunity to tell you: if you don't know what a forward declaration is, or you've never used @class before, you need to read about it. In brief: a @class forward declaration tells the compiler that a given name is a class but avoids the need to import the whole declaration (which would create an undesirable cross-dependency in the header file).

Basic rule: in header files, never #import another class from the same framework/application except the super class — always use an @class forward definition instead. The #import for a class should always be in the implementation (.m) file. Using #import for other frameworks (like #import <Cocoa/Cocoa.h>) is okay.

The cause of this warning is failure to follow the second part of this basic rule: you need to #import the actual definition in your implementation file.

Older versions of GCC (prior to 4.0) didn't always give this warning. The result was that you could accidentally use classes that didn't exist (resulting in runtime crashes). This warning is a big improvement.

3. Recursive headers

/path/file.h:13: warning: duplicate interface declaration for class 'Test'
/path/file.h:15: error: redefinition of 'struct Test'

There are two ways to get this error. The first is mundane: you have declared two classes with the same name — not an Objective-C specific problem.

The second is that you have used #include to import the header declaration instead of #import. This is especially recognizable when you see the error dozens (or hundreds) of times in a row, especially if it is further accompanied by:

/path/file.h:9:35: error: #include nested too deeply

Objective-C expects that all header files are imported using #import which prevents recursive inclusion, so files don't guard against repeat inclusion as they normally do in standard C.

Solution: always use #import to import header declarations (and don't listen to Richard Stallman's rants against the #import keyword — he is... different).

4. Interface not imported

/path/file.m:26: warning: no '-blah' method found
/path/file.m:26: warning: (Messages without a matching method signature
/path/file.m:26: warning: will be assumed to return 'id' and accept
/path/file.m:26: warning: '...' as arguments.)

The mundane explanation is that there is no blah method (you've simply mistyped it).

However, Objective-C provides a few ways to get this error, even when the method does exist.

The class where -blah is defined may not be in the set of imported classes. This can happen when the object you tried to invoke -blah on is declared as an id or the class is only forward declared.
You have imported the base class but the method is declared on a @category, which is not imported.

In either case, the solution is to find the header that defines the method and #import it.

There is one further situation where this error can occur: when there is no implementation of the method at compile-time at all. This can further be broken into two cases:

Runtime handled methods with clear association with a particular class. For example: accessor methods for the attributes of a Core Data NSManagedObjects. For methods like this, you should declare the method in a category (even though there will be no implementation at compile-time) and import this category.
Runtime handled methods with no clear class association. To highlight the runtime and unusual situation involved in this situation you should use [object performSelector:@selector(weirdRuntimeMethod)] instead of writing [object weirdRuntimeMethod] and causing compiler warnings.

5. Multiple, incompatible methods

/path/file.m:24: warning: multiple methods named '-setStringValue:' found

Normally, Objective-C won't complain if there are multiple methods matching a given name (it assumes runtime lookup will work it out) so this warning may be surprising when it occurs.

This type of problem occurs when you have multiple declarations with the same method name but the arguments to the method are different sizes (e.g. one declaration expects a 32-bit long parameter and one declaration expects a 64-bit long parameter). This is important because parameter sizes are fixed at compile-time (runtime lookup can't change it).

The solution is to tell the compiler which method is the correct method by casting your object to the exact class involved. For example:

[(NSXMLNode *)myObject setStringValue:@"value"];

NSXMLNode *myXMLNodeObject = myObject;
[myXMLNodeObject setStringValue:@"value"];

Both of these solutions produce the same compiled output.

6. Accessing a property on the wrong type

/path/file.m:23: error: request for member 'value' in something not a structure or union

This error can occur in standard C code when using struct or union as the error reports.

In Objective-C 2.0, it also occurs when accessing an Objective-C 2.0 property on a class and the compiler can't find the property.

If this error occurs and you have typed the name correctly, you probably need to cast the object to the correct class. i.e. if value is a property of MyClass:

id value = ((MyClass *)object).value;

MyClass *myClassObject = object;
id value = myClassObject.value;

These solutions are, as before, both equivalent.

The other potential cause of this error is that MyClass is not imported correctly, so be certain to check this as well.

7. Implicit downcasting on assignment

/path/file.m:22: warning: initialization from distinct Objective-C type

The mundane cause of this error is that you've tried to assign the return value of a method to an unrelated object type. That's just an error and you need to fix it.

The trickier case is an implicit downcast. By this I mean: the method has returned a super class (like NSObject) but you know it is actually a child class (like MyClass).

In this situation you must explicitly cast:

MyClass *myClassObject = (MyClass *)[someObject getObject];

C++ has the dynamic_cast operator for this type of action, which verifies that myClassObject is correctly a MyClass object. In Objective-C if you're concerned about runtime type, you should use:

NSAssert([myClassObject isKindOfClass:[MyClass class]],
    @"Return value is not of type MyClass as expected.");

You can use your own AssertCast macro to make this operation easier if you do it a lot.

There are two cases where implict casts are allowed:

upcasts (i.e. NSObject *myObject = myClassObject; is okay)
implicit conversions from id to anything (id is the universal object and can be implicitly cast or used as anything)

This error can also occur in the case where the assignment is actually an upcast but the source class has only a forward declaration — so you may also need to import the declaration if it is not imported.

8. Implicit downcasting of parameters

/path/file.m:24: warning: passing argument 1 of 'test:' from distinct Objective-C type

The causes and solutions for this are identical to downcasting on assignment. Cast correctly and import declarations as appropriate.

I know, this warning seems like a duplicate of number 7 but it's a programming blog: I had to have 8 things. In my head, I've stored them all in an array indexed from 0 to 7.

Conclusion

Never be content with warnings in your code. Always work to understand why GCC is issuing the warning and fix your code. Your code will be easier to understand and be safer at runtime.

Using NSKeyedArchiver to archive a C linked-list

2009-03-28T17:37:00.001-07:00

NSKeyedArchiver provides some support for archiving C primitive types but provides no support for pointers to C structs. I'll show you how you can archive a linked list of C structs, despite the lack of support in NSKeyedArchiver.

Standard C

Cocoa contains very little support for standard C data structures. The reason for this is pretty simple: introspection. An Objective-C object can report on what it is, its block size, its ivars and methods. Protocols can be implemented to provide further metadata about the object. With a pointer to an arbitrary block of standard C data, you have no information at all about the type and structure of the block.

While keeping all your data in Objective-C objects works well most of the time, sometimes you'll need to work with standard C data structures — for example when working with data produced by third party libraries.

To show how to use C data structures with libraries that expect Objective-C objects, I'll show you how to archive a linked-list of C structs using NSKeyedArchiver.

Metadata and wrappers

As I mentioned, the real problem with arbitrary C data is that it offers no introspection — we must be able to ask our data about its metadata. Specifically, we will need to know the size of the list node structs (we can copy the whole struct as a block of data) and the offsets within the struct of pointers to other list nodes.

In addition to metadata, we need a way to deal with pointers. NSKeyedArchiver provides no way to encode an arbitrary pointer.

To handle both these problems, the solution will use one Objective-C "wrapper" object to represent each struct, and one extra "context" object to encode data about the overall archive operation.

The context object will encode the size of the struct and byte offsets of each pointer within the struct (since this data is stored once, not per object, we assume that every node in the linked list is the same type).

The wrapper objects for each struct will serve two purposes: they will handle the encoding of each struct's data but they will also act as proxies for the pointers between structs — allowing us to encode pointers to objects (permitted by NSKeyedArchiver) instead of pointers to structs (not permitted).

To allow the wrapper objects to act as proxies for each pointer, we will also need a dictionary that stores the mapping from struct to associated proxy object — this mapping will be held in the context object.

Interface design

@interface BlockWrapper : NSObject <NSCoding>
{
    BlockContext *blockContext;
    void *blockPointer;
}

@property (readonly) void *blockPointer;

- (id)initWithBlockContext:(BlockContext *)aBlockContext
    blockPointer:(void *)aBlockPointer;

@end

The data for the wrapper object is very simple: a blockPointer that points to the data that the object will encode and blockContext which points to the context object for the archive operation.

I decided to name this class BlockWrapper instead of StructWrapper to properly reflect how the class handles the data it wraps — as an arbitrary block of bytes.

@interface BlockContext : NSObject <NSCoding>
{
    CFMutableDictionaryRef blockToBlockWrapperMappings;
    void *startingBlock;
    size_t blockSize;
    NSArray *pointerOffsets;
}

@property (readonly) size_t blockSize;
@property (readonly) void *startingBlock;
@property (readonly, retain, nonatomic) NSArray *pointerOffsets;

- (id)initWithStartingBlock:(void *)aStartingBlock
    blockSize:(size_t)aBlockSize
    pointerOffsets:(NSArray *)aPointerOffsets;
- (BlockWrapper *)wrapperForBlock:(void *)aBlock;

@end

The BlockContext class is fairly straightforward as well: it encodes all the previously discussed metadata about the block.

Since I wanted this code to work for any linked list node, I haven't hard-coded the number or location of pointers within each block — I store the offsets of each pointer as an array.

The wrapperForBlock: will be the correct way to find the BlockWrapper object for any of our list node pointers. This method will return the corresponding BlockWrapper from the blockToBlockWrapperMappings, creating a new BlockWrapper if one does not already exist for the given list node pointer.

Notice that I use a CFMutableDictionaryRef instead of an NSDictionary. This is because the keys in this dictionary will be the pointers to the blocks, not Objective-C objects, and NSDictionary requires that its keys be Objective-C objects. With CFMutableDictionaryRef, we can configure the dictionary to handle raw pointers.

Despite containing all this metadata during the encoding process, for its own encoding, the BlockContext only needs to save the startingBlock and pointerOffsets. The NSKeyedArchiver will implicitly store the blockSize for each encoded block and the mappings from BlockWrapper to pointer.

Encoding and decoding the BlockWrapper

- (void)encodeWithCoder:(NSCoder *)encoder
{
    [encoder encodeBytes:blockPointer length:[blockContext blockSize] forKey:@"block"];
    [encoder encodeObject:blockContext forKey:@"blockContext"];

    NSMutableArray *blockWrapperArray =
        [NSMutableArray arrayWithCapacity:[[blockContext pointerOffsets] count]];

    for (NSNumber *offsetNumber in [blockContext pointerOffsets])
    {
        NSUInteger offset = [offsetNumber integerValue];
        void *childBlock = *(void **)((NSUInteger)blockPointer + offset);
        if (!childBlock)
        {
            [blockWrapperArray addObject:[NSNull null]];
            continue;
        }

        BlockWrapper *childWrapper = [blockContext wrapperForBlock:childBlock];
        [blockWrapperArray addObject:childWrapper];
    }
    
    [encoder encodeObject:blockWrapperArray forKey:@"childBlocks"];
}

Encoding the block itself and storing a pointer to the BlockContext is simple. Most of the work in encoding relates to handling pointers to other nodes:

get each pointer offset
reading the value of the pointer from the block
map the pointer's value to a BlockWrapper object using the blockContext
encoding each referenced BlockWrapper in an NSArray using the childBlocks key

Notice that NULL pointers still require a NSNull object in the childBlocks array so that the indices in this array always correspond to the indices in the pointerOffsets array.

The decode process for BlockWrapper is mostly the same work in reverse: decode the block, decode the reference to the context object and then set all of the pointers according to the decoded childBlocks array.

- (id)initWithCoder:(NSCoder *)decoder
{
    self = [super init];
    if (self != nil)
    {
        NSUInteger blockSize;
        const void *bytes =
            [decoder decodeBytesForKey:@"block" returnedLength:&blockSize];
        blockPointer = malloc(blockSize);
        memcpy(blockPointer, bytes, blockSize);
        
        BlockContext *context = [decoder decodeObjectForKey:@"blockContext"];

        NSArray *childBlocks = [decoder decodeObjectForKey:@"childBlocks"];
        NSArray *pointerOffsets = [context pointerOffsets];
        NSInteger i;
        NSInteger count = [childBlocks count];
        
        NSAssert(count == [pointerOffsets count],
            @"Mismatch between childBlocks and pointerOffsets");
        
        for (i = 0; i < count; i++)
        {
            BlockWrapper *wrapperObject = [childBlocks objectAtIndex:i];
            NSNumber *offsetNumber = [pointerOffsets objectAtIndex:i];
            NSUInteger offset = [offsetNumber integerValue];
            
            void *childPointer = 0;
            if (![wrapperObject isEqual:[NSNull null]])
            {
                childPointer = [wrapperObject blockPointer];
            }
            
            *(void **)((NSUInteger)blockPointer + offset) = childPointer;
        }
    }
    return self;
}

The biggest difference between decoding and encoding is that in decoding, we need to malloc the memory for the list node (pointed to by blockPointer). When encoding, this memory was allocated externally before we began.

The result is that the code which unarchives the linked list is also responsible for free-ing it.

Conclusion

Download the complete solution (which includes a trivial sample program) LinkedListCoding.zip (48kB)

This solution will let you archive an arbitrary linked list of C structs using NSKeyedArchiver. The solution does make some assumptions — specifically, your list nodes must all be the same type and the only pointers must point to other list nodes or NULL. Other list arrangements would require changes to the solution.

Of course, this solution is not as elegant as avoiding linked lists altogether. If you have control over the code and it's simple enough, storing NSObject in an NSMutableArray is much better supported by Cocoa.

Recreating UITableViewController to increase code reuse

2009-03-22T19:33:00.001-07:00

UITableViewController and UIViewController are the two most commonly implemented controllers on the iPhone. It may not always be clear what UITableViewController adds to its superclass. I'll show you what UITableViewController does by recreating its functionality on top of UIViewController and show you why doing this can provide a richer base controller class that you can use throughout your iPhone application.

This week, an iPhone app

In this post, I'll present a small iPhone application that displays the time in a table on the front screen, with detail screens for each component when the respective row is clicked.

("second" shown on the right is the unit of time, not the 2nd row)

With this application, the code to monitor the time and update when it changes is in a base class common to both the UITableView's controller (left) and the UIView's controller (right).

If you followed the standard practice of using UITableViewController subclasses for UITableView-based screens and UIViewController subclasses for all other screens, keeping this code common would not be possible. I'll show how to make it possible by recreating the functionality of UITableViewController in your own UIViewController subclasses.

UITableViewController versus UIViewController

Between UITableView and navigation-based controllers, Apple did an excellent job of establishing a standard interaction paradigm for the iPhone. This established standard works so well that programmers use UITableViewController for most screens in their programs.

UITableViewController makes the simple, common case easier but it creates a problem if your program needs shared functionality between table view and views based on UIViewController (where self.view is not a UITableView). The problem is that common functionality for screens in your program must now be duplicated — once to include this functionality in your UIViewController subclass and once to include the functionality in your UITableViewController subclass.

My preferred solution to this problem is to create my own program-wide base class which is a subclass of UIViewController. I put my common code in the base class and when I need a controller for a UITableView, recreate the work done by UITableViewController in a subclass of my own base class which can then be the base class for all UITableView controllers in my program.

Recreating UITableViewController

To recreate it, we need to know what UITableViewController does. Given the class' ubiquity, it may be surprising to learn that it doesn't do very much.

As detailed in the API documentation, UITableViewController adds the following functionality:

A constructor (initWithStyle:) that sets the style for the default contructed table (if the table isn't constructed from a NIB file).
An implementation of loadView that creates the default table if the view controller is used without a NIB file.
Implementation of the tableView property.
Includes the UITableViewDelegate and UITableViewDataSource properties but doesn't provide any implementations of the methods.
Invokes setEditing:animated: on the UITableView when it is invoked on the controller.
Reloads the table data and clears the selection in viewWillAppear:.
Flashes the scroll indicators of the table in viewDidAppear:.

I personally consider some of these "optional" and normally leave them out unless I need to use them. I normally leave out the reloading of table data altogether as I feel application logic can handle this more efficiently. What follows are the essential methods.

An implementation of loadView looks like this:

- (void)loadView
{
    if (self.nibName)
    {
        [super loadView];
        NSAssert(tableView != nil, @"NIB file did not set tableView property.");
        return;
    }
    
    UITableView *newTableView =
        [[[UITableView alloc]
            initWithFrame:CGRectZero
            style:UITableViewStylePlain]
        autorelease];
    self.view = newTableView;
    self.tableView = newTableView;
}

I've hard-coded the UITableViewStyle here instead of relying on a initWithStyle: constructor. Since this is my code, I'm happy to select the default value I want for my program here, I don't need to specify this value at initialization.

Notice that I set the self.view and the self.tableView separately. In UITableViewController, these two properties are always the same value. I like to keep a distinction between the two in my UITableView controller so that my controller can manage a wrapper view around the table view as well. Obviously in this default case, there is no wrapper, so both are set to be the same. If there were both the same, I wouldn't need the tableView ivar (see accessors below) I would use the same self.view storage for both.

The only other default code required are the tableView and setTableView: methods for the tableView property. The only important steps here are to set the table's delegate and dataSource to the controller.

- (UITableView *)tableView
{
    return tableView;
}

- (void)setTableView:(UITableView *)newTableView
{
    if ([tableView isEqual:newTableView])
    {
        return;
    }
    [tableView release];
    tableView = [newTableView retain];
    [tableView setDelegate:self];
    [tableView setDataSource:self];
}

The time display application

In the sample app, my BaseViewController (a subclass of UIViewController) contains methods that start an NSTimer when the view appears and stop it when the view disappears.

This timer fires the following method:

- (void)timerUpdate:(NSTimer *)aTimer
{
    NSDate *date = [NSDate date];
    NSCalendar *calendar = [NSCalendar currentCalendar];
    
    const NSInteger unitFlags =
        NSHourCalendarUnit | NSMinuteCalendarUnit | NSSecondCalendarUnit;
    NSDateComponents *components =
        [calendar components:unitFlags fromDate:date];
    
    if (![components isEqual:lastComponents])
    {
        [lastComponents release];
        lastComponents = [components retain];
        [self updateWithDateComponents:components];
    }
}

The updateWithDateComponents: is empty but subclasses of BaseViewController can implement it to update themselves when the time changes. In this way, every screen in my application automatically receives per-second updates.

The TimeTableViewController in the application is then a subclass of BaseViewController which further adds UITableViewController-like functionality (as shown above) and combines the two to constantly update the time components in the table.

The DetailViewController (which is constructed when a row is clicked) is also a subclass of BaseViewController but when an updateWithDateComponents: message is received, only displays the component for which it is the "detail" view.

Conclusion

You can download the complete code for the RecreatingTableViewController application (29kB) discussed in this post.

UITableViewController exists to make working with simple tables slightly quicker, since they are the most common type of primary view on the iPhone.

However, this class is merely a convenience and if your design requires it you can avoid UITableViewController entirely — as in this post where the inheritance worked better without using UITableViewController.

Scripted window management in Xcode

2009-03-13T21:34:00.001-07:00

Xcode's placement of windows and views has never entirely satisfied me. In this post, I'll show you a series of Applescripts that I use to create my own arrangement of Xcode windows so that I can choose where different kinds of documents are placed and reorganize the layout of windows with basic key commands.

Xcode's window layout options

To show multiple files in Xcode's "Default" or "All-in-one" you need to open a second window since Xcode's project window does not support two neat column panes in the project window [edit: Yes it does. See first the first comment.]. This bothers me because I like to keep my windows tidy, so I found myself manually positioning these external windows a lot.

Furthermore, if you have positioned your main project window to look pretty when showing an 80 to 120 character width text document, opening a fundamentally different kind of document in the window (like a Core Data .xcdatamodel) requires that you resize the project window to view the new document properly and resize back again when done.

I could use the "Condensed" layout that Xcode provides which puts everything in a separate window by default — but this doesn't solve the "manual repositioning" problem and puts extra columns into the tree-view of the project window which I find cluttering and unnecessary.

Choose your own layout

In an effort to address all the things I dislike about Xcode's default layouts, I decided to create a series of Applescripts that would position windows where I want them and could do so based on the type of window (source document, Find results, Build results, Core Data .xcdatamodel, etc). The result is a "virtual" all-in-one window where the panes are positioned according to my choices and I can shift documents from the left-column to the right column or to fullscreen with a basic key command.

Here's a screenshot of my layout showing two edit windows in columns and the project window on the left:

I clearly use a minimalist layout but the approach I will present could be used to put find and build results at the top of one column and reserve the second column for the debugger and console.

The Xcode layout required is the "Default" layout but I collapse the Project window down to just the tree-view by double-clicking the "double-vertical-bar-and-arrow" icon at the right of the tree-view header.

Keyboard shortcuts and working without the toolbar

The only two toolbar items I use are the "Build Configuration" and "Active SDK" popup menus. I use the standard set in the Debug Window but for building I consider it a waste of time. There are only a few keyboard shortcuts you need for Xcode and you really should know them:

⌘Y — Build and Debug. This should be your most-used key command.
⌘⇧D — Open a file by name. Much faster than using the Project Tree for large projects.
⌘⇧Y — Show the Debug Window.
⌘⇧F — Show the Find Window.
⌘⇧R — Show the Run Console.
⌘+option+W — Close all windows of the current type (fast way to close all source windows)
F10 (or Control + Dashboard button on new keyboards) — Show the current app's windows.

To this collection of keyboard shortcuts, I'll add the following:

⌘1 —Position the front-most window in the first column.
⌘2 —Position the front-most window in the second column.
⌘3 —Position the front-most window filling the first and second columns.
⌘4 —Reposition all windows based on type.

The positioning scripts

The following is the Xcode user script for positioning the front-most window in the first column:

#! /usr/bin/osascript

set screenWidth to 1680
set screenHeight to 1050
set dockBottomPadding to 73
set dockLeftPadding to 0
set dockRightPadding to 0

set projectWindowWidth to 300
set menubarHeight to 22

set docWidth to (screenWidth - dockLeftPadding - dockRightPadding - projectWindowWidth) / 2
set leftDocBounds to {dockLeftPadding + projectWindowWidth, dockBottomPadding, screenWidth - dockRightPadding - docWidth - 1, screenHeight - menubarHeight}

tell application "Xcode"
    set bounds of item 1 of windows to leftDocBounds
end tell

To make this work, add it to your Xcode User Scripts as Input=No Input, Directory=Selection, Output=Discard Output, Error=Display in Alert. I then set the shortcut to ⌘1. If you've never added an Xcode User Script before, I explain the process more thoroughly in an earlier post.

Since it is difficult to get the actual screen size using Applescript (see John Gruber's pain in trying) I've hardcoded my screen size into the script. Change the width and height if your screen is a different size and change the dock padding values if your dock is a different height or placement.

This much is fairly simple. Much more interesting is the "reposition everything" script:

#! /usr/bin/osascript

set screenWidth to 1680
set screenHeight to 1050
set dockBottomPadding to 73
set dockLeftPadding to 0
set dockRightPadding to 0

set projectWindowWidth to 300
set menubarHeight to 22

set docWidth to (screenWidth - dockLeftPadding - dockRightPadding - projectWindowWidth) / 2
set projectBounds to {dockLeftPadding, dockBottomPadding, projectWindowWidth + dockLeftPadding - 1, screenHeight - menubarHeight}
set leftDocBounds to {dockLeftPadding + projectWindowWidth, dockBottomPadding, screenWidth - dockRightPadding - docWidth - 1, screenHeight - menubarHeight}
set rightDocBounds to {screenWidth - dockRightPadding - docWidth, dockBottomPadding, screenWidth - dockRightPadding - 1, screenHeight - menubarHeight}
set fullDocBounds to {dockLeftPadding + projectWindowWidth, dockBottomPadding, screenWidth - dockRightPadding - 1, screenHeight - menubarHeight}

tell application "Xcode"
    set leftHalfScreenSuffixes to {"m", "c", "h", "mm", "cpp"}
    set rightHalfScreenSuffixes to {"Results", "Find", "Console"}
    set fullScreenSuffixes to {"xcdatamodel", "Debugger"}
    set processedWindows to {}
    repeat with doc in documents
        set docName to name of doc
        if (length of docName) is greater than 10 then
            set docNameMinusExtension to text 1 thru ((length of docName) - 10) of docName
        else
            set docNameMinusExtension to ""
        end if
        repeat with win in windows of doc
            set n to name of win
            try -- wrap in a try in case the window name is undefined
                set end of processedWindows to name of win
                if n is equal to docNameMinusExtension then
                    set bounds of win to projectBounds
                else
                    set extension to last item in words of n
                    if extension is in leftHalfScreenSuffixes then
                        set bounds of win to leftDocBounds
                    else if extension is in rightHalfScreenSuffixes then
                        set bounds of win to rightDocBounds
                    else if extension is in fullScreenSuffixes then
                        set bounds of win to fullDocBounds
                    end if
                end if
            end try
        end repeat
    end repeat
    repeat with win in windows
        if not (processedWindows contains name of win) then
            set n to name of win
            try -- wrap in a try in case the window name is undefined
                set extension to last item in words of n
                if extension is in leftHalfScreenSuffixes then
                    set bounds of win to leftDocBounds
                else if extension is in rightHalfScreenSuffixes then
                    set bounds of win to rightDocBounds
                else if extension is in fullScreenSuffixes then
                    set bounds of win to fullDocBounds
                end if
            end try
        end if
    end repeat
end tell

This script iterates over the windows for each document, then over all windows not attached to a document to reach every window that Xcode has open. It then uses the window's title to decide where to place each window. Source code files are placed in the first column, results windows are placed in the second column and the Debugger is made dual column. This script also positions the Project window.

The "position in the second column" and "position filling first and second columns" scripts are just like the first script but with rightDocBounds and fullDocBounds from the second script respectively.

Conclusion

A few scripts to reposition your windows and connected to the shortcuts ⌘1 to ⌘4 is not a revolutionary idea but I don't think I was alone among Xcode programmers in continuously repositioning my windows as I opened and shut new documents and switched from debugging to editing to build results and back.

These scripts only save a few seconds at a time but they make Xcode feel much more magical as windows jump to exactly where I want them to be.

I doubt everyone will want to position their windows exactly as I have but these scripts should be easily adaptable to a range of different layouts — just tweak the calculated bounds and the sets of Window suffixes that are placed at each bounds.

An Asteroids-style game in CoreAnimation, Part Four.

2009-03-08T15:41:00.001-07:00

Over the last three weeks, I presented a simple 2D game using CoreAnimation. For the final post in this series, I'll look at CATransactions and why I didn't use them in the game to handle animations and I'll look at the performance of CoreAnimation as numbers of CALayers and sizes of CALayers change.

Frame-based animation

The Quartzeroids2 game (download the complete code from the previous post) uses traditional frame-based updates to process, position and render all objects on screen. This works much like stop-motion animation as filmed with optical cameras: a frame is needed approximately every 30th of a second so the game moves all objects to their locations for this new frame (as determined by speed and trajectory) and the renderer takes a snapshot.

As with stop-motion animation, the only reason this process appears smooth to the eye is because the frames are frequent enough that they run together appearing like motion.

This is the traditional way that 2D games are implemented. Initially though, I wanted to handle the game in a different way. Frame-based animation has two main problems:

The CPU must reprocess all game objects 30 times a second (or more) to place them on screen, creating a continuous burden on the CPU.
Even at 30 frames a second, fast moving objects leave distinct gaps which can cause problems with collision detection.

The following diagram illustrates the second point:

The blue and red balls never touch during a keyframe but if they were moving continuously would clearly collide in the middle. Such collisions could be detected by significantly increasing the frame-rate but that isn't always technically possible and would certainly make the first problem (excessive CPU usage) worse.

Continuous animation using CATransactions

What I wanted to do instead of frame-based animation was to create a continuous game instead.

The idea would be: instead of the game engine reprocessing for each frame, just load the speeds and trajectories into CoreAnimation and let the animation run automatically until the next "event" (collision or user action). That way, the animation runs smoothly, the game engine performs the minimum amount of work and all collisions are mathematically perfect (since we calculate them in advance using trajectory equations instead of reading quantized data at frame update time).

Continuous animation would involve taking the basic line equation (y = mx + b) for the two bounding edges of each object's trajectory and colliding it with the bounding box of the screen and every other object's trajectory equations. Between now and that first collision each object could be animated using a CoreAnimation CAAnimation, with the animations for all objects tied together using a CATransaction.

The first downside to this was adding user involvement. When the user presses a key, they are changing the modelling for their player object which involves recalculating the next collision. This means that while the user is pressing a key, 30 recalculations per second may be required. On its own, this negative won't outweigh the positives. Recalculating in his manner isn't much more work than traditional frame-based collision detection which is always performed 30 frames-per-second or more — and these collisions would still be mathematically perfect.

Testing CATransactions

To see how the worst case of 30 updates per second would perform, you can add CATransaction-based animation to Quartzeroids2 by removing the actionForKey: method from "ImageLayer.m" in the program and replacing the following code in "GameObjectLayer.m":

self.imageName = gameObjectImageName;
self.bounds = CGRectMake(0, 0, width, height);
self.position = CGPointMake(x, y);
self.transform = CATransform3DMakeRotation(angle, 0, 0, 1.0);
self.hidden = !visible;

with the CATransaction based version:

double distance =
    sqrt((self.position.x - x) * (self.position.x - x) +
    (self.position.y - y) * (self.position.y - y));
BOOL wrapping = distance > gameHeight;

if (wrapping)
{
    [self removeAllAnimations];
}

[CATransaction begin];
[CATransaction
    setValue:[NSNumber numberWithDouble:GAME_UPDATE_DURATION]
    forKey:kCATransactionAnimationDuration];

if (wrapping)
{
    [CATransaction
        setValue:[NSNumber numberWithBool:YES]
        forKey:kCATransactionDisableActions];
}

self.imageName = gameObjectImageName;
self.bounds = CGRectMake(0, 0, width, height);
self.position = CGPointMake(x, y);
self.transform = CATransform3DMakeRotation(angle, 0, 0, 1.0);
self.hidden = !visible;

[CATransaction commit];

Performance-based failure

The following performance numbers are running on my 2 x 2Ghz PowerMac G5.

Number of CALayers animated using CATransaction	Frames per second
50	> 33
75	10-25
100	<10
150	<2

I've given ranges since the frames per second varied significantly. This compares poorly with the CATransaction disabled version, where all tests ran faster than 30 frames per second.

Since each asteroid represents two separate objects and every shot fired is another object on screen, I decided that an inability to handle more than 50 objects smoothly was unacceptable and discarded the CATransaction-based approach.

Clearly, CATransaction-based animation has a significant amount of work to perform and this work increases more-than-linearly (greater than O(n)) with respect to the number of objects on screen. In CoreAnimation, you aren't expected to regenerate thousands of animations each second like this. I leave open the possibility that there's a modified approach that could still make this work but I didn't want to spend further time investigating.

Testing the render system in Quartzeroids2

To perform a series of performance tests on Quartzeroids2's rendering system, I removed the PlayerObject from the game, disabled the AsteroidLayerObject added for each asteroid by the GameController and used the ASTEROID_LARGE_SIZE and ASTEROID_BASE_NUM values to control the size and number of objects on the screen. I measured frame rates with the Quartz Debug frame meter.

Object size tests

The following test all involved 100 CALayers on screen. My graphics card is an ATI Radeon X800 with 256MB VRAM.

Width and Height of CALayer in pixels	Frames per second
110	> 33
440	> 33
660	> 33
770	> 33
880	< 5

Once you exceed the available video memory in CoreAnimation, frame rate immediately plummets. Some new Macs have double the VRAM that I have but many still ship with 256MB VRAM as standard, so these numbers are probably indicative of the average among newer machines.

Object count tests

The following tests all involved 11 pixel by 11 pixel objects.

Number of CALayers on screen	Frames per second
100	> 33
200	> 33
300	> 33
400	20
500	18
600	12
700	9
800	< 5

Profiling the 800 object version revealed CPU time was mostly spent in CALayer updating layer positions — so this would appear to be a basic CPU bound situation for CoreAnimation on the test machine. On newer Mac Pros, I wouldn't be surprised if object counts over 1000 were possible at 30 frames per second.

Other CALayer limitations

Depending on your graphics card, you may have a maximum texture size. On my ATI Radeon X800, that size is 2048 by 2048. Any texture bigger than 2048 in any CALayer with a native size bigger than 2048 in any direction will result in an empty white square when rendered, instead of the expected texture. CALayer does output an error when this occurs:

CoreAnimation: 2049 by 2049 image is too large for GPU, ignoring

Newer cards have maximum texture sizes of 4096 and even 8192 pixels. A hard limit here for your target systems could be difficult to know.

Conclusion

CoreAnimation is incredibly capable as a 2D renderer. I have spent this post discussing its limits but that is not because I consider its capabilities limiting but because I am impressed by how much it can do. With CoreAnimation layers, you can render hundreds of objects, each of which can be hundreds of pixels big, without paying any attention to performance — you can simply let CoreAnimation handle it.

Obviously, for the Quarteroids2 game I developed, most of this testing was irrelevant but it may prove useful to anyone looking to use CoreAnimation in a more ambitious manner.

An Asteroids-style game in CoreAnimation, Part Three.

2009-03-01T02:05:00.001-08:00

How would you write an arcade-style 2D game in CoreAnimation? I'll show you how to write a resolution independent, high-speed, model-view-controller designed, Asteroids-style arcade game using CoreAnimation as the screen renderer. In this third of four parts, I add the logic for the game and game objects and present the finished code for the project.

From renderer to game

In the previous post, I presented a rendering system using CoreAnimation layers (CALayer). To complete the game, we now need to add the game logic.

For this Asteroids-style game, the game logic will be very simple but will need to include the following components:

User control of the ship
Shooting and shot/asteroid collision detection and destruction.
Player/asteroid collision and a finite number of player "lives"
Level logic, so that a new, harder level is started when the previous one is cleared.

With the game logic added, the code for the project will be complete.

A screenshot of the game with shots and asteroid destruction.

User control

Most games treat keyboard input in a different manner to applications. Instead of reading keyDown: messages, including the isARepeat messages (whose delay and frequency are specified in the System Preferences), games simply want the state of specific keys at a given time. e.g. "Is the 'thrust' key pressed?"

To provide the game with what it wants, I created a subclass of NSView to use as the contentView of the window. The sole purpose of this view subclass is to read key event messages passed to the window. When keyDown: messages are received, boolean values on the GameData object are set. When the keyUp: message is received, the boolean values are cleared. In this way, we store the keyboard state so we can read it in an asynchronous manner whenever it is needed.

The implementation of the keyDown: method follows.

- (void)keyDown:(NSEvent *)event
{
    NSString *characters = [event characters];
    if ([characters length] == 1 && ![event isARepeat])
    {
        const NSInteger ESCAPE_KEY_CODE = 27;
        
        unichar character = [characters characterAtIndex:0];
        if (character == NSLeftArrowFunctionKey)
        {
            [[GameData sharedGameData] setLeftKeyDown:YES];
        }
        else if (character == NSRightArrowFunctionKey)
        {
            [[GameData sharedGameData] setRightKeyDown:YES];
        }
        else if (character == NSUpArrowFunctionKey)
        {
            [[GameData sharedGameData] setUpKeyDown:YES];
        }
        else if (character == ' ')
        {
            [[GameData sharedGameData] setShootKeyDown:YES];
        }
        else if (character == ESCAPE_KEY_CODE)
        {
            [gameController togglePause:self];
        }
    }
}

Notice that Apple provide constants for higher level keys (like the arrow keys) but you are expected to handle ASCII codes (like the Escape key) yourself. You can get these from the ASCII manual page (man ascii in a terminal window). Be careful to avoid the octal set — I have no idea how it earned first position in this file.

To respond to these new keyboard flags, I will create a subclass of GameObject (the generic class representing an object in the game) named PlayerObject to handle the player's ship. The real purpose of this subclass will be to add game-logic related behaviors. The primary location for adding behaviors will be an override of the parent class' updateWithTimeInterval: that supplements the default behavior with player-specific movement and interaction.

Here is the code to handle the "thrust" key (the up arrow):

if ([GameData sharedGameData].upKeyDown)
{
    double scaledAcceleration = timeInterval * PLAYER_ACCELERATION;
    double dX = speed * cos(trajectory) + scaledAcceleration * cos(angle + M_PI_2);
    double dY = speed * sin(trajectory) + scaledAcceleration * sin(angle + M_PI_2);
    
    speed = sqrt(dX * dX + dY * dY);
    trajectory = acos(dX / speed);
    if (dY < 0)
    {
        trajectory *= -1;
    }
    
    if (speed > PLAYER_MAX_SPEED)
    {
        speed = PLAYER_MAX_SPEED;
    }
}

This code is some basic trigonometry to add the ship's current speed/trajectory vector to the new thrust vector, limiting the ship's maximum speed. The actual x and y of the ship is modified by invoking the super implementation (which applies this speed and trajectory).

Model-view-controller design note
This approach to key control is not typical of an application. In an application, a user-interface controller chooses the target object and sends the keyboard control directly to that object. In this game, the user-interface sets keyboard state in a game-accessible location and game objects choose whether to incorporate that state into their own. This behavior is good for a game because it allows the game objects to choose their own interaction logic but games represent a special case in this regard.

Firing shots

The other key aspect of user control in the game is the ability to fire shots.

Once again, I will use a GameObject subclass to handle the shots. These ShotObjects will be created in the PlayerObject's updateWithTimeInterval: method, since they will need to incorporate speed and trajectory information from the PlayerObject.

The following code fires a shot when the user presses the 'shoot' key (spacebar).

ShotObject *newShot =
    [[ShotObject alloc]
        initWithX:x + 0.5 * width * cos(angle + M_PI_2)
        y:y + 0.5 * height * sin(angle + M_PI_2)];
[[GameData sharedGameData]
    addGameObject:newShot
    forKey:[[GameData sharedGameData] keyForShotAtIndex:nextShotIndex]];

nextShotIndex = (nextShotIndex + 1) % PLAYER_MAX_SHOTS;
[[GameData sharedGameData]
    setGameDataObject:[NSNumber numberWithInteger:nextShotIndex]
    forKey:GAME_DATA_NEXT_SHOT_INDEX_KEY];

double dX = speed * cos(trajectory) + PLAYER_SHOT_SPEED * cos(angle + M_PI_2);
double dY = speed * sin(trajectory) + PLAYER_SHOT_SPEED * sin(angle + M_PI_2);
double shotSpeed = sqrt(dX * dX + dY * dY);
double shotTrajectory = acos(dX / shotSpeed);
if (dY < 0)
{
    shotTrajectory *= -1;
}
newShot.speed = shotSpeed;
newShot.trajectory = shotTrajectory;

shotCooldown = PLAYER_SHOT_COOLDOWN;

The initWithX:y: line creates the ShotObject.

The addGameObject:forKey: part adds it to the game. GameObjects are all stored by a single key in this game but I use the keyForShotAtIndex: to create this key from a prefix ("shot") and a suffix (the shot's index) so that I can extract information about the object from its key.

This is a lazy approach to organizing game objects and any larger game would want to store its objects in a more metadata rich storage system. Better organizations might include:

metadata methods on each game object so you can query each object about what it is
additionally storing game objects in dictionaries keyed by type or other essential category information
storing game objects in richly indexed system like an SQLite database (which is then accessible by any column)

The setGameDataObject:forKey: line sets the number of shots that the player has fired in the GameData's generic object storage. This will allow us to limit the number of shots fired by the player to PLAYER_MAX_SHOTS.

The next code is some more trigonometry to apply the ship's speed and trajectory to the shot. Then finally the shotCooldown value is set. This is a simple counter (decremented on each updateWithTimeInterval:) which will prevent another shot being fired while it is greater than zero (allowing us to set the minimum time between shots).

Collisions

Last week's code contained a very simple main update loop that called the updateWithInterval: method on all GameObjects. This time, we expand the update loop to the following:

- (void)updateLevel:(NSTimer *)aTimer
{
    if (lastUpdate)
    {
        frameDuration = [[NSDate date] timeIntervalSinceDate:lastUpdate];
        [lastUpdate release];
        lastUpdate = [[NSDate alloc] init];
    }
    else
    {
        frameDuration = GAME_UPDATE_DURATION;
    }
    
    NSArray *allKeys = [gameObjects allKeys];
    for (NSString *gameObjectKey in allKeys)
    {
        [gameObjects willChangeValueForKey:gameObjectKey];
        GameObject *gameObject = [gameObjects objectForKey:gameObjectKey];
    
        if ([gameObject collide])
        {
            [gameObjects removeObjectForKey:gameObjectKey];
        }
    }
    for (NSString *gameObjectKey in allKeys)
    {
        GameObject *gameObject = [gameObjects objectForKey:gameObjectKey];
        if (!gameObject)
        {
            [gameObjects didChangeValueForKey:gameObjectKey];
            continue;
        }
        
        if ([gameObject updateWithTimeInterval:frameDuration])
        {
            [gameObjects removeObjectForKey:gameObjectKey];
        }
        [gameObjects didChangeValueForKey:gameObjectKey];
    }
}

We time the duration between updates ourselves, even though we ask the NSTimer to invoke us every 0.03 seconds. This allows us to keep the animation as smooth as possible even if the timer is delayed or frames start taking longer than 0.03 seconds to complete.

After this, we iterate over all the GameObjects twice: once to process collisions and once to update positions. The reason for this separation is to ensure that all of the game objects are at the same moment in time when we process them for collisions — if we processed collisions during the update of positions then everything already updated for position would be 1 frame ahead of objects not yet processed when collisions are tested.

I chose to perform collisions before the update so that the collision applies to what the user can currently see (rather than what they will see after CoreAnimation updates).

Performing collisions is very simple — especially in this game since I'm only performing bounding box collisions. The collision code in ShotObject which tests for collisions between shots and asteroids follows.

- (BOOL)collide
{
    NSString *collision = [[[GameData sharedGameData]
            collideObjectsWithKeyPrefix:GAME_ASTEROID_KEY_BASE
            withObjectForKey:keyInGameData]
        anyObject];
    if (collision)
    {
        [AsteroidObject spawnNewAsteroidsReplacing:collision];
        return YES;
    }
    return NO;
}

Once again, I'm using the prefix metadata in my game object keys to select asteroids for collisions.

The collision code lives on the GameData class.

- (NSSet *)collideObjectsWithKeyPrefix:(NSString *)prefix withObjectForKey:(NSString *)testObjectKey
{
    GameObject *testObject = [gameObjects objectForKey:testObjectKey];
    NSMutableSet *result = [NSMutableSet set];
    
    NSRect testRect = NSMakeRect(
        testObject.x - 0.5 * testObject.width,
        testObject.y - 0.5 * testObject.height,
        testObject.width,
        testObject.height);
    
    for (NSString *gameObjectKey in gameObjects)
    {
        if ([gameObjectKey isEqualToString:testObjectKey] ||
            [gameObjectKey rangeOfString:prefix].location != 0)
        {
            continue;
        }
        
        GameObject *gameObject = [gameObjects objectForKey:gameObjectKey];
        NSRect gameRect = NSMakeRect(
            gameObject.x - 0.5 * gameObject.width,
            gameObject.y - 0.5 * gameObject.height,
            gameObject.width,
            gameObject.height);
        
        if (NSIntersectsRect(gameRect, testRect))
        {
            [result addObject:gameObjectKey];
        }
    }
    
    return result;
}

This code creates a bounding rectangle from the GameObject specified by the testObjectKey and collides it with all objects stored by keys starting with prefix that aren't the testObject itself.

This code returns the whole set of colliding objects — overkill since the game only ever uses one at a time — but functional and easily fast enough for our purposes.

Tying it all together

We can control the ship, shoot and hit asteroids. There's a bit more that's in the game that you can see if you want:

The shots animate through 5 frames and expire after a fixed amount of time. I chose to store the current animation frame in the game data and handle the animation there (instead of in the view like the asteroid animation was in the last post). I wanted to show that animation state could be part of the game data if it is data-related (this animation isn't really data-related so I have some regrets).
The asteroids start at random locations in a ring around the player for each level and spawn 3 smaller asteroids when shot, each of which travels in a random direction with a random rotation.

Instead of dwelling on that, I'll jump to the last part of the game logic: the game (including lives) and the levels.

I want the following behaviors in the game:

The player begins with 3 lives at level 1.
Each level starts with a "Prepare for level X..." message for a few seconds before displaying the contents of the level and starting normal play.
Every time the player loses a life (collides with an asteroid) the game displays an "X lives remaining..." message for a few seconds before positioning the player in the middle of the screen and starting normal play again.
When the number of lives hits zero, a "Game Over" message is displayed and the game is stopped.

The data containing the number of lives and the current level are just objects in the gameData dictionary. Creating a new level creates (3 + levelNumber) asteroids and places the player in the center. The messages are just a string, set using a specific GAME_DATA_MESSAGE_KEY, also on the gameData dictionary. These values are displayed by using bindings to connect them to ordinary NSTextFields in the window.

More interesting is that the game needs to change its underlying behavior when the player dies or a new level begins.

The solution I chose is to maintain two different update loops for the two basic behaviors. The updateLevel: method I've already shown is the "normal" update method. A second update method named readyCountdown: will be used to do nothing (not update the GameObjects) for a few seconds while a message is displayed, before returning to the regular update method.

Along with newGame, newLevel and endGame methods, the game now has the ability to transition between different gameplay states.

Conclusion

Download the complete, finished game Quartzeroids2.zip (239 kB).

With the window and design from the first part, the rendering and layers from the second part and now the game logic, the game is complete. Download it, build it, play it and be underwhelmed by its simplicity.

In the final part, I'll present analysis of CoreAnimation's utility as a game rendering engine. I'll look at some features of CoreAnimation that I didn't use, including features that impacted negatively on performance. I'll also look at how CoreAnimation performance changes as the number of render objects is increased.

An Asteroids-style game in CoreAnimation, Part Two.

2009-02-22T19:49:00.001-08:00

How would you write an arcade-style 2D game in CoreAnimation? I'll show you how to write a resolution independent, high-speed, model-view-controller designed, Asteroids-style arcade game using CoreAnimation as the screen renderer. In this second of four parts, I'll create basic objects in the game and their corresponding CoreAnimation Layers on screen.

We have a window

In the previous post I proposed an Asteroids-style game in CoreAnimation and explained the basic design of the Quartzeroids2 game

I showed the code to construct and scale the window. It has a blue gradient background and can switch between fullscreen and windowed modes.

Now, we need to put something in that window.

Objects placed on screen in this part.

Image Layers

Drawing in the window is done using CoreAnimation layers. If you looked closely at how the window background was drawn in Part One, you'll notice that it was a CALayer, drawn using a single image:

NSImage *image = [NSImage imageNamed:imageName];
[image
    drawInRect:NSRectFromCGRect([self bounds])
    fromRect:[image alignmentRect]
    operation:NSCompositeSourceOver
    fraction:1.0];

Since this single image is a PDF made from vector (not bitmapped) components, this means that the layer can be drawn at any resolution without aliasing effects from resizing. In fact, the background PDF isn't even the right aspect ratio and Cocoa happily reshapes it for us. The added processing time to render a PDF, relative to bitmap, doesn't really matter since CoreAnimation only renders the CALayer once, then reuses the existing texture.

Game Objects and Layers

Placing a game-related object on screen will require two different components: the GameObject and the GameObjectLayer.

GameObject

The GameObject is the version of the object as handled in the GameData. Since the game logic is responsible for deciding the size, positioning, speed, trajectory and in some cases the image and angle of rotation of the object, these properties will all be properties of the GameObject.

The GameObjects are held by the GameData object. It tracks all of the GameObjects in a dictionary, so all GameObjects can be accessed at any time by their unique key in the GameData's gameObjects dictionary.

Resolution independence:
The biggest quirk about how I decided to implement the GameObject is that it is totally resolution independent. All coordinates and sizes are measured in units where 1.0 is the height of the game window. So the coordinates (0, 0), (0.5 * GAME_ASPECT, 0.5) and (GAME_ASPECT, 1.0) are the bottom-left corner, center and top-right corners of the screen respectively (GAME_ASPECT is the window aspect ratio: width of the window divided by the height).

With the GameObject being just a long list of Objective-C properties, most of the code in GameObject exists to set, modify or update those properties. The biggest common "update" that needs to be performed is to move the object according to its speed and trajectory and "wrap" the object if it goes off the edge of the screen:

- (BOOL)updateWithTimeInterval:(NSTimeInterval)timeInterval
{
    x += timeInterval * speed * cos(trajectory);
    y += timeInterval * speed * sin(trajectory);
    
    if (x > GAME_ASPECT + (0.5 + GAME_OBJECT_BOUNDARY_EXCESS) * width)
    {
        x = -0.5 * width;
    }
    else if (x < -(0.5 + GAME_OBJECT_BOUNDARY_EXCESS) * width)
    {
        x = GAME_ASPECT + 0.5 * width;
    }
    
    if (y > 1.0 + (0.5 + GAME_OBJECT_BOUNDARY_EXCESS) * height)
    {
        y = -0.5 * height;
    }
    else if (y < -(0.5 + GAME_OBJECT_BOUNDARY_EXCESS) * height)
    {
        y = 1.0 + 0.5 * height;
    }
    
    return NO;
}

This method returns "NO" to indicate that it was not deleted during the update. This won't be used until next week when we add more of the game logic.

The objects are allowed to exceed the edge of the bounds by GAME_OBJECT_BOUNDARY_EXCESS. This ensures that they don't feel like they disappeared with a tiny portion still onscreen.

GameObjectLayer

The GameObjectLayer is a subclass of ImageLayer, using that class' code to render a single image to a CALayer. A GameObjectLayer contains a key that identifies its corresponding GameObject in the GameData. It observes the GameData's gameObjects dictionary for changes on that key and when any of the observed GameObject properties change, the GameObjectLayer will update itself accordingly.

The result is that the only substantial work required in the GameObjectLayer is updating itself when a change in the GameObject is observed.

The GameObjectLayer's observeValueForKeyPath:ofObject:change:context: method is smart enough to realize when the GameObject changes to NSNull (i.e. is deleted) and autodeletes.

- (void)update
{
    GameObject *gameObject = [[[GameData sharedGameData] gameObjects] objectForKey:gameObjectKey];
    double gameHeight = [[GameData sharedGameData] gameHeight];

    NSString *gameObjectImageName = gameObject.imageName;
    double x = gameObject.x * gameHeight;
    double y = gameObject.y * gameHeight;
    double width = gameObject.width * gameHeight;
    double height = gameObject.height * gameHeight;
    double angle = gameObject.angle;
    BOOL visible = gameObject.visible;

    self.imageName = gameObjectImageName;
    self.bounds = CGRectMake(0, 0, width, height);
    self.position = CGPointMake(x, y);
    self.transform = CATransform3DMakeRotation(angle, 0, 0, 1.0);
    self.hidden = !visible;
}

Notice that the GameObjectLayer is not resolution independent, so the GameObject coordinates are multiplied through by the gameHeight to convert them to coordinates in the layer hierarchy.

Controller code to bind them

The final element required to make GameObjects and GameObjectLayers work together is controller code to construct the GameObjectLayer for each GameObject as it appears.

I chose to do this by making the GameData send a GameObjectNewNotification every time a new GameObject is added to the gameObjects dictionary. The GameController observes this notification with the following method:

- (void)createImageLayerForGameObject:(NSNotification *)notification
{
    NSString *gameObjectKey = [notification object];
    
    GameObjectLayer *newLayer =
        [[[GameObjectLayer alloc]
            initWithGameObjectKey:gameObjectKey]
        autorelease];

    [CATransaction begin];
    [CATransaction
        setValue:[NSNumber numberWithBool:YES]
        forKey:kCATransactionDisableActions];
    [backgroundLayer addSublayer:newLayer];
    [CATransaction commit];
}

Transactions are disabled so the layer doesn't fade in, it appears immediately.

Letting the view reinterpret the data

If you ran the program with the above code, the asteroid would not look like the slightly soccerball texture shown in the screenshot at the top and it would not spin. The asteroid would be a smooth gradient circle. This is because the the asteroid shown in the screenshot is made of two components: the non-rotating "asteroid-back" which provides a consistent lightsource-like effect and the "asteroid-front" which is a spinning second layer on top of the back layer.

The GameData only contains the basic bounds information, which is mapped onto the "asteroid-back" by default. How can we add the second spinning layer for the purposes of display?

We could add the second layer as another object in the game but since I want this layer for the purposes of display (it has no real game-logic impact), I decided to handle it a different way.

After the [CATransaction commit]; line in the previous code sample, I include the code:

if ([gameObjectKey rangeOfString:GAME_ASTEROID_KEY_BASE].location == 0)
{
    AsteroidFrontLayer *asteroidFrontLayer =
        [[[AsteroidFrontLayer alloc]
            initWithGameObjectKey:gameObjectKey]
        autorelease];
    
    [CATransaction begin];
    [CATransaction
        setValue:[NSNumber numberWithBool:YES]
        forKey:kCATransactionDisableActions];
    [backgroundLayer addSublayer:asteroidFrontLayer];
    [CATransaction commit];
}

So I look to see if the new GameObject is added to the gameObjects dictionary using a key that starts with GAME_ASTEROID_KEY_BASE. If it does, then I create a second layer that tracks the same underlying GameObject. This second layer is an AsteroidFrontLayer instead of the generic GameObjectLayer. This AsteroidFrontLayer class is a subclass of GameObjectLayer that overrides the imageName to be "asteroid-front" and applies a rotation to the layer on each update.

Conclusion

You can download the Quartzeroids2 Part 2 project (225kB) which demonstrates the classes presented in this post.

The project for this part shows the GameObject, GameObjectLayer and AsteroidFrontLayer in a simple, non-interactive display. To show everything on screen, the GameData class contains a newGame method which constructs some sample objects and then starts a timer running to call the updateWithTimeInterval: methods repeatedly.

Now that we can draw our objects on screen, Part 3 will add user-interaction and game logic.

An Asteroids-style game in CoreAnimation, Part One.

2009-02-17T14:55:00.001-08:00

How would you write an arcade-style 2D game in CoreAnimation? Over the next few weeks, I'll show you how to write a resolution independent, high-speed, model-view-controller designed, Asteroids-style arcade game using CoreAnimation as the screen renderer. In this first of four parts, I'll detail the concept for the overall application and show you how to create a resolution independent window for the game.

A screenshot of the finished game

CoreAnimation as a game renderer

Drawing on the Mac is normally done through either CoreGraphics or OpenGL. OpenGL is fast, supports 2D and 3D and is already used in many games. However, OpenGL is a low-level, pure-C API, so even simple rendering and animating of 2D surfaces can require a whole library of code to accomplish.

CoreGraphics and the NSView hierarchy are a whole library of well-written code. They are clean to use and support a wide range of features without needing to write them yourself. Sadly, CoreGraphics is not ideal for games since it does not easily render 30 fullscreen frames per second (the minimum standard for action games) — even with Quartz Extreme and the other improvements Apple has added since Mac OS X 10.0.

This is where CoreAnimation comes in. Apple introduced CoreAnimation in Mac OS X 10.5 (Leopard) to dramatically accelerate the animation of 2D rectangular textures. Since it integrates so well into the existing CoreGraphics and NSView hierarchy on the Mac, it suddenly gives CoreGraphics a way of delivering 30 (or more) fullscreen frames per second and makes a writing a game possible using nothing more than the Foundation, AppKit and QuartzCore libraries.

Quartzeroids One

The application I'll present over the next few weeks will be similar to an experiment I wrote about 8 years ago. Back then, the application was named Quartzeroids and it was an experiment to see if NSViews were fast enough to use for a 2D Asteroids game. The code was not good — if you find it out in the wild, keep your distance and call animal control.

Were NSViews fast enough for this type of animation? No, not really. At 640 by 480, the game played at 15 frames-per-second on my iMac G3 500Mhz. Computer and operating-system improvements have improved this (newer Intel Macs can now render this old 640 by 480 screen size at more than 30 frames per second) but even newer machines cannot maintain good frame rates at proper fullscreen resolutions of 1920 by 1200 using this approach.

Quartzeroids Two

Since Apple released CoreAnimation 15 months ago, I had been wanting to revisit the idea. To further increase the difficulty, I decided the project should also contain the following features:

Resolution independence (all vector graphics and completely resizeable).
Proper model-view-controller implementation where the "game-state" is the model and the view is free to reinterpret the state for the purposes of display.
Fullscreen or windowed mode for display.

Rough design

A rough block diagram of the program would look like this:

The decisions I think were most significant are:

There is not a one-to-one relationship between objects in the Game Data and Layers in the Window.
The updates to the Game Data are triggered by the Game Data's own timer, not directly by the controller (which can start and stop but nothing further).

The second point is most significant when the Game Data is compared to a normal application document. A normal document never updates itself — it only changes when instructions are sent from a controller. In a game however, choosing when to update is a part of the game logic (which I have included in the model) so the controller shown here is left with only the simplest level of control.

I spent some time deliberating about whether to make the GameData a normal document object or a singleton. A normal document style object can be swapped with another document or recreated. A singleton is lazier and simpler since it doesn't need to be connected to every object which needs to access it (since it is globally accessible). Ultimately, the convenience of a singleton won over the hypothetical flexibility of a normal document object since the game will only ever be strictly single instance.

A resolution independent, constant aspect-ratio view

To get the code started for the project, I'll show you how the top level of the CALayer hierarchy (named backgroundLayer in the application since it shows the background for the game) is implemented inside the contentView for the window.

The two hardest constraints for the backgroundView are maintaining a constant aspect ratio and maintaining a constant internal coordinates when the surrounding window resizes or reshapes.

- (void)updateContentViewFrame:(NSNotification *)notification
{
    double gameWidth = [[GameData sharedGameData] gameWidth];
    double gameHeight = [[GameData sharedGameData] gameHeight];
    
    NSSize contentSize = [contentView bounds].size;

    NSSize aspectSize = contentSize;
    double scale;
    if ((aspectSize.width / aspectSize.height) > (gameWidth / gameHeight))
    {
        scale = aspectSize.height / gameHeight;
        aspectSize.width = aspectSize.height * (gameWidth / gameHeight);
    }
    else
    {
        scale = aspectSize.width / gameWidth;
        aspectSize.height = aspectSize.width * (gameHeight / gameWidth);
    }
    
    [CATransaction begin];
    [CATransaction
        setValue:(id)kCFBooleanTrue
        forKey:kCATransactionDisableActions];
    backgroundLayer.transform = CATransform3DMakeScale(scale, scale, 1.0);
    backgroundLayer.frame =
        CGRectMake(
            0.5 * (contentSize.width - aspectSize.width),
            0.5 * (contentSize.height - aspectSize.height),
            aspectSize.width,
            aspectSize.height);
    [CATransaction commit];

    [contentView becomeFirstResponder];
}

The GameController adds this method as an observer of the contentView's NSViewFrameDidChangeNotification. The gameWidth and gameHeight methods on the GameData objecct are programmed to return values with a 16:10 ratio (matching common widescreen computer aspect ratios). The aspectSize calculated here is then the largest size that obeys this ratio and can fit inside the contentView.

Finally, the CATransform3DMakeScale transform, applied to the backgroundLayer before the frame is set, causes the backgroundLayer to always treat its internal coordinates as though they are gameWidth by gameHeight. This will mean that any layers our game adds to the backgroundLayer's subview hierarchy will always render at a constant fraction of the backgroundLayer's size. Order is important here: apply the transform after the frame is set and it will behave differently.

The other required behavior of the window is switching to fullscreen and back. This is another task which became extremely simple in Mac OS X 10.5:

- (IBAction)toggleFullscreen:(id)sender
{
    if ([contentView isInFullScreenMode])
    {
        [contentView exitFullScreenModeWithOptions:nil];
    }
    else
    {
        [contentView
            enterFullScreenMode:[[contentView window] screen]
            withOptions:nil];
        
        for (NSView *view in [NSArray arrayWithArray:[contentView subviews]])
        {
            [view removeFromSuperview];
            [contentView addSubview:view];
        }
    }
}

The "for" loop is an annoying necessity: if you don't do this for a CoreAnimation layer-enabled NSView, then all child NSViews will fail to update correctly after a switch to fullscreen.

Conclusion

You can download Quartzeroids2 Part 1 (20kb) which shows the full implementation of the window, contentView and backgroundLayer.

A simple as this game is, it is too big to describe in one post — this is as far as I'll get this week. I've presented a few goals, a rough design and the window management code for the game.

In the next post, I'll start to put objects in the game and layers in the window.

Breadth-first traversal of a graph of Objective-C objects

2009-02-07T23:48:00.001-08:00

If you have a collection of interconnected objects in Objective-C, what is the best way to traverse them all in order from nearest to furthest? Are the NSMutableSet methods good for tracking already-visited nodes? How much overhead does an NSMutableArray FIFO queue impose relative to a depth-first search (which doesn't require a FIFO queue)? Does NSMutableArray perform better if objects are pushed onto the front, or the back? In this post, I present answers to these questions and more.

Graph theory

In programming, a graph is any collection of connected data objects.

If that information was new to you, then I suggest you read this Wikipedia page: Graph (computer science), then read every page to which it links, then for each of those pages, also read every page to which they link. Come back to this page once the irony is apparent.

The two common means of processing nodes in a graph are depth-first and breadth-first traversal. Breadth-first graph traversals are normally slightly harder to write than depth-first traversals because we have the added requirement of a maintaining a FIFO queue to handle the nodes to be processed.

When all the nodes in the graph are Objective-C objects and an NSMutableArray is used to maintain the FIFO queue, what is the fastest way to traverse? I tested a few different approaches to see which would work best.

The graph used for testing

All my tests were on graphs where each node of the graph was connected to two more nodes until the center layer of the graph, at which point pairs of nodes were subsequently connected to a single node until the graph converged back to a single node.

An example of this graph structure (shown horizontally so layers are aligned in columns) with two increasing layers and two decreasing layers is:

Since there are two increasing layers and two decreasing layers, I called this a "half-depth" of 2. I will refer to the size of all subsequent graphs by their "half-depth".

All nodes are objects of the following class:

@interface Node : NSObject
{
    NSSet *linkedNodes;
}
@property (nonatomic, retain) NSSet *linkedNodes;
@end

These classes don't store any useful information but that's not the point of these tests: I'm testing traversal performance only.

Initial approach

The basic algorithm is:

create a set to track already-visited nodes
create an array to queue nodes-to-process
for every node (in order) in the nodes-to-process array:
1. get the set of nodes linked to the current node
2. exclude nodes that we've already visited from the linked set
3. add non-excluded, linked nodes to the nodes-to-process array

The first code I wrote implementing this algorithm was:

NSMutableSet *visitedNodes = [NSMutableSet setWithObject:startingNode];
NSMutableArray *queue = [NSMutableArray arrayWithObject:startingNode];

while ([queue count] > 0)
{
    NSMutableSet *newNodes =
        [[((Node *)[queue lastObject]).linkedNodes mutableCopy] autorelease];
    [newNodes minusSet:visitedNodes];
    
    [visitedNodes unionSet:newNodes];
    [queue
        replaceObjectsInRange:NSMakeRange(0, 0)
        withObjectsFromArray:[newNodes allObjects]];
    
    [queue removeLastObject];
}

This code uses NSMutableSet's own set-operators to exclude already visited nodes. It also pushes new objects onto the front of the queue and pops each node for processing off the end.

So, how did this approach perform? In a word: terrible — and it's the fault of -[NSMutableSet minusSet:].

Lesson 1:
Only ever use [setOne minusSet:setTwo] if setOne is bigger than setTwo. This method runs in O(n) time, where n is the size of setTwo. In the above code, where visitedNodes can be orders of magnitude bigger than newNodes it is much faster to iterate over newNodes and exclude nodes found in visitedNodes ourselves. That way we run in O(m) time, where m is the size of newNodes (and is actually small and constant for this test case).

The method minusSet: really should iterate over the smaller set between the receiver and the parameter. However, since it doesn't we must avoid it.

Front-to-back or back-to-front

The next problem to address: is it faster to push objects onto the front of an NSMutableArray and pop them off the end, or to push them onto the end and pop them off the front?

The following is the push onto front:

while ([queue count] > 0)
{
    NSSet *newNodes = ((Node *)[queue lastObject]).linkedNodes;
    for (Node *newNode in newNodes)
    {
        if (![visitedNodes containsObject:newNode])
        {
            [visitedNodes addObject:newNode];
            [queue insertObject:newNode atIndex:0];
        }
    }

    [queue removeLastObject];
}

This is the push onto back:

while ([queue count] > 0)
{
    NSSet *newNodes = ((Node *)[queue objectAtIndex:0]).linkedNodes;
    for (Node *newNode in newNodes)
    {
        if (![visitedNodes containsObject:newNode])
        {
            [visitedNodes addObject:newNode];
            [queue addObject:newNode];
        }
    }

    [queue removeObjectAtIndex:0];
}

The result, testing over graph half-depths of 8, 12, 16 and 20 (from 766 to 3145726 nodes) is that push onto end (the second one) is consistently 5% faster.

Lesson 2:
An add to the end of an NSMutableArray is the only operation that works quickly — most other operations are consistently slower. If the number of operations is equal, favor algorithms that add to the end of the array.

Conclusion

You can download the test code I used: FIFOQueues.zip (46kB)

Even in such a simple algorithm, there are clearly some lessons to learn. The biggest surprise for me was that I couldn't trust minusSet: to work in the most efficient manner. I think I'll need to submit a bug for this to Apple.

NSMutableArrays are not symmetric front-to-back, although the difference is minor enough that it may won't always matter.

Tools like NSOperationQueue are there to help multi-threading (to an extent) but don't work well on tiny snippets of code like this. Small loops like this would vectorize better than parallelize (SSE or Altivec) — but you can't vectorize loops with Objective-C method invocations so that still isn't an option here.

Interprocess communication: snooping, intercepting and subverting

2009-02-01T00:19:00.001-08:00

When Xcode is running, Interface Builder seems to magically know which classes, methods and variables are available. Where does Interface Builder get this information? How can you recreate this effect when editing source files in an external editor without Xcode running? This is the story of how I investigated the communication between Xcode and Interface Builder, so that I could recreate it for myself.

Xcode and Interface Builder, sitting in a tree...

Prior to Mac OS X 10.5 (Snowless Leopard), if you made a change to your classes, IBActions or IBOutlets, you needed to manually instruct Interface Builder to re-read the relevant header files before these changes were visible in Interface Builder.

With Xcode 3 and Interface Builder this has changed. If you add a new class to a project in Xcode, it is immediately available in class lists when you switch to Interface Builder. Similarly, change an IBAction or IBOutlet in Xcode, save the header file and switch to Interface Builder: your changes are immediately visible.

And yet, if you quit Xcode and edit the same files in an external editor, Interface Builder doesn't automatically detect the changes. Clearly, Interface Builder is using something other than basic file monitoring to detect the changes.

NSDistributedNotificationCenter

The simplest way for applications in Mac OS X to communicate is through the distributed notification center, NSDistributedNotificationCenter in Foundation or CFNotificationCenterRef (initialized with CFNotificationCenterGetDistributedCenter) in CoreFoundation. This allows applications to broadcast dictionaries of objects to any application interested in listening.

To see if Xcode is communicating to Interface Builder using a NSDistributedNotificationCenter, I needed to configure the process "distnoted" (the daemon which manages the NSDistributedNotificationCenter) to log notifications so I could see if anything relevant is broadcast.

Apple's Technical Note TN2124: Mac OS X Debugging Magic explains some of what's needed. On the command line:

sudo touch /var/log/do_dnserver_log

Apple's documentation leaves out the next (required) steps:

sudo touch /var/log/dnserver.log
sudo chown daemon /var/log/dnserver.log

and then restart.

Sadly for my investigation, this isn't how Xcode communicates to Interface Builder. Looking at the log when Xcode and Interface Builder are started, reveals nothing relevant from either program.

NSPortNameServer

I observed the next clue to how Xcode and Interface Builder communicate by starting two copies of each. In this setup, a new class created in the first instance of Xcode will be visible in both instances of Interface Builder but a new class created in the second instance of Xcode will not be detected by either copy of Interface Builder.

This type of behavior is typical of named port connections.

A quick Mac OS X lesson: almost all inter-process communication on the Mac is built on Mach Ports underneath. Mach Ports are a way to pass messages (blocks of data) between processes.

The easiest way to for a process advertise a Mach Port so that other processes may connect to it, is to give it a name. Network names are registered using NSNetService (Bonjour) but on a single host (as is far more likely in this case) network names are registered through NSPortNameServer.

NSPortNameServer is, in turn, handled by "launchd" (the daemon that Apple created to replace init, cron, inetd and others). So to see if the NSPortNameServer supposition was correct, I needed to get "launchd" to output log information about Port Names.

Again, I followed Technical Note TN2124: Mac OS X Debugging Magic to learn how to do this:

sudo launchctl log level debug

And once again, the information contained in the Tech Note turned out to be insufficient. Apple really need to update this Tech Note.

I wrote a program to send thousands of port name lookups on random names but no logging was output. However, I could see that the "syslog" process (the process that records logging information) was very busy but it wasn't recording any information anywhere.

This is a typical "syslog.conf" problem: you must direct "syslog" information for the relevant "facility" and "level" to a destination. Unfortunately, the "facility" name that Apple gives for "launchd" in Tech Note TN2124 is wrong. Instead, I appended a "*.debug" line to my "syslog.conf" file and sent the output to /var/log/debug.log instead.

This finally worked: "launchd" information (and debug information from other processes) found its way to the debug log file.

Finding the correct piece of information in this haystack looked like an impossible task until I started Interface Builder without Xcode running:

Mach service lookup failed: PBXProjectWatcherServerConnection-3.1.2

It doesn't follow Apple's own naming policy for Port Names (which would be something more like "com.apple.Xcode.projectwatcherserverconnection.3.1.2") but at least it is clear about its function.

NSConnection

At this point, the data sent over the Mach Port could be anything. How do you work out the format? I hoped that Apple used an NSConnection since the Cocoa libraries will handle this automatically for me.

Fortunately, running the following line of Cocoa Objective-C:

id rootObject =
    [NSConnection rootProxyForConnectionWithRegisteredName:
        @"PBXProjectWatcherServerConnection-3.1.2" host:nil];

cleanly returned an object of type PBXProjectWatcherManager, revealing that yes, this is a regular NSConnection served over the Mach Port.

Recreating PBXProjectWatcherManager

The final step in replacing Xcode's role in keeping Interface Builder up-to-date with changes was to recreate PBXProjectWatcherManager. The easiest way to get this working, is to use class-dump to tell us what methods PBXProjectWatcherManager implements.

Running class-dump directly on Xcode.app was no real help (Xcode.app doesn't directly contain most of Xcode's functionality — it's in shared libraries). Using Activity Monitor (or lsof on the command-line) to inspect the Open Files of Xcode reveals all the shared libraries that Xcode uses. Most of these libraries live in /Developer/Library/PrivateFrameworks, so I ran the following script in that directory:

foreach f (*.framework)
  class-dump $f > ~/Desktop/`basename $f .framework`.h
end

to generate header file descriptions of each framework on the desktop. "DevToolsInterface.h" turned out to contain the description of the PBXProjectWatcherManager class.

Then it was a matter of working out which methods of PBXProjectWatcherManager are invoked and what they needed to return. So I created two projects: one to advertise its own PBXProjectWatcherManager under the name "PBXProjectWatcherServerConnection-3.1.2" and listen as Interface Builder connected and one to connect to Xcode's version of the same and work out the correct responses.

Final solution

The result is that Interface Builder invokes the following:

Method invoked	Required response
`openProjectsContainingFile:`	An `NSString` containing a URI to any Projects that contain a file with the specified path.
`pathOfProject:`	An `NSString` containing the file path for the specified Project URI.
`nameOfProject:`	An `NSString` containing the project name for the specified Project URI.
`targetsInProject:`	An `NSArray` of `NSString` containing the UUIDs for all targets in the specified Project URI.
`nameOfTarget:inProject:`	An `NSString` containing the target name for the specified target UUID.
`filesOfTypes:inTarget:ofProject:`	Types is normally `nil` so the response is an `NSArray` of `NSString` containing file paths to all files contained in the target.

Apparently, Interface Builder gets all the header file paths for all targets that use a given XIB file and monitors these files itself for changes. Experimental testing indicates that all that is required to replace Xcode's role in this case is to return these Project, Target and File values and Interface Builder will handle the rest (parsing the header files for information it requires).

Interface Builder re-requests these values every time it is brought to the front, so it polls the "PBXProjectWatcherServerConnection-3.1.2" server, rather than implementing any automated form of observation (despite observation methods on PBXProjectWatcherManager). My guess is that this is more robust if either end of the NSConnection crashes.

Conclusion

I hope I've been informative about interprocess communication on the Mac and techniques for monitoring and intercepting these communications.

These techniques presented in this post are only useful for intercepting standard Cocoa communication techniques.

Obviously, implementing your own "PBXProjectWatcherServerConnection-3.1.2" server would require care. It isn't sending complicated information but you would need to update it every time Xcode is updated and there are dozens of other methods in the PBXProjectWatcherManager that may play a role I didn't uncover in this brief investigation.

Multiple virtual pages in a UIScrollView with just 2 child views

2009-01-23T22:38:00.001-08:00

The UIScrollView and UIPageControl in Cocoa Touch allow for user interfaces with multiple panning pages. The sample project that Apple provides (PageControl) keeps all child views for every page in a lazily loaded array. I'll show you how you can implement this using just two child views, no matter how many virtual pages you wish to represent.

First, something completely different...

Last week, Dan Grigsby of Mobile Orchard interviewed me about a post I wrote on Automated user interface testing on the iPhone. He posted the podcast of the interview online earlier this week, so I recommend you go listen if you're interested in the Director's Commentary for that earlier post.

Back to this post...

This week, I'm presenting the following application:

The black region is a UIScrollView with pagingEnabled set to YES. The dots at the bottom are a UIPageControl indicating the number of pages in the UIScrollView.

Apple's sample application "PageControl" presents a similar user interface that loads a different UIViewController and UIView for each of the pages in the UIScrollView. I'll show you how you can create the same effect using exactly two child UIViewControllers and UIViews — a "current" and the "next" view which leap around out-of-view to fill in each new page as the scrolling reaches it.

Fast display, slow content

The approach I will display is optimized for views that can redisplay quickly, once their data is loaded. The data may or may not be slow-to-load data so it is important that it is not loaded as part of the view.

Data is therefore loaded and cached in a separate, data-specific class. In the sample app, it will be a class named DataSource that holds an array of page titles and page text — simple in this case but it's just a sample app.

Holding your data in a view-independent class is basic program design — as good programmers, I'm sure you always do this and never, ever have your UIViewControllers directly load and store your data. Ever.

Moving child views to maintain the illusion

The trick in this post is handling an arbitrary array of child pages using just two views. It will work as follows:

Initially, the displayed view will be the currentPage view. The next view will be configured to display the cached data for Page 1
As the user begins scrolling to the right, the nextPage is quickly moved into the location for the next page in the scrolling direction. At the same time as it is positioned, nextPage is configured with the data for Page 2. Neither of these configuration changes will be visible to the user.
As the scroll operation ends, the pointers for currentPage and nextPage are swapped so that currentPage now points to the view displaying Page 2 and nextPage now points to Page 1
If the next scroll is to the left, nextPage is already configured and in position. If the next scroll is to the right, nextPage will be moved and configured as it was during the first scroll.

The code that chooses how to move the views as the scroll view scrolls (step 2 in the above description) looks like this:

- (void)scrollViewDidScroll:(UIScrollView *)sender
{
    CGFloat pageWidth = scrollView.frame.size.width;
    float fractionalPage = scrollView.contentOffset.x / pageWidth;
    
    NSInteger lowerNumber = floor(fractionalPage);
    NSInteger upperNumber = lowerNumber + 1;
    
    if (lowerNumber == currentPage.pageIndex)
    {
        if (upperNumber != nextPage.pageIndex)
        {
            [self applyNewIndex:upperNumber pageController:nextPage];
        }
    }
    else if (upperNumber == currentPage.pageIndex)
    {
        if (lowerNumber != nextPage.pageIndex)
        {
            [self applyNewIndex:lowerNumber pageController:nextPage];
        }
    }

I've left off the final condition for size but it is a rarely invoked path for when very fast scrolling leaves the currentPage out of position and it needs to configure both pages.

The exchange of pointers at the end of scrolling (step 3 in the above description) is handled in the scrollViewDidEndScrollingAnimation: method:

- (void)scrollViewDidEndScrollingAnimation:(UIScrollView *)newScrollView
{
    CGFloat pageWidth = scrollView.frame.size.width;
    float fractionalPage = scrollView.contentOffset.x / pageWidth;
    NSInteger nearestNumber = lround(fractionalPage);

    if (currentPage.pageIndex != nearestNumber)
    {
        PageViewController *swapController = currentPage;
        currentPage = nextPage;
        nextPage = swapController;
    }

    pageControl.currentPage = currentPage.pageIndex;
}

The only remaining component to reveal is exactly how the pages are positioned and configured in applyNewIndex:pageController:

- (void)applyNewIndex:(NSInteger)newIndex pageController:(PageViewController *)pageController
{
    NSInteger pageCount = [[DataSource sharedDataSource] numDataPages];
    BOOL outOfBounds = newIndex >= pageCount || newIndex < 0;

    if (!outOfBounds)
    {
        CGRect pageFrame = pageController.view.frame;
        pageFrame.origin.y = 0;
        pageFrame.origin.x = scrollView.frame.size.width * newIndex;
        pageController.view.frame = pageFrame;
    }
    else
    {
        CGRect pageFrame = pageController.view.frame;
        pageFrame.origin.y = scrollView.frame.size.height;
        pageController.view.frame = pageFrame;
    }

    pageController.pageIndex = newIndex;
}

You can see here that if a page is given an out-of-bounds index, it is placed below the bottom of the scroll view (invisible). I chose not to use setHidden: on the view because this resulted in "pop-in" when making the view visible again.

The actual configuration of the view for the new page index happens in the setter method for pageController.pageIndex. This method fetches the data for the page out of the DataSource and configures the view for displaying that page.

- (void)setPageIndex:(NSInteger)newPageIndex
{
    pageIndex = newPageIndex;
    
    if (pageIndex >= 0 &&
        pageIndex < [[DataSource sharedDataSource] numDataPages])
    {
        NSDictionary *pageData =
            [[DataSource sharedDataSource] dataForPage:pageIndex];
        label.text = [pageData objectForKey:@"pageName"];
        textView.text = [pageData objectForKey:@"pageText"];
    }
}

Notice that I've made this method tolerant of out-of-bounds indices. This is because while out-of-bounds indices are invalid for data from the DataSource, they can be valid locations for views in the scroll view (representing an offscreen position) so these positions must be permitted.

Offscreen UITextViews don't update correctly

If you take a look at the code for this sample project, you'll notice a method that I've added named updateTextViews: and a value I track named textViewNeedsUpdate.

These parts of the program exist because UITextView (used for the "Some text for Page X" display) don't update if they are offscreen (in this case: in an offscreen page of the UIScrollView). This behavior isn't a problem when the UITextView remains offscreen but becomes especially annoying when it is brought onscreen and still doesn't update.

I have addressed this in 2 ways:

When an update is applied, check if the UITextView is offscreen. If it is, set textViewNeedsUpdate to YES. I check this value regularly during a scroll, to see if the UITextView has appeared and update the view when it does.
In some fast scrolling cases (mostly when using the UIPageControl instead of the UIScrollView to page) this still doesn't work — so I always force one update to the currentPage at the end of scrolling. This case can result in a visible update if your eyes are quick but it is an uncommon case.

Conclusion

You can download the complete Xcode 3.1 project for PagingScrollView (31kB).

It is possible to handle a paging scroll view using just 2 child views, no matter how many virtual pages you wish to support.

This approach assumes the views can be reconfigured to display a new virtual page quickly (normally a safe assumption). Remember that the data displayed need not be fast to load for the pages to reconfigure quickly because the data is loaded and cached in a separate object, independent of the paging.

The bug in UITextView is annoying. I've presented a means of getting around it, although I'd be happy to see a better approach.

Demystifying NSApplication by recreating it

2009-01-18T14:18:00.001-08:00

In this post I will recreate code that is normally concealed between the NSApplicationMain call (invoked in a Cocoa application's main function) and the sendEvent: method (which distributes the events to windows and views from the main run loop). By recreating this code for you, I hope to explain the steps that occur between program startup and the dispatch of events to your code — so you can gain greater understanding of what NSApplication does on your behalf.

Introduction

The default Cocoa Application template provided by Xcode contains just one line of code, in one function:

int main(int argc, char *argv[])
{
    return NSApplicationMain(argc,  (const char **) argv);
}

Somehow, this one line of code is enough to create a menubar, put a window onscreen and then handle user events (mouse clicks and menu selections) until the user quits the program, at which point the application gracefully exits.

What we know

Scattered throughout the Cocoa documentation are hints about what must happen in NSApplicationMain:

Read from the "Info.plist" file to determine:
- The name of the "MainMenu" NIB file to load automatically on startup
- The name of the application's principal class (the class of the application object)
Construct the application object
Load the "MainMenu" NIB file
Begin the "Run Loop" (which handles the rest of the program)

I will recreate all of these steps by implementing my own version of NSApplicationMain — named MyApplicationMain — and by creating my own NSApplication subclass that implements the run method for itself.

MyApplicationMain

Create the application object

The first step in the MyApplicationMain function is to read the name of the "Principal class" and construct the application object from this class.

NSDictionary *infoDictionary = [[NSBundle mainBundle] infoDictionary];
Class principalClass =
    NSClassFromString([infoDictionary objectForKey:@"NSPrincipalClass"]);
NSAssert([principalClass respondsToSelector:@selector(sharedApplication)],
    @"Principal class must implement sharedApplication.");
NSApplication *applicationObject = [principalClass sharedApplication];

The infoDictionary method returns the "Info.plist" for a bundle (in this case, our application's bundle) converted into an NSDictionary for easy access. All we need to do is get the "NSPrincipalClass" string and fetch the class identified by that string.

Since the application is a singleton, we construct it by calling the sharedApplication method on the class. If we try to construct the object using standard alloc and init calls, the NSApp singleton instance won't be set correctly and an exception will be thrown at a later point when a second application is created.

For more information on singletons, you can see my earlier post about singletons or visit Apple's page on Creating a Singleton Instance.

Load the contents of the MainMenu NIB file

Loading the "MainMenu" NIB file is a similar task: get the name from the infoDictionary and then load it.

NSString *mainNibName = [infoDictionary objectForKey:@"NSMainNibFile"];
NSNib *mainNib =
    [[NSNib alloc] initWithNibNamed:mainNibName bundle:[NSBundle mainBundle]];
[mainNib instantiateNibWithOwner:applicationObject topLevelObjects:nil];

I briefly considered implementing the NSNib code too, to show how that works for loading objects in a NIB file, but since the format of a NIB file is not publicly declared, it wasn't possible. Suffice it to say that the instantiateNibWithOwner:topLevelObjects method performs the following steps:

Allocates all the objects in the NIB file and initializes them with one of the following methods:
- initWithFrame: (used for NSView objects)
- initWithCoder: (used for most other objects in the Interface Builder library)
- init (used for all other objects)
Sets the IBOutlet pointers on objects as specified in the NIB file and establishes all bindings
Invokes awakeFromNib on all objects that implement this method

Start the run loop

It is extremely important that the application's main loop runs on the main thread. For this reason, we don't directly invoke run but instead make sure it is performed on the main thread.

if ([applicationObject respondsToSelector:@selector(run)])
{
    [applicationObject
        performSelectorOnMainThread:@selector(run)
        withObject:nil
        waitUntilDone:YES];
}

I also check that the applicationObject will respond to the method before trying to invoke it, just in case the "Principal Class" from the Info.plist file is not a valid NSApplication or NSApplication-like object.

Implementing our own run loop

The remaining task required so that you can trace the application's execution from startup to dispatch of events to your code is the implementation of the run loop.

Despite Apple's comment in the NSApplication documentation that run is one of the "Methods to Override", my brief search failed to uncover anyone who had actually done it. My suspicion is this: it is not a method to override and that document is woefully out-of-date. The only reason to implement your own run method now is curiosity, not functionality.

In that spirit, here's a reimplementation of run and a corresponding terminate method:

- (void)run
{
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

    [self finishLaunching];

    shouldKeepRunning = YES;
    do
    {
        [pool release];
        pool = [[NSAutoreleasePool alloc] init];

        NSEvent *event =
            [self
                nextEventMatchingMask:NSAnyEventMask
                untilDate:[NSDate distantFuture]
                inMode:NSDefaultRunLoopMode
                dequeue:YES];

        [self sendEvent:event];
        [self updateWindows];
    } while (shouldKeepRunning);

    [pool release];
}

- (void)terminate:(id)sender
{
    shouldKeepRunning = NO;
}

It's as simple as you might expect: take the next event out of the queue for your application and route it appropriately using sendEvent: which handles the task of determining which window wants the event and invokes sendEvent: on the window to further route the event to a specific view.

For those interested: I discovered all the methods that need to be invoked in the run method in the most naive way: by searching the NSApplication documentation for "loop" to find all methods that claimed they were invoked in the main run loop.

The specific function of finishLaunching method is a bit of a mystery. All I know is that menus, menu updates and a host of other features won't work if it isn't invoked. It is possible that it sets up the responder chain for some actions. It is possible it adds observers to the run loop. I don't really know.

nextEventMatchingMask:untilDate:inMode:dequeue: is the biggest reason why I chose, when "reimplementing" NSApplication for this post, to make my implementation a subclass of NSApplication instead of a completely separate class. This method (or something it contains) converts notifications from the operating system and hardware drivers into NSEvent objects. A principal class is not required to be a subclass of NSApplication but I wouldn't know where to begin reimplementing this method, so I had to use NSApplication to do it.

Conclusion

You can download an implementation of the default Cocoa Application Xcode 3.1 project that uses this code: RecreatingNSApplication.zip (60kB)

This recreation of NSApplicationMain and NSApplication's run does not do everything that the real implementations do (I've deliberately kept it simple for clarity) but I think it shows that the key steps involved are straightforward and easy to understand.

There are a few steps that I haven't reimplemented: loading NIB files, retrieving events and routing events. Unfortunately, these remain black boxes to me, so I can't shed further light on them. You can find out some things by setting breakpoints (in your constructors for objects created in NIBs or in your event methods) and reading the names of Apple functions invoked to bring these commands to you.

Beyond this, you can also read how GNUStep implements the same methods. Apple doesn't necessarily do the same thing but GNUStep at least represents an observable solution to the same problems.