iPhone in Action

NSValue: Basics & The UIGeometry Extensions

iOS is a programming language that has slowly been built up over years and years of time, and sometimes that shows when you're trying to make functions from two different eras work together. That's especially true when you're working with graphics and you you need to intermix bare structs like CGPoints and CGRects with full-blown objects like NSArrays and NSDictionaries.

In iPhone in Action, we suggested the simplest way to interrelate these two different elements. You can just break apart the structs and then enter their individual elements into whatever class you want. For example, instead of saving a CGPoint, you could save x and y as NSNumbers.

However, there's an even easier answer: use the "SDK Missing Class": NSValue. That's what I'm going to talk about today: first, with its basic functionality, and then with the UIGeometry extensions that are actually what I regularly use.

Uses for NSValue

You should find NSValue useful in quite a few ways. You can:

1. Collect NSValues in NSArrays, NSDictionaries, NSSets, and other collection classes that require objects for entries.
2. Pass NSValues to performSelector:withObject:afterDelays: and other methods that require objects as arguments.
3. Use NSValue for debugging with NSLog.

How to Use NSValue: The Basics

NSValue is a container that can be used to hold other values. You can use it encode entirely arbitrary values of any type. The Apple document pages show a couple of examples of valuesWithBytes:objCType: being used to store a pointer to an object of a specific type:

NSValue *theValue = [NSValue valueWithBytes:&myRange objCType:@encode(NSRange)];

NSValue *theValue = [NSValue value:&myCString withObjCType:@encode(char **)];

I'm unconvinced of its use in cases where NSNumbers or NSStrings could be better used. However, if you create your own structures, this sort of thing can be very useful:

For example, here's a structure that I recently created for use in Reiner Knizia's Kingdoms:

struct GridCell {
    int row;
    int column;
};
typedef struct GridCell GridCell;

I could encode it like this:

GridCell myCell;

myCell.row = 2;

myCell.column = 4;

NSValue *myEncodedCell = [NSValue value:&myCell withObjCType:@encode(GridCell)];

Then I could treat my encoded struct like an object, with all the benefits that allows.

How to Use NSValue: The UIGeometry Extensions

I'm not sure that most programmers will do a lot of that, but, as I've already mentioned, you might regularly work with things like CGPoint, CGSize, and CGRect. Though they don't show up in the Apple documentation page, the header file UIGeometry.h contains short hand factory methods for these and more:

+ (NSValue *)valueWithCGPoint:(CGPoint)point;
+ (NSValue *)valueWithCGSize:(CGSize)size;
+ (NSValue *)valueWithCGRect:(CGRect)rect;
+ (NSValue *)valueWithCGAffineTransform:(CGAffineTransform)transform;
+ (NSValue *)valueWithUIEdgeInsets:(UIEdgeInsets)insets;

Then you just use the appropriate messaging short hand to get your object back out of the NSValue:

- (CGPoint)CGPointValue;
- (CGSize)CGSizeValue;
- (CGRect)CGRectValue;
- (CGAffineTransform)CGAffineTransformValue;
- (UIEdgeInsets)UIEdgeInsetsValue;

Here's an example of creating a NSValue of a CGSize, for use with a method of my own creation called setValue:forKey:inIconifiedDeck.

[self setValue:[NSValue valueWithCGSize:CGSizeMake(cardWidth, cardHeight)]
           forKey:@"size"
           inIconifiedDeck:thisDeck];

And here's an example of getting that CGSize back out of an NSDictionary which contains the NSValue under the key "size":

CGSize deckSize = [[thisIconInfo objectForKey:@"size"] CGSizeValue];

I find that much simpler and more intuitive than putting the individual items into my dictionary (or other collection object) and suspect you will too (though my biggest use for NSValue is certainly with NSLog).

Two Articles About Game Design

Occasionally I publish less technical articles about adapting board games to the iPhone over at BoardGameNews. Here's links to my two most recent.

We just released Reiner Knizia's Kingdoms, a tile-laying game for the iPhone. It led to a BGN article about what makes for a good iPhone game, called "What Makes a Great Mobile Eurogame?"

Three months ago, we released Reiner Knizia's High Society, a card-management auction game for the iPhone. That one caused me to write about my own thoughts of AI, in an article called "Making Computers Think Like Auction Players."

XCode: Build & Archive

One of the newer XCode features that you might not be familiar with is Build & Archive, a very useful system that can make it easy to create ad hocs and store distributions.

To use it, all you have to do is choose "Build > Build and Archive" from your XCode menu (presuming that you have one of the last couple of XCode releases). After your app builds, like normal, you'll see the Organizer pop up. Just click to the left on the menu entry, "Archived Applications". The result should look like this:

You'll note that you have three options. "Share Application" will let you distribute an ad hoc, while the other two have to do with store distributions.

To use one of these, first you need to click on your archived build. You'll need to first open up the program in question by clicking on the triangle (as shown above), then select an individual build--probably the newest one. After that, you select a sharing option, as discussed below ...

Archives & Ad Hocs

If you built an Ad Hoc release, your next step should be to click on the button that says "Share Application". That'll display a pop-up:

