iPhone in Action

The iPhone Simulator & Performance

In iPhone in Action we talk about some about using the iPhone Simulator as a testing & debugging facility for your iPhone programs. It's certainly an easy and convenient way to work on your programs. You hit command-r and with no additional work on your part, your program compiles, the Simulator starts up, and everything runs.

However, in iPhone in Action, we also talk a bit about the places where the iPhone Simulator comes up short. It includes: using the accelerometers, using the location manager (though you can do simple tests as the Simulator reports back Apple's Silicon Valley headquarters), and downloading streaming audio.

In the last two months I've been working on a card game, which I expect to write about more here when we're ready to release. It's shown me another pretty grave short-coming in the Simulator: performance. The issue? It's too good.

I mean, we all know that the iPhone is a mobile platform, and that by nature it'll ultimately be limited in its CPU capabilities. But, it's easy to forget that with all of the sexy animations and graphics that Apple pushes back and forth around the screen. Indeed, if you're just making simple use of Apple's more front-facing frameworks, you may not hit performance problems at all.

The problem arises when you start using more in-depth frameworks like Core Data and Core Graphics. You may end up with programs which work great on the Simulator but which seriously bog down when you put it out to a real iPhone or iPod Touch device.

Here were the top two performance problems that I hit when working on my card game:

• Rounded Corners. My cards are laid out as CALayers. When I used the new 3.0 property, cornerRadius, to round the corners of my cards, I discovered that a real iPhone got dragged to a blinking, laggy halt. I thought I was just going to need to square my corners as long as I used CALayers, but eventually discovered that if I rounded the corners myself, using a clipping area on the CALayer's context, everything worked pretty good.
• Too Much Core Data Writing. At one point, I accidentally set my program to rewrite the Core Data ordering property for my cards any time a deck was touched, rather than only when they were actually reordered. Until I resolved the inefficiency, my game felt like it was moving through molasses.

The important fact that I intend to convey here is: these problems did not show up in the Simulator, only on an actual device. This was particularly frustrating for the second problem, which I discovered after a half-day or so of programming lots of different changes.

So the moral? If you're using simple frameworks, don't worry about it, But, if you're doing more complex work, every couple of compiles, send one over to an actual hardware device. The first time you hit a performance problem that didn't show up in the Simulator, you'll be happy you did.

Next Up: I'll be back after the Thanksgiving holiday, probably talking about NSSets: how they work, why you'd want to use them, and how they integrate with Core Data.

Beautiful Section Heads

In the last couple of months, I've talked a lot about tables. In Beautiful Tables, I discussed how to make your tables look more attractive and in Table Tricks for iPhone OS 3.0, I updated some of that information for 3.0.

However, neither article talked about how to make your table's section heads look more attractive, and if you've got a beautifully tinted navigation bar, a carefully colored table, and multi-view cells, that gray section header will probably stand out like a sore thumb. So, how do you make it more attractive too?

Rewriting tableView:viewForHeaderInSection:

Sadly,there isn't a simple tintColor property to set for your section header. (I think there should be, but I suspect that Apple is generally trying to discourage uses of colors in tables.) Instead you have to replace the tableView:viewForHeaderInSection: method. In doing so, you must create a view that both displays your section text and does so in a color that you want.

Here's an example:

- (UIView *) tableView:(UITableView *)tableView
  viewForHeaderInSection:(NSInteger)section {

   UIView* customView = [[[UIView alloc]
     initWithFrame:CGRectMake(10.0, 0.0, 300.0, 44.0)]
       autorelease];
   customView.backgroundColor =
     [UIColor colorWithRed:.6 green:.6 blue:1 alpha:.9];

   UILabel * headerLabel = [[[UILabel alloc]
     initWithFrame:CGRectZero] autorelease];
   headerLabel.backgroundColor = [UIColor clearColor];
   headerLabel.opaque = NO;
   headerLabel.textColor = [UIColor whiteColor];
   headerLabel.font = [UIFont boldSystemFontOfSize:16];
   headerLabel.frame = CGRectMake(0,-11, 320.0, 44.0);
   headerLabel.textAlignment = UITextAlignmentCenter;
   headerLabel.text = [NSString stringWithString:@"Your Text"];

   [customView addSubview:headerLabel];

   return customView;
}


This is a pretty simple three-step process. First, I create the actual view for the section, drawing its background color appropriately; then I add a label with the correct text, positioned just right, and make that a subview of the section view; and finally I return the section view.

Voila! You now have a colorful section head that should match the rest of a color table.

(I'll add one more comment: note that I decided to make the alpha transparency of my section header's background color 90%. That's because of the 3.0 feature where a header sticks to the top of a table when it scrolls past. I like the three-dimensional effect that produced when you can just barely see a bit of the table beneath your stuck section head; your mileage may vary.)

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.

Table Tricks & Tips, Part Four: Editing Tables

In some of the iPhone's default apps, you may find that you can "edit" a table, then have little red minus signs appear to the left of the table, giving you the option to delete those rows. So, how do you do that in your own programs?

The answers, it turns out, is a very simple one:

[self.tableView setEditing:YES animated:YES];

That's literally all you need to do to set up those deletion marks. Then you just need to respond to tableView:commitEditingStyle: forRowAtIndexPath:.

However, there are some nuances, particularly the questions of how you start up a table's editing and how you end it, and I'm going to show some real-world examples of those methods over the course of this article ...

An Actual Example

The program that I've showed off elsewhere in this series makes uses of a tableView's editing functionality by allowing the user to delete characters from the app, each of whom are represented by a table row

First, you need to set up some way to activate the functionality:

- (void)editCharacters {
    [self.tableView setEditing:YES animated:YES];
    UIBarButtonItem *doneButton = [[UIBarButtonItem alloc]
        initWithBarButtonSystemItem:UIBarButtonSystemItemDone
                                           target:self
                                           action:@selector(endTableEditing)];
    self.navigationItem.leftBarButtonItem = doneButton;
    [doneButton release];

    self.navigationItem.rightBarButtonItem = nil;
}

This method is triggered when a user selects an "Edit" button. You'll note that besides starting the editing, I also change around the button in my navbar. That's because when a user is editing I no longer need an "Edit" button, but instead require a "Done" button. You might alternatively set buttons' enabled properties to NO ... but in any case, you always need to give users a way to get out of editing mode.

Your tableView: method will probably delete the table item from your table and/or the data store that it originates from:

- (void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath {

    if (editingStyle == UITableViewCellEditingStyleDelete) {
        [self recordWasDeleted:indexPath.row];
    }
}

For completeness state, I'll also include the method call generated when the "Done" button is clicked:

- (void)endTableEditing {
    [self.tableView setEditing:NO animated:YES];
    [self updateButtons];
}

This is pretty much the opposite of my editCharacters method: the editing is turned back off, then the buttons are returned to their original state.

And that's really all you need to do to edit a table: turn editing on, respond to the deletion message, and turn it back off at the end.

Doing More with Table Edits

You do have some other editing possibilities that I'm not going to cover in depth in this article. Most notably, you can adjust the editingStyle property of any individual cell. Apple claims it's set to UITableViewCellEditingStyleNone by default, but it sure looks to me like it's set to UITableViewCellEditingStyleDelete, which is what shows those handsome red minus marks. If you instead want to insert rows, you can set it to UITableViewCellEditingStyleInsert, and then do the appropriate thing when tableView:commitEditingStyle:forRowAtIndexPath: receives input of type insert.

That's it for me and tables for the nonce. If there's any other topics that you'd like covered regarding them, let me know in the comments. In the meantime, I'm planning to next return to my splashView topic, as some folks have requested in comments.

Table Tricks & Tips, Part 3B: ContentView & Cell Images Done Right

The advantage of writing a book is that you can go back and revamp and revise what you've already written as you go forward and learn more. I did that as I wrote iPhone in Action (which is why you'll find many handy forward and backward references throughout the book) and I've done it in most of my other major works.

When you're publishing live on the internet you don't have that same opportunity. (Or, rather you do, but if you take advantage of it by editing old pieces, you might leave people who read those pieces and moved on with the wrong impression.) So in this article I'd like to polish up some of my earlier discussions of contentView.

In Part One of this series, I offered a very simplified look at contentView, but there was the caveat that it wouldn't work if the table was refreshed (because the contentViews would get created again).

In Part Three of this series, I offered a somewhat clumsy way to keep your contentViews clean, by removing old contentViews whenever you redrew the table. It worked, but I'm certain it lacked something in efficiency.

The ContentView Done Right

So, let me offer an adjunct to those two articles by showing a clean and correct way to work with contentView:

#define topTag 1
#define botTag 2

 static NSString *CellIdentifier = @"Cell";

UILabel *topLabel;
UILabel *botLabel;

UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];

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

    topLabel = [[UILabel alloc] initWithFrame:CGRectMake(65,0,205,35)];
    topLabel.tag = topTag;
// Other standard setup like fonts and colors
    [cell.contentView addSubview:topLabel];
    [topLabel release];

    botLabel = [[UILabel alloc] initWithFrame:CGRectMake(65,30,205,20)];
    botLabel.tag = botTag;
// Other standard setup like fonts and colors
    [cell.contentView addSubview:botLabel];
    [botLabel release];        
} else {
    topLabel = (UILabel *)[cell viewWithTag:topTag];
    botLabel = (UILabel *)[cell viewWithTag:botTag];   
}

