UINavigation

UINavigationBar and UINavigationController

Key Skills & Concepts

• Understanding a UINavigationBar,UINavigationController,and a UINavigationItem
• Understanding how to use a navigation bar in a simple application
• Understanding how to programmatically manipulate a navigation bar’s items
• Adding a navigation bar to a tab in a tabbed application

  Anavigation bar is displayed along a window’s top, just below the status bar. The navigation bar optionally contains a title for each view displayed and one or more buttons. Typically, the button on the bar’s right, when clicked, takes the user to the next step in another view, although sometimes applications use the right button as a ―done‖ button. The button on the bar’s left is a Back button, returning to the previous view. Navigation bars are often used with tables, where a table is displayed with a navigation bar above it. When a user clicks a table’s rows, the navigation bar’s associated navigation controller takes the user to more detailed information about the selected item. For instance, the App Store application allows a user to refine his or her categories until the application of interest is found (Figure 9-1). For instance, if a user clicked Games, the navigation controller would take the user to a Games subcategory. If the user then clicked All Games, the navigation controller would take the user to a table of all games in the App Store. If a user wished to go back a step, he or she would press the button on the navigation bar’s upper-left area. This button is the Back button. Note the navigation controller labeled the button’s title with the previous view’s title. The navigation bar and navigation controller are useful for applications requiring hierarchical navigation, such as data drill-down. In the App Store application, you drill down to increasingly specific categories until reaching a list of items rather than further subcategories. When you select an item, it takes you to a more detailed view of your selection. Navigation bars are also useful for applications with multiple steps in a single task. In this chapter, you learn how to use a navigation bar and its associated classes. In the first task, you start with a Window-based application and manually create an application consisting of three views managed by a navigation controller. In the second task, you duplicate the Utility Application template. Although this template uses a navigation bar, the template is odd, compared to other Apple-provided templates. Rather than using Interface Builder, this template does almost everything using code. Moreover, this template uses a navigation bar without using an associated navigation controller. After finishing duplicating the Utility Application template, the chapter presents a navigation controller embedded in a tab bar’s tab. This is perhaps this chapter’s most useful task and should not be skipped. You will find embedding a navigation controller in a tab a ubiquitous requirement when developing iPhone applications.       Figure 9-1 Using the App Store application  

UINavigationBar, UINavigationController and UINavigationItem

Below the status bar but above the application window’s content, many applications have a navigation bar. Navigation bars display the current view’s title and contain one or more buttons for navigating to other screens. In this chapter’s introduction, you viewed the App Store application, a typical use for a navigation bar. The Notes application also uses a navigation bar (Figure 9-2). The navigation bar appears above the yellow notepad. Upon clicking the + key, the navigation bar displays a new note page. The navigation bar’s title is New Note and contains a back button labeled ―Notes‖ and a right button labeled ―Done.‖ Upon tapping either button, the application returns the user to the application’s primary page.You add navigation bars to an application using the UINavigationBar class. You almost never use a UINavigationBar class directly, instead using UINavigationBar’s controller, UINavigationController. You control a UINavigationBar using a UINavigation Controller. A UINavigationController uses a stack data structure to manage one or more view controllers. The first view controller, or the root view controller, is the first item on the stack. To navigate to other views, you push the view’s view controller onto the stack. To return to the previous view, you pop the current view from the stack.     Figure 9-2 The Notes App uses a navigation bar.  

Building a Three-View Application Using a Navigation Bar

It is easiest to learn the UINavigationController by example. In this task, you create a simple application containing three views. You navigate between the three views using a navigation bar. The first view has a button on the navigation bar’s right, which says ―Next.‖ Upon clicking the button, the application takes you to the next view. This view has a Back button and a button in the view rather than on the navigation bar. Upon clicking the button in the view, the application takes you to a third view. The third view has a navigation bar and a title.  

1. Create a new Window-based Name the application ThreeViewNavCont.
2. Create three UIViewController classes, naming them FirstViewController, SecondViewController, and Be certain to also generate xib files for each class.
3. Open each of the xibs and change the view’s color to a unique
4. Save and exit Interface
5. Open xib and drag a navigation controller from the library to the Document window (Figure 9-3). Notice Interface Builder shows the navigation controller’s canvas with a navigation bar and a view.
6. Select the navigation controller’s view controller. You can do this through the document window, by clicking the disclosure arrow next to navigation controller and then selecting the view controller. Alternatively, you can select the view directly in the navigation controller’s canvas. Change the controller’s class to FirstViewController in the Inspector. Also change its NIB name to FirstViewController in the Inspector (Figure 9-4).

                                                                               Figure 9-3 Adding a navigation controller to MainWindow.xib       Figure 9-4 Changing the view controller to FirstViewController