You should first double check that the signing identity and profile are right. (I, for one, never trust Apple's automatic choice.) Then you can do one of three things with your ad hoc:

• Distribute for Enterprise. This will create an IPA file and a PLIST which acts as a download manifest. You then create a web page to hold them.
• Save to Disk. The most useful option, in my opinion. It creates an IPA file in a file location of your choice. You can then do whatever you want with it, rather than using the internal 'distribute' or 'email', which are a little feature-poor. Note: this seems to fail currently if you try to overwrite a file with the same name, so be sure to delete any previous IPA first.
• E-Mail. This lets you quickly e-mail out an IPA, but it unfortunately uses Apple's internal mail, which you probably don't. Again, I suggest the 'save to disk' above.

The benefit of this is that you can create an IPA quickly without going through the bother of creating a Payload directory, zipping it, and renaming it. When you distribute your ad hoc, be sure to distribute your ad hoc provisioning profile too!

(If you're not familiar with ad hocs and IPAs, read Creating an Ad Hoc Distribution.)

Archives & Store Builds

You can also use Archive to create a build for the Apple Store and upload it.

The first thing you must do is go into iTunes Connect and enter all the meta-data for your new program or your update. Choose that you're going to upload your binary later, then save everything. If you don't put in the meta-data first, nothing will work.

Next return to XCode, select your 'store distribution' profile, and 'Build & Archive'. This time, after you select your archive, click on 'submit application to iTunes Connect' button. You'll see the following pop-up:

Double-check your signing identity, double-check your app, and then submit. You should get back a message in a minute or two saying that everything's OK.

Note that there is also a 'Validate Application' button. This does all the tests that Apple would usually do before accepting an application. If you're having any problems with your upload, or if you just want to be thorough, do this before submitting.

Warning: Bleeding Edge

Unfortunately, none of these options are quite as user-friendly as I'd like. The worst problem is that none of them have good failure responses. Most of them just don't do anything if there's a problem. This is worst when you're trying to upload your app, because it'll sit for a few minutes and give you a response if it works and site forever and do nothing if it doesn't. It can be hard to distinguish between the two at first (though looking at the Network usage of your Activity Monitor will do the trick).

The upload is also pretty picky. It seems to only work when your app is in the 'Waiting for Upload' state. If you're instead in 'Developer Rejected Binary', no dice.

Nonetheless, for the common situations, and especially for ad hocs, Build & Archive is a very nice time-saver for some very common situations.

Problems: My UIImage Doesn't Display on a Device!

One of the more frustrating problems that you can run into when developing for the iPhone is having everything work great on the simulator, but then fail when you load it onto a real device. One of the more common problems that shows up is when a UIImage that displayed on the simulator is missing on the iPhone.

Some folks trying to use the SplashScreen library have had this precise problem.

The problem is usually one of case. Your Macintosh is (probably) built on a case-independent file system. That means that if you try to load "Splash.png" when the filename is really "splash.png", it'll work fine.

Your iPhone is not case-independent, and thus it will fail to find the same file.

So, if you're unable to see a picture on an actual device, check the case of your file name first.

Converting an iPhone App for the iPad

In January I wrote Creating a First Iphone Game, an article about some of the general techniques learned (and used) in the production of Reiner Knizia's Money, RPGnet's first euro-card game.

Since then, Apple has revolutionized the electronic market again with the release of their iPad, a handheld computer that expands the world of iPhoneOS to a much larger 768x1024 scene. To keep up with the times, we decided to upgrade Reiner Knizia's Money to work optimally on this new device. Our total time spent was somewhere in the neighborhood of 50-60 hours, the majority of which was spent improving our original design to better work with multiple display sizes. What follows is an overview of our thinking and what we did, along with some screen shots of what our app looks like before and after.

You Don't Have to Do Anything

Here's the most important thing you should know as an iPhone developer considering expanding out onto the iPad: you don't need to do anything. Your native iPhone apps should work fine on the iPad. Mind you, they might not look ideal, as your graphics will be blown up in size and the aspect ration is slightly different: 480:320 is 3:2, while 1024:768 is 4:3.

However, there's no point in you doing any work unless you're planning to have the iPad actually look or work differently in some way, even if it just means uploading larger sized graphics for use on the iPad.

Checking for iPads

So, how do you know that your user is using an iPad? Apple has offered a very simple iPad check that you can use, which I won't reprint here as it might still be under NDA. Suffice to say: read the Apple docs about programming for the iPad and make sure that you use some sort of conditional statement to determine whether you're using an iPad.

As an alternative, you might want to check for screen size. That's as easy as making a call to "[[UIScreen mainScreen] applicationFrame]". This actually might be more reliable than specifically looking for an iPad as you can see the exact screen size that a user is using and set up your interface appropriately. That means it's more likely to work in the future when yet another display size appears.

(However, it's not what I did in my conversion, as right now there's no suggestion of there being different sized devices than the two we have, so I wouldn't even know what to plan for.)

Making Your App Display Independent

So, you want to update your app so that it works appropriately for both the iPad and the iPhone. How do you do it? The most important thing is to make your app display independent: you want your app to work (within reason) no matter what display size it's given.

That means you should never have numbers like 480, 320, 1024, and 768 in your app, if you can avoid them. Instead you should be look at the aforementioned "[[UIScreen mainscreen] applicationScreen]" to figure out how much space to work with, then go for there.

In other words use something like this:

tableSize = CGRectMake(0,0,mainRect.size.height,mainRect.size.width);

Not:

tableSize = CGRectMake(0,0,320,480);

Given these dynamic possibilities, how do you deal with complex layouts? When rewriting Reiner Knizia's Money I decide to do all of my layout as percentages. Thus I could say, for example, that my draw deck should be placed at 50,50--which is to say the middle of the screen--and then calculate exactly what that meant at run time. In order to make this work, I just translated the coordinates whenever I wanted to write to the screen:

-(CGPoint)translateCoords:(CGPoint)percentCoords {

    float newX = (percentCoords.x * screenSize.size.width) / 100; 
    float newY = (percentCoords.y * screenSize.size.height) / 100;

    return CGPointMake(newX, newY);

}

In this example, screenSize was the frame that my cardtable was handed when it was started up.

This methodology gave me some interesting advantages. Not only can Money run on several different devices, within reason, but it can also run in different frames. I no longer have to hand off my complete application frame to the card table.

In any case, you need to make your app display-independent in one way or another as a strong first step to porting your iPhone app to the iPad.

Making Your App Orientation Independent

If you're going to be doing native programming for the iPad, then you also need to be ready for some new human-interface guidelines. Most notably, your app now must work in equivalent orientations (e.g., if it works in LandscapeLeft it must also work in LandscapeRight) and it should work in all four rotations (including PortraitUpsideDown, which hadn't really been supported in some older versions of the OS).

The immediate application of this is easy enough. Edit shouldAutorotateToInterfaceOrientation:, which you should find in your view controller, and have it respond YES either for equivalent orientations or for all orientations, as appropriate for your app. I also find this method a good place to put changes that should happen whenever a rotation event occurs.

(You can alternatively listen for orientation-change notifications, if you prefer. I've seen some claims that this latter method is more reliable, and it may well be in cases where parent view controllers respond NO to certain orientations.)

Just telling the iPhoneOS that it's OK to use different orientations usually isn't sufficient, however. If you leave the iDevice to its own devices, it'll somewhat stupidly smoosh stuff from one orientation into another. If you get lucky, they'll both fill the screen, but you're unlikely to get lucky enough to have both of them look good.

That's probably not good enough if you're taking the time to create a solid, iPad-optimized program. Instead you want to carefully think how the view should change from one orientation to another.

Below is an example of one such orientation change that I programmed for the iPad version of Reiner Knizia's Money. The core class ("graphicMenu") depicts a background and several selections, which are effectively buttons placed atop the background. It reports out whenever a user pushes a button. My original version of the class only worked in landscape mode, where it showed two columns of buttons. To work in portrait, I decided that the class should instead show just a single column of buttons:

(Note that this first screen shot actually shows iPhone screens; once you go to the trouble of making your app orientation-independent for the iPad, you can then use those lessons learned to improve the experience of your iPhone users as well.)

The application of this orientation change is slightly time-consuming, but simple. Whenever an orientation change occurs, I swap the background of the UIView, then I move all of the extant buttons, to be centered either in one column or two columns as possible.

Some of the classes in Reiner Knizia's Money were even easier to deal with. For the options page, I just needed to resize the UITableView appropriately.

However, there was one class that gave me considerable trouble: the actual card table that's at the heart of Reiner Knizia's Money. On the iPhone, it's set up to use every square inch of space that it can. It depends upon the long edges of the screen surrounding the player to give him additional space to see his bid and his score and it depends on the long edges of the screen across from him to place the product logo and a menu button.

There was no practical way to make the app work in all orientations on the iPhone, because the short edge of the phone would just be too small to display everything, but the increased size of the iPad--along with its aspect ratio which was less rectangular than the iPhone--gave us another option: we could set the table aside as a square in the middle of the screen and then use the edges of the screen for some of those other informational elements. Below is what the result looked like, this time displayed on an iPad, as we could not backtrack this change to the iPhone, because the result would have been much too small:

As you can see, the central table doesn't actually change at all. However the positioning of other information, such as the score, the logo, and the position of buttons flows into the (new) edges of the device. It certainly isn't the only way to support multiple orientations, but I think it's a good one when you need to maintain some consistency of spacing within some part of your application.

Taking the Best Advantage of Size

The iPad is flat-out bigger than the iPhone. Giving your images higher resolution and giving your users more space to touch your screen objects will both be big wins for your program. However, to produce the best iPad program that you can, you also need to think outside the box--literally, outside the box that you placed your iPhone display in. Can you make use of the new screen space in some way that is more advantageous than simply doubling the size of all of your graphics?

I think we did that in Reiner Knizia's Money, and to show how I'm going to put some iPhone and iPad screens side by side. In each situation I've shrunk the iPad screen by 50% for better comparison.

The CardTable Display. You've already seen one display of our new cardtable display. What may not be immediately obvious is that the cards are smaller relative to the display as a whole. Whereas our screen size went up from 480x320 to 1024x768, our cards only increased from 110px tall to about 175px tall. That's because the cards on the iPhone had a lower bound determined by pure readability, while on the iPad we just needed to make sure that they were larger enough to remain the clear focus of the app.

Because we could make our cards smaller (relatively), we had more room for everything else. This allowed us to push the buttons and score off the table, making them more usable and more attractive. As a result we could also increase our max player count from 4 to 5, because we didn't have to "waste" part of our table space on those aforementioned buttons and other writing. Here's a comparison of before and after:

Help Screen. More generally, the iPhone screen really forces you to be utilitarian, while the iPad screen offers you more opportunity to make your app really beautiful.

The first thing I noted when I started redoing my help screens for the iPad was that I could put all of our information on one screen. But I didn't want to just drop a ton of text onto the large iPad screen, so instead I carefully crafted an attractive graphic, really showing off the improved display of the iPad to its best ability:

Conclusion

As I said at the start of this article, the whole conversion and expansion effort for creating our new iPad version of Reiner Knizia's Money took somewhere in the range of 50-60 hours. It would have been a lot faster if I'd done a good job of abstracting display locations from the start.

I think the results speak for themselves. The new version of the game is much more attractive and has some enhanced functionality, notably the ability to play with a fifth player.

There's still more we could do. Most notably, I'm considering taking several of the buttons which appear on the "menu" page (e.g., rules, credits, options) and just placing them straight on my game-playing page. After all, I've got the space set aside on that sidebar. Why not "think outside the box" and use it, even if it makes the two versions of the app work slightly differently? Really, that's the goal: making the app take best advantage of whichever platform it happens to be running on.

If you'd like to see this all in action, please pick up a copy of Reiner Knizia's Money from the iPhone App store. As of this writing, version 1.07 of the game is available, which is our last iPhone-only version. We've been approved for release of a universal app, which means that as soon as the iPad is available (on Saturday, April 3), you'll be able to download the 1.10 update, which includes all of our iPad extensions.

Core Data, Part 7: Lightweight Migration

In a previous article, I talked about the feared Core Data error, "The model used to open the store is incompatible". As I said at the time, it comes about when you've been running a Core Data program, then you go back and make a change to the underlying Data Model.

This is easy enough to fix when you're in development mode. As long as you don't care about losing the data you've entered into your program through use, just delete it on your testing device or in the Simulator by touching the app, waiting for it to shimmer, then hitting the "X". When you recompile, everything will work fine.

However, you can't do that once a program has been released. Fortunately, Core Data includes migration tools to help you get the database in your live program upgraded to match the updated model in your source. And, if you've made simple Model changes, the migration is called "lightweight", which means that it's almost entirely painless--as long as you know what you're doing, and this article should make sure you do.

Here's what you'll need to do:

1. Verify that you can use lightweight migration.

You can only use lightweight migration if you're doing a simple, obvious change to your data model. Fortunately, that includes adding a relationship or an attribute, and that's exactly what you'll be doing most of the time.

If you want to do more, that's beyond the scope of this article, but you can read the Apple Documentation.

2. Add a new model version.

Click on your data model, then choose "Design > Data Model > Add Model Version". Where you previously had an "xcdatamodel" file, you should now see an "xcdatamodeld" folder that contains your original "xcdatamodel", plus a new copy of it numbered with a "2".

For example, my "Money.xcdatamodel" was put into the "Money.xcdatamodeld" folder and cloned as "Money 2.xcdatamodel", as shown in the picture below.

3. Make your changes.

You should not have made any changes prior to adding that new model version. If you did, this upgrade will NOT work.

Now that you've created a new model version, you should edit the new one, adding the attributions, relationships, or other simple updates that you want.

4. Change your current verison.

When you're all done, click on the new version, then select "Design > Data Model > Set Current Version". This will make it so that the new, updated version of your model is now the one being used by program.

5. Update your persistentStoreCoordinator call.

By default, Xcode should have created a persisentStoreCoordinator method for you when you created your project. You now need to modify that by adding two options which tell the coordinator to attempt a lightweight migration whenever it's run.

Here's the updated coordinator, from my Money program:

- (NSPersistentStoreCoordinator *)persistentStoreCoordinator {
    
    if (persistentStoreCoordinator != nil) {
        return persistentStoreCoordinator;
    }

    NSURL *storeUrl = [NSURL fileURLWithPath: [[self applicationDocumentsDirectory] stringByAppendingPathComponent: @"Money.sqlite"]];
    
    NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys:
        [NSNumber numberWithBool:YES],
            NSMigratePersistentStoresAutomaticallyOption,
        [NSNumber numberWithBool:YES],
            NSInferMappingModelAutomaticallyOption,
        nil];
    
    NSError *error;

    persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc]
        initWithManagedObjectModel: [self managedObjectModel]];

    if (![persistentStoreCoordinator addPersistentStoreWithType:NSSQLiteStoreType
        configuration:nil URL:storeUrl options:options error:&error]) {

        NSLog(@"Could Not Start Peristent Store: %@, %@", error, [error userInfo]);
    }    
    
    return persistentStoreCoordinator;
}

