Titanium Mobile

# Titanium.UI.Toolbar

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

Availability
6.2.0
6.2.0
9.2.0
Extends
Titanium.UI.View

# Overview

A Toolbar is created by the Titanium.UI.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, Titanium.UI.iOS.SystemButton.FIXED_SPACE and Titanium.UI.iOS.SystemButton.FLEXIBLE_SPACE.

Note that toolbars are positioned like other views (using the top and bottom properties, for example), but the iOS Human Interface Guidelines (opens new window) 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 Titanium.Android.Activity. This allows a toolbar to inherit Titanium.Android.ActionBar 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:

# Examples

# Simple Toolbar

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

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();

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

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.

# Alloy Example (simple Toolbar)

Simple Toolbar example as an Alloy view.

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

# Alloy Example (Toolbar as ActionBar)

Example how to set up Toolbar as an ActionBar

<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

Availability
6.2.0
6.2.0
9.2.0
barColor :String | Titanium.UI.Color

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 property must be true.

To use a background gradient on a toolbar, barColor must be 'transparent' and the the translucent property must be true.

For information about color values, see the "Colors" section of Titanium.UI.

# contentInsetEndWithActions

Availability
6.2.0
contentInsetEndWithActions :Number

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

# contentInsetStartWithNavigation

Availability
6.2.0
contentInsetStartWithNavigation :Number

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

# extendBackground CREATION ONLY

Availability
6.2.0
6.2.0
9.2.0
extendBackground :Boolean

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.

Default: Undefined. Behaves as if set to false.

# items

Availability
6.2.0
6.2.0
9.2.0
items :Array<Titanium.UI.View>

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

Availability
6.2.0
logo :String | Titanium.Blob | Titanium.Filesystem.File

Image to be used as a logo in the Toolbar.

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

Availability
6.2.0
navigationIcon :String | Titanium.Blob | Titanium.Filesystem.File

Image to be used for a navigation icon.

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

# overflowIcon

Availability
6.2.0
overflowIcon :String | Titanium.Blob | Titanium.Filesystem.File

Image to be used for the overflow menu.

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

# subtitle

Availability
6.2.0
subtitle :String

Text of the subtitle.

# subtitleTextColor

Availability
6.2.0
subtitleTextColor :String

Color for toolbar's subtitle

# title

Availability
6.2.0
title :String

Text of the title.

# titleTextColor

Availability
6.2.0
titleTextColor :String

Color string with any Titanium supported format

# translucent

Availability
6.2.0
9.2.0
translucent :Boolean

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 is set to a semi-transparent or transparent color.

Default: true

# Methods

# collapseActionViews

Availability
6.2.0
collapseActionViews() → void

Collapses expanded ActionViews if there is any

Returns

Type
void

# dismissPopupMenus

Availability
6.2.0
dismissPopupMenus() → void

Collapses expandend ActionViews and hides overflow menu

Returns

Type
void

# getContentInsetEnd

Availability
6.2.0
getContentInsetEnd() → Number

Returns the margin at the toolbar's content end.

Returns

Type
Number

# getContentInsetLeft

Availability
6.2.0
getContentInsetLeft() → Number

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

Returns

Type
Number

# getContentInsetRight

Availability
6.2.0
getContentInsetRight() → Number

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

Returns

Type
Number

# getContentInsetStart

Availability
6.2.0
getContentInsetStart() → Number

Returns the margin at the toolbar's content start.

Returns

Type
Number

# getCurrentContentInsetEnd

Availability
6.2.0
getCurrentContentInsetEnd() → Number

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

Returns

Type
Number

# getCurrentContentInsetLeft

Availability
6.2.0
getCurrentContentInsetLeft() → Number

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

Returns

Type
Number

# getCurrentContentInsetRight

Availability
6.2.0
getCurrentContentInsetRight() → Number

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

Returns

Type
Number

# getCurrentContentInsetStart

Availability
6.2.0
getCurrentContentInsetStart() → Number

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

Returns

Type
Number

# hasExpandedActionView

Availability
6.2.0
hasExpandedActionView() → Boolean

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

Returns

Type
Boolean

# hideOverflowMenu

Availability
6.2.0
hideOverflowMenu() → void

Hides the overflow menu if there is one.

Returns

Type
void

# isOverflowMenuShowing

Availability
6.2.0
isOverflowMenuShowing() → Boolean

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

Returns

Type
Boolean

# setContentInsetsAbsolute

Availability
6.2.0
setContentInsetsAbsolute(insetLeft, insetRight) → void

Sets the content margins of the toolbar

Parameters

Name Type Description
insetLeft Number

Offset at the left side of the content

insetRight Number

Offset at the right side of the content

Returns

Type
void

# setContentInsetsRelative

Availability
6.2.0
setContentInsetsRelative(insetStart, insetEnd) → void

Sets the content margins relative to the layout direction

Parameters

Name Type Description
insetStart Number

Offset before the start of the content

insetEnd Number

Offset after the end of the content

Returns

Type
void

# showOverflowMenu

Availability
6.2.0
showOverflowMenu() → void

Shows the overflow menu if there is one

Returns

Type
void

Contents