# Titanium.UI.Tab

A tab instance for a Titanium.UI.TabGroup.

Availability

0.8

9.2.0

Extends

Titanium.UI.View

# Overview

A TabGroup tab instance. Each tab includes a button and one or more windows, which holds the "contents" of the tab. Users can select a tab by clicking on the tab button.

Use the Titanium.UI.createTab method or <Tab> Alloy element to create a tab.

Use Titanium.UI.TabGroup.setActiveTab to switch between tabs in a tab group.

The behavior of tabs and tab groups follows the platform's native navigation style, which varies significantly between platforms.

# iOS Platform Implementation Notes

On iOS, the tab maintains a stack of windows. Windows on top of the stack can partially or totally obscure windows lower in the stack. Calling Titanium.UI.Tab.open opens a new window on top of the window stack. When a window is closed, either by the user or by code, the window is removed from the stack, making the previous window visible. The root tab window cannot be removed.

On iOS the tab controls are generally kept on screen to allow a user to navigate inside the app. Tab controls are hidden when the user is performing a modal task (for example, composing a message). In this case, the app should provide a button in the navigation bar to return to the previous screen. On iOS, the window should also be opened as modal. On iOS, The tab controls can also be hidden by opening the new window with Titanium.UI.Window.tabBarHidden set to true.

When closing a tab window in iOS, you should always use the Titanium.UI.Tab.close method to ensure that the tab group maintains its navigation state.

# Android Platform Implementation Notes

On Android, the tab does not maintain a stack of windows. Calling Titanium.UI.Tab.open opens a new, heavyweight window, which by default covers the tab group entirely. This seems quite different from the iOS model, but it is the standard model for Android applications. Users can use the Back button to close the window and return to the tab group.

On Android, tab windows can be closed using either Titanium.UI.Tab.close or Titanium.UI.Window.close. Since no window stack is maintained, only a single window opened using Titanium.UI.Tab.open can be closed using Tab.close.

As on iOS, the root tab window cannot be closed.

# Examples

# Simple Tab Example

In this example, we create a simple tab and add it to a tab group.

var window = Ti.UI.createWindow({
    title: 'My Tab'
});

var tab = Ti.UI.createTab({
    window: window,
    title: 'My Tab',
    icon: 'myicon.png'
});

tabGroup.addTab(tab);

# Alloy XML Markup

Previous example an an Alloy view.

<Alloy>
    <TabGroup id="tabGroup">
        <Tab id="tab" title="My Tab" icon="myicon.png">
            <Window id="window" title="My Tab" />
        </Tab>
      </TabGroup>
</Alloy>

# Properties

# active

Availability

0.8

9.2.0

active :Boolean

true if this tab is active, false if it is not.

The tab can be activated by setting the property, but since this property is platform-specific, using setActiveTab is recommended instead.

# activeIcon

Availability

3.1.0

9.2.0

activeIcon :String

Icon URL for this tab when active.

If unspecified, iOS uses a tint color to indicate the active tab. See icon for more information.

