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.

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.

Download the source code for the Favorite Things project.

A Few of My Favorite Things

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

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

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

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

Display Order Attribute

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

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

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

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

Favorites Change

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

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

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

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

Further Considerations

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

Finishing Up

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

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

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

1
2
3
4
5
6
7
8

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

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

1
2
3
4

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

Conclusion

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

Download the source code for the Favorite Things project.

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

The File

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

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

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

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

#ifdef DEBUG

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

#define DLog(...)

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

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

#define ALog(...)

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

1

NSAssert(NO, @"It failed");

or if you want to see the variables:

1

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

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

1

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

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

NS_BLOCK_ASSERTIONS

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

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

#define ZAssert(condition, ...)

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

1
2
3
4
5
6

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

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

With ZAssert it gets a lot cleaner:

1
2

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

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

Wrap Up

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

Acknowledgements

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

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

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

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

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

NSImage vs UIImage

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

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

Unfortunately that fails in the portability department.

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

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

But that is hard right?

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

MyEntityWithAnImage.h

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

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

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

MyEntityWithAnImage.m

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

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

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

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

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

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

Wrap Up

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

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

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

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

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

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

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

Failure checks

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

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

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

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

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

Move the file

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

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


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

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

Commit it to version control

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

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

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

Conclusion

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

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

Move_dSYM_To_Storage.sh.zip

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

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

1
2
3
4
5

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

That’s it!

Docs for LSMinimumSystemVersionByArchitecture

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

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

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

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

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

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

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

We set up our CAShaperLayer using the following code:

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

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

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

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

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

Conclusion

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

Marching Ants Demo Project

1

UpdateSystemActivity(OverallAct);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6

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

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

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

I like this approach for a few reasons:

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

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

Logging Sample Application

Add the following to iTunesFilter_AppDelegate.h:

IBOutlet NSSearchField *searchField;
IBOutlet NSArrayController *songArrayController;

and

- (IBAction)filterSongs:(id)sender;

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

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

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

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

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

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

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

iTunesFilter Sample Application

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

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

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

1
2
3
4
5

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

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

All Or None

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

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

FirstViewController

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

SecondView Controller

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

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

Conclusion

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

Differentiating Keypath From Key

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

1
2
3
4
5
6
7
8
9
10
11

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

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

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

Adding The Animation, Again

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

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

1
2
3
4

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

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

Changing Direction While In Flight

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

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

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

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

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

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

Conclusion

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

Follow Me Demo Project

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

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

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

Mad props to Marcus. Congratulations!

The Slider Value

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

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

Layer Rotate

Rotation Animation

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

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

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

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

1
2
3
4
5
6

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

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

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

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

Retaining The Rotation Position

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

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

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

Conclusion

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

Layer Rotate Demo Project

1
2
3
4
5
6
7

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

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

Two Heads Better Than One

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

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

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

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

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

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

Your Own Composition

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

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

VideoCube QC Editor

Quartz Composer Layer

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

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

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

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

Conclusion

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

Quartz Composition Layer Demo Project

Why are these topics linked?

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

Scriptable plug-ins

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

Publishing a Formal Protocol Plug-ins Interface

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

Publishing an Informal Protocol Plug-ins Interface

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

Publishing a Base Class Plug-ins Interface

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

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

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

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

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

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

Building the plug-ins

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

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

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

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

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

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

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

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

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

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

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

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

The flow of loading bundles dynamically is as follows:

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

And the code for this is as follows:

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

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

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

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

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

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

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

Conclusion

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

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

Example Project