For anyone who’s developed exclusively with UIViews on iOS may take the title of this post a bit oddly. “WHAT?!” they might say, “Are you insane? Core Graphics is not only a C-only API, but has confusing function names, and needs way more code to do the same thing I can do in less code in UIView”.  Yes, they might be right, but there’s a reason why Core Graphics exists. It’s FAST!

But using Core Graphics doesn’t mean that your code has to be confusing, or that you have to compromise flexibility for performance. You can have your cake and eat it too (aka you can have high-performing code that is easy to read). Read on to see what I mean.

Baby steps in using drawRect:

The drawRect: method is your entry point to drawing in Core Graphics, and is (for the most part) the only place where drawing operations can be performed. This is the biggest problem newbies have when getting started with low-level drawing on iOS because they’re used to being able to add subViews or subLayers arbitrarily in whatever method they happen to be in.

drawRect: is called by the underlying graphics subsystem in its main frame rendering loop.  When it’s time to draw the next frame, iOS digs through all the views on the screen and checks to see if its content needs to be updated. If it does, then your drawRect: method is called with the appropriate rect that needs to be updated.  It’s as simple as that.  You get asked to draw your content when, and only when, it needs something from you.

Finding your context

All drawing operations in Core Graphics utilize a context pointer to keep track of what region your drawing operations will be made to. This is a standard thing you’ll find in C APIs because without an Object-Oriented “self” property easily available, you have to provide some means of providing context.

- (void)drawRect:(CGRect)rect {
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    // Do something with your context
}

From that point on you can use the “ctx” variable for all subsequent Core Graphics calls.

Saving state

If you want to draw anything on the screen, even if it’s something as simple as a single line, you’ll need to use several function calls to do so. This is because separate calls are used to set attributes such as the line colour, the line width, any end-cap settings you may want for the corners of your line, and then the actual path that your line will follow.  Core Graphics keeps track of all these different attributes by updating its internal state.

Think of the drawing state as a pen: you change the tip, you change the colour, and then you can draw many separate lines with the same pen.  But if you forget to change your pen back, you can mess future drawing calls up if you don’t clean up after yourself.

To work around problems like this it’s best to use the CGContextSaveGState and CGContextRestoreGState functions.  Think of it as saving a bookmark or a checkpoint of your current graphics state.  You can then change any drawing attributes you like, you can draw or fill or stroke any path, and when you’re done you reset the graphics state back to what it was before.

There is one important catch however: the number of times you call Save and Restore must match perfectly, because otherwise you may screw up the drawing state for whomever is calling your class. This is important because otherwise some really weird garbage may end up getting drawn to your screen.  To get around this, I use a very simple technique that I’ll show in the code sample below.

- (void)drawRect:(CGRect)rect {
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    CGContextSaveGState(ctx);
    {
        // Draw whatever you like
    }
    CGContextRestoreGState(ctx);
}

By including a new set of brackets in your code, you give yourself a visual indentation of code that is covered by a set of save and restore calls.

Simple drawing using UIView classes

There are some fairly simple operations that some people want to do that are made easy by a few simple helper methods provided in a few UIView subclasses. For example, assume you’re building the next greatest Twitter application and you want to squeeze as much performance out of your feed items as you possibly can.  Obviously rendering text, images, gradients, borders and shadows are fairly expensive operations if you want to handle scrolling through thousands of feed posts at 60fps.

Fortunately you don’t have to replace your UIView classes with hundreds of lines of Core Graphics calls. Many of the most common classes like UIImage, UIBezierPath and so on, all provide convenience methods for drawing their content within drawRect: using Core Graphics directly.

Update: The original post had a few bugs in it, mostly due to writing this post exclusively from memory during the Christmas holidays. As a result of some very helpful comments on this post however, I’ve had to make some changes. I apologize for the bugs in the first version.

UIImage drawing

We can use UIImage objects to directly draw to a Core Graphics context. Using raw API calls makes for very verbose code, since you’d have to create a CGImage object, a color-space object, and so forth. Instead, drawing an image can be as easy as the following.

- (void)drawRect:(CGRect)rect {
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    UIImage *img = [UIImage imageNamed:@"MyImage.png"];
    [img drawInRect:rect];
}

With this technique you have many more options, such as blending and alpha arguments. There are other methods that let you draw an image at a particular point, drawing a pattern, and so forth.

UIBezierPath drawing

Often times you might want to show rounded corners on some view, but you only want certain corners to be rounded. For example lets assume you want to show a container view with only the top two corners rounded. The most straight-forward strategy is to drop into Core Graphics to render. While it’s possible to compose a path using low-level APIs alone, it’s quite simple to do the following.

- (void)drawRect:(CGRect)rect {
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    CGContextSetStrokeColorWithColor(ctx, [UIColor blackColor].CGColor);
    CGContextSetLineWidth(ctx, 3);
    UIBezierPath *path;
    path = [UIBezierPath bezierPathWithRoundedRect:rect
                                 byRoundingCorners:(UIRectCornerTopLeft |
                                                    UIRectCornerTopRight)
                                       cornerRadii:10.0];
    [path stroke];
}

Responding to user input

Core Graphics tries to be as efficient as possible, and so it takes some shortcuts on your behalf. For the most part these are exactly what you want and would expect, and come as a pleasant surprise when you come from other platforms. But there are times that it can get in your way, so knowing in advance what those optimizations are and how to control them helps. And knowing is half the battle…

Knowing when your view “Needs Display”

Your drawRect: method will only be invoked when UIKit feels your content has become stale and needs to be redrawn. For the most part this typically means your drawRect: method will be called when the view is added to a superview. Since drawRect is called when the frame is drawn, calling it explicitly won’t work as you’d expect, so if some user interaction requires you to redraw your content, there’s a simple solution for that.

All UIView objects have a method called “setNeedsDisplay“. Invoking this will toggle a flag inside your object indicating that your view needs to be redrawn upon the next frame. This has several advantages, including the fact that it makes your code very quick; this is because no matter how many times you call it within the same runloop, your frame will still only be redrawn once on the next frame. Therefore you don’t have to worry about over-invoking it, ensuring that you can keep your content fresh from wherever your UI logic determine content needs to change.

- (id)initWithFrame:(CGRect)frame {
    self = [super initWithFrame:frame];
    if (self) {
        CGRect labelRect = CGRectMake(32, CGRectGetHeight(frame) - 32, CGRectGetWidth(frame), 32);
        self.likeLabel = [[[UILabel alloc] initWithFrame:labelRect] autorelease];
        self.likeLabel.font = [UIFont systemFontWithSize:12.0];
        self.likeLabel.autoresizingMask = (UIViewAutoresizingFlexibleTopMargin |
                                           UIViewAutoresizingFlexibleRightMargin);
        [self addSubview:self.likeLabel];
        
        self.likeIcon = [UIImage imageNamed:@"likeIcon.png"];
        self.unlikedIcon = [UIImage imageNamed:@"unlikedIcon.png"];
    }
}
 
- (void)dealloc {
    self.likeLabel = nil;
    self.likeIcon = nil;
    self.unlikedIcon = nil;
    [super dealloc];
}
 
- (IBAction)likeClicked:(id)sender {
    // Update the label's text
    self.isLiked = !self.isLiked;
    self.likeLabel.text = (self.isLiked) ? @"Liked by you" : @"";
 
    [self setNeedsDisplay];
}
 
- (void)drawRect:(CGRect)rect {
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    
    // Determine the coordinates we want our content drawn at
    CGPoint iconPoint = CGPointMake(floorf(self.likeIcon.size.width / 2),
                                    CGRectGetMidY(self.textLabel.frame));
    
    // Draw the content
    UIImage *image = (self.isLiked) ? self.likedIcon : self.unlikedIcon;
    [image drawAtPoint:iconPoint];
}

In the code example above you’ll notice that we’re creating the UIImage object in initWithFrame:, and are destroying it in dealloc, so that we don’t have to allocate objects within the drawRect: method. It’s important to keep that method as quick as possible so you don’t negatively impact your screen’s framerate.

Responding to frame size changes

When your view changes its size, either when explicitly set or when a superview autoresizes its subviews, your content will be invalidated in some way. But rather than calling expensive drawRect: methods all the time when this happens, UIView objects have a contentMode property that lets you give UIKit a hint about what you want it to do in this situation.

This property is an typedef enum named UIViewContentMode and has a bunch of different options that you should check out. The default value is UIViewContentModeScaleToFill which means if your frame’s size changes, UIKit will simply take the last-rendered result your drawRect: method created and will scale it up or down to fill the available space.

The simplest way to get your content to redraw is to set your view’s contentMode to UIViewContentModeRedraw, but in many cases this may be overkill.

For example, lets assume your drawRect: method draws a border and some comments along the bottom of your frame, as the “Like” example does in the previous section. If your frame changes its height it would be wasteful to perform a full redrawing operation when most of the content hasn’t changed. So if you set the contentMode to UIViewContentModeBottomLeft UIKit will align the content in the bottom-left corner of the view, cropping the rest of the content as it does so.

Avoid drawing across pixel boundaries

When you position elements on the screen (not just with Core Graphics, but in UIKit in general) you need to make sure that your views exist at integer pixel coordinates. iOS’ drawing coordinate system works in points, not absolute pixels, which means it’s possible to tell UIKit or Core Graphics to draw content at a fractional-pixel. Since this is impossible, the device attempts to anti-alias your content so that it blurs between several pixels. This is almost never what you want, so when calculating positions (especially when dividing one value by another) it’s important to use the floorf or ceilf functions to round the values down or up to the nearest integer.

This is more obvious when drawing or stroking lines or paths on the screen. Lets take the following example where we draw a single line along the bottom of the view. For this example however we’ll use the low-level drawing routines to compose a path, instead of using a UIBezierPath object.

- (void)drawRect:(CGRect)rect {
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    CGContextSetStrokeColorWithColor(ctx, [UIColor blackColor].CGColor);
    CGContextSetLineWidth(ctx, 1);
    
    CGContextBeginPath(ctx);
    CGContextMoveToPoint(ctx, 0, CGRectGetMaxY(rect));
    CGContextAddLineToPoint(ctx, CGRectGetMaxX(rect), CGRectGetMaxY(rect));
    CGContextStrokePath(ctx);
}

This code seems pretty straightforward; move the drawing “pen” position to the bottom-left corner, add a line to the bottom-right corner, and stroke the resulting path with the line width and line color previously defined.

The “gotcha” here is that when you create a point at (0, 0), that represents the logical upper-left corner of the screen. However the pixel in the top-left corner occupies the space defined by the frame (0, 0, 1, 1) (e.g. a 1-point square starting at (0, 0)). When you draw a line it is centred on whatever coordinates you give it. Therefore in the code example above, your code is asking Core Graphics to draw a line that has 0.5 in one pixel, and 0.5 in another pixel.

To get around this you should offset your drawing frame so that you draw 0.5 points offset. Here’s an updated version of that code which draws a solid unblurred line:

- (void)drawRect:(CGRect)rect {
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    CGContextSetStrokeColorWithColor(ctx, [UIColor blackColor].CGColor);
    CGContextSetLineWidth(ctx, 1);
    
    CGContextBeginPath(ctx);
    CGContextMoveToPoint(ctx, 0, CGRectGetMaxY(rect)) - 0.5;
    CGContextAddLineToPoint(ctx, CGRectGetMaxX(rect), CGRectGetMaxY(rect));
    CGContextStrokePath(ctx);
}

