Justin Voss

Skip Tunes for Mac

2012-02-13T00:00:00-06:00

Last week, my latest client project went live on the App Store. I’m thrilled to (somewhat belatedly) announce Skip Tunes, a menu bar app for controlling iTunes, Rdio, and Spotify. It’s on sale right now for just $0.99 on the Mac App Store.

Greg Dougherty, my client, has done a great job getting press attention for the app. So far, it’s been mentioned on The Unofficial Apple Weblog, CNET, Lifehacker, Cult of Mac, Macworld (3.5 out of 5 Mice) and a few other websites. Not long after launching, it even climbed to the #1 Music app in nine different countries!

Behind the Scenes

Warning: serious technical details ahead.

Chameleon

When I started working on the custom UI for the app, I tried to use the AppKit collection of classes: NSView, NSButton, NSTextField, and friends. It didn’t take long before I was really frustrated with how hard it was to customize the appearance of these controls. For example, on iOS it’s easy to use a custom image as the background of a UIButton, you just call setBackgroundImage:forState:. Using that method, you can even specify two different images: one to use normally, and another to use when the control is actually being pressed.

Getting the same thing done with NSButton is not so easy.

The most straightfoward way to get a custom image is to subclass NSButtonCell and override it’s drawBezelWithFrame:inView: method, which is not at all obvious if you’re not familiar with the way NSControl uses cells for drawing. Then, for each button, you have to instruct it to use your custom cell class instead of the default class. To show a different image when the button is pressed, your implementation of that cell method has to inspect the isHighlighted property to see if the user is holding down the mouse button. When drawing that NSImage, you need to make sure you use the right drawing method that respects the flipped or non-flipped setting for the image and the graphics context.

None of the above is rocket science, but it’s a lot of work for what seems like a really easy task. (Kudos to the UIKit team for taking the opportunity to rethink and clean up these interfaces.)

Instead of wrangling all this myself, I took a shortcut and used an open source framework called Chameleon.

Created by The Iconfactory, Chameleon is a re-implementation of a big chunk of UIKit on top of AppKit. In a nutshell, it lets developers write iOS code that runs on OS X.

Chameleon really shines when you want to use the same code to produce both an iOS and a Mac app, but in this case it was worth it just to use the better APIs from UIKit.

I was able to write most of the Skip Tunes user interface using UIView, UIButton, UILabel, and even UIViewController in addition to AppKit classes like NSStatusItem and NSWorkspace.

If I had to do it over again, I think I would still use Chameleon, although I think I would try a bit harder to get AppKit to behave. I generally don’t like using cross-platform toolkits, but in this case the result was good enough to make up for it.

Scripting Bridge

The job of actually controlling and inspecting the media players falls onto AppleScript. Luckily, all three apps have similar scripting interfaces, so it wasn’t hard to create an abstraction layer on top of them.

Along the way, I learned a couple of neat tricks about Scriping Bridge, which is an API for using AppleScript from Objective-C.

To generate header files for each app, I used two command line tools: sdef and sdp. Together, they take the scripting definition for an app and output an Objective-C .h file that you can include in your app. Here’s how I generated the header for iTunes:

sdef /Applications/iTunes.app/ | sdp -fh --basename iTunes -o ~/Desktop/iTunes.h

The basename is used to generate some of the object names in that header file. In the above example, the iTunes.h file contains classes named iTunesApplication, iTunesPlaylist, etc.

I also learned that the SBApplication object, which represents your app’s connection to the scriptable app, can have a delegate that it reports errors to. This was really helpful during development, because I could see where things were going wrong.

Distributed Notifications

If your app needs to respond to the behaviour of other apps, the way that Skip Tunes needs to respond to the media player starting, stopping, or changing tracks, you need to see if NSDistributedNotificationCenter has the information you need. Some apps will broadcast notifications over this channel about their state, which can save your app from doing nasty polling.

For example, whenever the state of playback changes, iTunes publishes a com.apple.iTunes.playerInfo notification on this notification center. Instead of checking iTunes’s state over Scripting Bridge every second, I just register for this notification and wait to hear back.

If you go down this route, though, make sure to listen to NSWorkspace notifications, too, since opening and closing apps doesn’t usually send those state change notifications.

Go Get It!

You’re still here? Go buy Skip Tunes, already!

2011 by the Numbers

2011-12-31T00:00:00-06:00

Visits to justinvoss.com: 915

Tweets by @justinvoss: approx. 600

Visits to justinvoss.com from Reddit: 374

Money made on the iOS App Store: $207.87

Albums on vinyl acquired: 9

