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!