Drawing with colour the easy way

Core Graphics has evolved over time, with new and improved APIs. This means that for many drawing operations there might be several different function calls that will give you the same result. This is especially true when dealing with colour.

For example, if you want to set the stroke (aka “line”) colour in Core Graphics, there are four separate function calls that will achieve the same result. Your impulse might be to pick the first result that comes up, but that means more work for yourself. The standard CGContextSetStrokeColor function call takes an array of CGFloats indicating the different colour values you want to draw with.

However there’s a much easier way. CGContextSetStrokeColorWithColor is a slightly more verbose function name, but allows you to supply a CGColorRef value to describe a colour. And as a convenience, the UIColor class provides a helper property called CGColor that returns a pre-calculated colour reference, which automatically releases its memory when the UIColor object goes away. This means you don’t need to manually malloc or release your colour references, and results in much less code.

You can see some of the code examples up above where I’ve already used this function and property. Whenever you see a function that has a “ColorWithColor” option, it uses this pattern.

Use the right tool for the job

Perhaps the best advice I can give is to use the right tool for the job.  For example, if you need to visually style some interface element, you shouldn’t add unnecessary subviews just to draw things like borders, rounded corners, tiled patterns, and so on.  Additionally there are cases where having a large number of subviews (such as in UITableViewCells) is inefficient and rendering simple elements like icons, text, or borders is better suited to Core Graphics.

iOS and UIKit is really a different environment than HTML, and you can’t treat device layout and rendering the same way.

And finally, make sure you practice, and don’t be afraid of trying out Core Graphics.  Start simple with things like borders, rendering images and text, or programmatically rendering effects that would otherwise be slow using Core Animation or image-based textures.

As developers we spend most of our lives dealing with broken and barely-functional software: our own software. We do our best to make the applications we develop somewhat less broken and try to add features to make it functional. And once we finally get our software working bug-free and functioning stably, what do we do? Do we bask in the joy of a stable app and spend countless hours enjoying that moment? No, we move on to v1.1 or v2.0, adding more features and consequently more bugs.  It’s kind of sad if you think about it.

Since much of our lives are spent with applications in various states of brokenness, understanding how to debug our software and catch those exceptions that arise is vital to getting our applications to a stable state so we can release, consequently moving on to create a whole new set of bugs that need to be fixed.

Here are some basic tips and tricks to make your life easier dealing with Xcode 4, and tracking down those places where your code runs off into the bushes.

Using breakpoints

Most people are familiar with the concept of breakpoints, but if you’re not I’ll reproduce it here. Click the line number next to a line of code, and a breakpoint icon will show up, causing your application to pause when it gets there.  From that point you can inspect the values of variables within your scope, you can single-step from one line of code to the next, etc. It’s something most web developers wish they had.

Editing breakpoints

You can also edit breakpoints.  Right-click on a particular breakpoint and you can click the “Edit Breakpoint” menu. You also have a few other options available to you, including the ability to disable or delete a breakpoint. However there’s easier ways to do the same things; you can either drag the breakpoint off of the line-number margin, just like removing an icon from your dock, or you can click the line to toggle its “disabled” state.

Conditional breakpoints

When you select “Edit Breakpoint” you are presented with a context menu showing additional options for that breakpoint. You can set a condition that will cause your breakpoint to trigger only when that condition is met, you can cause it to ignore the breakpoint until a certain number of times, and can even trigger complex actions to be performed automatically when that breakpoint is hit.

For example, you can log a line to the console, you can play a sound, you can capture an OpenGL frame for later comparison, and can even invoke a shell script or AppleScript.

Managing your breakpoints

Once you have a lot of breakpoints in your code it can often be difficult to manage it. So in the Xcode 4 navigator pane you can click on the “Breakpoints” tab (or you can press ⌘-6) to see a full list of your current breakpoints.

You can enable or disable the breakpoints right from there, you can delete them, etc. But as you can see, at the bottom of the navigator, there’s a toolbar.  From there you can create new breakpoints, filter breakpoints, and other fun tasks.

The most important feature here however is the ability to add explicit breakpoints without having to have an associated line number.  Clicking the “+” button brings up a menu with two options: “Add Exception Breakpoint” and “Add Symbolic Breakpoint”.

Exception breakpoint

This is perhaps one of the most powerful breakpoints you can have in your debugging arsenal, and is something you’ll almost always want to add to your project. In a nutshell it will cause your program to pause at a line that triggers an exception, rather than simply crashing and burning with an EXC_BAD_ACCESS or some other similar exception.

This makes debugging your code quite a lot easier because instead of seeing a mysterious crash in main.m, or in objc_msgSend, you will see the line of code in your application that resulted in that exception happening in the first place. This is true debugging power because without that bit of context you’d have no other idea about where or why your application is crashing.

Symbolic breakpoints

Symbolic breakpoints are just like regular breakpoints, but instead of catching a particular line of code, you can pause your application when a method or function call is made.  There are some pre-defined symbols you can use, or you can break on a particular method name.  For example, “objc_exception_throw” is a handy symbol to break on since it will capture an exception being thrown, regardless of whether or not it is caught. Another useful breakpoint to set is “-[NSObject doesNotRecognizeSelector:]” which will allow you to capture situations where a selector is being invoked against the wrong object.

There are of course other symbolic breakpoints you can set but there’s too exhaustive of a list to outline them here, so use the Almighty Google for future reference.

Using the debugger console

Once your breakpoint has triggered, your next question may be “Well now what?” What can you do with your code once your program has suspended? The most obvious thing you can do is single-step through the following lines to see what happens, what paths your code takes, and so forth.  But there will be times that you’ll want to deeply inspect properties or ivars in ways that the variable window won’t let you.  For this you can use the debugger console to control the debugger explicitly to find answers to your question “What’s my app doing right now?”

Printing objects

Say for the sake of argument that you’ve got an ivar named “_myDictionary” that contains some object, and you want to print out its default value.  That’s simple, you can click in the console window (the right-hand pane of the bottom debugger panel), and you can type: “po _myDictionary“.  That will print out the result of the -[NSObject description] method for that object.

However lets say you want to dig deeper, and want to print the result of a method call on that dictionary.  This is also simple: “po [_myDictionary allKeys]” works just as well.  The debugger console doesn’t understand Objective-C 2.0 Properties, but regular bracket-notation method calls works.

Printing primitives and structs

What if what you want to print isn’t an object? What if you want to print out the value of a literal (e.g. a float or NSUInteger), a struct (e.g. CGRect, CGPoint, etc), or really anything else that may or may not be an object?  With that you can use the “p” command.  However since you’re not printing an object, you need to give the debugger a hint about what kind of primitive you’re expecting.

To print a float, I would say: “p (float)_myFloatValue“. Simple variable casting here works just great.

Printing out the frame of a view is also pretty simple. “p (CGRect)[[self view] frame]“.  You notice here that I’m combining a set of method calls with a casted print statement. This will give you a pretty-formatted rendition of the rect, making it easier to debug.

Printing CPU registers

When your code is compiled down into machine code and is run on a device, your CPU steps through each operation and invokes them sequentially. When something goes wrong, and your program suspends, there are ways to inspect the state the CPU was in when a crash occurred and you can glean information from it. This is a lot less difficult than you might think.  For more information on this topic, please refer to this excellent post titled “So you crashed in objc_msgSend()“.  I’ll only be giving a high-level overview, so I highly suggest you read and bookmark that link.

Consider the sample that that above post tries to cover: your application has crashed in the objc_msgSend() method, which is Objective-C’s low-level method invocation function.  When this happens you usually don’t have any information to go on, other than a cryptic exception titled EXC_BAD_ACCESS, with your breakpoint pointing at your main.m file.

By printing the value of the CPU registers in the debugger console you can extract information about what method was being invoked.  Typing “x/s $ecx” for the iOS Simulator, or “x/s $r1” for an iOS device, will print the name of the selector that was being run that resulted in a crash.  It’s that simple!

Defensive coding

Above all else some of your best debugging techniques will be to avoid crashes altogether. Practice defensive coding by using some common C and Objective-C patterns. Don’t retain delegates, release your ivars in dealloc or in viewDidUnload. And when you release an ivar, also set its value to nil.  In fact I go so far as to create a macro that handles that for me.

#define DNRelease(x) [x release], x = nil

A technique referred to as “Yoda-Conditions” means for you to reverse your conditionals so that constants are placed on the left-hand side of your operator.  For example:

if (YES == someBoolean) ...

That is much less intuitive since nobody but Yoda speaks in reverse like that, but what this does buy you is compile-time protection against accidentally assigning a value instead of comparing it.  A simple “if (someBoolean = YES)” statement can be time-consuming to track down and is easily avoided if you always write your comparisons the other way around.

And above all else make sure you write readable code. Nobody likes ugly code, but for more than pure aesthetics. Ugly or confusing code can hide more bugs, and when you use good whitespace, sensible variable names, and you structure your code cleanly, you can expose bugs earlier and make them easier to track down later.

Good luck and happy bug-hunting, and I hope this starts you off on the right foot!

One of my pet peeves is Open Source iOS libraries distributed as just a collection of Objective-C classes, rather than being bundled as a static library. I know a lot of people prefer it that way, but from a maintainability standpoint it really doesn’t make much sense to me. So when I’m faced with another library I want to use that doesn’t have a static library readily available for it, I typically wrap it up in my own Xcode project, check it in to Github, and configure my Jenkins continuous integration build server to compile it for me.

I thought I’d walk you through the steps I go through to make this happen, so you can use this technique too.

Why I prefer static libraries

Before I go too far on this topic I wanted to explain my reasoning behind preferring static libraries, as opposed to loosely-distributed sets of classes.

Consider a large project where I’m utilizing a few libraries built by third-parties to speed up my development; a recent example of this on one of my projects is using the AFNetworking library from Gowalla. Now I could simply sync their source tree from Github, drag-n-drop their classes into my project, and I could be done with it. But what happens when one of their classes is upgraded? I have to re-sync the code, resolve any differences, and drag it back into my project.  I could of course make their project a git sub-module of my own, but then whenever I perform an update to my git project I may not know which changes their source has undergone, meaning I have no control whether or not my project will pass or fail.  And this assumes I’m using Git for my project; at work we use Perforce which has terrible Git integration.

Assuming I have an up-to-date set of classes from a third-party integrated into my project, what happens in the event I change some C pre-processor definitions that break those classes? Since every time I compile my code I have to also compile the third-party code, I don’t know if a compilation bug in the third-party classes are a problem caused by my build settings, or is a problem in their code.  If I were to consume a static library I could re-use that binary safe in the knowledge that no random changes will take place in it.  If I wanted to bring in any updates from a third-party I can choose when to integrate those updates in since I can choose when to copy over the new library.

And finally, the reason why I had to create a static library for AFNetworking in the first place, is in the transition from manual reference counting to “Automatic Reference Counting” (also known as ARC).  ARC requires actual code-level changes since such method calls as “release”, “autorelease”, “dealloc” etc are now a compilation error.  This means you can’t mix-and-match ARC and non-ARC classes in the same project.  Non-ARC code compiled in its own separate static library though can still play nice within a different ARC project.

How to create a static library

First you should begin by either forking the target library on Github, or by acquiring the source code in some other way. If you fork from Github it will make it easier to merge changes down later as the project is updated in the future, or provides for the ability to merge your static library up into the main project.

