UINavigationBar

Important

This is a preliminary document for an API or technology in development. Apple is supplying this information to help you plan for the adoption of the technologies and programming interfaces described herein for use on Apple-branded products. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation. Newer versions of this document may be provided with future betas of the API or technology.

The UINavigationBar class provides a control for navigating hierarchical content. It’s a bar, typically displayed at the top of the screen, containing buttons for navigating within a hierarchy of screens. The primary properties are a left (back) button, a center title, and an optional right button. You can use a navigation bar as a standalone object or in conjunction with a navigation controller object.
More...

Using a Navigation Bar 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.

A navigation controller automatically assigns itself as the delegate of its navigation bar object. Therefore, when using a navigation controller, don’t assign a custom delegate object to the corresponding navigation bar.

Customizing the Appearance of a Navigation Bar

In iOS 5.0 and later, you can customize the appearance of the bar using the methods listed in Customizing the Bar Appearance. You can customize the appearance of all navigation bars using the appearance proxy ([UINavigationBar appearance]), or just of a single bar.

In iOS 7, a navigation bar’s tintColor affects the color of the back indicator image, button titles, and button images. The barTintColor property affects the color of the bar itself. Additionally, navigation bars are translucent by default. Turning the translucency off or on does not affect buttons, since they do not have backgrounds.

In general, when a property is dependent on the bar metrics (on the iPhone in landscape orientation, bars have a different height from standard), be sure to specify a value for UIBarMetricsDefault as well as for other metrics.

Discussion

If the navigation bar was created by a navigation controller and is being managed by that object, you must not change the value of this property. Navigation controllers act as the delegate for any navigation bars they create.

Declaration

Parameters

item

The navigation item to push on the stack.

animated

YEStrue if the navigation bar should be animated; otherwise, NOfalse.

Discussion

Pushing a navigation item displays the item’s title in the center on the navigation bar. The previous top navigation item (if it exists) is displayed as a back button on the left side of the navigation bar. If the new top item has a left custom view, it is displayed instead of the back button.

Declaration

Parameters

items

The UINavigationItem objects to place in the stack. The front-to-back order of the items in this array represents the new bottom-to-top order of the items in the navigation stack. Thus, the last item added to the array becomes the top item of the navigation stack.

animated

If YEStrue, animate the pushing or popping of the top stack item. If NOfalse, replace the stack items without any animations.

Discussion

You can use this method to update or replace the navigation items in the stack without pushing or popping each item explicitly. In addition, this method lets you update the stack without animating the changes, which might be appropriate at launch time when you want to restore the state of the navigation stack to some previous state.

If animations are enabled, this method decides which type of transition to perform based on whether the last item in the items array is already on the current navigation stack. If the item is currently on the stack, but is not the topmost item, this method uses a pop transition; if it is the topmost item, no transition is performed. If the item is not on the stack, this method uses a push transition. Only one transition is performed, but when that transition finishes, the entire contents of the stack are replaced with the new items. For example, if items A, B, and C are on the stack and you set items D, A, and B, this method uses a pop transition and the resulting stack contains the items D, A, and B.

Declaration

Discussion

The default value is nil, which corresponds to the default shadow image. When non-nil, this property represents a custom shadow image to show instead of the default. For a custom shadow image to be shown, a custom background image must also be set with the setBackgroundImage:forBarMetrics: method. If the default background image is used, then the default shadow image will be used regardless of the value of this property.

Import Statement

Availability

A Boolean value indicating whether the navigation bar is translucent (YEStrue) or not (NOfalse).

Declaration

Swift

var translucent: Bool

Objective-C

@property(nonatomic,assign,getter=isTranslucent)BOOLtranslucent

Discussion

The default value is YEStrue. If the navigation bar has a custom background image, the default is YEStrue if any pixel of the image has an alpha value of less than 1.0, and NOfalse otherwise.

If you set this property to YEStrue on a navigation bar with an opaque custom background image, the navigation bar will apply a system opacity less than 1.0 to the image.

If you set this property to NOfalse on a navigation bar with a translucent custom background image, the navigation bar provides an opaque background for the image using black if the navigation bar has UIBarStyleBlack style, white if the navigation bar has UIBarStyleDefault, or the navigation bar’s barTintColor if a custom value is defined.

Declaration

Discussion

You can specify the font, text color, text shadow color, and text shadow offset for the title in the text attributes dictionary, using the text attribute keys described in NSString UIKit Additions Reference.