1. Provide a safe, generic alternative to Cocoa’s -setValuesForKeysWithDictionary: for use with NSManagedObject and its subclasses
2. Handle cases where JSON data didn’t match up with what the managed objects expected. Getting a string where you expect a numeric value, or vice versa, for example, or getting a string representation of a date when you want a real NSDate object.

The first item was the most important. It’s tempting to use -setValuesForKeysWithDictionary: to transfer JSON to a model object in one step. The method runs through the dictionary and calls -setValue:forKey: on the target object for every entry. It has a fatal flaw though, in that it doesn’t check to see if the target object actually has a key before trying to set it. Using this method when you don’t have absolute control over the dictionary contents is an invitation to unknown key exceptions and nasty app crashes.

Fixing this for managed objects was relatively easy because Core Data provides convenient Objective-C introspection methods. The general approach was:

• Get a list of the target object’s attributes
• For each attribute, see if the incoming dictionary has an entry. If so,
• Compare the incoming type to the expected type, and convert if necessary.
• Call -setValue:forKey: with that key and its value.

And then just last week I had the thought, wouldn’t it be nice if this worked for any object, not just for managed objects?

Objective-C introspection

Since Objective-C is dynamic, pretty much everything you’d want to know about a class is available at run time. I’m not just talking about methods like -respondsToSelector: and -isKindOfClass:, though those are extremely useful. You can go much, much deeper than that, inspecting (and even changing) every aspect of a class’s implementation. Much of this happens via C function calls rather than Objective-C method calls. The Objective-C runtime is not actually written in Objective-C, and it’s the runtime that has the information.

To update the code for use with objects that don’t inherit from NSManagedObject the new code looks through the properties declared on a class and uses those to run through the incoming JSON. The general approach is the same but the implementation uses NSObject properties instead of NSEntityDescription attributes.

It’s also possible to look through the instance variables instead of the properties. Often this would amount to the same thing. Where they differ is when the backing ivar has a different name, i.e. when you’re using something like:

@synthesize foo = __myReallyBizarrePrivateName____;

In that case iterating over properties would find foo while iterating over instance variables would find __myReallyBizarrePrivateName____. Either is valid but I’m going with the properties because (at least for me) they’re more likely to match up with the JSON keys.

First pass: iterating over properties

A simple version that meets requirement #1 looks like this:

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

- (void)setValuesForKeysWithJSONDictionary:(NSDictionary *)keyedValues dateFormatter:(NSDateFormatter *)dateFormatter
{
    unsigned int propertyCount;
    objc_property_t *properties = class_copyPropertyList([self class], &propertyCount);
 
    for (int i=0; i<propertyCount; i++) {
        objc_property_t property = properties[i];
        const char *propertyName = property_getName(property);
        NSString *keyName = [NSString stringWithUTF8String:propertyName];
 
        id value = [keyedValues objectForKey:keyName];
        if (value != nil) {
            [self setValue:value forKey:keyName];
        }
    }
    free(properties);
}

This starts with a call to class_copyPropertyList(), which gets a C-style array of property declarations for the requested class. The propertyCount argument indicates how many properties are in the array. The array contains zero or more objc_property_t entries, which is an opaque structure.

The code iterates through this array. For each one it uses property_getName to get the property name as a C-style string. Then it converts this to an NSString and uses that to look up entries in the incoming dictionary. And, voila, we’re using the class’s own properties to look up values in the dictionary instead of the other way around.

A final detail– unusual in Objective-C code– is the call to free(). Since class_copyPropertyList() has copy in its name, the calling code is responsible for disposing of the returned data. And since it’s a C call, this needs to be done C style. This call would need to be there even if the project were using ARC.

Back to Core Data, briefly

The great thing about this solution is that it’s not the non-managed-object alternative to the previous version, it’s a direct replacement. This approach works just as well on managed objects as on other objects– provided, that is, that you create custom subclasses of NSManagedObject for your entities that declare properties for managed object attributes. So long as the properties exist, the code works. If you’re using Xcode or mogenerator to generate your managed object subclasses, you’re covered. If you aren’t creating custom subclasses, first of all, why not? But in that case this approach won’t work since NSManagedObject doesn’t have the necessary property declarations.

Does it have to be like this?

Some of you may have noticed that it’s possible to do the same thing without any mucking about with the runtime by doing something like this:

1
2
3
4
5
6
7
8

    for (NSString *key in keyedValues) {
        @try {
            [self setValue:[keyedValues objectForKey:key] forKey:key];
        }
        @catch (NSException *exception) {
            // Do nothing
        }
    }

In this case the dictionary keys still drive the action, but exception handling means the code doesn’t crash on unknown keys. So why bother then? Because of requirement #2 above. Coercing JSON into appropriate data types is going to require introspection. With this simplified approach you don’t crash, but you also don’t get type conversions. If not crashing is all you’re interested in, this works just as well and is probably faster. It’s certainly simpler anyway. It’s not going to do what I need though.

JSON Fixes

To meet requirement #2 the code needs to go deeper. As with the Core Data implementation, it needs to look up the expected value for the property and compare that to the type of the incoming data. To do this I’ll expand the if block beginning on line 12 above to look like this:

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

if (value != nil) {
    char *typeEncoding = NULL;
    typeEncoding = property_copyAttributeValue(property, "T");
 
    if (typeEncoding == NULL) {
        continue;
    }
    switch (typeEncoding[0]) {
        case '@':
        {
            // Object
            Class class = nil;
            if (strlen(typeEncoding) >= 3) {
                char *className = strndup(typeEncoding+2, strlen(typeEncoding)-3);
                class = NSClassFromString([NSString stringWithUTF8String:className]);
            }
            // Check for type mismatch, attempt to compensate
            if ([class isSubclassOfClass:[NSString class]] && [value isKindOfClass:[NSNumber class]]) {
                value = [value stringValue];
            } else if ([class isSubclassOfClass:[NSNumber class]] && [value isKindOfClass:[NSString class]]) {
                // If the ivar is an NSNumber we really can't tell if it's intended as an integer, float, etc.
                NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];
                [numberFormatter setNumberStyle:NSNumberFormatterDecimalStyle];
                value = [numberFormatter numberFromString:value];
                [numberFormatter release];
            } else if ([class isSubclassOfClass:[NSDate class]] && [value isKindOfClass:[NSString class]] && (dateFormatter != nil)) {
                value = [dateFormatter dateFromString:value];
            }
 
            break;
        }
 
        default:
        {
            break;
        }
    }
    [self setValue:value forKey:keyName];
    free(typeEncoding);
}

The runtime provides information about properties via the call to property_copyAttributeValue() on line 3. The first argument is the property of interest. The second one can have a bunch of different values depending on what you want to look up. A “T” requests a C-style string that describes the property type. For full details on what you can do with the second argument, see the (somewhat out of date as of this writing) “Declared Properties” section of Apple’s Objective-C Runtime Programming Guide.

If the property type is a pointer to a class, the return value will be something like T@"NSNumber", T@"NSString", T@"MyClass", etc. The next thing the code does then is to check for a leading @ and, if found, set about getting the Class that the type string names. This happens in lines 12-16. The code strips off the @ and the quotes, converts to NSString, and uses NSClassFromString to get the Class.

The rest of this code is remarkably similar to the Core Data version, looking for type mismatches and converting the incoming value where needed. The chief difference is that it uses -isSubclassOfClass: to check on the expected type of the property instead of looking at the Core Data-specific NSAttributeType.

Except for one important difference. For numeric properties, the Core Data attribute type would indicate whether a floating point or integer value was expected. With NSNumber we have no way of knowing. So the code uses NSNumberFormatter to parse incoming strings and leaves it at that. If this kind of mismatch occurs then there are bigger problems anyway. You could change the code to round a float to an int, but is that actually going to be a valid result? Maybe, maybe not.

The type comparisons in this code could go on forever but in this case the code is specifically looking for problems that sometimes crop up with JSON.

Since property_copyAttributeValue() has copy in its name, this block adds another call to free() to clean up after itself.

Handling primitives

But what if the expected value is not an object at all? What if it’s a primitive int? Fortunately property_copyAttributeValue() covers that case as well. In this case the type encoding string is shorter, with values like Ti for int, Tf for float, TQ for unsigned long long, etc (again, see Apple’s docs for a full list).

With this information, the switch statement above can be expanded with a few more cases.

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

        case 'i': // int
        case 's': // short
        case 'l': // long
        case 'q': // long long
        case 'I': // unsigned int
        case 'S': // unsigned short
        case 'L': // unsigned long
        case 'Q': // unsigned long long
        case 'f': // float
        case 'd': // double
        case 'B': // BOOL
        {
            if ([value isKindOfClass:[NSString class]]) {
                NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];
                [numberFormatter setNumberStyle:NSNumberFormatterDecimalStyle];
                value = [numberFormatter numberFromString:value];
                [numberFormatter release];
            }
            break;
        }
 
        case 'c': // char
        case 'C': // unsigned char
        {
            if ([value isKindOfClass:[NSString class]]) {
                char firstCharacter = [value characterAtIndex:0];
                value = [NSNumber numberWithChar:firstCharacter];
            }
            break;
        }

The first half of this, up to line 20, handles all the numeric types. As with the previous code block there’s no attempt to work out floating point/integer conflicts since it’s impossible to know how to handle this in the general case. It would be possible to break this up into more specific checks, say by using -[NSString intValue] when an integer result is expected and hope for valid data. But the code above handles the case where you actually have an integer value, and if you don’t have one then again, you have bigger problems.

The rest of this block handles a primitive char property by taking the first character in the incoming string. Longer strings can’t be stored in a char anyway, so this is the best approach.

In both cases the conversion results in an NSNumber instead of a primitive type. That’s OK though– -setValue:forKey: has our back here and will unbox the object for us.

Conclusion

Using this approach makes it a lot easier to deal with web services. You can’t always rely on the results matching what you expect (or what’s documented). Inspecting classes at run time takes a more defensive approach to dealing with data you can’t control.

A category on NSObject that implements this code can be found at github.

Publishing lead times being what they are, this post covers information not included in the book.

The Ugly/Crude Way

I’m going to assume that the incoming JSON more or less matches your managed object, i.e. that you have a JSON dictionary with keys that match the attribute names of your Core Data entities. Given a dictionary jsonDict that has been created by parsing incoming JSON data using a JSON library (TouchJSON and json-framework are good choices) and a managed object imaginatively called myObj, the dead simple approach is to just do something like:

[myObj setValue:[jsonDict objectForKey:@"name"] forKey:@"name"];
[myObj setValue:[jsonDict objectForKey:@"city"] forKey:@"city"];
[myObj setValue:[jsonDict objectForKey:@"phone"] forKey:@"phone"];

…and on and on and on ad nauseum. It works but it’s astoundingly ugly. It also makes maintenance more challenging, since any changes to the data structure require changes not only to your Core Data model and related managed object classes but also to your data import code.

The Easy/Dangerous Way

Cocoa provides a method that makes this much, much simpler. Thanks to key-value coding there’s a method in NSObject that reduces the above to a single line:

[myObj setValuesForKeysWithDictionary:jsonDict];

This will run through key/value pairs in jsonDict and set the same key/value pairs on myObj. The only caveat is that the key names must match, but that shouldn’t be a problem assuming you’ve named them the same in your data model.

Actually there’s one more caveat, and it’s a biggie. In this method, the keys contained in the dictionary determine what keys are used on the managed object. But what if the dictionary contains a key that’s not part of the entity description? Then your app crashes with an error about how the object is not key-value coding compliant for the key. Using this method here puts your app’s stability at the mercy of the web service you’re using. If you don’t have absolute control over the web service, you’re running serious risks using this method here. We can do better.

Inspecting Managed Objects

Since we’re using Core Data, we can use NSEntityDescription to inspect a managed object’s attributes and turn the logic above around. Instead of using the incoming dictionary to determine what key/value pairs to use, we can use the managed object.

You can look up the entity description for a managed object by asking for its entity. That gives you an NSEntityDescription which you can then ask for all kinds of useful information, like what attributes exist. That leads to a safer approach when converting from JSON:

NSDictionary *attributes = [[myObj entity] attributesByName];
for (NSString *attribute in attributes) {
    id value = [jsonDict objectForKey:attribute];
    if (value == nil) {
        continue;
    }
    [myObj setValue:value forKey:attribute];
}

This code iterates over the entity’s attributes, looks up a key in the dictionary for each of them, and applies that key/value pair to the managed object. That’s still nice and generic, and has the advantage that changes to incoming data won’t crash the app any more. It looks up values in the dictionary only for attributes that actually exist in the entity description. Extra dictionary keys are simply ignored.

The check for nil is there because the code does hit all of the entity’s attributes. If the entity has any attributes that aren’t present in the incoming data (a “favorites” flag, for example) the code would end up setting a nil value for the attribute. That could lead to accidentally wiping out data that you really want to keep.

