UINavigationController Class Reference

Overview

The UINavigationController class implements a specialized view controller that manages the navigation of hierarchical content. This class is not intended for subclassing. Instead, you use instances of it as-is in situations where you want your application’s user interface to reflect the hierarchical nature of your content. This navigation interface makes it possible to present your data efficiently and also makes it easier for the user to navigate that content.

The screens presented by a navigation interface typically mimic the hierarchical organization of your data. At each level of the hierarchy, you provide an appropriate screen (managed by a custom view controller) to display the content at that level. Figure 1 shows an example of the navigation interface presented by the Settings application in iPhone Simulator. The first screen presents the user with the list of applications that contain preferences. Selecting an application reveals individual settings and groups of settings for that application. Selecting a group yields more settings and so on. For all but the root view, the navigation controller provides a back button to allow the user to move back up the hierarchy.

Figure 1  A sample navigation interface

A navigation controller object manages the currently displayed screens using the navigation stack. At the bottom of this stack is the root view controller and at the top of the stack is the view controller currently being displayed. You use the methods of your navigation controller object to modify the stack at runtime. The most common operation is to push new view controllers onto the stack using the pushViewController:animated: method. Pushing a new view controller object onto the stack causes the view of that view controller to be displayed and the navigation controls to be updated to reflect the change. You typically push view controllers in response to the user selecting an item that leads to the next level in your information hierarchy.

In addition to pushing view controllers onto the navigation stack, you can also pop them using the popViewControllerAnimated: method. Although you can pop view controllers yourself, the navigation controller also provides a back button (when appropriate) that pops the top view controller in response to user interactions.

A navigation controller object notifies its delegate object in response to changes in the active view controller. The delegate object is a custom object provided by your application that conforms to the UINavigationControllerDelegate protocol. You can use the methods of this protocol to respond to the change and perform additional setup or cleanup tasks.

For more information about how to integrate navigation controllers into your application, see View Controller Programming Guide for iPhone OS.

Navigation Controller Views

Because the UINavigationController class inherits from the UIViewController class, navigation controllers have their own view that is accessible through the view property. When deploying a navigation interface, you must install this view as the root of whatever view hierarchy you are creating. For example, if you are deploying the navigation interface by itself, you would make this view the main subview of your window. To install a navigation interface inside a tab bar interface, you would install the navigation controller’s view as the root view of the appropriate tab.

The view for a navigation controller is just a container for several other views, including a navigation bar, an optional toolbar, and the view containing your custom content. Figure 2 shows how these views are assembled to present the overall navigation interface. Although the content of the navigation bar and toolbar views changes, the views themselves do not. Only the custom content view changes to reflect the view controller that is at the top of the navigation stack.

Figure 2  The views of a navigation controller

The navigation controller is responsible for managing the configuration and display of the navigation bar and navigation toolbar. You must never modify these views directly. Instead, you should manipulate them through the methods and properties of the UINavigationController class. You can hide and show the navigation bar using the navigationBarHidden property or setNavigationBarHidden:animated: method. To specify custom items for the navigation bar, you configure the displayed view controller as described in “Updating the Navigation Bar.” For information on how to specify items for the navigation toolbar, see “Displaying a Toolbar.”

With only a few exceptions, you should never modify the navigation bar object directly. It is permissible to modify the barStyle or translucent properties of the navigation bar but you must never change its frame, bounds, or alpha values directly. In addition, the navigation controller object builds the contents of the navigation bar dynamically using the navigation items (instances of the UINavigationItem class) associated with the view controllers on the navigation stack. To change the contents of the navigation bar, you must therefore configure the navigation items for your custom view controllers. For more information about navigation items, see UINavigationItem Class Reference.

Updating the Navigation Bar

When the user changes the top-level view controller, whether by pushing or popping a view controller or changing the contents of the navigation stack directly, the navigation controller updates the navigation bar accordingly. Specifically, the navigation controller updates the bar button items displayed in each of the three navigation bar positions: left, middle, and right. Bar button items are instances of the UIBarButtonItem class. You can create items with custom content or create standard system items depending on your needs. For more information about how to create bar button items, see UIBarButtonItem Class Reference.

The bar button item on the left side of the navigation bar allows for navigation back to the previous view controller on the navigation stack. The navigation controller updates the left side of the navigation bar as follows:

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

• If the top-level view controller does not have a custom left bar button item, but the navigation item of the previous view controller has a valid item in its backBarButtonItem property, the navigation bar displays that item.

• If a custom 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 stack. (If there is only one view controller on the navigation stack, no back button is displayed.)

The navigation controller updates the middle of the navigation bar as follows:

• If the new top-level view controller has a custom title view, the navigation bar displays that view in place of the default title view. To specify a custom title view, set the titleView property of the view controller’s navigation item.

• If no custom title view is set, the navigation bar displays a label containing the view controller’s default title. The string for this label is usually obtained from the title property of the view controller itself. If you want to display a different title than the one associated with the view controller, set the title property of the view controller’s navigation item instead.

The navigation controller updates the right side of the navigation bar as follows:

• 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 view controller’s navigation item.

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

The navigation controller updates the navigation bar each time the top view controller changes. Thus, these changes occur each time a view controller is pushed onto the stack or popped from it. When you animate a push or pop operation, the navigation controller similarly animates the change in navigation bar content.

Displaying a Toolbar

In iPhone OS 3.0 and later, navigation controller objects make it easy to provide a custom toolbar for each screen of a navigation interface. The navigation controller object now manages an optional toolbar in its view hierarchy. When displayed, this toolbar obtains its current set of items from the toolbarItems property of the active view controller. When the active view controller changes, the navigation controller updates the toolbar items to match the new view controller, animating the new items into position when appropriate.

The navigation toolbar is hidden by default but you can show it for your navigation interface by calling the setToolbarHidden:animated: method of your navigation controller object. If not all of your view controllers support toolbar items, your delegate object can call this method to toggle the visibility of the toolbar during subsequent push and pop operations.