Titanium.UI.Toolbar

viewAndroidiPhoneiPadmacOSsince 6.2.0

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

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, FIXED_SPACE and FLEXIBLE_SPACE.

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

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.BUTTON_STYLE_OPTION_POSITIVE,
});

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 73

accessibilityDisableLongPress

BooleanAndroidsince 12.4.0

Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

Parameters	Type	Description
animation	Titanium.UI.Animation \| Dictionary<Titanium.UI.Animation>	Either a dictionary of animation properties or an Animation object.
callback?	Callback<Object>	Function to be invoked upon completion of the animation.

Parameters	Type	Description
point	Point	A point in this view's coordinate system. If this argument is missing an `x` or `y` property, or the properties can not be converted into numbers, an exception will be raised.
destinationView	Titanium.UI.View	View that specifies the destination coordinate system to convert to. If this argument is not a view, an exception will be raised.

Parameters	Type	Description
insetLeft	Number	Offset at the left side of the content
insetRight	Number	Offset at the right side of the content

Parameters	Type	Description
insetStart	Number	Offset before the start of the content
insetEnd	Number	Offset after the end of the content

Parameters	Type	Description
callback?	Callback<Titanium.Blob>	Function to be invoked upon completion. If non-null, this method will be performed asynchronously. If null, it will be performed immediately.
honorScaleFactor?	Boolean	Determines whether the image is scaled based on scale factor of main screen. (iOS only) When set to true, image is scale factor is honored. When set to false, the image in the blob has the same dimensions for retina and non-retina devices.

Event properties	Type	Description
x	Number	X coordinate of the event from the `source` view's coordinate system.
y	Number	Y coordinate of the event from the `source` view's coordinate system.
obscured	Boolean	Returns `true` if the click passed through an overlapping window belonging to another app. This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Event properties	Type	Description
scale	Number	The scale factor relative to the points of the two touches in screen coordinates.
velocity	Number	The velocity of the pinch in scale factor per second.
time	Number	The event time of the current event being processed.
timeDelta	Number	The time difference in milliseconds between the previous accepted scaling event and the current scaling event.
currentSpan	Number	The average distance between each of the pointers forming the gesture in progress through the focal point.
currentSpanX	Number	The average X distance between each of the pointers forming the gesture in progress through the focal point.
currentSpanY	Number	The average Y distance between each of the pointers forming the gesture in progress through the focal point.
previousSpan	Number	The previous average distance between each of the pointers forming the gesture in progress through the focal point.
previousSpanX	Number	The previous average X distance between each of the pointers forming the gesture in progress through the focal point.
previousSpanY	Number	The previous average Y distance between each of the pointers forming the gesture in progress through the focal point.
focusX	Number	The X coordinate of the current gesture's focal point.
focusY	Number	The Y coordinate of the current gesture's focal point.
inProgress	Boolean	Returns `true` if a scale gesture is in progress, `false` otherwise.

Event properties	Type	Description
direction	String	Direction of the swipe--either 'left', 'right', 'up', or 'down'.
x	Number	X coordinate of the event's endpoint from the `source` view's coordinate system.
y	Number	Y coordinate of the event's endpoint from the `source` view's coordinate system.
obscured	Boolean	Returns `true` if the swipe passed through an overlapping window belonging to another app. This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Examples

Simple Toolbar

Toolbar (iOS) with extended background

Alloy Example (simple Toolbar)

Alloy Example (Toolbar as ActionBar)

Properties 73

Linear and Radial Gradients

Methods 29

Events 15