topLabel.text = [NSString stringWithFormat:@"%@",thisName];
botLabel.text = [NSString stringWithFormat:@"%@",thisText];

cell.image = thisImage;

return cell;

Similar to my earlier methodology, this differentiates between a draw and a redraw by seeing if the cell exists. However now, instead of the inefficient destroying and recreating of subviews, this method just reuses the existing subviews by changing their text. You could similarly change images in UIImageViews, which are the other element you're likely to use in a table cell (but more on a better way to implement some of those momentarily).

The trick is finding your old subviews a second time through. This is done by tagging each subview with an integer that describes it, then running the viewWithTag: method on the cell when you return, which will identify the subview which have the tag in question.

Do not ever use or look for a "0" tag as that will identify everything that's untagged.

The Cell Image Done Right

There's one other bit of magic here: the cell's image property. This property will take the image it's passed and place it to the left of the cell. It's the easiest way to drop an image to the left of a table cell, as you often see in Apple's programs. It doesn't save a lot of effort, but it does save you the work of creating an individual subview for the image yourself.

Table Tricks & Tips, Part Three: Beautiful Tables

We talk several times in iPhone in Action about the importance of tables as a central programming paradigm on the iPhone. The problem with this methodology is that, by default, a listing of black text on white backgrounds just doesn't look that interesting. As an example, I offer the table shown at right, a part of an app that I've been working on which very simply lists a game character's name and level, while offering a chevron to click through to a page with more information.