Regardless, once you get the code you begin by creating a new static library project in Xcode. It’s simple enough; just make sure you select the “Cocoa Touch” static library project and you should be good to go.  Once this opens up it will give you some boilerplate classes and settings; feel free to delete those.  You might want to create the new project somewhere within the source tree for the library in a way that won’t annoy other developers.  For example, you might not want to move the original classes around too much since it might make it difficult for other developers to merge your change into their own branches.

Once you have your empty library project you can go ahead and add all the classes you’ll be wanting to include in the library, either by using the “Add files to…” menu item, or by drag-and-dropping them from Finder into an appropriate folder in the navigation pane of your project.

At this point the code might compile, but you need to make some changes to the project settings in order to make it possible to compile, and to make it easy for you to get at the built results of the project.  Click on the root of your project to open the project settings, and make the following changes:

1. Installation Directory (INSTALL_PATH): Set this to “/”. This indicates where the products of the build (namely the static libAFNetworking.a file) will be installed, relative to the target installation root.
2. Public Headers Folder Path (PUBLIC_HEADERS_FOLDER_PATH): This controls where the public headers for your library will be installed, relative to the installation root. Set this to “Headers”.
3. Header Search Paths (HEADER_SEARCH_PATHS): This isn’t strictly necessary for all projects, but in this case we’re going to compile against the JSONKit library, but are not going to be including it in the resulting static library. So we need to tell Xcode where to find the header so it can properly compile the classes that might potentially depend on it.
4. Skip Install (SKIP_INSTALL):Set this to “No” or, in the example in the above screenshot, set delete it so the Xcode default of “No” will take effect. This is important because without this we won’t be able to install the results of this build into a directory where we can get at it.
5. Precompile Prefix Header & Prefix Header (Optional): In the example I’m showing here I didn’t actually want to add more unnecessary files to the project than needed, and since the prefix header only adds a global import of “Foundation.h”, I removed those from the Xcode project.

Once you get the static library settings configured you can take one final step to control the build phases your library will go through.  The particular build phase we want to configure is the “Copy Headers” build step.  This setting is broken down into three sections: Public, Private, and Project sections. By default all the header files of your project will reside in the “Project” section, meaning those headers will only be available to your project and will not be installed when you complete your build. The other two sections, “Public” and “Private” let you indicate a directory path where you’d like your headers put when it’s installed.

You can see in the screenshot that I’ve moved all of the AFNetworking headers into the Public section, and left JSONKit in the Project section. This is because if a user of this library wants to use JSONKit they’ll presumably get it on their own, so any headers we include here might result in a conflict. So it’s best to just include the headers for the code that is actually present in your project.

If you’re creating an SDK or a reusable API for others to use and there are some parts of your code that you would rather remain hidden, simply don’t move those headers into the “Public” section.

Building your library in Jenkins

At this point your code should compile cleanly when you click the “Build” button. But more than that we want to be able to simplify the compilation of this library so it can easily be packaged up and shipped off.  I like to either use shell scripts or “Ant” to automate my build process since it allows me to predictably run my builds deterministically with little room for human error.

There are several things we want the build script to accomplish:

1. Create a directory where the results of the build will reside;
2. Compile versions of the static library for both the device and the simulator;
3. Create a “FAT” library containing both the device and simulator results for easy debugging;
4. Create a ZIP file containing the static library and its headers.

#!/bin/sh
set -ex
INSTALL_PATH=$WORKSPACE/artifacts
[ -z $INSTALL_PATH ] || INSTALL_PATH=$PWD/artifacts
rm -rf $INSTALL_PATH
mkdir -p $INSTALL_PATH
PROJ=AFNetworking/AFNetworking.xcodeproj
xcodebuild -project $PROJ -sdk iphoneos INSTALL_ROOT=$INSTALL_PATH/device install
xcodebuild -project $PROJ -sdk iphonesimulator INSTALL_ROOT=$INSTALL_PATH/simulator install
lipo -create -output $INSTALL_PATH/libAFNetworking.a $INSTALL_PATH/device/libAFNetworking.a $INSTALL_PATH/simulator/libAFNetworking.a
mv $INSTALL_PATH/device/Headers $INSTALL_PATH
rm -rf $INSTALL_PATH/device $INSTALL_PATH/simulator
(cd $INSTALL_PATH; zip -r ../AFNetworking.zip libAFNetworking.a Headers)

If you understand Bourne Shell that code should be pretty straight-forward. You simply set up an install path relative to the Jenkins workspace (or relative to your current directory if you’re running the script by hand), run two separate builds using “xcodebuild”, use “lipo” to merge the resulting static libraries, and we create a ZIP file of the resulting files.

I’ll go through each part of the “xcodebuild” command to point out why I’m doing things this way.

• “xcodebuild -project $PROJ” – Indicate the project file that you want to build. I’m using a variable defined higher up in the script to make it easy to change.
• “-sdk iphoneos” or “-sdk iphonesimulator” – Manually specifying the SDK to use so we can compile both the device and simulator versions.
• “INSTALL_ROOT=…” – This passes a variable into the build process, allowing us to customize the path the resulting artifacts will be installed to. By default, as you can see from the above screenshots, that the path “/tmp/AFNetworking.dst” is defined.  This command-line argument lets us override that setting to configure a path of our choosing.
• “install” – Perhaps the most important part, we’re saying we want to install the files, rather than just simply building them. Xcode normally creates its build artifacts in a folder in ~/Library/Developer/Xcode/DerivedData, keyed off some awfully long UUID, and there’s no easy and deterministic way of identifying the path Xcode will choose when building its artifacts.  When using “install” the appropriate files are copied from that interim build directory and into the directory you selected above.

Getting Jenkins to rebuild when code is checked in

The final and most useful step is to get your code rebuilding automatically when you check new code into Github. This technique will work for other version control systems, but Github is certainly the easiest to control.

Make sure your build script is checked into your source tree, and configure a new job in Jenkins for your static library project. I won’t walk you through the entire process, but it’s simple enough to create a “Freestyle” project, set up your Github credentials for checking code out when a build is triggered.  From there, add a new “Execute Shell” build step, and add the following to the command:

“$WORKSPACE/build.sh”

Make sure you include the quotes, because your $WORKSPACE path that Jenkins assigns you may potentially contain whitespaces that would break that command.  From there you should be able to trigger a new build manually and have it compile your project for you.  Give it a try and make sure it works.

Next you’ll want to do something with the resulting build artifacts. What I like to do is create a single directory under which all my compiled resources will be collected and archived by Jenkins, but since the above build script created a single convenient ZIP file we can just archive that. Check the “Archive the artifacts” box, and type “AFNetworking.zip” into the field.

At this point we’re finally able to integrate our build into Github, but it’s a lot simpler than you might think.  Jenkins has an amazing REST API that lets you interact with it programmatically. If you want to kick off a new build, all you need to do is perform an HTTP GET against the “build” URL for your job. If your Jenkins server is located at http://jenkins.mycompany.com/ and your job is named “MyLibrary”, you only need to issue a GET to http://jenkins.mycompany.com/job/MyLibrary/build.

With that in mind, go to your “Admin” settings on Github for your project, and click on the “Service Hooks” menu.  Github provides a long list of services it can interact with, but the simplest and most straightforward is the “Post-Receive URLs” section. This lets you supply a list of URLs that Github should issue a request to after it has received a new checkin.

As you can see from the screenshot to the right, it’s fairly simple and is easy to test.  Next time you perform a “git push” back up to Github, your Jenkins server should automatically trigger a new build.

If you want to see everything I’ve talked about here, go to my Github fork of AFNetworking or download the AFNetworking.zip file from my website created from the process I describe above.

With iOS 4.0 Apple introduced two new technologies to the iOS platform: Grand Central Dispatch, and blocks.  Simply put, it is to multi-threaded programming what fire is to a barbecue.  Sure you can do without it, but the end result is much better.

Despite all this, developers still seem to avoid using it. Some of the reasons for this, off the top of my head, could be backwards-compatibility for older versions of iOS, unfamiliarity with the funky syntax it uses, or simply a lack of practice.  The biggest thing I find however is a general misunderstanding about the importance of multi-threading among new developers, which was made worse by the difficulty of dealing with threads before blocks and GCD was released.

Fortunately there’s no reason to avoid multi-threaded programming in iOS, but before I dive into the specifics I’d like to point out just how important it is to use an asynchronous approach to development on iOS, or any mobile platform in general.

Why should I care about GCD?

Before going into the specifics of how to use blocks and Grand Central Dispatch, I’d like to explain why it’s important. If you don’t take anything else away from this article, these points are important.  Here it goes:

Don’t make the device wait around for you to figure out what you want it to do.

The CPUs in mobile devices are really weak, memory is limited, you have some really hard limitations that you just can’t work around.  Performance problems aren’t often caused by a single slow operation, but many inefficiencies in how you utilize the hardware.  Performing expensive calculations, querying a database, reading images from disk, or other activities all take time.  Are you using caches effectively? Are you performing expensive tasks in the main thread?  There are many other things that you may be doing that can block the CPU from doing what really needs to happen: Rendering your interface to the screen 60 times per second.  If you can’t meet that target, your app is failing to provide smooth animations, and it will stick out like a sore thumb compared to the other applications on the device.

Each thread on your device runs its own event loop.  The operating system picks up a page of code, runs it, and when that chunk of code exits out the next iteration of the loop picks up.  When rendering your display, the main thread wakes up, runs all the code necessary to assemble your UI, paints a picture onto a memory buffer, and throws that on the screen. It tries to do this 60 times per second.  If each iteration of this runloop takes more than 16ms to run, then your device will drop frames and your display will get jittery.  If it takes less than 16ms, this means there’s spare CPU cycles available to do other work.

The basics of asynchronous programming

Developers in general are quite lazy; in fact, laziness is a great virtue to have as a programmer.  It means we’d rather be doing something else, so we want to do as little work as possible so we can get on with other work.  So it’s quite understanding why so many applications are developed with lots of synchronous code: It’s just easier to think about problems in a linear fashion.  You break a problem down into a series of steps, and write the code necessary to do those steps in order. Fortunately for us most computers are fast enough that this technique works well.  But once you switch to a mobile platform, long linear functions need to be broken down into smaller steps.

Consider an example where you download an image over the network, you resize and scale it to a thumbnail, and then put it onto the screen.  Because any operation interacting with the UI must be performed on the main thread, the easy route is to do all the above as a single synchronous set of instructions on the main thread.  Doing so however will result in the UI freezing up during the download, image conversion, and image resizing operations.

// Download the image
NSURL *url = [NSURL URLWithString:@"http://bit.ly/nUX01h"];
NSURLRequest *req = [NSURLRequest requestWithURL:url];
NSURLResponse *res = [[NSURLResponse alloc] init];
NSError *err = nil;
NSData *data = nil;
data = [NSURLConnection sendSynchronousRequest:req
                             returningResponse:&res
                                         error:&err];
// Convert the data to a UIImage
UIImage *image = [UIImage imageWithData:data];
   
// Scale the image
UIImage *thumbImage = nil;
CGSize newSize = CGSizeMake(90, (90 / image.size.width) * image.size.height);
UIGraphicsBeginImageContext(newSize);
[image drawInRect:CGRectMake(0, 0, newSize.width, newSize.height)];
thumbImage = UIGraphicsGetImageFromCurrentImageContext();
UIGraphicsEndImageContext();
 
// Add this to a UIImageView
self.imageView.image = thumbImage;