Handling Broken and Inconsistent JSON

The JSON standard is quite clear about how to distinguish strings from numbers– basically, strings are surrounded by quotes and numbers are not. JSON web services however, are not always good about following this requirement. And even when they are, they are not always consistent from one record to another.

An example, similar to one I encountered recently: Size information for clothing. Sizes are provided by the web service and are typically something like “30-32″, “34-36″, etc. These are correctly quoted as strings in the JSON, and the app saves them as string attributes and displays them to the user as is.

But sometimes the size just has one number, e.g. “8″, “10″, etc. In this case the server drops the quotes, making them numbers. My JSON parser correctly produces an NSNumber. Only I want to save this in my entity’s string attribute! I can use Objective-C introspection to see if I received an NSString or an NSNumber from my JSON parser, but I also need to know what type the managed object expects for the property. I briefly considered breaking my JSON parser so that it would always return NSString, so at least I would know what to expect from it. Fortunately NSEntityDescription came to the rescue again.

Besides asking the entity description what its attribute names are, you can also inquire about the attribute types configured in the Core Data model. This is returned as an NSAttributeType. Using this, we can expand the code above to handle mismatched data types. It’s probably a good idea to abstract the code for easy reuse, too, so I’ll put it in a category on NSManagedObject:

@implementation NSManagedObject (safeSetValuesKeysWithDictionary)
 
- (void)safeSetValuesForKeysWithDictionary:(NSDictionary *)keyedValues
{
    NSDictionary *attributes = [[self entity] attributesByName];
    for (NSString *attribute in attributes) {
        id value = [keyedValues objectForKey:attribute];
        if (value == nil) {
            // Don't attempt to set nil, or you'll overwite values in self that aren't present in keyedValues
            continue;
        }
        NSAttributeType attributeType = [[attributes objectForKey:attribute] attributeType];
        if ((attributeType == NSStringAttributeType) && ([value isKindOfClass:[NSNumber class]])) {
            value = [value stringValue];
        } else if (((attributeType == NSInteger16AttributeType) || (attributeType == NSInteger32AttributeType) || (attributeType == NSInteger64AttributeType) || (attributeType == NSBooleanAttributeType)) && ([value isKindOfClass:[NSString class]])) {
            value = [NSNumber numberWithInteger:[value  integerValue]];
        } else if ((attributeType == NSFloatAttributeType) && ([value isKindOfClass:[NSString class]])) {
            value = [NSNumber numberWithDouble:[value doubleValue]];
        }
        [self setValue:value forKey:attribute];
    }
}
@end

This code inspects the types of both the value found in the dictionary we created from the incoming JSON and the attribute on the managed object, and if there’s a string/number mismatch it modifies the value to make sure it matches what’s expected.

This is getting pretty useful. Not only is it a generic JSON-to-NSManagedObject conversion, it also handles mismatches between numeric and string types without needing any entity-specific information. It could be even better, though.

Handling Dates

JSON does not have a date type, but dates are nevertheless common in JSON. They’re just represented as strings using one date format or another. Only you probably want an NSDate, not a string. NSDateFormatter is really useful here, but wouldn’t it be nice to make the date conversion generic as well, so you don’t need to special-case your date attribute? Can you see where I’m going with this?

Having written the category method above, it’s not much more work to add an optional NSDateFormatter argument, and then to use it whenever an entity’s attribute expects a date. This modified version adds that argument, and an extra case to the “else … if” chain:

@implementation NSManagedObject (safeSetValuesKeysWithDictionary)
 
- (void)safeSetValuesForKeysWithDictionary:(NSDictionary *)keyedValues dateFormatter:(NSDateFormatter *)dateFormatter
{
    NSDictionary *attributes = [[self entity] attributesByName];
    for (NSString *attribute in attributes) {
        id value = [keyedValues objectForKey:attribute];
        if (value == nil) {
            continue;
        }
        NSAttributeType attributeType = [[attributes objectForKey:attribute] attributeType];
        if ((attributeType == NSStringAttributeType) && ([value isKindOfClass:[NSNumber class]])) {
            value = [value stringValue];
        } else if (((attributeType == NSInteger16AttributeType) || (attributeType == NSInteger32AttributeType) || (attributeType == NSInteger64AttributeType) || (attributeType == NSBooleanAttributeType)) && ([value isKindOfClass:[NSString class]])) {
            value = [NSNumber numberWithInteger:[value integerValue]];
        } else if ((attributeType == NSFloatAttributeType) &&  ([value isKindOfClass:[NSString class]])) {
            value = [NSNumber numberWithDouble:[value doubleValue]];
        } else if ((attributeType == NSDateAttributeType) && ([value isKindOfClass:[NSString class]]) && (dateFormatter != nil)) {
            value = [dateFormatter dateFromString:value];
        }
        [self setValue:value forKey:attribute];
    }
}
@end

Conclusion

Saving JSON data to a managed object is one of those things that’s not as easy as it seems at first glance. Making it happen is easy enough, but making it happen safely in maintainable code can quickly get complicated. Fortunately, Core Data has your back and will help you work out what needs to happen along the way.

Whenever most cocoa developers mention threading and Core Data in the same sentence, the reaction I see most often is that of mysticism and disbelief. For one, multithreaded programming in general is hard–hard to design correctly, hard to write correctly, and debugging threads is just asking for trouble. Introducing Core Data into that mix can seem like the straw that broke the camel’s back. However, by following a few simple rules and guidelines, and codifying them into a super simple pattern, one that may be familiar to you, we can achieve safer Core Data threading without the common headaches.

Another reminder: the examples in this blog post will refer to the open source project on Github, MagicalRecord, which is basically several helpful categories and classes I’ve written to extend the standard Core Data APIs.

What would Apple do?

Let’s start by looking up in the docs (see Concurrency with Core Data) to see what needs to happen in order to set up Core Data to pass data objects across threads and perform save operations in the background. Summarizing the main points from the recommended approach:

• Each thread should have its one NSManagedObjectContext
• NSManagedObjects themselves are not thread-safe
• NSManagedObjectIDs are thread-safe
• If you save in the background, you need to merge your changes to other contexts using one of the Core Data system notifications, NSManagedObjectContextDidSaveNotification.

How do we do this in code? The most common solution is to create a custom NSOperation, and make sure we create and set up our new context in the main method of the operation, like so:

#import "MGPCoreDataOperation.h"
 
@interface MGPCoreDataOperation ()
 
@property (nonatomic, retain) NSManagedObjectContext *context;
 
@end
 
@implementation MGPCoreDataOperation
 
- (void)main
{
	[self setContext:[NSManagedObjectContext context]];
 
	//perform my core data operations here
}
 
@end

Remember to create the NSManagedObjectContext in the main method of your custom NSOperation, and not the init method. The main is the only one of the two that is guaranteed to be called from another thread. Your secondary NSManagedObjectContext needs to be created inside the thread where it will be used.

This solution is fairly straightforward, however, let’s think beyond this class. Using this approach, while a valid solution, is somewhat cumbersome to reuse. For every save operation using this technique you will:

• need to subclass, or create this class via a template every time
• instantiate this objects on the main thread, and give it to an NSOperationQueue
• have to pass in object ids through a property

This solution is for the heavy lifting algorithms such as parsing data in the background and saving it in once the parse is done, and all on a background thread. Let’s try a solution that is a little lighter weight, a little easier on the eyes, and uses one of the more fun and recent additions to Objective C–blocks and GCD.

A small idea

Before we get started with our threading adventure, we need to first seed our minds with a small idea that will help us for the remainder of this post. In the context of threading and UI, we need to examine the concept of a Main Thread. The main thread is different from other threads in that it is considered the foreground thread, and is the thread which runs the main runloop, which in turn, processes messages sent from outside your app such as taps or clicks, and sends them to your application. From this example, let’s introduce the concept of a Main Managed Object Context. This context is meant to only be accessed from the same thread as the UI. This context is also always available, as is the Main Thread, and Main Runloop. In the MagicalRecord helpers, I have implemented a defaultContext class method that provides access from anywhere.

The default Xcode Core Data application template promotes this idea by virtue of putting a reused managed object context in the app delegate. Both the app delegate, and the managed object context are implied singletons. MagicalRecord also keeps it’s default context in a single place for easy reuse in your applications, and is also a singleton-like pattern. But, unlike the application templates, it keeps its reference away from your app delegate. Technically speaking, moving the shared NSManagedObjectContext out of the app delegate is merely a preference, but my preference is to keep the application delegate as free from actual application responsibility as possible.

This main context provides some neat features. First, it let’s us simplify the find methods described in my previous post, while still having the option for a context parameter. Second, this lets us get started with Core Data very quickly since we can do fetching from the main thread on the main context, and not have cross thread issues. And third, and most importantly, we have a single context to which any background changes are merged. And if those benefits weren’t helpful enough, changes to observed managed object instance can immediately be acted upon by any UI components using KVO.

Core Data, Blocks and GCD…oh my!

Multithreading in Core Data is important when it comes to saving data in the store. While complex fetches can certainly take quite a bit of time to return, most frequently the bottleneck is during a save. As such, the goal in this solution is to make background saving easy and safe.

This block based solution is inspired by one of the newer iOS APIs for animating views. Blocks are incredibly powerful, and for Core Animation code, have greatly simplified animation code. A simple animation now looks like this:

UIView *redView = ...;
[UIView animateWithDuration:5.0
		 animations:^{
			redView.alpha = 0.0;
		 }
 ];

Can we use this paradigm to save Core Data objects on a background thread? What if we had a save API resembling this animation API? Let’s first think about the synchronous (aka. easy) case. The API would probably look something like this:

+ (void) saveDataInContext:(void(^)(NSManagedObjectContext *context))saveBlock;

When using this API our code will resemble this sample:

PersonEntity *person = ...;
NSManagedObjectID *objectID = [person objectID];
[NSManagedObjectHelper saveDataInContext:^(NSManagedObjectContext *localContext){
	PersonEntity *localPerson = (PersonEntity *)[localContext objectWithID:objectID];
 
	//make my updates to localPerson here
	localPerson.name = @"IronMan";
	//...more changes
}];

While it’s not terribly important in this particular example because it’s all running in the same tread, I must remind you that NSManagedObjects are NOT thread-safe, but NSMangedObjectIDs are, so we need to pass an NSManagedObject’s object ID across the thread, or in this case, block boundary.

In order for this code sample to work, the implementation of the saveDataInContext method should be:

• creating a new NSManagedObjectContext instance, AND
• setting up the both contexts with the proper merge policy, AND
• setting up the main context to listen to the background context to merge on save,
• sending that context as the parameter into the block for use by other code.

This would make creating lightweight save or update operations as easy as creating a UIView block-based animation.

So, what would the body of this method look like? Let’s start the first item on the list.

+ (void)saveDataInContext:(void(^)(NSManagedObjectContext *context))saveBlock
{
	NSManagedObjectContext *context = [NSManagedObjectContext context];			//step 1
	[context setMergePolicy:NSMergeByPropertyObjectTrumpMergePolicy];				//step 2
	[defaultContext setMergePolicy:NSMergeObjectByPropertyStoreTrumpMergePolicy];
	[defaultContext observeContext:context];						//step 3
 
	block(context);										//step 4
	if ([context hasChanges])								//step 5
	{
		[context save];  //MagicalRecord will dump errors to the console with this save method
	}
}

This code uses some MagicalRecord helper methods, but the steps as implemented are:

• Step 1: Create the new context
• Step 2: Set the merge policy
• Step 3: Set up the notification
• Step 4: Call back our block with our newly created context that’s been set up properly.
• Step 5: Save the context if it has any changes

Notice also, that in order for a merge to occur automatically, one context has to be set to win during the merge. In this case, we want the background context to win by telling the main context that we want the information in our data store to be the correct answer in the case of a conflict. Also notice that much of the setup of a second context is as simple as calling a single method. We can now build upon this simple foundation and introduce background threading for our saves. Since we’re using blocks, we can also take advantage of the Grand Central Dispatch APIs.

A background operation using our synchronous method can easily be written using GCD:

+ (void)saveDataInBackgroundWithContext:(void(^)(NSManagedObjectContext *context))saveBlock
{
	dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_BACKGROUND, 0), ^{
		[self saveDataInContext:saveBlock];
	});
}

Going the Distance

But, can we do more? What is one neat feature of the UIView block animation APIs? Their ability to call a block when the animation has completed. How useful would it be to have a block of code called exactly after the changes to your object have been saved and merged? I thought so; let’s look again at a UIView animation API for inspiration:

+ (void)animateWithDuration:(NSTimeInterval)duration animations:(void (^)(void))animations completion:(void (^)(BOOL finished))completion