Books read in The Dark Tower series: 7

Video games completed: 6

Uncharted 1-3
Portal 2
Half-Life 2 and HL2: Episode 1

Google Reader subscribers for justinvoss.com (including me): 5

Apps released: 4

May - Kowabunga
June - Herograph
September - Simple Desktops
November - CARFAX Reports

Transmissions repaired: 1 (details)

Marriages: 1 :)

Discover Django Servers with Bonjour

2011-12-12T00:00:00-06:00

Running a Django server that provides content to an iOS client is a combination that’s worked great for the apps I’ve worked on. Getting everything talking to each other is easy as long as both processes are running on the same machine: just run the Django server as usual, then run the iOS app in the simulator and point it to localhost.

Some iOS features, though, are hard to test in the simulator. Barcode scanning, accelerometer tracking, and other hardware features can only be tested on a real device. But running the app on a device means you can’t just say localhost and expect to connect to your laptop; you’ll need a way to reference your development machine without using the IP address, which changes too often to be useful.

This is exactly what Bonjour is for. Bonjour is Apple’s implementation of “zero configuation networking,” which lets apps publish and browse network services.

Finding a Server the Easy Way

Among other things, Bonjour gives your machine a hostname in the .local domain, which stays constant even as your IP changes.

You can find your machine’s Bonjour hostname in the Sharing pane of System Preferences.

You can see that my laptop goes by the name justin-macbook-pro.local. In my iPhone app, instead of connecting to localhost:8000, I’ll instead connect to justin-macbook-pro.local:8000. There is no Step 2; it’s really that easy! No matter how many times my laptop changes it’s IP address, that hostname will always resolve to the right machine. Now I can run my iPhone app on a real device and it’s almost as easy as when everything was on localhost (you do have to remember to tell Django to listen on all interfaces: just say manage.py runserver 0.0.0.0:8000).

There’s an obvious downside, though: now my machine name is in the code. What if I’m not the only developer on the project? Is everyone going to maintain their own version of the configuration, with their own hostname in place of mine? That would work, but it just feels icky, to use a technical term.

What if we didn’t have to hard-code anything at all, and the iPhone app could discover the server totally automatically?

Finding a Server the Over-Engineered Way

Let’s publish our Django server as a full-fledged Bonjour service, and then write some iOS code to browse for it.

Publishing

Apple has some Objective-C APIs for publishing services, and there’s at least one Python library that claims to do the same, but there’s an even easier way: a commandline tool called dns-sd (read the man page for details). In a nutshell, invoking dns-sd follows this format:

dns-sd -R <name> <type> <domain> <port>

Breaking it down a piece at a time:

The -R means we want to register (i.e., publish) a service.
The name should be a human-readable description of this instance of the service. For example, an iTunes library uses a name like “Justin’s Library”.
The type is a Bonjour service type. This follows a format that puts the scheme first and the network protocol second. For example, a web server is of the type _http._tcp. You can and should make up your own types, like _myapp._tcp.
The domain is what Bonjour domain to publish this service to. In general, you almost always want to use local.
Finally, the port is what port your app is listening for connections on. For Django, this is usually 8000.

So, our hypothetical Django server would be published like so:

dns-sd -R "App API on Justin's MacBook" _myapp._tcp local 8000

To make life easier, I’ve written a Python script called runserver-bonjour that will both run your Django project and publish it using Bonjour.

Side Note: Bonjour Types

A Bonjour type, like _http._tcp, is used to filter for specific services. Unless you’re trying to be a drop-in replacement for something else, your app should have it’s own unique type. In these examples, I’m using _myapp._tcp. There’s a list of all registered types that has lots of examples.

You might be thinking, “Wait, aren’t we just an HTTP server? Why not use _http._tcp?” We don’t want to do that, because the fact that our service uses HTTP as a transport should be considered an implementation detail. The _http._tcp type has a very specific use: it’s for servers that deliver web pages intended to be displayed in a browser. That’s not what our server does: it’s an API, not web pages, so that’s not the right type for us.

To use a real example, when you enable iTunes music sharing, your copy of iTunes starts up an embedded web server: the music sharing is actually done over HTTP. But iTunes uses the Bonjour type _daap._tcp to distinguish itself from other HTTP servers. Your app should use the same strategy.

Browsing

Finding a Bonjour service isn’t too hard, but it does involve two layers of delegation, which can make the code hard to follow. There are two phases: in the first, we’ll browse for any services that match the type we want (_myapp._tcp); then, we’ll pick a single service and resolve it, which will tell us the hostname and port to connect to.