Not only is converting the image from data to a UIImage or scaling the image to a  thumbnail expensive, but depending on the speed of the user’s network (e.g. wifi, 3G, AT&T, etc) the download could take significantly longer.  So the best way is to break this up into multiple smaller steps. When each step finishes, the system will work on the next chunk.

Taking the above example of what not to do, lets refractor it slightly to use blocks.

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_LOW, 0), ^{
    NSURL *url = [NSURL URLWithString:@"http://bit.ly/nUX01h"];
    NSURLRequest *req = [NSURLRequest requestWithURL:url];
    [NSURLConnection sendAsynchronousRequest:req
                                       queue:[NSOperationQueue currentQueue]
                           completionHandler:
     ^(NSURLResponse *res, NSData *data, NSError *err) {
         // Convert the data to a UIImage
         UIImage *image = [UIImage imageWithData:data];
          
         // Scale the image
         UIImage *thumbImage = nil;
         CGSize newSize = CGSizeMake(90, (90 / image.size.width) * image.size.height);
         UIGraphicsBeginImageContext(newSize);
         [image drawInRect:CGRectMake(0, 0, newSize.width, newSize.height)];
         thumbImage = UIGraphicsGetImageFromCurrentImageContext();
         UIGraphicsEndImageContext();
          
         dispatch_async(dispatch_get_main_queue(), ^{
             self.imageView.image = thumbImage;
         });
     }];
});

As you can see most of the code is the same, except we’re breaking things down into smaller discrete chunks.  Each block is nested, allowing code to be called only when it is needed.  I’ll go into more detail with this shortly, but see if you can piece together what’s different between these two samples of code.

Doing the above fully asynchronously without blocks is entirely possible, but results in more complicated code that is more difficult to maintain.  The biggest difficulty is in keeping track of values and properties between threads, and results in a lot more boilerplate code.  Using blocks you can simply access the variables accessible within your current scope, making everything much easier.

What is a block?

Blocks in essence are nested functions that can be passed around as a pointer that has access to variables defined in the scope the block is defined in.  If you have ever worked in a language that supports “closures” (e.g. JavaScript, Perl, etc) you’ll probably already be familiar with this.

Blocks in Objective-C are defined rather strangely, but once you get used to it they make sense.  The carat “^” character is used to define a block. For example, “^{ … }” is a block. More specifically, it is a block that returns “void” and accepts no arguments.  It is equivalent to a method such like: “- (void)something;” but there is no inherent name associated with the code block.

Defining a block that can accept arguments work very similarly.  If you wanted to supply an argument to a block, you define the block like so: ^(BOOL someArg, NSString* someStr) { … }.  When you use API calls that support blocks, you’ll be writing blocks that look similar to this, especially for animation blocks or NSURLConnection blocks as shown in the above example.

The easiest way to get started with blocks is to simply use existing APIs that support them. NSURLConnection above supports blocks, as do UIView animations, like so:

[UIView animateWithDuration:1.0
                 animations:^{
                     someView.alpha = 0;
                     otherView.alpha = 1;
                 }
                 completion:^(BOOL finished) {
                     [someView removeFromSuperview];
                 }];

If you have any experience with animating views without blocks, getting a completion handler to run after an animation has completed is extremely cumbersome, so much so that many developers don’t bother with them. Using the block-enabled alternative makes for much cleaner code, and makes it fun to create complex animations.

How does GCD tie into this?

Grand Central Dispatch is a facility for managing threads and queueing tasks in parallel efficiently, without you needing to worry about the boilerplate specifics around performance and startup / shutdown of threads.  Blocks and GCD are both completely different technologies, but since they work so well together it’s trivial to get started with it.

In order to use GCD, you use one of the functions that begin with “dispatch_“.  One of the common tasks a developer would want to perform is to run some small task in a background thread, and then run some other code on the main thread once that task has completed.  You may notice the call to “dispatch_async” up above, which explicitly runs a block on the main thread.

Dispatching blocks can either be triggered synchronously or asynchronously by using the dispatch_sync or dispatch_async functions, and they both take two arguments: The queue you want to dispatch your block on, and the block you’d like to dispatch.  Individual queues are analogous to threads, but the specifics about which thread your code will be run on is hidden from you, meaning the operating system can optimize the use of threads based on the number of cores your system possesses.

The two most common ways you’d get a pointer to a queue is to either fetch the main queue using “dispatch_get_main_queue()” or to fetch a queue with a specific priority, you use dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0) and specify the priority you’d like (DEFAULT, LOW, HIGH, or BACKGROUND).

How do I create my own block APIs?

The most difficult part of dealing with blocks for many people is how to define your own methods or APIs that utilize blocks, mostly due to the confusing syntax used to define them.  Once you figure out how the syntax is broken down however, it’s quite easy.  Let me start with a few examples.

So first, let me show you how to define a block that takes no arguments and returns nothing.

- (void)noArgBlock:(void (^)(void))block;

The syntax we’re concerned about here is in the definition of the “block” argument.  As you know, you declare the type of an argument in parenthesis immediately before the name of the attribute.  So it’s easiest to ignore those outer parenthesis when dealing with block definitions.

void (^)(void)

Now things are looking a little more straight-forward, and a little closer to a standard C function.  The first word is the return type we expect a block with this definition to return.  Since we said we were creating a basic block that returned nothing, this is set to “void“.

Normally in a C function definition the very next thing after the return type would be the function name.  But since blocks aren’t actually named, instead we use “(^)” to denote that it’s an unnamed block that we’re defining.  So far so good, right?

Finally we define the parameters this block will accept.  Again with regular C functions this should be familiar, since you give a parenthesized list of arguments you’ll be providing to this function.  Since we’re not accepting any arguments to this block, we indicate that by putting in “void“.

And that’s it! Lets show you how you’d use that in your function!

- (void)noArgBlock:(void (^)(void))block {
    // Do something...
     
    // Call our block
    block();
}

When you want to invoke a block function supplied to your method, you can just call it like you would any C function.  But what if we want to call that block on a different queue or thread?  That’s easy enough too.

- (void)noArgBlock:(void (^)(void))block {
    // Do something...
     
    // Call our block
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_LOW, 0), block);
}

We’re using the GCD dispatch function here to trigger our block asynchronously on a low-priority queue.  Blocks can be passed around as variables, so we don’t have to explicitly define our own inline block here like we did in the animation or image examples at the beginning of this article.

Armed with all that syntax in mind, lets create a block that accepts an argument, and I’ll show you how to use it.

- (void)hasArgsBlock:(void (^)(NSString *name, BOOL animated))block {
    block(@"FOO", NO);
}

Remember from what I said that the second set of parenthesis in a block definition is the argument list you’ll be supplying to the block.  In this case, we’re accepting a callback that takes an NSString and a BOOL argument.  This is a contrived example since we’re simply dispatching the block immediately, but we could just as easily include our block call in our own block callback as the result of a UIView animation, an NSURLConnection completion block, or anything else.  A user of this method could look like this:

[self hasArgsBlock:^(NSString *name, BOOL animated) {
    NSLog(@"Name: %@, animated %d", name, animated);
}];

How do I store a block as an ivar?

This is a much trickier question, and is one of the things that makes people run screaming from blocks, assuming they didn’t already do so when they saw the “void(^)(void)” syntax soup.  Consider the example where you want to store a block for later use, or re-use.  If we want to store a void block, a simple solution is to use a built-in GCD type to reference blocks.

The dispatch_block_t type can be used.

@interface MyViewController : UIViewController {
    dispatch_block_t _simpleBlock;
}
 
@property (nonatomic, copy) dispatch_block_t simpleBlock;

If you want to store a block that either accepts arguments or returns a value, it’s possible to use the block-parenthesis-soup as the type definition for an ivar.  For example, assume we want an ivar named “completionBlock” defined within our class. We can do so with the following code:

@interface MyViewController : UIViewController {
    void (^completionBlock)(NSString *name, BOOL animated);
}

However that looks hideous, and is difficult to maintain. Instead it’s in your best interest to define your own custom type based on the block-soup you’d use in a method declaration. If we wanted to create a typedef for our above block, the one that accepts a name and animated property.  We could do so with the following declaration.

typedef void (^MyCompletionBlock)(NSString *name, BOOL animated);

By including a name after the carat symbol you can assign the block definition a name.  Then, later, you can use that typedef in an ivar, in a property, or even as an argument to another method.

@interface MyViewController : UIViewController {
    MyCompletionBlock _completeBlock;
}
 
@property (nonatomic, copy) MyCompletionBlock completeBlock;
 
- (void)storeMyBlock:(MyCompletionBlock)block;

Since blocks are objects, you need to copy them if you want to store them as a property, and don’t forget to release them when you’re done with them, or in your class’ dealloc method.

Closures, variables, and retain cycles

As I mentioned above, blocks work as closures, meaning you have access to the local variables within the scope a block is defined in.  This makes your code really easy to work with, but there are some limitations that are imposed for some very good reasons.  Consider the following example:

NSArray *someArray = ...;
int myCount = 0;
[someArray enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
    int someValue = [obj intValue];
    myCount += someValue;
}];

This is a great way to perform an operation against an array or set using blocks because it will take advantage of multiple cores to be able to run your code faster when it’s possible.  However the above code won’t work if you actually tried it, because there’s a specific limitation in blocks which prevent you from writing to values declared outside of the block.  Think of it as a thread-locking problem. If you were to build that above code, you’d get an error that says “Variable is not assignable (missing __block type specifier)”.

It’s simple enough to work around this.  You can use the “__block” flag when declaring a variable so you can allow it to be writeable from within a block.  For example, the above code could just have this one change and everything would work as you’d expect:

 __block int myCount = 0;

One other gotcha is regarding retain cycles when using the special “self” variable.  In the case where you retain a block and, within that block you refer to your “self” object, this will cause an unbroken retain cycle where the block is retained by self, and “self” is retained by the block.

self.completionBlock = ^(NSData *result) {
    [self saveFile:result];
};

This little block will take some data returned from some code and save it in some way.  However because the “self” variable is retained by the block, as well as the scope outside of the block, this block will leak memory.  Yet again, this is easily solved by declaring a “weak” reference to the self variable, and then using that within the block.  If you’ve ever worked in JavaScript you’ll be familiar with this pattern.  The resulting code would look like the following:

__block __typeof__(self) _self = self;
self.completionBlock = ^(NSData *result) {
    [_self saveFile:result];
};

Bringing it all together

Blocks are an extraordinary enhancement to the language, and if you take full advantage of it in your applications you’ll be able to seamlessly take advantage of faster language features, your code can spread across multiple cores seamlessly, and you can easily break serialized tasks into fast divisible units of labour.

Take a look through the various block APIs that Apple supports, and embrace it as much as you can.  In the long run it’ll make your code easier to understand, and faster as technology advances.  Don’t be left behind!

One of the things I like most about Apple’s iOS SDK is the consistent and easy-to-use API they provide.  Across all their different frameworks there’s a pattern at work that makes using their classes easy to understand.  This is due in part to the simplicity for configuring those objects.  In most cases you don’t need to call cryptic methods to setup or teardown classes.  If you want to change a label’s font, you just set a property.  If you want to add a new set of tabs to a UITabBarController, you simply have to assign an array of view controllers to the “viewControllers” property and away you go.

This up front simplicity comes at a cost however: somebody had to write code to intercept the setting of those properties and update the view to reflect the changes made.  Fortunately for those developers at Apple, Cocoa and Cocoa Touch makes this simple through the use of Key-Value-Observing (KVO).  If you know how to use it, you can do the same thing in your applications as well.  Read on to see what I do to make implementing KVO in my projects easy and intuitive.

