UITabBarController Class Reference

Overview

The UITabBarController class implements a specialized view controller that manages a radio-style selection interface. This tab bar interfacedisplays tabs at the bottom of the window for selecting between the different modes and for displaying the views for that mode. This class is generally used as-is but may be subclassed in iOS 6 and later.

Each tab of a tab bar controller interface is associated with a custom view controller. When the user selects a specific tab, the tab bar controller displays the root view of the corresponding view controller, replacing any previous views. (User taps always display the root view of the tab, regardless of which tab was previously selected. This is true even if the tab was already selected.) Because selecting a tab replaces the contents of the interface, the type of interface managed in each tab need not be similar in any way. In fact, tab bar interfaces are commonly used either to present different types of information or to present the same information using a completely different style of interface. Figure 1 shows the tab bar interface presented by the Clock application, each tab of which presents a type of time based information.

Figure 1  The tab bar interface in the Clock application

You should never access the tab bar view of a tab bar controller directly. To configure the tabs of a tab bar controller, you assign the view controllers that provide the root view for each tab to the viewControllers property. The order in which you specify the view controllers determines the order in which they appear in the tab bar. When setting this property, you should also assign a value to the selectedViewController property to indicate which view controller is selected initially. (You can also select view controllers by array index using the selectedIndex property.) When you embed the tab bar controller’s view (obtained using the inherited view property) in your application window, the tab bar controller automatically selects that view controller and displays its contents, resizing them as needed to fit the tab bar interface.

Tab bar items are configured through their corresponding view controller. To associate a tab bar item with a view controller, create a new instance of the UITabBarItem class, configure it appropriately for the view controller, and assign it to the view controller’s tabBarItem property. If you do not provide a custom tab bar item for your view controller, the view controller creates a default item containing no image and the text from the view controller’s title property.

As the user interacts with a tab bar interface, the tab bar controller object sends notifications about the interactions to its delegate. The delegate can be any object you specify but must conform to the UITabBarControllerDelegate protocol. You can use the delegate to prevent specific tab bar items from being selected and to perform additional tasks when tabs are selected. You can also use the delegate to monitor changes to the tab bar that are made by the More navigation controller, which is described in more detail in “The More Navigation Controller.”

For more information about using tab bar controllers to build your user interface, see View Controller Programming Guide for iOS.

The Views of a Tab Bar Controller

Because the UITabBarController class inherits from the UIViewController class, tab bar controllers have their own view that is accessible through the view property. When deploying a tab bar interface, you must install this view as the root of your window. Unlike other view controllers, a tab bar interface should never be installed as a child of another view controller.

The view for a tab bar controller is just a container for a tab bar view and the view containing your custom content. The tab bar view provides the selection controls for the user and consists of one or more tab bar items. Figure 2 shows how these views are assembled to present the overall tab bar interface. Although the items in the tab bar and toolbar views can change, the views that manage them do not. Only the custom content view changes to reflect the view controller for the currently selected tab.

Figure 2  The primary views of a tab bar controller

You can use navigation controllers or custom view controllers as the root view controller for a tab. If the root view controller is a navigation controller, the tab bar controller makes further adjustments to the size of the displayed navigation content so that it does not overlap the tab bar. Any views you display in a tab bar interface should therefore have their autoresizingMask property set to resize the view appropriately under any conditions.

The More Navigation Controller

The tab bar has limited space for displaying your custom items. If you add six or more custom view controllers to a tab bar controller, the tab bar controller displays only the first four items plus the standard More item on the tab bar. Tapping the More item brings up a standard interface for selecting the remaining items.

The interface for the standard More item includes an Edit button that allows the user to reconfigure the tab bar. By default, the user is allowed to rearrange all items on the tab bar. If you do not want the user to modify some items, though, you can remove the appropriate view controllers from the array in the customizableViewControllers property.

State Preservation

In iOS 6 and later, if you assign a value to this view controller’s restorationIdentifier property, it preserves a reference to the view controller in the selected tab. At restore time, it uses the reference to select the tab with the same view controller.