To browse for services, you need an NSNetServiceBrowser. Give it a delegate, then tell it what type of services you want (FYI, all these code samples are using ARC).

self.serviceBrowser = [NSNetServiceBrowser new];
self.serviceBrowser.delegate = self;
[self.serviceBrowser searchForServicesOfType:@"_myapp._tcp" inDomain:@""];

Passing in an empty string for the domain means you want the default domain, local.

As the service browser finds services, it notifies the delegate. It calls the delegate once per service, so if you want to do something with the whole collection of them, you need to maintain a list yourself.

- (void)netServiceBrowser:(NSNetServiceBrowser *)aNetServiceBrowser 
           didFindService:(NSNetService *)aNetService 
               moreComing:(BOOL)moreComing
{
    // __foundServices is an NSMutableArray
    [__foundServices addObject:aNetService];
    
    if (!moreComing) {
        [self resolveFirstService];
    }
}

The moreComing parameter is a hint that there may or may not be more pending calls to this method. Apple recommends using this flag to determine when to update your UI, but in this case I’m using it to decide when to stop browsing and start resolving.

- (void)resolveFirstService
{
    NSNetService *service = [__foundServices objectAtIndex:0];
    service.delegate = self;
    [service resolveWithTimeout:10.0];
}

In some apps, you might want to let the user choose which service to use. For our purposes, we can assume there’s usually only one service, so we’ll just grab the first one and resolve it. This is where the second level of delegation happens: the service needs a delegate to notify when it finishes resolving.

- (void)netServiceDidResolveAddress:(NSNetService *)sender
{
    NSLog(@"Resolved service with hostname=%@, port=%d", sender.hostName, sender.port);
}

At this point, you have all the info you need to connect to this service. I just take the hostname and port, slap them together with +[NSString stringWithFormat:], then create an NSURL from that.

I put together a class to handle the details for me, called RBServerLocator (The RB prefix is to match runserver-bonjour). Using it is as easy as specifying the type and providing a completion block that takes a resolved service. There’s even a category on NSNetService to create an HTTP URL for you.

[[RBServerLocator sharedLocator] locateServerMatchingType:@"_myapp._tcp"
                                               completion:^(NSNetService *service) {
                                                   NSLog(@"found server: %@", [service RBResolvedURL]);
                                               }];

Smoothing Data with Low-Pass Filters

2011-11-07T00:00:00-06:00

I should have paid more attention in my math classes. There’s actually a lot of neat things you can do with a good working knowledge of math: I’ve started to go back over the material I should have learned in college and I’m trying to apply it to programming.

One handy trick is an algorithm called a low-pass filter. This basically takes a stream of data and filters out everything but the low-frequency signal. Effectively, this “smooths” out the data by taking out the jittery, high-frequency noise.

Like I said before, my math skills are weak, but looking at the algorithmic implementation on Wikipedia it seems like it’s basically a weighted average: some of the data is from the previously filtered value, and some of the data is from the raw stream. Here’s my breakdown of what each piece means:

The alpha value determines exactly how much weight to give the previous data vs the raw data.
The dt is how much time elapsed between samples.
I don’t totally understand what the RC value is for, but by playing with it’s value it’s possible to control the aggressiveness of the filter: bigger values mean smoother output.

Demo Time: Fun with the Accelerometer

So, how can we apply this to something useful?

If you haven’t already seen GitHub’s 404 page, go take a look: make sure you move your mouse around the page. See how the images move around in parallax? If you visit the same page on your smartphone, it can even use the accelerometer in your device to make the images move.

I thought it would be neat to replicate the effect in a native iOS app. Grabbing data from the accelerometer and shifting the views around is pretty easy, but the result is poor. The accelerometer is way too sensitive to small movements, and it makes the app feel over-caffeinated.

Low-pass filtering to the rescue!

Here’s a before-and-after video. Each version of the app is using the same recorded accelerometer data, running in a 10-second loop. The version on the left is using the raw data, while the version on the right is using data run through a low-pass filter.

The results should speak for themselves: the filtered data is a little slower to react, but moves smoothly and deliberately. The raw data jumps and twitches too much for comfort.

Show Me the Code!

First things first, let’s get some accelerometer data. I put this in my view controller’s viewWillAppear: method.

NSOperationQueue *accelerometerQueue = [NSOperationQueue mainQueue];
self.motionManager = [[CMMotionManager alloc] init];
[self.motionManager setAccelerometerUpdateInterval:(1.0 / 20)];
[self.motionManager startAccelerometerUpdatesToQueue:accelerometerQueue withHandler:^(CMAccelerometerData *data, NSError *error) {
    [self updateViewsWithFilteredAcceleration:data.acceleration];
}];

