Enhancing the standard NSXMLParser class

Cocoa offers a "complete" XML parser with the NSXML family of classes. This tree-based parser is fairly sophisticated but it is not included in Cocoa-Touch. In the spirit of small and simple, iPhone developers have the NSXMLParser class to use. This is an event-driven parser, which calls methods on a delegate to handle "events" as it parses through the XML. The basic operation of the NSXMLParser class will not be covered here. This is well documented in the Apple Programming Guide "Introduction to Event-Driven XML Programming Guide for Cocoa". What I would like to introduce is an enhancement to this parser. For very simple XML parsing purposes, NSXMLParser is probably adequate, but it is not going to handle all your XML parsing needs. The biggest problem with this type of streaming parser is that you lose the structure of your data; your call-backs do not provide any context or hierarchy. Thus your parser:didStartElement and parser:foundCharacters methods tend to be very messy with lots of if/else if statements, and you have to keep track of your own context via instance variables.

A better way: a Tree

One solution is to use the parser to build a tree first, then your application can access the tree afterwards. Even the above referenced document alludes to this solution. Below is such a solution, an implementation of the XMLTreeParser and XMLTreeNode classes. The tree that is built uses nodes of type XMLTreeNode. The node is defined this way:

@interface XMLTreeNode : NSObject {
   XMLTreeNode* parent;
   NSString* name;                  // element name
   NSMutableDictionary* attributes;
   NSMutableString* text;           // from foundCharacters()
   NSMutableDictionary* children;   // key is child's element name, value is NSMutableArray of tree nodes
} 

Most of these properties are obvious. The text property is a concatenation of all the free-floating text that were inside an element. For example, the text "Hello World" would be stored in the text property:

<elementName>Hello World</elementName>

The choice of using a dictionary for the children property might be a curious one. The key of the dictionary is an NSString, which is the element name. The value of the dictionary is an NSArray of XMLTreeNode objects. To illustrate, here is some sample XML:

<stuff>
<item attr="value1"/>
<item attr="value2"/>
<note>TEXT</note>
</stuff>

Parsing this would create a root node with one child whose name is "stuff". The "stuff" node has two entries in its children dictionary: one entry for "item" and one for "note". The value for these entries is an NSArray of XMLTreeNode objects. The "item" array will have two nodes, and the "note" array will have only one. The use of a dictionary allows us to quickly search for children, as we'll see later. The downside of this is that the order of the "item" and "note" child nodes for "stuff" will not be retained. This is a side-effect of dictionaries not preserving the order. However, proper XML should not care about the order of the elements, only that the hierarchy is correct. I should note that the order of children of the same element is preserved. For example, when you query the tree, you have no idea if the "item" children will come before the "next" child or not. What you do know, though, is that you will get the item with "value1" before the item with "value2". This is important for the indexing scheme described below.

Building the tree

To create a parser, simply instantiate the XMLTreeParser class:

XMLTreeParser* parser = [[XMLTreeParser alloc] init];

This is a very simple implementation, so as it currently stands, an instance can only parse one XML input. There is no way to reuse a parser instance to parse some other XML. But that would be an easy exercise for the reader to address. Now to start parsing, call the parse method and provide the XML data:

XMLTreeNode* root = [parser parse:xmlData];

Again, this simple implementation only handles XML passed directly to it, not indirectly through a filename. When this returns, your XML has been completely parsed. The beautiful part is you don't have to write all those event handlers. What you get back is the root node of the tree. This node does not have any useful data other than its children. This return will be nil if there is any problem parsing the supplied XML.

Querying the tree

Now you could traverse through the tree manually looking for things. A good demonstration of how to do this is in the XMLTreeNode method "description". This method will recreate the XML from the tree; unparse it, if you will. It will dump out the element name and any attributes. Then it will iterate over all the children and recursively call description on all of them. Please take a look at the implementation of -(NSString*) description in the XMLTreeNode class to see this. For simpler queries, the XMLTreeNode class offers methods to find child nodes. These are the find* methods.

Do you know where your children are?

The most basic find method is findChildren. This simply returns an array of children that match the given element name. Referring back to the simple XML above, the statements below will pull out a list of XMLTreeNodes for the "item" elements:

NSArray* stuffs = [root findChildren:@"stuff"];
XMLTreeNode* stuff = [stuffs objectAtIndex:0];
NSArray* items = [stuff findChildren:@"item"];

OK, this is great, but a little cumbersome. If you know that there is only one "stuff" element, it's a shame you have to get back an array of them. So there is the findChild method, which returns a single XMLTreeNode object:

XMLTreeNode stuff = [root findChild:@"stuff"];

What if there are more than one "stuff" elements? This version of findChild: always takes the first element in the array. If you want a different element, you must use findChild:at:

XMLTreeNode* item2 = [stuff findChild:@"item" at:1];

This will return the second "item" node.

Getting deeper

Pretty cool, but this is still a little cumbersome. What if you have XML with elements 10 layers deep? That means at least 10 separate calls to findChild:. The findChild: method supports paths. Here is an example to get the first "item" node in one call:

XMLTreeNode* item1 = [root findChild:@"stuff/item"];

This basically combines two searches into 1. Now, for your 10-deep XML, you could use something like this:

XMLTreeNode* deep = [root findChild:@"stuff/items/item/something/lists/list/test"];

That's 7 searches in 1.

Pinpoint accuracy

Note that for every step through the path in the above example, if there are more than one element with the same name, this will traverse the first one. If you want a different element besides the first one, then you would have to fall back on the single-step findChild:at: method. Or, you can specify an index:

// I want the 3rd doodad in the 4th thingamajig of the 2nd whatchacallit
XMLTreeNode* doodad3 = [root findChild:@"whatchacallit[1]/thingamajig[3]/doodad[2]"];

Remember that these indeces are 0-based, so they are one less than what you'd expect. Now you can dig around in your XML to your heart's content. Be aware that if the query fails anywhere along the path, it will return nil. So if you get nil back from a find method, you can assume that it didn't find what you were looking for.

Optmization

If you find yourself traversing over the same ground over and over, you can move your starting point. There is no need to always start at the root node. Each node has these find methods, so you can get a new starting point and search from there:

XMLTreeNode* searchRoot = [root findChild:@"stuff/same/old/path"];
XMLTreeNode* newThing = [searchRoot findChild:@"cool/new/thing"];

Think of this as changing your current directory so you don't always have to type in the full path.

Room for improvement

That's it for now. This simple implementation could have a lot more features added. For instance, you could pluck out attributes from a path like this:

NSString* value = [root findChildAttr:@"stuff/item[1].value"];

This would get the attribute "value" from the second "item" element under "stuff". But what it does now is all that was required for my current project. Other enhancements could follow as the needs arise.

Download

You can access the source code to XMLTreeParser and XMLTreeNode here.

Trapping the UINavigationBar Back Button

I recently had a need to trap the back button tap on the navigation bar in order to do something before popping to the previous controller. However, I soon discovered that this was not possible. The standard back button is a "special" button that developers cannot override, at least not with the current public SDK.

The only thing you can change on the standard back button is the text. By default, this is the title of the controller. You can change it with code like this:

[self.navigationItem.backBarButtonItem = [[UIBarButtonItem alloc] initWithTitle:@"New Title" style:UIBarButtonItemStyleBordered target:nil action:nil]; 

The important but subtle thing about a controller's backBarButtonItem property is that it is not the back button displayed when that controller is on top; it is for other controllers that are pushed on top of it. In other words, if you have a "root" controller whose title is something very long, you set its backBarButtonItem title to something shorter. Then when other controllers are pushed on the stack, they will use this back button item as their back button. This is unintuitive at first glance, but makes sense when you think about it: you can redefine the back button title once, and all other controllers that are pushed on top will use this back button.

Even though there are four parameters to the initializer, only the title is used for this "special" back button. The style specified seems to be ignored, as are the target and action parameters. Because of this, you cannot insert your own event handler for the back button, which is what I needed to do.

After some digging and research, I have a solution. It is not a pretty solution, but it's good enough.

The navigationItem property of a UIViewController has another property called leftBarButtonItem. This, like the backBarButtonItem, is a UIBarButtonItem object. If you set this to something other than nil, then this new button will replace the standard back button item. So now, I can get my custom back button event handler to work, because this one honors the style and the target/action parameters:

- (void) viewDidLoad
{
   // change the back button and add an event handler
   self.navigationItem.leftBarButtonItem =
   [[UIBarButtonItem alloc] initWithTitle:@"Pages"
                                    style:UIBarButtonItemStyleBordered
                                   target:self
                                   action:@selector(handleBack:)];
}

- (void) handleBack:(id)sender
{
    // do your custom handler code here

    // make sure you do this!
   // pop the controller
    [self.navigationController popViewControllerAnimated:YES];
}

If you still want this button to behave like a back button, it is important to put the popViewControllerAnimated: call in your handler. I should also say that this leftBarButtonItem should be set on the controller who will actually show the back button, unlike the backBarButtonItem. Now the reason I stated this wasn't a perfect solution is the following: The "special" back button looks different. Here is what the standard backBarButtonItem looks like:

Yet, the leftBarButtonItem looks like this:

I have been unable to force my custom back button to have the different shape. This is another indication that this back button object is treated specially that is not exposed in the SDK. Other than this little aesthetic discrepency, this approach met my needs. Hopefully it will meet yours as well.

A General Purpose Table Form Editor

Note: You may have come here from another link. Be aware that I have updated this package and can read about it here. Sometimes your iPhone applications need the ability to enter or edit data on a form. For example, here is a screen from the contacts app when adding a new contact:

If you have ever coded up the UITableViewController class to do this sort of the form editing, you know that this coding task is very tedious and time-consuming. Wouldn't it be nice if there was a general purpose, reusable class for doing this? Here I present such a class.

Features

The TableFormEditor class is intended to be used within a UINavigationController. In other words, you allocate a TableFormEditor instance, configure it, then push it on top of the navigation stack. The TableFormEditor will create a grouped table and the first section will contain rows with UITextField objects to display and allow editing of data. These rows can optionally contain labels that identify what each row represents, or you can have no labels as in the above example. Optionally, you can configure a delete button to appear at the bottom of the form. This is intended to allow the user to delete the record. The text on the button is configurable. The action of the delete button will ask for confirmation before continuing.

Basic Usage

Here is how the TableFormEditor works:

1. You allocate and initialize a TableFormEditor object.
2. You configure various other aspects of the object, such a your fields names and what your data is.
3. Then you push the object onto the navigation controller stack. At this point, the TableFormEditor is in control.
4. You can bounce around the fields and edit to your heart's content. When you are done, you hit the "save" button. This will pop the controller off the navigation stack and send a message to the delegate you provide, passing the new data. It is up to your delegate to do something with this data.
5. If you decided to hit "cancel" instead, the controller is popped off the navigation stack and a message is sent to the delegate.
6. If you have a delete button enabled, and this button was selected, then the controller is popped off the stack and a different message is sent to the delegate.

Each of these steps is discussed in greater detail below.

Initialize

There are two schools of thought concerning initializers. Some like to force the user to pass all required parameters, often resulting in very long initializer statements. The other side prefers simple initializers, and the remainder of the parameters can be set as properties. The benefit of the former is that there will be no forgetting to set a required parameter. However this approach is not very flexible; any new additions or changes to the class often require the initializer to be changed. Very specialized initializers create fragile code. Therefore I have opted for the approach of simple initializers and setting properties. True, some properties must be set, otherwise the resulting code will be next to useless. However, I will document clearly which properties are mandatory and which are optional. There are two modes the TableFormEditor can be in: edit mode or add mode. In edit mode, you are editing/viewing existing data. In add mode you are adding a new record. What mode you're using has subtle differences in the default behavior. For instance, in add mode there isn't a delete button displayed, since there is no record yet to delete. To initialize for add mode, use the initForAdd: method:

TableFormEditor* add = [[TableFormEditor alloc] initForAdd:self];

All you provide is the delegate, typically self. The delegate must conform to the protocol TableFormEditorDelegate:

@protocol TableFormEditorDelegate
@optional
- (void) formDidCancel;
- (void) formDidSave:(NSMutableDictionary*) newData;
- (void) formDidDelete;
@end

All these methods are optional, but obviously without the formDidSave: you don't have very functional software. To initialize for edit more, use the initForEdit: method.

TableFormEditor* edit = [[TableFormEditor alloc] initForEdit:self];

Just as with the add mode, you pass in a delegate to handle the same protocol.

Configure

Now we'll discuss all the various properties you can and must set to configure the form editor. Note that even though some of these are labelled as "required", that doesn't mean your program will crash without them. But you may not see very interesting results.

Required

NSArray* fieldNames

This is a list of NSString objects which are the field names. Each field equates to a row in the form. This list serves several purposes:

1. It determines how many rows to create in the table,
2. It provides the labels to preface each row with,
3. It provides the order to present the fields in the form, and
4. It provides the key names to be used in the data dictionary.

Note that the data you provide in the data dictionary (described next) must use keys that match these names.

NSMutableDictionary* fieldData

This is the data. Depending on the mode the object was initialized with, this data has different purposes. If initialized in edit mode, then this data represents the current data. The keys are the fieldNames given above. The values are the data. Both of these are assumed to be NSString objects. If the form editor was initialized in add mode, then this data represents the placeholder text to put in each row. The example above shows placeholder text on each row. This text gives the user a hint what's to go in that field, and it disappears as soon as you start entering text. If you don't want placeholders, don't set the data. This dictionary is copied (deep copy), because TableFormEditor may modify the values.

Optional

id <TableFormEditorDelegate> delegate

This is the delegate to handle the callbacks when the user wants to exit the form. This is set up in the initializer, but if you ever need to change it, you can via this property.

BOOL showLabels

When the form rows are displayed, by default each row has the field name displayed on the left as a label. This may be overkill, especially if you use placeholders, so you can turn off the labels by setting this property to NO.

BOOL allowDelete

In edit mode, by default, this is set to YES. When YES, a delete button will be displayed after the form. Set to NO if you don't want to see the delete button. If you are in add mode, and for some reason want the delete button, you will have to force it by setting the property to YES.

NSString* deleteButtonLabel

If a delete button is displayed, this is the text used. If unset, it will use "Delete".

NSString* saveButtonLabel

The TableFormEditor puts a button in the right position of the nav bar. This button is for saving your changes and exiting the form. By default, the button text is "Save", but this can be modified with this property.

NSString* cancelButtonLabel

The TableFormEditor also puts a button in the left position of the nav bar. This is for canceling any edits made and exit the form. By default, the button text is "Cancel". Modify with this property.

NSInteger firstFocusRow

By default, the form editor will place the focus (first responder) on the first row (row 0). This action brings up the keyboard automatically. If you wish to have the focus placed somewhere else first, set this property to the row you want. If you don't want any row given focus (and thus no keyboard will come up automatically), then set this property to -1.

NSString* title

This is the title string placed in the middle of the nav bar. Default value is blank.

Future

In future releases of TableFormEditor, I will be adding more configuration options, like options to configure the keyboard and how the text fields behave.

Download

The source code to the TableFormEditor class can be freely downloaded here: version 1.0 . This software is covered under the MIT License.

Tab Bar Icons (part 2)

In part 1 of this article I talked about general guidelines for the icons in a tab bar view. In this part, I will go into specifics as to how to actually create tab bar icons. One thing I noticed is there is little documentation or help out there on the Web regarding tab bar icons, so hopefully this information will be beneficial. Since I wrote part 1, I have found that the Apple documentation may be incorrect when it states that the icons should be 30x30 points. By making icons exactly that size, I found the icons were too big and they were truncated. I have since changed over to icons the size of 30x30 pixels and that seems to work well. In fact, the iPhone Human Interface Guidelines does specify "about" 30x30 pixels. There definitely is extra space to grow, but 30x30 pixels will be my starting point and only increase in size if I need the extra space. As a reminder, we're looking to create these type of icons:

1. PNG
2. 30x30 pixels
3. no color, as alpha values determine the image and shading
4. transparent background

Drawing without color is basically impossible, so I use black & white. Even the black and white colors are thrown out since the tab bar just uses the alpha channel data. By using black and white, it allows me to draw without fussing with colors. One important thing to realize is that tab bar icons are inverted. Things that you draw black come out white; things that you draw white are black. If you're old enough to remember film negatives, it is the same concept. You might be tempted to make your icons already inverted so that they look "normal" in the tab bar, but I believe this would be a mistake. Judging by the Apple application tab bar icons (You Tube and iPod), it is expected for the icons to be negatives. Another important point is that when you draw a black line, you are not applying a black color on top a white canvas. Drawing with alpha channels is a bit of a paradigm shift. Think of this way: you have a black canvas. You draw on this canvas using white paint. If you use really thick paint (a high alpha value), then this will show as bright white. If you thin your paint (a low alpha value), then some of the black from the background will bleed through, making is less bright and more gray. This is exactly what an alpha value is: it is the degree of transparency. A low alpha value means it is completely transparent. Using an alpha value of 0 means none of the white shows. As you increase the alpha value, the white color becomes less and less transparent, thus becoming brighter. When the alpha value is at its max of 255, it is completely opaque and you cannot see through the paint at all. Thus it shows up as white. Hopefully you aren't totally confused by now! An example will help demonstrate some of these concepts. Let's say we want to create a typical "documents" icon, three pages of paper stacked on one another. The top page could have some super tiny text on it. A "normal" icon for this would look like this:

When this is displayed in the tab bar, it looks like this:

See how this is a negative of our original icon? Everywhere you see white means those lines have an alpha value of 255. If this negative effect drives you crazy, you probably could draw using white paint on a black background, and then remove the background just before exporting the image. Again, the black and white colors are meaningless here; you could use purple and pink if you wish. It is the alpha values that are important, so make sure your white paint (or pink) has a high alpha value. So, how do we make such an icon? Icons can be created with numerous tools, but I will focus on one that I feel is best suited for this task, and the price is right (free). Inkscape is a Windows, Linux, and Mac OS vector graphics editor. It is freely available and can be found on the web here: Inkscape homepage. If you are installing Inkscape on Leopard, you may have a problem with it hanging while caching fonts. This is a bug that is easily fixed by going into the terminal and typing this:

$ mkdir ~/.fontconfig

After this, it should start normally. I didn't experience this when I installed version 0.46, so this may be fixed already. When you fire up Inkscape, you see a blank canvas that looks like this:

Edit the properties of this to get what we need. Select the menu File>Document properties... Set the size in the "Custom size" box. Make sure the units is "px" (pixels) and the width and height both to 30. You might also want to disable snapping, which I find annoying when trying to position drawings exactly where I want them. This is the "Enable snapping" checkbox on the snap tab. Close the properties window. Now, your canvas is probably really small, so select the menu option View>Zoom>Page to zoom the canvas to fit the window. To get into black and white mode, select grayscale from the color palette on the bottom. You can bring up the color palette window by clicking on the little triangle I circled in red in the lower right of the picture above. Inkscape automatically has a transparent background, so there is nothing more you need to do there. The area inside the gray border is your canvas. Even though this is white, remember it will be black on the tab bar. So the first thing we want to do is create the top page. Choose the "rectangle and square" tool on the left tool bar, or hit f4. Click where you want the top left corner and drag. Put the rectangle a little low and to the left to leave room for the other pages. We can center everything later. Once you have your rectangle, we need to fix it up. Select menu item Object>Fill and Stroke The fill is what is inside the object, and the stroke is the outline around the edge. What we want is a stroke with a high alpha (255) so that the border of the page shows as white, but the fill should be black, meaning an alpha of 0. The diagram below shows setting the fill alpha to 0:

Alpha values are the A at the bottom of the RGB tab. At the far left of the alpha scale it shows a checkerboard pattern. This indicates transparency. As you go higher, the checkerboard disappears and black replaces it. You could also hit the "X" button to remove the fill altogether, which will result in a transparent fill. Now we show the properties for the stroke paint. We want the stroke to have a high alpha value so it looks white in the tab bar:

You can also go to the "Stroke style" tab and play around with the line thickness and line pattern. Now we need to put pages in the back. You might be thinking that since this editor can do layers, you can simply copy the top page, shift it over some, and then put that layer underneath. Well, that won't work (at least I don't know how to make it work). Because the top page has a transparent fill (alpha of 0), the border of the bottom page shows through. What you end up with is this:

This is not what we want. Here lies a problem with using alpha values. It makes it very difficult to layer objects. It's best to think of creating a "flat" picture. All impressions of depth are fake. So instead of layering another page below the first one, we cheat and just draw the outline of the page edges next to the top page. When you're working with icons, it's also best to turn the grid on, which makes drawing lines easier. View>Grid. Use the Bezier curve tool to draw straight lines. Click once to select the starting point and move your mouse (don't hold the mouse button down). When you want to change direction, click to set another point. Double click to create your final point. For the right angle shown below, it consists of:

1. click to start, then move mouse right
2. click to form angle, then move mouse down
3. double click to end

Draw the third page the same way. Or to make it easier, duplicate the second one via ctrl-D, then drag the third one into place:

I will leave the "text" on the top page as an exercise to the reader. (Hint: use the bezier curve tool to draw lines, then adjust the stroke style of each line to be dotted.) Let's save it and try it out. To save as a PNG file, it is a bit non-intuitive: File>Export bitmap... select "Page" for the Export area select "Browse" button and choose location to put file. Find folder and type in filename. Inkscape will provide the .png extension for you. Hit "Save" This doesn't actually "Save" the file. You then need to hit "Export" button What you have is an icon that looks like this:

When I insert this into my tab bar, I get this result:

Notice how the large icon doesn't look like much, but when it is shrunk down to icon size, it doesn't look too bad. You even can see the 3-D effect that is not apparent in the full-size version. This is due to the loss of detail when it gets smaller, and your eyes/brain fill in the gaps. Think of it as the "Monet affect", where his paintings just look like a bunch of dots up close, but as you step back, you lose detail and the picture morphs into something beautiful. To help you visualize your icon as you are drawing your image, Inkscape has an icon preview mode which shows your current drawing in various icon sizes. Select menu View>Icon Preview... to bring up that window. That should be a good start to get you going on creating your own tab bar icons. I strongly urge you to learn more about Inkscape; it is a very powerful tool and can also handle all your other icon needs. Good luck and create something beautiful!

Radio-button behavior for table rows

One thing missing from the iPhones UI kit is a plain old radio button. There are some controls that kind of give you the exclusive selection behavior, like a tab bar or a segment control, but there is nothing like a typical RadioButton widget. The closest you can probably get using the standard UIKit framework is a table. Tables have rudimentary support for radio button behavior. When using the standard UITableCell class, it has provisions for setting the accessory type of a row to a checkmark. You have probably seen this technique in the calendar app while editing an event alert. Your choices are presented like this:

Unfortunately, this is pure visual asthetics; you still have to manage the exclusive behavior in your code. The document "Table View Programming Guide for iPhone OS " has a good example of how to implement both exclusive and inclusive selections in chapter 7 that makes use of the checkmark accessory. I won't repeat that code here, but in a nutshell, this example code handles the message tableView:didSelectRowAtIndexPath:, and what it does (for the exclusive selection behavior) is find the previously selected cell, clear it's accessory checkmark, and put the checkmark on the current cell. It's a little cumbersome, but it works. This is all fine, but what if you didn't want to use the checkmark accessory? I have an application where I need to use the disclosure button accessory, so I needed to implement the checkmark somewhere else. The solution I chose was to create my own checkmark icon and place that in the image portion of the standard cell, over on the left hand side of the cell. I quickly discovered, though, that you can't use the same technique as in the above document. If you change the image of a cell, the changes will not be seen. For some reason, changing the accessory type of a cell is rendered immediately, but not so for the image. The only way I could get the image change to be reflected is to call reloadData: on the table view. After I did that, everything worked. However, I took this opportunity to clean up the clunky code from the example. Instead of finding my old cell, all I do in tableView:didSelectRowAtIndexPath: is set the current active row in our data and call reloadData:. The real work was moved over to the table:cellForRowAtIndexPath: method, which sets the image for each cell according to the active row. First we must handle the row selection. The instance variable activeRow is simply an integer of the currently selected row.

