Defining the Custom View Controllers for a Navigation Interface

One of the key things you must do to implement a navigation interface is decide what data you plan to present at each stage. Every navigation interface has at least one level of data that represents the root level of data. This is the starting point of your interface. For example, the Photos application displays the list of available photo albums at the root level of its data hierarchy. Selecting a photo album then displays the photos in that album and selecting a photo shows a larger version of the photo.

For each level of your data hierarchy, you must provide a custom view controller object to manage and present the data at that level. If the presentation at multiple levels is essentially the same, you can reuse the same view controller class if you want. However, at runtime, you must still create separate instances of that class and configure each one to manage its own set of data. For example, the Photos application has three distinct presentation types, so it would need to be three separate view controller objects, such as the ones shown in Figure 3-4.

With the exception of view controllers managing leaf data, each custom view controller must provide a way for the user to navigate to the next level of the data hierarchy. A view controller that displays a list of items can use taps in a given table cell to display the next level of data. For example, when a user selects a photo album from the top-level list, the Photos application creates a new photo album view controller. The new view controller is initialized with enough information about the album for it to present the relevant photos.

If your application has highly structured data, with a known progression from one level to the next, defining the view controllers at each level (and the relationships between them) should be relatively straightforward. (The Photos application always displays albums, followed by the contents of an album, followed by a single photo.) But if your application presents data differently depending on which item is selected at the current level, you might want to use additional information in your data model to determine how to present that data. You could use that information to determine whether to use different view controller classes or to customize the presentation style of a single view controller class. For example, viewing songs by Composer in the iPod application displays a list of albums or a list of songs depending on whether the songs for that composer come from the same album or from several different albums. In both cases though, the data is presented in list form using a table; therefore, you could use a single view controller but simply provide different table cells for each type of data.

For general information and guidance on defining custom view controllers, see Custom View Controllers.

Loading Your Navigation Interface from a Nib File

Although Interface Builder supports the inclusion of navigation controller objects in nib files, the semantics are slightly different than they are for custom view controllers. With a custom view controller, you use a nib file to store the views associated with the view controller, but you typically create the view controller separately—either programmatically or by loading it from a different nib file. However, with a navigation controller, the view is always created programmatically so there is no view to put in a separate nib file. One consequence of this behavior is that a navigation controller never manages a nib file—in other words, you never assign a navigation controller to the File’s Owner placeholder. Instead, the only time you mix navigation controllers and nib files is when the navigation controller itself is stored in the nib file. For this reason, a navigation controller is almost always a passenger in a nib file managed by some other object.

It makes the most sense to include navigation controllers in your application’s main nib file. You do this when the navigation controller itself provides the main view for your application’s window or in situations where the navigation controller provides the root view for a tab bar interface. Although you could also load standalone or modally presented navigation controllers from your main nib file (or any other nib file), doing so is not optimal. In those scenarios, it is usually easier to create the navigation controller programmatically at the point of use.

Figure 3-5 shows the configuration of the main nib file for an application that displays a navigation interface in its main window. The nib file includes the window object, the navigation controller, and the root view controller for the navigation interface, which is embedded inside the navigation controller itself. (The view managed by the root view controller typically would not need to be in the same nib file, and in this example is shown in a separate nib file.)

Because the navigation controller creates its view programmatically, you cannot install that view in a window using Interface Builder. Instead, you must also add the view to a window programmatically. If the window and navigation controller themselves are in a nib file, then you must remember to store references to those objects so that you can access them later.

To configure a navigation controller in a nib file, you do the following:

1. Drag a navigation controller object from the library to your Interface Builder document window.

   When you add a navigation controller, Interface Builder also adds a navigation bar, an embedded root view controller object, and a navigation item for your root view controller. You can access some of these objects by selecting them in the navigation controller edit surface. You can also select any of the objects from the document window when in outline and browser modes.

2. Save a reference to the navigation controller using an outlet.

   In order to access the navigation controller at runtime, you either need to use an outlet or you must explicitly retrieve the nib file’s top-level objects when you load the nib file. Using an outlet is generally much simpler. To add an outlet, add a variable to the declaration for your application delegate class that is similar to the following:

   @interface MyAppDelegate : NSObject <UIApplicationDelegate> {

   IBOutlet UINavigationController* myNavigationController;

   }

   @end

   After adding the outlet definition, create a connection from that outlet to the navigation controller object in Interface Builder.

3. Set the class of the root view controller to a custom class from your Xcode project.

   The class you choose should be the one responsible for displaying the highest-level data in your navigation hierarchy. If there are multiple levels of data, the view presented by your view controller class should include controls for navigating to the next level of data. For information about how to design your view controllers, see Defining the Custom View Controllers for a Navigation Interface.