UIView *redView = ...;
[UIView animateWithDuration:5.0
		 animations:^{
			redView.alpha = 0.0;
		 }
		 completion:^(BOOL  completed){
			[redView removeFromSuperview];
			[redView release];
			redView = nil;
		 }
];

To be safe, let’s make sure our completion block is called on the main thread while we’re at it.

+ (void)saveDataInBackgroundWithContext:(void(^)(NSManagedObjectContext *context))saveBlock completion:(void(^)(void))completion
{
	dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_BACKGROUND, 0), ^{
		[self saveDataInContext:saveBlock];
 
		dispatch_sync(dispatch_get_main_queue(), ^{
			completion();
		});
	});
}

Now, you can save and reload, or update your data in a single place sort of like this:

 
NSArray *listOfPeople = ...;
[NSManagedObjectHelper saveDataInBackgroundWithContext:^(NSManagedObjectContext *localContext){
	for (NSDictionary *personInfo in listOfPeople)
	{
		PersonEntity *person = [PersonEntity createInContext:localContext];
		[person setValuesForKeysWithDictionary:personInfo];
	}
} completion:^{
	self.people = [PersonEntity findAll];
}];

This small block of code does a lot for you. It,

• creates and sets up a background Managed Object Context
• creates and sets up a background GCD queue
• saves the background context, which was set up to notify our Managed Object Context in the Main thread
• calls back your completion block on the main thread AFTER the changes have been pushed all the way to the persistent store

However, there is one more thing we could add to help keep our saving simple. As it is now, the background operations are performed on a global background queue. I’ve encountered times where it is necessary to have a single dedicated GCD queue only for Core Data operations. In MagicalRecord, we’ve defined a simple static function that allows access to a write only GCD queue.

static dispatch_queue_t coredata_background_save_queue;
 
dispatch_queue_t background_save_queue()
{
    if (coredata_background_save_queue == NULL)
    {
        coredata_background_save_queue = dispatch_queue_create("com.magicalpanda.coredata.backgroundsaves", 0);
    }
    return coredata_background_save_queue;
}

And this would only modify our background core data save method like so:

+ (void)saveDataInBackgroundWithContext:(void(^)(NSManagedObjectContext *context))saveBlock completion:(void(^)(void))completion
{
	dispatch_async(coredata_background_save_queue(), ^{
		[self saveDataInContext:saveBlock];
 
		dispatch_sync(dispatch_get_main_queue(), ^{
			completion();
		});
	});
}

Using blocks, GCD and a little bit of convention, we’ve helped to make multithreaded Core Data code much easier to write and stay consistent with Apple’s recommended methods. Not only that, but this solution consolodates much of the manual boilerplate setup required to properly save data in the background and safely update data throughout your applications.

Core Data, for both iPhone and Mac, is a very powerful framework for persisting your objects out of memory, and into a more permanent storage medium. With the enormous power of Core Data, it can be easy to slip into the trap of thinking that Core Data is very complex.

Easy Fetches

When I was first learning about Core Data, I naively thought that getting data from a data store would be easy. Core Data is a framework for fetching and persisting data, after all! I eventually learned that the minimum code required in order to fetch data from the store resembled this:

NSManagedObjectContext *context = [[[UIApplication sharedApplication] delegate] managedObjectContext];
NSFetchRequest *request = [[NSFetchRequest alloc] init];
 
NSEntityDescription *entity = [NSEntityDescription entityForName:@"MyEntity" inManagedObjectContext:context];
[request setEntity:entity];
 
NSPredicate *searchFilter = [NSPredicate predicateWithFormat:@"attribute = %@", searchingFor];
NSError *error = nil;
NSArray *results = [context executeFetchRequest:request error:&error];

This is quite a bit of code for pulling data out of a store, and this doesn’t even include error handling. I’ve often seen this code copied and pasted where needed in other projects. Some developers even use code snippets to generate these fetch requests. All that similar code can easily become a nightmare to maintain once your app starts to contain many entities. What I wanted was a little more automagic.

About a year ago, I ran across this post by Matt Gallagher on his terrific blog Cocoa with Love, which introduced the idea of the “one line fetch”. The blog post had a good idea, and a simple example of how to implement such an idea, however it occurred to me there were some ways I could enhance the example. The first was the use of the entity name in the method as a string parameter. This is required for the case that there are no custom NSManagedObject subclasses for your entities. And second, the example still required the helper methods to be part of your view controllers.

One reason to use helper methods to generate your fetch requests is that your code remains dry. That is, you remove duplication. Once you start using Core Data, you quickly realize that many requests start to look alike after a while. By consolidating this logic into a single method, or set of methods, we can be sure that optimizing one request can improve many requests. But perhaps more important is that by condensing the code, and removing the repetitive parts, you can easily see at a glance what the code intends to do, with the details only a method call away.

Dynamically Generating your Fetch Requests

In order to request data from your Core Data store, you must start with an NSFetchRequest. As the sample request above showed, we’ll need to at least set the entity for the data we’re intending to fetch.

I always use mogenerator to generate custom subclasses for my Core Data entities. With each custom subclass, you get some valuable information that can help ease the process of building helper methods to autogenerate fetch requests. The primary bit of useful information is a Class object that is related to your Entity. If your entity names and class names are identical, it’s fairly easy to derive a class method to create the correct NSEntityDescription at runtime by using the NSStringFromClass() function. However, with mogenerator, a convenience method that returns the entity description required for fetch requests is auto generated for you called entityInManagedObjectContext:.

When you have a class method, the self object refers to the current Class object, from which you can get a string to look up the proper entity description required for a lookup. This is a big step in autogenerating requests. In the case of mogenerated code, we can check if the current Class responds to a particular selector, entityInManagedObjectContext:, and call that instead. For now, assume that the following methods are class methods in an NSManagedObject subclass called MyEntity.

+ (NSEntityDescription *)entityDescriptionInContext:(NSManagedObjectContext *)context
{
    return [self respondsToSelector:@selector(entityInManagedObjectContext:)] ?
        [self performSelector:@selector(entityInManagedObjectContext:) withObject:context] :
        [NSEntityDescription entityForName:NSStringFromClass(self) inManagedObjectContext:context];
}

Using this method, we can dynamically determine the entity for which we should fetch data. So, let’s start by creating a class method to find all instances of a particular entity in the store:

+ (NSArray *)findAllObjects
{
    NSManagedObjectContext *context = [[[UIApplication sharedApplication] delegate] managedObjectContext];
    NSEntityDescription *entity = [self entityDescriptionInContext:context];
    NSFetchRequest *request = [[[NSFetchRequest alloc] init] autorelease];
    [request setEntity:entity];
    return [context executeFetchRequest:request error:nil];
}

And using this method from, for example a View Controller in our app, we could simply call:

[MyEntity findAllObjects];

The niceness of this syntax over the fully verbose glob is that at a glance I can quickly see what’s going on. In this case, I want all the instances of MyEntity in the store, in no particular order. Simple and to the point without having to decipher a series of NSFetchRequest customizations (which would be minimal for this example). In this case, we’re passing a message to the class method on MyEntity.

Next, we need to set some default error handling, and we have a simple way to find all objects in a store that are MyEntity instances.

+ (NSArray *)findAllObjects
{
    NSManagedObjectContext *context = [[[UIApplication sharedApplication] delegate] managedObjectContext];
    NSEntityDescription *entity = [self entityDescriptionInContext:context];
    NSFetchRequest *request = [[[NSFetchRequest alloc] init] autorelease];
    [request setEntity:entity];
 
    NSError *error = nil;
    NSArray *results = [context executeFetchRequest:request error:&error];
 
    if (error != nil)
    {
      //handle errors
    }
    return results;
}

I’m not explicitly adding error handling here, however inspecting the error object will give you some useful information to track down Core Data issues, such as validation errors, that might prevent your data from being saved. But there are two problems here. First, we don’t always want to use the default context from the Application Delegate. Second, and more importantly, we should be able to use this for other entities in the store.

Addressing the first issue–the matter of specifying the context–this is important because there will be cases where we need to perform some operation on this data in the background on another thread. The proper way to do that in Core Data is to create another context, so let’s make the context a method parameter:

+ (NSArray *)findAllObjectsInContext:(NSManagedObjectContext *)context
{
    ...
}

and we can still use the simple version of the find method like this:

+ (NSArray *) findAllObjects
{
    return [self findAllObjectsInContext:[[[UIApplication sharedApplication] delegate] managedObjectContext]];
}

So, now we have two methods that help find entities in our store, and the context is an injectable dependency. Fancy…and helpful for those cases involving threads.

The other problem was the matter of reusing this method across any custom NSManagedObject subclass. All objects that store data for you in Core Data are instances of or subclasses of NSManagedObject. The easiest way to reuse this method in this case is via a category. However, by placing these methods in a category of NSManagedObject, rather than the MyEntity subclass, all subclasses of NSManagedObject will inherit them at runtime. This means all entities in our store will have this nice helper method for retrieving all instances.

//NSManagedObject+EasyFetching.h
@interface NSManagedObject (EasyFetching)
 
+ (NSEntityDescription *)entityDescriptionInContext:(NSManagedObjectContext *)context;
+ (NSArray *)findAllObjects;
+ (NSArray *)findAllObjectsInContext:(NSManagedObjectContext *)context;
 
@end
 
//NSManagedObject+EasyFetching.m
@implementation NSManagedObject (EasyFetching)
 
+ (NSEntityDescription *)entityDescriptionInContext:(NSManagedObjectContext *)context;
{
    return [self respondsToSelector:@selector(entityInManagedObjectContext:)] ?
    [self performSelector:@selector(entityInManagedObjectContext:) withObject:context] :
    [NSEntityDescription entityForName:NSStringFromClass(self) inManagedObjectContext:context];
}
 
+ (NSArray *)findAllObjects;
{
    NSManagedObjectContext *context = [[[UIApplication sharedApplication] delegate] managedObjectContext];
    return [self findAllObjectsInContext:context];
}
 
+ (NSArray *)findAllObjectsInContext:(NSManagedObjectContext *)context;
{
    NSEntityDescription *entity = [self entityDescriptionInContext:context];
    NSFetchRequest *request = [[[NSFetchRequest alloc] init] autorelease];
    [request setEntity:entity];
    NSError *error = nil;
    NSArray *results = [context executeFetchRequest:request error:&error];
    if (error != nil)
    {
        //handle errors
    }
    return results;
}
@end

So now we have a class level find method on any NSManagedObject that will:

• create the fetch request based on the class,
• execute that request
• use the same error handling for all requests (this is handy for logging core data errors to the console)

And, in addition, we now have a place to put any custom helper methods. Since these methods are categories, they won’t interfere with any current fetching code already in your apps. These methods also have the handy side effect of being included in the type-ahead list in Xcode so they are there when you need them.

Next time, we’ll discuss how to handle other common request operations such as filtering, prefetching keys and even returning only one object.

Download Demo Project

The Trick Is In Listening To The View

Let me cut to the chase here and clue you in on what you need to do. The easiest way to take advantage of the CATiledLayer is to create a UIView based subclass and override the +layerClass class method to return a [CATiledLayer class].

+ layerClass
{
  return [CATiledLayer class];
}

Then, you just need to override drawRect: and draw what it tells you to draw. That’s it! Listen to the UIView. It’s telling you in drawRect: which rectangle it wants to draw. So while your user is scrolling a scroll view that contains your view, for example, drawRect: will be getting called continuously. You just need to calculate how that rectangle corresponds to the image you’re wanting to draw.

- (void)drawRect:(CGRect)rect
{
  // You cant get the current context if you need it.
   CGContextRef context = UIGraphicsGetCurrentContext();
 
  // Your drawing code here ...
}

I’ll show you a fuller implementation of drawRect: later. Feel free to skip there now or even download the demo project if you want to see the project in action. First I’m going to discuss how we get our tiles and truly take advantage of the memory use reduction we get from the CATiledLayer.

The Downside Is Tiling the Image

So, now that you’ve implemented a UIView derived subclass that overrides drawRect: performance is going to improve drastically, right? Well, unfortunately, not exactly. If you pull the entire image into memory with -imageNamed or even -imageWithContentsOfFile, you’re going to be up against the exact same memory problem you had before using a tiled layer. So what are the solutions? Well, if there were a way to map tiles to bytes on disk, that would be great, but unfortunately that is far more complicated and I’m not even sure it’s possible. In the end, we have to actually tile the image manually and store the images on disk to be loaded on demand.

So, the first question I asked when I realized this is can I do the tiling programmatically and write the files out to disk or do I need to slice them up in a photo editor manually? Just like everything in programming, there are tradeoffs between various solutions. If you have a different part of your workflow where it makes sense to tile the images before sending them to the device, I would choose that solution, however, that doesn’t seem terribly likely. In most cases you’re probably going to need to tile the images on device programmatically. If that’s true, then I suggest that you don’t just tile every image, but rather set a threshold size. If your images reach a certain dimension, only tile those since it will take some time and processing power to do so.