Although the tab bar controller causes its child view controllers to be added to the preservation state, it does not restore those children to its tabs. Your code is responsible for storing the information needed to restore each view controller to the appropriate tab.

When preserving a tab bar controller, it is recommended (but not required) that you also assign restoration identifiers to the view controllers in each tab. Omitting a restoration identifier from a child view controller would simply result in that tab always returning to its default configuration. The child view controllers may use the same restoration identifiers. The tab bar controller automatically stores additional information to ensure that each child’s restoration path is unique.

Although the tab bar controller saves its tabs in the same order that they are listed in the viewControllers property, the save order is actually irrelevant. Your code is responsible for providing the new tab bar controller during the next launch cycle, so your code can adjust the order of the tabs as needed. The state preservation system restores the contents of each tab based on the assigned restoration identifier, not based on the position of the tab.

For more information about how state preservation and restoration works, see iOS App Programming Guide.

Tasks

Accessing the Tab Bar Controller Properties

•   delegate  property
•   tabBar  property

Managing the View Controllers

•   viewControllers  property
• – setViewControllers:animated:
•   customizableViewControllers  property
•   moreNavigationController  property

Managing the Selected Tab

•   selectedViewController  property
•   selectedIndex  property

Properties

customizableViewControllers

The subset of view controllers managed by this tab bar controller that can be customized.

@property(nonatomic, copy) NSArray *customizableViewControllers

Discussion

This property controls which items in the tab bar can be rearranged by the user. When the user taps the More item on the tab bar view, a custom interface appears displaying any items that did not fit on the main tab bar. This interface also contains an Edit button that allows the user to rearrange the items. Only the items whose associated view controllers are in this array can be rearranged from this interface. If the array is empty or the value of this property is nil, the tab bar does not allow any items to be rearranged.

Changing the value of the viewControllers property (either directly or using the setViewControllers:animated: method) also changes the value of this property. When first assigned to the tab bar controller, all view controllers are customizable by default.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property moreNavigationController

Declared In

UITabBarController.h

delegate

The tab bar controller’s delegate object.

@property(nonatomic, assign) id<UITabBarControllerDelegate> delegate

Discussion

You can use the delegate object to track changes to the items in the tab bar and to monitor the selection of tabs. The delegate object you provide should conform to the UITabBarControllerDelegate protocol. The default value for this property is nil.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• SimpleNetworkStreams
• SimpleURLConnections

Declared In

UITabBarController.h

moreNavigationController

The view controller that manages the More navigation interface. (read-only)

@property(nonatomic, readonly) UINavigationController *moreNavigationController

Discussion

This property always contains a valid More navigation controller, even if a More button is not displayed on the screen. You can use the value of this property to select the More navigation controller in the tab bar interface or to compare it against the currently selected view controller.

Do not add the object stored in this property to your tab bar interface manually. The More controller is displayed automatically by the tab bar controller as it is needed. You must also not look for the More navigation controller in the array of view controllers stored in the viewControllersproperty. The tab bar controller does not include the More navigation controller in that array of objects.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property customizableViewControllers

Related Sample Code

• Tabster

Declared In

UITabBarController.h

selectedIndex

The index of the view controller associated with the currently selected tab item.

@property(nonatomic) NSUInteger selectedIndex

Discussion

This property nominally represents an index into the array of the viewControllers property. However, if the selected view controller is currently the More navigation controller, this property contains the value NSNotFound. Setting this property changes the selected view controller to the one at the designated index in the viewControllers array. To select the More navigation controller itself, you must change the value of theselectedViewController property instead.

In versions of iOS prior to version 3.0, this property reflects the index of the selected tab bar item only. Attempting to set this value to an index of a view controller that is not visible in the tab bar, but is instead managed by the More navigation controller, has no effect.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property selectedViewController

Related Sample Code

• AVPlayerDemo
• Tabster

Declared In

UITabBarController.h