What is Key-Value-Observing?

Key-Value-Observing, or more commonly KVO, is a mechanism by which you can observe changes to keys and their values bound to an object.  It lets you make arbitrary objects aware of changes made to values in other objects that are important to you.  When those values are changed at all, the observeValueForKeyPath:ofObject:change:context: method is invoked on the listener, or “observer”.  In essence, it lets you listen to when people change properties on your object.

You might say “Really? That’s all it does? I can get the same by creating a custom setter!” and you might be right, but there’s several reasons why creating custom setters to handle update logic might be undesirable:

1. It’s easy to create one or two custom setters, but quite tedious if you have lots of properties you want to observe.
2. Custom setters only work if you are monitoring properties under your control, but impossible if you want to monitor changes made to other objects you encapsulate.
3. You have to implement your own retain/release/copy cycles manually, instead of simply using @synthesize.
4. You have to manually keep track of what the old and new values of a property, if they’re important to you.
5. Your code looks like dog food.

Using KVO in a class essentially buys you flexibility and easy-to-read code, and with a few general practices can be made easy to read and easy to extend.

Setting up KVO the hard way

Many developers getting started with KVO, myself included, typically start by assigning observers for one or two keyPath properties in either their init or viewDidLoad methods.  Then, within their observeValueForKeyPath:ofObject:change:context: method they will have code to respond to those setting changes.

As an example lets assume we’re creating a UIView subclass that has a UIColor property that controls the display of several subviews.

@property (nonatomic, copy) UIColor *color;

When that property changes lets make our view update all our sub-views to the appropriate color. We could do this with a custom setter, like so:

- (void)setColor:(UIColor *)color {
    if (color != color) {
        [color release];
        color = [color retain];
 
        mTitleLabel.textColor = color;
        mDescriptionLabel.textColor = color;
        [mButton setTitleColor:color
                      forState:UIControlStateNormal];
    }
}

For the purposes of this example though, lets utilize KVO for this.

 - (id)initWithFrame:(CGRect)frame {

    self = [super initWithFrame:frame];
    if (self) {

        [self addObserver:self
               forKeyPath:@"color"
                  options:0
                  context:nil];
    }
}
 

- (void)observeValueForKeyPath:(NSString*)keyPath
                      ofObject:(id)object
                        change:(NSDictionary*)change
                       context:(void*)context
{
	if ([keyPath isEqualToString:@"color"]) {
        mTitleLabel.textColor = self.color;
        mDescriptionLabel.textColor = self.color;
        [mButton setTitleColor:self.color
                      forState:UIControlStateNormal];
	}
 
    else {
        [super observeValueForKeyPath:keyPath
                             ofObject:object
                               change:change
                              context:context];
    }
}

In the initWithFrame: method we add ourselves as an observer of the keyPath “color”, passing in the default options.  We also define a method that Cocoa Touch uses to notify the observer, in this case “self”, when a keyPath has been changed.  This method is invoked for different properties that are changed, so you should always pass the message along to “super” if this method is called for a property you didn’t explicitly add as an observer.

While the above code does look longer than the custom setter equivalent, in the long-run this code is much easier to extend over the life of your class, especially as you add more complex behaviors.

Keeping Track of Your Key Paths

As my experience with KVO improved, so did my techniques for managing my observers, responding to keyPath value changes, and generally keeping my code clean.  One of the things I found was that it is useful to keep a list of the keyPaths you’re observing so that you can conveniently iterate over them programmatically.

To illustrate my point, consider an example where you expose multiple subviews as properties, and when some values change you would like to perform some sort of redraw operation.

- (id)initWithFrame:(CGRect)frame {

    if (ObservableKeys == nil) {
        ObservableKeys = [[NSSet alloc] initWithObjects:
                          @"titleLabel.font",
                          @"descriptionLabel.font",
                          // ...
                          nil];
    }
 
    self = [super initWithFrame:frame];
    if (self) {

        for (NSString *keyPath in ObservableKeys)
            [self addObserver:self
                   forKeyPath:keyPath
                      options:0
                      context:nil];
    }
}
 

- (void)dealloc {
    for (NSString *keyPath in ObservableKeys)
        [self removeObserver:self
                  forKeyPath:keyPath];
    [super dealloc];
}
 


- (void)observeValueForKeyPath:(NSString*)keyPath
                      ofObject:(id)object
                        change:(NSDictionary*)change
                       context:(void*)context
{
    if ([ObservableKeys containsObject:keyPath]) {
        [self redrawView];
	}
 
    else {
        [super observeValueForKeyPath:keyPath
                             ofObject:object
                               change:change
                              context:context];
    }
}

As you can see not only would this be impossible to do with custom setters, but we managed to respond to several different property changes using a single block of code.

Additionally, keeping a static NSSet object around with a list of the keys you’re observing is convenient for several reasons:

1. It lets you easily add your object as an observer of several keyPaths without having to copy/paste code.
2. Your generated code is tighter because you don’t have to worry about inline strings being littered throughout your class.
3. If you change the name of a keyPath, it happens in a much more limited area.

There are other advantages, but this is just the tip of the iceberg.

Implementing KVO in a UITableViewCell Subclass

In order to illustrate how to build a more complicated feature using KVO, lets create a UITableViewCell subclass that makes it easy to create a gloss icon in your table cells, just like the iTunes App Store app.  If we’re successful we should be able to create a table cell whose icon looks like the screenshot to the right.

Instead of requiring us to worry about the details of rendering the gloss icon overlay every time we want to display an app icon, lets create a property on our table cell that encapsulates this behavior.  Ideally we should be able to set the app icon’s original image once, and the UITableViewCell imageView.image property should be set to the appropriate content.  We could do this with a custom accessor, but I’d like to show you an easy way to do this with KVO.

#import <UIKit/UIKit.h>
 
@interface AppStoreItemView : UITableViewCell
 
@property (nonatomic, retain) UIImage *icon;
@property (nonatomic) BOOL iconNeedsGlossEffect;
 
@end

You can see from our interface declaration that we’re adding two properties for the icon image itself, and a boolean indicating whether or not we want the gloss effect.  Now lets look at the implementation.

#import "AppStoreItemView.h"
#import <QuartzCore/QuartzCore.h>
 
static NSSet * ObservableKeys = nil;
static NSString * const IconKeyPath = @"icon";
static NSString * const IconNeedsGlossEffectKeyPath
    = @"iconNeedsGlossEffect";
 
@interface AppStoreItemView ()
 
- (UIImage*)glossImageForImage:(UIImage*)image;
 
@end
 
@implementation AppStoreItemView
 
@synthesize icon;
@synthesize iconNeedsGlossEffect;
 
- (id)initWithStyle:(UITableViewCellStyle)style
    reuseIdentifier:(NSString *)reuseIdentifier
{
    // Setup our set of observable keys only once
    if (nil == ObservableKeys) {
        ObservableKeys = [[NSSet alloc] initWithObjects:
                          IconKeyPath,
                          IconNeedsGlossEffectKeyPath,
                          nil];
    }
 
    self = [super initWithStyle:UITableViewCellStyleSubtitle
                reuseIdentifier:reuseIdentifier];
    if (nil != self) {
        // Add observers for each of the keyPaths we care about
        for (NSString *keyPath in ObservableKeys)
            [self addObserver:self
                   forKeyPath:keyPath
                      options:(NSKeyValueObservingOptionOld |
                               NSKeyValueObservingOptionNew)
                      context:nil];
         
        self.imageView.layer.cornerRadius = 10.0;
        self.imageView.layer.masksToBounds = YES;
    }
     
    return self;
}
 
- (void)dealloc {
    // Tidy up and remove all the observers when the view is destroyed
    for (NSString *keyPath in ObservableKeys)
        [self removeObserver:self
                  forKeyPath:keyPath
                     context:nil];
     
    [super dealloc];
}
 
- (void)observeValueForKeyPath:(NSString *)keyPath
                      ofObject:(id)object
                        change:(NSDictionary *)change
                       context:(void *)context
{
    // If the keyPath being changed isn't one we care about,
    // pass this up to super and return immediately.
    if (![ObservableKeys containsObject:keyPath]) {
        [super observeValueForKeyPath:keyPath
                             ofObject:object
                               change:change
                              context:context];
        return;
    }
     
    // Fetch the old and new objects from the change dictionary
    id oldObject = [change objectForKey:NSKeyValueChangeOldKey];
    id newObject = [change objectForKey:NSKeyValueChangeNewKey];
     
    // Detect null values, since the changed object references
    // are object references.
    if ([NSNull null] == (NSNull*)oldObject)
        oldObject = nil;
    if ([NSNull null] == (NSNull*)newObject)
        newObject = nil;
     
    // Update imageView when the icon is changed
    if ([IconKeyPath isEqualToString:keyPath]) {
        self.imageView.image = [self glossImageForImage:newObject];
    }
     
    // If the gloss effect is changed, refresh the gloss image
    else if ([IconNeedsGlossEffectKeyPath isEqualToString:keyPath]) {
        self.imageView.image = [self glossImageForImage:self.icon];
    }
}
 
- (UIImage*)glossImageForImage:(UIImage*)image {
    // Code goes here to create the gloss image
    // and return the resulting image.  See the
    // sample code for the full example.
    return mergedImage;
}
 
@end

This code may seem complicated, but in the end it is very straight-forward. I’m also introducing a few additional concepts here that I’d like to call out specifically.

Observing Options

KVO allows you to specify different options for when you’re observing a set of keyPaths. It’s a bit-mask, so you can enable multiple options simultaneously.  In this example I’m indicating that I want to be notified of both the old and new values of these properties.  When the icon is changed, the change dictionary supplied to our callback tells us both the old and new values of the property.

Using static strings for keyPaths

This is a pattern I use which helps for simplicity of code, as well as a defensive coding mechanism. By declaring static NSString variables for each keyPath you’re observing, it ensures you won’t accidentally type the wrong keyPath somewhere in your code. It also gives you a single place for defining, or changing, the keyPath you’re interested in observing.

Returning early from the observer callback

In this example I’m returning early in the block, when the keyPath is not in my set of “ObservableKeys”. This makes the callback code cleaner since you eliminate one extra nested “if” block, and helps to prevent mistakes.

Detecting null values in the observer callback

I find it useful to extract values from the change dictionary as early as possible, and then cast those values as needed.

Using private methods for observer callback behaviour

If you’re not careful your observer callback can get quite large.  It’s powerful to be able to have a single point where complex behaviours and patterns can be established between different properties, but you should make sure it doesn’t become overgrown with logic. It’s better to start out by pushing complex logic into private methods, and simply invoke that from within your callback.

Where to go for help

Apple’s own documentation, as always, is a good source of information but it can tend to be a lot to take in.  At this point you should have a basic understanding of how KVO works, and how you can use it in your application.  You can also download the sample application created above at Github.

Once you get started, finding answers to your questions becomes simpler when you’ve gotten the hang of KVO.  Good luck, and happy coding!

Following up on my previous post in this series, I’m going to continue talking about beginner topics that I and many other developers take for granted. So for this entry in my “Back To Basics” series I’d like to talk about UITableViews, and how to simply and easily construct one without convoluted or confusing code.

This topic in particular is something I’ve struggled over in the past and never managed to find a clear example for how to get started. Certainly there’s a lot of examples to show how to construct a table view, how to create a datasource for it, and the basics for how to construct cells. But hardly anyone tells you how to easily and conveniently construct a menu of options without going down a maze of twisty passages.