If the icon provided is larger than [30 pixels (60 pixels for retina, 90 pixels for super-retina)] (https://developer.apple.com/ios/human-interface-guidelines/icons-and-images/image-size-and-resolution/), this image will be scaled to fit.

# activeIconIsMask

Availability

3.1.3

9.2.0

activeIconIsMask :Boolean

Defines if the active icon property of the tab must be used as a mask.

This is the equivalent of the iconIsMask property, but for the active icon. When this is true, the active icon is tinted with the color specified in tabsTintColor. When this is false the image is rendered as is, though the title of the tab is still tinted.

Default: true

# activeTintColor

Availability

9.0.3

0.8

9.2.0

activeTintColor :String

Defines the color of the tab icon when it is active.

# activeTitleColor

Availability

8.0.0

4.1.0

9.2.0

activeTitleColor :String | Titanium.UI.Color

Defines the color of the title of tab when it's active.

The color of the title of the tab when it's active.

# backgroundColor

Availability

3.0.0

backgroundColor :String | Titanium.UI.Color

Sets the color of the tab when it is inactive.

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

# backgroundFocusedColor

Availability

3.0.0

backgroundFocusedColor :String

Sets the color of the tab when it is focused.

On the Android platform, this sets the color of the active tab and is only supported by TABS_STYLE_BOTTOM_NAVIGATION.

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

# badge

Availability

9.3.0

0.8

9.2.0

badge :String

Badge value for this tab. null indicates no badge.

On the Android platform you will need to use a Theme with parent="Theme.MaterialComponents.*" in order to use a badge. You have to pass a number as a string. Non-numberic characters will not be displayed.

On iOS, a badge will only be shown if the tab has been assigned an icon. Text only tabs do not support badges.

# badgeColor

Availability

9.3.0

6.1.0

9.2.0

badgeColor :String | Titanium.UI.Color

If this item displays a badge, this color will be used for the badge's background. If set to null, the default background color will be used instead.

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

# icon

Availability

0.8

9.2.0

icon :String

Icon URL for this tab.

# iOS Tab Icons

On iOS, tab icons are usually white with a transparent background. The system uses a transparent tint color to indicate whether the tab is active or inactive. In the inactive state, the tint color is based on the tab bar's color tabsBackgroundColor, which defaults to black. In the active state, the tint color is usually blue. Prior to Titanium 3.1, there was no way to override the default active icon tint.

Some icon-related features:

You can specify the active tab's tint color as activeTabIconTint.
You can set separate icon images for the active and inactive states. If activeIcon is set, then icon is used in the inactive state, and activeIcon is used in the active state. No default tint is applied to either icon.

# iconInsets

Availability

5.2.0

9.2.0

iconInsets :TabIconInsets

The icon inset or outset for each edge.

Use this property for example to center an icon without providing a title. To do that, set the insets to { top: 6 } and/or { left: 6 }. The right and bottom are calculated internally to prevent the icon from mutating.

Default: All insets are zero.

# iconIsMask

Availability

3.1.3

9.2.0

iconIsMask :Boolean

Defines if the icon property of the tab must be used as a mask.

When this property is true, the color data of the image specified as the icon is ignored and the image is used as an alpha mask. When this is false, the color data of the image is preserved.

Default: true

# tintColor

Availability

9.0.3

3.1.3

9.2.0

tintColor :String

Defines the color of the tab icon.

This property is a direct correspondant of the tintColor property of UIView on iOS. If no value is specified, the tintColor of the View is inherited from its superview.

Default: null

# title

Availability

0.8

9.2.0

title :String

Title for this tab.

# titleColor

Availability

8.0.0

4.1.0

9.2.0

titleColor :String | Titanium.UI.Color

Defines the color of the title of tab when it's inactive.

The color of the title of the tab when it's inactive.

# titleid

Availability

0.8

9.2.0

titleid :String

Key identifying a string from the locale file to use for the tab title. Only one of title or titleid should be specified.

# window CREATION ONLY

Availability

0.8

9.2.0

window :Titanium.UI.Window

Root-level tab window. All tabs must have at least one root-level tab window.

# Methods

# close

Availability

0.8

9.2.0

close(window[, options]) → void

Closes the top-level window for this tab.

On iOS, this method should be used when closing a window opened from a tab, to correctly maintain the iOS tab group's navigation state. Note that the window to be closed must be passed in as a parameter:

myTab.close(tabWin);

On Android, this method does not take a window parameter.

myTab.close();

On Android, if a window has been opened in front of the tab using Tab.open, a subsequent call to Tab.close is equivalent to calling close on that window. No window stack is maintained, so only the most-recently opened window on a given tab can be closed in this way.

All platforms accept an optional options parameter. The only supported property for this dictionary is the animated flag, which specifies whether the window close should be animated. animated is true by default.

Parameters

Name	Type	Description
`window`	Titanium.UI.Window	Window to close. This parameter must be omitted on Android.
`options`	Object	Dictionary of display and animation settings to use when closing the window. Identical to the `options` parameter to close. iOS only supports the animated parameter.

Returns

Type: void

# open

Availability

0.8

9.2.0

open(window[, options]) → void

Opens a new window.

On iOS, the new window is opened as the top window in the tab's window stack. On Android, the new window is opened as a new, heavyweight window, obscuring the tab group.

Parameters

Name	Type	Description
`window`	Titanium.UI.Window	Window to open.
`options`	openWindowParams	Dictionary of display and animation settings to use when opening the window. Identical to the `options` parameter to open. iOS only supports the animated parameter.

Returns

Type: void

# popToRootWindow

Availability

6.2.0

9.2.0

popToRootWindow([options]) → void

Closes all windows that are currently opened inside the tab.

Note that only the close event of the most recently opened window is fired.

Parameters

Name	Type	Description
`options`	AnimatedOptions	Options supporting a single `animated` boolean property to determine whether the windows will be animated while being closed (default: false).

Returns

Type: void

# setWindow DEPRECATED

Availability

0.8

9.2.0

setWindow(window) → void

DEPRECATED SINCE 10.0.0

Set the value of the window property directly.

Sets the root window that appears in the tab.

You can only use this method to set the tab's root window before the TabGroup containing this tab is openened, that is, once the TabGroup is displayed, you cannot change the root window that appears in the tab.

Parameters

Name	Type	Description
`window`	Titanium.UI.Window	Root window of the tab.

Returns

Type: void

# Events

# click

Availability

0.9

9.2.0

Fired when this tab is clicked in the tab group.

There is a subtle difference between singletap and click events.

A singletap event is generated when the user taps the screen briefly without moving their finger. This gesture will also generate a click event.

However, a click event can also be generated when the user touches, moves their finger, and then removes it from the screen.

On Android, a click event can also be generated by a trackball click.

Properties

Name	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.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# focus DEPRECATED

Availability

0.9

0.8

DEPRECATED SINCE 5.2.0

Use selected event instead.

Fired when the tab gains focus.

This event only fires when using the trackball to navigate.

Properties

Name	Type	Description
index	Number	Index of the current active tab.
previousIndex	Number	Index of the previous active tab.
tab	Titanium.UI.Tab	Current active tab object.
previousTab	Titanium.UI.Tab	Previous active tab object.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# blur DEPRECATED

Availability

0.8

DEPRECATED SINCE 5.2.0

Use unselected event instead.

Fired when the tab loses focus.

Properties

Name	Type	Description
index	Number	Index of the current active tab.
previousIndex	Number	Index of the previous active tab.
tab	Titanium.UI.Tab	Current active tab object.
previousTab	Titanium.UI.Tab	Previous active tab object.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# unselected

Availability

3.5.1

5.2.0

9.2.0

Fired when the tab is no longer selected.

Properties

Name	Type	Description
index	Number	Index of the current active tab.
previousIndex	Number	Index of the previous active tab.
tab	Titanium.UI.Tab	Current active tab object.
previousTab	Titanium.UI.Tab	Previous active tab object.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# selected

Availability

3.5.1

5.2.0

9.2.0

Fired when the tab is selected.

Properties

Name	Type	Description
index	Number	Index of the current active tab.
previousIndex	Number	Index of the previous active tab.
tab	Titanium.UI.Tab	Current active tab object.
previousTab	Titanium.UI.Tab	Previous active tab object.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.