Creating an Application with a Map

For starters, create a new View-based Application and open the default .xib file that is created. All that is really needed to get the point across is a view controller. This example will utilize a .xib file and Interface Builder, but the interactions with Interface Builder are limited to establishing a reference and a delegate. If you prefer to do the example entirely in code, that should be just fine too. From within Interface Builder, drag and drop a Map View component from the Library Window onto the View. You may want it to be just this easy, but there are a few things that we need to do before exiting Interface Builder. Take a look at the Attributes of the Map View you just added in the Inspector Window:

The options are pretty straight forward to configure. Quit Interface Builder, but be sure to save all work before exiting. If you try to build and run the project at this point, it will fail. This is because the MapKit Framework has not jet been added to the project. From within Xcode, select the Frameworks folder and Add an Existing Framework to the Project. Now the project should build and execute properly. In the simulator, all that should display is a map of the world (assuming you have network connectivity on the Mac you are using to develop with).

Centering the Map

As a first step, let’s try and take control of the World by centering the Map on just the United States. As a first step in this process, one needs to know the actual latitude and longitude of the center of the United States. Breaking away from Google (who has defined the center of the U.S. elsewhere), we will use a small park near the town of Lebanon, Kansas since they have a historical monument declaring itself as the center of the country, rather than a spot just north of a country club in Coffeyville, Kansas. When working with a Map View, it wants to center on a region, more specifically a MKCoordinateRegion. Now this region in turn wants to know a location (or CLLocationCoordinate2D) and a span (or MKCoordinateSpan). Basically a region is initially configured with a center point and knowledge in coordinate terms as to how far to zoom in/out on the map. How far to zoom would define the span. The first step is ensuring that both that the MapKit and the CoreLocation frameworks have been added to the view controller’s header:

#import <MapKit/MapKit.h>
#import <CoreLocation/CoreLocation.h>

At this point it is time to establish the center of the United States by creating a location with the appropriate latitude and longitude.

	CLLocationCoordinate2D location;
	location.latitude = 37.250556;
	location.longitude = -96.358333;

Now for the tricky part. The span object will need to know about the four corners of the area in question, not just the center. The furthest points north, south, east and west. Once these coordinates are known, it is a simple calculation to determine the span. Rather than using an exact number, pad the span by 4 percent in order to make a more natural looking map:

	MKCoordinateSpan span;
	span.latitudeDelta = 1.04*(126.766667 - 66.95) ;
	span.longitudeDelta = 1.04*(49.384472 - 24.520833) ;

The center location is known and set, and the span is known and set. These are the requirements of the region:

	MKCoordinateRegion region;
	region.span = span;
	region.center = location;

Then in Interface Builder, select the Map View Component, and from the Connections Tab inside the Inspector, create a New Referencing Outlet and assign it to the File’s Owner (which in this case is the View Controller). Quit and Save Interface Builder and run the application. In the header file, be sure to create an IBOutlet for the MapView, otherwise you will not have anything to wire up when using Interface Builder.

	IBOutlet MKMapView *myMapView;

All that is left to do is to wire up the MapView that was created in Interface Builder with the View Controller, and set the region of the map View.

	[myMapView setRegion:region animated:NO];
	[myMapView regionThatFits:region];

The continental United States should now be centered within the simulator. This technique can be used at any time to center the map within any region. All that is needed is the max and min latitude, the max and min longitude, and the center lat/lng coordinates. There are other means to control the span based on just knowing the center location. What I have found is that knowing the center is not always as easy as it sounds, especially when dealing with a list of locations. It is far easier to keep track of the furthest point north, south, east and west in an effort to determine the couners of the area in question.

Annotating a Map

Annotating a map is basically just adding pins to it. This can occur programmatically by accessing data that has been stored locally or is accessed via a remote API, or can be the result of getting location information from either the device in the form or Core Locations API or by data entered by the user like an address. In the end, in order to get it to show up on a map (however the data is collected, stored or referenced), it must conform to the MKAnnotation protocol. The only required property of an object that adopts this protocol is a CLLocationCoordinate2D of the name coordinate:

@property (nonatomic, readonly) CLLocationCoordinate2D coordinate

There are also two optional instance methods that can be implemented. These are not required to be added to a map, but are necessary if one wants to support callouts on the pins that display on the map. These two methods return strings and are named title and subtitle:

- (NSString *)title
- (NSString *)subtitle

Keep in mind that since you are not subclassing, any object can adopt this protocol and be added to a map as an annotation. In its simplest form, an implementation of an annotation would have at least the following declared in its header:

#import <Foundation/Foundation.h>
#import <MapKit/MapKit.h>
@interface AdoptingAnAnnotation : NSObject  {
}
@property (nonatomic, readonly) CLLocationCoordinate2D coordinate;
- (NSString *) title;
- (NSString *) subtitle;
@end

What is great about the MKAnnotation protocol is that any class can adopt it. This means that if you already have a model object that has address information contained within it, you could adopt the MKAnnotation protocol in the existing class and delegate access to information already contained within that class to the optional title and subtitle accessor methods. Keeping the example simple, the following is the basics that are required to support the MKAnnotation protocol in a simple to reuse implementation:

#import "AdoptingAnAnnotation.h"
@implementation AdoptingAnAnnotation
@synthesize latitude;
@synthesize longitude;
- (id) initWithLatitude:(CLLocationDegrees) lat longitude:(CLLocationDegrees) lng {
	latitude = lat;
	longitude = lng;
	return self;
}
- (CLLocationCoordinate2D) coordinate {
	CLLocationCoordinate2D coord = {self.latitude, self.longitude};
	return coord;
}
- (NSString *) title {
        return @"217 2nd St";
}
- (NSString *) subtitle {
        return @"San Francisco CA 94105";
}
@end

Thats it! Depending on how you want to have annotations added to the map, this could be behind the scenes by parsing through the result of a network call that returns data that must be parsed through, or by using CoreLocations and adding a button to the user interface to add annotations each time the button is clicked. Using the simple implementation of a class that adopted the MKAnnotaiton protocol above, the following code would could be added anywhere within the ViewController:

	AdoptingAnAnnotation *someAnnotation = [[[AdoptingAnAnnotation alloc] initWithLatitude:37.786521 longitude:-122.397850 ] autorelease];
	[mMapView addAnnotation:someAnnotation];

Custom Pins

Default red pins are fine, but you may want to use custom annotations as well. The simplest form of customizing the annotations is to simply change the color of the pin. So we get to the main event, a means to display the annotated class on the map that we have added to the view. The first step is to decide which class will be the delegate to the MKMapView that was added to the View. Typically this is the ViewController that the MapView was added to. This can be done in Interface Builder by making the ViewController the delegate to the MapView, or in code by setting the delegate of the MapView to self in one of the init methods of the View Controller. Once this is complete, it is assumed that the View Controller has adopted the MKMapViewDelegate protocol. Once the header of the View Controller has been updated to indicate this fact, all that is required is that the following method is implemented in the View Controller class:

- (MKAnnotationView *) mapView:(MKMapView *) mapView viewForAnnotation:(id ) annotation {
	MKPinAnnotationView *customPinView = [[[MKPinAnnotationView alloc] initWithAnnotation:annotation reuseIdentifier:nil] autorelease];
	customPinView.pinColor = MKPinAnnotationColorPurple;
	customPinView.animatesDrop = YES;
	customPinView.canShowCallout = YES;
	return customPinView;
}

In this way, one has control over some of the basic aspects of the pin annotations that are added to the mapView. If you find that the above code does not work for you, check and double-check that the delegate for the map view has been set up properly. This can be done in Interface Builder or in code as follows:

	[myMapView setDelegate:self];

Custom Annotations

Taking control of the Pins by implementing the mapView method in the MKMapViewDelegate protocol is a good start, but most want to abandon pins all together and utilize custom images on the MapView instead. The technique is identical, but the difference is in the implementation:

- (MKAnnotationView *) mapView:(MKMapView *) mapView viewForAnnotation:(id ) annotation {
	MKAnnotationView *customAnnotationView=[[[MKAnnotationView alloc] initWithAnnotation:annotation reuseIdentifier:nil] autorelease];
	UIImage *pinImage = [UIImage imageNamed:@"ReplacementPinImage.png"];
	[customAnnotationView setImage:pinImage];
    customAnnotationView.canShowCallout = YES;
    return customAnnotationView;
}

The difference is that in this situation a MKAnnotationView is used instead of the MKPinAnnotation class. Try as you might, adding images to pins will not work. Setting a MKAnnotations’s image property will achieve the desired results. This is where several online code examples can be misleading by using the same reference name like pinView or annoView and only change the Class in the alloc statement. And since this is all in the MapKit framework, the imports do not need to change. Therefore this one subtle difference is often the culprit of several hours of pain and suffering.

NOTE: It is recommended that one resize the image prior to compilation using a tool like preview rather than attempt to resize the image in code.

Annotation Callouts

As we saw earlier, annotations can have titles and subtitles. These are optionally displayed when the user taps on a given pin or custom annotation. In the prior code examples, we set the property of ShowCallout to YES. These callouts can also have images associated with them. These images are not meant to be the same image that was utilized as the pin image as these will be displayed in the callout above the pin when the pin receives a tap event. This technique will expand upon the one utilized in either of the two prior examples by adding the following two lines of code inside of the MKAnnotationView delegate method:

	UIImageView *leftIconView = [[UIImageView alloc] initWithImage:[UIImage imageNamed:@"LeftIconImage.png"]];
	customAnnotationView.leftCalloutAccessoryView = leftIconView;

You’re not required to use the MKAnnotationView in order to add an image to the left callout accessory view. This can also be done with the MKPinAnnotationView.

NOTE: It is recommended that you resize the image prior to compilation using a tool like Preview rather than attempt to resize the image in code.

Assigning Actions to Annotation Callouts

Finally there is the matter of assigning an action to an annotation’s callout. Typically, these actions pop another view onto the stack, but really can do anything. What is required here is that a button be added to the AnnotationView (either the MKPinAnnotiaonView or the MKAnnotationView example above). This button will assign one of its control events to a method typically in the same ViewController that is also the delegate to the MapView itself:

	UIButton *rightButton = [UIButton buttonWithType:UIButtonTypeDetailDisclosure];
	[rightButton addTarget:self action:@selector(annotationViewClick:) forControlEvents:UIControlEventTouchUpInside];
	customAnnotationView.rightCalloutAccessoryView = rightButton;