The updateViewsWithFilteredAcceleration: does the actual filtering.

- (void)updateViewsWithFilteredAcceleration:(CMAcceleration)acceleration
{
    static CGFloat x0 = 0;
    static CGFloat y0 = 0;
    
    const NSTimeInterval dt = (1.0 / 20);
    const double RC = 0.3;
    const double alpha = dt / (RC + dt);
    
    CMAcceleration smoothed;
    smoothed.x = (alpha * acceleration.x) + (1.0 - alpha) * x0;
    smoothed.y = (alpha * acceleration.y) + (1.0 - alpha) * y0;
    
    [self updateViewsWithAcceleration:smoothed];
    
    x0 = smoothed.x;
    y0 = smoothed.y;
}

And finally, the updateViewsWithAcceleration: method actually moves the center points of the views.

- (void)updateViewsWithAcceleration:(CMAcceleration)acceleration;
{
    CGPoint center = self.view.center;
    const CGFloat maxOffset = 200;
    
    CGPoint frontCenter  = CGPointMake(center.x - (+1.0 * maxOffset * acceleration.x),
                                       center.y + (+1.0 * maxOffset * acceleration.y));

    CGPoint middleCenter = CGPointMake(center.x - (+0.2 * maxOffset * acceleration.x),
                                       center.y + (+0.2 * maxOffset * acceleration.y));
    
    CGPoint backCenter   = CGPointMake(center.x - (-1.0 * maxOffset * acceleration.x),
                                       center.y + (-1.0 * maxOffset * acceleration.y));    
    
    self.frontView.center = frontCenter;
    self.middleView.center = middleCenter;
    self.backView.center = backCenter;
}

Pretty simple, right? The math isn’t that bad, and it gives us a great result. This is just a small example of what real math can do for your app. In the next few months, I’ll try to do some more posts about using advanced math and statistics to make more intelligent systems.

If anyone’s interested, I can do a follow-up post about how I recorded the accelerometer for playback later.

Custom UIFont Gotchas

2011-09-23T00:00:00-05:00

Custom fonts are fun! Getting custom fonts to work with UIFont isn’t always as much fun. The tricky part that gets me every time is getting the font name right: it has little or nothing to do with the filename of the font. How am I supposed to figure out what name to use?! It turns out the developers at Apple are way ahead of me: the easiest way to get the name right it just ask the UIFont class what names it knows.

Thanks to Richard Warrender’s article about custom fonts on iOS, I discovered the awesome +[UIFont familyNames] and +[UIFont fontNamesForFamilyName:] methods. The first returns a list of every font family the system recognizes. The second takes one of those family names and returns a list of font names associated with it. The font name is the one you should give to +[UIFont fontWithName:size:] to get your custom font.

You still have to do the regular “add your font file to the project and specify it in your Info.plist” dance, but that’s not the hard part.

Hopefully this saves you some time and frustration!

Simple Desktops for Mac

2011-09-06T00:00:00-05:00

I’m pumped to finally share what I’ve been working on for the Mac: Simple Desktops.

This handy little app can change your desktop background automatically or on-demand, and it pulls all of it’s content from SimpleDesktops.com, impeccably curated by Tom Watson.

Big props go out to Greg Aker for server monkeying and Louis Harboe for the smashing icon.

Buy it, rate it, tell your friends, email me with any feedback.

Creating and Consuming Data Sources in UIKit

2011-09-02T00:00:00-05:00

By popular demand in the comments from last week’s article on delegates, this week’s article is about data sources. I’ll talk about what a data source is, why UIKit uses them, and how you can write your own views that consume data sources.

What is A Data Source?

A data source is a species of delegate. It’s a separate object that provides data to another according to a defined standard. That standard can be formal, like an Objective-C protocol, but doesn’t need to be.

The most common UIKit class that consumes data sources is UITableView. Typically, the view controller of a particular screen will be both the delegate and the data source for a UITableView that takes up most or all of screen. This pattern is so common, in fact, that Apple includes a view controller class called UITableViewController that does all this wiring for you!

To provide data to the table view, the data source implements at least these methods:

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section;
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath;

The first method, tableView:numberOfRowsInSection:, is called by the table view to determine how many rows are in the section with the given index. By default, a table view has only one section, so in the simplest case the section argument will always be zero.¹ The data source should consult whatever data it has and return the number of rows the table view should display.

The second method, tableView:cellForRowAtIndexPath:, is how the table view will determine what content to display for a particular row in the table. The object returned here is an instance of UITableViewCell, which is a fully-fledged UIView subclass. The indexPath argument is essentially a list of integers that describes the section and row that the table view needs a cell for. To get the individual values, call the section and row methods:²