1. Save and exit Interface builder.
2. Open ThreeViewNavContAppDelegate.h in Xcode. Add a UINavigationControllerIBOutlet declaration to the header file (Listing 9-1).

Listing 9-1 ThreeViewNavContAppDelegate.h #import<UIKit/UIKit.h> @interface ThreeViewNavContAppDelegate : NSObject<UIApplicationDelegate> { IBOutlet UIWindow *window; IBOutlet UINavigationController * navController; } @property (nonatomic, retain) IBOutlet UIWindow *window; @property (nonatomic, retain) IBOutlet UINavigationController * navController; @end  

9. Add the UINavigationController to m and add the UINavigationController’s view to the window (Listing 9-2). Save and build.

Listing 9-2 ThreeViewNavContAppDelegate.m #import "ThreeViewNavContAppDelegate.h" @implementation ThreeViewNavContAppDelegate @synthesize window; @synthesize navController;(void)applicationDidFinishLaunching:(UIApplication *)application { [window addSubview: view]; [window makeKeyAndVisible]; } (void)dealloc { [window release]; [navController release]; [super dealloc]; } @end    

1. Open xib in Interface Builder. Right-click ThreeViewNavContApp Delegate in the document window and connect the navController outlet to the UINavigationController in the document window (Figure 9-5).
2. Save and exit Interface
3. Click Build And Go to run the application, and FirstViewController’s view should appear (Figure 9-6).

                                                                                             Figure 9-5 Connecting the navigation controller       Figure 9-6 The application running in iPhone Simulato   The first step to using a navigation bar is to add a navigation controller to a document window. Upon adding the navigation controller, Interface Builder also adds a root view controller and you changed this view controller to your view controller. Making this connection in Interface Builder allows the nib to manage the property’s life cycle. When you build and run the application, the application knows MainWindow.xib is the application’s main nib and loads it. Upon loading, the nib initializes the objects it manages, which includes the navigation controller property, navController. The navigation controller loads its root view controller. Because the root view controller has an associated navigation item, the navigation controller adds a navigation bar above the view with the navigation item’s title. Because MainWindow.xib handles all the application’s initialization, all you do in the applicationDidFinishLaunching method is add the view to the window. After adding the navigation controller, you must provide navigation controls so a user can move from view to view. You can either add a button to the navigation bar itself or add a control to a view’s canvas. The next few steps do both.

1. Open xib and select the navigation item in the document window (Figure 9- 7). Change the navigation item’s title to First View.
2. Drag a bar button item from the library to the navigation bar (Figure 9-8). Rename the button ―Ne‖
3. Save and exit Interface
4. Open h and add a new action called moveToNextView (Listing 9-3). Import SecondViewController and add SecondViewController as a property.

  Figure 9-7 Selecting the navigation item in the Document window     Figure 9-8 Adding a button to FirstViewController’s navigation bar Listing   9-3 FirstViewController.h #import<UIKit/UIKit.h> #import "SecondViewController.h" @interface FirstViewController : UIViewController { SecondViewController * second; } @property (nonatomic, retain) SecondViewController * second; - (IBAction) moveToNextView: (id) sender; @end

7. Open m and implement moveToNextView, as in Listing 9-4. Listing 9-4 FirstViewController.m

#import "FirstViewController.h" @implementation FirstViewController @synthesize second; - (IBAction) moveToNextView: (id) sender{ self.second = [[[SecondViewController alloc]  initWithNibName:@"SecondViewController" bundle:nil] autorelease]; [self.navigationController pushViewController:self.second animated: YES]; } -(void)dealloc { [second release]; [super dealloc]; } @end

