Titanium.UI.Tab

Object of Titanium.UI.

Platform	Since
Android	0.8
iPhone	0.8
iPad	0.8
Mobile Web	1.8

Summary

A tab instance for a TabGroup.

Description

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 TabGroup.setActiveTab to switch between tabs in a tab group. The Titanium.UI.currentTab property provides a global reference to the currently active tab. Use the Titanium.UI.createTab method to create a tab.

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 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 open the new window as modal and provide a button in the navigation bar to return to the previous screen. The tab controls can also be hidden by opening the new window with tabBarHidden set to true.

When closing a tab window in iOS, you should always use the 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 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 Tab.close or Window.close. Since no window stack is maintained, only a single window opened using Tab.open can be closed using Tab.close.

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

Mobile Web Platform Implementation Notes

On Mobile Web, the tab maintains a stack of windows, as on iOS. However, the tab controls are always hidden by the window, and the user can use the browser's back button to close the window.

On Mobile Web, Tab windows can be closed using either Tab.close or Window.close.

On Mobile Web, the root tab window can be closed. If the root tab window is closed, the tab group's background color becomes visible where the window used to be. If the tab group doesn't have a background color set, whatever is underneath the tab group becomes visible.

Code Examples

Simple Tab Example

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

var tab = Titanium.UI.createTab({
    window:mywin,
    title:'Hello',
    icon:'myicon.png'
});
tabGroup.addTab(tab);

Methods

Name	Summary
add	Adds a child to this view's hierarchy.
addEventListener	Adds the specified callback as an event listener for the named event.
animate	Animates this view.
close	Closes the top-level window for this tab.
convertPointToView	Translates a point from this view's coordinate system to another view's coordinate system. (Android, iPhone, iPad only.)
fireEvent	Fires a synthesized event to any registered listeners.
getActive	Gets the value of the active property. (iPhone, iPad only.)
getAnchorPoint	Gets the value of the anchorPoint property. (iPhone, iPad only.)
getAnimatedCenterPoint	Gets the value of the animatedCenterPoint property. (Android, iPhone, iPad only.)
getBackgroundColor	Gets the value of the backgroundColor property.
getBackgroundDisabledColor	Gets the value of the backgroundDisabledColor property. (Android only.)
getBackgroundDisabledImage	Gets the value of the backgroundDisabledImage property. (Android only.)
getBackgroundFocusedColor	Gets the value of the backgroundFocusedColor property. (Android only.)
getBackgroundFocusedImage	Gets the value of the backgroundFocusedImage property. (Android only.)
getBackgroundGradient	Gets the value of the backgroundGradient property. (iPhone, iPad, Mobile Web only.)
getBackgroundImage	Gets the value of the backgroundImage property.
getBackgroundLeftCap	Gets the value of the backgroundLeftCap property. (iPhone, iPad only.)
getBackgroundRepeat	Gets the value of the backgroundRepeat property. (iPhone, iPad only.)
getBackgroundSelectedColor	Gets the value of the backgroundSelectedColor property. (Android, Mobile Web only.)
getBackgroundSelectedImage	Gets the value of the backgroundSelectedImage property. (Android, Mobile Web only.)
getBackgroundTopCap	Gets the value of the backgroundTopCap property. (iPhone, iPad only.)
getBadge	Gets the value of the badge property. (iPhone, iPad only.)
getBorderColor	Gets the value of the borderColor property.
getBorderRadius	Gets the value of the borderRadius property.
getBorderWidth	Gets the value of the borderWidth property.
getBottom	Gets the value of the bottom property.
getCenter	Gets the value of the center property.
getChildren	Gets the value of the children property.
getFocusable	Gets the value of the focusable property. (Android only.)
getHeight	Gets the value of the height property.
getIcon	Gets the value of the icon property.
getKeepScreenOn	Gets the value of the keepScreenOn property. (Android only.)
getLayout	Gets the value of the layout property.
getLeft	Gets the value of the left property.
getOpacity	Gets the value of the opacity property.
getRight	Gets the value of the right property.
getSize	Gets the value of the size property.
getSoftKeyboardOnFocus	Gets the value of the softKeyboardOnFocus property. (Android only.)
getTitle	Gets the value of the title property.
getTitleid	Gets the value of the titleid property.
getTop	Gets the value of the top property.
getTouchEnabled	Gets the value of the touchEnabled property.
getTransform	Gets the value of the transform property.
getVisible	Gets the value of the visible property.
getWidth	Gets the value of the width property.
getWindow	Gets the value of the window property.
getZIndex	Gets the value of the zIndex property.
hide	Hides this view.
open	Opens a new window.
remove	Removes a child view from this view's hierarchy.
removeEventListener	Removes the specified callback as an event listener for the named event.
setActive	Sets the value of the active property. (iPhone, iPad only.)
setAnchorPoint	Sets the value of the anchorPoint property. (iPhone, iPad only.)
setBackgroundColor	Sets the value of the backgroundColor property.
setBackgroundDisabledColor	Sets the value of the backgroundDisabledColor property. (Android only.)
setBackgroundDisabledImage	Sets the value of the backgroundDisabledImage property. (Android only.)
setBackgroundFocusedColor	Sets the value of the backgroundFocusedColor property. (Android only.)
setBackgroundFocusedImage	Sets the value of the backgroundFocusedImage property. (Android only.)
setBackgroundGradient	Sets the value of the backgroundGradient property. (iPhone, iPad, Mobile Web only.)
setBackgroundImage	Sets the value of the backgroundImage property.
setBackgroundLeftCap	Sets the value of the backgroundLeftCap property. (iPhone, iPad only.)
setBackgroundRepeat	Sets the value of the backgroundRepeat property. (iPhone, iPad only.)
setBackgroundSelectedColor	Sets the value of the backgroundSelectedColor property. (Android, Mobile Web only.)
setBackgroundSelectedImage	Sets the value of the backgroundSelectedImage property. (Android, Mobile Web only.)
setBackgroundTopCap	Sets the value of the backgroundTopCap property. (iPhone, iPad only.)
setBadge	Sets the value of the badge property. (iPhone, iPad only.)
setBorderColor	Sets the value of the borderColor property.
setBorderRadius	Sets the value of the borderRadius property.
setBorderWidth	Sets the value of the borderWidth property.
setBottom	Sets the value of the bottom property.
setCenter	Sets the value of the center property.
setFocusable	Sets the value of the focusable property. (Android only.)
setHeight	Sets the value of the height property.
setIcon	Sets the value of the icon property.
setKeepScreenOn	Sets the value of the keepScreenOn property. (Android only.)
setLayout	Sets the value of the layout property.
setLeft	Sets the value of the left property.
setOpacity	Sets the value of the opacity property.
setRight	Sets the value of the right property.
setSoftKeyboardOnFocus	Sets the value of the softKeyboardOnFocus property. (Android only.)
setTitle	Sets the value of the title property.
setTitleid	Sets the value of the titleid property.
setTop	Sets the value of the top property.
setTouchEnabled	Sets the value of the touchEnabled property.
setTransform	Sets the value of the transform property.
setVisible	Sets the value of the visible property.
setWidth	Sets the value of the width property.
setWindow	Sets the value of the window property.
setZIndex	Sets the value of the zIndex property.
show	Makes this view visible.
toImage	Returns an image of the rendered view, as a Blob. (Android, iPhone, iPad only.)