- (void)
tableView:(UITableView *) aTableView didSelectRowAtIndexPath:(NSIndexPath *) indexPath
{
 [aTableView deselectRowAtIndexPath:indexPath animated:NO];

 if(indexPath.row != activeRow) {
    // reset the active account
    activeRow = indexPath.row;

    // tell the table to rebuild itself
    [aTableView reloadData];
 }
}

Next we handle the actual image setting:

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

 if (cell == nil) {
    cell = [[UITableViewCell alloc] initWithFrame:CGRectZero reuseIdentifier:@"Cell"];

    // set up the cell properties that are the same for all cells on this table
    cell.accessoryType = UITableViewCellAccessoryDetailDisclosureButton;
 }

 // get our text for the row
 cell.text = [self.data forRow:indexPath.row];

 if(indexPath.row == activeRow) {
    cell.image = checkedImage;
 }
 else {
    cell.image = uncheckedImage;
 }

 return cell;
}

After we get a cell to work with, I compare the row with the active row. If it is a match, I use the checked image. If not I use the unchecked image. Here is the final output:

Tab Bar Icons (Part 1)

Tab bars are for toggling between application views. This is a common controller on the screen-constrained iPhone. Not to be confused with toolbars, tab bars are the black bars at the bottom of the screen with gray unselected icons and one blue selected icon. You see tab bars in the phone and ipod and YouTube apps, among others. Here is an example, from the ipod app:

When you are creating a tab bar for your own application, you face the problem of providing the icons. You have several options here. Your first option is to use one of Apple's system icons. Like the navigation bar, you have access to some of Apple's system icons, and they even encourage you to use them. Unfortunately, there are a couple caveats with using these. First, the list is pretty skimpy. Second, the icons include the text as well. You cannot set the image and the text separately; it's both or nothing. Here is what is offered:

icon	text	enum
	More	UITabBarSystemItemMore
	Favorites	UITabBarSystemItemFavorites
	Featured	UITabBarSystemItemFeatured
	Top 25	UITabBarSystemItemTopRated
	Recent	UITabBarSystemItemRecents
	Contacts	UITabBarSystemItemContacts
	History	UITabBarSystemItemHistory
	Bookmarks	UITabBarSystemItemBookmarks
	Search	UITabBarSystemItemSearch
	Updates	UITabBarSystemItemDownloads
	Most Recent	UITabBarSystemItemMostRecent
	Most Viewed	UITabBarSystemItemMostViewed

If you can make use of them, you access them via an enum for each defined in the UITabBarItem class. Here is how you would programatically set your tab bar image to the magnifying glass:

self.tabBarItem = [[UITabBarItem alloc] initWithTabBarSystemItem:UITabBarSystemItemSearch tag:0];

You execute this in your UIViewController subclass that you are putting into the tab bar. This is best done in your view controller's initializer method:

- (id) init
{
self.title = "search";
self.tabBarItem = [[UITabBarItem alloc] initWithTabBarSystemItem:UITabBarSystemItemSearch tag:0];
return self;
}  

If the system icons don't meet your needs, some people have suggested doing a screen capture of an app that has an icon you like. Ignoring the legalities of this, this may not give you good results because Cocoa-Touch has already applied affects to the icons. Your next option would be to search for some free or pay-for icons. I noticed many freelance graphics designers putting their shingle up and offering their services. I didn't look long, but I did not find any suitable, free icons for iPhone tab bars. This leaves you one last option: create your own. So the first questions that come up are:

1. what format?
2. what size?
3. what colors?

After researching these questions, I found some conflicting answers and lots of confusion among the iPhone developer community. I will try to summarize and disperse the clouds. For format, this is pretty well agreed upon to be PNG, which is the image format of choice on the iPhone. You're not limited to this format, but PNG is the recommended format and gives best performance. The background should be transparent, else your icon will be a plain square. The size issue is a bit more contentious. I saw reports of sizes ranging from 20 x 20 all the way up to 57 x 57. Most people don't differentiate between pixel or point sizes, and they are different. Here is what Apple says in the reference documentation for the UITabBarItem:

If this image is too large to fit on the tab bar, it is scaled to fit. The size of an [sic] tab bar image is typically 30 x 30 points.

