iOS Developer Library

Developer

UIKit Framework Reference UIToolbar Class Reference

Options
Deployment Target:

On This Page
Language:

UIToolbar

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.

Inheritance


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.
  • items items Property

    The items displayed on the toolbar.

    Declaration

    Swift

    var items: [AnyObject]?

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sets the items on the toolbar by animating the changes.

    Declaration

    Swift

    func setItems(_ items: [AnyObject]?, animated animated: Bool)

    Objective-C

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

    Parameters

    items

    The items to display on the toolbar.

    animated

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

    Discussion

    If animated is YEStrue, 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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    items

  • barStyle barStyle Property

    The toolbar style that specifies its appearance.

    Declaration

    Swift

    var barStyle: UIBarStyle

    Objective-C

    @property(nonatomic) UIBarStyle barStyle

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The tint color to apply to the toolbar background.

    Declaration

    Swift

    var barTintColor: UIColor?

    Objective-C

    @property(nonatomic, retain) UIColor *barTintColor

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • tintColor tintColor Property

    The tint color to apply to the bar button items.

    Declaration

    Swift

    var tintColor: UIColor!

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value that indicates whether the toolbar is translucent (YEStrue) or not (NOfalse).

    Declaration

    Swift

    var translucent: Bool

    Objective-C

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

    Discussion

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

    If you set this property to YEStrue 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 NOfalse 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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func backgroundImageForToolbarPosition(_ topOrBottom: UIBarPosition, barMetrics barMetrics: UIBarMetrics) -> UIImage?

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func setBackgroundImage(_ backgroundImage: UIImage?, forToolbarPosition topOrBottom: UIBarPosition, barMetrics barMetrics: UIBarMetrics)

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func shadowImageForToolbarPosition(_ topOrBottom: UIBarPosition) -> UIImage?

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func setShadowImage(_ shadowImage: UIImage?, forToolbarPosition topOrBottom: UIBarPosition)

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • delegate delegate Property

    The toolbar’s delegate object.

    Declaration

    Swift

    unowned(unsafe) var delegate: UIToolbarDelegate?

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Use UIBarPosition instead.

    Declaration

    Objective-C

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

    Constants

    • UIToolbarPositionAny

      UIToolbarPositionAny

      Indicates the toolbar may be in any position.

      Available in iOS 5.0 through iOS 6.1.

    • UIToolbarPositionBottom

      UIToolbarPositionBottom

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

      Available in iOS 5.0 through iOS 6.1.

    • UIToolbarPositionTop

      UIToolbarPositionTop

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

      Available in iOS 5.0 through iOS 6.1.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 5.0 through iOS 6.1.