1. Build the application.
2. Open xib in Interface Builder, select the FirstViewController, and connect its moveToNextView action to the Next button (Figure 9-9).
3. Save and exit Interface
4. Click Build And Go to run the Tapping the Next button results in the second view being displayed (Figure 9-10). Tap First View, and the application returns to the first view.

  Figure 9-9 Connecting moveToNextView action to the navigation button     Figure 9-10 The application running in iPhone Simulator   In step 13, you changed the default title to your view’s title. Actually, to be specific, you changed the default title to your view controller’s navigation item’s title. In step 14, you added a bar button item to the navigation bar and set it as the navigation bar item’s rightBarButtonItem. Establishing this connection ensures the application displays the button on the bar’s right. You then created an action that, when clicked, pushes the second view controller onto the navigation controller’s stack. The navigation controller displays this view and a navigation bar containing the new view’s navigation bar element. Notice you must push view controllers onto the stack manually through code, as in Listing 9-4. [self.navigationController pushViewController:self.second animated: YES]; If a view controller is in a navigation controller’s stack, then the navigationController property automatically refers to the navigation controller managing the stack. So, the navigation controller in ThreeViewNavContAppDelegate pushes FirstViewController’s SecondViewController onto the stack. Note that setting the animated parameter to YES causes the view to slide in from the left.As the task illustrates, creating an application using a navigation controller and associated navigation bar is not difficult. The Back button, and popping a view controller from the navigation controller, is implemented for you. You provide the control and action to push view controllers onto the navigation controller’s stack.  

Adding Another View

You are not limited to bar buttons if you wish to push views onto a navigation controller’s stack. In the following steps, you first add a bar button item to SecondViewController. You then add an additional button to SecondViewController’s view, but instead of it being a bar button, you use a regular button.

1. Open the ThreeViewNavCont project in Xcode.
2. Open SecondViewController and add an IBOutlet for a UIBarButtonItem to SecondViewController as a Name the property navBut; don’t forget to synthesize the property.
3. Open m and implement the viewDidLoad method to set the navigationItem’s right bar button item to navBut. Note that every UIViewController has a navigationItem and that it is a read-only property.
4. Open xib in Interface Builder and add a new bar button item to the document window (Figure 9-11). Connect the newly added bar button item to the navBut outlet.
5. Save and exit Interface
6. Build and run the application, and the second view now displays its title in the navigation bar (Figure 9-12). But notice, clicking the Next button in the navigation bar has no effect because you haven’t connected it to a method

  Figure 9-11 Adding a UIBarButtonItem     Figure 9-12 The application displaying the second view controller’s navigation item’s title    

1. Open h and add a new action called moveToNextView (Listing 9- 5). Import ThirdViewController and ThreeViewNavContAppDelegate. Add a ThirdViewController as a property.
2. Open m and implement moveToNextView, as in Listing 9-6. Save and build.
3. Open xib in Interface Builder. Connect the bar button’s selector to the File’s Owner moveToNextView action (Figure 9-13).
4. Save and exit Interface
5. Build and run the application. The second view now has a Next button and tapping it moves to the next view (Figure 9-14). Now consider pushing a view onto the stack using a regular button.

  Figure 9-13 Connecting the bar button to the moveToNextView action         Figure 9-14 The second view with a Next button                              Figure 9-15 Connecting button to moveToNextView method    

1. Open xib and add a button to the view. Connect the button to moveToNextView (Figure 9-15). Connect to the button’s Touch Up Inside action.
2. Save and exit Interface
3. Build and run the Click the button on the second view, and it, too, navigates to the third view.

  Using a button rather than a bar button item is that easy. Typically, though, in most iPhone applications, you will see a table in the view rather than a button (see Figure 9-1). For instance, SecondViewController might have an embedded table listing categories. Upon clicking a table row, you would invoke the moveToNextView method, passing the specific table row’s identifier as a parameter. The App Store application is an example of this type of navigation (see Figure 9-1).   Listing 9-5 SecondViewController.h #import<UIKit/UIKit.h> #import "ThirdViewController.h" @interface SecondViewController : UIViewController { ThirdViewController * third; IBOutlet UIBarButtonItem * navBut; } @property (nonatomic, retain) IBOutlet UIBarButtonItem * navBut; @property (nonatomic, retain) ThirdViewController * third; -(IBAction) moveToNextView: (id) sender; @end Listing 9-6 SecondViewController.m #import "SecondViewController.h" @implementation SecondViewController @synthesize third; @synthesize navBut;(void) viewDidLoad{ navigationItem.title = @"SecondView"; self.navigationItem.rightBarButtonItem = navBut; }(IBAction) moveToNextView: (id) sender{ third = [[[ThirdViewController alloc] initWithNibName:@"ThirdViewController" bundle:nil] autorelease]; [self.navigationController pushViewController: self.third animated: YES]; }(void)dealloc { [third release]; [super dealloc]; } @end More on the UINavigationController You are not limited to pushing items onto a stack. You can also pop items off the stack. You can also modify the navigation bar, hiding elements, adding new ones, and making other modifications.

Pushing and Popping

