# Titanium.UI.iOS.Toolbar

> An iOS toolbar, which can contain buttons and certain other controls.

- Source: https://titaniumsdk.com/docs/sdk/12.6.2/Titanium.UI.iOS.Toolbar
- Titanium SDK version: 12.6.2
- Kind: view
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK iPhone 0.8, iPad 0.8, macOS 9.2.0
- Extends: Titanium.UI.View
- Inheritance: Titanium.UI.View > Titanium.Proxy
- DEPRECATED since 6.2.0, removed in 10.0.0. Use the cross-platform [Titanium.UI.Toolbar](Titanium.UI.Toolbar) instead.

A `Toolbar` is created by the [Titanium.UI.iOS.createToolbar](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#createToolbar) factory method or **`<Toolbar>`** Alloy element.

A `Toolbar` can contain buttons, as well as certain other widgets, including text fields and
labels.

To provide spacing between items in the toolbar, you can use the special iOS system button types,
[FIXED_SPACE](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.SystemButton.md#FIXED_SPACE) and
[FLEXIBLE_SPACE](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.SystemButton.md#FLEXIBLE_SPACE).

Note that toolbars are positioned like other views (using the `top` and `bottom` properties,
for example), but the [iOS Human Interface Guidelines](https://developer.apple.com/ios/human-interface-guidelines/overview/themes/#//apple_ref/doc/uid/TP40006556-CH12-SW4)
have specific requirements for placing toolbars, specifically:

* On iPhone, a toolbar should be at the bottom of the window.
* On the iPad, a toolbar should appear at the top or bottom of a window.

Due to an iOS limitation, the buttons in the toolbar only support the `click` event.
The native object underlying a toolbar button does not generate standard view events,
such as `touchstart` and `touchend`.

**Note**:
This API has been deprecated in Titanium SDK 6.2.0 in favor of the cross-platform
UI component [Titanium.UI.Toolbar](https://titaniumsdk.com/docs/sdk/Titanium.UI.Toolbar.md) that can also be used on Android. The API itself
did not change, so it is a drop-in replacement for existing usages. This deprecated
API will be removed in Titanium SDK 8.0.0 and later.

See also:

*  [Toolbar in the iOS Human Interface Guidelines.](https://developer.apple.com/ios/human-interface-guidelines/overview/themes/#//apple_ref/doc/uid/TP40006556-CH12-SW4)

## Example: Simple Toolbar

The following code excerpt creates a simple toolbar, placed at the bottom of the window.

``` js
var win = Ti.UI.createWindow({
    backgroundColor: 'white'
});

var send = Ti.UI.createButton({
    title: 'Send',
    style: Ti.UI.iOS.SystemButtonStyle.DONE,
});

var camera = Ti.UI.createButton({
    systemButton: Ti.UI.iOS.SystemButton.CAMERA,
});

var cancel = Ti.UI.createButton({
    systemButton: Ti.UI.iOS.SystemButton.CANCEL
});

var flexSpace = Ti.UI.createButton({
    systemButton: Ti.UI.iOS.SystemButton.FLEXIBLE_SPACE
});

var toolbar = Titanium.UI.iOS.createToolbar({
    items: [send, flexSpace, camera, flexSpace, cancel],
    bottom: 0
});

win.add(toolbar);
win.open();
```

Note the use of the flexible space for positioning the toolbar buttons -- the
`FLEXIBLE_SPACE` button doesn't appear as a button, but a variable space between the
controls on either side of it. Available space in the toolbar is divided between all of the
flexible space buttons in the toolbar. Without the flexible spaces in this example,
the toolbar buttons would be grouped tightly together on the left side of the toolbar.

## Example: Toolbar with extended background

The following code excerpt creates a simple toolbar, placed at the top of the window which extends its background under the status bar. 

``` js
var win = Ti.UI.createWindow({
    backgroundColor: 'white'
});

var send = Ti.UI.createButton({
    title: 'Send',
    style: Ti.UI.iOS.SystemButtonStyle.DONE,
});

var camera = Ti.UI.createButton({
    systemButton: Ti.UI.iOS.SystemButton.CAMERA,
});

var cancel = Ti.UI.createButton({
    systemButton: Ti.UI.iOS.SystemButton.CANCEL
});

flexSpace = Ti.UI.createButton({
    systemButton: Ti.UI.iOS.SystemButton.FLEXIBLE_SPACE
});

var toolbar = Ti.UI.iOS.createToolbar({
    items: [send, flexSpace, camera, flexSpace, cancel],
    top: 20,
    extendBackground: true
});

win.add(toolbar);
win.open();
```

## Example: Alloy XML Markup

Simple Toolbar example as an Alloy view.

``` js
<Alloy>
    <Window id="win">
        <Toolbar platform="ios" bottom="0">

            <!-- The Items tag sets the Toolbar.items property. -->
            <Items>
                <Button id="send" title="Send" style="DONE" />
                <FlexSpace/>
                <Button id="camera" systemButton="CAMERA" />
                <FlexSpace/>
                <Button id="cancel" systemButton="CANCEL" />
            </Items>

            <!-- Place additional views for the Toolbar here -->

        </Toolbar>
    </Window>
</Alloy>
```

## Properties

### barColor

- Type: String | Titanium.UI.Color
- Platforms: iPhone, iPad, macOS

Background color for the toolbar, as a color name or hex triplet.

To use a background image on the toolbar, either `barColor` must be a fully or
partially transparent color,
or the [translucent](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.Toolbar.md#translucent) property must be `true`.

To use a background gradient on a toolbar, `barColor` must be `'transparent'`
*and* the the [translucent](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.Toolbar.md#translucent) property must be `true`.

For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### extendBackground

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK iPhone 3.3.0, iPad 3.3.0, macOS 9.2.0
- Default: `Undefined. Behaves as if set to false.`

If `true`, the background of the toolbar extends upwards.

This property allows the user to specify that the toolbar's background show through the status bar. This property is 
only intended to be used with toolbars hosted in windows with **no navigation controllers**. The toolbar must be placed at the
top of the screen just below the status bar for this property to work as expected. This **must** be specified at creation.

### items

- Type: Array<Titanium.UI.View>
- Platforms: iPhone, iPad, macOS

An array of buttons (or other widgets) contained in the toolbar.

### translucent

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `true`

If `true`, a translucent background color is used for the toolbar.

Note that if `translucent` is `false`, views under the toolbar are hidden, even
if [barColor](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.Toolbar.md#barColor) is set to a semi-transparent or
transparent color.

## Inherited members

65 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.2/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/12.6.2/Titanium.UI.View.md): `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundGradient`, `backgroundImage`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `clearMotionEffects`, `click`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `getViewById`, `height`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keypressed`, `left`, `longpress`, `opacity`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotation`, `show`, `singletap`, `size`, `swipe`, `tintColor`, `toImage`, `tooltip`, `top`, `touchEnabled`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transform`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.