4. Configure the view for your root view controller.

   You can include the view in the same nib file or store it in a different nib file. Using a different nib file is recommended because it gives the system the option of removing the view from memory during low-memory conditions.

   To specify a separate nib file, set the NIB Name attribute of the root view controller to the name of your nib file. To include the views in the same nib file as the navigation controller, drag your view objects to the navigation controller edit surface.

5. In the applicationDidFinishLaunching: method of your application delegate, add the navigation controller’s view to your main window.

   The navigation controller does not install itself automatically in your application’s window. You must do this programmatically with code similar to the following:

   - (void)applicationDidFinishLaunching:(UIApplication *)application {

   [window addSubview:myNavigationController.view];

   }

6. Save your nib file.

In addition to configuring the root view controller object, you can also use the inspector to change the attributes of the navigation item and navigation bar that Interface Builder creates. For the navigation bar, you can change some basic stylistic attributes. For the navigation item, you can specify a custom title and prompt text. If you do not specify a custom string for the navigation item, Interface Builder uses the string in the custom view controller’s title property.

The navigation controller’s edit surface provides a convenient way to edit the configuration of the navigation bar. To add additional buttons or views to the navigation bar, drag the appropriate objects from the library to the navigation bar in the edit surface. Doing so adds the corresponding objects to the root view controller’s navigation item. You can then configure the items you dragged as you would other Interface Builder objects. For example, you could connect buttons in the navigation item to action methods of your view controller in order to facilitate the handling of user taps at runtime.

For information about using Interface Builder to configure the contents of your nib files, including how to connect views and other controls to action methods, see Interface Builder User Guide.

Creating a Navigation Interface Programmatically

If you prefer to create a navigation controller programmatically, you may do so from any appropriate point in your code. For example, if the navigation controller provides the root view for your application window, you could create the navigation controller in the applicationDidFinishLaunching: method of your application delegate.

There are other situations where it might make more sense to create a view controller programmatically. For example, if you plan to present a navigation interface modally, it is usually simpler to create the navigation controller object at the point of use, present it, and then release it when it is no longer needed. Loading such a view controller from a nib file would require extra overhead for loading the nib file and might require you to store a pointer to the navigation controller object for longer than necessary.

When creating a navigation controller, you must do the following:

1. Create the root view controller for the navigation interface.

   This object is the top-level view controller in the navigation stack. The navigation bar displays no back button when its view is displayed and the view controller cannot be popped from the navigation stack.

2. Create the navigation controller, initializing it using the initWithRootViewController: method.

3. Add the navigation controller’s view to your window (or otherwise present it in your interface).

After you create the navigation controller, you can use it as appropriate. For example, you could add its view to your window, use it to initialize another view controller, or present it modally.

Listing 3-1 shows a simple implementation of the applicationDidFinishLaunching: method that creates a navigation controller and adds it to the application’s main window. The navigationController and window variables are member variables of the application delegate and the MyRootViewController class is a custom view controller class. When the window for this example is displayed, the navigation interface presents the view for the root view controller in the navigation interface.

Listing 3-1  Creating a navigation controller programmatically

- (void)applicationDidFinishLaunching:(UIApplication *)application

{

    UIViewController *rootController = [[MyRootViewController alloc] init];

    navigationController = [[UINavigationController alloc]

                                initWithRootViewController:rootController];

    [rootController release];

    window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];

    [window addSubview:navigationController.view];

    [window makeKeyAndVisible];

}

Configuring the Navigation Item Object

The structure of a navigation bar is similar to the structure of a navigation controller in many ways. Like a navigation controller, a navigation bar is a container for content that is provided by other objects. In the case of a navigation bar, the content is provided by one or more UINavigationItem objects, which are stored using a stack data structure known as the navigation item stack. Each navigation item provides a complete set of views and content to be displayed in the navigation bar. Unlike a navigation controller, a navigation bar is an actual view object that can be embedded inside other views.

Figure 3-7 shows some of the key objects related to a navigation bar at runtime. The owner of the navigation bar (whether it is a navigation controller or your custom code) is responsible for pushing items onto the stack and popping them off as needed. In order to provide proper navigation, the navigation bar maintains pointers to select objects in the stack. Although most of the navigation bar’s content is obtained from the topmost navigation item, a pointer to the back item is maintained so that a back button (with the title of the preceding item) can be created.

When used in a navigation interface, the contents of the navigation bar’s stack always parallel the contents of the parent navigation controller’s stack. In other words, for each view controller in the navigation stack, there is a corresponding navigation item in the same position on the navigation item stack of the navigation bar. The reason for this one-to-one correspondence is that each view controller actually provides its own navigation item.