Of course, you’re going to want to do your tiling on a background thread as to not block your user interface, but here is some basic image tiling code that will write your image tiles to disk. You can place this in an NSOperation or use a block and run it on a background queue.

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

- (void)saveTilesOfSize:(CGSize)size 
               forImage:(UIImage*)image 
            toDirectory:(NSString*)directoryPath 
            usingPrefix:(NSString*)prefix
{
  CGFloat cols = [image size].width / size.width;
  CGFloat rows = [image size].height / size.height;
 
  int fullColumns = floorf(cols);
  int fullRows = floorf(rows);
 
  CGFloat remainderWidth = [image size].width - 
                          (fullColumns * size.width);
  CGFloat remainderHeight = [image size].height - 
                          (fullRows * size.height);
 
 
  if (cols > fullColumns) fullColumns++;
  if (rows > fullRows) fullRows++;
 
  CGImageRef fullImage = [image CGImage];
 
  for (int y = 0; y < fullRows; ++y) {
    for (int x = 0; x < fullColumns; ++x) {
      CGSize tileSize = size;
      if (x + 1 == fullColumns && remainderWidth > 0) {
        // Last column
        tileSize.width = remainderWidth;
      }
      if (y + 1 == fullRows && remainderHeight > 0) {
        // Last row
        tileSize.height = remainderHeight;
      }
 
      CGImageRef tileImage = CGImageCreateWithImageInRect(fullImage, 
                                        (CGRect){{x*size.width, y*size.height}, 
                                          tileSize});
      NSData *imageData = UIImagePNGRepresentation([UIImage imageWithCGImage:tileImage]);
      NSString *path = [NSString stringWithFormat:@"%@/%@%d_%d.png", 
                        directoryPath, prefix, x, y];
      [imageData writeToFile:path atomically:NO];
    }
  }    
}

Let me walk you through this a little bit. We pass in the size of the tiles we want to break our image into. We pass in the image itself, the directory we want to save it to, and finally a prefix that we will use as a unique identifier for the file names for the image in question. We need this so that we can retrieve them again later when we’re ready display them.

The first thing we do is calculate the number of tiles we’re going to have in columns and rows by dividing the total width by the tile width and the total height by the tile height. The result is a floating point number. We then get the number of columns and rows that are full sized tiles by using floorf(). We then calculate the width of the last column and the height of last row. Next we iterate through the entire grid of what will soon be tiled images, columns per row. Then we extract the image data at the rect in question and write its contents to disk using an NSData. The filename format we’re using takes into account the x and y positions in our grid of tiles such that an image would have its tiles named:

<directory>/<prefix>x_y.png

Where directory and prefix are the strings passed into the function. The .png extension here is really just for clarity. It is completely unnecessary.

Implementing Draw Rect

The first implementation of CATiledLayer expected that you would create a delegate for your layer and then override

- (void)drawLayer:(CALayer*)theLayer 
            inContext:(CGContextRef)theContext

This was error prone for several reasons. The trouble was you couldn’t use both UIKit and Core Graphics calls to draw in the layer which people would often do. They would soon start asking why their app was crashing and would discover that the problem could be solved by only drawing using only Core Graphics.

Now, in iOS4, things have gotten much easier. You can simply override drawRect: in your UIView subclass and everything works correctly. To draw my layer correctly, I adapted the drawing code you find in the PhotoScroller sample code from the WWDC 2010 sessions (Link opens iTunes). It looks like this:

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

- (void)drawRect:(CGRect)rect {
 	CGContextRef context = UIGraphicsGetCurrentContext();
 
  CGSize tileSize = (CGSize){256, 256};
 
  int firstCol = floorf(CGRectGetMinX(rect) / tileSize.width);
  int lastCol = floorf((CGRectGetMaxX(rect)-1) / tileSize.width);
  int firstRow = floorf(CGRectGetMinY(rect) / tileSize.height);
  int lastRow = floorf((CGRectGetMaxY(rect)-1) / tileSize.height);
 
  for (int row = firstRow; row <= lastRow; row++) {
    for (int col = firstCol; col <= lastCol; col++) {
      UIImage *tile = [self tileAtCol:col row:row];
 
      CGRect tileRect = CGRectMake(tileSize.width * col, 
                         tileSize.height * row,
                         tileSize.width, tileSize.height);
 
      tileRect = CGRectIntersection(self.bounds, tileRect);
 
      [tile drawInRect:tileRect];
 
      // Draw a white line around the tile border so 
      // we can see it
      [[UIColor whiteColor] set];
      CGContextSetLineWidth(context, 6.0);
      CGContextStrokeRect(context, tileRect);
    }
  }
}

Our view port in the app is set by the frame of the scroll view. This view is a lot larger than a single tile, which we have set to the default size of 256 x 256. That means we need to find all of the tiles that need to be drawn for displaying in the view port. So, we calculate the first column, last column, first row, and last row. This tells us where within the image we need to start and stop drawing. It also tells us which tiles we need to load. Once we’ve got all of these rows and columns calculated, we can then iterate through them and grab the tile for the current row and column using the same filename format we used to save the files in the first place. The code to load the image tiles looks like this:

1
2
3
4
5

- (UIImage*)tileAtCol:(int)col row:(int)row
{
  NSString *path = [NSString stringWithFormat:@"%@/%@%d_%d.png", tileDirectory, tileTag, col, row];
  return [UIImage imageWithContentsOfFile:path];  
}

Notice we’re using -imageWithContentsOfFile rather than -imageNamed, since -imageNamed actually caches the image in memory–which we don’t want. If we used that, we would be right back at our memory usage issue after scrolling around for a few minutes.

Conclusion

Using the CATiledLayer makes a lot of sense when memory is of the essence, which it is much of the time when doing iOS development. Examples from Apple and other places do a good job showing how you can use a tiled layer for use with PDFs, but if you want to tile an image, things are a little more complicated. I hope this post has served to help you better understand this powerful Core Animation layer. Until next time.

Download Demo Project

Notes on the Demo Project

When running on the device the image I am tiling is just too large to be tiled completely before the app uses up too much memory and is killed. You will probably want to run in the simulator to see the tiling finish. As noted in the code comments, you un-comment the tiling code and do a first run with the app allowing it to finish tiling. Then, stop the app and re-comment that tiling code and it will just load and display the tiles it created without having to go through that tiling again. I suppose I could have made the tiling code get called in response to a button tap or something like that, but I’ll leave that as an exercise for the reader. Contact me through the comments below if you have any problems or questions.

The documentation on Core Data for the iPhone has lead to some confusion about how best to use Core Data on a Cocoa Touch device. One particular section seems to be the most confusing, specifically:

A view controller typically shouldn’t retrieve the context from a global object such as the application delegate. This tends to make the application architecture rigid. Neither should a view controller typically create a context for its own use. This may mean that operations performed using the controller’s context aren’t registered with other contexts, so different view controllers will have different perspectives on the data.

When you create a view controller, you pass it a context. You pass an existing context, or (in a situation where you want the new controller to manage a discrete set of edits) a new context that you create for it. It’s typically the responsibility of the application delegate to create a context to pass to the first view controller that’s displayed.

The idea behind this section is the issue of rigidity. Ideally, each view controller should be an island on its own. It should not rely on its parent, nor should it rely on the Application Delegate. Once a view controller is pushed onto the screen it should ideally be its own master.

Why Rigidity is bad

It is fairly common when designing a Cocoa Touch application to “hard code” everything. Take the following navigation controller design:

When this design, it is common to code each view controller and make it “aware” of its parent. In that design, it would be common to see view controller B call methods or call back (to its delegate) view controller A. While there is nothing technically wrong with this design, it is very rigid. It is nearly impossible to either move view controller B to another location in the stack or to reuse view controller B somewhere else. This is the trap that the documentation is trying to help new developers avoid.

Solution One

Again using a standard/normal navigation controller design, it is expected that the detail flows from left to right. The left most (or root) view controller contains the most vague information and the right most (or deepest) view controller contains the greatest detail.

In this case then the best solution is to use a UIFetchedResultsController. This controller can be considered a thin layer between the view controllers and the Core Data bits. The advantage is that the UIFetchedResultsController is designed to work with tables. The other advantage is that your least detailed view (the root most likely) can listen as the delegate of the UIFetchedResultsController for changes and update itself.

In this design, however, instead of passing around a context, you would hand off just the entity that the child view controller needs to know about. The Core Data Recipes example provided by Apple illustrates this design quite well.

How does this break rigidity? Each view controller, from the root on down, only knows what is passed into it. The root gets the UIFetchedResultsController passed into it. The child views only get the items it cares about passed into it. None of them care what their parent view controller is. There is no call back to a parent.

Solution two

What happens when we don’t have a typical navigation controller design? Perhaps a child view can pop up a modal view that displays different information. Perhaps a child view, for whatever reason needs to access information that cannot be directly passed into it every time.

In these cases there are a few different options.

View already has a NSManagedObject

Following our example above, lets say that view controller C needs to create a new object. Perhaps it is a detail view of a recipe and the user wants to add a new recipe type (perhaps she is a vegan and just discovered there is no vegan type in the list). In this case we have passed in an entity (the recipe) but not a reference to the NSManagedObjectContext. Fortunately this solution is easy to fix. The NSManagedObject retains a reference to its NSManagedObjectContext internally and we can access it. Therefore we can easily retrieve the NSManagedObjectContext from the NSManagedObject and create the new Type entity and pass it to the modal child or whatever our design calls for.

This again avoids rigidity because the view controller that represents the entity does not need to call up to a parent object or the UIApplication delegate. It is self contained and only manages view controllers that are down stream from it.

View does not have a NSManagedObject

In this situation things are slightly more complicated. In this case we want to create a @property for the NSManagedObjectContext and require that our creator set the property.

@interface MyViewController : ViewController
{
    NSManagedObjectContext *moc;
}

@property (nonatomic, retain) NSManagedObjectContext *moc;

@end

Again, the view controller is an island of its own because it does not care where that NSManagedObjectContext came from. All it knows is that it is required for the view to function. It does not care of it is a new NSManagedObjectContext specifically created for its use (perhaps for a cancelable edit tree) or if it is the same NSManagedObjectContext that has been passed around since the launch of the application. All it knows is that it has the elements it needs to perform its function.

By making the NSManagedObjectContext a settable property we can also transplant the view easily. If, at some point in the project lifecycle, we decide that it makes more sense to have the following design:

Taking from Apple’s Recipes Application, perhaps we decide that moving from the table view directly to the image of the recipe is more pleasing to the users and that when they want to see how to make it they can “flip” the image over and see the detail.

Making this change with each view controller being an island is quite simple. We just rearrange the views without having to worry too much about breaking the application.

Solution three

Up until now we have been looking at just a navigation controller design. But what about tab bars? In the situation of a tab bar we again want to avoid rigidity because it is even more common that tabs will get moved around.

The solution to this is to again use a @property for the NSManagedObjectContext and require that the creator set this property before the view is displayed on screen. If you are creating the tabs in code this is trivial because you are already calling init on the view controller and you can add one more line of code after the init to set the property.

If the user interface is being developed mostly in Interface Builder it is slightly more tricky. Personally I am not a fan of creating navigation controllers or tab bar controllers in Interface Builder. However if that is the design then I would recommend referencing the view controllers as properties and passing along the context upon initialization of the application. It may be possible to do this entirely in Interface Builder but I am not comfortable enough to recommend that as a solution.

Conclusion

The overall idea behind this article is to keep each view controller separate from anything up stream or in a different silo. This will make the design far more flexible in the long run. Any time that you feel the “need” to pass in a parent view controller to a child view controller, reconsider the design. Consider using a @protocol delegate design or NSNotification calls instead. Keep each view controller as its own private island.

Overriding Touch Event Handlers

In order to know how many times your user tapped, you listen for the events in the various touch handlers. Let start with -touchesEnded. This is where we will determine how many taps we received and respond accordingly. Consider the following code.

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

- (void)touchesEnded:(NSSet*)touches withEvent:(UIEvent*)event 
{
  if(touches.count == 1)
  {  
    if([[touches anyObject] tapCount] == 2)
    {
      [self handleDoubleTap];
    }
    else if([[touches anyObject] tapCount] == 3)
    {
      [self handleTripleTap];
    }
    else
    {
      [self handleSingleTap]; 
    }
  }
}

If you place a breakpoint inside each of the code blocks for the three tap counts, you will find that in the case where you triple tap, it will break in all three. If you double tap, it will break in both the double tap and single tap and of course if you single tap, it will break in the single tap branch.

In most cases, this is not desirable. You will likely want a clean differentiation between each touch as each tap count will likely mean something different. So how can we fix this? The trick is to use -peformSelector:withObject:afterDelay and then canceling the perform action if a new action occurs. Got it?