selectedViewController

The view controller associated with the currently selected tab item.

@property(nonatomic, assign) UIViewController *selectedViewController

Discussion

This view controller is the one whose custom view is currently displayed by the tab bar interface. The specified view controller must be in theviewControllers array. Assigning a new view controller to this property changes the currently displayed view and also selects an appropriate tab in the tab bar. Changing the view controller also updates the selectedIndex property accordingly. The default value of this property is nil.

In iOS 3.0 and later, you can use this property to select any of the view controllers in the viewControllers property. This includes view controllers that are managed by the More navigation controller and whose tab bar items are not visible in the tab bar. You can also use it to select the More navigation controller itself, which is available from the moreNavigationController property. Prior to iOS 3.0, you could select only the More navigation controller and the subset of view controllers whose tab bar item was visible. Attempting to set this property to a view controller whose tab bar item was not visible had no effect.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property selectedIndex

Related Sample Code

• MoviePlayer

Declared In

UITabBarController.h

tabBar

The tab bar view associated with this controller. (read-only)

@property(nonatomic,readonly) UITabBar *tabBar

Discussion

You should never attempt to manipulate the UITabBar object itself stored in this property. If you attempt to do so, the tab bar view throws an exception. To configure the items for your tab bar interface, you should instead assign one or more custom view controllers to theviewControllers property. The tab bar collects the needed tab bar items from the view controllers you specify.

The tab bar view provided by this property is only for situations where you want to display an action sheet using the showFromTabBar: method of the UIActionSheet class.

Availability

• Available in iOS 3.0 and later.

Related Sample Code

• AVPlayerDemo

Declared In

UITabBarController.h

viewControllers

An array of the root view controllers displayed by the tab bar interface.

@property(nonatomic, copy) NSArray *viewControllers

Discussion

The default value of this property is nil. When configuring a tab bar controller, you can use this property to specify the content for each tab of the tab bar interface. The order of the view controllers in the array corresponds to the display order in the tab bar. Thus, the controller at index 0 corresponds to the left-most tab, the controller at index 1 the next tab to the right, and so on. If there are more view controllers than can fit in the tab bar, view controllers at the end of the array are managed by the More navigation controller, which is itself not included in this array.

If you change the value of this property at runtime, the tab bar controller removes all of the old view controllers before installing the new ones. The tab bar items for the new view controllers are displayed immediately and are not animated into position. When changing the view controllers, the tab bar controller remembers the view controller object that was previously selected and attempts to reselect it. If the selected view controller is no longer present, it attempts to select the view controller at the same index in the array as the previous selection. If that index is invalid, it selects the view controller at index 0.

Setting this property also sets the customizableViewControllers property to the same set of view controllers.

Availability

• Available in iOS 2.0 and later.

See Also

• – setViewControllers:animated:

Related Sample Code

• AVPlayerDemo
• GeocoderDemo
• Tabster
• TheElements

Declared In

UITabBarController.h

Instance Methods

setViewControllers:animated:

Sets the root view controllers of the tab bar controller.

- (void)setViewControllers:(NSArray *)viewControllers animated:(BOOL)animated

Parameters

viewControllers

The array of custom view controllers to display in the tab bar interface. The order of the view controllers in this array corresponds to the display order in the tab bar, with the controller at index 0 representing the left-most tab, the controller at index 1 the next tab to the right, and so on.

animated

If YES, the tab bar items for the view controllers are animated into position. If NO, changes to the tab bar items are reflected immediately.

Discussion

When you assign a new set of view controllers at runtime, the tab bar controller removes all of the old view controllers before installing the new ones. When changing the view controllers, the tab bar controller remembers the view controller object that was previously selected and attempts to reselect it. If the selected view controller is no longer present, it attempts to select the view controller at the same index in the array as the previous selection. If that index is invalid, it selects the view controller at index 0.

This method also sets the value of the customizableViewControllers property to the contents of the viewControllers parameter.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property viewControllers

Declared In

UITabBarController.h