UIBarButtonItem Class Reference

Inherits from
UIBarItem : NSObject
Conforms to
NSCoding
UIAppearance (UIBarItem)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UIBarButtonItem.h
Related sample code

Overview

A bar button item is a button specialized for placement on a UIToolbar or UINavigationBar object. It inherits basic button behavior from its abstract superclass, UIBarItem. The UIBarButtonItem defines additional initialization methods and properties for use on toolbars and navigation bars.

You typically use Interface Builder to create and configure bar button items.

Customizing Appearance

You use the methods listed in “Customizing Appearance” to customize the appearance of buttons. You send the setter messages to the appearance proxy ([UIBarButtonItem appearance]) to customize all buttons, or to a specific UIBarButtonItem instance. You may use customized buttons in standard places in a UINavigationItem object (backBarButtonItem, leftBarButtonItem, rightBarButtonItem) or a UIToolbar instance.

In general, you should specify a value for the normal state to be used by other states which don’t have a custom value set. Similarly, when a property is dependent on the bar metrics (on iPhone, in landscape orientation bars have a different height from standard), you should specify a value of UIBarMetricsDefault.

Tasks

Initializing an Item

Getting and Setting Properties

Customizing Appearance

Properties

action

The selector defining the action message to send to the target object when the user taps this bar button item.

@property(nonatomic) SEL action
Discussion

If the value of this property is NULL, no action message is sent. The default value is NULL.

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

customView

A custom view representing the item.

@property(nonatomic, retain) UIView *customView
Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIBarButtonItem.h

possibleTitles

The set of possible titles to display on the bar button.

@property(nonatomic, copy) NSSet *possibleTitles
Discussion

Use this property to provide a hint to the system on how to correctly size the bar button item to be wide enough to accommodate your widest title. Set the value of this property to an NSSet object containing all the titles you intend as possible titles for the bar button item. Use the actual text strings you intend to display.

This property applies to bar button items placed on navigation bars or toolbars.

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

style

The style of the item.

@property(nonatomic) UIBarButtonItemStyle style
Discussion

One of the constants defined in UIBarButtonItemStyle. The default value is UIBarButtonItemStylePlain.

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

target

The object that receives an action when the item is selected.

@property(nonatomic, assign) id target
Discussion

If nil, the action message is passed up the responder chain where it may be handled by any object implementing a method corresponding to the selector held by the action property. The default value is nil.

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

tintColor

The tint color for the button item.

@property(nonatomic, retain) UIColor *tintColor
Availability
  • Available in iOS 5.0 and later.
Declared In
UIBarButtonItem.h

width

The width of the item.

@property(nonatomic) CGFloat width
Discussion

If this property value is positive, the width of the combined image and title are fixed. If the value is 0.0 or negative, the item sets the width of the combined image and title to fit. This property is ignored if the style uses radio mode. The default value is 0.0.

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

Instance Methods

backButtonBackgroundImageForState:barMetrics:

Returns the back button background image for a given control state and bar metrics.

- (UIImage *)backButtonBackgroundImageForState:(UIControlState)state barMetrics:(UIBarMetrics)barMetrics
Parameters
state

A control state.

barMetrics

Bar metrics.

Return Value

The back button background image for state and barMetrics.

Discussion

This modifier applies only to navigation bar back buttons and is ignored by other buttons.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

backButtonBackgroundVerticalPositionAdjustmentForBarMetrics:

Returns the back button vertical position offset for given bar metrics.

- (CGFloat)backButtonBackgroundVerticalPositionAdjustmentForBarMetrics:(UIBarMetrics)barMetrics
Parameters
barMetrics

Bar metrics.

Return Value

The back button vertical position offset for barMetrics.

Discussion

This modifier applies only to navigation bar back buttons and is ignored by other buttons.

This offset is used to adjust the vertical centering of bordered bar buttons within the bar.

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

backButtonTitlePositionAdjustmentForBarMetrics:

Returns the back button title offset for given bar metrics.

- (UIOffset)backButtonTitlePositionAdjustmentForBarMetrics:(UIBarMetrics)barMetrics
Parameters
barMetrics