Just as in the prior example, this code should be added to the delegate method implemented in the View controller. For example, if all of the details were added to the MKAnnotationView, the code would look as follows:

- (MKAnnotationView *) mapView:(MKMapView *) mapView viewForAnnotation:(id ) annotation {
	MKAnnotationView *customAnnotationView=[[[MKAnnotationView alloc] initWithAnnotation:annotation reuseIdentifier:nil] autorelease];
	UIImage *pinImage = [UIImage imageNamed:@"ReplacementPinImage.png"];
	[customAnnotationView setImage:pinImage];
    customAnnotationView.canShowCallout = YES;
	UIImageView *leftIconView = [[UIImageView alloc] initWithImage:[UIImage imageNamed:@"LeftIconImage.png"]];
	customAnnotationView.leftCalloutAccessoryView = leftIconView;
	UIButton *rightButton = [UIButton buttonWithType:UIButtonTypeDetailDisclosure];
	[rightButton addTarget:self action:@selector(annotationViewClick:) forControlEvents:UIControlEventTouchUpInside];
	customAnnotationView.rightCalloutAccessoryView = rightButton;
    return customAnnotationView;
}
- (IBAction) annotationViewClick:(id) sender {
    NSLog(@"clicked");
}

Conclusion

These are the basic building blocks that are used when working with maps on the iPhone. These building blocks can be used in isolation, or can be added together to work with each other in concert. For instance, when adding an annotation to a map, the map can be re-centered taking the location new annotation into account. While these bare bones examples are not a true representation of a real world application, they were meant to illustrate the basics in a very minimalist approach that simply works.

References

• iPhone OS Reference Library - MKMapView Class Reference
• iPhone OS Reference Library - MKAnnotation Protocol Reference
• iPhone OS Reference Library - MKMapViewDelegate Protocol Reference
• iPhone OS Reference Library - MKAnnotationView Class Reference

Unfortunately, there’s no recipe for how to write a simple, intuitive and compelling app. Our best bet for getting our hands on that recipe is probably this guy, but until he makes that announcement, handling these points is left as an exercise for the reader.

Writing a responsive app, however, is much easier.

A good working definition for a “responsive” app is one that responds to user input quickly and doesn’t hang without telling the user what’s going on. The rule of thumb here is that GUIs should respond to input in no more than 1 second, so the bar is set pretty high, especially for web-enabled apps. This article describes the most common reason GUIs get unresponsive and what to do about it.

How Do These Newfangled GUIs Work, Again?

Cocoa Touch’s GUI (like most GUIs) is built on an “event + event loop” architecture. User interactions like taps and keypresses are translated to events, and these events are then processed one-by-one in the imaginatively named event loop:

Simplified Event Flow in a Cocoa App

As long as each event gets processed quickly, the GUI stays nice and zippy. But because events are processed serially, one event can back up the whole gravy train. If one event takes five second to process, then the GUI will be completely unresponsive for those five seconds until the event loop can start processing new events again.

But what if you have some GUI resources that take five seconds to load? We can’t load them all at app initialization time because we don’t always know what resources we’ll need when the app is starting up, especially for things like profile pictures. Also, the iPhone is an embedded platform, so memory for preloading is in short supply, anyway. How, then, can we appease the event loop tiki gods? The answer, young grasshopper, is to load such resources asynchronously, and then update the GUI when they’re done loading.

Responsiveness Test Bench

To illustrate these ideas, I’ve made a simple iPhone app that loads an image resource for display in an iPhone app GUI three different ways.

The Responsiveness Tester. The people responsible for the appearance of this iPhone app have been sacked.

Each method loads and displays the same image, but does the loading differently to demonstrate the effect each approach has on GUI responsiveness. The source code for this app is attached to this article if you’d like to play along at home.

When the user chooses a loading technique by tapping its table row, a corresponding method is called to illustrate that loading technique. These methods are called directly from the UITableViewDelegate tableView:didSelectRowAtIndexPath: method, which runs in the event loop, so all this code runs directly in the GUI thread.

First, let’s have a look at the code from the load-from-file example:

- (void)showSynchFileDemoWithTitle:(NSString *)title {
    UIImage *image;
    image = [UIImage imageNamed:@"apple-logo.png"];
    EagerViewController *view=[[EagerViewController alloc]
        initWithNibName:@"EagerViewController" bundle:nil title:title image:image];
    [self.navigationController pushViewController:view animated:YES];
    [view release];
}

The code looks like it sounds, right? We load the image from disk, use it to create a new UIViewController, push that UIViewController onto our UINavigationController, and then release the UIViewController back into the wild. This is exactly why synchronous loading is so popular: it’s ridiculously simple. And since we’re just loading a small image from a file, the GUI is still zippy, so synchronous loading is actually fine here.

Now let’s look at loading that same image from a synchronous web request instead of a file:

- (void)showSynchWebDemoWithTitle:(NSString *)title {
    UIImage *image;

    NSURLRequest  *request=[NSURLRequest requestWithURL:[NSURL
        URLWithString:IMAGEURL]];
    NSURLResponse *response=nil;
    NSError *error=nil;
    NSData *content=[NSURLConnection sendSynchronousRequest:request
        returningResponse:&response error:&error];
    if(content == nil)
        image = [UIImage imageNamed:@"big-red-x.png"];
    else
        image = [UIImage imageWithData:content];

    EagerViewController *view=[[EagerViewController alloc]
        initWithNibName:@"EagerViewController" bundle:nil title:title image:image];
    [self.navigationController pushViewController:view animated:YES];
    [view release];
}

The code is slightly more complicated, but still not too bad. We set up a web request for the image, wait for it to download, build an image with the contents of that request if it succeeded or load a default image if it failed, and then build our UIViewController from that image. Still nice and easy, but how does it perform?

The problem with synchronous web loading. Hang much?

Turns out, not so well. After the user taps “Synchronous from Web,” the app just kind of sits there for a few seconds before it shows the next view. Why? The synchronous web request loading the image in the event loop takes a while to complete, which blocks the event loop and hangs the GUI. This kind of code is surprisingly common despite the hangs it causes. Unless you’re willing to tick off your customers, which is usually considered harmful, synchronous web loading in the event loop is right out.

So what’s the asynchronous web loading equivalent look like? Behold, ye mortals, and despair…

From RootViewController.m:

- (void)showAsynchWebDemoWithTitle:(NSString *)title {
    LazyViewController *view=[[LazyViewController alloc]
        initWithNibNamed:@"LazyViewController" bundle:nil title:title
        imageURL:[NSURL URLWithString:IMAGEURL]];
    [self.navigationController pushViewController:view animated:YES];
    [view release];
}

From LazyViewController.m:

- (id)initWithNibNamed:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil title:(NSString *)title imageURL:(NSURL *)imageURL {
    if(self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil]) {
        self.navigationItem.title = title;
        if(imageURL != nil) {
            self.getlogo = [AtomicAsynchronousWebRequest requestWithURL:imageURL
                andDelegate:self];
        }
    }
    return self;
}

- (void)updateLogoWithImage:(UIImage *)image {
    [self.logo stopLoadingWithActiveView:[[[UIImageView alloc] initWithImage:image]
        autorelease]];
}

- (void) atomicAsynchronousWebRequest:(AtomicAsynchronousWebRequest *)request didFailWithError:(NSError *)error {
    if(request == self.getlogo) {
        [self updateLogoWithImage:[UIImage imageNamed:@"big-red-x.png"]];
        self.getlogo = nil;
    }
    else {
        // We have no idea which request this is. Just log it and move on.
        NSLog(@"Failed unrecognized HTTP request: %@", request);
    }
}

- (void)atomicAsynchronousWebRequest:(AtomicAsynchronousWebRequest *)request didSucceedWithResponse:(NSURLResponse *)response andContent:(NSData *)content {
    if(request == self.getlogo) {
        [self updateLogoWithImage:[UIImage imageWithData:content]];
        self.getlogo = nil;
    }
    else {
        // We have no idea which request this is. Just log it and move on.
        NSLog(@"Succeeded unrecognized HTTP request: %@", request);
    }
}

Oh… that’s all? Well, I guess that’s not so bad. We pass the URL for our image to the UIViewController initializer, and the UIViewController then starts an asynchronous web request for the image and updates the logo view with an image when the web request either succeeds or fails. (Observant readers will notice some custom methods above. Hang tight, we’ll talk about those in a minute.) What does all this trouble buy us?

Nice and Zippy. Asynchronous Loading FTW!

A wonderfully responsive app, that’s what. The transition from the first view to the second view is instantaneous; the second view shows its spinner until the web request completes or fails, and then the logo is updated with a new image. Why is this UI so snappy? Because all long-running operations are performed outside the message loop, so nothing hangs the GUI thread. Lazy loading for slow resources is clearly the way to go.

And if you think about it, this approach is good not only because it runs faster, but also because it’s more modular. The UIViewController being created knows what it’s displaying; it should probably be loading its resources too, especially if that loading is complex, in case that UIViewController needs to be reused elsewhere in the app.

So… sweet. A twofer.

Being Lazy About Being Lazy

If asynchronous loading is what we need to be doing — and it is – then how can we make it easy? It turns out that asynchronous loading is easier in Objective-C than it is in many other languages.

In Java, for example, asynchronous loading requires you to mess with callbacks and Threads, SwingWorkers, or ExecutorServices, which feels like jumping through a bunch of flaming hoops while wearing a newspaper tutu. In Objective-C, though, web requests are baked into the API and already have asynchronous callback functionality, which means that asynchronous loading can be had essentially for free, especially if we do a little customization of our own.

The app uses two custom classes. I’ll discuss them here just in case the classes themselves or what they do is useful to other developers. Both classes are in the attached source if you want to put your eyes on them, or use them for your own nefarious purpose.

AtomicAsynchronousWebRequest

The iPhone SDK’s generalized web request API is NSURLConnection, and you can find a good primer on how to use it here. The NSURLConnection exposes way more features than most apps need, though, like hooks for reacting to redirects and chunked input, which makes it more difficult to use than it needs to be. AtomicAsynchronousWebRequest is a thin wrapper around NSURLConnection that lets developers perform the most common web tasks (namely atomic GETs and POSTs) asynchronously by implementing a dead-simple 2-method protocol.

