# Titanium.UI.Toolbar

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

- Source: https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.UI.Toolbar
- Titanium SDK version: 12.6.3
- Kind: view
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 6.2.0
- Extends: Titanium.UI.View
- Inheritance: Titanium.UI.View > Titanium.Proxy

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

To provide spacing between items in the toolbar, on iOS you can use the special 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 the iPhone and Android, 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`.

On Android a toolbar can also be used as an ActionBar for [activities](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md). This allows a toolbar to
inherit [ActionBar's](https://titaniumsdk.com/docs/sdk/Titanium.Android.ActionBar.md) methods, properties and events as well as provide a better customization of this
design element. For example you can provide your own images to be used as navigation button icon, overflow menu icon and logo.
In order to do that, an application must use a theme without a title bar. For Titanium 9.3.0 and higher,
set the theme to `Theme.Titanium.NoTitleBar`. For older Titanium versions, set the theme to `Theme.AppCompat.NoTitleBar`.

See also:

*  [Toolbar in the iOS Human Interface Guidelines.](https://developer.apple.com/ios/human-interface-guidelines/bars/toolbars/)

## 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'
});

var camera = Ti.UI.createButton({
    title: 'Camera'
});

var cancel = Ti.UI.createButton({
    title: 'Cancel'
});

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

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

## Example: Toolbar (iOS) 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.createToolbar({
    items: [send, flexSpace, camera, flexSpace, cancel],
    top: 20,
    extendBackground: true
});

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: Alloy Example (simple Toolbar)

Simple Toolbar example as an Alloy view.

``` xml
<Alloy>
    <Window>
        <Toolbar bottom="0">

            <!-- The Items tag sets the Toolbar.items property. -->
            <Items>
                <Button id="send" title="Send" />
                <Button id="camera" title="Camera" />
                <Button id="cancel" title="Cancel" />
            </Items>

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

## Example: Alloy Example (Toolbar as ActionBar)

Example how to set up Toolbar as an ActionBar

``` xml
<Alloy>
    <Window title="My Test App" backgroundColor="gray" customToolbar="toolbar">
        <Toolbar
            title="MyMenu"
            subtitle="Subtitle"
            width="Ti.UI.FILL"
            top="0"
            barColor="#639851"
            displayHomeAsUp="true"
            homeButtonEnabled="true"
            overflowIcon="logo.png">

            <!-- The Items tag sets the Toolbar.items property. -->
            <Items>
                <Button id="ok" title="OK"/>
                <Button id="cancel" title="Cancel"/>
            </Items>
        </Toolbar>

        <!-- The MenuItem's to be mapped to the toolbar -->
        <Menu>
            <MenuItem id="item1" title="Settings" showAsAction="Ti.Android.SHOW_AS_ACTION_NEVER"/>
            <MenuItem id="item2" title="Search" showAsAction="Ti.Android.SHOW_AS_ACTION_NEVER"/>
        </Menu>
    </Window>
</Alloy>
```

## Properties

### barColor

- Type: String | Titanium.UI.Color
- Platforms: Android, 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.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.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).

### contentInsetEndWithActions

- Type: Number
- Platforms: Android

Returns the margin after the toolbar's content when there are action buttons.

### contentInsetStartWithNavigation

- Type: Number
- Platforms: Android

Returns the margin at the toolbar's content start when there is a navigation button.

### extendBackground

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- 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.
and 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 and used as an ActionBar on Android for this
property to work as expected.
This **must** be specified at creation.

### items

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

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

### logo

- Type: String | Titanium.Blob | Titanium.Filesystem.File
- Platforms: Android

Image to be used as a logo in the Toolbar.

This property is used only when the Toolbar is used as an ActionBar.

### navigationIcon

- Type: String | Titanium.Blob | Titanium.Filesystem.File
- Platforms: Android

Image to be used for a navigation icon.

This property is used only when the Toolbar is used as an ActionBar.

### navigationIconColor

- Type: String
- Platforms: Android
- Since: Titanium SDK 12.1.0

Tint color of the navigation icon (e.g. home arrow)

### overflowIcon

- Type: String | Titanium.Blob | Titanium.Filesystem.File
- Platforms: Android

Image to be used for the overflow menu.

This property is used only when the Toolbar is used as an ActionBar.

### subtitle

- Type: String
- Platforms: Android

Text of the subtitle.

### subtitleTextColor

- Type: String
- Platforms: Android

Color for toolbar's subtitle

### title

- Type: String
- Platforms: Android

Text of the title.

### titleTextColor

- Type: String
- Platforms: Android

Color string with any Titanium supported format

### 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.Toolbar.md#barColor) is set to a semi-transparent or
transparent color.

## Methods

### collapseActionViews

- Platforms: Android

Collapses expanded ActionViews if there is any

### dismissPopupMenus

- Platforms: Android

Collapses expandend ActionViews and hides overflow menu

### getContentInsetEnd

- Platforms: Android

Returns the margin at the toolbar's content end.

Returns: Number

### getContentInsetLeft

- Platforms: Android

Returns the margin on the left of the toolbar's content.

Returns: Number

### getContentInsetRight

- Platforms: Android

Returns the margin on the right of the toolbar's content.

Returns: Number

### getContentInsetStart

- Platforms: Android

Returns the margin at the toolbar's content start.

Returns: Number

### getCurrentContentInsetEnd

- Platforms: Android

Returns the margin at the toolbar's content end that will be used with the current configuration of the toolbar.

Returns: Number

### getCurrentContentInsetLeft

- Platforms: Android

Returns the margin on the left of the toolbar's content that will be used with the current configuration of the toolbar.

Returns: Number

### getCurrentContentInsetRight

- Platforms: Android

Returns the margin on the right of the toolbar's content that will be used with the current configuration of the toolbar.

Returns: Number

### getCurrentContentInsetStart

- Platforms: Android

Returns the margin at the toolbar's content start that will be used with the current configuration of the toolbar.

Returns: Number

### hasExpandedActionView

- Platforms: Android

Checks if the toolbar is currently hosting an expanded action view.

Returns: Boolean

### hideOverflowMenu

- Platforms: Android

Hides the overflow menu if there is one.

### isOverflowMenuShowing

- Platforms: Android

Checks if the toolbar is currently hosting an expanded action view.

Returns: Boolean

### setContentInsetsAbsolute

- Platforms: Android

Sets the content margins of the toolbar

Parameters:

- `insetLeft` (Number): Offset at the left side of the content
- `insetRight` (Number): Offset at the right side of the content

### setContentInsetsRelative

- Platforms: Android

Sets the content margins relative to the layout direction

Parameters:

- `insetStart` (Number): Offset before the start of the content
- `insetEnd` (Number): Offset after the end of the content

### showOverflowMenu

- Platforms: Android

Shows the overflow menu if there is one

## Inherited members

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

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundGradient`, `backgroundImage`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `clearMotionEffects`, `click`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `elevation`, `filterTouchesWhenObscured`, `focus`, `focusable`, `getViewById`, `height`, `hiddenBehavior`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keepScreenOn`, `keypressed`, `left`, `longpress`, `opacity`, `overrideCurrentAnimation`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `singletap`, `size`, `stopAnimation`, `swipe`, `tintColor`, `toImage`, `tooltip`, `top`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transform`, `transitionName`, `translationX`, `translationY`, `translationZ`, `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`.