Bar metrics.

Return Value

The back button title offset for barMetrics.

Discussion

This modifier applies only to navigation bar back buttons and is ignored by other buttons.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

backgroundImageForState:barMetrics:

Returns the background image for a given state and bar metrics.

- (UIImage *)backgroundImageForState:(UIControlState)state barMetrics:(UIBarMetrics)barMetrics
Parameters
state

A control state.

barMetrics

Bar metrics.

Return Value

The background image for the button given state and metrics.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

backgroundImageForState:style:barMetrics:

Returns the background image for the specified state, style, and metrics.

- (UIImage *)backgroundImageForState:(UIControlState)state style:(UIBarButtonItemStyle)style barMetrics:(UIBarMetrics)barMetrics
Parameters
state

The bar button state.

style

The bar button style.

barMetrics

The bar button metrics.

Return Value

The background image associated with the specified state, style, and metrics.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIBarButtonItem.h

backgroundVerticalPositionAdjustmentForBarMetrics:

Returns the background vertical position offset for given bar metrics.

- (CGFloat)backgroundVerticalPositionAdjustmentForBarMetrics:(UIBarMetrics)barMetrics
Parameters
barMetrics

Bar metrics.

Return Value

The background vertical position offset for barMetrics.

Discussion

This offset is used to adjust the vertical centering of bordered bar buttons within the bar.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

initWithBarButtonSystemItem:target:action:

Initializes a new item containing the specified system item.

- (id)initWithBarButtonSystemItem:(UIBarButtonSystemItem)systemItem target:(id)target action:(SEL)action
Parameters
systemItem

The system item to use as the first item on the bar. One of the constants defined in UIBarButtonSystemItem.

target

The object that receives the action message.

action

The action to send to target when this item is selected.

Return Value

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

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

initWithCustomView:

Initializes a new item using the specified custom view.

- (id)initWithCustomView:(UIView *)customView
Parameters
customView

A custom view representing the item.

Return Value

Newly initialized item with the specified properties.

Discussion

The bar button item created by this method does not call the action method of its target in response to user interactions. Instead, the bar button item expects the specified custom view to handle any user interactions and provide an appropriate response.

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

initWithImage:landscapeImagePhone:style:target:action:

Initializes a new item using the specified images and other properties.

- (id)initWithImage:(UIImage *)image landscapeImagePhone:(UIImage *)landscapeImagePhone style:(UIBarButtonItemStyle)style target:(id)target action:(SEL)action
Parameters
image

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

landscapeImagePhone

The image to be used for the item in landscape bars in the UIUserInterfaceIdiomPhone idiom.

style

The style of the item. One of the constants defined in UIBarButtonItemStyle.

target

The object that receives the action message.

action

The action to send to target when this item is selected.

Return Value

A new item initialized to use using the specified images and other properties

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

initWithImage:style:target:action:

Initializes a new item using the specified image and other properties.

- (id)initWithImage:(UIImage *)image style:(UIBarButtonItemStyle)style target:(id)target action:(SEL)action
Parameters
image

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

The images displayed on the bar are derived from this image. If this image is too large to fit on the bar, it is scaled to fit. Typically, the size of a toolbar and navigation bar image is 20 x 20 points. The alpha values in the source image are used to create the images—opaque values are ignored.

style

The style of the item. One of the constants defined in UIBarButtonItemStyle.

target

The object that receives the action message.

action

The action to send to target when this item is selected.

Return Value

Newly initialized item with the specified properties.

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

initWithTitle:style:target:action:

Initializes a new item using the specified title and other properties.

- (id)initWithTitle:(NSString *)title style:(UIBarButtonItemStyle)style target:(id)target action:(SEL)action
Parameters
title

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

style

The style of the item. One of the constants defined in UIBarButtonItemStyle.

target

The object that receives the action message.

action

The action to send to target when this item is selected.

Return Value

Newly initialized item with the specified properties.

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

setBackButtonBackgroundImage:forState:barMetrics:

Sets the back button background image for a given control state and bar metrics

