UIToolbar Class Reference

Inherits from
UIView : UIResponder : NSObject
Conforms to
NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
View Programming Guide for iOS
Declared in
UIToolbar.h
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. For example, the image is converted to white and then bevelled by adding a shadow for the normal state.

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.

Tasks

Configuring the Toolbar

Configuring Toolbar Items

Customizing Appearance

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

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.
See Also
Related Sample Code
Declared In
UIToolbar.h

tintColor

The color used to tint the bar.

@property(nonatomic, retain) UIColor *tintColor
Discussion

The default value is nil.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
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

Applying translucence to a toolbar is intended primarily for landscape orientation, when you want the user to be able to view the area beneath the toolbar. The default value for this property is NO. However, if you set the toolbar style to UIBarStyleBlackTranslucent, the value for this property is always YES.

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:(UIToolbarPosition)topOrBottom barMetrics:(UIBarMetrics)barMetrics
Parameters
topOrBottom

A toolbar position constant.

barMetrics

A bar metrics constant.

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.
See Also
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:(UIToolbarPosition)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.
See Also
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:(UIToolbarPosition)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.
See Also
Declared In
UIToolbar.h

shadowImageForToolbarPosition:

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

- (UIImage *)shadowImageForToolbarPosition:(UIToolbarPosition)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.
See Also
Declared In
UIToolbar.h

Constants

UIToolbarPosition

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

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

Indicates the toolbar may be in any position.

Available in iOS 5.0 and later.

Declared in UIToolbar.h.

UIToolbarPositionBottom

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

Available in iOS 5.0 and later.

Declared in UIToolbar.h.

UIToolbarPositionTop

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

Available in iOS 5.0 and later.

Declared in UIToolbar.h.



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

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