DelayedLoadView

While the iPhone has a nice “spinner” GUI element (UIActivityIndicatorView) that’s handy for telling the user something is loading, it has no explicit API for populating GUI views lazily. DelayedLoadView is essentially a “container” view that shows a spinner until it’s updated with its “real” content view, which makes handling activity indicators and lazy content really easy, especially for GUIs built-in Interface Builder.

Gotchas

A couple gotchas have been glossed over in the interest of keeping things at least a little brief. Now that we’re past the good stuff, I’ll mention a few of them here, just in case you want to get creative on your own:

1. All GUI updates must happen on the GUI thread. Cocoa Touch GUI elements, like GUI elements in most toolkits, are not thread-safe. So, if you need to interact with a GUI element, you need to do it from the main thread. If you’re not making your own threads, you probably don’t need to worry about this. If you are, you may need to make use of NSObject’s performSelectorOnMainThread:withObject:waitUntilDone: or similar.
2. Remember that UIViewController IBOutlets are not initialized after super’s initializer completes. Instead, the UIViewController must be set to appear before IBOutlets are properly connected. This means that failure conditions can’t really be handled inside a UIViewController initializer, so any custom load code you write needs to take that into account. If you want an example of how to work around this issue, check how AtomicAsynchronousWebRequest calls its failure method from its initializer roundabouts using a performSelector call.
3. UIActivityIndicatorViews are kind of confusing. You probably want to set hidesWhenStopped to YES. That way, startAnimating and stopAnimating will do what you expect them to. If you don’t see a spinner and you expect to, make sure your UIActivityIndicatorView isn’t hidden. If you see a spinner but it’s not spinning, you need to call startAnimating.
4. Not all long-running operations have asynchronous callbacks baked in. Web requests do, which is very handy, but if you need to do some other kind of loading you’ll have to get creative. If you’re only going to load things now and then, using performSelectorInBackground:withObject: is probably just fine. If you’re going to be doing a lot of loading, though, you won’t want to create a new background thread each time you load something, so you’ll probably want to create a custom NSRunLoop and kick off your loading with performSelector:onThread:withObject:waitUntilDone:. You can synch up the GUI when loading’s done with a simple performSelectorOnMainThread:withObject:waitUntilDone:.

Conclusion

You’re now an expert on how to build responsive network-enabled GUIs! Or at least you know more than you did.

It’s worth mentioning that even though the article focused on loading images, the very same principles can be applied to executing web service calls, loading web pages, or any other task that requires time to complete.

I now expect all apps to have responsive GUIs, even if they’re loading resources from the web. You’ve been warned. I’ve got my eye on you, iPhone developers.

Stay QWERTY, my friends.

Two popular techniques to pass references to objects from one view to the next are to create properties in the Application Delegate, or to continue to pass references from one view to the next like a relay race passes a baton from one runner to the next using a series of carefully placed update methods making for an allocation nightmare and increase the opportunities for memory leaks or the hard to track down crashes. Sometimes this need in programming is referred to as implementing Global Variables. There is also a well established design pattern that can assist with this need as well, it is called the Singleton Pattern.

Singleton Pattern

The Singleton Pattern is a derivative of the Factory Pattern that ensures that one and only one instance of an Object can ever exist. By creating one or more implementations of the Singleton Pattern within a given application, the concept of ‘global variables’ can better be managed through tighter control. This allows for what is called lazy instantiation. If you do not need the variable based on what is going on in the application, then do not ask for or create an instance of one.  In Objective-C, Apple has outlined the recommended technique for implementing the singleton pattern.

Objective-C Singleton Pattern

static MySingletonClass *sharedGizmoManager = nil;
(MySingletonClass*)sharedManager{
  if (sharedSingletonManager == nil) {
    sharedSingletonManager = [[super allocWithZone:NULL] init];
  }
  return sharedGizmoManager;
}
(id)allocWithZone:(NSZone *)zone{
  return [[self sharedManager] retain];
}
(id)copyWithZone:(NSZone *)zone{
  return self;
}
(id)retain{
  return self;
}
(NSUInteger)retainCount{
  return NSUIntegerMax;
}
(void)release{
  //do nothing
}
(id)autorelease{
  return self;
}

But you may find that the following is all that is necessary:

Singleton.h

#import <Foundation/Foundation.h>
@interface Singleton : NSObject {
}
+ (Singleton*) retrieveSingleton;
@end

Singleton.m

#import "Singleton.h"
@implementation Singleton
static Singleton *sharedSingleton = nil;
+ (Singleton*) retrieveSingleton {
  @synchronized(self) {
    if (sharedSingleton == nil) {
      sharedSingleton = [[Singleton alloc] init];
    }
  }
  return sharedSingleton;
}
+ (id) allocWithZone:(NSZone *) zone {
  @synchronized(self) {
    if (sharedSingleton == nil) {
      sharedSingleton = [super allocWithZone:zone];
      return sharedSingleton;
    }
  }
  return nil;
}
@end

Try and keep each singleton’s scope limited to manage only the information that is related to a particular use case and not as a catch-all for all global information across the application. It is probably best to utilize each singleton as a delegate to the information it is responsible for managing, and not use it as a means to gain access to any objects it has associations with. Although on the iPhone, and when being used in primarily a read only or a write seldom implementation, the risk of writing code that is not thread safe increases when utilizing shared objects. Keeping concurrency in mind, and utilizing the singleton as a delegate to the information at hand, one can watch out for multi thread related issues and deal with them in kind. One thing to watch out for would be include updating or setting properties of the singleton from within an implemented perform selector or a notification. If concurrency issues do arise, it may become necessary to synchronize access to certain properties or methods.

No, not the AppDelegate!

So why not just keep adding properties to the AppDelegate? After all, the AppDelegate is a singleton as well and is therefore accessible by invoking the sharedApplication class method. The problem with this techniques is that you end up loading up the application with too much information that may or may not be necessary depending on what functions the user chooses to evoke. It could also lead to longer and longer startup times. Get the application started as quickly as possible, and don’t leave the user hanging for too long.

What about Global Constants?

Keep in mind that this is not the best technique to employ if all you need is a means to define and gain access to Global Constants. The quickest way to do that is to create a Precompiled Prefix Header file and include that in your project. By default, most of the projects generated in XCode that create iPhone Applications will include a file with an extension of .pch. This file will initially look like the following:

#ifdef __OBJC__
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#endif

One can then add any number of #define statements that will be included in all header files across the entire project.

#define SOME_STRING_CONSTANT @"My Important String"

Conclusion

The Singleton Pattern can be used to make the complex and ugly means of sharing a simple variable between two different views or view controls an easy task. If used sparingly and some basic guidelines are followed as not to bloat the application and create a multi thread nightmare to debug, this technique can be quite useful. Much more so than passing Objects back and forth among views or by breaking the encapsulation of the AppDelegate by assigning it more responsibility than it should have.

References

• Mac OS X Reference Library – Cocoa Fundamentals Guide – Creating a Singleton Instance
• iPhone OS Reference Library – UIApplication Class Reference
• Mac OS X Reference Library – Xcode Build system Guide – Using a Precompiled Prefix Header

The key to a smooth and professional looking launch sequence starts with knowing exactly where the application will land at startup. Some applications start at exactly the same place each and every successive launch, others attempt to preserve the application’s state and launch into the screen where the user last used the application. Keeping this in mind can change the strategy of how the launch sequence is implemented. This includes screen orientation as well as how and even if the status bar it to be displayed.

One may witness flickering of the status bar from blue, to black or from black to blue during the launch sequence. This is mainly due to the fact that there are two places to change the behavior of the status bar. One is hidden in the info.plist file, and the other is typically via code in the Application Delegate’s applicationDidFinishLaunching method. The info.plist configuration is used before the main window is loaded, and the code in the Application Delegate is used during the launching of the main window. The reason one may want to utilize both styles is to take advantage of a full screen splash page, and then enable the appropriate looking status bar once the application has finished loading.

For the purpose of this example application, we will assume that the user state is preserved between executions, and we do not know exactly what the screen will look like when the user enters the application. We will therefore be implementing a full-screen splash view that will have the status bar hidden during the launch sequence. Once the splash view has disappeared, a black opaque status bar will be utilized throughout the application. It is also assumed that the application will launch in portrait mode, and that the first screen the user will see will also be in portrait mode.

Editing the Configuration File

The first order of business is to take care of the status bar. In Xcode, locate the info.plist file for the project. To add an additional property to the plist file, simply select one of the entries and click on the plus tab that appears to the right and select Status Bar Style from the drop down list:

Edit Projects plist File

There are only three different styles to choose from. Try each style out to see which one fits the needs of the application being developed. For this example we will set the style to UIStatusBarStyleDefault.

UIStatusBarStyles:
UIStatusBarStyleDefault — Gray (the default)
UIStatusBarStyleBlackTranslucent — Transparent black (specifically, black with an alpha of 0.5)
UIStatusBarStyleBlackOpaque — Opaque black

If on the other hand the desire is to hide the status bar when the application launches, then yet another property needs to be set. In this case, add the “Status Bar is initially hidden” property to the plist file and be sure to check the box next to the property.

Editing the Application Delegate code

So now that the status bar style is set, and initially hidden, how does one get the status bar to display again? You can actually turn the status bar on and off programmatically via code. This is particularly handy when the need arises to display a full screen view, such as the splash screen this application is utilizing. In the applicationDidFinishLaunching method of the Application’s designated AppDelegate class, add the following line of code to make the status bar visible again:

- (void)applicationDidFinishLaunching:(UIApplication *)application {
    // Override point for customization after app launch
    [window addSubview:viewController.view];
    [window makeKeyAndVisible];
    [[UIApplication sharedApplication] setStatusBarHidden:NO animated:YES];
}

Adding a Default.png Image

Surprisingly, the size of this file is not as important as the naming convention of the file. Default.png is a case sensitive PNG file. The image should be 480×320 according to Apple. Following Apple’s conventions, this image should look like the view that the user will see when the application has launched, and not the actual splash screen.

Xcode provides a mechanism to create a Default.png file from an attached device running the application. From the Organizer window, select the device, click on screenshots and click capture. To make that screenshot your application’s default image, click Save As Default Image. Even though the image that is created includes the status bar as it looked when the screen shot was captured, the iPhone OS replaces it with the current status bar when your application launches. Just to be clear, this is not a splash screen…not yet.