- (void)setBackButtonBackgroundImage:(UIImage *)backgroundImage forState:(UIControlState)state barMetrics:(UIBarMetrics)barMetrics
Parameters
backgroundImage

The image to use for the back button’s background.

state

A control state.

barMetrics

Bar metrics.

Discussion

This modifier applies only to navigation bar back buttons and is ignored by other buttons.

For good results, backgroundImage must be a stretchable image.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

setBackButtonBackgroundVerticalPositionAdjustment:forBarMetrics:

Sets the back button vertical position offset for given bar metrics.

- (void)setBackButtonBackgroundVerticalPositionAdjustment:(CGFloat)adjustment forBarMetrics:(UIBarMetrics)barMetrics
Parameters
adjustment

The back button vertical position offset for barMetrics.

barMetrics

Bar metrics.

Discussion

This modifier applies only to navigation bar back buttons and is ignored by other buttons.

This offset is used to adjust the vertical centering of bordered bar buttons within the bar.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

setBackButtonTitlePositionAdjustment:forBarMetrics:

Sets the back button title offset for given bar metrics

- (void)setBackButtonTitlePositionAdjustment:(UIOffset)adjustment forBarMetrics:(UIBarMetrics)barMetrics
Parameters
adjustment

The back button title offset for barMetrics.

barMetrics

Bar metrics.

Discussion

This modifier applies only to navigation bar back buttons and is ignored by other buttons.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

setBackgroundImage:forState:barMetrics:

Sets the background image for a given state and bar metrics.

- (void)setBackgroundImage:(UIImage *)backgroundImage forState:(UIControlState)state barMetrics:(UIBarMetrics)barMetrics
Parameters
backgroundImage

The background image for the specified state and metrics.

state

A control state.

barMetrics

Bar metrics.

Discussion

For good results, backgroundImage must be a stretchable image.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

setBackgroundImage:forState:style:barMetrics:

Sets the background image for the specified state, style, and metrics.

- (void)setBackgroundImage:(UIImage *)backgroundImage forState:(UIControlState)state style:(UIBarButtonItemStyle)style barMetrics:(UIBarMetrics)barMetrics
Parameters
backgroundImage

The background image to use for the specified state, style, and metrics.

state

The bar button state.

style

The bar button style.

barMetrics

The bar button metrics.

Discussion

For good results, backgroundImage must be a stretchable image.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIBarButtonItem.h

setBackgroundVerticalPositionAdjustment:forBarMetrics:

Sets the background vertical position offset for given bar metrics.

- (void)setBackgroundVerticalPositionAdjustment:(CGFloat)adjustment forBarMetrics:(UIBarMetrics)barMetrics
Parameters
adjustment

The background vertical position offset for barMetrics.

barMetrics

Bar metrics.

Discussion

This offset is used to adjust the vertical centering of bordered bar buttons within the bar.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIBarButtonItem.h

setTitlePositionAdjustment:forBarMetrics:

Sets the title offset for given bar metrics.

- (void)setTitlePositionAdjustment:(UIOffset)adjustment forBarMetrics:(UIBarMetrics)barMetrics
Parameters
adjustment

The title offset for barMetrics.

barMetrics

Bar metrics.

Discussion

This offset is used to adjust the position of a title (if any) within a bordered bar button.

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

titlePositionAdjustmentForBarMetrics:

Returns the title offset for given bar metrics.

- (UIOffset)titlePositionAdjustmentForBarMetrics:(UIBarMetrics)barMetrics
Parameters
barMetrics

Bar metrics.

Return Value

The title offset for barMetrics.

Discussion

This offset is used to adjust the position of a title (if any) within a bordered bar button.

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

Constants

UIBarButtonSystemItem

Defines system-supplied images for bar button items.