So today I’ll show you how you can use simple “typedef” structures to describe and control a simple menu of options.

Basics of UITableView datasources

Before we get started I wanted to go over the UITableViews themselves. Essentially they’re broken down into three parts:

1. The tableview itself;
2. The datasource which supplies the tableview with information about the sections and rows that should be shown in the tableview;
3. The delegate which responds to user interactions, such as selecting an individual cell.

There are many reasons why they’re broken down into those parts, but the big reason is this: performance.

Table views are great because of the sheer speed at which you can scroll through one, even on a tiny device such as an iPhone. It’s trivial to even zoom through a table containing 10,000 rows, and this is because the table only ever constructs views for the cells that happen to be visible at a given moment. If only 10 rows can be visible at a time, that’s a much smaller amount of memory and CPU needed to construct and paint those views on the screen.

The other performance benefit you get is the views for individual cells are reused, meaning you only have to (theoretically) construct them once, and all subsequent cells simply change the values for each cell.

Due to all of that, the datasource is interrogated by the table, asking questions like this:

• How many sections are in the table?
• How many rows are in section X?
• What’s the title of section X?
• Give me a UITableViewCell for row Y in section X

And so on. Typically your delegate and datasource is the same object, so you’ll just have a few methods that answer those questions.

Easily displaying a menu of options

Recently on an update to my oldest iOS application, aCookie Fortune, I wanted to show a menu of options. Some simple buttons, a multiple-choice selection, and a few toggle buttons. Nothing major, but I didn’t want to make things overly complicated. And more to the point, I wanted to build the settings menu as quickly as possible because I don’t have a lot of time in my day, especially for an app that generates as little revenue as this one does.

So when I wanted to have an easily configurable tableview that allowed me to quickly change the order of sections, rows, intermix cell types and accessory views easily, I turned to my good old friend “enum”.

You see, I use enums to control the order of sections, the order of rows, and so forth. If you’re not familiar with an enum, it’s a feature of C that lets you create an enumerated list of variables easily.

Keeping track of sections

In order to define the order of my sections, and the number of visible sections, all I do is declare the following:

enum {
	SettingsSectionSettings,
	SettingsSectionCategories,
	CountSettingsSections
};

This simply describes 3 variables, each with a value 0, 1 and 2. But when the tableview asks my datasource how many sections are in my table, all I have to do is this:

- (NSInteger)numberOfSectionsInTableView:(UITableView*)tableView {
    return CountSettingsSections;
}

Even though I only plan to show two sections in my table, I declare a third enum constant that is used to show how many sections will be displayed. If I later choose to add an extra section in the middle that will push the “CountSettingsSections” key down, resulting in it having a higher number. This conveniently keeps track of the number of sections without me having to maintain a separate counter.

Number of rows per section

Another thing I need to tell my tableview about is how many rows will be in each section. Similar to the listing of sections, the listing of rows in the first section is controlled by yet another enum listing.

enum {
	SettingsSectionSettingsRowInBed,
	SettingsSectionSettingsRowSharingOptions,
	CountSettingsSectionSettingsRows,
};

The second section, the listing of categories, will be controlled directly by an array of the available categories. So we simply return the appropriate value based on which section number the tableview is asking the datasource about.

- (NSInteger)tableView:(UITableView*)tableView
 numberOfRowsInSection:(NSInteger)section {
	switch (section) {
		case SettingsSectionSettings:
			return CountSettingsSectionSettingsRows;
        case SettingsSectionCategories:
            return [allCategories count];
		default:
			return 0;
	}
}

Notice in the tableView:numberOfRowsInSection: method we use a switch statement to test which section we’re being asked about? Conveniently enough we’re able to use the constants defined in our first enum which lists the sections we’ll use. The handy thing is that if you want to reorganize your sections, all you have to do is reorganize the associated constants in your enum and your section numbers will all update accordingly.

Section titles

There isn’t much difference between returning the number of rows in a section, or the titles for the sections themselves. Again notice that we’re using the section enum to evaluate which section we’re being asked about.

- (NSString*)tableView:(UITableView*)tableView
titleForHeaderInSection:(NSInteger)section {
	switch (section) {
		case SettingsSectionSettings:
			return NSLocalizedString(@"Sharing settings", nil);
        case SettingsSectionCategories:
            return NSLocalizedString(@"Fortune categories", nil);
		default:
			return nil;
	}
}

Note: You may notice that I’m not simply returning the plain strings, but am instead making them localizable. Do yourself a favour and just do that. Trust me.

Cell contents

Rendering the cell contents is fairly straight-forward, but since there’s typically more code involved in populating your cells I prefer to break those out into separate methods.

- (UITableViewCell *)tableView:(UITableView*)tableView
         cellForRowAtIndexPath:(NSIndexPath*)indexPath {
    static NSString *CellIdentifier = @"CellDefault";
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    if (!cell) {
        cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleValue1
                                       reuseIdentifier:CellIdentifier] autorelease];
    }
	switch (indexPath.section) {
		case SettingsSectionSettings:
			[self configureSettingsCell:cell atRow:indexPath.row];
			break;
		case SettingsSectionCategories:
			[self configureCategoriesCell:cell atRow:indexPath.row];
			break;
		default:
			break;
	}
    return cell;
}

This block of code sets up a common cell, potentially reusing it for performance reasons, and then uses our section enum to determine which section the row we’re being asked to provide lives in. Then depending on section we invoke a different method, supplying the row number that we need to return.

Wrapping up

It’s really that simple. You can create fairly sophisticated interfaces, or part of an interface, using nothing but enums and switch statements. For more involved interfaces you’ll want to mature into using Core Data or your own private data structures to provide your table views with information. But even in complicated applications there are instances where “Simple is better”.

These days I’ve been working on some fairly advanced iOS development techniques on my various projects: I’ve taught myself (badly) about Core Audio, I’m learning OpenGL, I’m developing a series of applications using Core Data, asynchronous parsing of JSON from a streaming HTTP connection, etc. It’s extremely fun and easy once you understand the basics.

What I tend to forget however is that you have to crawl before you can walk, and many people still struggle with some of the simpler techniques that I’ve learned that may not be so obvious, even when reading books or tutorials on Objective-C programming.

Since my previous series of articles on Core Animation (Part 1, Part 2, Part 3, Part 4) were so well received, I thought I’d do another series of articles titled “Back To Basics”.

So without further ado, I give you the first part in my series: Positioning UIViews.

One size does not fit all

First please forgive me for the horrible pun in this title. Originally I meant that there are several different ways to resize and position views in UIKit, but the pun about sizes was a bonus. The point is that there are several properties UIView and UIView subclasses have that can influence their size and position, and none of them are wrong. However there are circumstances where one is better or more convenient to use than the other.

view.frame

The most common method people seem to use for positioning their views is through the “frame” property. For those of you unfamiliar with it, this is used to set the X,Y position of the top-left corner, and the Width/Height of the view. Many people use this without realizing it, because some views are created like so:

CGRect fr = CGRectMake(x, y, w, h);
UIView *view = [[UIView alloc] initWithFrame:fr];

While this is a powerful method to layout interfaces, it can get pretty tedious if you’re arranging several views that need to be positioned relative to each other. Consider a case where you want to align a row of buttons and distribute them evenly across the screen.

NSArray *allButtons; // Add UIButton objects here
int btnNum = 0;
int numBtns = [allButtons count];
for (UIButton *button in allButtons) {
   CGFloat w, h, x, y;
   w = button.frame.size.width;
   h = button.frame.size.height;
   x = self.view.frame.size.width / numBtns * btnNum;
   y = self.view.frame.size.height / 2 - h / 2;
   button.frame = CGRectMake(x, y, w, h);
   [self.view addSubview:button];
   btnNum++;
}

That is a lot of extra code that looks fairly messy. If you have a few instances of that, your code can get pretty cluttered.

view.center

The “center” property represents the X,Y coordinate for the center-point of your view. I know a lot of you will say “Well, duh!” but what you may not realize is that it’s a read/write property that is automatically tied to the “frame” property. So changing the frame for your view will automatically update your “center” property, and vice-versa.

I prefer setting the center property when aligning or arranging multiple views relative to each other because:

1. You don’t risk accidentally changing the size of the views;
2. You don’t have to constantly divide by 2 to align views;
3. The code is much more concise.

This property is especially useful when moving views using animations.

[UIView beginAnimations:@"BounceAnim" context:nil];
[UIView setAnimationRepeatCount:1];
[UIView setAnimationRepeatAutoreverses:YES];
myView.center = CGPointMake(myView.center.x,
                            myView.center.y + 10);
[UIView commitAnimations];

This simple bit of code lets you animate a view so that it bounces once. By using the “center” property we can trust that we’re simply moving the view around, instead of having to worry about maintaining its size.

view.bounds

Similar to the “center” property, the “bounds” property is related to the “frame” property. When you alter the bounds, it changes the size of the view relative to its center point. This is really convenient if you adjust the center and bounds independently. For example, you can set the bounds property to a CGRect region with an origin of (0,0) to set its size, and can then adjust the center coordinate to position it in the screen.

UIView *view = [[UIView alloc] initWithFrame:CGRectZero];
view.center = CGPointMake(x, y);
view.bounds = CGRectMake(0, 0, w, h);

The example code above shows us creating a brand new UIView instance, and changing its center and bounds properties independently. Even though we’ll be setting those properties after, when we call “initWithFrame:” we still have to supply a valid CGRect value.  In this case we use the constant “CGRectZero” which essentially means a frame with all values set to 0.

Managing your views like this is convenient when you either don’t know what size the view should be yet, or you don’t know where on the screen it should be. Or, frankly, it might make your code prettier to separate the construction and positioning of your views.

view.transform

As you may have seen in my previous series on Core Animation, Apple provides a very sophisticated animation framework for your interface. What many people don’t realize is that every UIView object in UIKit is backed by a CALayer, which is where the actual drawing operations happen (there’s more to it than this simple explanation, but for now it’ll do).

By setting the “transform” property of a view to a CGAffineTransform you can alter the position of the view’s layer without having to explicitly move its position. Translation, rotation and even scaling or skewing your view are all possible easily with this property.

This is useful when you want to perform subtle movements such as rotations, or you want to scale your object in or out. For example, you may want a button to “throb” by animating its scale.  Or you may want your view to spin, even in 3D.  These are all examples of what you’d use this property for.

view.autoresizingMask

This property is often neglected by beginner iOS programmers and is by far one of the most useful for laying out your interfaces. Consider the situation where you want your view to resize when the device is rotated between portrait and landscape orientations. The novice programmer will detect the screen rotation and will explicitly set the “frame” property of all their views to fit the new screen size. This is the WRONG way to manage your interface.

Visual guide to where each UIResizing option is used

Instead you can use the “autoresizingMask” property to describe how you want your view to adapt to orientation changes. Your options (shortened for brevity) are:

• None
• FlexibleWidth
• FlexibleHeight
• FlexibleLeftMargin
• FlexibleRightMargin
• FlexibleTopMargin
• FlexibleBottomMargin

Consider the example of a toolbar at the bottom of your screen. If you want to have the toolbar stretch to fill the available width, but still remain snug against the bottom of the window, you can say:

myView.autoresizingMask = (UIViewAutoresizingFlexibleWidth |
			   UIViewAutoresizingFlexibleTopMargin);

Using a bitwise “OR” (the “|” pipe character) you combine multiple options together into a single value that tells UIKit how you want your view to adapt to changes to the screen, and even to changes in your view’s superview.