Wait For It…

If you call the method directly as we did in the sample code above, there is no way to delay when it runs nor is there a way to cancel it should another tap be received. Both of these things are necessary. If you think about it, waiting to run our -handleSingleTap method until a certain amount of time passes helps make sure it actually was a double tap. If the user taps once and nothing else occurs, we’re safe to run the -handleSingleTap code. If another tap is received in the mean time, however, we can cancel the action from the first tap. The way we do this is by changing our -touchesEnded: code to something like this:

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

- (void)touchesEnded:(NSSet*)touches withEvent:(UIEvent*)event 
{
  if(touches.count == 1)
  {  
    if([[touches anyObject] tapCount] == 2)
    {
      [self performSelector:@selector(handleDoubleTap)
                 withObject:nil
                 afterDelay:0.35]; 
    }
    else if([[touches anyObject] tapCount] == 3)
    {
      [self handleTripleTap];
    }
    else
    {
      [self performSelector:@selector(handleSingleTap)
                 withObject:nil
                 afterDelay:0.35]; 
    }
  }
}

Notice that we are delaying 350 milliseconds to see if another event occurs. You should also notice that we still call -handleTripleTap directly without using -performSelector:withObject:afterDelay. This is because it has now been isolated as a distinct event. If we get a triple tap, we’re pretty well assured now that a double or single tap event was not actually run as those events will have been cancelled. So how does that work? How do we cancel them?

Canceling The Action

Now that we are waiting around to see if another tap event occurs, we need to override the -touchesBegan: method. It will look something like this:

1
2
3
4
5
6
7
8
9
10

- (void)touchesBegan:(NSSet*)touches withEvent:(UIEvent*)event
{
  [NSObject cancelPreviousPerformRequestsWithTarget:self
                                           selector:@selector(handleSingleTap)
                                             object:nil];
 
  [NSObject cancelPreviousPerformRequestsWithTarget:self
                                           selector:@selector(handleDoubleTap)
                                             object:nil];
}

The method -cancelPreviousPerformRequestsWithTarget:selector:object: is able to determine which action you want to cancel and then cancel it preventing the selectors, -handleSingleTap or -handleDoubleTap from being called–assuming the second or third taps occurred within the allocated 350 milliseconds. That’s all there is to it.

There *Is* a Catch

That is all there is to it, however, you have to be careful if you intend to pass parameters to your selectors. If you use a selector that takes a parameter so that you have to call something with -performSelector:withObject:afterDelay: passing an object to the second parameter, you will need that object or one identical to it in your call to cancel the action with -cancelPreviousPerformRequestsWithTarget:selector:object:. It must be able to evaluate to true when equals is called on the object passed into the object parameter. This can be tricky, but you can overcome it in one of two ways using an ivar:

• Create an ivar to hold onto the variable that you will use as a parameter to the cancel when you first pass it to the -performSelector:withObject:afterDelay: call.

• Create an ivar to hold onto the variable when you first enter touches ended and call -performSelector:withObject:afterDelay passing it nil for the object parameter. Then, grab the ivar when you need it in your handler code. The cancel call can then take nil for its object parameter.

These points are crucial if you are intending to pass parameters as the cancel will fail if you try to pass a parameter and it doesn’t match what you used in your call to -performSelector:withObjecct:afterDelay:. The only parameter that doesn’t matter is the afterDelay: param.

Conclusion

I’m finding the need to differentiate tap counts more and more often so this post is really as much a way for me to keep a journal of things I need to do frequently as it is to help others figure things out too. I hope it’s been helpful to you. Until next time.

Update

So, apparently Gesture Recognizers do address this issue. I had looked at them as a possible solution, but ran into the same differentiation problems, hence this blog post. However, Ashley Clark pointed me to the -requireGestureRecognizerToFail: method, which apparently enables you to have this cancellation functionality by creating a dependency between recognizers. The code to take advantage of it looks something like this:

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

UITapGestureRecognizer *tripleTap = 
[[UITapGestureRecognizer alloc]
 initWithTarget:self action:@selector(handleTripleTap:)];
 
[tripleTap setNumberOfTapsRequired:3];
[[self view] addGestureRecognizer:tripleTap];
[tripleTap release];
 
UITapGestureRecognizer *doubleTap = 
[[UITapGestureRecognizer alloc]
 initWithTarget:self action:@selector(handleDoubleTap:)];
 
[doubleTap setNumberOfTapsRequired:2];
[doubleTap requireGestureRecognizerToFail:tripleTap];
[[self view] addGestureRecognizer:doubleTap];
[doubleTap release];
 
UITapGestureRecognizer *singleTap = 
[[UITapGestureRecognizer alloc]
 initWithTarget:self action:@selector(handleSingleTap:)];
 
[singleTap setNumberOfTapsRequired:1]; // Unnecessary since it's the default
[singleTap requireGestureRecognizerToFail:doubleTap];
[[self view] addGestureRecognizer:singleTap];
[singleTap release];

So, if your project is 3.2 and later, use gesture recognizers. The effect is about the same, but the code is quite a bit cleaner.

Download the source code for the Favorite Things project.

A Few of My Favorite Things

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

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

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

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

Display Order Attribute

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

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

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

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

Favorites Change

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

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

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

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

Further Considerations

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

Finishing Up

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

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

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

1
2
3
4
5
6
7
8

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

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

1
2
3
4

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

Conclusion

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

Download the source code for the Favorite Things project.

Gut The Default Template

It’s not quite as drastic as the work ‘gut’ might imply, but you want to remove some things from the default template nib. To get started create a Split View project, by selecting File | New Project… in Xcode. Then choose Split View-based Application and click Choose…. Name your application. I called mine ‘SpiffySplitView’.

Double-click DetailView.xib under the Resources group in your newly created project. This will open Interface Builder.

The first thing you will notice in the Interface Builder editor is that there is a UINavigationBar at the top. Select this bar and delete it. We will be switching the detail view of this split view project to use a UINavigationController which will add this nav bar back in for us but will provide the whole navigation stack along with it providing us the flexibility to push new view controllers in the detail view.

In the View inspector you will also want to make the Orientation Landscape, make the Top Bar a Navigation Bar, and set the Split View option to “Detail”.

Once you have made these changes, save the nib and switch back to Xcode. Now, double click the MainWindow.xib file in the Resources section of your Xcode project which will open it in Interface Builder.

Implementing a Navigation Controller In The Detail View

When MainWindow.xib opens in Interface Builder, take a look at the MainWindow.xib resources and switch to the detailed list view if you haven’t already so that the window looks something like this:

Notice that the Split View Controller contains two view controllers. The first one is a navigation controller, but the second one is our detail view controller. The first thing you want to do is change that. From the Library palette in Interface Builder, select the Navigation Controller object and drag and drop it on top of the detail view controller in the resources window.

The detail view controller will automatically switch to a navigation controller. Now you need to twirl down the new nav controller and change the root view controller type to a DetailViewController by switching to the Identity tab in the inspector.

Finally we are going to need to make our new navigation controller a delegate of the UISplitViewController in order to receive split view change notifications. Drag a connection from the Split View Controller to the Detail View Controller and select delegate.

Save your work. If you switch back to Xcode and run the application, you may not notice much of a difference in the look of the application, however, we can now make some changes in code that will give us a lot more flexibility.

Changes In Code

Edit DetailViewController.m in Xcode and change the -viewDidLoad method to set a title for the view controller. This will get passed up to the navigation controller which will display the title in the navigation bar.

1
2
3
4
5

- (void)viewDidLoad
{
  [super viewDidLoad];
  [self setTitle:@"Spiffy"];
}

This code will allow you to see the word ‘Spiffy’ in the navigation bar.

Next, you will notice that in portrait view, we have no button to tap to see our table view. It is only available in landscape view. To remedy this, you need to change a few lines of code–again in the DetailViewController you will modify the split view delegate methods. These methods simple add and remove the bar button item depending upon which mode we’re in, landscape or portrait or more specifically whether we are showing or hiding our list view controller.

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

- (void)splitViewController:(UISplitViewController*)svc 
     willHideViewController:(UIViewController *)aViewController 
          withBarButtonItem:(UIBarButtonItem*)barButtonItem 
       forPopoverController:(UIPopoverController*)pc
{  
  [barButtonItem setTitle:@"Root List"];
  [[self navigationItem] setLeftBarButtonItem:barButtonItem];
  [self setPopoverController:pc];
}
 
 
- (void)splitViewController:(UISplitViewController*)svc 
     willShowViewController:(UIViewController *)aViewController 
  invalidatingBarButtonItem:(UIBarButtonItem *)barButtonItem
{
  [[self navigationItem] setLeftBarButtonItem:nil];
  [self setPopoverController:nil];
}

Now you can see our button show and hide correctly.

A problem you my run into now is that when you select one of the items in the list view, the detail view doesn’t actually update. This is due to the fact that we disconnected things when we changed our detail view controller in the split view to a navigation controller and we never re-connected it. To re-connect, open MainWindow.xib in Interface Builder again by double clicking it from the Resources group in Xcode. Then drag a connection from the root view controller to the Detail View Controller and select detailViewController.

The Point

So now what? The project is, in essence, now back to where it was when we started, right? Except now we can push new view controllers onto the stack. To demonstrate this, let’s add a button to the detail view controller that will be the trigger for pushing a new view controller and then we can create the new view controller to push.

In Xcode, create an action in the detail view controller that we will connect to. The code will look something like this.

1
2
3
4
5

- (IBAction)pushNewViewController:(id)sender;
{
  // Create and push new view controller here
 
}

In Xcode, double click the DetailView.xib to open it in Interface Builder. Then add a button to the view. Drag a connection from the new button to the action we just created.

Save your changes and go back into Xcode. Select File | New File…. In the ensuing dialog, choose UIViewController subclass in the Cocoa Touch Class group and make sure you have Targeted for iPad and With XIB for user interface selected. Click Next and then provide a name. I called my NewViewController.

Double-click the NewViewController.xib file to open it in Interface Builder. Change the settings on the view to do the following:

• Set orientation to landscape
• Set Top Bar to Navigation Bar
• Set Split View to Detail

Save your changes and switch back to Xcode. In the -viewDidLoad of your NewViewController.m file, set the title again.

1
2
3
4
5

- (void)viewDidLoad
{
  [super viewDidLoad];
  [self setTitle:@"New View Controller"];
}

Now, in your DetailViewController.m file, #import the NewViewController.h file and then implement the push new view controller action.

1
2
3
4
5
6
7

- (IBAction)pushNewViewController:(id)sender;
{
  // Create and push new view controller here
  NewViewController *controller = [[NewViewController alloc] init];
  [[self navigationController] pushViewController:controller animated:YES];
  [controller release], controller = nil;
}

Now, when you tap the button on the detail view controller, a NewViewController will be pushed onto the navigation stack.

Conclusion

There are certainly legitimate reasons to place a navigation bar into your view manually. You might want to just use it as a place for tool bar items or other information. You may not need the navigation controller stack functionality, but providing yourself a way to push a new view controller on the navigation stack opens up additional possibilities while retaining the capabilities you have by using only a navigation bar. As the kids say, “it’s all good”. Until next time.

SpiffySplitView Xcode Project

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

The File

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

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

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

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

#ifdef DEBUG

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

#define DLog(...)

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

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

#define ALog(...)

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

1

NSAssert(NO, @"It failed");

or if you want to see the variables:

1

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

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

1

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

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

NS_BLOCK_ASSERTIONS

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

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

#define ZAssert(condition, ...)

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

1
2
3
4
5
6

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

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

With ZAssert it gets a lot cleaner:

1
2

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

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

Wrap Up

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

Acknowledgements

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

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

Note: The last code block has been corrected as the save was inadvertently being flipped.

In many cases when you go to access remote data, you do so through a web service API. While services based on such technologies as SOAP or XML-RPC are standards that provide reasonable methods for retrieving and updating data, REST seems to be the methodology gaining the most ground lately. For our purpose in this post I won’t get into great detail of how to implement a REST base web service as, again, REST is not a specific implementation but rather a methodology. (Read up on it elsewhere if you don’t understand what this means). However, I will talk about it briefly so that you can get on the right path for doing your own REST implementation.

What Is The Cloud

It seems that the term ‘cloud’ in this context has been around for a pretty long time, however, you can just think of it as, well, the Internet. If you access your data “in the cloud”, you are accessing your data that is hosted on some server somewhere in the world. The idea behind it being that you can always access it no matter where you are. If your data is not “in the cloud”, then it is hosted locally only and only accessible from that location.