NSUInteger section = [indexPath section];
NSUInteger row = [indexPath row];

The actual implementation of tableView:cellForRowAtIndexPath: is specific to the data you want to display. As an extremely simple example, here’s what it might look like if you wanted a plain table view and your data is simply an array of strings, in the names attribute.

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    static NSString *CellIdentifier = @"Cell";
    
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    if (cell == nil) {
        cell = [[[UITableViewCell alloc] initWithFrame:CGRectZero reuseIdentifier:CellIdentifier] autorelease];
    }
    
    NSString *currentName = [self.names objectAtIndex:indexPath.row]
    cell.textLabel.text = currentName;
    
    return cell;
}

The business with dequeueReusableCellWithIdentifier: is a caching mechanism that UITableView uses to avoid creating more cells than is strictly necessary. Since only a handful of cells will ever be on-screen at any given instant, there’s no reason to create any more than a handful of cell objects. As soon as a cell moves off-screen, it becomes reusable as a cell that’s about to come on-screen.

The Reason for Data Sources

You might be thinking that this seems like overkill. Why create a separate object and two separate methods for controlling some cells in a list?

The biggest reason is performance. For a small amount of data, the benefits of using the data source pattern won’t be clear. But look at how many songs are in your iTunes library on your iDevice (you can see the total in Settings > General > About). Right now, I have 1,297 songs on my iPhone. When I tap on the Songs tab in the iPod app, only about eight rows are on-screen at a time. If every song was loaded in-memory, 1,289 of them would be wasted space because the user can’t see them.

Instead, the only pieces of information that need to be calculated are:

How many total songs are there?
What are the first eight?

The total is an easily-cached number, since the music library on iOS is relatively static, and the first few rows are quick to look up in SQLite.³

Besides the memory usage issues, it may be that not all of the data is known at the time that the table view needs to be displayed. If each row has an image that needs to be downloaded from a web server, you obviously may not want to fetch all the images up front: it would be wiser to wait until that particular row is on-screen before starting the download.

Obviously, not every view in UIKit uses data sources: simple views like UIImageView just have a property that represents the data they need to display. Even a view as complex as MKMapView doesn’t use a data source: each pin on the map is added manually with addAnnotation: or in bulk by setting the annotations property.⁴ The right time to reach for the data source pattern is when performance is an issue and the data lends itself well to being loaded piece-by-piece.

Besides performance, separating the presentation of the data from the mechanics of loading it is just good engineering. The view only needs to know how to display the data. Where it comes from and how much of it is loaded is outside the scope of that the user interface needs to worry about.

Consuming Data Sources

While writing your app, you may want to create a view that has the same constraints as a table view: it needs to potentially display a lot of data, but only a fraction of it will be needed at any given moment. Sounds like a job for a data source!

The first step is to back away from the code and head for the whiteboard. Figure out your strategy for how the view will interact with the data source; this will be different for every situation. When Kyle and I wrote the grid view in Kowabunga, called LOGridView, we decided to use a data source because we knew that at some point we would want multiple pages of icons. Our strategy was to create a simplified version of the UITableView data source. The two methods are:

- (NSUInteger)numberOfCellsInGridView:(LOGridView *)gridView;
- (LOGridViewCell *)gridView:(LOGridView *)gridView cellForObjectAtIndex:(NSUInteger)index;

The similarity between this and a table view data source should be obvious. The first method alone is enough for the grid view to calculate how many pages of icons will be needed: it just divides the total by twelve, rounded up.

As each page of icons comes on-screen, the grid view asks the data source for more cells. The first page asks for cells 0-11, the second pages asks for cells 12-23, etc.

After the grid view has been put on-screen and the data source is wired up, we call reloadData on the grid view to start laying out the grid. Each page in the view is an instance of LOGridViewPage, which is a private class that LOGridView uses to organize the cells. Each page has it’s own reloadData method, which is called on each page as it’s displayed:

// LOGridViewPage.m

- (void)reloadData
{
    // remove all the pre-existing cells
    [__cells makeObjectsPerformSelector:@selector(removeFromSuperview)];
    [__cells removeAllObjects];
    
    if(__cells == nil) {
        __cells = [[NSMutableArray alloc] initWithCapacity:(self.endIndex - self.startIndex)];
    }
    
    for(NSUInteger index = self.startIndex; index < self.endIndex; index++) {

        LOGridViewCell *cell = [self.dataSource gridView:self.gridView cellForObjectAtIndex:index];
        cell.frame = [self frameForCellAtIndex:index];
  
        UITapGestureRecognizer *gesture = [[[UITapGestureRecognizer alloc] initWithTarget:self
                                                                                   action:@selector(cellWasTapped:)] autorelease];
        [cell addGestureRecognizer:gesture];
        
        [__cells addObject:cell];
        
        [self addSubview:cell];		
    }
}

