iPhone in Action

Table Tricks for iPhone OS 3.0

In March we talked about our intention to start writing articles about the new iPhone OS 3.0 ... and immediately came to a screeching halt as we discovered that Apple had updated their NDA to prevent discussion of prerelease versions of the SDK.

Now, fortunately, iPhone OS 3.0 has been officially released, and so we can start talking about what's changed from when we wrote iPhone in Action. One of the biggest differences shows up in UITableViewCells, with the entire old way to do things being deprecated (though still functional at this time).

Here's what you should know:

Creating Table Cells

We talked about how to fill in a cell for a table on p.235 of iPhone in Action. As of 3.0, however, you no longer work with a bare cell, but instead can use a stylized cell, which will allow you to arrange up to four data elements (two text labels, one image, and one accessory view) in standardized ways. To do so, you create your cell with a new init function:

cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle
             reuseIdentifier:CellIdentifier] autorelease];

The style can be set to one of four types:

1. UITableViewCellStyleDefault creates a old-style cell with just one label.
2. UITableViewCellStyleValue1 includes two labels, a black one to the left and a blue one to the right, just like the Settings cells that we talked about in a previous article.
3. UITableViewCellStyleValue2 does the opposite, putting a blue label to the left (and right justifying it) and a black label to the right (and left justifying it), like is shown for the Info page of individual contacts.
4. UITableViewCellStyleSubtitle puts one line of text in black, then another below it in gray, allowing much the same functionality as shown in our beautiful tables post.

Besides these one or two labels, you can also automatically insert a picture to the left of each table cell and (of course) an accessory to the right. Those are available in all styles.

Accessing the Cell Views

The other big change in cell is how you access its elements. You should no longer be using the simple image and text properties that you depended on in 2.x. Instead, a set of three properties give you access to the actual objects that make up the cell, allowing you to change any of their properties. imageView contains the UIImageView placed to the left, textLabel contains the UILabel for the main (or only) text and detailTextLabel contains the UILabel for the subsidiary text (if there is such). You can manipulate those as you see fit.

Here's an example of some code that fills in both text labels and an image in a subtitle-styled box.

cell.textLabel.text = [textLabelContents objectAtIndex:indexPath.section];
cell.textLabel.font = [UIFont boldSystemFontOfSize:14];

cell.detailTextLabel.text = [detailLabelContents objectAtIndex:indexPath.section]

cell.imageView.image = [imageList objectAtIndex:indexPath.section];

Note that I can change not only the text and image properties of these objects, but also other things, such as the font change shown for textLabel.

This setup has advantages and disadvantages.

On the good side, it's a lot easier to do somewhat more complex things, which should save you a lot of programming time for the standard styles that you develop for filling in table cells.

On the bad side, because so much is done for you, you can end up kind of constrained. For example, I set the textLabel to a font size of 14 in the code above, which is pretty small. The problem is that the whole style is really set up for a larger text size, and so this leaves more space than I'd like between the two lines of text. I suppose I could next go through and move the UILabels around and shrink the rowHeight ... but at a certain point I start to wonder if I should just create my own UITableViewCell subclass from scratch.

Of course, even doing that's probably simpler as long as you start with one of these styles ...

About 3.0 Deployment

When I started thinking about coding with new 3.0 API elements, my first concern was whether I'd be cutting off potential customers by doing so. Fortunately, this doesn't seem to be a concern. The tapbots blog shows a 75% adoption rate of 3.0 over the first 5 days.

That's high enough that I have no qualms about working on new programs using 3.0, though I'd be a bit more careful updating old programs, until that rate gets to 90% or so.