A navigation bar has three primary positions for placing items: left, right, and center. Table 3-2 lists the properties of the UINavigationItem class that are used to configure each of these positions. When configuring a navigation item for use with a navigation controller, be aware that custom controls in some positions may be ignored in favor of the expected controls. The description of each position includes information about how your custom objects are used.

Figure 3-8 shows how the contents of the navigation bar are assembled for a navigation interface. The navigation item associated with the current view controller provides the content for the center and right positions of the navigation bar. The navigation item for the previous view controller provides the content for the left position. Although the left and right items require you to specify a UIBarButtonItem object, you can wrap a view in a bar button item as shown in the figure. If you do not provide a custom title view, the navigation item creates one for you using the title of the current view controller.

Showing and Hiding the Navigation Bar

When used in conjunction with a navigation controller, you always use the setNavigationBarHidden:animated: method of UINavigationController to show and hide the navigation bar. You must never hide the navigation bar by modifying the UINavigationBar object’s hidden property directly. In addition to showing or hiding the bar, using the navigation controller method gives you more sophisticated behaviors for free. Specifically, if a view controller shows or hides the navigation bar in its viewWillAppear: method, the navigation controller animates the appearance or disappearance of the bar to coincide with the appearance of the new view controller.

Because the user needs the back button on the navigation bar to navigate back to the previous screen, you should never hide the navigation bar without giving the user some way to get back to the previous screen. The most common way to provide navigation support is to intercept touch events and use them to toggle the visibility of the navigation bar. For example, the Photos application does this when a single image is displayed full screen. You could also detect swipe gestures and use them to pop the current view controller off the stack, but such a gesture is less discoverable than simply toggling the navigation bar’s visibility.

Modifying the Navigation Bar Object Directly

In a navigation interface, a navigation controller owns its UINavigationBar object and is responsible for managing it. It is not permissible to change the navigation bar object or modify its bounds, frame, or alpha values directly. However, there are a few properties that it is permissible to modify, including the following:

• barStyle property

• translucent property

• tintColor property

Figure 3-9 shows how the barStyle and translucent properties affect the appearance of the navigation bar. For translucent styles, it is worth noting that if the main view of the underlying view controller is a scroll view, the navigation bar automatically adjusts the content inset value to allow content to scroll out from under the navigation bar. It does not make this adjustment for other types of views.

If you want to show or hide the entire navigation bar, you should similarly use the setNavigationBarHidden:animated: method of the navigation controller rather than modify the navigation bar directly. For more information about showing and hiding the navigation bar, see Showing and Hiding the Navigation Bar.

Using Custom Buttons and Views as Navigation Items

To customize the appearance of the navigation bar for a specific view controller, modify the attributes of its associated UINavigationItem object. You can get the navigation item for a view controller from its navigationItem property. The view controller does not create its navigation item until you request it, so you should ask for this object only if you plan to install the view controller in a navigation interface.

If you choose not to modify the navigation item for your view controller, the navigation item provides a set of default objects that should suffice in many situations. Of course, any customizations you make take precedence over the default objects.

For the topmost view controller, the item that is displayed on the left side of the navigation bar is determined using the following rules:

• If you assign a custom bar button item to the leftBarButtonItem property of the topmost view controller’s navigation item, that item is given the highest preference.

• If you do not provide a custom bar button item and the navigation item of the view controller one level down on the navigation stack has a valid item in its backBarButtonItem property, the navigation bar displays that item.

• If a bar button item is not specified by either of the view controllers, a default back button is used and its title is set to the value of the title property of the previous view controller—that is, the view controller one level down on the navigation stack. (If the topmost view controller is the root view controller, no default back button is displayed.)

For the topmost view controller, the item that is displayed in the center of the navigation bar is determined using the following rules:

• If you assign a custom view to the titleView property of the topmost view controller’s navigation item, the navigation bar displays that view.

• If no custom title view is set, the navigation bar displays a custom view containing the view controller’s title. The string for this view is obtained from the title property of the view controller’s navigation item. If the value of that property is nil, the string from the title property of the view controller itself is used.

For the topmost view controller, the item that is displayed on the right side of the navigation bar is determined using the following rules:

• If the new top-level view controller has a custom right bar button item, that item is displayed. To specify a custom right bar button item, set the rightBarButtonItem property of the navigation item.

• If no custom right bar button item is specified, the navigation bar displays nothing on the right side of the bar.

To add some custom prompt text above the navigation bar controls, assign a value to the prompt property of the navigation item.

Figure 3-10 shows some different navigation bar configurations, including several that use custom views and prompts. The navigation bars in this figure are from the sample project NavBar: Customizing UINavigationBar's appearance.

