UIToolbar Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UIToolbar.h
Companion guides
Related sample code

Overview

A toolbar is a control that displays one or more buttons, called toolbar items. A toolbar momentarily highlights or does not change the appearance of an item when tapped.

To create toolbar items, use the UIBarButtonItem class. To add toolbar items to a toolbar, use the setItems:animated: method.

Toolbar images that represent normal and highlighted states of an item derive from the image you set using the inherited image property from the UIBarItem class. In iOS 7.0, the image is colored with the toolbar’s tintColor.

If you need radio button style controls, use the UITabBar class instead of UIToolbar.

Customizing Appearance

You use the methods listed in “Customizing Appearance” to customize the appearance of toolbars. You send the setter messages to the appearance proxy ([UIToolbar appearance]) to customize all toolbars, or to a specific UIToolbar instance. When a property is dependent on the bar metrics (on iPhone, in landscape orientation bars have a different height from standard), you should typically specify a value for UIBarMetricsDefault as well as forUIBarMetricsLandscapePhone.

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

Tasks

Configuring Toolbar Items

Customizing Appearance

Managing the Delegate

Properties

barStyle

The toolbar style that specifies its appearance.

@property(nonatomic) UIBarStyle barStyle
Discussion

See UIBarStyle for possible values. The default value is UIBarStyleDefault.

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

barTintColor

The tint color to apply to the toolbar background.

@property(nonatomic, retain) UIColor *barTintColor
Discussion

This color is made translucent by default unless you set the translucent property to NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIToolbar.h

delegate

The toolbar’s delegate object.

@property(nonatomic, assign) id<UIToolbarDelegate> delegate
Discussion

The delegate should conform to the UIToolbarDelegate protocol. You may not set the delegate when the toolbar is managed by a navigation controller. The default value is nil.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIToolbar.h

items

The items displayed on the toolbar.

@property(nonatomic, copy) NSArray *items
Discussion

The items, instances of UIBarButtonItem, that are visible on the toolbar in the order they appear in this array. Any changes to this property are not animated. Use the setItems:animated: method to animate changes.

The default value is nil.

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

tintColor

The tint color to apply to the bar button items.

@property(nonatomic, retain) UIColor *tintColor
Discussion

In iOS v7.0, all subclasses of UIView derive their behavior for tintColor from the base class. See the discussion of tintColor at the UIView level for more information.

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

translucent

A Boolean value that indicates whether the toolbar is translucent (YES) or not (NO).

@property(nonatomic, assign, getter=isTranslucent) BOOL translucent
Discussion

The default value is YES. If the toolbar has a custom background image, the default is YES if any pixel of the image has an alpha value of less than 1.0, and NO otherwise.

If you set this property to YES on a toolbar with an opaque custom background image, the toolbar will apply a system opacity less than 1.0 to the image.

If you set this property to NO on a toolbar with a translucent custom background image, the toolbar provides an opaque background for the image using black if the toolbar has UIBarStyleBlack style, white if the toolbar has UIBarStyleDefault, or the toolbar’s barTintColor if a custom value is defined.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIToolbar.h

Instance Methods

backgroundImageForToolbarPosition:barMetrics:

Returns the image to use for the background in a given position and with given metrics.

- (UIImage *)backgroundImageForToolbarPosition:(UIBarPosition)topOrBottom barMetrics:(UIBarMetrics)barMetrics
Parameters
topOrBottom

The location the bar is being drawn in.

barMetrics

The metrics being used to draw the bar.

Return Value

The image to use for the toolbar background in the position specified by topOrBottom and with the metrics specified by barMetrics.

Discussion

The default value is nil. When non-nil the image will be used instead of the system image for toolbars in the specified position.

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

setBackgroundImage:forToolbarPosition:barMetrics:

Sets the image to use for the background in a given position and with given metrics.

- (void)setBackgroundImage:(UIImage *)backgroundImage forToolbarPosition:(UIBarPosition)topOrBottom barMetrics:(UIBarMetrics)barMetrics
Parameters
backgroundImage

The image to use for the toolbar background in the position specified by topOrBottom and with the metrics specified by barMetrics.

topOrBottom

A toolbar position constant.

barMetrics

A bar metrics constant.

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

setItems:animated:

Sets the items on the toolbar by animating the changes.

- (void)setItems:(NSArray *)items animated:(BOOL)animated
Parameters
items

The items to display on the toolbar.

animated

A Boolean value if set to YES animates the transition to the items; otherwise, does not.

Discussion

If animated is YES, the changes are dissolved or the reordering is animated—for example, removed items fade out and new items fade in. This method also adjusts the spacing between items.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIToolbar.h

setShadowImage:forToolbarPosition:

Sets the image to use for the toolbar shadow in a given position.

- (void)setShadowImage:(UIImage *)shadowImage forToolbarPosition:(UIBarPosition)topOrBottom
Parameters
shadowImage

The image to use for the toolbar shadow in the position specified by topOrBottom.

topOrBottom

A toolbar position constant. You can use this parameter to indicate whether the shadowImage is intended for a toolbar at the top or bottom of the view.

Discussion

When the shadowImage parameter is nil, the default shadow will be used. When non-nil, the shadowImage property is a custom shadow image to show instead of the default. Using the topOrBottom parameter, you can set a different shadow for toolbars at the top and bottom of the view. For a custom shadow image to be shown, a custom background image must also be set with the setBackgroundImage:forToolbarPosition:barMetrics: method. If the default background image is used, then the default shadow image will be used regardless of the value of the shadowImage parameter.

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

shadowImageForToolbarPosition:

Returns the image to use for the toolbar shadow in a given position.

- (UIImage *)shadowImageForToolbarPosition:(UIBarPosition)topOrBottom
Parameters
topOrBottom

A toolbar position constant. You can use this parameter to indicate whether the shadow image returned is intended for use in a toolbar at the top or bottom of the view.

Return Value

The image to use for the toolbar shadow in the position specified by topOrBottom.

Discussion

The default value is nil, which corresponds to the default shadow image being used. When non-nil, the return value represents the shadow that is used on the toolbar in the position specified by the topOrBottom parameter.

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

Constants

UIToolbarPosition

Constants to identify the position of a toolbar for appearance customization (see setBackgroundImage:forToolbarPosition:barMetrics:). (Deprecated. Use UIBarPosition instead.)

typedef enum {
   UIToolbarPositionAny = 0,
   UIToolbarPositionBottom = 1,
   UIToolbarPositionTop = 2,
} UIToolbarPosition;
Constants
UIToolbarPositionAny

Indicates the toolbar may be in any position.

Available in iOS 5.0 through iOS 6.1.

Declared in UIToolbar.h.

UIToolbarPositionBottom

Indicates the toolbar is at the top of its containing view.

Available in iOS 5.0 through iOS 6.1.

Declared in UIToolbar.h.

UIToolbarPositionTop

Indicates the toolbar is at the bottom of its containing view.

Available in iOS 5.0 through iOS 6.1.

Declared in UIToolbar.h.

Special Considerations

In iOS 7.0 and later, these constants are defined in terms of UIBarPosition, which also introduces a new possible position: UIBarPositionTopAttached.