Long Launch Sequences to Varying Views

So far, this is what most applications will implement if they implement any sort of controlled visual experience when the application launches. If you follow Apple’s guidelines, and the image you produce is the first screen that the user will see, all is good. Except, what if the launch sequence is not as fast as the user expects? What if the application preserves state and lands on a different view based on the users last know state? Then this technique is not up to the task.

Photoshop a branded image representing the application and save it as a PNG image sized at 480×320. Do not include a status bar of any kind in the image file being created. Add this image file to the project. Now the application sort of has a splash screen, through a misused implementation of the Default.png file. To correct this, simply add an image view as a property to the App Delegates header and create it as follows:

    splashView = [[UIImageView alloc] initWithFrame:CGRectMake(0, 0, 320, 480)];
    splashView.image = [UIImage imageNamed:@"Default.png"];
    [window addSubview:splashView];
    [window bringSubviewToFront:splashView];

At this point, the image view is utilizing the exact same image file that was created in Photoshop. There’s no chance of the initial view being different than the Default.png file at this point. The one remaining problem is the timing of when to remove the image view from the subview. This can be handled in one of two ways…

Controlling the Duration of the Splash Screen

The first option is for those with quick startup times that just want a splash screen. In this situation, create a method to remove and release the splash view, then calling that method via a timed perform selector call as follows:

    [self performSelector:@selector(removeSplash) withObject:nil afterDelay:1.5];

The removeSplash method does just that, removes the image view from the subview and releases the object.

    -(void)removeSplash;
    {
      [splashView removeFromSuperview];
      [splashView release];
    }

The second method uses the same remove splash method, but relies on the built in event management to trigger when the method gets called.

    [[NSNotificationCenter defaultCenter] addObserver:self
          selector:@selector(saveClaim:)
          name:@"RemoveSplashScreen"
          object:nil];

Now all that needs to be done is to post the notification from anywhere. This technique is particularly useful if the reason that the launch sequence is taking a long time has nothing to do with code that was implemented in the App Delegate.

    [[NSNotificationCenter defaultCenter]
          postNotificationName: @"RemoveSplashScreen"
          object: nil];

This technique can be employed from anywhere within the application. Removing the observer after the fact may avoid crashes if there is an opportunity for this notification to be fired multiple times. Releasing an object when no object it there to be released can lead to troublesome crashes to track down. The quick and dirty is to use the delay on the performSelector call.

Conclusion

And there it is, a splash screen that conforms to Apple’s guidelines. No hidden APIs, no hacks, no special sauce. A simple, straight forward approach to making the initial interaction with the user as pleasant as possible.

References:

• iPhone OS Reference Library UIApplication Class Reference UIStatusBarStyle
• iPhone OS Reference Library iPhone Development Guide Capturing Screen Shots
• Mac OS X Reference Library Threading Programming Guide Cocoa Perform Selector Sources
• Mac OS X Reference Library NSNotificationsCenter Class Reference

Welcome to another episode of TheAppleBlog’s iPhone Dev Sessions. We left off with a drum app tutorial called Bickboxx. For this tutorial, we’re building off of the first Bickboxx project, so go back and finish it if you haven’t already. Or if you want to cheat, grab the Bickboxx code from Github.

The Story

The Boss is happy we’ve released Bickboxx, the iPhone drum app, but now he wants to know how it’s doing. Not just sales-wise.

How many people use our app? How many times have they used the app? How much time do they spend using our app? How many users do we have in each city, state and country? How many illegal haxored versions are out there? How many people open the app once and never use it again?

Yikes. That’s a lot of questions.

Lucky for us, we don’t have to write hundreds of lines of code and roll our own analytics server to track the answer to these questions.

There are dozens of iPhone analytics APIs that will do all of the heavy lifting for us. Flurry, Mobclix, and Medialets come to mind.

There isn’t a clear leader in iPhone analytics yet but for this tutorial we’ll be using Pinch Analytics. It has comprehensive documentation and its reporting is detailed as well.

Signing Up for a Pinch Media Account

The first thing you want to do is sign up for a Pinch Media account. The first part of registration is the usual username/email/password page. The second part detailing your app takes you to this:

Since Bickboxx isn’t a real app that you’ll be distributing, you don’t have to fill out any of this. You can skip this part by clicking the “I’ll do it later” button.

When you are adding analytics to your real-life app, I’ve filled out some sample data for you to go by. Note that if you don’t add an app into Pinch Media, you won’t be able to view any analytics reports.

Download and Install the Pinch Media SDK

After you’ve signed up for an account, download and unzip the SDK.

Open up the Bickboxx project in Xcode. Drag the Beacon+FBConnect.h and Beacon.h files into the Classes directory in the Xcode project.

Make sure the “Copy items into destination group’s folder (if needed)” checkbox is checked. Click Add. We do this so our code knows how to access the Pinch Media methods in the libPMAnalytics-rXX.a library.

We’ll need to import the libPMAnalytics-rXX.a library next. Do this by dragging the libPMAnalytics-rXX.a file to the Frameworks folder in Xcode. Again, make sure the “Copy items into destination group’s folder (if needed)” checkbox is checked. Click Add.

Install the Supporting SDKs

We need a few more frameworks to get going. We may not use these frameworks directly, but Pinch Analytics does.

Ctrl-Click the Frameworks folder and choose Add → Existing Frameworks…

Select libsqlite3.dylib and click Add.

Do the same for the SystemConfiguration.framework.

Lastly, do the same for CoreLocation.framework.

Build the project to make sure everything is in place. It should compile. Got it? Good.

Adding the Pinch Analytics Code

Add this import statement for the Beacon.h file into BickBoxxAppDelegate.h.

#import “Beacon.h”

Adding this will allow us access to the Pinch Analytics methods from inside our BickBoxxAppDelegate.m file. Your BickboxxAppDelegate.h file should now look like this. Our change is in line 2.

#import <UIKit/UIKit.h>
#import "Beacon.h"

@class BickBoxxViewController;

@interface BickBoxxAppDelegate : NSObject <UIApplicationDelegate> {
  UIWindow *window;
  BickBoxxViewController *viewController;
}

@property (nonatomic, retain) IBOutlet UIWindow *window;
@property (nonatomic, retain) IBOutlet BickBoxxViewController *viewController;

@end

Open up BickBoxxAppDelegate.m and locate the applicationDidFinishLaunching method. Add this line of code.

NSString *applicationCode = @"REPLACE THIS WITH YOUR APPLICATION CODE";

Replace the REPLACE THIS WITH YOUR APPLICATION CODE with your Application Code from Pinch Media. You can find your application code in your Pinch Media account.

This is your unique ID that Pinch Media uses to identify which app is sending data to them. If you opted to not setup an app during registration, you need to do this to get an Application Code. If you don’t put in a valid Application Code, you won’t get any analytics reports and you’re wasting your time.

We’re going to use this applicationCode NSString to activate our analytics beacon. Add this line of code to the applicationDidFinishLaunching method.

[Beacon initAndStartBeaconWithApplicationCode:applicationCode
    useCoreLocation:YES useOnlyWiFi:NO];

This fires up the analytics code when the app launches. Note that we’re sending in the applicationCode NSString that we inserted in the previous step. Also note the useCoreLocation parameter. You can set this to YES or NO depending on whether you want to capture location statistics.

Use this with caution. If you think you’ll offend your users by asking for their location, set this to NO.

Another parameter is useOnlyWiFi. Not everyone in the world has an unlimited data plan. They’ll be none to happy if your app is sending data over the mobile network when they don’t want it to.

Like the useCoreLocation parameter, use this parameter with caution. If set to YES, the analytics data will be sent to Pinch Media only when they’re connected to Wi-Fi. This way, the people who pay their mobile carrier per kilobyte won’t get mad. The downside is that you will miss usage statistics if they never connect to Wi-Fi.

If you’re not worried about being responsible for someone’s data overages, set this to NO.

Your code in BickBoxxAppDelegate.m for the applicationDidFinishLaunching method should now look like this.

- (void)applicationDidFinishLaunching:(UIApplication *)application {

	// New code below this
	NSString *applicationCode = @"REPLACE THIS WITH YOUR APPLICATION CODE";
  [Beacon initAndStartBeaconWithApplicationCode:applicationCode
								 useCoreLocation:YES useOnlyWiFi:NO];

  // Old code below this
	[[UIApplication sharedApplication] setStatusBarHidden:YES animated:NO];

  // Override point for customization after app launch
  [window addSubview:viewController.view];
  [window makeKeyAndVisible];
}

Finally, when we exit the app or your app crashes (your apps never crash right?), we need to stop the analytics beacon.

Add this method to the BickBoxxAppDelegate.m file.

- (void)applicationWillTerminate:(UIApplication *)application {
  [[Beacon shared] endBeacon];
}

Build and run your app.

You’re Done!

That’s it — you’re done! Go to lunch and have a sandwich. Nothing’s changed to the user except it’s going to ask if it’s okay that Bickboxx uses their location. You can now login to Pinch Media’s site and see all your pretty statistics and graphs. Worth noting is that the data isn’t real-time — it’s only updated twice a day.

Homework

The Boss is happy now that we can measure the performance of our app. He wants more detail on which buttons are pressed the most. You can do this by adding sub-beacons, which you can read about at the documentation site.

BickBoxx On Github and the iTunes App Store

Like last time, the code is open-sourced on Github. You can check your code against the code here if you start to stumble.

We’re here to show you how to build actual apps. You can download the app as it’s built at the iTunes App Store. More info on the open-source/open-tutorialized efforts on the BickBoxx website.

Related research and analysis from GigaOM Pro:
Subscriber content. Sign up for a free trial.

• Mobile Q4: All Eyes Were on Android, 4G and the Rising Tablet Tide
• Report: A Mobile Video Market Overview
• In Q3, the Tablet and 4G Were the Big Stories

You’ve seen all the different drum apps, right? Well, they’re really easy to make. In this iPhone Dev Sessions article, I want to teach you how to make Bickboxx, an actual app that’s in the iTunes App Store.

Grab Bickboxx (FREE) from the iTunes App Store if you want to see this puppy in action so you have an idea of what you’re building. Also, I’ve opened up the source code for free at Github. Feel free to download it, report issues, or even fork your own version and change it as you see fit.