Properties

Name	Type	Summary
active	Boolean	`true` if this tab is active, `false` if it is not. (iPhone, iPad only.)
anchorPoint	`Point`	Anchor point where animation should occur, relative to the view's boundaries. (iPhone, iPad only.)
animatedCenterPoint	`Point`	Current position of the view during an animation. (Android, iPhone, iPad only.) read-only
backgroundColor	String	Background color of the view.
backgroundDisabledColor	String	Disabled background color of the view. (Android only.)
backgroundDisabledImage	String	Disabled background image for the view, specified as a local file path or URL. (Android only.)
backgroundFocusedColor	String	Focused background color of the view. (Android only.)
backgroundFocusedImage	String	Focused background image for the view, specified as a local file path or URL. (Android only.)
backgroundGradient	`Gradient`	A background gradient for the view. (iPhone, iPad, Mobile Web only.)
backgroundImage	String	Background image for the view, specified as a local file path or URL.
backgroundLeftCap	Number	Size of the left end cap. (iPhone, iPad only.)
backgroundRepeat	Boolean	Toggle for whether or not to tile a background across a view. (iPhone, iPad only.)
backgroundSelectedColor	String	Selected background color of the view. (Android, Mobile Web only.)
backgroundSelectedImage	String	Selected background image url for the view, specified as a local file path or URL. (Android, Mobile Web only.)
backgroundTopCap	Number	Size of the top end cap. (iPhone, iPad only.)
badge	String	Badge value for this tab. `null` indicates no badge. (iPhone, iPad only.)
borderColor	String	Border color of the view.
borderRadius	Number	Border radius of the view.
borderWidth	Number	Border width of the view.
bottom	Number or String	View's bottom position, in platform-specific units.
center	`Point`	View's center position, in the parent view's coordinates.
children	Array<`Titanium.UI.View`>	Array of this view's child views. read-only
focusable	Boolean	Whether view should be focusable while navigating with the trackball. (Android only.)
height	Number or String	View height, in platform-specific units.
icon	String	Icon URL for this tab.
keepScreenOn	Boolean	Whether to keep the device screen on. (Android only.)
layout	String	Specifies how the view positions its children. One of: 'absolute', 'vertical', or 'horizontal'.
left	Number or String	View's left position, in platform-specific units.
opacity	Number	Opacity of this view, from 0.0 (transparent) to 1.0 (opaque).
right	Number or String	View's right position, in platform-specific units.
size	Object	Rendered size of the view as a dictionary of width and height properties. read-only
softKeyboardOnFocus	Number	Determines keyboard behavior when this view is focused. (Android only.)
title	String	Title for this tab.
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.
top	Number or String	The view's top position.
touchEnabled	Boolean	Whether view should receive touch events.
transform	`Titanium.UI.2DMatrix` or `Titanium.UI.iOS.3DMatrix`	Transformation matrix to apply to the view.
visible	Boolean	Boolean value indicating whether the view is visible.
width	Number or String	View's width, in platform-specific units.
window	`Titanium.UI.Window`	Root level tab window. All tabs must have at least one root level tab window.
zIndex	Number	Z index position relative to other sibling views.

Events

Name	Summary
blur	Fired when the tab loses focus.
click	Fired when this tab is clicked in the tab group.
dblclick	Fired when the device detects a double click against the view.
doubletap	Fired when the device detects a double tap against the view. (Android, iPhone, iPad only.)
focus	Fired when the tab gains focus.
longclick	Fired when the device detects a long click. (Android only.)
longpress	Fired when the device detects a long press. (Android, iPhone, iPad only.)
pinch	Fired when the device detects a pinch gesture. (iPhone, iPad only.)
singletap	Fired when the device detects a single tap against the view.
swipe	Fired when the device detects a swipe gesture (left or right) against the view. (iPhone, iPad, Mobile Web only.)
touchcancel	Fired when a touch event is interrupted by the device.
touchend	Fired when a touch event is completed.
touchmove	Fired as soon as the device detects movement of a touch.
touchstart	Fired as soon as the device detects a touch gesture.
twofingertap	Fired when the device detects a two-finger tap against the view.