iPhone OS Reference Library Apple Developer Connection spyglass button

UIBarButtonItem Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iPhone OS 2.0 and later.
Declared in
UIBarButtonItem.h
Related sample code

Overview

The UIBarButtonItem class encapsulates the properties and behaviors of items added to UIToolbar and UINavigationBar objects. It inherits basic button behavior from its parent class. This class defines additional initialization methods and properties for use on tab bars and navigation bars that allow more custom views.

Tasks

Initializing an Item

Getting and Setting Properties

Properties

For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.

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
See Also
Declared In
UIBarButtonItem.h

customView

A custom view representing the item.

@property(nonatomic, retain) UIView *customView
Availability
Related Sample Code
Declared In
UIBarButtonItem.h

possibleTitles

Collection of possible titles to display on the bar.

@property(nonatomic, copy) NSSet *possibleTitles
Availability
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
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
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
Declared In
UIBarButtonItem.h

Instance Methods

initWithBarButtonSystemItem:target:action:

Creates and returns 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 iPhone OS 2.0 and later.
See Also
Related Sample Code
Declared In
UIBarButtonItem.h

initWithCustomView:

Creates and returns 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.

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

initWithImage:style:target:action:

Creates and returns 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 iPhone OS 2.0 and later.
See Also
Related Sample Code
Declared In
UIBarButtonItem.h

initWithTitle:style:target:action:

Creates and returns 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 iPhone OS 2.0 and later.
See Also
Related Sample Code
Declared In
UIBarButtonItem.h

Constants

UIBarButtonSystemItem

Defines system defaults for commonly used 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,        // iPhoneOS 3.0
   UIBarButtonSystemItemRedo,        // iPhoneOS 3.0
} UIBarButtonSystemItem;
Constants
UIBarButtonSystemItemDone

The system Done button. Localized.

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemCancel

The system Cancel button. Localized.

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemEdit

The system Edit button. Localized.

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemSave

The system Save button. Localized.

Available in iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemCompose

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemReply

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemAction

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemOrganize

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemBookmarks

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemSearch

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemRefresh

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemStop

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemCamera

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemTrash

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemPlay

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemPause

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemRewind

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemFastForward

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

Available in iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemUndo

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

Available in iPhone OS 3.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonSystemItemRedo

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

Available in iPhone OS 3.0 and later.

Declared in UIBarButtonItem.h.

Availability
  • Available in iPhone OS 2.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 iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

UIBarButtonItemStyleBordered

A simple button style with a border.

Available in iPhone OS 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 iPhone OS 2.0 and later.

Declared in UIBarButtonItem.h.

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

Last updated: 2009-05-06

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