More info on the open-source community project at Bickbot’s Bickboxx page.

Note: You don’t need to download the code from Github to get through the tutorial.

An On-going Project

I plan on adding more tutorials with enhancements to this project. Here are a couple of things that could be featured in future iPhone Dev Sessions.

• Key logger
• Adding analytics tracking
• Adding application preferences
• Track recorder and editor
• Vibration feedback
• Add your own custom sounds
• Access your iPod library as a background track

Leave a comment with other enhancements you want to learn.

OK, let’s get to creating Bickboxx!

Get Started

Create a new View-based project in XCode. Name the project “Bickboxx”.

Download this zip file and unzip it. These are all the sounds, images, and icons you need for Bickboxx. Drag all these files to the Resources. Hat tip to John Ellenich for the graphics/sounds.

You need to copy the item to the project’s directory, so put a check mark next to “Copy items into destination group’s folder (if needed).” Your settings should look similar to this. Click Add.

Adding the background image in Interface Builder

Double-click BickboxxViewController.xib to open it in Interface Builder. Drag an Image View (UIImageView) from the Library to the View window. This will act as a placement holder for our background image.

Bring up the Attributes Inspector. Set the Image to Background.png.

Creating the Button in Interface Builder

Drag a Round Rect Button (UIButton) to the View.

Bring up the Attributes Inspector. We don’t want the button to look like an ugly white rectangle. Set the Type to Custom.

Further down the Attributes Inspector, set the button’s state to Normal (or Default State Configuration depending on your version of Xcode). This is what the button looks like when it’s not doing anything.

Set the button’s Image to B Inactive.png. You need to resize the button in the View to make sure the “B” button is fully shown.

Now, change the button’s state to Highlighted (or Highlighted State Configuration depending on your version of Xcode). This is what the button looks like when it’s pressed down.

Set the button’s Image to B Active.png.

Drag another Round Rect Button (UIButton) to the View and repeat this section for the letters “E”, “A”, and “T”. Your View should now look like this:

Close Interface Builder for now.

Build and Go to make sure everything is still working. Touch the buttons, and they should light up.

Adding the Sounds Code

We have an interface that doesn’t do anything. Let’s fix that. The audio framework we need isn’t added by default. We have to add the AudioToolbox framework.

Control+Click the Frameworks folder on the left. Go to Add → Existing Frameworks…

Select the AudioToolbox.framework from /System/Library/Frameworks.

Click OK and add it to the project.

Open BickboxxViewController.h and add this code to it.

#import <UIKit/UIKit.h>
#import <AudioToolbox/AudioServices.h>

@interface BickboxxViewController : UIViewController {
    CFURLRef        bNoteFileURLRef;
    SystemSoundID    bNoteFileObject;
    CFURLRef        eNoteFileURLRef;
    SystemSoundID    eNoteFileObject;
    CFURLRef        aNoteFileURLRef;
    SystemSoundID    aNoteFileObject;
    CFURLRef        tNoteFileURLRef;
    SystemSoundID    tNoteFileObject;
}

@property (readwrite)    CFURLRef        bNoteFileURLRef;
@property (readonly)    SystemSoundID    bNoteFileObject;
@property (readwrite)    CFURLRef        eNoteFileURLRef;
@property (readonly)    SystemSoundID    eNoteFileObject;
@property (readwrite)    CFURLRef        aNoteFileURLRef;
@property (readonly)    SystemSoundID    aNoteFileObject;
@property (readwrite)    CFURLRef        tNoteFileURLRef;
@property (readonly)    SystemSoundID    tNoteFileObject;

@end

At the top, we’re referencing AudioServices.h from the AudioToolbox framework we imported earlier.

Below that is the declaration of properties for four sounds for the “B”, “E”, “A” and “T” buttons.

bNoteFileURLRef is the file location reference for the bNoteFileObject. This is the sound the “B” button will make.

These are the properties for the “E”, “A” and “T” sounds as well.

The BickboxxViewController.m File

Open BickboxxViewController.m. We need to synthesize the getters/setters for our properties.

You can do this by adding this after @implementation BickBoxxViewController:

@synthesize bNoteFileURLRef, bNoteFileObject, eNoteFileURLRef,
eNoteFileObject, aNoteFileURLRef, aNoteFileObject,
tNoteFileURLRef, tNoteFileObject;

Changing the viewDidLoad Method

Locate the viewDidLoad method. It will be commented out. You want to uncomment it to activate it.

The viewDidLoad method gets called after all the UI components are created. This is a good place for any startup code you need your app to perform. In this case, we’ll need to set our properties to the correct sounds.

The first thing we need to do in viewDidLoad is get the main bundle for the app. The main bundle allows you to use a folder hierarchy to organize and locate many types of application resources including images, sounds, localized strings, and executable code.

After [super viewDidLoad];, add this code to get the main bundle for the app.

// Get the main bundle for the app
CFBundleRef mainBundle;
mainBundle = CFBundleGetMainBundle ();

To build the sound for the “B” button, we need to get the path of the sound file we want to play. The name of the sound file is B.aifc. This is the code to get the URL to the found file to play. Put this code after the code where you get the main bundle.

// Get the URL to the sound file to play
bNoteFileURLRef  =    CFBundleCopyResourceURL (
                                             mainBundle,
                                             CFSTR ("B"),
                                             CFSTR ("aifc"),
                                             NULL
                                             );

Note that valid system sound packages are .wav, .aif and .caf files.

Now that we have bNoteFileURLRef set we can associate the sound file with the system sound object bNoteFileObject. The AudioServicesPlaySystemSound function lets you very simply play short sound files.

Add this code after the code that gets the sound file URL.

// Create a system sound object representing the sound file
AudioServicesCreateSystemSoundID (bNoteFileURLRef, &bNoteFileObject);

We finished loading up the sound for the “B” button. We’ll need to load up the sounds for the “E”, “A” and “T” buttons.

Try to code this part yourself. If you get stuck, the viewDidLoad method should look like this when you’re done.

// Implement viewDidLoad to do additional setup after loading the view, typically from a nib.
- (void)viewDidLoad {
    [super viewDidLoad];

    // Get the main bundle for the app
    CFBundleRef mainBundle;
    mainBundle = CFBundleGetMainBundle ();

    // Get the URL to the sound file to play
    bNoteFileURLRef  =    CFBundleCopyResourceURL (
                                                 mainBundle,
                                                 CFSTR ("B"),
                                                 CFSTR ("aifc"),
                                                 NULL
                                                 );

    // Create a system sound object representing the sound file
    AudioServicesCreateSystemSoundID (bNoteFileURLRef, &bNoteFileObject);

    // Get the URL to the sound file to play
    eNoteFileURLRef  =    CFBundleCopyResourceURL (
                                                 mainBundle,
                                                 CFSTR ("E"),
                                                 CFSTR ("aifc"),
                                                 NULL
                                                 );

    // Create a system sound object representing the sound file
    AudioServicesCreateSystemSoundID (eNoteFileURLRef, &eNoteFileObject);

    // Get the URL to the sound file to play
    aNoteFileURLRef  =    CFBundleCopyResourceURL (
                                                 mainBundle,
                                                 CFSTR ("A"),
                                                 CFSTR ("aifc"),
                                                 NULL
                                                 );
    // Create a system sound object representing the sound file
    AudioServicesCreateSystemSoundID (aNoteFileURLRef, &aNoteFileObject);

    // Get the URL to the sound file to play
    tNoteFileURLRef  =    CFBundleCopyResourceURL (
                                                 mainBundle,
                                                 CFSTR ("T"),
                                                 CFSTR ("aifc"),
                                                 NULL
                                                 );

    // Create a system sound object representing the sound file
    AudioServicesCreateSystemSoundID (tNoteFileURLRef, &tNoteFileObject);
}

Creating Our IBActions

Our BEAT buttons need to be associated with IBActions to make them do something. First, let’s declare the methods. Open BickboxxViewController.h and add this code before the @end line.

- (IBAction)bSound:(id)sender;
- (IBAction)eSound:(id)sender;
- (IBAction)aSound:(id)sender;
- (IBAction)tSound:(id)sender;

Your BickboxxViewController.h should now look like:

#import <UIKit/UIKit.h>
#import <AudioToolbox/AudioServices.h>

@interface BickBoxxViewController : UIViewController {
    CFURLRef        bNoteFileURLRef;
    SystemSoundID    bNoteFileObject;
    CFURLRef        eNoteFileURLRef;
    SystemSoundID    eNoteFileObject;
    CFURLRef        aNoteFileURLRef;
    SystemSoundID    aNoteFileObject;
    CFURLRef        tNoteFileURLRef;
    SystemSoundID    tNoteFileObject;
}

@property (readwrite)    CFURLRef        bNoteFileURLRef;
@property (readonly)    SystemSoundID    bNoteFileObject;
@property (readwrite)    CFURLRef        eNoteFileURLRef;
@property (readonly)    SystemSoundID    eNoteFileObject;
@property (readwrite)    CFURLRef        aNoteFileURLRef;
@property (readonly)    SystemSoundID    aNoteFileObject;
@property (readwrite)    CFURLRef        tNoteFileURLRef;
@property (readonly)    SystemSoundID    tNoteFileObject;

// The new code you added
- (IBAction)bSound:(id)sender;
- (IBAction)eSound:(id)sender;
- (IBAction)aSound:(id)sender;
- (IBAction)tSound:(id)sender;

@end

Close the file and open BickboxxViewController.m. Add the implementation to make the IBAction methods make the appropriate system sounds by invoking the AudioServicesPlaySystemSound method.

To play the “B” sound, the implemented method should make a call to AudioServicesPlaySystemSound and use the bNoteFileObject we created above. Add this after the property synthesis code:

- (IBAction)bSound:(id)sender {
AudioServicesPlaySystemSound (self.bNoteFileObject);
}

Add similar implementations for the “E”, “A” and “T” sounds as well.

For reference, the top of BickboxxViewController.m should look like:

#import "BickBoxxViewController.h" 

@implementation BickBoxxViewController

@synthesize bNoteFileURLRef, bNoteFileObject, eNoteFileURLRef,
eNoteFileObject, aNoteFileURLRef, aNoteFileObject,
tNoteFileURLRef, tNoteFileObject;

- (IBAction)bSound:(id)sender {
    AudioServicesPlaySystemSound (self.bNoteFileObject);
}