You pop view controllers from a stack using the method popViewControllerAnimated:. This method pops the top view controller off the navigation controller’s stack and updates the displayed view to the stack’s next view controller’s view. (UIViewController *) popViewControllerAnimated: (BOOL) animated   The method takes one parameter, which indicates if the transition should be animated. The method also returns the popped view controller, should you wish to retain it for future use. Other methods you might use include popToRootViewControllerAnimated: and popToViewController:animated:. Refer to Apple’s online reference, ―UINavigationController Class Reference,‖ for more information.

Configuring the Navigation Bar

In the previous example, you hid the navigation bar by calling the navigation controller’s setNavigationBarHidden: method. - (void)setNavigationBarHidden:(BOOL)hidden animated:(BOOL)animated This method hides or displays the navigation bar, depending upon if you passed YES or NO as the initial parameter. You also specify if the navigation bar should slide in from the top by specifying YES for the animated parameter.You might also change a navigation bar’s style by changing its style property. You can use code to change the navigation bar’s style, but the easiest way to do this is through Interface Builder. You can also change a navigation bar’s color. You change the color using the tintColor property.

Using a Navigation Controller in a Tab

Applications usually use a navigation bar with other navigation views, such as a tab bar or table view. You haven’t learned about table views yet—you won’t learn about using a table view with a navigation bar until Chapter 10. However, you learned about the tab bar in Chapter 8. A navigation bar might be placed within a tab bar. For instance, returning to the App Store application, notice the navigation screens are steps within the Categories tab (see Figure 9-1). The Featured, Categories, Top 25, and Updates tabs are different views on the same data. The Search tab is a subtask. Within the Categories tab, there is a navigation bar combined with a table view. This combination provides a way to drill down hierarchically to a specific application.Although you don’t learn about tables until Chapter 10, consider a navigation bar in a tab.

1. Create a new Window-based Name the application NavInTab.
2. Create two new UIViewController Name the first FirstTabViewController and the second StepTwoViewController; be certain to create nibs for both.
3. Open both newly created nibs and change the background color for each
4. Open xib and add a UITabBarController to the document.
5. Delete the first tab bar view Drag a navigation controller to the document and drop it so it is the first item below the tab bar (Figure 9-19).
6. Change the navigation controller’s root view controller to FirstTabViewController by changing its class and nib name in the The canvas should indicate the view is from FirstTabViewController.nib (Figure 9-20).
7. Change the navigation item’s title from ―Root View Controller‖ to ―step ‖
8. Drag a bar button item from the library to the navigation item in the Document window (Figure 9-21). Change the button’s title to ―Next.‖ The button should automatically be set as the navigation item’s If not, connect the navigation item’s rightBarButton outlet to the newly added bar button item.
9. Save and exit Interface

                       Figure 9-19 Adding a navigation controller.                                                                                                                                              Figure 9-20 Canvas indicates view is from a different nib.                                                                                                  Figure 9-21 Bar button added to document window    

1. Open h and NavInTabAppDelate.m and adopt the UITabBarController Delegate protocol. Also add a UITabBarController property and a UINavigationController property. Modify applicationDidFinishLaunching so it loads the tabBarController property’s root view. The files should match Listings 9-11 and 9-12. Save and build.

  Listing 9-11 NavInTabAppDelegate.h #import<UIKit/UIKit.h> @interface NavInTabAppDelegate : NSObject<UIApplicationDelegate, UITabBarControllerDelegate> { UIWindow *window; UITabBarController *tabBarController; UINavigationController *navBarController; } @property (nonatomic, retain) IBOutlet UIWindow *window; @property (nonatomic, retain) IBOutlet UITabBarController *tabBarController; @property (nonatomic, retain) IBOutlet UINavigationController * navBarController; @end Listing 9-12 NavInTabAppDelegate.m #import "NavInTabAppDelegate.h" @implementation NavInTabAppDelegate @synthesize window; @synthesize tabBarController; @synthesize navBarController;(void)applicationDidFinishLaunching:(UIApplication *)application { [window addSubview:tabBarController.view]; [window makeKeyAndVisible]; }(void)dealloc { [window release]; [tabBarController release]; [navBarController release]; [super dealloc]; }@end

1. Open xib in Interface Builder and connect the NavInTabAppDelegate’s navBarController to the newly added navigation controller (Figure 9-22). Connect the tabBarController to the newly added tab bar controller.
2. Save and exit Interface
3. Open h and implement the viewDidLoad method so that it sets the navigationItem’s title to ―step two‖ (Listing 9-13).

  Figure 9-22 Connecting the navBarController       Figure 9-23 The finished application in iPhone Simulator