If you compare that to the original, you'll see two notable changes. First,an options dictionary is created with two objects, then options is passed as an argument to addPersistentStoreWithType: ...

5. Prefill Any Data

You may now need to prefill the new attribute or relationship you created, to make sure that your data content catches up with the new data field. Here's a sample of some code I used in my Money program:

-(void)upgradePath {

    int upgradeV = [[cardDecks getOptionStringForKey:@"upgradeVersion"] intValue];
    
    if (!upgradeV || upgradeV <= 1) {
        int cardBackNum = [[cardDecks getOptionStringForKey:@"cardBack"] intValue];
        NSString *thisBack = [self cardBackForInt:cardBackNum];
        
        [cardDecks setCardBacks:thisBack forType:nil];
        [cardDecks setOptionString:@"2" forKey:@"upgradeVersion"];
    }

}

Most of these method calls are internal to my own program. However, the general philosophy should be quickly adaptable.

First, you want to maintain some variable (probably in Core Data) that keeps track of how far you've updated your data to match your database. Here, if a user skips this version, but then downloads the next which has another data content change, he'll still be back at "upgradeVersion" 1, and so the program will know to do the 2nd upgrade as well as any newer ones.

Second, you want to fill your new relationship or attribute with some rational information. In this case, I went off and I set the "cardBack" (which was my new relation) for the entire deck to a standard cardBack selected by the user in an option file.

Your Mileage Will Vary, but the core ideas will be similar.

6. Make clean.