typedef enum {
   UIBarButtonSystemItemDone,
   UIBarButtonSystemItemCancel,
   UIBarButtonSystemItemEdit,
   UIBarButtonSystemItemSave,
   UIBarButtonSystemItemAdd,
   UIBarButtonSystemItemFlexibleSpace,
   UIBarButtonSystemItemFixedSpace,
   UIBarButtonSystemItemCompose,
   UIBarButtonSystemItemReply,
   UIBarButtonSystemItemAction,
   UIBarButtonSystemItemOrganize,
   UIBarButtonSystemItemBookmarks,
   UIBarButtonSystemItemSearch,
   UIBarButtonSystemItemRefresh,
   UIBarButtonSystemItemStop,
   UIBarButtonSystemItemCamera,
   UIBarButtonSystemItemTrash,
   UIBarButtonSystemItemPlay,
   UIBarButtonSystemItemPause,
   UIBarButtonSystemItemRewind,
   UIBarButtonSystemItemFastForward,
   UIBarButtonSystemItemUndo,        // iOS 3.0 and later
   UIBarButtonSystemItemRedo,        // iOS 3.0 and later
   UIBarButtonSystemItemPageCurl,    // iOS 4.0 and later
} UIBarButtonSystemItem;
Constants
UIBarButtonSystemItemDone

The system Done button. Localized. image: ../Art/UIBarButtonSystemItemDone.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemCancel

The system Cancel button. Localized. image: ../Art/UIBarSystemItemCancel.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemEdit

The system Edit button. Localized. image: ../Art/UIBarSystemItemEdit.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemSave

The system Save button. Localized. image: ../Art/UIBarButtonSystemItemSave.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemAdd

The system plus button containing an icon of a plus sign. image: ../Art/UIBarButtonAdd.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemFlexibleSpace

Blank space to add between other items. The space is distributed equally between the other items. Other item properties are ignored when this value is set.

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemFixedSpace

Blank space to add between other items. Only the width property is used when this value is set.

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemCompose

The system compose button. image: ../Art/UIBarButtonCompose.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemReply

The system reply button. image: ../Art/UIBarButtonReply.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemAction

The system action button. image: ../Art/UIBarButtonAction.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemOrganize

The system organize button. image: ../Art/UIBarButtonOrganize.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemBookmarks

The system bookmarks button. image: ../Art/UIBarButtonBookmarks.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemSearch

The system search button. image: ../Art/UIBarButtonSearch.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemRefresh

The system refresh button. image: ../Art/UIBarButtonRefresh.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemStop

The system stop button. image: ../Art/UIBarButtonStop.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemCamera

The system camera button. image: ../Art/UIBarButtonCamera.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemTrash

The system trash button. image: ../Art/UIBarButtonTrash.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemPlay

The system play button. image: ../Art/UIBarButtonPlay.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemPause

The system pause button. image: ../Art/UIBarButtonPause.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemRewind

The system rewind button. image: ../Art/UIBarButtonRewind.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemFastForward

The system fast forward button. image: ../Art/UIBarButtonFastForward.png

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemUndo

The system undo button.image: ../Art/UIBarButtonSystemItemUndo.png

Available in iOS 3.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemRedo

The system redo button.image: ../Art/UIBarButtonSystemItemRedo.png

Available in iOS 3.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemPageCurl

The system page curl button. image: ../Art/UIBarButtonSystemItemPageCurl.png

This bar button image can be used only for bar button items placed on toolbars.

Available in iOS 4.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonItemStyle

Specifies the style of a item.

typedef enum {
   UIBarButtonItemStylePlain,
   UIBarButtonItemStyleBordered,
   UIBarButtonItemStyleDone,
} UIBarButtonItemStyle;
Constants
UIBarButtonItemStylePlain

Glows when tapped. The default item style.

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonItemStyleBordered

A simple button style with a border.

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonItemStyleDone

The style for a done button—for example, a button that completes some task and returns to the previous view.

Available in iOS 2.0 and later.

Declared in UIBarButtonItem.h.

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

UIBarMetrics

Constants to specify metrics to use for appearance.

typedef enum {
   UIBarMetricsDefault,
   UIBarMetricsLandscapePhone,
} UIBarMetrics;
Constants
UIBarMetricsDefault

Specifies default metrics for the device.

Available in iOS 5.0 and later.

Declared in UIBarButtonItem.h.

UIBarMetricsLandscapePhone

Specifies metrics for landscape orientation using the phone idiom.

Available in iOS 5.0 and later.

Declared in UIBarButtonItem.h.



© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

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