(The biggest problems seems to be Apple's decision to charge iPod users $10 to upgrade their OS.)

Animating Sublayers

In iPhone in Action we talked about two ways that you can animate graphics in your apps.

First, we talked about Quartz (pp.367-391). Although we didn't specifically talk about using it for animation, the methodology should be obvious: by redrawing your CALayer in slightly different ways, you can explicitly create an animation.

Second, we talked about Core Animation (pp. 391-394). It makes animation a lot easier, because if you want to animate something in a standard way (such as by adjusting its position or its opacity) you can do so just by changing that value, then having the SDK implicitly create the animation for you.

So, what do you do if you want to create a Quartz drawing (some of which might animate explicitly--or not) that itself contains simple, implicit animations? That's what this article will talk about.

From Quartz to Core Animation

The secret lies in the use of sublayers. We briefly touch upon this on p.392, where we note that you can add sublayers to a layer and then animate the individually. (We also warn about sublayers having inverted coordinate systems, which is no longer the case, as far as I can see.) However, we don't give details because (as ever) there's limited space in a print book.

So, here are the details:

You can easily create a sublayer as part of a drawRect: method call in a UIView subclass. Here's an example of creating a subview that has an arrow drawn on it:

if (!leftLayer) {
    leftLayer = [CALayer layer];   
    leftLayer.frame = CGRectMake(stripX,stripY,arrowSpace,stripHeight);

    UIGraphicsBeginImageContext(CGSizeMake(arrowSpace,stripHeight));
    CGContextRef leftCtx = UIGraphicsGetCurrentContext();

    CGContextSetFillColorWithColor(leftCtx, [toolColor CGColor]);
    CGContextMoveToPoint(leftCtx, arrowSpace, verticalMargin);
    CGContextAddLineToPoint(leftCtx, arrowSpace, stripHeight-verticalMargin);
    CGContextAddLineToPoint(leftCtx, verticalMargin, stripHeight/2);
    CGContextClosePath(leftCtx);
    CGContextFillPath(leftCtx);

    UIImage *leftPic = UIGraphicsGetImageFromCurrentImageContext();
    UIGraphicsEndImageContext();

    leftLayer.contents = (id)[leftPic CGImage];
    [self.layer addSublayer:leftLayer];
}

There are broadly three steps to creating a sublayer. First, you create the sublayer with the [CALayer layer] message, usually followed by a message to set its frame size. Second, you create the sublayer's content. Third, you add the new layer as a sublayer to your existing CALayer.

Step one requires one additional note. Be aware that we only create this sublayer if it hasn't been created previously. This is a similar methodology to our discussions of creating subviews of a table, several weeks back.

The trickiest element, however, is in step two, because there aren't a lot of easy ways to add content to a sublayer without creating a whole subclass of CALayer, then creating its content there. Though that's surely possibly, it's nice to keep all of your drawing of layers and sublayers together, thus I offer up a pretty good alternate methodology here: create a bitmap content, draw to it, and save it (using the same techniques we discussed on pp.383-384), then set the content property of your sublayer to the CGImage you create from your bitmap.

Animating Your Sublayer

From this point,animating your sublayer should be largely trivial, following our Core Animation example from iPhone in Action. Here's some snippets of code that are used to animate the subview.They appear in touchesMoved:withEvent:

CABasicAnimation *arrowAnim = [CABasicAnimation animationWithKeyPath:@"opacity"];
arrowAnim.duration = .25;
arrowAnim.fromValue = [NSNumber numberWithFloat:1];
arrowAnim.toValue = [NSNumber numberWithFloat:.5];
arrowAnim.autoreverses = YES;
arrowAnim.delegate = self;

CABasicAnimation *arrowMoveAnim = [CABasicAnimation
    animationWithKeyPath:@"transform.translation.x"];
arrowMoveAnim.duration = .25;
arrowMoveAnim.fromValue = [NSNumber numberWithFloat:0];
arrowMoveAnim.toValue = [NSNumber numberWithFloat:-40];
arrowMoveAnim.autoreverses = YES;

[leftLayer addAnimation:arrowAnim forKey:@"animateOpacity"];
[leftLayer addAnimation:arrowMoveAnim forKey:@"animateLayer"];

As you can see, this is very similar to the airplane example we used on p.392, with opacity and movement both being animated. The biggest change is that we work with a property that we don't mention in the book, autoreverses. That tells the animation to go all the way forward, then back out too. In this case it moves an arrow to the left, and then back (which I use in the program to help cue a user that he's moving a strip of icons in that direction).

As always, Core Animation is simple and quick. The only trick in this bit of code for me was figuring out how to create the sublayer and populate it correctly. Beyond that, you existing Core Animation knowledge should work fine.

Warning: kCGColorSpaceGenericRGB is deprecated

You might see this warning when you create a color space, for example when you're working toward making a gradient. It's non-fatal, but you should correct it so that your program doesn't fail at some time in the future.

You probably have a line of code something like this:

CGColorSpaceRef myColorSpace =  
    CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);

It should be changed to this:

CGColorSpaceRef myColorSpace = CGColorSpaceCreateDeviceRGB();

You can find out why by reading the CGColorSpace reference, which says:

Prior to Mac OS X v10.4, you could pass this function one of the constants defined in “Named Color Spaces (Deprecated)”. As of Mac OS X v10.4, this function returns a generic color space even if you pass is one of the deprecated named color spaces.

In other words, just use CGColorSpaceCreateDeviceRGB();.

UIActionSheet, Part One: Alternate User Input

Your options for how accept input in an iPhone app are limited both by the innate constraints of the screen and by the standard human interfaces which Apple has developed. So, if you want to give users a few options, how do you do it?

Changing State

There are a couple of robust ways to let a user quickly change state:

• A Table View. iPhone in Action pp.231-238. This is a standard methodology for changing the state of a program. For example, when you click the "More" tab in the "iPod" program you'll see six choices: "Audiobooks", "Compilations", "Composers", "Genres", "Songs", and "Videos". In order to make good use of a table view, you really need to make it beautiful, as discussed in Table Tips & Tricks Part Three. At the least, you should put a graphic to the left, as shown in the "iPod" program.
• A Tab View Controller. iPhone in Action pp.265-271. This is probably the most common methodology for changing state. In the 'iPod" example given above, the "More" page is actually overflow from a standard tab interface.

I think that using one or both of these methods to allow a user to control state is usually sufficient, particularly if you link them together via a "More" option (which is easy to do with a tab bar).

Selecting Actions

However, as a programmer, I'm a little less happy with the options allowed for selecting actions. Here's a quick run-down:

• In-Line Buttons. iPhone in Action pp.255-257. In-line buttons aren't used very often in Apple's iPhone Apps, and I think that shows in the very limited functionality that the UIButton currently allows. You basically can't make it look like anything but an ugly white button unless you define a graphic. I've gone the graphic route more than once in programs, but I don't think I've ever shown a bare in-line button in a real program.
• Navigation Bar Buttons. iPhone in Action pp.275-276. If you have a navigation bar in your program, you can add one button to the right. Further, if you don't mind covering up the back button, you can add one button to the left. This is a pretty good option for user input, but you have to constrain your options to just one or two choices.
• Tool Bar. iPhone in Action p.287. This expands upon the same idea. You create a toolbar solely to hold a variety of buttons. In iPhone in Action, we make use of it in our photo collage example (pp.351-355), but I'm not convinced of its general utility. I don't find it a particularly attractive interface if you have lots of individual buttons (but, see the Calendar program for a good example of a UIToolBar with a button and a segemented button that ends up looking OK), and it also takes up the space that you'd want to use for a tab bar. Still, it's a possibility if you want more than 1-2 buttons on your page.
• Touch Control. iPhone in Action pp.240-252. Finally, you can opt to create your own interface by using Quartz to draw an interface and capturing touches to determine what it does. This is a fine option if you want to have some sort of full-screen control, but is a lot of work otherwise.

Putting that all together, it sounds like there's a gap in the support for action user input. If you want to have more than one or two choices, and you want to make it look good, and you want it to be simple ... what do you do?

The answer is that you create an UIActionSheet, one of the SDK classes that we didn't cover in iPhone in Action.

Using a UIActionSheet

Action sheets allow a good alternative for action selection: you don't have to fill up your UI with buttons on every page; instead your main selection window only appears when it's needed. When you request it, it'll display as a menu of buttons which slides up from the bottom of the screen. Consider it the iPhone version of a drag down window.

An action sheet will often be loaded up from a button. Here's an example of some code that can be activated by a button, to give a user two choices of actions:

-(void)popupActionSheet {
    UIActionSheet *popupQuery = [[UIActionSheet alloc]
        initWithTitle:nil
        delegate:self
        cancelButtonTitle:@"Cancel"
        destructiveButtonTitle:nil
        otherButtonTitles:@"Add a Character",@"Delete a Character",nil];

    popupQuery.actionSheetStyle = UIActionSheetStyleBlackOpaque;
    [popupQuery showInView:self.tabBarController.view];
    [popupQuery release];
}

As you can see, creating an action sheet is a three-step process. First, you alloc and init the action sheet, then you set its properties, and finally you send it a showInView: message.

The initWithTitle: function lets you set an optional title and an optional delegate. It also gives you three sorts of buttons that you can create. Destructive buttons have a red background, other buttons have a light gray background, and cancel buttons have a dark gray background.

When the action sheet pops up, it will have indexed all the buttons you supplied in that order: destructive, other, cancel. So, for example, in the above code, my action sheet would appear with these button indices:

0: Add a Character
1: Delete a Character
2: Cancel

If I'd also include a destructive button labeled "Destroy Program", the indices would instead be as follows:

0: Destroy Program
1: Add a Character
2: Delete a Character
3: Cancel

So now you've got a good looking action sheet, how do you respond to it? The answer is, of course, found in that delegate that you set up.

Responding to an Action Sheet

The UIActionSheetDelegateProtocol reference at Apple lists all of your standard delegate methods. The most important one is actionSheet:clickedButtonAtIndex:. This will tell you which of the other or destructive buttons was selected. You can then take actions based on the buttonIndex:

- (void)actionSheet:(UIActionSheet *)actionSheet
    clickedButtonAtIndex:(NSInteger)buttonIndex {

    if (buttonIndex == 0) {
// Add Character
    } else if (buttonIndex == 1) {
// Delete Character
    }
}

That only leaves the cancel button. By default, you can not worry about this, figuring that the system will do the right thing, dismissing the action sheet when you click the button. If you want to do something more, write an actionSheetCancel: method.

And that's it for the basics of action sheets. If there's anything more complex you'd like to know about the class, just let me know.