Before you recompile, do a "Build > Clean All Targets". If you do not you may get the error, "Can't merge models with two different entities named 'Whatever'", followed by an annoying crash.

Conclusion

Once you've done a lightweight migration once, it should be simple and stress-free in the future. Just follow the same procedures.

Bringing Mü to the iPhone

While working on Reiner Knizia's Money I had the privilege of speaking with designer Steve Blanding, who was working on bringing another popular card game, Mü, to the iPhone. Steve was kind enough to offer me an article on his own design experiences on Mü, which I've printed below. If you're interested in playing the game, you can purchase Mü at the Apple iPhone store.

---

Bringing Mü to the iPhone

by Steve Blanding 

About a year and a half ago I had a Zune. I'd been given one as a gift and my beloved iPod classic was broken. Microsoft had just released a free SDK that let people write code for it. Being the geek I am, I thought it would be a fun project to write a version of Mü that would run on my Zune. My friends all thought I was crazy. Surely it wasn't possible to make a good version of Mü on such a tiny, wimpy device! Nevertheless, I ignorantly forged ahead and a few months later I had a version of Mü that not only worked on the Zune, it worked surprisingly well! What I didn't have was a license to distribute the game. The Zune games market being what it is (non-existent) I didn't see much of a point.

Fast forward a few months. My wife and I had just bought iPhones and suddenly I was looking at some interesting possibilities. Unlike Zune, the iPhone has a very vibrant games market. While I was pretty sure I wouldn't make any serious money doing it (let's face it, the game is a little too complicated to appeal to your average iPhone gamer) I recognized that there just might be a market for an iPhone version of Mü; and besides, I wanted one for myself!

In this article I'll discuss some of the challenges I had to overcome and some of the things that I learned along the way.  Perhaps you'll find it interesting.

Becoming Legal

The first hurdle that I had to overcome was the fact that Mü is a copyrighted game. I didn't really fancy the idea of stealing Frank Nestel's game and Doris Matthäus' artwork so before I even started writing code I sent email to Dr. Nestel, explained what I wanted to do, and asked if he would be interested in licensing his game. Happily he replied in the affirmative.

I probably don't need to tell you that the internet is a pretty wonderful thing. Thanks to the magic of the internet, finding Frank's contact information was extremely easy and we were able to handle pretty much everything via email. Still, conducting international business is never without its challenges. He's in Germany. I'm in Seattle. Luckily his English is way better than my German. Negotiations went fairly quickly since we were both pretty enthusiastic from the start but it still took quite some time to actually get a contract signed. In the mean time, I had begun development in earnest.

Preparing for Development

When this project started, I hadn't used a personal computer made by Apple since the 1980s. Since iPhone development requires a Mac, I had some shopping to do. I decided that the cheapest and quickest way to get things going would be to buy a used Mac Mini. My wife thought I was nuts when I spent most of a Saturday driving to some stranger's house to buy one that he'd advertised on Craig's List. It turned out to be a pretty good way to go though. I love the portability of the machine and while it's not the fastest Mac out there, it's more than powerful enough for iPhone development.

The other hurdle I had to overcome was that I had to learn the development environment. Luckily that didn't prove to be too difficult. Apple's on-line documentation and videos are surprisingly good. If anything, there was too much information. Objective C isn't my favorite language but it's not too bad. I've never been much of a language bigot. Unfortunately, since Zune development is typically done in C#, virtually none of the code that I'd done for the Zune version could be used unaltered. I had to essentially re-write the entire game from scratch. Still, that was probably a good thing. It forced me to reevaluate most of the decisions that I'd made on the first version and the result was a much stronger game.

I spent several weeks just pouring over Apple's documentation, trying to learn the environment and absorbing as many of Apple's recommended best practices as I could. I installed the SDK, I played around with sample code. I familiarized myself with the environment. I watched scores of video presentations. Looking back, I'm glad I did. All of that initial groundwork would eventually pay off when I submitted Mü to Apple and they approved it in just two days.

Screen Size

One major hurdle that any developer has bringing anything to a portable platform such as the iPhone is the small screen. The iPhone's 320x480 screen is pretty big for a hand-held device (that's twice as many pixels as there were on my Zune) but it's still pretty cramped. Furthermore, those pixels are crammed onto a screen that's only 3 inches high so coming up with cards that are readable becomes a huge challenge.

The cards underwent several design changes. I started with raw scans of the original cards shrunk down to 40x65 pixels. While that had worked OK on the Zune, that turned out to be way too small for the iPhone so I started over, this time with cards that were shrunk down to 44x70. That was still too small but I couldn't really go much bigger and still leave room for bidding areas for each player so I decided that I had to make some subtle changes to the card design.

The first thing I did was get rid of most of the white border around each card. I kept all of Doris' lovely artwork but made all of the elements on each card just a little bit larger. The numbers were pushed a little bit closer to the color bands and the color bands were enlarged so that they more completely filled each card. That left me with virtual cards that looked almost undistinguishable from the original cards but if you look closely, you might notice that the numbers are actually a bit larger.

The next thing that I did was dramatically over-saturate all of the colors on the cards. I found that the original suit colors were far too difficult to distinguish when reduced to those sizes. Over saturating and slightly altering all of the colors made it much easier to tell blue from green from black.

I finally had cards that were readable and still looked like Doris' originals but that still wasn't good enough. The ornate numbers on the cards made them a little difficult to read and one of my testers was really pushing for a solution that was more friendly to the color-blind. I was really reluctant to abandon any elements of Doris' card design but I finally realized that it had to be done. Not wanting to completely abandon the traditional design, I left the traditional cards in the game as an optional setting but the default card set was changed to use the cleanest font I could find and different symbols were used as the pips of each suit.

original colors

traditional cards

final design

Screen Layout

The next difficult decision I had to make was how to arrange all of the game elements.  I had originally thought that I would lay out the screen in landscape mode as I had done on the Zune (right) but the more I experimented with my mock-ups the more I began to drift away from that decision. I realized that if I used the standard iPhone OS elements of a navigation bar at the top and a status bar at the bottom, I'd be left with a nearly perfect square in the center of the screen (below). That would give me a natural place to put menu icons and status text and allow me to follow iPhone conventions as much as possible. Following iPhone conventions would mean that users would feel more at home with the user interface and it would also make it possible for me to use many of the built-in features of the iPhone operating system.

I also realized that when I hold my iPhone, it just feels more natural in the portrait orientation. Landscape is fine for two-handed action games like shooters and the like but for a card game, where one hand cradles the device and the other hand is used to interact with the game, portrait mode just feels more natural to me. That's a personal preference of course but hey, it's my game so I get to do what I like.

Early in the development process I realized one other unanticipated benefit of sticking with portrait mode. I could use the iPhone's built-in accelerator functionality to attach subordinate UI screens to the two landscape orientations. I decided to use the left landscape orientation to display the summary cards and the right landscape orientation to display a score sheet.

The game screen can still get quite crowded because I had to make it possible to represent the scenario where the maximum of six players have bid nearly all of their cards, and I needed room for essential scoring information, player names, link status and bidding feedback. Despite being a little crowded, I think it works pretty well.