Note it doesn't say what the max size is before it gets scaled. One poster thought the max size was around 48 x 32 before scaling happens. But if Apple doesn't publish this information explicitly, I would hesitate to use it. You could explore yourself to find out what the max is, but obviously Apple would like to retain some latitude in this area to possibly change it in future firmware releases. I believe 30 x 30 is a safe size that will give you the best look. There also seems to be a great deal of confusion regarding colors. From my research, colors are basically ignored. Here is what the Apple document "View Controller Programming" has to say about it:

The unselected and selected images displayed by the tab bar are derived from the images that you set. The alpha values in the source image are used to create the other images—opaque values are ignored.

In other words, Cocoa Touch will create new images from your source images, using alpha values only. Alpha, in the PNG world, is the degree of a pixel's opacity. Maximum alpha values denote a completely opaque pixels. In the example below this quoted text, they have an example source image and the resulting unselected and selected icons. Color is irrelevant. In part 2 of this article, I will discuss various tools used to compose icons, specifically how to create tab bar icons.

Property Pitfalls and Patterns

Properties are a handy, if not a cumbersome, addition to Objective-C 2.0. Although they add a good deal of convenience, you must never forget what is happening under the covers, else you could end up with problems and confusion. The problem I blindly walked into was not considering the automatic retain done when using the setter. Consider this statement:

self.name = input_name;

This actually invokes a setter that the compiler has synthesized for you. If you declared the property with the "retain" attribute, as in this:

@property (nonatomic,retain) NSString* name;

then what the above assignment will do is:

1. release whatever name is pointing to
2. set the new value
3. retain the new value (take ownership)

This shortcut is extremely handy; however, it's easy to forget that there are some cases where you are already the owner of an object, so the retain is redundant and will cause a memory leak:

self.name = [[NSString alloc] initWithString:input_name];

When you alloc an object, the retain count is already set to one. When you assign this to your property, the setter will bump up the retain count again. The retain count of self.name is now 2. Thus, you have a memory leak. [update date:@"Feb 19, 2009"]; It should be noted that the line above is different than this line:

name = [[NSString alloc] initWithString:input_name];

This form is accessing the instance variable directly, whereas the self.name form is invoking the property's setName: method. This distinction is important because when you skirt around the setter, you don't get the 3 little "side-effects" mentioned above. This can be both useful and dangerous. I recommend NOT using the instance variable directly if it is a property, unless you are in an initializer. It is just too easy to get things wrong; if you assign directly to the instance variable and it already has something assigned to it, you get a memory leak. It is best to be consistent with how you use your properties. [endupdate]; There are a couple solutions I have seen so far, but I don't think any of them are very pretty. One common trick is to autorelease the return from init. This way, the retain count will still be 2, but the next time the autorelease pool is emptied, the redundant reference is cleaned up:

self.name = [[[NSString alloc] initWithString:input_name] autorelease];

This violates the general rule of avoiding autorelease as much as possible. Autoreleasing will release the memory (at some point), but you have no control when that actually happens. Memory could get bloated or even run out before it does happen. When coding on a limited resource device like the iPhone, I think this is a good rule to follow. Another solution is simply to release after the assignment:

self.name = [[NSString alloc] initWithString:input_name];
[self.name release];

But this is non intuitive and can be confusing. A clumsier but cleaner way would be to use a local variable:

NSString* temp = [[NSString alloc] initWithString:input_name];
self.name = temp;
[temp release];

Any other ideas on how best to do this? There is another pattern in common use that I missed in my first applications. It concerns dealloc and properties. Here is what I used to do:

- (void) dealloc
{
  [property1 release];
  [property2 release];

  [super dealloc];
}

Seems perfectly reasonable, and I believe in most cases, this is fine. However, the preferred mechanism for releasing properties is to assign nil to them:

- (void) dealloc
{
   self.property1 = nil;
   self.property2 = nil;

   [super dealloc];
}

So what's the difference? I'm still searching for the definitive answer, but I believe this is preferred because it releases the property and sets it to nil. How? At first glance, this looks like a memory leak. But remember the steps that synthesized setters do for you: 1) release the old value, 2) assign the new value, then 3) retain the new value. In this case, you can't retain nil, so the 3rd step is a no-op. This is a common technique in C++ destructors, which prevents a deallocated pointer from being used later on. This syntax is not intuitive, though, and you have to understand what's going on in the setter.