- (IBAction)eSound:(id)sender {
    AudioServicesPlaySystemSound (self.eNoteFileObject);
}

- (IBAction)aSound:(id)sender {
    AudioServicesPlaySystemSound (self.aNoteFileObject);
}

- (IBAction)tSound:(id)sender {
    AudioServicesPlaySystemSound (self.tNoteFileObject);
}

For the last piece of code, we need to clean up our mess so we don’t have memory leaks. At the bottom of BickboxxViewController.m, add these lines to your dealloc method:

- (void)dealloc {
    [super dealloc];
    AudioServicesDisposeSystemSoundID (self.bNoteFileObject);
    AudioServicesDisposeSystemSoundID (self.eNoteFileObject);
    AudioServicesDisposeSystemSoundID (self.aNoteFileObject);
    AudioServicesDisposeSystemSoundID (self.tNoteFileObject);
    CFRelease (bNoteFileURLRef);
    CFRelease (eNoteFileURLRef);
    CFRelease (aNoteFileURLRef);
    CFRelease (tNoteFileURLRef);
}

We’re done coding. Build and Go the project to make sure nothing is on fire. Your buttons won’t make any sounds yet. We’ll need to link our code to our interface.

Linking the buttons to the code in Interface Builder

Now that our code is done, we can link our buttons to our code. We’ll start with the “B” button link it with the bsound method. To do this, open up BickboxxViewController.xib.

Control+Click on the File’s Owner object so we can link our “B” button to our bsound.

Drag from the bSound in File’s Owner to the “B” button in the View.

An overlay should pop up. Choose Touch Down. The normal default is to execute the action when the finger is lifted from the button. We don’t want that. Soundboards don’t work that way. This will call the bSound IBAction method when the button is pressed down.

Do this linking with the rest of the buttons. When you’re done, Control+Clicking File’s owner should look like this.

Here’s a video of me using Bickboxx to practice for my opening act for Paul Oakenfold.

You’re done!

That’s it — you’re done! Compile and run this and you’ll be DJ-ing parties with Moby in no time.

Again, you can download the source from social coding site Github. Feel free to file issues here if the code needs fixing or enhancing.

Homework

Are you ready to apply your newfound knowledge? Solidify it with this extra credit assignment.

Your homework: Add a new button and a new sound to the project.

If there are any typos, problems, suggestions, or questions, let me know here in the comments.

Related research and analysis from GigaOM Pro:
Subscriber content. Sign up for a free trial.

• Mobile Q4: All Eyes Were on Android, 4G and the Rising Tablet Tide
• Report: A Mobile Video Market Overview
• In Q3, the Tablet and 4G Were the Big Stories

• Create and run a Navigation-Based Application from XCode
• Create and add a user interface, designed in Interface Builder, as a sub-view to a navigation based application
• Navigate to sub-views from a UITableView
• Allow sub-views to access application data

Creating and Running a Navigation-Based Application in XCode

Let’s start off by opening up XCode and creating a Navigation-Based Application.

Click Choose… and give your application the name BasicNavigation. Once completed, your project window should look like this.

At this point, if you click “Build and Go” and have your project selected to run on the iPhone simulator, you should see the application launch and display a bare UITableView, with undefined row elements. No worries, this is going to change very soon. Your app at this point should look like the following below.

Adding a Sub-view (Designed in Interface Builder) to a UITableView

We are now going to add a sub-view to our application. This sub-view will consist of three key elements.

• A Header File (*.h file extension) — Used for defining methods and variables to be used by an accompanied implementation file.
• An Implementation File (*.m file extension) — Used for implementing methods and accessing variables defined in an accompanied header file. This is where we will place code for view specific logic and functionality.
• An Interface File (*.xib extension) — Used for defining the visual look of the view, using Interface Builder.

In XCode, within the project area on the left, right-click on the Classes folder and select Add, then New File…. You will be presented with the following dialogue.

Make sure you’ve selected Cocoa Touch Classes on the left and select the file template for UIViewController subclass as illustrated above, and click Next. You will be presented with a dialogue in which you will assign a name for this asset. Name this file SubViewOneController.m and make sure the checkbox for Also create ‘SubViewOneController.h’ is checked as well. Click Finish when this is done. The dialogue should look like the following, before clicking on Finish.

At this point, you will see two additional files in the Classes folder that we’ve just added. So far we’ve added a header file (SubViewOneController.h) and an implementation file (SubViewOneController.m), which takes care of two out of three key elements. We’ll now add the last element here before moving on towards implementation.

In XCode, right-click the Resources folder and select Add, then New File…. On the left, select User Interfaces and select View XIB and click next. In the next dialogue, you will give this user interface a name. Type SubViewOne.xib under File Nam” and click Finish. These steps are illustrated below.

The contents of your project window should now look similar to the illustration below.

Open the file SubViewOneController.h and add the following code:

#import <UIKit/UIKit.h>

@interface SubViewOneController : UIViewController {
	IBOutlet UILabel *label;
	IBOutlet UIButton *button;
}

@property (retain,nonatomic) IBOutlet UILabel *label;
@property (retain,nonatomic) IBOutlet UIButton *button;

- (IBAction) OnButtonClick:(id) sender;

@end

Open the file “SubViewOneController.m” and add the following code:

#import "SubViewOneController.h"

@implementation SubViewOneController

@synthesize label, button;

- (id) init {
	self = [super init];
	if (self != nil) {
		// set the title of this view
		self.title = NSLocalizedString(@"Subview One", @"");
	}
	return self;
}

- (IBAction) OnButtonClick:(id) sender {
}

- (void)didReceiveMemoryWarning {
    [super didReceiveMemoryWarning]; // Releases the view if it doesn't have a superview
    // Release anything that's not essential, such as cached data
}

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

@end

What we’ve done thus far is write a bit of view controller code. In our code, we’ve declared a variable for a UILabel and a UIButton. We’ve also created a stubbed handler method for responding on the button click action. What we haven’t done yet is create a user interface to go with our view controller code. Let’s go ahead do that now.

In the project window, let’s expand the Resources node, and double click on the file SubViewOne.xib. You will then see Interface Builder open this file and be presented with a blank View file. In the menu bar, click on Tools, then Library. When the Library window opens, click on the Inputs & Values node. The Library window will look this.

Drag a UILabel and a UIButton such that your view mimics the following interface.

At this point, if you have not saved and built your project, please do so by going back into XCode and clicking the Build button. If all is well, everything will build successfully. We’re not done just yet, so let’s head back to Interface Builder.

Highlight File’s Owner and then from the menu bar, click on Tools, then Identity Inspector. In the Class text input, type or scroll down to the menu option that says SubViewOneController. Your view properties should now look similar to the following.

In the next steps we are going to wire up the user interface elements of the view we’ve created to the view controller we created earlier. First make sure File’s Owner is selected. In the menu bar, click on Tools, then Connections Inspector.

Under Outlets and Received Actions in the Connections Inspector make the following associations:

• Drag the “button” outlet to the button on the visual interface
• Drag the “label” outlet to the label on the visual interface
• Drag the “view” outlet to anywhere on the visual interface
• Drag the “onButtonClick” action to the button on the visual interface. Select “Touch Up Inside”

At this point we’ve created our first sub-view, however we’re not going to be able to get to it from application just yet. That’s the next step.

Before moving on, go back into XCode and click on Build before moving onto the next part. Your build should compile and the results should report back successfully at this point.

Navigating to a Sub-View from a UITableView

The code below will do the following:

• Sets up an array of views and supplies that array to our UITable as a data source
• Adds multiple sub views to our application using the sub view we’ve designed and written thus far
• Allows us to navigate to different sub views upon view selection from our UITableView

Open the file “RootViewController.h” and add the following code:

#import <UIKit/UIKit.h>

@interface RootViewController : UITableViewController {
	IBOutlet NSMutableArray *views;
}

@property (nonatomic, retain) IBOutlet NSMutableArray *views;

@end

Open the file “RootViewController.m” and add the following code:

#import "RootViewController.h"
#import "SubViewOneController.h"

@implementation RootViewController

@synthesize views;

- (void)awakeFromNib {
	// we'll keep track of our views in this array
	views = [ [NSMutableArray alloc] init];

	// allocate a set of views and add to our view array as a dictionary item
	SubViewOneController *subViewOneController = [[SubViewOneController alloc] init];
	subViewOneController.title = @"Subview One";
	[views addObject:[NSDictionary dictionaryWithObjectsAndKeys:
						@"Subview One",			@"title",
						subViewOneController,	@"controller",
						nil]];
	[subViewOneController release];

	subViewOneController = [[SubViewOneController alloc] init];
	subViewOneController.title = @"Subview Two";
	[views addObject:[NSDictionary dictionaryWithObjectsAndKeys:
					  @"Subview Two",			@"title",
					  subViewOneController,	@"controller",
					  nil]];
	[subViewOneController release];

	subViewOneController = [[SubViewOneController alloc] init];
	subViewOneController.title = @"Subview Three";
	[views addObject:[NSDictionary dictionaryWithObjectsAndKeys:
					  @"Subview Three",			@"title",
					  subViewOneController,	@"controller",
					  nil]];
	[subViewOneController release];

	// create a custom navigation bar button and set it to always say "Back"
	UIBarButtonItem *temporaryBarButtonItem = [[UIBarButtonItem alloc] init];
	temporaryBarButtonItem.title = @"Back";
	self.navigationItem.backBarButtonItem = temporaryBarButtonItem;
	[temporaryBarButtonItem release];

	//set the title of the main view
	self.title = @"Basic Navigation";
}

- (void)didReceiveMemoryWarning {
    [super didReceiveMemoryWarning]; // Releases the view if it doesn't have a superview
    // Release anything that's not essential, such as cached data
}

#pragma mark Table view methods

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

// Customize the number of rows in the table view.
- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
    return [views count];
}

// Customize the appearance of table view cells.
- (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];
    }

    // Set up the cell...
	cell.text = [[views objectAtIndex:indexPath.row] objectForKey:@"title"];

    return cell;
}

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
    // Navigation logic may go here. Create and push another view controller.
	UIViewController *targetViewController = [[views objectAtIndex: indexPath.row] objectForKey:@"controller"];
	[[self navigationController] pushViewController:targetViewController animated:YES];
}

- (void)dealloc {
	[views dealloc];
    [super dealloc];
}