Amazon.com among other technology leaders has helped to make this metaphor easier to understand. If you are familiar with Amazon S3 (Simple Storage Service), then you know what it means to store your data “in the cloud”. Amazon has made it very cheap and very easy to access data that you store on their servers from anywhere in the world. They provide a RESTful web service through which you can securely add, remove, and update data that you have stored there. If you have image or video assets, for example, that you find get accessed a lot through your website, you may find that hosting those files on S3 is cheaper than paying your own web host to provide the bandwidth and storage for them. This is a perfect example of what cloud computing is and provides.

On a more generic level, cloud computing can mean setting up your own service and providing access to resources or data in the same fashion. The difference in this case, however, is that you are managing it all on your own. Let’s take a look at how you might do this.

Sending Arbitrary Data

The simplest PHP script can really teach you a great deal about what is going on between client and server. Remember that since we are depending on the Apache web server to serve up our PHP responses a huge portion of the work is already done. We don’t have to worry about low-level networking APIs and sockets. Instead we can create a simple connection using a URL and the NSURLConnection class and we’re most of the way there. Consider the following PHP code sample.

1
2
3

<?php
print $HTTP_RAW_POST_DATA;
?>

With one line of code (not including the tags), we have just implemented an echo server. Whatever you send to this script on the server will be sent right back to you. You should understand though that it is the body of the request that gets stored in this $HTTP_RAW_POST_DATA variable. So what does that mean?

This really means that you can send anything you want as the body of the request and this script will store it in the $HTTP_RAW_POST_DATA and then print it back as the response. You just specify in your request the type of data you’re sending. Say you want to send raw XML, for example, you specify”‘text/xml” as the content-type of the request that you will hand off to your NSURLConnection as in the following code snippet.

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

NSMutableURLRequest *request = [[NSMutableURLRequest alloc] 
        initWithURL:[NSURL 
        URLWithString:@"http://www.cimgf.com/testpost.php"]];
 
[request setHTTPMethod:@"POST"];
[request setValue:@"text/xml" 
              forHTTPHeaderField:@"Content-type"];
 
NSString *xmlString = @"<data><item>Item 1</item><item>Item 2</item></data>";
 
[request setValue:[NSString stringWithFormat:@"%d",
        [xmlString length]] 
        forHTTPHeaderField:@"Content-length"];
 
[request setHTTPBody:[xmlString 
        dataUsingEncoding:NSUTF8StringEncoding]];
 
[[NSURLConnection alloc] 
        initWithRequest:request 
                   delegate:self];

When this request finishes, the same XML in the xmlString variable will be sent right back to our application and will be available in our delegate method, - (void)connectionDidFinishLoading:(NSURLConnection *)connection; assuming we’ve been appending the data to an NSMutableData object in our delegate method, - (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)d;.

This example is just echoing back whatever we send, but if we wanted to get a little fancier, we could load and parse the XML with the PHP XML parser and respond back to the client with something more useful.

What is also interesting about this code is that you can replace the body of the request with any data type you’re interested in POSTing to your server. If you post image data, for example, you can save that image data on the server side using something like this PHP script:

1
2
3
4
5
6
7
8
9

<?php
$handle = fopen("image.png", "wb"); // write binary
 
fwrite($handle, $HTTP_RAW_POST_DATA);
 
fclose($handle);
 
print "Received image file.";
?>

Keep in mind that this is very primitive and it does no sanity checking on the body data. You would need to add that in order to implement any real world server side application. That being said, these few lines of code demonstrate how you can send most any data as the request body and process it on the server side. Our Objective-C code from earlier modified to support sending a PNG image would look like this:

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

NSData *imageData = UIImagePNGRepresentation([UIImage imageNamed@"localimage.png"]);
 
NSMutableURLRequest *request = [[NSMutableURLRequest alloc] 
        initWithURL:[NSURL 
        URLWithString:@"http://www.cimgf.com/testpostimage.php"]]; // Not a real URL. 
 
[request setHTTPMethod:@"POST"];
[request setValue:@"image/png" 
        forHTTPHeaderField:@"Content-type"];
[request setValue:[NSString stringWithFormat:@"%d", 
        [imageData length]] 
        forHTTPHeaderField:@"Content-length"];
[request setHTTPBody:imageData];
 
[[NSURLConnection alloc] initWithRequest:request delegate:self];

The request we are sending will be asynchronous so our UI will not hang, however, there is no accurate progress monitoring capability, so you would need to implement that if you want to have an idea of how long it is going to take to post the image up to the web service. See the section called Simplifying Cloud Access below to see one solution to providing progress.

Working With Web Forms

A lot of web applications began life as web forms in which the user can obtain a list of records or a detail record based on input the user provides. You can post form data programmatically using a fairly trivial implementation not much different from the code we demonstrated above. In the previous section we discussed that you can send any arbitrary data to a web service or script by placing that data in the body of the request. This is also true for sending form data.

If you send form data, which is the default when you create an NSURLConnection object and use it to talk to your server, you will see a string of key value pairs in the same format you would normally see in a get request–something like key1=value1&key2=value2&key3=value3, etc. This is what gets sent in the body for web form requests.

Consider the following Bug Reporter web form.

Yes, yes, I know–it’s beautiful. Looks like something you would see circa 1995. Stick with me here as I’m trying to keep things simple. The form takes two fields and just formats the input and responds to the user with what the user entered. This same form can also be submitted using code similar to what we’ve already shown. Here is how you would programmatically post data to this form using and NSURLConnection/NSURLRequest.

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

NSMutableURLRequest *request = 
        [[NSMutableURLRequest alloc] initWithURL:
            [NSURL URLWithString:@"http://www.cimgf.com/test/testform.php"]];
 
[request setHTTPMethod:@"POST"];
 
NSString *postString = @"go=1&name=Bad%20Bad%20Bug&description=This%20bug%20is%20really%20really%20super%20bad.";
 
[request setValue:[NSString 
        stringWithFormat:@"%d", [postString length]] 
        forHTTPHeaderField:@"Content-length"];
 
[request setHTTPBody:[postString 
        dataUsingEncoding:NSUTF8StringEncoding]];
 
[[NSURLConnection alloc] 
        initWithRequest:request delegate:self];

Notice that we are passing a variable called go in the postString variable. This tells our PHP script to see the request as if the submit button was clicked. You’ll notice in the PHP script that we are checking whether the submit button was clicked with the call to isset($_POST['go']). Take a look at the complete PHP web form script.

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

<html>
<head><title>Bug Reporter</title></head>
<body>
<h2>Fancy Bug Reporter</h2>
<hr />
<?php
if (isset($_POST['go']))
{
        // Form was posted
        print "User submitted bug: ". $_POST['name'] . ": " . $_POST['description'];
}
else
{
        // Form was not posted, display form
?>
<form method="POST" action="<?php echo $PHP_SELF; ?>">
Bug Name:<br /><input type="text" name="name" maxlength="100" /><br />
Bug Description:<br /><input type="text" name="description" maxlength="1000" size="80" /><br />
<input type="submit" name="go" value="Add Bug">
</form>
<?php
}
?>
</body>
</html>

When the request finishes posting to this form, you will have the same HTML code in your data object as what you would see if you were to view the source in the actual web page after posting the form.

Simplifying Cloud Access

Ben Copsey developed a networking library called ASIHTTPRequest that is a really good replacement for NSURLConnection and related classes. There are a couple reasons I prefer it to NSURLConnection. These include:

• You can specify a delegate selector when you create your request object that will get called back when the request fails or succeeds. This is really just a preference over NSURLConnection/NSURLRequest as it just seems simpler to me.
• If you do want to see accurate progress for either downloads or uploads, you can pass in a reference to a UIActivityIndicatorView that will be updated automatically
• Different types of classes are available for different types of requests. For example, to post form data to a web form, you use ASIFormDataRequest instead of the more generic ASIHTTPRequest. It handles setting up the request body correctly and even enables you to post a file to the form if the form accepts one.
• While Ben still considers it experimental code, there is also support for access to Amazon’s S3. You create an ASIS3Request object and provide your S3 credentials to the request. Then you can create, update, or delete any assets you may be storing in your S3 buckets.

Using the example I mentioned earlier of sending XML to our PHP echo script, the request would now look like the following using the ASIHTTPRequest object:

1
2
3
4
5
6
7

ASIHTTPRequest *request = [ASIHTTPRequest requestWithURL:url];
NSString *xmlString = @"<data><item>Item 1</item><item>Item 2</item></data>";
[request appendPostData:[xmlString dataUsingEncoding:NSUTF8StringEncoding]];
[request setDelegate:self];
[request setDidFinishSelector:@selector(requestFinished:)];
[request setDidFailSelector:@selector(requestFailed:)];
[request startAsynchronous];

Then you implement your delegate selector as in the following:

1
2
3
4
5
6
7
8
9
10
11

- (void) requestFinished:(ASIHTTPRequest *)request
{
    NSString *response = [request responseString];
    // response contains the data returned from the server.
}
 
- (void) requestFailed:(ASIHTTPRequest *)request
{
    NSError *error = [request error];
    // Do something with the error.
}

Similarly, if you want to submit data to a form like we did earlier using the NSURLConnection/NSURLRequest combination, we can instead use the ASIFormDataRequest class.

1
2
3
4
5
6
7

ASIFormDataRequest *request = [ASIFormDataRequest requestWithURL:url];
[request setPostValue:@"1" forKey:@"go"];
[request setPostValue:@"Bad%20Bad%20Bug" forKey:@"name"];
[request setPostValue:@"This%20bug%20is%20really%20really%20super%20bad." forKey:@"description"];
[request setDidFinishSelector:@selector(requestFinished:)];
[request setDidFailSelector:@selector(requestFailed:)];
[request startAsynchronous];

When this request completes, we will have the formatted HTML in the responseString of the ASIHTTPRequest object:

1
2
3
4
5

- (void) requestFinished:(ASIHTTPRequest *)request
{
    NSString *response = [request responseString];
    // response contains the HTML response from the form.
}

I have come to prefer using ASIHTTPRequest for network access, however, this is a matter of taste. It is a very clean and well written library of classes, so I highly recommend it, but your mileage may vary.

So What About REST?

As I said at the beginning, I’m not going to go into a lot of detail about how to set up a REST web service as implementation of the REST philosophy is really up to the developer. However, here are a few points about how I go about it:

• Create individual server side scripts for each of the functions you want to implement. Instead of creating one master script, create one for each function you want to implement. This helps you maintain the code as when you need to update or fix something, it can be very targted.


• Make heavy use of mod_rewrite in your Apache server. Just use Apache. If you’re using something else, I’m sorry but you’re on your own. The rewrite mechanism that mod_rewrite provides enables you to take difficult to read URLs and make them easy to understand. WordPress, which we use for this blog, changes a URL that looks like this http://www.cimgf.com/?p=235, into something that looks like this: http://www.cimgf.com/2010/01/28/fun-with-uibuttons-and-core-animation-layers/ using mod_rewrite .
  
  It also so happens to provide a great way to implement a REST web service. Say you want to look up a bug by it’s unique ID in a bug tracker database. Your request would normally look like this http://www.cimgf.com/showbug.php?id=1234. The mod_rewrite module allows you to define rewrite rules that would change this URL to http://www.cimgf.com/bugs/1234. The rule to do this is very simple.

  1 2	RewriteEngine On RewriteRule ^bugs/([[:alnum:]]+)$ /showbug.php?id=$1

  The RewriteRule line uses a regular expression to define how to translate from the uglier URL to the pretty one. This regex means the following: “look for the word bugs at the beginning of the parameters string, followed by a forward slash, followed by one or more numbers until you reach the end of the line.” Notice the $1 in the second section. If you are not familiar with perl compatible regular expressions, this simply means use whatever was found between the parens in the regex. In our case the parens are “capturing” the ID of the bug the user is requesting. The rewrite rule is then passing that along to the real showbug.php script.
  
  You just add this to the .htaccess file in the directory where you are hosting your server side scripts and you will be able to load the load your data using the REST looking URL–assuming of course your Apache web server has mod_rewrite enabled. Even if you are using shared hosting, there is no excuse for a web host not to have this enabled. If it is not enabled, you need to find a new web host.


• Drive your web service with a scripted backend that connects to a commodity database like MySQL. Sanity check all of the input you get from your user by looking for vulnerabilities such as SQL injection attacks, but then insert the data into the database using standard SQL calls. If you receive the data, as XML for example, you can simply parse the XML into a DOM object and insert it from there. Better yet, use a (PHP) server side module that converts from XML to SQL for you.


• Use a framework like Rails. Most of the folks I know who have used it have nothing to say but good about implementing web services using Ruby on Rails. I can’t recommend it personally, but people I respect swear by it. It handles a lot of the heavy lifting of developing a web service by constructing the underlying functionality for you after you have specified basic meta data that defines the entities you want to manage.
  
  The down side of this option for me is that I need to learn yet another programming language, Ruby. While I’m getting around to it, it hasn’t been on the top of my priority list.