The heart of the method is the loop, where we load only the cells we need for this particular page. Each page has attributes for the grid view, the data source, and the start and end indices, so it has enough information to build up its grid of icons.

Your view will need a similar method, although the way you determine what to display and how you ask for it will be different. Maybe instead of discrete pages, like Kowabunga, your app has a more fluid layout like UITableView. In that case, you may need to calculate the start and end indices based on what’s on-screen.

In general, you’ll need to understand both how the data is retrieved and how it’s displayed before you can determine the right way to coordinate the two.

Until Next Time

That’s it for this week. Leave a comment below if I glossed over any details or made any mistakes (as if that ever happens…)

Let me know what you want to read about next week! I might change gears and talk about a non-Cocoa topic, like Django or Coffeescript. It’s up to you!

If you need to have more than one section, the numberOfSectionsInTableView: will let you control how many are displayed. The tableView:numberOfRowsInSection: will be called once for each section.↩
The section and row methods actually aren’t in the default implementation of NSIndexPath: they’re added by a UIKit category. These two helper methods are just wrappers around the indexAtPosition: method.↩
That’s assuming, of course, that the library data is in a SQLite database. It very well may not be, I don’t know. The data in your own apps probably will be, since that’s one of the storage backends Core Data uses.↩
According to Apple’s documentation, you should add all the annotations at once, even if they’re not on-screen. As the user moves the map around, the map view will notify the delegate and ask it to create the pin views as-needed. So you could consider this a hybrid model of delegation and using a data source.↩

Talking About Fabric at CoMoRichWeb

2011-09-01T00:00:00-05:00

Last week, Greg Aker and I gave a talk at CoMoRichWeb about Fabric, a Python tool for automating sysadmin tasks over SSH. This is the first time at Comorichweb that we had someone record video, (thank you Robert Boyd) so enjoy the talk below.

Fabric - Justin Voss & Greg Aker from CoMoRichWeb on Vimeo.

Notes

The Gist I referred to is my Example Fabric and Cuisine Scripts.
Get Cuisine on GitHub.

Intro to Delegation - Core Location and Address Book UI

2011-08-26T00:00:00-05:00

In my article last week about target-action, I mentioned the delegate pattern as another common pattern in Cocoa. Apple’s libraries make heavy use of delegation so you can reuse their code without needing to subclass the provided classes.

To illustrate how to implement delegates, I’ll talk briefly about both the Core Location and Address Book frameworks that are included in the iOS SDK.

What is a Delegate?

A delegate is a helper object that can react to or control events happening in another object. For example, a UITableView object notifies it’s delegate whenever the user taps on a row in the table, asks it’s delegate what height to use for each row, and informs the delegate when cells are edited.¹

Unlike the target-action pattern, the delegate doesn’t get to choose it’s own method names: they’re defined by the class that uses it. Often the delegate is expected to implement more than one method in order to have the most control over the other object. A common pattern is to have one method for successful completion of a task, and another method for failure.

APIs that rely on hardware or the network often use delegation as way to provide asynchronous responses. When using the Core Location framework, your code may start a request for GPS data, but the chip needs a while to warm up and connect to the satellites. Instead of blocking or polling the hardware, your code provides delegate methods that will be notified when the location data is ready to be used.

- (void)viewDidAppear:(BOOL)animated
{
  CLLocationManager *locationManager = [[CLLocationManager alloc] init];
  locationManager.delegate = self;
  [locationManager startUpdatingLocation];
}

- (void)locationManager:(CLLocationManager *)manager
    didUpdateToLocation:(CLLocation *)location
           fromLocation:(CLLocation *)oldLocation
{
  NSLog(@"The device's new location is: %@", location);
}

The viewDidAppear: method starts up the location framework, which abstracts away the details of the GPS (or cell tower triangulation). The startUpdatingLocation method returns immediately, so your app’s main thread won’t be blocked.

At some point in the future, after the framework has determined the user’s location, the locationManager:didUpdateToLocation:fromLocation: method will be called.² As the user moves around, the location manager will continue to call this method on the delegate until you ask it to stop updating the location.

Side Note: Protocols