@end

Click the “=Build and Go button in XCode. Our application thus far should now allow us to select a sub view and navigate to it. The application should look similar to the following:

Accessing Global Application Data

In an iPhone application, the Application Delegate can commonly be used to store global variables accessible by all views. You may run into a situation where a view may require data that has been modified by another view or may need to be notified of updates to this data. This piece of the tutorial will cover that very scenario. In this, we’ll be covering some key points in our code:

• Subscribing to central events
• Broadcasting events globally
• Reading/writing global application data

To begin, let’s open the file BasicNavigationAppDelegate.h and add the following code.

#import <UIKit/UIKit.h>

@interface BasicNavigationAppDelegate : NSObject <UIApplicationDelegate> {

	//Application Model Data
	NSString *modelData;

    UIWindow *window;
    UINavigationController *navigationController;
}

@property (nonatomic, retain) IBOutlet UIWindow *window;
@property (nonatomic, retain) IBOutlet UINavigationController *navigationController;

- (void) setModelData:(NSString *)modelData;
- (NSString *) getModelData;

@end

Now open BasicNavigationAppDelegate.m and add the following code.

#import "BasicNavigationAppDelegate.h"
#import "RootViewController.h"

@implementation BasicNavigationAppDelegate

@synthesize window;
@synthesize navigationController;

- (void)applicationDidFinishLaunching:(UIApplication *)application {
	// Configure and show the window
	[window addSubview:[navigationController view]];
	[window makeKeyAndVisible];
}

- (void)applicationWillTerminate:(UIApplication *)application {
	// Save data if appropriate
}

// accessor methods for "data" property

- (void) setModelData:(NSString *) newData {
	modelData = newData;
	[[NSNotificationCenter defaultCenter] postNotificationName:@"dataChangeEvent" object:self];
}

- (NSString *) getModelData {
	if ( modelData == nil ) {
		modelData = @"Hello World";
	}
	return modelData;
}

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

@end

We’ve added a model variable and accessor methods to read and write to this variable. Notice on the setModelData method, how we have the following line [[NSNotificationCenter defaultCenter] postNotificationName:@"dataChangeEvent" object:self]. When this setter method is called, we will be broadcasting an event, dataChangeEvent, to observers of this event notification. For this application, our sub views will subscribe to this event notification.

Go back and open up SubViewController.h and add the following line:

- (void) getModelData;

Now open SubViewOneController.m, and update the code to look like the following:

#import "SubViewOneController.h"
#import "BasicNavigationAppDelegate.h"

@implementation SubViewOneController

@synthesize label, button;

- (id) init {
	self = [super init];
	if (self != nil)
	{
		// subscribe to changes on global data and course of action to take
		[[NSNotificationCenter defaultCenter]
		 addObserver:self
		 selector:@selector(onDataChangeEvent:)
		 name:@"dataChangeEvent"
		 object:nil];
	}
	return self;

}

- (IBAction) OnButtonClick:(id) sender {
	// this view will set our model data
	BasicNavigationAppDelegate *appDelegate =
	(BasicNavigationAppDelegate *)[[UIApplication sharedApplication] delegate];
	NSString *displayString = [NSString stringWithFormat: @"Set By %@", [self title]];
	[appDelegate setModelData:displayString];
}

- (void)onDataChangeEvent:(id) sender {
	[self getModelData];
}

-(void)viewWillAppear:(BOOL)animated {
	[self getModelData];
}

// set our label to reflect the latest copy of the data that we're observing
- (void) getModelData {
	BasicNavigationAppDelegate *appDelegate =
	(BasicNavigationAppDelegate *)[[UIApplication sharedApplication] delegate];
	[label setText:[appDelegate getModelData] ];
}

- (void)didReceiveMemoryWarning {
    [super didReceiveMemoryWarning]; // Releases the view if it doesn't have a superview
    // Release anything that's not essential, such as cached data
}

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

@end

Let’s note the relevant things that are going on here:

• The view subscribes to the dataChangeEvent on the init method. When the dataChangeEvent is fired, the method onDataChangeEvent is triggered and executed.
• On Button click, we will be setting the the model data located in our application delegate. Remember, that in our implementation, whenever that variable is set, the OnDataChangeEvent is fired and all observers of that event will respond to it

Here’s how we know that our sub views are operating off the same global data.

• Click on Sub View One, then click the button in that view. You’ll notice the label will change to “Set By Subview One”
• Click “back”, then click on Sub View Two. Notice the label says “Set By Subview One”
• Click the button, the label should change in Sub View Two to “Set By Subview Two”
• Click “back, then click on Sub View Three. Notice the label says “Set By Subview Two”

Do you notice what’s happening here? Our data is persisting across views and this data can be read and set by any of our sub views. What we’ve demonstrated here are some very basic practices in model-view-control design and implementation. I hope this lesson carries well for you. Happy coding.

Related research and analysis from GigaOM Pro:
Subscriber content. Sign up for a free trial.

• Connected world: the consumer technology revolution
• Survey: the next wave of enterprise mobility
• Tablet market to hit over 377 million units by 2016

For this tutorial we’re going to build a simple clock that is orientation-aware, meaning that when you rotate your iPhone, the time rotates with it. I’m assuming you have a basic knowledge of the iPhone SDK.

To get started, you will need a label for the time and a background image. You will also need a timer. To get started, you must declare your outlets in code before Interface Builder will be able to use them. I’ll show you how to do that now.

Let’s Get Our Hands in Some Code

Edit SimpleClockViewController.h so it looks like this:

#import <UIKit/UIKit.h>

@interface SimpleClockViewController : UIViewController {
	IBOutlet UILabel* clockLabel;
	NSTimer *myTicker;
}

@end

The myTicker is going to be responsible for updating the clockLabel. We will implement that code later.

The next thing you want to do is drag background_image.png to your project (see image below). You can get the image here.

You want to copy the item to the project’s directory so put a check mark next to “Copy items into destination group’s folder (if needed).” Your settings should look similar to this. Click Add.

Open SimpleClockViewController.xib. Drag UIImageView from the Library to the View window. This will act as a placement holder for our background image.

Bring up the Attributes Inspector. Set the Image to background_image.png. Set the Mode to Scale To Fill so that the background_image.png stretches out when we rotate the iPhone.

Bring up the Size Inspector and change the Autosizing settings to look like this. The arrows in the Autosizing box act as outward springs, which cause the view to resize itself proportionally based on the width or height of its superview. The “I”s act as struts that keep a fixed distance when the View is changed when you rotate the iPhone. If that’s hard to visualize, Interface Builder has an animation to the right of the Autosizing box will help you visualize its current settings.

Drag a Label to the View window and resize to approximately the width of the window. Center it. This makes the time larger and also positions the time to be rotated around its center point when you turn the iPhone into landscape mode.

Change the font of the label by selecting the Label and hitting Command-T. Change the settings so you’re using Helvetica, Bold, size 48.

Bring up the Attributes Inspector. Change the Layout Alignment to Center. Again, we’re doing this so the time rotates around its center. Change the font color to white so it looks good on the dark background. It should look similar to this:

Bring up the Size Inspector and change your Autosizing settings to look like the image below. This makes sure the time rotates and positions itself correctly around its center.

Lastly, Control-Drag from File’s Owner to the Label and choose clockLabel when the outlet box pops up. This tells your Label which variable it is in the code.

Save and close Interface Builder. Back in Xcode, open SimpleClockViewController.h and add runTimer and showActivity methods. These declare the functions we’re going to write.

#import <UIKit/UIKit.h>

@interface SimpleClockViewController : UIViewController {
	IBOutlet UILabel* clockLabel;
	NSTimer *myTicker;
}

/* New Methods */
- (void) runTimer;
- (void)showActivity;

Open SimpleClockViewController.m and add the methods we just declared.

- (void)runTimer {
  // This starts the timer which fires the showActivity
  // method every 0.5 seconds
  myTicker = [NSTimer scheduledTimerWithTimeInterval: 0.5
                        target: self
                        selector: @selector(showActivity)
                        userInfo: nil
                         repeats: YES];

}

// This method is run every 0.5 seconds by the timer created
// in the function runTimer
- (void)showActivity {

  NSDateFormatter *formatter =
          [[[NSDateFormatter alloc] init] autorelease];
    NSDate *date = [NSDate date];

    // This will produce a time that looks like "12:15:00 PM".
    [formatter setTimeStyle:NSDateFormatterMediumStyle];

  // This sets the label with the updated time.
  [clockLabel setText:[formatter stringFromDate:date]];

}

The runTimer method only has 1 line of code split into multiple lines. All it does is call the showActivity method every 0.5 seconds.

The showActivity method formats the clockLabel so it looks like “12:15:00 PM” and sets it to the current time. As mentioned above, this method is called every 0.5 seconds.

We want to call runTimer after the view loads. This is a common method that, when Xcode generated SimpleClockViewController.m, they included a method called viewDidLoad. This method is called immediately after the View items are loaded. Find the viewDidLoad method and uncomment it.

Add [self runTimer]; to the end of the method. It should now look like this:

// Implement viewDidLoad to do additional
// setup after loading the view, typically from a nib.
- (void)viewDidLoad {
    [super viewDidLoad];

// This calls the runTimer method after loading
// SimpleClockViewController.xib
  [self runTimer];
}

When Xcode generated SimpleClockViewController.m, they also included shouldAutorotateToInterfaceOrientation. By default, views display only in portrait orientation, so you need to implement shouldAutorotateToInterfaceOrientation method if you want to support other orientations.

Locate the shouldAutorotateToInterfaceOrientation method and uncomment it. You can support only some orientations such as portrait or landscape with Home button on the right, but we don’t need to limit ourselves to those scenarios. We want to support all orientations so the view rotates correctly no matter how we’re holding the iPhone. To do this, replace return (interfaceOrientation == UIInterfaceOrientationPortrait); with return YES;.

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

Now you can build and run it! Hit Command-Left to see your UI rotate with the iPhone simulator. You can Build and Run the project to make sure everything is compiling and running.

Related research and analysis from GigaOM Pro:
Subscriber content. Sign up for a free trial.

• Mobile Q4: All Eyes Were on Android, 4G and the Rising Tablet Tide
• Report: A Mobile Video Market Overview
• In Q3, the Tablet and 4G Were the Big Stories

Let’s get started