Listing 3-2 shows the code from the NavBar application that would be required to create the third navigation bar in Figure 3-10, which is the navigation bar containing the right bar button item with a custom view. Because it is in the right position on the navigation bar, you must wrap the custom view with a UIBarButtonItem object before assigning it to the rightBarButtonItem property.

Listing 3-2  Creating custom bar button items

// View 3 - Custom right bar button with a view

UISegmentedControl *segmentedControl = [[UISegmentedControl alloc] initWithItems:

[NSArray arrayWithObjects:

[UIImage imageNamed:@"up.png"],

[UIImage imageNamed:@"down.png"],

nil]];

[segmentedControl addTarget:self action:@selector(segmentAction:) forControlEvents:UIControlEventValueChanged];

segmentedControl.frame = CGRectMake(0, 0, 90, kCustomButtonHeight);

segmentedControl.segmentedControlStyle = UISegmentedControlStyleBar;

segmentedControl.momentary = YES;

defaultTintColor = [segmentedControl.tintColor retain]; // keep track of this for later

UIBarButtonItem *segmentBarItem = [[UIBarButtonItem alloc] initWithCustomView:segmentedControl];

[segmentedControl release];

self.navigationItem.rightBarButtonItem = segmentBarItem;

[segmentBarItem release];

Configuring your view controller’s navigation item programmatically is the most common approach for most applications. Although you could create bar button items using Interface Builder, it is often much simpler to create them programmatically. You should create the items in the viewDidLoad method of your view controller.

Using Edit and Done Buttons

Views that support in-place editing can include a special type of button in their navigation bar that allows the user to toggle back and forth between display and edit modes. The editButtonItem method of UIViewController returns a preconfigured button that when pressed toggles between an Edit and Done button and calls the view controller’s setEditing:animated: method with appropriate values. To add this button to your view controller’s navigation bar, you would use code similar to the following:

myViewController.navigationItem.rightBarButtonItem = [myViewController editButtonItem];

If you include this button in your navigation bar, you must also override your view controller’s setEditing:animated: method and use it to adjust your view hierarchy. For more information on implementing this method, see Enabling Edit Mode for a View.

Specifying the Toolbar Items

When configuring bar button items, always remember to associate an appropriate target and action with the button. The target and action information is what you use to respond to taps in the toolbar. In most cases, the target should be the view controller itself, since it is responsible for providing the toolbar items.

Figure 3-12 shows a sample toolbar that places a segmented control in the center of the toolbar and Listing 3-3 shows the code needed to configure such a toolbar. You would implement the method in your view controller and call it at initialization time.

Listing 3-3  Configuring a toolbar with a centered segmented control

- (void)configureToolbarItems

{

   UIBarButtonItem *flexibleSpaceButtonItem = [[UIBarButtonItem alloc]

                        initWithBarButtonSystemItem:UIBarButtonSystemItemFlexibleSpace

                        target:nil action:nil];

   // Create and configure the segmented control

   UISegmentedControl *sortToggle = [[UISegmentedControl alloc]

                        initWithItems:[NSArray arrayWithObjects:@"Ascending",

                                        @"Descending", nil]];

   sortToggle.segmentedControlStyle = UISegmentedControlStyleBar;

   sortToggle.selectedSegmentIndex = 0;

   [sortToggle addTarget:self action:@selector(toggleSorting:)

               forControlEvents:UIControlEventValueChanged];

   // Create the bar button item for the segmented control

   UIBarButtonItem *sortToggleButtonItem = [[UIBarButtonItem alloc]

                                    initWithCustomView:sortToggle];

   [sortToggle release];

   // Set our toolbar items

   self.toolbarItems = [NSArray arrayWithObjects:

                         flexibleSpaceButtonItem,

                         sortToggleButtonItem,

                         flexibleSpaceButtonItem,

                         nil];

   [sortToggleButtonItem release];

   [flexibleSpaceButtonItem release];

}

In addition to setting toolbar items during initialization, a view controller can also change its existing set of toolbar items dynamically using the setToolbarItems:animated: method. This method is useful for situations where you want to update the toolbar commands to reflect some other user action. For example, you could use it to implement a set of hierarchical toolbar items, whereby tapping a button on the toolbar displays a set of related child buttons.

Showing and Hiding the Toolbar

To hide the toolbar for a specific view controller, set the hidesBottomBarWhenPushed property of that view controller to YES. When the navigation controller encounters a view controller with this property set to YES, it generates an appropriate transition animation whenever the view controller is pushed onto (or removed from) the navigation stack.

If you want to hide the toolbar sometimes (but not always), you can call the setToolbarHidden:animated: method of the navigation controller at any time. A common way to use this method is to combine it with a call to the setNavigationBarHidden:animated: method to create a temporary full-screen view. For example, the Photos application toggles the visibility of both bars when it is displaying a single photo and the user taps the screen.