When working with delegates, you’ll hear a lot about Objective-C protocols. In a nutshell, a protocol is a lot like an interface in other object-oriented languages. Some methods may be required, others may be marked as optional.

To declare that your class conforms to a particular protocol, you put the name of the protocol in angle brackets after the superclass name.

@interface AddContactDelegate : NSObject <ABPeoplePickerNavigationControllerDelegate> {
    NSMutableArray *contacts;
}

@end

The Address Book UI

If your app needs to interact with the user’s contact list, you can access the data programmatically using the Address Book and Address Book UI frameworks. The first is designed to give your app access to the underlying contact data. The second is a set of pre-built views and interface elements for displaying, editing, and choosing contacts.

When displaying the Address Book UI views, your code participates by setting itself as a delegate of the Apple-provided views. As the user makes their selections, your delegate will be notified and have the opportunity to affect the workflow.

To prompt the user to choose a property (like phone number) for a contact, you have to create an ABPeoplePickerNavigationController and give it a delegate. In Photo Dialer’s case, that delegate is a AddContactDelegate. Here’s the actual code that one of the view controllers uses to present the UI:

// a long time ago, in a view controller far, far away

- (IBAction)addContact:(id)sender
{
    ABPeoplePickerNavigationController *picker = [[ABPeoplePickerNavigationController alloc] init];
    [picker setDisplayedProperties:[NSArray arrayWithObject:[NSNumber numberWithInt:kABPersonPhoneProperty]]];
    picker.peoplePickerDelegate = [[AddContactDelegate alloc] init];
    [self presentModalViewController:picker animated:YES];
}

The actual display of the user’s contacts, and managing the stack of views involved, is handled entirely by Apple’s code. The only time Photo Dialer has to worry about it is in the delegate methods. As the user selects a contact, selects a phone number, or presses “cancel”, the delegate is notified.

After some of the methods, the delegate can tell the UI to stop allowing the user to drill down. This doesn’t dismiss the view, however: you still have to manually remove it from the screen.

#import <AddressBook/AddressBook.h>
#import <AddressBookUI/AddressBookUI.h>


@implementation AddContactDelegate

- (id)init
{
    if(self = [super init]) {
        contacts = [[[ContactDataLoader sharedLoader] loadContactData] retain];
    }
    return self;
}

- (void)dealloc
{
    [contacts release];
    [super dealloc];
}

#pragma mark - People Picker

- (void)peoplePickerNavigationControllerDidCancel:(ABPeoplePickerNavigationController *)peoplePicker
{
    [peoplePicker dismissModalViewControllerAnimated:YES];
}

- (BOOL)peoplePickerNavigationController:(ABPeoplePickerNavigationController *)peoplePicker
      shouldContinueAfterSelectingPerson:(ABRecordRef)person
{
    return YES;
}

- (BOOL)peoplePickerNavigationController:(ABPeoplePickerNavigationController *)peoplePicker 
      shouldContinueAfterSelectingPerson:(ABRecordRef)person
                                property:(ABPropertyID)property 
                              identifier:(ABMultiValueIdentifier)identifier
{
    
    PDContact *newContact = [PDContact contactFromABRecord:person identifier:identifier];
    [contacts addObject:newContact];
    [[ContactDataLoader sharedLoader] saveContactData];
    [peoplePicker dismissModalViewControllerAnimated:YES];
    
    return NO;
}

@end

The specifics of what all the Address Book objects represent isn’t important, except that an ABRecordRef represents a particular person, and the ABMultiValueIdentifier specifies which of potentially many phone numbers the user tapped on.

By wrapping these views in a reusable class and providing a mechanism for a delegate to participate, Apple has allowed us to remove a lot of code that we would normally have to write ourselves.

Delegating in Your Code

When designing your own objects, take a minute to consider if the app-specific features could be implemented by a delegate, leaving reusable code in the original class. For example, if your app uses WebSockets to connect to a live stream of data, split the WebSocket-specifics into a generic class that delegates to an app-specific class. You might find that with just a few delegate methods, most of the code can be reused in another app without changes: just give it a different delegate.

When using a delegate from your class, keep a few tips and tricks in mind:

Don’t retain the delegate. Most of Apple’s classes don’t, so users of your code will be surprised with an ugly memory leak if yours does.
The first argument to each delegate method should be the object that triggered the call. It seems redundant now, but as soon as you need to handle two objects with the same delegate, you’ll be glad you added it.
Consider defining the required methods in a protocol. It’s a bit more work up front, but then the compiler will be able to help you spot any omissions.
If you don’t use a protocol, or have optional methods in your protocol, make sure to use respondsToSelector: to make sure the delegate supports the method you’re about to call.