This table is simple and utilitarian. It provides the information that's required, but with very little attention to beauty ... and as such it falls down a little when viewed alongside some of the standard iPhone apps, because Apple did spend a bit of time figuring out how to make their tables look nicer, as you can see if you call up some of the Apple programs, such as iPod, Mail, and Photos.

Generally, Apple uses two tricks to make their tables look nicer:

First, they often have a picture off to the left of each table cell, that in some way depicts the individual item described in the cell. In iPod, that's usually an album picture, in Mail that's a simple icon to describe each of your mail boxes, and in Photos that's a thumbnail of the most recent photo in the set.

Second, Apple often provides a variety of information within a table cell. The iPod list of albums shows off a really standard mechanism. It displays two rows of text: the first one in bold, listing the album name, and the second in normal, GrayColor text, showing the artist name. Mail's folder page shows another example: sender name, subject, time, and content are shown in a variety of sizes, weights, and colors.

Returning to contentView

So, how do you make your table views attractively depict a variety of content and/or pictures? The answer is to make use of the table feature that I described in the first article in this series: contentView.

At the time I described contentView mainly as a tool that you could use to mimic a specific sort of Setting. However, you've probably already realized that its utility can go far beyond that. You can also use it to hold together all the building blocks that make up a more complex cell, whether they be images or text.

At right, I've shown how I rebuilt my page out of three building blocks. First up is a button (masquerading as an image) which I place to the left. Second is a large, bold UILabel listing the name of the character. Third is the level, sitting below the character in darkGrayColor text of a smaller size.

Building these cells was a simple process of creating the three object types that I wanted, positioning each within the bounds of the cell, then adding each to the content view in turn.

Following is a somewhat shortened look at how these things were all done:

- (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];
    } else {
        NSArray *cellSubs = cell.contentView.subviews;
        for (int i = 0 ; i < [cellSubs count] ; i++) {
            [[cellSubs objectAtIndex:i] removeFromSuperview];
        }
    }

    UILabel *nameLabel = [[UILabel alloc] initWithFrame:CGRectMake(65,0,205,35)];
    ...
    [cell.contentView addSubview:nameLabel];
    [nameLabel release];

    UILabel *levelLabel = [[UILabel alloc] initWithFrame:CGRectMake(65,30,205,20)];
    ...
    [cell.contentView addSubview:levelLabel];
    [levelLabel release];

    NumberedButton *checkbutton = [NumberedButton
        buttonWithType:UIButtonTypeCustom];
    ...
    [cell.contentView addSubview:checkbutton];

    cell.accessoryType = UITableViewCellAccessoryDisclosureIndicator;
    return cell;
}

There are two gotchas to contentViews that I didn't cover in my prior article on the topic.

First, when you're adding subviews to your contentView, you have to be careful about not creating a memory leak by recreating the same subviews again and again.

Often you'll only create a subview when you create a cell for the first time (cell == nil). In this case I instead removed the old subviews on subsequent returns to this function (because the cells can be easily moved around, meaning that the new cell content may no longer match the old subview; it'd still probably be better to use the old subviews, and I suspect I'll update that before I send the project off to the app store).

(And indeed I did; you can find my updated code in: Part 3B.)

Second, you need to either build within the constraints of a table cell's standard height (about 30 pixels) or else explicitly change the height. If you're displaying multiple rows of text, as in my example, you'll probably do the latter. The following appears in my table's ViewDidLoad:

self.tableView.rowHeight = 55;

The result of an extra 20 or 30 lines of code and $5 worth of (great) stock art is a table that's vastly more interesting.

Adding Color to the Mix

Apple usually stops right here in their table beautification. However, two of their standard apps show off a bit more ... color.

The Weather app looks quite attractive because of great use of graphics and because it colors tables in alternating shades of gray (though the Weather app might actually mimic a table rather than using one explicitly).

The Notes main page shows a great use of a yellow background and a brown navigation bar which together imply a pad of legal paper.

You can similarly color your tables with two simple variables.

To color your Navigation Controller's Navigation Bar, set its tintColor property.

To color your page backgrounds, set the backgroundColor of your table view controller's view.

When you're working with table cell subviews, you'll need to set the background color of those as well. The easiest solution is probably to set them to the color of their table view or else to a clearColor, so that you only have to adjust the color of your application in one place.

Following is a code snippet from my app delegate, which depicts how I quickly colored all of the navigation bars and all of the views in my application.

for (int i = 0 ; i < 3 ; i++) {

    [[[tabBar.viewControllers objectAtIndex:i] navigationBar]
     setTintColor:[UIColor colorWithRed:.4 green:.2 blue:.6 alpha:1]];

    [[[[tabBar.viewControllers objectAtIndex:i] topViewController] view]
     setBackgroundColor:[UIColor colorWithRed:.8 green:.8 blue:1 alpha:1]];

}

The results are shown above. I invite you to compare them to the table at the top of this article, and decide which one you'd prefer to have in your app.

---

Some icons by Joseph Wain / glyphish.com
Weapons stock art by Rita (SaDE) / DriveThruRPG.com

Table Tricks & Tips, Part Two: Clickable Accessories

We cover table accessories on p.236 of iPhone in Action. They're the element that appears to the right of a table cell. Usually an accessory is just an icon (defined by accessoryType), but sometimes it's a full subview (defined by accessoryView).

Most frequently, you don't care if a user clicks on the main body of a table cell or on its accessory. For ease of UI, they should do the same thing. However on occasion, your interface might strongly suggest that the accessory should do something different different, and thus you'll want to discriminate between clicks on the cell content and clicks on the cell accessory.

How do you do that? The SDK offers three possibilities--though none of them are great.

Solution #1: The Disclosure Button (Restricted!)

The easiest way to make a clickable accessory is to define your accessory type as a UITableViewCellAccessoryDetailDisclosureButton, which is the chevron inside a blue button. You can detect this directly by filling in the appropriate table view delegate method:

- (void)tableView:(UITableView *)tableView
    accessoryButtonTappedForRowWithIndexPath:(NSIndexPath *)indexPath {

...

}

Easy! You'd think that this method might also work with other sorts of accessories ... but it doesn't. It's the detail disclosure button or nothing.

Solution #2: The accessoryAction (Not Helpful!)

