UITabBarItem Class Reference

Inherits from	UIBarItem : NSObject
Conforms to	UIAppearance (UIBarItem) 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	UITabBarItem.h
Related sample code	AVPlayerDemo GLImageProcessing Tabster

Overview

The UITabBarItem class implements an item on a UITabBar object. A tab bar operates strictly in radio mode, where one item is selected at a time—tapping a tab bar item toggles the view above the tab bar. You can also specify a badge value on the tab bar item for adding additional visual information—for example, the Messages app uses a badge on the item to show the number of new messages. This class also provides a number of system defaults for creating items.

Use the initWithTabBarSystemItem:tag: method to create one of the system items. Use the initWithTitle:image:tag: method to create a custom item with the specified title and image.

Customizing Appearance

In iOS v5.0 and later, you can customize the appearance of tab bars by setting item label text attributes using appearance selectors declared by UIBarItem. You can also use the methods listed in “Customizing Appearance.” You can customize the appearance of all tab bar items using the appearance proxy (for example, [UITabBarItem appearance]), or just of a single tab bar item. You can also provide finished selected and unselected images using the methods listed in “Managing the Finished Selected Image”; these methods, though, do not participate in the UIAppearance proxy API (see UIAppearance). UIKit does not provide any automatic treatment to finished images. For good results, you must provide finished selected and unselected images in matching pairs using setFinishedSelectedImage:withFinishedUnselectedImage:.

Tasks

Initializing an Item

Getting and Setting Properties

Managing the Finished Selected Image

Customizing Appearance

Properties

badgeValue

Text that is displayed in the upper-right corner of the item with a surrounding red oval.

@property(nonatomic, copy) NSString *badgeValue

Discussion

The default value is nil.

Availability

Available in iOS 2.0 and later.

Declared In

UITabBarItem.h

Instance Methods

finishedSelectedImage

Returns the finished selected image.

- (UIImage *)finishedSelectedImage

Return Value

The finished selected image.

Availability

Available in iOS 5.0 and later.

Declared In

UITabBarItem.h

finishedUnselectedImage

Returns the finished unselected image.

- (UIImage *)finishedUnselectedImage

Return Value

The finished unselected image.

Availability

Available in iOS 5.0 and later.

Declared In

UITabBarItem.h

initWithTabBarSystemItem:tag:

Creates and returns a new item containing the specified system item.

- (id)initWithTabBarSystemItem:(UITabBarSystemItem)systemItem tag:(NSInteger)tag

Parameters

systemItem: The system item to use as the first item on the tab bar. One of the constants defined in UITabBarSystemItem.
tag: The receiver’s tag, an integer that you can use to identify bar item objects in your application.

Return Value

A newly initialized item containing the specified system item. The item’s target is nil.

Discussion

This method returns a system-supplied tab bar item. The title and image properties of the returned item cannot be changed later.

Availability

Available in iOS 2.0 and later.

Declared In

UITabBarItem.h

initWithTitle:image:tag:

Creates and returns a new item using the specified properties.

- (id)initWithTitle:(NSString *)title image:(UIImage *)image tag:(NSInteger)tag

Parameters

title

The item’s title. If nil, a title is not displayed.

image

The item’s image. If nil, an image is not displayed.

The images displayed on the tab bar are derived from this image. The alpha values in the source image are used to create the unselected and selected images—opaque values are ignored. If this image is too large to fit on the tab bar, it is clipped to fit. The size of a tab bar image is typically 60 x 60 pixels. See “Custom Icon and Image Creation Guidelines” for more information about tab bar icons.

tag

The receiver’s tag, an integer that you can use to identify bar item objects in your application.

Return Value

Newly initialized item with the specified properties.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Tabster

Declared In

UITabBarItem.h

setFinishedSelectedImage:withFinishedUnselectedImage:

Sets the finished selected and unselected images.

- (void)setFinishedSelectedImage:(UIImage *)selectedImage withFinishedUnselectedImage:(UIImage *)unselectedImage

Parameters

selectedImage: The finished selected image.
unselectedImage: The finished unselected image.

Availability

Available in iOS 5.0 and later.

Declared In

UITabBarItem.h

setTitlePositionAdjustment:

Sets the offset to use to adjust the title position.

- (void)setTitlePositionAdjustment:(UIOffset)adjustment

Parameters

adjustment: The offset to use to adjust the title position.

Availability

Available in iOS 5.0 and later.

Declared In

UITabBarItem.h

titlePositionAdjustment

Returns the offset to use to adjust the title position.

- (UIOffset)titlePositionAdjustment

Return Value

The offset to use to adjust the title position.

Availability

Available in iOS 5.0 and later.

Declared In

UITabBarItem.h

Constants

UITabBarSystemItem

System items that can be used on a tab bar.

typedef enum {
   UITabBarSystemItemMore,
   UITabBarSystemItemFavorites,
   UITabBarSystemItemFeatured,
   UITabBarSystemItemTopRated,
   UITabBarSystemItemRecents,
   UITabBarSystemItemContacts,
   UITabBarSystemItemHistory,
   UITabBarSystemItemBookmarks,
   UITabBarSystemItemSearch,
   UITabBarSystemItemDownloads,
   UITabBarSystemItemMostRecent,
   UITabBarSystemItemMostViewed,
} UITabBarSystemItem;