Next Week

What do you want to read for next Friday’s article? I’m thinking either data sources, or diving into something more advanced, like working with REST APIs or Bonjour networking. Cast your vote for next week’s topic in the comments!

Table views in particular have two helper objects: the delegate and the datasource. The datasource is what the table view uses to determine what information to display, while the delegate controls almost every other aspect of the view.↩
Not only could there be several seconds between the two method calls above, but iOS will ask the user for their permission before revealing their GPS location. If the user denies you, the second method may never be called at all!↩

Cocoa's Target-Action Pattern

2011-08-19T00:00:00-05:00

Despite being a thin wrapper on top of C, Objective-C has dynamic features that make it feel more like a peer to Ruby than to C++. In this short article, I’ll introduce one of those features and show you how to use it in your code to reduce coupling and increase reuse.

Selectors

A selector is essentially the name of an Objective-C method, realized as an object in code. It has the type SEL, which is a primitive (no memory management needed). The actual contents of the selector are opaque, but you can get one from a method name with the @selector() syntax.

SEL setToolbar = @selector(setToolbarItems:animated:);

You can also get a selector from an NSString. This is handy if you want to store the selector in a config file.

SEL setToolbar = NSSelectorFromString(@"setToolbarItems:animated:");

Using Selectors

Once you have the selector, there’s a few things you can do with it.

You can ask an object if it responds to that selector; this is like asking if the object implements this method. If you’ve ever done reflection in Java, prepare for a breath of fresh air!

if ([controller respondsToSelector:@selector(setToolbarItems:animated:)]) {
  /* it's possible to set toolbar items on this controller */
}

You can ask an object to perform that selector:

// direct
[controller viewDidLoad];

// indirect
SEL action = @selector(viewDidLoad);
[controller performSelector:action];

This is the same as calling the method directly, but because the selector could come from a variable, it’s possible to change the method at runtime.

For example, UIBarButtonItem uses a target and action to call your code when the button is tapped. You might have some code in your view controller like this:

- (void)viewDidLoad
{
  
  button = [[UIBarButtonItem alloc] initWithTitle:@"Done"
                                            style:UIBarButtonItemStyleBordered
                                           target:self
                                           action:@selector(doneButtonHit:)];
  // more code
}

- (void)doneButtonHit:(id)sender
{
  NSLog(@"The done button was tapped!");
}

When you run the app and tap on the button, you’ll see “The done button was tapped!” in the console. It’s as if the button has a line of code like [controller doneButtonHit:self], but obviously it doesn’t: the button is a generic object that you can use off-the-shelf. The secret sauce is performSelector!

This pattern, called “target-action”, is used throughout Cocoa, especially in user interface code. It allows the UI widgets to stay generic, while making it easy to integrate your custom controller without needing to subclass anything.

Implementing Target-Action

Let’s write a really simple object that implements the target-action pattern. We’ll call it a button, but we’ll skip writing any view-related code. For simplicity, let’s assume that when the user taps on the button, the button will receive the tap message.

Here’s our interface.

@interface JVButton : NSObject {
  id _target;
  SEL _action;
}

- (void)initWithTarget:(id)target action:(SEL)action;

- (void)tap;

@end

And here’s the implementation.

@implementation JVButton

- (void)initWithTarget:(id)target action:(SEL)action
{
  self = [super init];
  if (self) {
    _target = target;
    _action = action;
  }
  return self;
}

- (void)tap
{
  [_target performSelector:_action withObject:self];
}

@end

The init method is simple, just some vanilla setup. We store the target and action for later. Notice that we don’t retain the target.

In the tap method, we ask the target to perform the action. We also pass the button as an argument to the action. There’s a bunch of variations on the basic performSelector: method to help with things like passing arguments or delaying before performing: check Apple’s documentation for all of them.

The controller wired up to this button might look like this:

- (void)viewDidLoad
{
  button = [[JVButton alloc] initWithTarget:self action:@selector(customButtonTapped:)];
}

- (void)customButtonTapped:(id)sender
{
  NSLog(@"The custom button was tapped!");
}

If you look back at the example with UIBarButtonItem, you’ll see that they’re almost identical! Mimicking Apple’s code is easier than it sounds, right? :)

When to Use Target-Action

The best time to reach for this pattern is when:

You need or want one object to stay generic (e.g., the button class) but be able to call into custom code.
The generic object has exactly one action to perform (e.g., being tapped).

If the generic object has more than one action to perform, or needs to collect information from your custom code, your problem is probably better solved with the delegate pattern or the data source pattern. I’ll cover those in later articles.