1. Open Xcode and choose the “File” menu, in which you’ll click the “New Project…” item.
2. Click “Application” under “iPhone OS” in the list at left.
3. On the right, choose “Navigation-Based Application”. Then click the “Choose…” button. You’ll be prompted to pick a name and location. Type in the name “TAB RSS reader”.
4. Save it wherever you wish.

The Xcode project window will appear, with the standard 3 panes – I recommend pulling the horizontal divider on the right side all the way to the top, since you’ll need that editor area and all the real estate you can give it.

Do you see a “Build and Go” button in the toolbar? Click it, or go to the “Build” menu, and click “Build and Go (Run)” there. It should open the Simulator application and launch a simple iPhone app that displays a blank navigation bar and blank table. Whee! Your first iPhone app. Now let’s sculpt it into something.

The project template that Apple provides has a lot of things already set up to get us started. On the list at the left of the project window, find “MainWindow.xib”, and double-click it. This is the basic framing of your application’s UI. Be careful not to mess around here too much. You just need to do one thing: you should see a “Navigation Controller” window with a basic interface mocked up – double-click on the navigation bar (which has no title in it), and type “The Apple Blog”. Press return. Save and quit Interface Builder.

Click once on “RootViewController.h” in the list, and see the code on the right. Make it look like this:

@interface RootViewController : UITableViewController {
	IBOutlet UITableView * newsTable;
	UIActivityIndicatorView * activityIndicator;
	CGSize cellSize;
	NSXMLParser * rssParser;
	NSMutableArray * stories;

	// a temporary item; added to the "stories" array one at a time, and cleared for the next one
	NSMutableDictionary * item;

	// it parses through the document, from top to bottom...
	// we collect and cache each sub-element value, and then save each item to our array.
	// we use these to track each current item, until it's ready to be added to the "stories" array
	NSString * currentElement;
	NSMutableString * currentTitle, * currentDate, * currentSummary, * currentLink;
}
@end

That’s the declaration file, where we’re telling the compiler what to expect when it runs through the controller logic. Here’s where the real work happens… Open “RootViewController.m“.

You’ll see that there’s more of the basic code to make that table view display – this controller is the table’s “delegate” – the table looks here to find out what it’s supposed to see/display/do in various situations, and sends calls for methods when the user performs various actions.

Change the value of - (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section to return [stories count];

In our declarations, we told it we would have an array (NSMutableArray – a modifiable collection of objects), which we called “stories”. The [brackets] around that bit signify that it’s a message – we’re asking the stories array what its current count is – that is, how many items it has. Our RSS reader will grab as many items as it can (one for each story in the RSS feed), and place them in that array, so this method will tell the table This is how many rows we need: one for each item in the array, or for each item in the feed. Before, it was set to 0, so you’re giving it more information on our array.

Next up, modify the method below the one you just changed, like so:

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
	static NSString *MyIdentifier = @"MyIdentifier";
	UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];

	if (cell == nil) {
		cell = [[[UITableViewCell alloc] initWithFrame:CGRectZero reuseIdentifier:MyIdentifier] autorelease];
	}

	// Set up the cell
	int storyIndex = [indexPath indexAtPosition: [indexPath length] - 1];
	[cell setText:[[stories objectAtIndex: storyIndex] objectForKey: @"title"]];

	return cell;
}

As you can see, we used the “setText:” method to tell the cell what the contents will be. Each row in the table is basically a cell, and its properties are set in this method.

There are 4 methods highlighted in green about 3/4 of the way down – you can delete those if you wish, since we won’t be using them. They have to do with adding/deleting items.

If you were to run the program again now, it still wouldn’t do anything: we haven’t added the ability to download the feed and use it yet, so let’s do that now.

Edit the “viewDidAppear:” method to look like this:

- (void)viewDidAppear:(BOOL)animated {
	[super viewDidAppear:animated];

	if ([stories count] == 0) {
		NSString * path = @"http://feeds.feedburner.com/TheAppleBlog";
		[self parseXMLFileAtURL:path];
	}

	cellSize = CGSizeMake([newsTable bounds].size.width, 60);
}

This is where we tell the parser which feed to download. It calls a method, which you’ll want to paste in now:

- (void)parseXMLFileAtURL:(NSString *)URL {
	stories = [[NSMutableArray alloc] init];

	//you must then convert the path to a proper NSURL or it won't work
	NSURL *xmlURL = [NSURL URLWithString:URL];

	// here, for some reason you have to use NSClassFromString when trying to alloc NSXMLParser, otherwise you will get an object not found error
	// this may be necessary only for the toolchain
	rssParser = [[NSXMLParser alloc] initWithContentsOfURL:xmlURL];

	// Set self as the delegate of the parser so that it will receive the parser delegate methods callbacks.
	[rssParser setDelegate:self];

	// Depending on the XML document you're parsing, you may want to enable these features of NSXMLParser.
	[rssParser setShouldProcessNamespaces:NO];
	[rssParser setShouldReportNamespacePrefixes:NO];
	[rssParser setShouldResolveExternalEntities:NO];

	[rssParser parse];
}

This is a method we’ve added that creates the empty array for stories, creates a parser, and starts downloading the feed. As the parser works, this controller we’re working in will receive the various delegate methods, which you can paste in now:

- (void)parserDidStartDocument:(NSXMLParser *)parser {
	NSLog(@"found file and started parsing");
}

- (void)parser:(NSXMLParser *)parser parseErrorOccurred:(NSError *)parseError {
	NSString * errorString = [NSString stringWithFormat:@"Unable to download story feed from web site (Error code %i )", [parseError code]];
	NSLog(@"error parsing XML: %@", errorString);

	UIAlertView * errorAlert = [[UIAlertView alloc] initWithTitle:@"Error loading content" message:errorString delegate:self cancelButtonTitle:@"OK" otherButtonTitles:nil];
	[errorAlert show];
}

- (void)parser:(NSXMLParser *)parser didStartElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName attributes:(NSDictionary *)attributeDict{
	//NSLog(@"found this element: %@", elementName);
	currentElement = [elementName copy];

	if ([elementName isEqualToString:@"item"]) {
		// clear out our story item caches...
		item = [[NSMutableDictionary alloc] init];
		currentTitle = [[NSMutableString alloc] init];
		currentDate = [[NSMutableString alloc] init];
		currentSummary = [[NSMutableString alloc] init];
		currentLink = [[NSMutableString alloc] init];
	}
}

- (void)parser:(NSXMLParser *)parser didEndElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName{

	//NSLog(@"ended element: %@", elementName);
	if ([elementName isEqualToString:@"item"]) {
		// save values to an item, then store that item into the array...
		[item setObject:currentTitle forKey:@"title"];
		[item setObject:currentLink forKey:@"link"];
		[item setObject:currentSummary forKey:@"summary"];
		[item setObject:currentDate forKey:@"date"];

		[stories addObject:[item copy]];
		NSLog(@"adding story: %@", currentTitle);
	}
}

- (void)parser:(NSXMLParser *)parser foundCharacters:(NSString *)string{
	//NSLog(@"found characters: %@", string);
	// save the characters for the current item...
	if ([currentElement isEqualToString:@"title"]) {
		[currentTitle appendString:string];
	} else if ([currentElement isEqualToString:@"link"]) {
		[currentLink appendString:string];
	} else if ([currentElement isEqualToString:@"description"]) {
		[currentSummary appendString:string];
	} else if ([currentElement isEqualToString:@"pubDate"]) {
		[currentDate appendString:string];
	}
}

- (void)parserDidEndDocument:(NSXMLParser *)parser {

	[activityIndicator stopAnimating];
	[activityIndicator removeFromSuperview];

	NSLog(@"all done!");
	NSLog(@"stories array has %d items", [stories count]);
	[newsTable reloadData];
}

Unfortunately, the NSXMLParser is the only simple XML-parsing tool available on iPhone (some of my favorites from the Mac are missing). So, this means we have to crunch through the file in order from top to bottom. We have a series of strings that we assign values to, and then collect them into story items, which are saved one by one. Once it hits the closing “item” tag, it saves that story, clears out the fields, and starts on the next item until we reach the end of the file. Not my favorite approach, but it works.

Finishing up

We need to shut off any potential memory leaks (it’s a good habit to get into, when you don’t have garbage collection – who needs that anyway?). Drop in this change:

- (void)dealloc {
	[currentElement release];
	[rssParser release];
	[stories release];
	[item release];
	[currentTitle release];
	[currentDate release];
	[currentSummary release];
	[currentLink release];

	[super dealloc];
}

Next, open up “RootViewController.xib“, and hold down the “control” key on your keyboard, while dragging from the “RootViewController” cube icon over to the table view, and release. You should see a list of three items appear, so click on the “newsTable” item. Save and quit Interface Builder.

Build and Go

If you click “Build and Go”, you’ll see the results we have so far. If you were to run this on an actual iPhone and not in simulator, the results would be different slightly: the hardware is slower, and if you’re on EDGE, the RSS feed will take a very long time to download. But, hey, it works! One thing that doesn’t work yet: when you tap on an item in the table, nothing happens. This is default behavior, but let’s make the stories open in Safari – that’s an easy thing to do. Just change this method:

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
	// Navigation logic

	int storyIndex = [indexPath indexAtPosition: [indexPath length] - 1];

	NSString * storyLink = [[stories objectAtIndex: storyIndex] objectForKey: @"link"];

	// clean up the link - get rid of spaces, returns, and tabs...
	storyLink = [storyLink stringByReplacingOccurrencesOfString:@" " withString:@""];
	storyLink = [storyLink stringByReplacingOccurrencesOfString:@"n" withString:@""];
	storyLink = [storyLink stringByReplacingOccurrencesOfString:@"	" withString:@""];

	NSLog(@"link: %@", storyLink);
	// open in Safari
	[[UIApplication sharedApplication] openURL:[NSURL URLWithString:storyLink]];
}

Now, click “Build and Go” again, to see that it works.

Done for Now

You can download the finished project file here if you wish.

Check back here later, and we’ll cover some steps on how to clean up the UI, and add some navigation.

Related research and analysis from GigaOM Pro:
Subscriber content. Sign up for a free trial.

• Mobile Q2: Smartphone growth surges; iPad’s rule continues
• How to Market Your iPhone App: A Developer’s Guide
• Controversy, courtrooms and the cloud in Q1