Another example is an interface that has the standard round “i” button in the bottom-right corner of the screen.

myView.autoresizingMask = (UIViewAutoresizingFlexibleLeftMargin |
			   UIViewAutoresizingFlexibleTopMargin);

If you play with those values you can get around the need to explicitly position or resize your views in almost all cases.

When in doubt, use a NIB

If you’re just getting started, or even if you’re a veteran iOS developer, you may want to simply layout your interfaces in Interface Builder rather than positioning your views manually. The performance difference is negligible, and there’s even ways in iOS 4 and above that can cache NIBs for greater performance. And there’s nothing that says you can’t rough-in your interfaces in Interface Builder, and then customize or fine-tune it after your view has loaded.

The most important thing above all else is to just play around with your application and see what works for you. There is no single “silver bullet” to laying out your interfaces. Every case is different, and use the method that is suited to your scenario.

When in doubt, if you find you have a ton of cluttered and error-prone code for laying out your interfaces, chances are you’re just simply doing it wrong. Try something else and do what works.

Like most developers, I look to Apple’s default application templates to get up-to-speed on what would appear as being the Right Way™ of developing apps on iOS. In practice however what you need to realize is Apple’s templates are meant to be the easiest introduction to a set of tools that can be fairly complicated for beginners to understand.  Core Data is one of those areas. The problem is when you try to grow your application you’ve built on top of Apple’s sample template. You’ll experience some annoying growing pains, and will need to give your code a thorough washing and a fresh coat of wax to be able to mature your application.

In my code I’ve learned to share and reuse my classes with other applications I’m writing by encapsulating a lot of the boilerplate into reusable classes, as well as wrapping my whole Core Data model in a reusable static library. This wasn’t the most intuitive thing to get right, but now that it’s done it was really worth the effort. Let me show you how it’s done.

Note: All code samples here will be for iOS4 and above and have been formatted to fit this blog post. For the sake of brevity I use blocks to make the Singleton examples easier; this is possible in iOS3.x, but it’s much more verbose.

Default Core Data templates get it wrong

Before I dive into any details I wanted to start with a bold statement:

Apple’s sample Core Data templates suck.

That isn’t to say that it isn’t valuable for Core Data beginners to get started, but it isn’t a good idea to use them verbatim as an optimal approach for designing an application around Core Data. This is due to the following reasons:

Application Delegate overloading

Your UIApplicationDelegate class should be there for one thing only: responding to application’s state changes. Overloading it to manage your Core Data stack is the wrong place to do things.

There are certain database-related operations that should be called from within your application delegate, such as performing a “save” when the application is about to terminate, but those are fairly minor cases that shouldn’t drive the entire design of your application.

Managed Object Model versioning

The way the NSManagedObjectModel is constructed in Apple’s templates assumes you only have one version of your object model. You’ll have to change this code around when you add another version later in the life of your application. You might as well start on the right foot and assume your application will mature and eventually grow into a second version of its object model.

The easiest way to create an NSManagedObjectModel, and the way it works in Apple’s templates, is with the following call:

[NSManagedObjectModel modelByMergingModels:nil];

This essentially tells Core Data to take all available object models included with your application’s [NSBundle mainBundle] and merges them together into one contiguous view. This blows up in your face however if you have multiple versions of the same object model, or if your managed object model lives somewhere other than your main bundle.

Instead you can construct your managed object model like so:

NSManagedObjectModel *objModel;
NSString *modelPath;
NSURL *modelURL;
modelPath = [bundle pathForResource:@"MyModel"
						     ofType:@"momd"];
modelURL = [NSURL fileURLWithPath:modelPath];
objModel = [[NSManagedObjectModel alloc]
			initWithContentsOfURL:modelURL];

This allows you to explicitly load the current version of your object model, potentially even in a separate bundle. Rarely will you need to merge multiple object models together, and if you do there are ways around that while still being able to explicitly point Core Data at the latest versions of them all.

Cumbersome Managed Object Context passing

The standard Core Data template assumes your NSManagedObjectContext will be passed from view-controller to view-controller manually. This is extremely cumbersome and is prone to error. It’s much easier to provide a centralized mechanism for getting at an object context.

I tend to create a central singleton that implements my Core Data stack, which provides a convenient property for accessing the main object context. This allows me to do something like the following:

NSFetchRequest *request;
// Configure the request
NSManagedObjectContext *context;
context = [DatabaseManager sharedInstance].mainObjectContext;
results = [context executeFetchRequest:request
								 error:nil];

Without having to pass the object context around explicitly you can gain access to your Core Data model wherever you need to.

Additionally, since NSManagedObjectContext objects aren’t thread-safe (and you should really have one context per running thread) you can create a convenience method for creating new object contexts without needing to reference your specific object model or persistent store every time.

SQLite file storage security

The default location for saving your SQLite database is in the Application Documents directory. This becomes a problem if you want to share documents your application creates with your user or to other applications (using UIFileSharingEnabled). These files should be saved in the <Application>/Library directory so they can be backed up, but not shared with the user.

Additionally the default implementation doesn’t enable encryption of your SQLite database file, which is simple enough to do and can be vital for the protection of your database content.  The iPhone 3GS and above has hardware-level encryption and supports varying levels of security. A single call enables extremely robust file protection features for files stored on disk, but only provides extra security if you ask for it.

Your MOM is in a Static Library!

All developers are inherently lazy and don’t want to do any unnecessary work. This is why we try to reuse as much of our code as possible. We do this by creating common classes that we can share not only between our own projects, but between each other. There are times that sharing individual files becomes a burden though, and you’d like to create some sort of reusable static library that can easily be linked into your project. I go so far as to create a separate static library target in my iOS applications, and anything not directly related to my application is created in this library.

Recently I tried to take this same approach with the Core Data implementation for a project of mine, and this is where I started to run into murky waters. The implementation classes for my various Core Data entities could easily be compiled into a static library, as well as the singleton class I use to manage my Core Data stack (persistent store, managed object model, etc). However this is all meaningless unless you have the Managed Object Model for your Core Data implementation, and accessing that from within a static library isn’t all that intuitive. There are ways to work around this however, though you have to make some tweaks to make it work.

The important thing to know about Core Data is that the Managed Object Model file (with a .mom extension which explains my “Your Mom” joke above) is created at compile-time by Xcode. This however isn’t source code, and can’t be directly stored in a static library. Additionally the default method for accessing your .mom file assumes it lives in your main bundle.

The simplest approach for working around this is to include a resource bundle along with your static library. By dragging your .xcdatamodeld directory into the “Compile Sources” section of your bundle, or set your custom bundle to be the target of your Core Data model when adding it to your project.

Once you have your bundle, you simply change your code that constructs your NSManagedObjectModel object to look in the new bundle instead.

NSString *bundlePath, *modelPath;
NSBundle *bundle;
NSURL *bundleURL;
NSManagedObjectModel *objModel;
bundlePath = [[NSBundle mainBundle]
					pathForResource:@"MyLibrary"
							 ofType:@"bundle"];
bundle = [NSBundle bundleWithPath:bundlePath];
modelPath = [bundle pathForResource:@"MyModel"
						     ofType:@"momd"];
modelURL = [NSURL fileURLWithPath:modelPath];
objModel = [[NSManagedObjectModel alloc]
			initWithContentsOfURL:modelURL];

Sample Implementation

When working on an update to myDrumPad I encountered many of the problems I describe above, especially since I needed to migrate my user’s databases to a new version of the object model. In addition to the updated database I also wanted to share my audio engine with another music-related app I’m designing, so my goals for this updated included:

1. Migrate the datamodel to a new version.
2. Unit test the migration of data from the old to the new version.
3. Move the datamodel into a static library.
4. Minimize the amount of boilerplate code that needed to reside in the application delegate class.
5. Allow these classes to be reused.

While I never got unit testing data migrations working, I did manage to accomplish my other problems.  In fact the Singleton class I created, DataManager, has already been reused in 4 other projects. So to get you started on the right foot, here’s an example of how you can start where Apple’s templates leave off. Simply add this singleton to an Xcode project, optionally create your own static library target and bundle, and tie all the ends together to create your own application.

I’ve written about building iOS applications with Hudson Jenkins, but until recently there hasn’t been a convenient way of getting those applications to your testers. Of course the most important part of your build output will be the app bundle you send to Apple’s iTunes Connect web interface, but throughout your development cycle you’ll want to test your app.  Sure you could build and deploy a debug build straight to your own personal device, but you get the most benefit from having other people beta test your app.

With recent releases of Xcode and the iOS SDK, Apple improved their AdHoc distribution support with two main enhancements:

1. Mobile provisioning files can now be embedded in the App’s IPA itself, meaning you don’t have to maintain and update separate .mobileprovision files separately;
2. A specially-formated manifest Plist file can be created that, when linked to properly, allows test devices to install new versions of your AdHoc app without needing to plug into a computer to sync the app using iTunes.

These improvements are huge, but require some changes to your build scripts and your Continuous Integration environment.  I’d like to show you how to do this in your own installations, and show you some options for how to distribute your apps to your testers.

Building IPAs properly

In the past, if you wanted to create an AdHoc distributable binary, you could either zip up the MyAppName.app bundle directory and mobile provisioning files separately, or you could attempt to create an IPA manually to fake-out iTunes. Getting this right was difficult however since the contents of the app directory are signed, and any changes (e.g. trying to include an embedded mobileprovision or iTunesArtwork file) would break the codesign.

With recent iOS SDK releases Apple added a “Build And Archive” menu that builds an IPA and archives it for later use. This is fairly nifty if you are a one-man shop and don’t practice Continuous Integration, but for the rest of us this just won’t cut it. However, some adventurous people dug through Xcode’s command-line build output to see just what was happening when the “Build And Archive” command was generating the IPA, and here’s what they found:

xcrun -sdk iphoneos PackageApplication \
    "path/to/build/MyApp.app" \
    -o "output/path/to/MyApp.ipa" \
    --sign "iPhone Distribution: My Company" \
    --embed "path/to/something.mobileprovision"

If you run that on the command-line, lo’ and behold, you can generate properly-signed IPAs to your heart’s content. But there’s more! The interesting thing about this command is that it takes both the codesign name and certificate file as arguments while generating your IPA.  There’s a subtlety to this that many people haven’t stumbled upon.  Here it goes:

No matter what provisioning profile you use within your Xcode project file to build your apps, you can re-sign them later in your Continuous Integration environment!

This is a powerful point that you can really take advantage of while setting up your build scripts. As mobile provisioning files change, you only need to ensure you perform the final IPA creation with the proper profile.

Adding a statement above to your build script is fairly straight-forward. Here is a snippet of code I use in my own build scripts:

