Registering Custom Fonts With iOS

Last week, I explained how to load a font directly from a file using Quartz data providers. While this is a perfectly acceptable way to load a custom font, it is no longer necessary. In iOS 3.2, a new key was added to Info.plist called UIAppFonts (special thanks to @hanspinckaers and Ilari Sani for reminding me it exists). This little gem takes an array of font file names, and it makes the named fonts available through the normal font loading mechanism. This means you can finally use Comic Sans instead of Marker Felt in your apps.

Using UIAppFonts is very simple. First, you need to make sure your font files are in your app bundle. Then, add the UIAppFonts key to your Info.plist, and add an entry in the array for each font file you want available to your app.

Provided your font is one of the supported font types, it should now be available to load like any system font. The following line of code uses Core Text to load our font:

CTFontRef canHazComicSans =
  CTFontCreateWithName(CFSTR("ComicSans"), 24.f, NULL);

Next Week: Configuring Font Attributes

Core Text fonts are very configurable. The power lies in CTFontDescriptor, and it will be our topic next week. Here’s a little code teaser to whet your appetite:

NSDictionary *fontAttributes =
  [NSDictionary dictionaryWithObjectsAndKeys:
    @"Courier", (NSString *)kCTFontFamilyNameAttribute,
    @"Bold", (NSString *)kCTFontStyleNameAttribute,
    [NSNumber numberWithFloat:16.f], (NSString *)kCTFontSizeAttribute,
    nil];
CTFontDescriptorRef descriptor =
  CTFontDescriptorCreateWithAttributes((CFDictionaryRef)attributes);
CTFontRef font = CTFontCreateWithFontDescriptor(descriptor, 0, NULL);
CFRelease(descriptor);

See you next week!

P.S. – If you actually want to see me in person next week, I’ll be giving a half day workshop on Core Animation as well as a shorter talk about drawing with Quartz in UIKit at the iPhone/iPad DevCon in San Diego. Hopefully I’ll see you there!

Displaying Custom Fonts

Using CATextLayer to display a custom font is fairly simple. There are two things we must do to make it work:

• Load the font into memory (most likely from our app bundle).
• Hand the font to our CATextLayer for drawing.

Once the font has been passed to our CATextLayer instance, we can set the string of the layer and treat it like any other Core Animation layer. Let’s see how this looks in code.

Load the Font into Memory

Because CATextLayer uses Core Text internally, we’ll need to touch a little of Core Text to render our custom font. Like Quartz, Core Text is a Core Foundation API, and it is entirely C based. If you’ve done any custom drawing with Quartz, the Core Text API will look familiar. If this is your first foray into a Core Foundation framework, don’t worry, CATextLayer abstracts most of Core Text away. You still might want to take a look at the Apple Core Foundation docs if this part is way over your head.

CATextLayer expects a CTFontRef (CT is the prefix for all Core Text types and functions) for its font attribute. This is where we have to use Core Text directly.

We actually go about this in a bit of a roundabout way. Core Text does not know how to load a font from a font file. That’s the domain of Qaurtz. So we have to load the font file with Quartz and convert the CGFontRef to a CTFontRef. Thankfully, this conversion is just a single function call.

- (CTFontRef)newCustomFontWithName:(NSString *)fontName
                            ofType:(NSString *)type
                        attributes:(NSDictionary *)attributes
{
  NSString *fontPath = [[NSBundle mainBundle] pathForResource:fontName ofType:type];

  NSData *data = [[NSData alloc] initWithContentsOfFile:fontPath];
  CGDataProviderRef fontProvider = CGDataProviderCreateWithCFData((CFDataRef)data);
  [data release];

  CGFontRef cgFont = CGFontCreateWithDataProvider(fontProvider);
  CGDataProviderRelease(fontProvider);

  CTFontDescriptorRef fontDescriptor = CTFontDescriptorCreateWithAttributes((CFDictionaryRef)attributes);
  CTFontRef font = CTFontCreateWithGraphicsFont(cgFont, 0, NULL, fontDescriptor);
  CFRelease(fontDescriptor);
  CGFontRelease(cgFont);
  return font;
}

As you can see, we use a CGDataProvider to load the font from the app bundle and create a CGFontRef with the data provider.

Next, we create at CTFontDescriptorRef. CTFont is very configurable, and the CTFontDescriptor holds all of that configuration information. We’ll get to it in a later post. You can ignore the CTFontDescriptor for now.

The last thing we do in this method is create the CTFontRef using our CGFontRef and the CTFontDescriptorRef. Now, our font is loaded and ready to be used.

Configure the CATextLayer

CATextLayer could not be easier to configure. Like other CALayer objects, the CATextLayer exposes a set of attributes that we can set to configure the look of our text. Since we loaded the font earlier, we can just set the font attribute of CATextLayer, and the layer handles the rest.

