UINavigationBar Class Reference

Overview

The UINavigationBar class implements a control for navigating hierarchical content. It’s a bar, typically displayed at the top of the screen, containing buttons for navigating up and down a hierarchy. The primary properties are a left (back) button, a center title, and an optional right button. You can specify custom views for each of these.

You can use a navigation bar as a standalone object or in conjunction with a navigation controller object. To use a navigation bar as a standalone object, you create it and add it to your view hierarchy like you would any other view. Specifically, you can create it in Interface Builder and load it with the rest of your views or you can create it programmatically using the standard alloc and initWithFrame: methods.

You can modify the appearance of the bar using the barStyle, tintColor, and translucent properties. These properties affect the visual appearance of the bar itself but they also affect the way buttons are displayed in the bar. For example, if you set the translucent property to YES, any buttons in the bar are also made partially opaque.

For information about using a navigation bar with a navigation controller object, see “Using With a Navigation Controller.”

Adding Content to a Navigation Bar

When you use a navigation bar as a standalone object, you are responsible for providing its contents. Unlike other types of views, you do not add subviews to a navigation bar directly. Instead, you use a navigation item (an instance of the UINavigationItem class) to specify what buttons or custom views you want displayed. A navigation item has properties for specifying views on the left, right, and center of the navigation bar and for specifying a custom prompt string.

A navigation bar manages a stack of UINavigationItem objects. Although the stack is there mostly to support navigation controllers, you can use it as well to implement your own custom navigation interface. The topmost item in the stack represents the navigation item whose contents are currently displayed by the navigation bar. You push new navigation items onto the stack using the pushNavigationItem:animated: method and pop items off the stack using the popNavigationItemAnimated: method. Both of these changes can be animated for the benefit of the user.

In addition to pushing and popping items, you can also set the contents of the stack directly using either the items property or the setItems:animated: method. You might use these methods at launch time to restore your interface to its previous state or to push or pop more than one navigation item at a time.

If you are using a navigation bar as a standalone object, you should assign a custom delegate object to the delegate property and use that object to intercept messages coming from the navigation bar. Delegate objects must conform to the UINavigationBarDelegate protocol. The delegate notifications let you know when the contents of responsible for deciding when items are pushed or popped from the stack—for example, it should display the previous view when the user clicks the back button.

For more information about creating navigation items, see UINavigationItem Class Reference. For more information about implementing a delegate object, see UINavigationBarDelegate Protocol Reference.

Using With a Navigation Controller

The most common way to use a navigation bar is in conjunction with a UINavigationController object. If you use a navigation controller to manage the navigation between different screens of content, the navigation controller creates the navigation bar automatically and pushes and pops navigation items when appropriate. You do not have to create the navigation bar and you do not have to manage the pushing and popping of navigation items yourself.

When used in conjunction with a navigation controller, there are only a handful of direct customizations you can make to the navigation bar. Specifically, it is alright to modify the barStyle, tintColor, and translucent properties of this class, but you must never directly change UIView-level properties such as the frame, bounds, alpha, or hidden properties directly. In addition, you should let the navigation controller manage the stack of navigation items and not attempt to modify these items yourself.

A navigation controller automatically assigns itself as the delegate of its navigation bar object. Therefore, when using a navigation controller, you must not attempt to assign a custom delegate object to the corresponding navigation bar.