• Use S3 for Assets. This is simply a suggestion, however, I think it’s a good one. If all you need is to access assets from your iPhone app, keep a structured data document around, like an XML document in your S3 bucket. Let it map out where the assets are stored in your S3 buckets. Then all you have to do is maintain that one XML document and upload a new one each time your content needs to change. It will define for your app where the various assets are located along with any other information you might want to provide about that asset.

Conclusion

Networking code has gotten much simpler to implement in recent years, so accessing your resources in the cloud is a great solution to many application development problems. There are some great tools out there these days regardless of whether you are developing the client or the server. If you need to access the cloud, use the various libraries available to you and keep your designs simple. Doing so will yield great results.

If you have some suggestions for how to implement REST web services for iPhone apps, leave them in the comments section below. Remember that all comments are moderated, so if you don’t see your comment appear right away, just be patient. We’ll approve it as soon as possible. Until next time.

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

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

Failure checks

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

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

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

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

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

Move the file

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

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


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

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

Commit it to version control

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

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

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

Conclusion

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

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

Move_dSYM_To_Storage.sh.zip

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

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

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

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

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

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

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

We set up our CAShaperLayer using the following code:

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

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

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

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

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

Conclusion

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

Marching Ants Demo Project

• Create, configure, and add a UILabel as a subview of the contentView in the cell.

• Calculate the height in the UITableView delegate method, – (CGFloat)tableView:(UITableView*)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath;
• Calculate the frame for the UILabel in the UITableView delegate method, – (UITableViewCell*)tableView:(UITableView*)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath;

I am going to cover each of these rules in detail, but take a look at the output of the example project in the screenshot.

Add a UILabel to the Cell

In simpler table view based applications, you can simply set the text of the table view cell’s text label like this:

[[cell textLabel] setText:@"Text for the current cell here."];

Doing so might make you think that you can manipulate the UILabel that the cell uses, however, I’ve found my attempts to change the UILabel’s frame get ignored completely, so it is not a good candidate for use with our dynamic resizing code.

Instead what we need to do is programatically create a UILabel and add it to the cell’s content view. Do this in the call to -cellForRowAtIndexPath. Use something like the following code:

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

- (UITableViewCell *)tableView:(UITableView *)tv cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
  UITableViewCell *cell;
  UILabel *label = nil;
 
  cell = [tv dequeueReusableCellWithIdentifier:@"Cell"];
  if (cell == nil)
  {
    cell = [[[UITableViewCell alloc] initWithFrame:CGRectZero reuseIdentifier:@"Cell"] autorelease];
 
    label = [[UILabel alloc] initWithFrame:CGRectZero];
    [label setLineBreakMode:UILineBreakModeWordWrap];
    [label setMinimumFontSize:FONT_SIZE];
    [label setNumberOfLines:0];
    [label setFont:[UIFont systemFontOfSize:FONT_SIZE]];
    [label setTag:1];
 
    [[cell contentView] addSubview:label];
  }
}

This is not the completed code as you’ll notice that we have initialized the label only when the cell needs created for the first time, that is if (cell == nil) after a call to -dequeueReusableCellWithIdentifier. There are two points I want to address in relation to this. First, notice the label has a tag associated with it after a call to -setTag:1. This will be used in the case where the cell is not equal to nil after a call to -dequeueReusableCellWithIdentifier. In that case we will need to get a handle to the label by calling [cell viewWithTag:1] which will return the view that we associated with that tag. Second, notice that we have added our label to the cell’s content view with a call to [[cell contentView] addSubview:label]. This is done when the label is initialized and should only be done once. Adding it each time this method is called will add the label again to the subviews array. We will come back to this code to finish it in a minute, but first let’s take a look at how we can set the height for our cell now that our label has been added.

Calculate the Cell Height

In a complex cell, your calculations could get a bit challenging, however, you only need to worry with the items that will change in height. In our example, the only item you need to deal with is the label that we added. We calculate the height of the cell by determining the size of the text based on the length of the text and the font we intend to use. The NSString class provides a method called -sizeWithFont that enables us to obtain this size. The following code show how we implement our call to -heightForRowAtIndexPath:

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

- (CGFloat)tableView:(UITableView *)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath;
{
  NSString *text = [items objectAtIndex:[indexPath row]];
 
  CGSize constraint = CGSizeMake(CELL_CONTENT_WIDTH - (CELL_CONTENT_MARGIN * 2), 20000.0f);
 
  CGSize size = [text sizeWithFont:[UIFont systemFontOfSize:FONT_SIZE] constrainedToSize:constraint lineBreakMode:UILineBreakModeWordWrap];
 
  CGFloat height = MAX(size.height, 44.0f);
 
  return height + (CELL_CONTENT_MARGIN * 2);
}

You will notice that we have several constants we are using to calculate the size of our cell. These are defined as follows:

1
2
3

#define FONT_SIZE 14.0f
#define CELL_CONTENT_WIDTH 320.0f
#define CELL_CONTENT_MARGIN 10.0f

The constant CELL_CONTENT_WIDTH is the width of the entire cell. CELL_CONTENT_MARGIN is the margin we want to use all the way around the cell as the content inset, and of course FONT_SIZE is the size of the font we want to use for the label text.

The first place we use these is to create a constraint with the content width. Notice that CGSizeMake takes as its first parameter the total content width minus the margin times 2. This subtracts the margin from the left and the margin from the right from the total width to have the actual width of the label. The second parameter is just a maximum number we provide. The call to -sizeWithFont will set this to the actual height in the next line. This call to -sizeWithFont calculates the size according to the constant UILineBreakModeWordWrap which causes it to return the correct size for word wrap–which is why the width is important to get right. Next we set our height for the cell using a call to the MAX macro. This will ensure that our cell height will never be shorter than the default 44 pixels as MAX returns the larger of the two variables. Finally, we add our margin height back into the height for both top and bottom (hence x 2) and then return the result.

To help visualize how the margin is working, take a look at the following screenshot to see what each label looks like with a border around it. Turning this on with a call to [[label layer] setBorderWidth:2.0f] on the UILabel we added in the previous section makes it clear where the margins are.

Calculate the UILabel Frame and Set It

The same calculation we used to determine the height in the previous section is the code we use to set the frame for the UILabel we added in the beginning. To complete this tutorial we will finish out our implementation of -cellForRowAtIndexPath with the following code.

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

- (UITableViewCell *)tableView:(UITableView *)tv cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
  UITableViewCell *cell;
  UILabel *label = nil;
 
  cell = [tv dequeueReusableCellWithIdentifier:@"Cell"];
  if (cell == nil)
  {
    cell = [[[UITableViewCell alloc] initWithFrame:CGRectZero reuseIdentifier:@"Cell"] autorelease];
 
    label = [[UILabel alloc] initWithFrame:CGRectZero];
    [label setLineBreakMode:UILineBreakModeWordWrap];
    [label setMinimumFontSize:FONT_SIZE];
    [label setNumberOfLines:0];
    [label setFont:[UIFont systemFontOfSize:FONT_SIZE]];
    [label setTag:1];
 
    [[label layer] setBorderWidth:2.0f];
 
    [[cell contentView] addSubview:label];
 
  }
  NSString *text = [items objectAtIndex:[indexPath row]];
 
  CGSize constraint = CGSizeMake(CELL_CONTENT_WIDTH - (CELL_CONTENT_MARGIN * 2), 20000.0f);
 
  CGSize size = [text sizeWithFont:[UIFont systemFontOfSize:FONT_SIZE] constrainedToSize:constraint lineBreakMode:UILineBreakModeWordWrap];
 
  if (!label)
    label = (UILabel*)[cell viewWithTag:1];
 
  [label setText:text];
  [label setFrame:CGRectMake(CELL_CONTENT_MARGIN, CELL_CONTENT_MARGIN, CELL_CONTENT_WIDTH - (CELL_CONTENT_MARGIN * 2), MAX(size.height, 44.0f))];
 
  return cell;
}

Just remember that anything done within the if (cell == nil) block is initialization code and should only be done when the cell is first created. Anything done outside of the block will be used every time the -cellForRowAtIndexPath is called, which is any time the data gets reloaded or the view gets scrolled.

That being said, you will see that the only thing we do every time it gets called is setting the text of the current item and setting the label’s frame for the current item (lines 32 and 33). Notice that we got a handle to our UILabel by calling [cell viewWithTag:1] (lines 29 and 30) in the case where the label is nil in subsequent/non-initialization calls to this method. You will notice that our frame calculation code is exactly the same as what we used in the previous section to determine the row height.

Conclusion

Calculating dynamic cell heights is really not too hard. If you have a very complex cell, just remember that all you really need to calculate is the height based up a width that shouldn’t change and the size of the text of a certain font (unless of course you support both portrait and landscape modes–which makes things a little more challenging. I will, however, leave this as an exercise for the reader). If you find yourself wondering where your actual frame is displaying for a given view, just turn on the view border by calling [[view layer] setBorderWidth:2.0f]. This will help you see what is going on and give you the ability get to the bottom of your display problems quicker. Until next time.

DynamicHeights Demo Project

TabBarNavigator Demo Project

To get started, create a new project in Xcode. Select the Tab Bar Application template and click Choose….

Name the project, TabBarNavigator and click Save

TabBarNavigator Project

Change The Controller Type

1. In Xcode, expand the Resources group in the Groups and Files view and double-click MainWindow.xib to open the xib in Interface Builder

2. When Interface builder opens, change the xib View Mode to the tree view mode and expand your Tab Bar Controller item.

3. Make sure that the Tab View Controller object is selected. In the object inspector switch to the Attributes tab and change the Class for the First controller from View Controller to Navigation Controller.

4. You will notice back in the MainWindow.xib window that the view controller for First View is now a UINavigationController. Expand the UINavigationController item now.

5. Now select the View Controller that is a child of our new UINavigationController. Click on the Identity tab of the object inspector and change the Class to FirstViewController.

6. Click on the Navigation Item that is a child of the First View Controller and change the Title in the Attributes tab of the object inspector to “First”.

7. Save your changes in Interface Builder, switch back to Xcode and Build & Go. You should see something like the following in your First view tab.

8. Notice that there is a Toolbar visible at the bottom of the first view. If you would like to hide this, go back into Interface Builder and select the Navigation Controller In the object inspector, uncheck the Shows Toolbar checkbox.

Pushing a New Controller

Before we create a new view controller, let’s set up our FirstViewController to create an event that will trigger pushing the new controller. Since our FirstView was not created with a xib, let’s create one and then add actions and outlets to it.

1. In Xcode, right-click or ctrl-click the Resources group and select Add | New File…. In the ensuing dialog, select View XIB in the User Interface section of iPhone OS templates and click Next. Name the XIB FirstView and click Finish.

2. Double-click the new XIB to open it in Interface Builder and select the Identity tab after you have made sure that File’s Owner is selected. Change the Class field to FirstViewController.

3. Ctrl-click and drag a connection from the File’s Owner object to the View object in the main window for our XIB and select view in the ensuing pop up menu.

4. From the Object Library drag and drop a button onto the view. Double-click the button and give it the title “Push”. Save your changes in Interface Builder and switch back to Xcode.

5. Open the file FirstViewController.h and add an action so that the header looks like this:

   1 2 3 4 5 6 7 8 9

   #import <UIKit/UIKit.h>   @interface FirstViewController : UIViewController {   }   - (IBAction)push:(id)sender;   @end

6. Open the file FirstViewController.m and implement the action so that the code looks like this:

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

   #import "FirstViewController.h"   @implementation FirstViewController   - (IBAction)push:(id)sender {   }   - (void)dealloc { [super dealloc]; }   @end

   Note: You can safely delete all of the view controller template code which I have done in this example. Don’t worry. You won’t hurt anything.

We will come back to the push implementation after we have created our new view controller that we are going to push.

Create the New View Controller

We are now going to create the new view controller that will be displayed when we tap our “Push” button in the FirstViewController.

1. In Xcode, right-click or ctrl-click the Classes group and select Add | New File…. In the ensuing dialog, select UIViewController subclass in the Cocoa Touch Class category of the iPhone OS templates. Make sure With XIB for user interface is checked and click Next. Name the file NewViewController.m and click Finish.

2. For organization purposes, move the newly created NewViewController.xib file into the Resources group. Then double-click it to open it in Interface Builder.

3. In Interface Builder, drag a UILabel onto the view and give it the title “New View Controller”. Save the file and switch back to Xcode.

4. Open the file FirstViewController.m again and implement controller push code so that it looks like this:

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

   #import "FirstViewController.h" #import "NewViewController.h"   @implementation FirstViewController   - (IBAction)push:(id)sender { NewViewController *controller = [[NewViewController alloc] initWithNibName:@"NewViewController" bundle:nil]; [[self navigationController] pushViewController:controller animated:YES]; [controller release], controller = nil; }   - (void)dealloc { [super dealloc]; }   @end

   Don’t forget to #import “NewViewController.h”