One request that I've had from time to time is to display points taken during the current hand while the hand is in progress. Early on I decided not to do that for a number of reasons: first, it would be yet another set of numbers on an already crowded screen; second, it's information that you normally would be required to keep in your head during a real game; but third, and more importantly, if you stop to think about it, it's not really very useful information. Think about it. Are you really likely to change the way you play on a trick based on that knowledge? Almost certainly not. You're going to try to give as many points to your team as you can while keeping as many points away from your opponents. It doesn't really matter if the bid is already made or not. The only scenario where it might matter is if you've already got the result you wanted and you're deciding whether to give a point card to a partner or trying to keep it for yourself, and that scenario really isn't all that important in the grand scheme of things. If you're the type of player for whom that one or two points really matters, then you can track the points in your head, just as you would have to do in a live game.

Input Method

Another difficult, and perhaps somewhat controversial decision that I had to make was to decide how the user would select, bid, and play cards.  I looked at several different methods before finally making a choice.

The most obvious method for playing a card would be simply to allow the player to touch the card he wants to play. On its surface this seems like a good idea but I quickly rejected it. Fat fingers touching tiny cards on a tiny screen are not very precise. The cards are small enough that it is all too easy to accidentally touch the wrong card. There are few things more frustrating than playing a card by mistake. That clearly wasn't going to work.

Tapping a card and dragging or flicking it to the middle of the screen worked a little better but I still found it too easy to accidentally select the wrong card. What I wanted was an input method that was very clear and as error free as I could make it.

Eventually I settled on an input method where the selected card is always shown in front of the rest of the hand, making it very obvious which one is selected. If you've got the wrong card you can tap on a different one or slide your finger to one side or the other until you find the card you want. An arrow icon appears above the selected card, further reinforcing the selection.  Only after tapping on that icon is the card actually played to the table. This extra step has seemed a little awkward to some but of all the input methods that I experimented with, this one was by far the most error resistant.

Bidding uses exactly the same method except that instead of playing your card to the trick, it pushes your card forward in a "marked for bidding" state.  The icon above the card changes to a down arrow. Touch the down arrow and the card will be pulled back into your hand.  A second icon, pointing to your opponent, is used to lock in your bid and yield control to the next player. This results in an input method that is consistent across the entire game and very resistant to accidental taps, touches or swipes. It may take a little bit of getting used to at first but I remain convinced that it's the best solution.

From the start, I disallowed selecting illegal cards but one of my testers suggested a wonderful finishing touch: that I grey out or dim illegal cards, making it easy to tell at a glance which cards are legal to play and which ones are not.

Artificial Intelligence

Of all the obstacles that I had to overcome on this project, the AI was certainly the most challenging. Mü is a very complicated game with a rich bidding mechanic. When I was doing the initial Zune version I did a lot of research on the topic and I have to say that what I learned was not very encouraging. After decades of research and development, computers are only just now able to play a decent game of Bridge, and that's on a very powerful computer! Card play isn't too terribly difficult but even that's not easy (witness all of the really crappy Hearts games out there) but bidding! that's another matter entirely. Getting bidding right is a notoriously hard problem.

Step one to creating a good game of Mü is just to get the computer to play a hand correctly. I didn't even think about bidding at the start. Card play is complicated by the fact that trump changes dramatically from hand to hand, as do partnerships, and the cards are not all worth the same amount of points. That meant that a lot of the conventional optimization tricks that are used to speed card play in a Bridge game just don't apply. I had to come up with my own optimization techniques, based on some of what I'd seen in Bridge implementations to be sure, but my own nonetheless.

