UINavigationItem Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
View Controller Catalog for iOS
Declared in
UINavigationBar.h
Related sample code

Overview

The UINavigationItem class encapsulates information about a navigation item pushed on a UINavigationBar object’s stack. A navigation bar is a control used to navigate hierarchical content. A UINavigationItem specifies what is displayed on the navigation bar when it is the top item and also how it is represented when it is the back item.

Use the initWithTitle: method to create a navigation item specifying the item’s title. The item cannot be represented on the navigation bar without a title. Use the backBarButtonItem property if you want to use a different title when this item is the back item. The backBarButtonItem property is displayed as the back button unless a custom left view is specified.

The navigation bar displays a back button on the left and the title in the center by default. You can change this behavior by specifying custom left, center, or right views. Use the setLeftBarButtonItems:animated: and setRightBarButtonItems:animated: methods to change the left and right views; you can specify that the change be animated. Use the titleView method to change the center view to a custom view.

These custom views can be system buttons. Use the UIBarButtonItem class to create custom views to add to navigation items.

For information about how navigation items work together with a navigation controller, custom view controllers, and the navigation bar to display their content, see View Controller Programming Guide for iOS.

Tasks

Initializing an Item

Getting and Setting Properties

Customizing Views

Properties

backBarButtonItem

The bar button item to use when a back button is needed on the navigation bar.

@property(nonatomic, retain) UIBarButtonItem *backBarButtonItem
Discussion

When this navigation item is immediately below the top item in the stack, the navigation controller derives the back button for the navigation bar from this navigation item. When this property is nil, the navigation item uses the value in its title property to create an appropriate back button. If you want to specify a custom image or title for the back button, you can assign a custom bar button item (with your custom title or image) to this property instead. When configuring your bar button item, do not assign a custom view to it; the navigation item ignores custom views in the back bar button anyway.

The default value of this property is nil.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UINavigationBar.h

hidesBackButton

A Boolean value that determines whether the back button is hidden.

@property(nonatomic, assign) BOOL hidesBackButton
Discussion

When set to YES, the back button is hidden when this navigation item is the top item. This is true regardless of the value in the leftItemsSupplementBackButton property. When set to NO, the back button is shown if it is still present. (It can be replaced by values in either the leftBarButtonItem or leftBarButtonItems properties.) The default value is NO.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UINavigationBar.h

leftBarButtonItem

A custom bar button item displayed on the left of the navigation bar when the receiver is the top navigation item.

@property(nonatomic, retain) UIBarButtonItem *leftBarButtonItem
Discussion

In iOS 5.0 and later, the contents of this property always refer to the first bar button item in the leftBarButtonItems array. Assigning a new value to this property replaces the first item in the leftBarButtonItems array with the new value. Setting this property to nil removes the first item in the array. If the bar button item is already in the array, it is moved from its current location to the front of the array.

Prior to iOS 5.0, this property contained the single bar item to display on the left side of the navigation bar instead of the back button.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UINavigationBar.h

leftBarButtonItems

An array of custom bar button items to display on the left side of the navigation bar when the receiver is the top navigation item.

@property(nonatomic, copy) NSArray *leftBarButtonItems
Discussion

This array can contain 0 or more bar items to display on the left side of the navigation bar. Items can include fixed-width and flexible-width spaces. If the leftItemsSupplementBackButton property is YES, the items are displayed to the right of the back button, otherwise the items replace the back button and start at the left edge of the bar. Items are displayed left-to-right in the same order as they appear in the array.

If there is not enough room to display all of the items in the array, those that would overlap the title view (if present) or the buttons on the right side of the bar are not displayed.

The first item in the array can also be set using the leftBarButtonItem property.

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h

leftItemsSupplementBackButton

A Boolean value indicating whether the left items are displayed in addition to the back button.

@property BOOL leftItemsSupplementBackButton
Discussion

Normally, the presence of custom left bar button items causes the back button to be removed in favor of the custom items. Setting this property to YES causes the items in the leftBarButtonItems or leftBarButtonItem property to be displayed to the right of the back button—that is, they are displayed in addition to, and not instead of, the back button. When set to NO, the items in those properties are displayed instead of the back button. The default value of this property is NO.

The value in the hidesBackButton property still determines whether the back button is actually displayed.

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h

prompt

A single line of text displayed at the top of the navigation bar.

@property(nonatomic, copy) NSString *prompt
Discussion

The default value is nil.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UINavigationBar.h

rightBarButtonItem

A custom bar button item displayed on the right of the navigation bar when the receiver is the top navigation item.

@property(nonatomic, retain) UIBarButtonItem *rightBarButtonItem
Discussion

In iOS 5.0 and later, the contents of this property always refer to the first bar button item in the rightBarButtonItems array. Assigning a new value to this property replaces the first item in the rightBarButtonItems array with the new value. Setting this property to nil removes the first item in the array. If the bar button item is already in the array, it is moved from its current location to the front of the array.