normalTextLayer_ = [[CATextLayer alloc] init];
normalTextLayer_.font = font;
normalTextLayer_.string = @"This is just a plain old CATextLayer";
normalTextLayer_.wrapped = YES;
normalTextLayer_.foregroundColor = [[UIColor purpleColor] CGColor];
normalTextLayer_.fontSize = 20.f;
normalTextLayer_.alignmentMode = kCAAlignmentCenter;
normalTextLayer_.frame = CGRectMake(0.f, 10.f, 320.f, 32.f);

As you can see, there are a bunch of configuration options for CATextLayer. You can see them all in the class reference doc. Once we’ve finished setting up our layer, we add it to the layer tree, and Core Animation will render it. The final product looks something like this:

Now, Unleash the Designers

Thanks to the updates in iOS 4, developers are no longer stuck with the fonts built into iOS. Good typography can really elevate the look of an app, and I encourage you to experiment with quality fonts. Let you designers run wild. They’ll love you for it.

The Problem

Early in development, the data model model changes often, and errors are inevitable. Forget to make a new attribute optional, and the code blows up while saving the context. Because I move pretty fast and change things often, this kind of stuff happens to me all the time. Core Data provides me this error message quite often:

Domain=NSCocoaErrorDomain Code=1560 UserInfo=0x14f5480 "Operation could not be completed. (Cocoa error 1560.)"

For the developer inexperienced with Core Data, this is a very disheartening message. It does not give us any indication of what went wrong or how we should attempt to fix the problem.

The Solution

It turns out that, if there is more than one error, Core Data puts an array of NSError objects in the userInfo dictionary with the key NSDetailedErrorsKey. This is not obvious, and it drove me crazy for a while until I turned to Stack Overflow where someone else had already asked my question. There, someone named Charles provided this solution with code to get at the "real" error. Overjoyed, I turned the code into a macro, and I use it exclusively to save a context during development. Here is the macro:

#define FT_SAVE_MOC(_ft_moc) \
do { \
  NSError* _ft_save_error; \
  if(![_ft_moc save:&_ft_save_error]) { \
    NSLog(@"Failed to save to data store: %@", [_ft_save_error localizedDescription]); \
    NSArray* _ft_detailedErrors = [[_ft_save_error userInfo] objectForKey:NSDetailedErrorsKey]; \
    if(_ft_detailedErrors != nil && [_ft_detailedErrors count] > 0) { \
      for(NSError* _ft_detailedError in _ft_detailedErrors) { \
        NSLog(@"DetailedError: %@", [_ft_detailedError userInfo]); \
      } \
    } \
    else { \
      NSLog(@"%@", [_ft_save_error userInfo]); \
    } \
  } \
} while(0);

Now, whenever I need to save the context, I can do it safely and comfortably like so:

FT_SAVE_MOC([self managedObjectContext])

This macro only prints the error messages, but all I want during development is error messages in the console. This code can easily be moved to a function or method to do more robust error handling in a production scenario, but that would fill an entire post on its own.

The Problem

Core Data allows you to choose from multiple backend storage methods, and, other than having to choose a type, the data store is completely transparent. The recommended store on the iPhone is sqlite, and not only is it fast, but the schema generated by Core Data is fairly readable. Being able to poke around in the sqlite file was an immeasurable help while I was learning Core Data. The biggest problem is finding the sqlite database file. Every time you build and run your app in the simulator, the application directory is renamed with a new GUID which makes it really hard to find:

Can you find your app?

The Solution

Thankfully, OS X has the full compliment of unix command line tools. Wrap the proper commands in a Makefile, and you have some instant command line Core Data database management tools. Unix to the rescue! Here are the four make targets that I use the most:

SQLITE_DB_FILE=AppData.sqlite
SIMULATOR_HOME=$(HOME)/Library/Application\ Support/iPhone\ Simulator

dbshell:
      find $(SIMULATOR_HOME) -name "$(SQLITE_DB_FILE)" -exec sqlite3 {} ';'

killdb:
      find $(SIMULATOR_HOME) -name "$(SQLITE_DB_FILE)" -exec rm {} ';'

dbschema:
      find $(SIMULATOR_HOME) -name "$(SQLITE_DB_FILE)" -exec sqlite3 {} .schema ';'

dbdump:
      find $(SIMULATOR_HOME) -name "$(SQLITE_DB_FILE)" -exec sqlite3 {} .dump ';'

The target names should make their use self explanatory, but I’ll summarize them:

dbshell

Open up the sqlite command line shell with the Core Data database selected.

killdb

Delete the database file. This is useful if you’re making big changes to the schema and you would rather delete the whole database and start over rather than migrating the schema.

dbschema

Dumps the CREATE statements required to recreate the schema. This is useful to see how Core Data persists your object graph.

dbdump

Dumps the schema as CREATE statements and all of the data as INSERT statements.

There is nothing magical or difficult about these, but I have found them to be very useful while developing my data model.