The card play logic in Mü (like most card games) is handled using something called a Monte Carlo routine. In a Monte Carlo routine you start with all of the cards that you know (because they've already been played or because they've been bid or because they're in your own hand) and you randomly assign all of the others. Then you play a number of tricks and you evaluate the outcome. Repeat that process a number of times and whichever card gives the best results, that is the card you play. It's a brute-force implementation that, given enough random samples, and given that you play enough tricks ahead, will result in optimal play. The problem is that on the iPhone we don't have nearly enough computing power to evaluate enough tricks or samples to arrive at optimal play so on top of this foundation I poured a little bit of secret sauce that allows the computer to make slightly better than average choices despite the very limited thinking time. The computer DOES NOT CHEAT but it does get a little bit of help from my experience as a player. There isn't enough time to really analyze the hand properly so it will occasionally make a blunder or two but most of the time it gets it right and in my opinion, that only serves to make the game a little more interesting and lifelike.

Bidding is a much harder problem. At its core, it still works much the same way: you take a whole bunch of random samples, you analyze them, and you make the choice that seems to yield the best results. Unfortunately, if computing power was scarce during card play, it's REALLY scarce during bidding so I had to take a lot of short cuts.  Still, I did manage to leave most of the bidding decisions up to the computer. It analyzes the current bids to determine who it thinks is likely to be chief, who is likely to be partner, who is likely to be vice, and what is likely to be trump.  At each stage in the bidding it needs to decide if it should take chief, take vice, put itself on the hook, position itself to be partner, or just pass. Every major decision is made by playing a number of randomized hands to completion and deciding what it thinks the score in a given situation is likely to be. It doesn't take chief or vice unless it thinks there is a material advantage to doing so within a given margin for error. Deciding what that margin for error should be can be tricky. I probably played thousands of hands where the computer played against me or against itself. I analyzed so many hands that I got well and truly sick of looking at them but the results were worth it. It still doesn't play perfectly but given the limitations of the hardware, I'm very satisfied.  The fact that I can regularly lose to my own game is quite satisfying.

Linked Play

The final challenge, and certainly a formidable one, was getting linked play to work. I really wanted to be able to play a game with several human players, all linked over the network. Getting there turned out to be a lot of work.

I immediately discarded the idea of linking arbitrary iPhones over the internet. That would require some sort of match-making service or dedicated server to enable players to find one another and that was way beyond the scope of what I was interested in doing.  Instead, I focused on linking over Bluetooth. That had some immediate advantages: first, it meant that I didn't also have to implement some sort of chat facility because using Bluetooth implies that all players are within shouting distance of one another; second, the iPhone v3.0 SDK has built in matchmaking facilities for linking players over Bluetooth.  The only real drawback there was that I wanted to be able to link more than two players at a time and nowhere could I find any examples of code that did that. I couldn't even find any games in the App Store that did that. (I'm sure they must exist but I couldn't find any in my admittedly short search.)

Once I'd figured out how to link multiple players, I still had other challenges. Even though I had designed the game from the start with the knowledge that I would be adding networked play, and even though I had experience working on other networked games, I still found it more difficult than I had anticipated. When you have two computers linked together, all playing the same game, you need to be very careful that they both stay in sync. Furthermore, because they ARE separate computers, there is a built-in expectation that they should both be able to be doing different things at the same time. For instance, one player could be reviewing the score sheet while another player is bidding. Keeping all of those states synchronized and dealing with the fact that you could be getting messages (or not getting messages) from another player at any time is really challenging. Despite all of my careful planning, I still went through several builds where I was unable to play more than a hand or two without encountering really strange behavior. Players would play cards that had already been played. I'd end up with multiple partners, or sometimes no partner at all. Cards would mysteriously move about the screen. Good times.

That was complicated further by the fact that none of my beta testers seemed to be much help where multi-player games were concerned. Most of my beta testers lived in different cities (or even countries) and therefore they couldn't really test linked play. Luckily my wife and I both have iPhones and my son has an iPod Touch so I was able to test linked play myself. My son and I played a lot of games but I still wish we'd had a lot more time to test. I'm keeping my fingers crossed that someone won't run into some really hideous bug when playing with six humans all linked over Bluetooth.

There were some other really interesting limitations imposed by the iPhone form factor. The iPhone does not support running more than one application at once and your application can be shut down at any time for any number of reasons. That meant that the game had to be designed from the start to be able to save and resume automatically and with a minimum amount of user interaction.

Furthermore, what do you do if someone gets a phone call or a text message in the middle of your linked game and he has to exit the game to answer it? How do you get that player back into the game? And what if someone has to go home? Do you force everyone to quit the game just because little Bobby's out past his curfew? Clearly I needed to allow players to jump back into the middle of a game in progress and I needed to allow the computer to fill in should someone leave. Making that happen in a way that was as simple as possible for the user was a bit of a challenge.

Localization

Both Frank and I really wanted Mü to be available in more languages than just English. One of the first things that Frank requested was that we do a German version. I was completely on board with that idea, especially knowing that the German board game market is so active, so from the start, I structured the game to allow localization. That turns out to be really easy on the iPhone. The iPhone has built-in facilities for separating localizable resources and bundling multiple languages into the same application package. I also had past experience with localization so I was aware of virtually all of the issues I would come up against. From the start I made sure that any localizable strings used the NSLocalizedString macros. I used icons instead of text whenever it made sense to do so. I was also very careful to avoid writing code that would build sentences from component phrases. That resulted in some redundant strings here and there but it gave me the luxury of rewording longer sentences if they became too long to fit on screen after localization and it meant that localizers were always free to use the proper grammar.

I speak Portuguese so I did a very rough Portuguese translation early on which I used to work out any kinks in the process.  Unfortunately, my Portuguese isn't good enough that I could release THAT version of the game. It's currently being proof-read by a native speaker to fix all of my many embarrassing mistakes.

All of the in-game documentation (and there is quite a bit of it) is displayed using the iPhone's wonderful built-in web controls so I was able to put it all in html files which made localizing the rules and credits a breeze.

Conclusion

This was a phenomenally satisfying project. I feel that I've produced a fantastic game and I've learned a lot along the way. I can now play my favorite card game during my commute! Will it prove to be financially profitable? That remains to be seen but either way it was well worth the undertaking. Bringing a game I love to the iPhone has been a reward unto itself.

Thanks for reading. Now go play Mü!

Creating a First iPhone Game: Output & Input

Today we released our first complete iPhone game, Reiner Knizia's Money. It's a "Eurogame", which means that it's part of a stream of very intelligent game design that's been coming out of Germany (primarily) for the last 30 years. It's full of games that are often quick to play, but have carefully designed mechanics, and allow for a lot of strategy. Depending on how you classify it, Money is either a card game or an auction game. You're trying to use money you're dealt to earn more money, eventually collecting sets of the same currency to earn points.

If you've enjoyed this blog, and want to see what one of our actual designs looks like, I encourage you to buy a copy. We're offering it for $1.99 until Sunday, after which we increase to our normal price of $2.99.

With that crass commercialism out of the way, I'm now going to talk a bit about some of the decisions we made when putting together the game, as a guide to what you might want to consider in your own designs. This is going to be a code-free blog entry. My goal is to talk about higher-level design considerations, specifically on the topics of output and input, which together represent the foundation of the program. If you think the code for any section would be particularly interesting, leave me a note in the comments, and I'll consider it for a future entry.

Choosing the Graphic System

The first step in writing the game was figuring out how to represent the playing field and the cards. Clearly, they'd need to be drawn on the iPhone in some way, but there were several possibilities, including using Core Graphics to write directly to a view, designing with UIImageViews (or something similar), and going with a more complex language like OpenGL.

 I believe that building with Apple's core expertise is likely to benefit you in the long run, as it's probably more likely to be upgraded and improved through future releases. Thus I threw out OpenGL pretty early.

However, I also didn't want to use a higher-level class like UIImageView, because I was afraid it would create additional overhead, and that could really add up, as I'd have almost 70 cards on the screen in Money. That left me with two potential middle grounds: creating each card as a UIView and creating each card as a CALayer of a UIView. To be honest, I'm still not certain how much of an efficiency difference either would have made, but since I know that every UIView is backed by a CALayer, clearly going with a UIView would have meant something more in resource allocation. So I went with the simplest answer possible, the CALayer, which could be created as a sublayer of my main GameTableView.

Choosing an individual object--the CALayer--over something more kludgy--like scribbling card images directly onto the main rectangle of my GameTableView--also offered a few more advantages. First, I could directly access Core Animation--and that's in fact how almost all the animations in the game are managed. Second, it abstracted things well, in the way that you'd expect from an object-oriented program.

That meant that I could actually expand on Apple's basic CALayer a bit, attaching more information to each object. And, I did. When I was done I'd created a subclass called CArdLayer which actually included a number of different CALayers (for the front and back of the card, plus some additional layers to brighten or darken the card) and several properties (most importantly, a tag, which let me uniquely identify the layer).

Just having all of those cards shuffling around as sublayers of a UIView did most of what I wanted. It allowed me to represent a card game. However late in the process I ran into one other problem: I wanted to create some popups and other information that would always appear above my cards.

I discovered that I couldn't guarantee the position of layers relative to each other, but it was a pretty simple matter to instead break out two subviews from my GameTableView and keep the cards on the lower view and the info on the higher one.

Figure 1-1 shows how these various objects ended up laying out in relation to one another.

Before I close out, I should offer one final caveat about my graphic design. There turned out to be some performance problems with the display of my 70 cards, which makes them slower than I wanted when animations like dealing ran on my actual iPhone. My colleague noted that he'd read about some people moving over to OpenGL as a result of similar problems. Fortunately, the performance problems turned out to be related only to 1st generation iPhones, which is what I was testing on. The GPUs on everything newer offered very sprightly animation speeds. So though I'm still not thrilled that 1st-gen iPhones go slower than I'd like, I can now see that it's an issue that affects just a fraction of the user base, and one getting smaller day by day. So for the moment I feel confident in my decision about how to display things graphically, as I go forward.

Designing the Touch Interface

Now that I knew how I was going to display the output of the game, I needed to figure out how to manage the input. That meant building touch interfaces as described on pages 240-252 of iPhone in Action.

I don't find the code itself that interesting. It builds out of touchesBegan:withEvent:, touchesEnded:withEvent:, and touchesMoved:withEvent: as you'd expect. Beyond that it's a rat's nest of conditionals to support three different types of touches for active cards (card selection, card movement, and deck movement--only two of which are used in this particular game) and touches for "nonactive" cards (e.g., actions for decks other than the one you're currently holding), both over multiple game phases.

However, I do think the design of the big-picture input is more interesting, and so that's what I'm going to talk about here.

When designing the input of Money, I set two major goals:

• Every object must do something when touched, to create a playing space that feels alive and three-dimensional.
• The UI must be consistent.

These goals haven't been entirely fulfilled in the first release of Money, but the framework is there, which will allow for self-consistent expansion if the game does well enough to warrant more work.

To accomplish the second goal, of consistency, I broadly defined four types of input. As you'll see, when I had this rich set of gestures in hand, I could then assign actions to most objects on the screen.

• tap-and-release could be used to simultaneously select multiple objects. In Money you bid with your cards by selecting several of them, one at a time, then clicking a "bid" button to mark that you're done.
• tap-drag-and-release could be used to move one object to another, initiating an action. In Money this is used to drag your completed bid to an available set of money, exchanging them.
• tap-and-hold could be used to view information on an object. In Money, this is what allows for actions to occur on most "non-active" cards on the screen. For example, touching an opponent's deck tell you their win-loss stats, touching an opponent's bid makes it easier to see, and touching the draw deck tells you (approximately) how many cards are left.
• double-tap could be used to initiate a default action for an object. This is not coded into the game yet, but in a future revision you'll be able to continue to tap-drag-and-release to exchange your bid with an available set of money, or you can alternatively double-click on an available set of money to do so automagically.

The trick of overloading this many input functions is making sure that they don't bash into each other. For the purposes of Money, all of the single-tap functions are singular: no object supports more than one of them, and the interface strives to make it obvious which you'd want to use on each place. tap-and-release and tap-drag-and-release are only used for manipulating your active deck of cards while tap-and-hold are only used for revealing information on other objects.

Implementing the double-taps is a bit trickier, because it means you need to slightly delay your single-tap results, so that they don't show up when a double-tap is intended. That's the main reason that they haven't gone into the game yet.

However, as soon as they do, I think we'll make an intuitive interface even stronger, and that we'll be creating a model of interactivity that we can continue using across similar games. (There are also still a few objects that don't have touch-and-hold info--namely the two lots, our game logo, and our score info--mainly because we're still thinking about the best info to include for each.)

Conclusion

So those are my thoughts on how we designed input and output for our first iPhone game. I'm considering a future article talking about how we designed the game infrastructure. In the meantime you can read a companion article on what was specifically required to adapt an existing game over at BoardGameNews.com.

And finally I'll again encourage you to buy a copy of Reiner Knizia's Money if you're interested. I hope that knowing a bit about how it was designed will help you enjoy the game that much more!

2009 Table of Contents

2009 not only saw the actual publication of iPhone in Action, but also the posting of many (hopefully) helpful articles here, on the iPhone in Action blog. To help make those articles continually useful and accessible, this article supplements our tags by organizing all of the articles based on where they would have appeared if published in the iPhone in Action book. A few things are listed in multiple places.

Chapter 2: Web Development or the SDK

• Presentation: Web Development or SDK: A slide show derived from chapter 2 of our book.

Chapter 7: Building Web Apps with Dashcode

• Dashcode: setCurrentViewWithTransition: A simple transition animation in Dashcode.

Chapter 9: SDK Programming for Web Developers

• All About Casting: About casting generally, and how it relates to some of Objective-C's multiple families of classes. 

Chapter 10: Learning Objective-C and the iPhone OS

• Creating Delegate Protocols for the iPhone: How to create your own delegate protocol. (Sometimes the article title just explains itself.)

Chapter 11: Using Xcode

• The iPhone Simulator & Performance: How the iPhone Simulator can give you too good a view of your app.
• Errors: No Provisioned iPhone OS Device is Connected: An annoying error when trying to build to a device. 
• Problems: Can't Build >> Clean: When the "Build Clean" option doesn't show up.
  

Chapter 13: Creating Basic View Controllers

• Table Tricks & Tips, Part 1: The ContentView: How to create a Settings-like table (now somewhat redundant due to new capabilities introduces in 3.0; overall this is the series of articles impacted most by 3.0 and by later correction, so read with care).
• Table Tricks & Tips, Part 2: Clickable Accessories: So how can you click those checkmarks? Several so-so answers.
•  Table Tricks & Tips, Part 3: Beautiful Tables: How to create multicell table cells from scratch--and how to use color. (Some of this is made easier in 3.0, but sometimes you'll still need to go back to the basics, as described here.)
• Table Tricks & Tips, Part 3B: Content View and Cell Images Done Right: Some corrections to the code in parts one and three.
• Table Tricks & Tips Part 4: Editing Tables: How to use the delegates that support table editing. (Of the table articles, this one remains the most relevant.)  
• Table Tricks for iPhone OS 3.0: A look at the multiple sorts of table cells available in 3.0.
• Beautiful Section Heads: More table tricks to make sections look nicer.

Chapter 14: Monitoring Events and Actions

• UIActionSheet, Part 1: Alternate User Input: Another way to accept input from users.
• UIAlertView, Part 1, The Basics: Another method for accepting simple, action-based input.
• UIAlertView, Part 2, The Complexities: Expanding the above with buttons and delegation.  
• Creating a UITextField ... by Hand: Some quick notes on using alloc/init instead of Interface Builder.
  

Chapter 16: Data: Actions, Preferences, Files, SQLite, and Addresses

• SKDatabase 1.1: A SQLite Library for the iPhone: An SQL library, offered with no guarantees.
  
• Errors: SQLite3 Database Doesn't Remain Updated: How file locking can mess up your SQLite db.
• Core Data, Part 1: An Introduction: Introducing the next generation of data storage.
• Core Data, Part 2: The Data Model: How Core Data models its data.
• Core Data, Part 3: Retrieving Data: How to get data out of Core Data.
• Core Data, Part 4: Inserts, Updates & Deletes: How to put data into Core Data.
• Core Data, Part 5: Prefilling Data: How to insert data in advance.  
• Core Data, Part 6: There's More than One Way to Do It: Moving away from the SQL paradigm.
• NSSet, Part 2: Core Data Integration: How NSSets work directly with Core Data. 
  
• Errors: The Model Used to Open the Store is Incompatible (and other Core Data Errors): A common Core Data error, concerning changing data models.
  

Chapter 19: Graphics: Quartz, Core Animation, and OpenGL

• Thinking About User Interface: How to build within Apple's interface paradigm. 
• Animating Sublayers: How to animate sublayers instead of views.
• Creating a Splash Screen, Part 3: Part of the splash screen class recipe (see Appendix E) that contains an example of animation.
• Warning: kCGColorSpaceGenericRGB is Deprecated: What to do about this graphical warning.
  

Chapter "21": iPhone OS 3.0

• A Preview of iPhone OS 3.0: A list of six new categories of functionality for 3.0. 
• Table Tricks for iPhone OS 3.0: A look at the multiple sorts of table cells available in 3.0.
• Core Data, Part 1: An Introduction: Introducing the next generation of data storage.
• Core Data, Part 2: The Data Model: How Core Data models its data.
• Core Data, Part 3: Retrieving Data: How to get data out of Core Data.
• Core Data, Part 4: Inserts, Updates & Deletes: How to put data into Core Data.
• Core Data, Part 5: Prefilling Data: How to insert data in advance.   
• Core Data, Part 6: There's More than One Way to Do It: Moving away from the SQL paradigm.
• NSSet, Part 2: Core Data Integration: How NSSets work directly with Core Data. 
  
• Errors: The Model Used to Open the Store is Incompatible (and other Core Data Errors): A common core data error, concerning changing data models.

Appendix A: iPhoneOS Class Reference

• NSSet, Part 1: The Basics: Why and how to use an NSSet.
• NSSet, Part 2: Core Data Integration: How NSSets work directly with Core Data. 
• UIActionSheet, Part 1: Alternate User Input: Another way to accept input from users.
  
• UIAlertView Part 1, The Basics: Another method for accepting simple, action-based input.
• UIAlertView Part 2, The Complexities: Expanding the above with buttons and delegation. 

Appendix C: Publishing Your SDK Programs

• Creating an Ad Hoc Distribution: Everything about sending your program out.

Appendix D: Common Errors

• Errors: No Provisioned iPhone OS Device is Connected: An annoying error when trying to build to a device. 
• Errors: SQLite3 Database Doesn't Remain Updated: How file locking can mess up your SQLite db.
• Errors: The Model Used to Open the Store is Incompatible (and other Core Data Errors): A common core data error, concerning changing data models.
• Problems: Can't Build >> Clean: When the "Build Clean" option doesn't show up. 
• Warning: kCGColorSpaceGenericRGB is Deprecated: What to do about this graphical warning.

Appendix E: Class Recipes

• Creating a Splash Screen, Part 1: A new splash screen class, and how to use it.
• Creating a Splash Screen, Part 2: About the class header file.
• Creating a Splash Screen, Part 3: About the class source file.  
  Creating a Splash Screen: splashView 1.1: Updates to the class and improved instructions.
• SKDatabase 1.1: A SQLite Library for the iPhone: An SQL library, offered with no guarantees.
  

NSSet, Part Two: Core Data Integration

In the first part of this article I discussed the basics of NSSet: why you'd want to use one and how you can simply access the contents of an NSSet.

As I wrote at the time, my greatest use of NSSet thus far has come when using Core Data. That's because you get an NSSet whenever you access a one-to-many relationship in Core Data. In this article, I'm going to talk about some of the many ways to use NSSets in that context.

All of my examples will center around the data model that I laid out way back in Core Data, Part Two: The Data Model. You might want to look at the graphics there for clarification, but the basic idea that I'll focus on here is that I have a "CardStack" entitity which includes a one-to-many relationship with a "Card" entity called "cards". In other words, it's an entity that represents a deck of cards.

The Simple Core Data Stuff

The simplest thing you can do with Core Data is directly grab an NSSet by looking up a one-to-many relationship. If you want, you can then turn it into an array with the allObjects method call that I mentioned in the last article:

NSArray *theseCards = [fromDeck.cards allObjects];

You can similarly set one-to-many relationships using NSSet, as I did when I set up my cards initially:

[card setImages:[NSSet setWithObject:

    [self setupCardPic:(CardPics *)myCardPic]]];

This example shows the creation of a one-to-many-relationship with a single element, but it's easy enough to use other NSSet messages such as setWithArray: and setWithObjects: to instead add multiple objects to your relationship.

Note that this methodology is also what I was highlighting in Core Data Part Six, There's More Than One Way to Do It. Accessing an NSSet often represents a cleaner, more intuitive way to get to your data. However, it's not just restricted to the simple NSSet lookups described here.

What follows are some more complex NSSet lookups that really highlight the power of the class--and its powerful integration with Core Data. Each of the examples that follows is part of a method directly built into my CardStack class. Thus you'll see references to things like "self.cards" which is just a way to access the cards relationships from inside a CardStack object.

Enumerating an NSSet

Thus far I've talked about how to access an NSSet mainly by turning it into a different sort of object (an NSArray). That's by no means necessary. You can walk through the contents of an NSSet with the help of an NSEnumerator:

-(NSNumber *)worthOfType:(NSString *)thisType {

    NSSet *theseCards = [self cardsOfType:thisType];

    NSEnumerator *thisEnum = [theseCards objectEnumerator];

    Card *thisCard; float totalWorth = 0;

    while (thisCard = [thisEnum nextObject]) {

        totalWorth += [thisCard.worth floatValue];

    }

    return [NSNumber numberWithFloat:totalWorth];

}

This examples figures out the total worth of the cards of a specific type. Once you create an NSEnumerator object with the ObjectEnumerator NSSet message, you can step through it by continuously sending the NSEnumerator a nextObject message. I'll offer one warning that's also noted in the Apple docs: don't change an NSMutableSet as you're enumerating it. I've accidentally done that more than once, and sure enough, it doesn't work.

Mind you, there's an alternative way to do this same thing with key paths, but stepping through an NSSet with an NSEnumerator will probably have many uses for you.

Predicates & NSSets

The cardsOfType: message call in the previous example shows another way that you can use an NSSet, by filtering it with an NSPredicate.

Here's a complete example, with cardsOfType: actually sending a more generic cardsWithKey:Value: message:

-(NSSet *)cardsOfType:(NSString *)type {

    return [self cardsWithKey:@"type" Value:type];

}

-(NSSet *)cardsWithKey:(NSString *)thisKey Value:(id)thisValue {

    NSSet *theseCards = self.cards;

    NSPredicate *predicate =

        [NSPredicate predicateWithFormat:@"%K=%@", thisKey,thisValue];

    NSSet *filteredCards = [theseCards filteredSetUsingPredicate:predicate];

    return filteredCards;

}

As you can see, a simple three-step process lets you reduce your NSSet to a subset based on a predicate.

First, you create an initial NSSet, here with self.cards.

Second, you create a predicate. This example uses the slightly more complex %K=%@ invocation, which allows me to set the key for my predicate dynamically. What I'm really doing in this example is 'type=%@,thisValue'.

Third, you use the NSSet's filteredSetUsingPredicate: message to turn your original NSSet and your NSPredicate in a smaller NSSet subset.

With this example in hand you can now see how it integrates with the previous example, which let me get the worth of just a subset of all my cards.

Key Paths & NSSets

iPhone in Action doesn't discuss key-value coding, but it's a handy way to quickly apply operators to an entire collection of objects. This means that for NSArrays and NSSets you can compute averages, sums, maxes, minimums, counts, and lots more. You should take a look at Apple's Key-Value Coding Guide for more information.

The earlier NSEnumerator example could have been done with key-value coding and a @sum operator (but I left it as was so that I could show off NSEnumerator). Here's a very similar example that instead uses a key-value path:

-(NSNumber *)selectedWorth {

    NSSet *filteredCards = [self cardsSelected];

    NSString *keyPath = [NSString stringWithFormat:@"@sum.worth"];

    NSNumber *worthSum = [filteredCards valueForKeyPath:keyPath];

    return worthSum;

}

As you can see, you create a key path as an NSString. It must have an operator, which begins with an @ symbol, followed by the property that the operator is working on. Thus, here, we're summing the value of the worth property. You then can apply that to an NSSet with a valueForKeyPath: message. That's surely easier than digging through the entire NSSet as I did the first time through.

This example also shows how you can stack up these different NSSet methods, as my original 'filteredSet' was created with an NSPredicate operation (in the cardsSelected method, not shown).

A more complex keyPath might look something like this:

[email protected]

This shows a different way to invoke a key path. You're putting a property name before the @operator, to dig down through a hierarchy of properties. In this example, the key path wll be operating directly on the self object (the CardStack). It digs down to the cards property, and that's the set that it actually operates on. There it again looks for the @sum of the worth (thus showing a third way to calculate worth using NSSets).

Conclusion

You can do pretty powerful things with NSSets without turning them into NSArrays. This article showed three primary ways to do things: by enumerating an NSSet, by filtering it through an NSPredicate, and by operating upon it with a key value. There's considerable more that you can do with NSPredicates and key values, and you should take a look at Apple's documents on them if you want to know more, but this should get you started.