5. To connect our button to the push action, double-click the FirstView.xib file in the Resources group to open it in Interface Builder.

6. Ctrl-click and drag a connection from the “Push” button in our view to the File’s Owner object and select push: in the ensuing pop up menu. Save your changes in Interface Builder. Switch back to Xcode and Build & Go.

7. Additionally, you can give your New View Controller a title by implementing -viewDidLoad. Just open your NewViewController.m file and uncomment the -viewDidLoad code making it look like the following:

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

   #import "NewViewController.h"   @implementation NewViewController   - (void)viewDidLoad { [self setTitle:@"New View"]; [super viewDidLoad]; }   - (void)dealloc { [super dealloc]; }   @end

And that’s pretty much all there is to it. There are a lot of steps here, but I think you’ll see that setting up your application to implement both a UITabBarController and a UINavigationController is pretty straight forward.

Conclusion

How best to organize your views in an iPhone application is a design process. Often applications will have a lot of data for your users to access and it will be up to you to find the best way to organize it. Being able to utilize both a tab bar and a navigation controller can really help in this process. Until next time.

TabBarNavigator Demo Project

Every now and again while doing development you stumble upon something that makes you go, hmmmm. Those are normally the moments at which you have to ask yourself, “is this a bug or a feature”. If it’s a bug, then you should file a radar with Apple, however, what if it’s a feature? You blog about it, of course!

I have done a bit less iPhone development than Marcus, so he was a little stumped while looking through some of my code where I created a view controller using a simple alloc/init. Most interestingly is that fact that the app works. It loads the correct nib and displays the view just fine without any trouble. Notice I said alloc/init and not alloc/initWithNibName. How can this possibly work? How did my controller “know” which view to use?

Well, the answer is pretty simple, but not immediately obvious. I could try to act like I meant to use an undocumented feature because I’m just that cool, but the fact of the matter is I was in band. Marching band, even. Band people aren’t cool. Though the color guard thought we were cool. But I digress. I just inadvertently added the alloc/init code without thinking and never looked back since the view loaded and displayed just fine. After renaming the nib/xib in the project and in doing so causing the view to fail to load properly we were able to determine that there must be some underlying feature of view controllers where it will automagically look for a view based upon its own name.

Say Huh?

Yep. That’s correct. If you create a view controller with the name MySpiffyViewController, for example, and instantiate it with alloc/init in your code, it will assume that the nib you want is actually called MySpiffyView. Spiffy eh? Some people may call this a bug, but the fact that it works this way shows that it was intentional. Now, I recommend that you steer clear of intentionally creating your view controllers this way as Apple may decide it’s a bug after all and change (fix?) it in a future release. It is however an interesting undocumented feature at the moment.

You Can Duplicate It

Here are the steps if you want to try this yourself. Of course, you can just download the example project below if you don’t want to go through the steps.

1. In Xcode, press Command+Shift+N to open the New Project templates and select View-based Application in the iPhone OS category and click Choose….


2. Name the project SpiffyView and click Save


3. The first thing we need to do is change our code in the app delegate (called SpiffyViewAppDelegate.m) to add a UINavigationController.

   1 2 3 4 5 6

   - (void)applicationDidFinishLaunching:(UIApplication *)application { UINavigationController *navController = [[UINavigationController alloc] initWithRootViewController:viewController]; [[navController navigationBar] setBarStyle:UIBarStyleBlackTranslucent]; [window addSubview:[navController view]]; [window makeKeyAndVisible]; }

   This will enable us to navigate to the new view we create next.


4. Press Command+N and select View XIB under the User Interfaces category. Click Next. Name the file MySpiffyView and click Finish


5. Press Command+N again and select UIViewController subclass under the Cocoa Touch Classes category. Click Next. Name the file MySpiffyViewController.m and click Finish.


6. Next we need to create an action in the view controller created by the project template called SpiffyViewViewController. Add the following code to the respective .m and .h files as follows.

   1 2 3 4 5 6 7 8 9 10

   // Add this to your SpiffyViewViewController.h - (IBAction)showSpiffyView:(id)sender;   // Add this to your SpiffyViewViewController.m. Make sure you #import "MySpiffyViewController.h" as well. - (IBAction)showSpiffyView:(id)sender; { id controller = [[MySpiffyViewController alloc] init]; [[self navigationController] pushViewController:controller animated:YES]; [controller release], controller = nil; }



7. Now we need to connect a button to the action. In your project under resources, double-click SpiffyViewViewController.xib to open it in Interface Builder.


8. In Interface Builder, drag a button onto the view and change its text to “Spiffy View”


9. Now, Control-Click and drag a connection from your button in the view, to the File’s Owner and select showSpiffyView: in the ensuing menu. Save the file in IB.


10. Now, back in Xcode, double click MySpiffyView.xib to open it in Inteface Builder.


11. Change the File’s Owner class to MySpiffyViewController in the Identity tab of the Inspector.


12. Drag a label onto the view. Double click it to edit it and change the text to “This is the super spiffy view.” Save the file in IB.


13. Everything should be hooked up now. Go back to Xcode and “Build & Go”. Your app should load in the simulator. When you see the “Spiffy View” button, click it and it should show your new view!!

Conclusion

So how is that working? The only answer is there must be some underlying code that the view controller is using to locate its nib. Remember, we never told our controller what nib to use. We simply called alloc/init and voila, it works!!

If you think I ought to register this as a bug with Apple, let me know your thoughts in the comments. Oh and one other thing. I may have been in band, but I married a smokin’ hot cheerleader. Take that all you cool people. ;-) Until next time.


Example Project SpiffyView.zip

The basic process flow goes like this. Clicking the ‘Capture’ button on the user interface calls an IBAction called -saveAnimation. It prompts the user to select an output file for the movie. When the user has selected the file, the animations are created and added to the layer. Next we create a timer that is going to call a function that will grab the current frame and place it into the QTMovie object using -addImage at a specified interval. We set our AppDelegate to also be the delegate for the animation group so that when the animation completes we get notified and can then write our QTMovie object data to disk.

Use An Interesting Animation

First you are going to need an animation that is worth recording. Of course any old animation will do, but we’ll keep it interesting by adding multiple animations to a single layer. I have created four different keyframe animations that we will add to an animation group. The keypaths are “backgroundColor”, “borderWidth”, “position”, and “bounds”. Check the sample code to see how these animations are constructed.

We set the duration for all of the animations to five seconds. We also need to make sure that we set the duration for the group itself, otherwise it will override the five second duration we set for the animations themselves and run in the default 0.25 seconds. The code below shows how the animations are added to the layer.

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

- (void)loadAnimations;
{
  CAAnimationGroup *group = [CAAnimationGroup animation];
 
  [group setAnimations:[NSArray arrayWithObjects:[self backgroundColorAnimation],
                          [self borderWidthAnimation],
                          [self positionAnimation],
                          [self boundsAnimation], nil]];
 
  [group setValue:@"mainGroup" forKey:@"name"];
  [group setDuration:5.0];
  [group setAutoreverses:YES];
  [group setDelegate:self];
 
  [layer addAnimation:group forKey:@"group"];  
}

Notice that we have used KVC here to set a name for the animation group. We will use this as a tag later to make sure the animation that triggers our -animationDidStop:finished animation delegate is the correct one. More on that later.

Get Our Movie Ready

Prior to loading the animations, we prompt the user to select a file to write the movie file to. After loading the animations, we start our timer.

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

- (IBAction)saveAnimation:(id)sender;
{
  NSSavePanel *savePanel;
 
  savePanel = [NSSavePanel savePanel];
  [savePanel setExtensionHidden:YES];
  [savePanel setCanSelectHiddenExtension:NO];
  [savePanel setTreatsFilePackagesAsDirectories:NO];
 
  if( [savePanel runModal] == NSOKButton )
  {
    movie = [[QTMovie alloc] initToWritableFile:[savePanel filename] error:nil];    
  }
 
  [self loadAnimations];
 
  timer = [NSTimer scheduledTimerWithTimeInterval:1.0/(NSTimeInterval)10.0
                                           target:self
                                         selector:@selector(updateTime:)
                                         userInfo:NULL
                                          repeats:YES];    
 
}

Our -updateTime selector will get called every 1/10th of a second and will grab the current frame to save it to the QTMoive object. Here is the -updateTime code.

1
2
3
4
5
6
7
8
9
10
11

- (void)updateTime:(NSTimer*)theTimer;
{
  NSBitmapImageRep *image = [self getCurrentFrame];
 
  QTTime time = QTMakeTime(1, 10);
  NSDictionary *attrs = [NSDictionary dictionaryWithObject:@"png " forKey:QTAddImageCodecType];
  NSImage *img = [[NSImage alloc] initWithData:[image TIFFRepresentation]];
  [movie addImage:img forDuration:time withAttributes:attrs];
 
  [image release];
}

Obtaining the Current Frame

The code to obtain the current frame is somewhat lengthy, but the concepts are pretty simple. We need to create a graphics context that we can draw into and then draw into it using the presentationLayer of the contenView’s root layer. If you’re not familiar, the presentationLayer provides the current state of the animated fields while “in-flight”.

Core Animation doesn’t provide any callbacks for when a frame is ready to be displayed which is why we are using a timer. This means that we may be capturing more frames than we need to, so getting the right frame rate takes a bit of trial and error, which I have to confess I wasn’t able to get nailed down completely. I’m still working on it and will update here when I get that part figured out. Meanwhile, here is the code for -getCurrentFrame

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

- (NSBitmapImageRep*)getCurrentFrame;
{
  CGContextRef    context = NULL;
  CGColorSpaceRef colorSpace;
  int bitmapByteCount;
  int bitmapBytesPerRow;
 
  int pixelsHigh = (int)[[[window contentView] layer] bounds].size.height;
  int pixelsWide = (int)[[[window contentView] layer] bounds].size.width;
 
  bitmapBytesPerRow   = (pixelsWide * 4);
  bitmapByteCount     = (bitmapBytesPerRow * pixelsHigh);
 
  colorSpace = CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);
 
  context = CGBitmapContextCreate (NULL,
                                   pixelsWide,
                                   pixelsHigh,
                                   8,
                                   bitmapBytesPerRow,
                                   colorSpace,
                                   kCGImageAlphaPremultipliedLast);
  if (context== NULL)
  {
    NSLog(@"Failed to create context.");
    return nil;
  }
 
  CGColorSpaceRelease( colorSpace );
 
  [[[[window contentView] layer] presentationLayer] renderInContext:context];
 
  CGImageRef img = CGBitmapContextCreateImage(context);
  NSBitmapImageRep *bitmap = [[NSBitmapImageRep alloc] initWithCGImage:img];
  CFRelease(img);
 
  return bitmap;
 
}

Notice that we are calling -renderInContext on the presentationLayer of the window’s contentView’s root layer. If we were only to render our animated layer, we wouldn’t be able to see the animation as it will only render the containing rectangle of the animating layer.

Finishing Up

Finally we need to write the movie data out to disk. The QTMovie object provides a single call to do so, but we need a way to know when the animation has finished so we can make this call. When we created our animation group, we set its delegate to our AppDelegate which will cause the delegate method -animationDidStop:finished to get called. Remember that setting the delegate for each of the individual animations gets ignored when you are using an animation group. We implement the -animationDidStop:finished delegate as shown below.

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

- (void)animationDidStop:(CAAnimation *)theAnimation finished:(BOOL)flag;
{
  NSLog(@"Animation stopped: %@", theAnimation);
 
  id name = [theAnimation valueForKey:@"name"];
  if( name )
    if( [name isEqualToString:@"mainGroup"] )
    {
      [movie updateMovieFile];
      [timer invalidate];
    }
}

The first thing we do is check the animation tag we set when creating the animation group. This really isn’t necessary in this code example since there is only one animation that is going to use it, but this code shows you how to differentiate if you were to use multiple animations or groups and wanted to know when each of them finished animating.

The call to -updateMovieFile writes the data to disk and we now have a QuickTime movie that will play our animation. Open the resulting file in QuickTime or just invoke QuickLook to see the result.

Conclusion

Maybe you can think of a use for this kind of thing. I haven’t yet–other than for writing a blog post of course. Shoot me your thoughts and comments in the comments section. Until next time.

CA Animation Capture Demo Project

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

1
2
3
4
5
6

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

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

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

I like this approach for a few reasons:

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

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

Logging Sample Application

Add the following to iTunesFilter_AppDelegate.h:

IBOutlet NSSearchField *searchField;
IBOutlet NSArrayController *songArrayController;

and

- (IBAction)filterSongs:(id)sender;

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

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

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

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

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

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

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

iTunesFilter Sample Application

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

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

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

1
2
3
4
5

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

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

All Or None

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

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

FirstViewController

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

SecondView Controller

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

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

Conclusion

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