Class

UIBarButtonItem

A button specialized for placement on a toolbar or tab bar.

Declaration

class UIBarButtonItem : UIBarItem

Overview

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 UIBarMetrics.default.

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

Topics

Initializing an Item

init(barButtonSystemItem: UIBarButtonItem.SystemItem, target: Any?, action: Selector?)

Initializes a new item containing the specified system item.

init(customView: UIView)

Initializes a new item using the specified custom view.

init(image: UIImage?, style: UIBarButtonItem.Style, target: Any?, action: Selector?)

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

init(title: String?, style: UIBarButtonItem.Style, target: Any?, action: Selector?)

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

init(image: UIImage?, landscapeImagePhone: UIImage?, style: UIBarButtonItem.Style, target: Any?, action: Selector?)

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

init()

Initializes the bar button item to its default state.

init?(coder: NSCoder)

Getting and Setting Properties

var target: AnyObject?

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

var action: Selector?

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

var style: UIBarButtonItem.Style

The style of the item.

var possibleTitles: Set<String>?

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

var width: CGFloat

The width of the item.

var customView: UIView?

A custom view representing the item.

Customizing Appearance

var tintColor: UIColor?

The tint color to apply to the button item.

func backButtonBackgroundImage(for: UIControl.State, barMetrics: UIBarMetrics) -> UIImage?

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

func setBackButtonBackgroundImage(UIImage?, for: UIControl.State, barMetrics: UIBarMetrics)

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

func backButtonTitlePositionAdjustment(for: UIBarMetrics) -> UIOffset

Returns the back button title offset for given bar metrics.

func setBackButtonTitlePositionAdjustment(UIOffset, for: UIBarMetrics)

Sets the back button title offset for given bar metrics

func backButtonBackgroundVerticalPositionAdjustment(for: UIBarMetrics) -> CGFloat

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

func setBackButtonBackgroundVerticalPositionAdjustment(CGFloat, for: UIBarMetrics)

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

func backgroundVerticalPositionAdjustment(for: UIBarMetrics) -> CGFloat

Returns the background vertical position offset for given bar metrics.

func setBackgroundVerticalPositionAdjustment(CGFloat, for: UIBarMetrics)

Sets the background vertical position offset for given bar metrics.

func backgroundImage(for: UIControl.State, barMetrics: UIBarMetrics) -> UIImage?

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

func setBackgroundImage(UIImage?, for: UIControl.State, barMetrics: UIBarMetrics)

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

func backgroundImage(for: UIControl.State, style: UIBarButtonItem.Style, barMetrics: UIBarMetrics) -> UIImage?

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

func setBackgroundImage(UIImage?, for: UIControl.State, style: UIBarButtonItem.Style, barMetrics: UIBarMetrics)

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

func titlePositionAdjustment(for: UIBarMetrics) -> UIOffset

Returns the title offset for given bar metrics.

func setTitlePositionAdjustment(UIOffset, for: UIBarMetrics)

Sets the title offset for given bar metrics.

Getting the Shortcuts Group Information

var buttonGroup: UIBarButtonItemGroup?

The group on the shortcuts bar to which the button belongs.

Constants

enum UIBarButtonItem.SystemItem

Defines system-supplied images for bar button items.

enum UIBarButtonItem.Style

Specifies the style of an item.

Relationships

Inherits From

Conforms To

See Also

Bars

class UIBarItem

An abstract superclass for items that can be added to a bar that appears at the bottom of the screen.

class UIBarButtonItemGroup

A set of bar button items on the shortcuts bar above the keyboard on iPad.

class UINavigationBar

Navigational controls displayed in a bar along the top of the screen, usually in conjunction with a navigation controller.

class UISearchBar

A specialized view for receiving search-related information from the user.

class UIToolbar

A control that displays one or more buttons along the bottom edge of your interface.

class UITabBar

A control that displays one or more buttons in a tab bar for selecting between different subtasks, views, or modes in an app.

class UITabBarItem

An item in a tab bar.

protocol UIBarPositioning

A set of methods for defining the ways that bars can be positioned in iOS apps.

protocol UIBarPositioningDelegate

A set of methods that support the positioning of a bar that conforms to the UIBarPositioning protocol.