iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIBarButtonItem Class Reference

Options
Deployment Target:

On This Page
Language:

UIBarButtonItem

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.

For more information about appearance and behavior configuration, see Toolbars.

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

    Declaration

    Swift

    unowned(unsafe) var target: AnyObject?

    Objective-C

    @property(nonatomic, assign) id _Nullable 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.

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

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property(nonatomic) SEL _Nullable 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

    target

  • The style of the item.

    Declaration

    Swift

    var style: UIBarButtonItemStyle

    Objective-C

    @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.

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

    Declaration

    Swift

    var possibleTitles: Set<String>?

    Objective-C

    @property(nonatomic, copy) NSSet <NSString *> * _Nullable 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.

  • The width of the item.

    Declaration

    Swift

    var width: CGFloat

    Objective-C

    @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.

  • A custom view representing the item.

    Declaration

    Swift

    var customView: UIView?

    Objective-C

    @property(nonatomic, strong) __kindof UIView * _Nullable customView

    Availability

    Available in iOS 2.0 and later.

Data Types

  • Specifies the style of a item.

    Declaration

    Swift

    enum UIBarButtonItemStyle : Int { case Plain case Bordered case Done }

    Objective-C

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

    Constants

    • Plain

      UIBarButtonItemStylePlain

      Glows when tapped. The default item style.

      Available in iOS 2.0 and later.

    • Bordered

      UIBarButtonItemStyleBordered

      A simple button style with a border.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • Done

      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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Defines system-supplied images for bar button items.

    Declaration

    Swift

    enum UIBarButtonSystemItem : Int { case Done case Cancel case Edit case Save case Add case FlexibleSpace case FixedSpace case Compose case Reply case Action case Organize case Bookmarks case Search case Refresh case Stop case Camera case Trash case Play case Pause case Rewind case FastForward case Undo case Redo case PageCurl }

    Objective-C

    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

    • Done

      UIBarButtonSystemItemDone

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

      Available in iOS 2.0 and later.

    • Cancel

      UIBarButtonSystemItemCancel

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

      Available in iOS 2.0 and later.

    • Edit

      UIBarButtonSystemItemEdit

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

      Available in iOS 2.0 and later.

    • Save

      UIBarButtonSystemItemSave

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

      Available in iOS 2.0 and later.

    • Add

      UIBarButtonSystemItemAdd

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

      Available in iOS 2.0 and later.

    • FlexibleSpace

      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.

    • FixedSpace

      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.

    • Compose

      UIBarButtonSystemItemCompose

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

      Available in iOS 2.0 and later.

    • Reply

      UIBarButtonSystemItemReply

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

      Available in iOS 2.0 and later.

    • Action

      UIBarButtonSystemItemAction

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

      Available in iOS 2.0 and later.

    • Organize

      UIBarButtonSystemItemOrganize

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

      Available in iOS 2.0 and later.

    • Bookmarks

      UIBarButtonSystemItemBookmarks

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

      Available in iOS 2.0 and later.

    • Search

      UIBarButtonSystemItemSearch

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

      Available in iOS 2.0 and later.

    • Refresh

      UIBarButtonSystemItemRefresh

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

      Available in iOS 2.0 and later.

    • Stop

      UIBarButtonSystemItemStop

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

      Available in iOS 2.0 and later.

    • Camera

      UIBarButtonSystemItemCamera

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

      Available in iOS 2.0 and later.

    • Trash

      UIBarButtonSystemItemTrash

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

      Available in iOS 2.0 and later.

    • Play

      UIBarButtonSystemItemPlay

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

      Available in iOS 2.0 and later.

    • Pause

      UIBarButtonSystemItemPause

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

      Available in iOS 2.0 and later.

    • Rewind

      UIBarButtonSystemItemRewind

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

      Available in iOS 2.0 and later.

    • FastForward

      UIBarButtonSystemItemFastForward

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

      Available in iOS 2.0 and later.

    • Undo

      UIBarButtonSystemItemUndo

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

      Available in iOS 3.0 and later.

    • Redo

      UIBarButtonSystemItemRedo

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

      Available in iOS 3.0 and later.

    • PageCurl

      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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.