Prior to iOS 5.0, this property contained the single bar item to display on the right side of the navigation bar.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UINavigationBar.h

rightBarButtonItems

An array of custom bar button items to display on the right side of the navigation bar when the receiver is the top navigation item.

@property(nonatomic, copy) NSArray *rightBarButtonItems
Discussion

This array can contain 0 or more bar button items to display on the right side of the navigation bar. Items are displayed right-to-left in the same order as they appear in the array. Thus, the first item in the array is the rightmost item and other items are added to the left of the previous item.

If there is not enough room to display all of the items in the array, those that would overlap the title view (if present) or the buttons on the left side of the bar are not displayed.

The first item in the array can also be set using the rightBarButtonItem property.

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h

title

The navigation item’s title displayed in the center of the navigation bar.

@property(nonatomic, copy) NSString *title
Discussion

The default value is nil.

When the receiver is on the navigation item stack and is second from the top—in other words, its view controller manages the views that the user would navigate back to—the value in this property is used for the back button on the top-most navigation bar. If the value of this property is nil, the system uses the string “Back” as the text of the back button.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UINavigationBar.h

titleView

A custom view displayed in the center of the navigation bar when the receiver is the top item.

@property(nonatomic, retain) UIView *titleView
Discussion

If this property value is nil, the navigation item’s title is displayed in the center of the navigation bar when the receiver is the top item. If you set this property to a custom title, it is displayed instead of the title. This property is ignored if leftBarButtonItem is not nil.

Custom views can contain buttons. Use the buttonWithType: method in UIButton class to add buttons to your custom view in the style of the navigation bar. Custom title views are centered on the navigation bar and may be resized to fit.

The default value is nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
UINavigationBar.h

Instance Methods

initWithTitle:

Returns a navigation item initialized with the specified title.

- (id)initWithTitle:(NSString *)title
Parameters
title

The string to set as the navigation item’s title displayed in the center of the navigation bar.

Return Value

A new UINavigationItem object initialized with the specified title.

Discussion

This is the designated initializer for this class.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UINavigationBar.h

setHidesBackButton:animated:

Sets whether the back button is hidden, optionally animating the transition.

- (void)setHidesBackButton:(BOOL)hidesBackButton animated:(BOOL)animated
Parameters
hidesBackButton

Specify YES if the back button should be hidden when this navigation item is the top item. Specify NO if the back button should be visible, assuming it has not been replaced by a custom item.

animated

YES to animate the transition; otherwise, NO.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UINavigationBar.h

setLeftBarButtonItem:animated:

Sets the custom bar button item, optionally animating the transition to the new item.

- (void)setLeftBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated
Parameters
item

A custom bar item to display on the left side of the navigation bar.

animated

Specify YES to animate the transition to the custom bar item when this item is the top item. Specify NO to set the item immediately without animating the change.

Discussion

If two navigation items have the same custom left or right bar button items, those bar button items remain stationary during the transition when the navigation item is pushed or popped.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UINavigationBar.h

setLeftBarButtonItems:animated:

Sets the left bar button items, optionally animating the transition to the new items.

- (void)setLeftBarButtonItems:(NSArray *)items animated:(BOOL)animated
Parameters
items

An array of custom bar button items to display on the left side of the navigation bar.

animated

Specify YES to animate the transition to the custom bar items when this item is the top item. Specify NO to set the items immediately without animating the change.

Discussion

If two navigation items have the same custom left or right bar button items, those bar button items remain stationary during the transition when the navigation item is pushed or popped.

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h

setRightBarButtonItem:animated:

Sets the custom bar button item, optionally animating the transition to the view.

- (void)setRightBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated
Parameters
item

A custom bar item to display on the right of the navigation bar.

animated

Specify YES to animate the transition to the custom bar item when this item is the top item. Specify NO to set the item immediately without animating the change.

Discussion

If two navigation items have the same custom left or right bar button items, those bar button items remain stationary during the transition when the navigation item is pushed or popped.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UINavigationBar.h

setRightBarButtonItems:animated:

Sets the right bar button items, optionally animating the transition to the new items.

- (void)setRightBarButtonItems:(NSArray *)items animated:(BOOL)animated
Parameters
items

An array of custom bar button items to display on the right side of the navigation bar.

animated

Specify YES to animate the transition to the custom bar items when this item is the top item. Specify NO to set the items immediately without animating the change.

Discussion

If two navigation items have the same custom left or right bar button items, those bar button items remain stationary during the transition when the navigation item is pushed or popped.

Availability
  • Available in iOS 5.0 and later.
Declared In
UINavigationBar.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)

Did this document help you? Yes It's good, but... Not helpful...