UIBarItem Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UIBarItem.h

Overview

UIBarItem is an abstract superclass for items added to a bar that appears at the bottom of the screen. Items on a bar behave in a way similar to buttons (instances of UIButton). They have a title, image, action, and target. You can also enable and disable an item on a bar.

Customizing Appearance

You can customize the image to represent the item, and the position of the image, using imageand imageInsets respectively.

In iOS v5.0 and later, you can also specify a custom image and position to use in landscape orientation when using the iPhone appearance idiom using landscapeImagePhoneand landscapeImagePhoneInsets respectively. In addition, you can customize the title’s text attributes using setTitleTextAttributes:forState:, either for a single item, or for all items by using the appearance proxy (for example, [UIBarItem appearance]).

Tasks

Getting and Setting Properties

Customizing Appearance

Properties

enabled

A Boolean value indicating whether the item is enabled.

@property(nonatomic, getter=isEnabled) BOOL enabled
Discussion

If NO, the item is drawn partially dimmed to indicate it is disabled. The default value is YES.

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

image

The image used to represent the item.

@property(nonatomic, retain) UIImage *image
Discussion

This image can be used to create other images to represent this item on the bar—for example, a selected and unselected image may be derived from this image. You should set this property before adding the item to a bar. The default value is nil.

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

imageInsets

The image inset or outset for each edge.

@property(nonatomic) UIEdgeInsets imageInsets
Discussion

The default value is UIEdgeInsetsZero.

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

landscapeImagePhone

The image to use to represent the item in landscape orientation when using the iPhone appearance idiom.

@property(nonatomic, retain) UIImage *landscapeImagePhone
Discussion

This image can be used to create other images to represent this item on the bar—for example, a selected and unselected image may be derived from this image. You should set this property before adding the item to a bar. The default value is nil.

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

landscapeImagePhoneInsets

The image inset or outset for each edge of the image in landscape orientation when using the iPhone appearance idiom.

@property(nonatomic) UIEdgeInsets landscapeImagePhoneInsets
Discussion

The default value is UIEdgeInsetsZero.

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

tag

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

@property(nonatomic) NSInteger tag
Discussion

The default value is 0.

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

title

The title displayed on the item.

@property(nonatomic, copy) NSString *title
Discussion

You should set this property before adding the item to a bar. The default value is nil.

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

Instance Methods

setTitleTextAttributes:forState:

Sets the title’s text attributes for a given control state.

- (void)setTitleTextAttributes:(NSDictionary *)attributes forState:(UIControlState)state
Parameters
attributes

A dictionary containing key-value pairs for text attributes.

You can specify the font, text color, text shadow color, and text shadow offset using the keys listed in NSString UIKit Additions Reference.

state

The control state for which you want to set the text attributes for the title.

Availability
  • Available in iOS 5.0 and later.
Related Sample Code
Declared In
UIBarItem.h

titleTextAttributesForState:

Returns the title’s text attributes for a given control state.

- (NSDictionary *)titleTextAttributesForState:(UIControlState)state
Parameters
state

The control state for which you want to know the text attributes for the title.

Return Value

The title’s text attributes for state.

Discussion

The dictionary may contain key-value pairs for text attributes for the font, text color, text shadow color, and text shadow offset using the keys listed in NSString UIKit Additions Reference.

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