The second way that you can capture an accessory touch is through the table cell's accessoryAction property. You'd think that this would allow you to capture other sorts of accessory clicks than that singular accessory button, but that turns out once more to not to be the case, as you can suss out if you carefully read Apple's manual:

If you specify a selector for the accessory action, a message is sent only if the accessory view is a detail disclosure button—that is, the cell’s accessoryType property is assigned a value of UITableViewCellAccessoryDetailDisclosureButton.

In other words this property does you no more good than the tableView: method I listed above. It only captures touches to the  disclosure button. Basically, you can set your delegate method to something other than tableView:accessoryButtonTappedForIndexPath:, but that's it.

(I tested this out considerably last week, trying some options like also setting the cell's target property and setting the accessoryType to the detail disclosure button before overwriting it with an accessoryView, and none of them every gave me a response for anything but the disclosure button.)

Discussions on the 'net suggest that the average programmer considers this a bug (despite the documentation), as I've seen lots of folks trying to capture clicks on other accessory types without success. I'd generally agree with the sentiment, as I don't think it's intuitive for these methods to only capture the results for one sort of accessory.

I can, however, see why Apple thinks this is intuitive. It's because the disclosure button literally looks like a button, and thus they're trying to make sure that clickable things always look clickable in the UI. I just don't agree with the architecture decision in this particular case.

So, what do you have to do to make an accessory other than a disclosure button clickable? The answer is that you have to introduce a button of your own.

Solution #3: The UIButton (A Kludge!)

As far as I've been able to ascertain, there's no way to make any of the standard accessoryTypes other than the detail disclosure button clickable. If you want to make something else clickable, the only way to do so is by creating an accessoryView that recognizes touches. The easiest way to do so is to embed a UIButton in your accessoryView, then capture its clicks.

Here's a few steps that will let you do so.

First up, you probably need to better identify your buttons, since there will be several identical ones on your page. My current methodology for doing so is to create a subclass of UIButton which can store a number (in this case, the indexPath.row, which will help keep each button to the table). Here's all that''s necessary to do that:

@interface NumberedButton : UIButton {
    int number;
}

@property int number;

@end

@implementation NumberedButton
@synthesize number;

@end

I'm not 100% happy with this methodology, so if you have any alternatives, please feel free to comment, below.

The creation of the button is then done in tableView:cellForRowAtIndexPath:, where you normally build out your cells. Here's some code for that, that I'm currently using in a live program:

    NumberedButton *checkbutton = [NumberedButton
        buttonWithType:UIButtonTypeCustom];
    checkbutton.number = indexPath.row;

    UIImage *uncheckmark = [UIImage imageNamed:@"uncheck.png"];
    [checkbutton setImage:uncheckmark forState:UIControlStateNormal];

    UIImage *checkmark = [UIImage imageNamed:@"check.png"];
    [checkbutton setImage:checkmark forState:UIControlStateSelected];

    [checkbutton addTarget:self
                    action:@selector(checkmarkTouched:)
          forControlEvents:UIControlEventTouchUpInside];

    [checkbutton sizeToFit];
    cell.accessoryView = checkbutton;

If you're forgotten the basics of the UIControl's addTarget:action:forControlEvents: method, you can find them on pp.254-255 of iPhone in Action.

Generally, the most important elements of this cell setup are:

1. The creation of the numbered button.
2. The use of addTarget:action:forControlEvents:, which is what makes the button clickable.
3. The use of  sizeToFit to get the button correctly aligned and setup for your cell.
4. The setting of your accessoryView to the new button.

What goes in between depends on the specific needs of your program.

In my case, the whole goal was to make a clickable checkmark, so that users could easily toggle it on and off without going to the editing subpage (which is where they'd go if they clicked on the main content of the cell). Thus I made PNGs that showed the standard checkmark (thanks to a screen grab) when the checkmark was set and that showed it at 20% opacity (thanks to Photoshop) when it could be clicked. I thenconnected those two images with two of the checkmark's states, and voila, I had what looked like a clickable accessory of type checkmark.

There's one gotcha. From what I've read elsewhere, a button usually uses an alpha mask of its images to determine what's clickable. That's really not what you want for something tiny like a checkmark. There's an easy solution: don't make your image transparent; instead keep the background white. This means you probably also need to turn off the selected color for the cell (so that the checkmark doesn't look like a square box when the cell is selected), but in my view it's worth it to keep everything simple and intuitive.

You'll also want to make sure your button is big enough for a user to be able to easily touch it. I choose a 40x40 PNG for my baseline and that seems to do the trick 95% of the time, which is good enough for this setup.

Conclusion

I'm not entirely happy with any of the ways to make an accessory clickable. You either have to make a very restricted choice for what your accessory looks like, or else you have to program what feels, at best, like a big kludge. Nonetheless, if your program cries out for a clickable accessory (and I'll argue that most shouldn't), then these methods will get you there ... at least until something better comes along (perhaps in 3.0?).

Next Up: An article on the basics of table editing is my last scheduled piece in this series, but if you'd like to see discussion of anything else regarding tables, let me know in comments.

Table Tricks & Tips, Part One: The ContentView

iPhone in Action covers the basics of table views in chapter 13 (pp.231-238). We go into some depth, covering issues like accessories and various cell properties, but as we note on page 238, there's a lot of extra stuff we don't cover. Now, without the constraint of the printed page hanging over us, I'm going to be covering some of those additional table issues in a series of blog posts.

To start off with, I'm going to discuss the cell's contentView property, which will allow you to implement one of the iPhone's standard UI elements.

The Settings Conundrum

If you look at the Settings page on your iPhone, you should broadly know how to mimic it, based on what we present in the book. The whole thing is laid out as a table view of type UITableViewStyleGrouped. At the time of this writing, my Settings page is broken into three sections.

There's an "Airplane Mode" entry at the top with a switch to the right, which is a simple application of an accessoryView (explained p.236, with an actual example of this on pp.289-290) and there are a slew of even simpler accessories of type UITableViewCellAccessoryDiscolureIndicator (which is to say, a gray chevron). However there are two entries which may puzzle you, the "Wi-Fi" and "Fetch New Data" entries, each of which has a gray chevron to the right with blue text to the left of it.

This is a very standard UI element in iPhone tables, yet it's not immediately obvious how to create it. This first tabular article will show you how.

A Variety of Views

The standard methodologyfor working with table cells is to set a variety of properties, such as text, lineBreakMode, and selectedImage. Similarly, you can set the accesoryType property to adjust what icon appears in the accessory space, to the right of the table cell. However as we discuss in the book, you can alternatively ignore the property and embed an entire view in that space by overwriting the accessoryView property.

It thus shouldn't suprise you that you can do the same thing for the other side of the cell, which contains the content. Instead of setting a bunch of standard properties to display a regularized set of text, you can instead embed whole new objects to the left of your table cells by updating the contentView.

And, that's exactly what's done to produce a text and chevron setup as shown on the Settings page. Your accessoryType is  set normally to the disclosure indicator, but then your contentView is created with two elements: regular text which justifies left and blue text which justifies right.

The Code

Following is sample code for just such a setup, which would appear as part of the tableView:cellForRowAtIndexPath: method.

UILabel *leftLabel = [[UILabel alloc] initWithFrame:CGRectMake(10,0,260,40)];
leftLabel.text = @"Setting Name";
leftLabel.font = [UIFont boldSystemFontOfSize:14];
[cell.contentView addSubview:leftLabel];
[leftLabel release];

UILabel *rightLabel = [[UILabel alloc] initWithFrame:CGRectMake(130,0,140,40)];
rightLabel.text = @"Setting Value";
rightLabel.textColor = [UIColor blueColor];
rightLabel.textAlignment = UITextAlignmentRight;
rightLabel.font = [UIFont systemFontOfSize:14];
[cell.contentView addSubview:rightLabel];
[rightLabel release];

cell.accessoryType = UITableViewCellAccessoryDisclosureIndicator;
return cell;

In this case, we don't actually overwrite the contentView, but instead add two subviews to it, each of which shows a label with appropriate text (which would presumably be dynamic in a real program). When you run the program, it should look just like those Settings examples that I led off with.

(Please note that this methodology has one flaw, which is that the contentViews will get added a second time if your table ever gets withdrawn. That may not be a problem for very simple tables, but if you're doing more complex stuff, see my notes in Part 3B.)

Next Up: I've got immediate plans for two more articles in this series, one that talks about creating clickable accessories (which doesn't seem to work well in the current iPhone OS) and one which touches upon the dynamic editing capabilities of tables. Feel free to post other table-related topics that you'd like to see covered.

Create Delegate Protocols for the iPhone

Though we want iPhone in Action to be a great introductory book, there was only so much space we could spend on the basics of Objective-C, the programming language at the heart of the iPhone SDK. We introduce protocols pretty quickly on page 179 then follow up on delegation on page 188. That's hopefully enough to get you started with writing the protocol methods for existing classes such as the TableViewController.

However, what we don't talk about in iPhone in Action is how to create your own, new protocols. In particular, delegate protocols are a pretty important element when you're creating new classes for use and reuse, so you should know how to build them.

Here's a quick step-by-step process. Generally, you'll need to take three broad steps: write the protocol; add the delegate property; and incorporate the protocol into your class.

1. Design the Protocol

As with composition of any type, the first thing you have to do is decide what you're going to do. You should have an existing reusable class that you've designed, and you should have some data that you want to send outside of the class, to the rest of your program. You need to decide what methods you want to define to export that data.

For the purposes of this article we're going to use a database class similar to the SKDatabase class shown on pp.307-308 of iPhone in Action as an example. This class can do all sorts of database work, from simple SELECTs to INSERTs, UPDATEs, and DELETEs.

One necessary protocol immediately suggests itself: it'd be nice to report out whenever a database table is updated, so that an iPhone program can update its own internal data representations. So, that's the method we're going to define in a protocol in this article.

2. Define the Protocol

In order to define a protocol, you must include @protocol information in a header file--probably the header file for the related class. It should probably go up at the top of the file, before the @interface description of your class. Here's what I wrote for my SKDatabaseDelegate protocol:

@protocol SKDatabaseDelegate <NSObject>
@optional
- (void)databaseTableWasUpdated:(NSString *)table;
@end

You'll usually write a list of  methods in between a @protocol and @end statement, as shown here. There are two things of note in this example.

First, the protocol itself is given a protocol: <NSObject>. This allows it to effectively inherit protocol methods up its inheritance chain.

Second, the one method in this example is listed as @optional, which means that the delegate object doesn't have to respond to this message. Any methods which appear before such an @optional statement are considered to be required.

You're now done designing a protocol, but as of yet it's not actually linked into your class. Because we're offering an example of a delegate protocol here, the next thing you need to do is define your delegate property.

3. Create the delegate property

To create a standard delegate property you must create an instance variable and define it in your header file, then synthesize it in your .m file.

Here's the .h file info:

@interface SKDatabase : NSObject {

    id<SKDatabaseDelegate> delegate;
}

@property (assign) id<SKDatabaseDelegate> delegate;

The only thing of note here is the definition of the variable as of type "id<SKDatabaseDelegate>" That should be pretty typical when you're creating a delegate property: your delegate can be an object of any type, but it must follow the protocol in question.

The synthesis in the source code file is entirely standard:

@synthesize delegate;

4. Link to the Protocol

Now you're just missing one (entirely crucial) step. Your class actually needs to send a protocol message to the delegate under the appropriate circumstance. In my SKDatabase class, this means that whenever a table is updated, the delegate must be told. Here's the code that does so:

- (BOOL)runDynamicSQL:(NSString *)sql forTable:(NSString *)table {

    // Actual Code to run SQL goes here

    if (result) {
        if (self.delegate != NULL && [self.delegate respondsToSelector:@selector(databaseTableWasUpdated:)]) {
            [delegate databaseTableWasUpdated:table];
        }   
        return YES;
    }

}

Ignoring all the SQLite3 code for the moment, you can see that the delegate code does three things.

1. It makes sure that a delegate has been defined.
2. It makes sure that the delegate responds to the selector in question--which is  important since this was an optional protocol method. For a required method, you might actually just let the program crash, to help alert the programmer to his bug.
3. It tells the delegate to run the method.

5. Use Your Class

With that code all in hand, you can now use your class just like you'd use any protocol already defined by Apple.

In the case of my database, I'm currently using it in a program that draws Table Views and UIViews based on database contents. Thus, it's really handy to know when a database table is updated, and thus when I should redraw the pages in question.

I'll be sharing the actual class, as promised, this week or next, once I finish polishing everything up.

All About Casting

A few days ago Christopher & I chatted with an iPhone in Action reader about why Listing 18.3 in the book generated the warning "Warning: 'UIView' may not respond to -addPic:at:'". The answer is casting, and I think it's a topic that deserves some additional discussion.

All About Casting

Casting is a fundamental of C. Wikipedia defines it as an "explicit type conversion." We demonstrate it briefly on p.156, where we show that you can turn a float into an int with a little bit of casting magic:

float a = 6.00;
int b;
b = (int) a;

Beyond that, we give it pretty short attention. That's probably great for folks with experience with rigorous programming languages, but less useful for those of you just getting into them for the first time.

So in this article I'm going to talk more about casting by concentrating on three three times that I've seen it most in SDK development (and thus where you're most likely to encounter it). In order I'm going to cover: toll-free bridging; math casts; and, finally, method casts (the topic that got us started).

Toll-Free Bridging

This is the other cast-related topic that we covered pretty extensively in iPhone in Action. There are some details on p.157 (at the end of the discussion of casting) and on p.321 (in the "Using Core Fondation" box).

Much of your iPhone programming will be done using Cocoa frameworks, such as the UI and NS libraries. However, sometimes you'll have to instead use Apple's older libraries, such as Core Foundation. Core Foundation is object-oriented, just like the NS libraries, and as a result you end up with alternative ways to represent a lot of standard variable types. For example Core Foundation's CFStringRef and Cocoa's NSString * are alternate ways to represent strings.

Fortunately, Apple recognizes this equivalence and "toll-free bridges" equivalent Core Foundation and NS classes. In order to use one in the place of another, you just need to cast it, as we do throughout Listing 16.11 (pp.318-320):

(NSString *)ABRecordCopyCompositeName(thisPerson);

This sort of casting will come up frequently if you use older frameworks, such as Address Book and Core Graphics.

Math Casting

I've run into the most problem with casting when I was writing mathematical formulas.  Listing 17.10 (pp.340-341) shows off one such examples. Most of the way through that example, you can see a line which reads:

int currentHeight = 395 - ceil((float)newLocation.altitude/savedDestinationHeight*(401-65));

Clearly, that's a cast, but I don't really explain why in the description of the code.

I had to cast because of the "int" variable that I'm saving the formula off to. A problem arises because there's not necessarily a consensus (among all programming languages) for how to treat the right-hand side of such an equation. Should the elements all be treated as integers, or should they be left in their native form until the final conversion is done? Apple's Objective-C appears to assume a conversion to the final variable type almost immediately.

In this situation that resulted in altitude/height being made into an integer before it was multiplied by 401-65, which was not the desired result, because I was trying to generate a percent (meaning that 0 or 1 was really not useful). Thus the cast of that division as a float.

I find this sort of thing to be the one situation where a cast is really required ... where leaving it out results in your program not working, and it can be very confusing to figure out why.

Method Casting

And so finally we come to query that started this article off. If you compile the code associated with Listing 18.3, you'll see "Warning: 'UIView' may not respond to -addPic:at:'". This is a non-fatal warning that has to do with yet another casting nuisance. You'll find the line that generates the warning at the top of p.353:

[self.view addPic:myImageView.image at:myImageView.frame];

If you think about it, the reason for this warning should jump out. The view controller's view property is defined as a UIView, which does not contain the addPic:at: method introduced in CollageView. Thus, if you don't like the warning, you can just cast the property appropriately:

[(collageView *)self.view addPic:myImageView.image at:myImageView.frame];

You can run into this sort of thing when a property or method assumes a very specific class of object, rather than the more general "id." If memory serves I also hit it when using the nextResponder method (probably in Listing 14.2 on p.247).

Some Final Words on Casting Warnings

It's important to note that casting problems will generally result in warnings.You don't have to resolve them. In particular a warning about uncasted toll-free bridging or a warning about an uncasted method isn't a problem as long as you know what you're doing. It's usually worth fixing them, just to make sure that you understand the reason for the warning, but you don't have to if you're doing something quick-and-dirty or have some reason to leave the warning in.

(In the case of the warning generated by Listing 18.3 we opted to leave out the casting to keep the code more readable, not really thinking about the fact that people might be concerned about the warning if they compiled the code.)

Much more insidious are the math-related casting problems which probably won't generate a warning at all. In my opinion, they're what you really have to watch out for--and they're also a good reason to generally be conscientious about casting all the time, so that you don't run into mystery problems without warnings when you get careless about math casts.