. "$WORKSPACE/autobuild/build.config"
for config in $CONFIGURATIONS; do
    provfile=$(eval echo \$`echo ProvisionFile$config`)
    codesign=$(eval echo \$`echo Codesign$config`)
    cert="$WORKSPACE/autobuild/$provfile"
    fileprefix="$JOB_NAME-$BUILD_NUMBER-$config";
    ipaname="$fileprefix.ipa"
    xcodebuild -activetarget -configuration $config build || failed build;
    app_path=$(ls -d build/$config-iphoneos/*.app)
    xcrun -sdk iphoneos PackageApplication \
        "$app_path" -o "$OUTPUT/$ipaname" \
        --sign "$codesign" --embed "$cert"
done

I then place some simple configuration into the “build.config” file, that looks like so:

CONFIGURATIONS="Release Distribution"
ProvisionFileDistribution=AdHocProfile.mobileprovision
CodesignDistribution="iPhone Distribution: Decaf Ninja Software"
ProvisionFileRelease=AppStoreProfile.mobileprovision
CodesignRelease="iPhone Distribution: Decaf Ninja Software"
OTAURL="http://path/to/my/beta/site"
OTASmallIcon=appstore/Icon-57.png
OTALargeIcon=appstore/Icon-512.png

This is used by the script to determine, at runtime and on a per-artifact basis, which codesign and mobile provision file should be used.  This means that if your provisioning profile changes (if you add or remove devices from an AdHoc profile, for example) you only have to check the new provisioning file into your SCM, submit to Jenkins, and wait for a new build. (Note: The settings starting with “OTA” will be used in the next section)

The great thing I discovered is that Apple’s iTunes Connect web interface accepts properly-signed IPA files as your final app submission, as long as they’re signed with your App Store mobile provisioning profile.  This means if you build an IPA for both AdHoc and App Store configurations, that’s all you need.

Over-The-Air Distribution

Once you have an IPA generated with an embedded mobile provision profile, you can start distributing your apps to beta testers much easier. In my experience it’s difficult to find beta testers who will diligently put your app through its paces thoroughly enough to truly test your application’s limits. It makes matters even harder when you require users to: a) download an IPA, b) maybe download a new mobile provision profile, c) drag them into iTunes (in the right order), and d) sync their phone.  You’ll be lucky at that point if they actually have the time to launch your app.

There are a few 3rd-party solutions (such as TestFlight or Hockey) that handle the nitty-gritty of getting Over-The-Air installs working to manage your beta testers and to push updates out to them, but most of the features they provide can be built yourself simply enough just by adding a little bit of creativity to your Jenkins build scripts. I’m going to work backwards, since that might be easier to follow along with.

Send email notifications to your testers

Sample "Build Success" email that beta testers receive

The screenshot to the right shows a sample email that my beta testers and I receive when a new build is successfully compiled. I use the Jenkins Email-ext plugin to customize my build result emails, and enable HTML output so that I can include custom links in it.  Using this plugin allows you to easily send separate messages on success, failure, etc, and provides a number of variables/tags that can provide additional context to your testers. For example, I use the “$CHANGES_SINCE_LAST_SUCCESS” tag to show my testers what’s changed since the last build, using my SCM commit log messages.

Apple uses a special URL scheme to indicate that an app install should be performed.  In the email screenshot, you’ll see that I have a link titled “Install beta build #32″. This is link to the following URL:

itms-services://?action=download-manifest&url=http://url/to/app-manifest.plist

Clicking an itms-services:// URL results in this prompt

Clicking that link from an iOS device will tell the OS to download the application update manifest and, if it’s properly formulated, will prompt the user if they want to install the app.

Assuming the manifest is valid and the user taps “Install”, it behaves exactly as if the user purchased the app from the App Store. The device switches back to the home screen, and begins downloading the application.

Note: If your user’s device UDID isn’t included in the embedded mobile provision profile, the user will get a vague error about being unable to install the application.

Generating the update manifest

All of this assumes you’ve generated your update manifest to begin with. The format is pretty verbose, and has a few hard requirements for the information you need to supply. But honestly these are files you should have available to begin with. They include:

• Your company name
• The name of the application
• The version number that you want to report for this app
• Your 57×57 app icon
• Your 512×512 app icon

There is some other information you can optionally supply, but that is the minimum you need. All of those files need to be available on a web server the user will have access to. So if your Jenkins server is password protected, you might want to archive those files elsewhere.  For my installation I use the Jenkins SCP plugin to archive the relevant files to a public “Beta” section of my website and reference the files from my app manifest.

I generate my app manifest from my build scripts, which looks something like this:

mkdir $OUTPUT/$fileprefix
cp $WORKSPACE/$OTASmallIcon $OUTPUT/$fileprefix/Icon-57.png
cp $WORKSPACE/$OTALargeIcon $OUTPUT/$fileprefix/Icon-512.png
info_plist=$(ls *Info.plist | sed -e 's/\.plist//')
bundle_version=$(defaults read $WORKSPACE/$info_plist CFBundleShortVersionString)
bundle_id=$(defaults read $WORKSPACE/$info_plist CFBundleIdentifier)
cat << EOF > $OUTPUT/$otaname
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>items</key>
   <array>
       <dict>
           <key>assets</key>
           <array>
               <dict>
                   <key>kind</key>
                   <string>software-package</string>
                   <key>url</key>
                   <string>$OTAURL/$ipaname</string>
               </dict>
               <dict>
                   <key>kind</key>
                   <string>display-image</string>
                   <key>needs-shine</key>
                   <true/>
                   <key>url</key>
                   <string>$OTAURL/output/$fileprefix/Icon-57.png</string>
               </dict>
               <dict>
                   <key>kind</key>
                   <string>full-size-image</string>
                   <key>needs-shine</key>
                   <true/>
                   <key>url</key>
                   <string>$OTAURL/output/$fileprefix/Icon-512.png</string>
               </dict>
           </array>
           <key>metadata</key>
           <dict>
               <key>bundle-identifier</key>
               <string>$bundle_id</string>
               <key>bundle-version</key>
               <string>$bundle_version #$BUILD_NUMBER</string>
               <key>kind</key>
               <string>software</string>
               <key>title</key>
               <string>$OTATitle</string>
               <key>subtitle</key>
               <string>$OTASubtitle</string>
           </dict>
       </dict>
   </array>
</dict>
</plist>
EOF

The contents of the “output” directory are subsequently SCP’d to my beta server, and this manifest file is referenced in my Jenkins build success email.

The last step is to maintain an email mailing list of your beta testers and configure your Jenkins build job to notify that list when a successful build is finished. Your testers are then notified the moment any new changes are available, and with a single tap they can download and update to the latest build from anywhere. And your testers can see, based on your SCM changelog, what features may have changed and areas where they might need to focus their test efforts.

If you have any questions about this technique, please don’t hesitate to leave comments below. I use this for my personal iOS application builds, as well as at work, and we’ve had great success with it, especially since it doesn’t require the installation or configuration of any extra 3rd-party software.

This is the fourth in a series of posts I’m writing on animating iOS interfaces using Core Animation. In the first post I created a planetary orbit demo using nested CALayer objects. The second post showed how to dress up a UI by animating an image. The third post shows how you can trigger animations in response to button actions.

This post will show how you can create the beginnings of a full game using Core Animation combined with CAShapeLayer and UIBezierPath objects.

Read on to see more

Race Track sample

Race Track demo

This is perhaps my favorite sample, if only because it not only looks neat but shows how you can build an actual game using nothing but Core Animation. This sample shows how you can construct a car race track on the screen using CAShapeLayer objects, and can then animate an image of a car along that track. This sample’s code is broken down into five main blocks:

1. Defining the path the car should follow;
2. Drawing the black line that defines the track;
3. Drawing the white dashed center-line of the track;
4. Creating the layer defining the car;
5. Animating the car along the path.

Luckily there are some handy routines for defining paths in UIKit. Core Animation deals with paths as CGPathRef objects, but luckily there is the UIBezierPath class that simplifies the process of drawing and creating a path object.

UIBezierPath *trackPath = [UIBezierPath bezierPath];
[trackPath moveToPoint:CGPointMake(160, 25)];
// ... Path drawing operations ...

I’ve omitted the actual path drawing code because it’s pretty verbose, but you can download the source code and sift through it yourself. Once the path has been created, you can use it as many times as you like. First we create a layer defining the black shape of the track.

CAShapeLayer *racetrack = [CAShapeLayer layer];
racetrack.path = trackPath.CGPath;
racetrack.strokeColor = [UIColor blackColor].CGColor;
racetrack.fillColor = [UIColor clearColor].CGColor;
racetrack.lineWidth = 30.0;
[self.view.layer addSublayer:racetrack];

The CAShapeLayer class isn’t used often enough I find; it is extremely powerful, and reduces the amount of processing the device has to do. Core Animation is fairly low-level, so instead of assigning the UIBezierPath object directly, you use the CGPath accessor that conveniently creates the low-level struct that it can understand. We specify the colors that we want the outline (the “Stroke” of the path) and the filled area to be, also using low-level CGColor objects.

We also specify a fairly wide width of 30 points and then add this layer to our main view’s CALayer object. An important thing to note is that the stroke color fills in on either side of the path, so the coordinates our path describes has 15 points of black on either side of it.

CAShapeLayer *centerline = [CAShapeLayer layer];
centerline.path = trackPath.CGPath;
centerline.strokeColor = [UIColor whiteColor].CGColor;
centerline.fillColor = [UIColor clearColor].CGColor;
centerline.lineWidth = 2.0;
centerline.lineDashPattern = [NSArray arrayWithObjects:
                              [NSNumber numberWithInt:6],
                              [NSNumber numberWithInt:2],
                              nil];
[self.view.layer addSublayer:centerline];

For the center-line of the racetrack, we create another CAShapeLayer object, filling out its properties similarly to the previous layer. In this case however we’re using a white stroke color, we’re using a much smaller line width, and we also specify a “Line Dash Pattern”.

This pattern describes where we want the path to be stroked, and where we want it to skip drawing the outline. You specify it in groupings of two, so for every 6 points of space along the line, there will be 2 points of blank space. This gives us a very nice dashed pattern.

One thing you may want to take note of is that we’re using the same UIBezierPath object to create the second layer. You can reuse that path as many times as you like.

CALayer *car = [CALayer layer];
car.bounds = CGRectMake(0, 0, 44.0, 20.0);
car.position = CGPointMake(160, 25);
car.contents = (id)([UIImage imageNamed:@"carmodel.png"].CGImage);
[self.view.layer addSublayer:car];

Next we create a regular CALayer for the image of our car. Notice how we assign the image to the layer’s contents? By using the CGImage property of our UIImage, it passes the content directly to the layer in a way it can understand, greatly reducing the amount of boilerplate code we need.

We also make sure to add the layer at the exact point where the path starts, so that the car lines up with the track.

CAKeyframeAnimation *anim = [CAKeyframeAnimation animationWithKeyPath:@"position"];
anim.path = trackPath.CGPath;
anim.rotationMode = kCAAnimationRotateAuto;
anim.repeatCount = HUGE_VALF;
anim.duration = 8.0;
[car addAnimation:anim forKey:@"race"];

Finally we create a CAKeyframeAnimation object on the “position” property. You might remember from my previous post about creating button action animations that a keyframe animation allows you to perform an animation along a path. In this case we’re creating a much more complicated path, but we’re using the exact same path used to create our CAShapeLayer objects above.

As shown in previous examples, we set the repeat count to infinite and a fairly long duration. But the important property is the rotationMode. By setting this to one of two potential values, the CAKeyframeAnimation object will automatically rotate the target layer along the path for you. If you’ve ever seen the game Harbor Master where you direct little boats along a path to their harbor? Or Flight Control HD where you direct planes to their airports. You can reproduce these same effects using simple CAKeyframeAnimation objects.

Finally, when the animation is added to the car, you see the effect shown in the video below.

I have plans to write more posts on Core Animation in the future, but for now this is all I’ve got. Feel free to download the sample project and pick through the code yourself. And don’t forget to read the previous samples showing Orbiting Planets, Floating Clouds and Button Actions.

CALayerAnimTest.zip – Xcode Project