# Titanium.UI.TabGroup

A tabbed group of windows.

Availability
0.9
0.9
9.2.0

# Overview

Android iOS
Android

A tab group can contain one or more Titanium.UI.Tab objects, each of which has an associated tab control that is used to bring it into focus.

Use the Titanium.UI.createTabGroup method or <TabGroup> Alloy element to create a tab group that, in turn, contains one or more <Tab> elements.

You can add tabs to the group using Titanium.UI.TabGroup.addTab, and programmatically switch to a specific tab using Titanium.UI.TabGroup.setActiveTab.

# Platform Implementation Notes

When using a tab group, note the following differences between platforms:

  • The tab group controls are positioned at the top of the display on Android and at the bottom on iOS.

  • On Android, only one tab group may exist at one time. A tab group may be closed to allow a new one to be opened later, but the root of the application must be a heavyweight window to prevent it exiting. Tabs cannot be removed from the tab group once added, and tabs cannot be reordered.

  • On iOS, more than one tab group may exist, and may be opened and closed as required. Each tab can contain a stack of windows, and the user can switch between them by tapping the tab's associated control. Tabs can be removed, and the user may (optionally) be allowed to reorder tabs.

  • On iOS, it is also possible to add tabs by updating the Titanium.UI.TabGroup.tabs property, and to switch active tabs by setting the Titanium.UI.Tab.active property on one of the tabs to true. Since these mechanisms are platform-specific, it is recommended that you use addTab and setActiveTab instead.

  • If you use the iOS-specific mechanisms, it is possible to add multiple active tabs to a tab group. In this case, the result of which tab is initially selected is undefined.

# Further Reading

If using tab groups on iOS, see iOS UI Element Usage Guidelines (opens new window).

# Examples

# Alloy XML Markup

Default Titanium project as an Alloy view.

<Alloy>
    <TabGroup backgroundColor="white" >
        <Tab id="tab1" title="Tab 1" icon="KS_nav_views.png">
            <Window id="win1" title="Tab 1">
                <Label id="label1" color="#999">I am Window 1</Label>
            </Window>
        </Tab>
        <Tab id="tab2" title="Tab 2" icon="KS_nav_views.png">
            <Window id="win2" title="Tab 2">
                <Label id="label2" color="#999">I am Window 2</Label>
            </Window>
        </Tab>
        <!-- Use the Require tag to include external Ti.UI.Tab views -->
    </TabGroup>
</Alloy>

# Classic Titanium Example

Simple two-tabbed app.

var win1 = Ti.UI.createWindow({
    backgroundColor: 'blue',
    title: 'Blue'
});
win1.add(Ti.UI.createLabel({text: 'I am a blue window.'}));

var win2 = Ti.UI.createWindow({
    backgroundColor: 'red',
    title: 'Red'
});
win2.add(Ti.UI.createLabel({text: 'I am a red window.'}));

var tab1 = Ti.UI.createTab({
    window: win1,
    title: 'Blue'
}),
tab2 = Ti.UI.createTab({
    window: win2,
    title: 'Red'
}),
tabGroup = Ti.UI.createTabGroup({
    tabs: [tab1, tab2]
});
tabGroup.open();

# Example with different colors

Create a TabGroup with different active and inactive colors.

function createTab(title, icon) {
  const window = Ti.UI.createWindow({ title: title });
  window.add(Ti.UI.createLabel({ text: title + " View" }));
    const tab = Ti.UI.createTab({
    title: title,
    icon: icon,
    window: window,
  });
  return tab;
}

const tabGroup = Ti.UI.createTabGroup({
  tabs: [
    createTab("Tab 1", "/assets/images/tab1.png"),
    createTab("Tab 2", "/assets/images/tab2.png"),
    createTab("Tab 3", "/assets/images/tab1.png")
  ],
  activeTintColor: "red",
  activeTitleColor: "red",
  tintColor: "purple",
  titleColor: "purple",
  tabsBackgroundColor: "#F7F7F7",
});
tabGroup.open();

# Properties

# activeTab

Availability
0.9
0.9
9.2.0
activeTab :Number | Titanium.UI.Tab

Active tab.


# activeTabBackgroundImage

Availability
3.1.0
9.2.0
activeTabBackgroundImage :String

Default background image for the active tab.


# activeTabIconTint DEPRECATED

Availability
3.1.0
9.2.0
activeTabIconTint :String | Titanium.UI.Color

DEPRECATED SINCE 9.0.3

Deprecated in favor of activeTintColor or alternatively activeTintColor.

Color applied to active tabs icons, as a color name or hex triplet, where the tab's activeIcon was not defined.

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


# activeTintColor

Availability
9.0.3
9.0.3
9.2.0
activeTintColor :String

The activeTintColor to apply to tabs.

This property affects the tint of selected tab icons.

Default: null


# activeTitleColor

Availability
9.0.3
9.0.3
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.


# activity READONLY

Availability
3.0.0

Reference to the Android Activity object associated with this tab group.

An Activity object is not created until the tab group opens. Before the tab group opens, activity refers to an empty JavaScript object. You can set properties on this object but cannot invoke any Activity methods on it. Once the tab group opens, the actual Activity object is created, using any properties set on the JavaScript object. At this point, you can call methods on the activity and access any properties that are set when the activity is created.

Prior to Release 3.4.0, you can only set properties on the activity after the tab group opens.


# activityEnterTransition CREATION ONLY

Availability
5.2.0
activityEnterTransition :Number

The type of transition used when activity is entering.

Activity B's enter transition determines how views in B are animated when A starts B. Applicable for Android 5.0 and above. This transition property will be ignored if animated is set to false. Will also be ignored unless at least 1 view has been assigned to the addSharedElement() method, except on Titanium 8.0.1 and higher where shared elements are no longer required to do transitions.

See "Material design activity transitions in Android" in the main description of Titanium.UI.Window for more information.

Default: If not specified uses platform theme transition.


# activityExitTransition CREATION ONLY

Availability
5.2.0
activityExitTransition :Number

The type of transition used when activity is exiting.

Activity A's exit transition determines how views in A are animated when A starts B. Applicable for Android 5.0 and above. This transition property will be ignored if animated is set to false. Will also be ignored unless at least 1 view has been assigned to the addSharedElement() method, except on Titanium 8.0.1 and higher where shared elements are no longer required to do transitions.

See "Material design activity transitions in Android" in the main description of Titanium.UI.Window for more information.

Default: If not specified uses platform theme transition.


# activityReenterTransition CREATION ONLY

Availability
5.2.0
activityReenterTransition :Number

The type of transition used when reentering to a previously started activity.

Activity A's reenter transition determines how views in A are animated when B returns to A. Applicable for Android 5.0 and above. This transition property will be ignored if animated is set to false. Will also be ignored unless at least 1 view has been assigned to the addSharedElement() method, except on Titanium 8.0.1 and higher where shared elements are no longer required to do transitions.

See "Material design activity transitions in Android" in the main description of Titanium.UI.Window for more information.

Default: If not specified uses `activityExitTransition`.


# activityReturnTransition CREATION ONLY

Availability
5.2.0
activityReturnTransition :Number

The type of transition used when returning from a previously started activity.

Activity B's return transition determines how views in B are animated when B returns to A. Applicable for Android 5.0 and above. This transition property will be ignored if animated is set to false. Will also be ignored unless at least 1 view has been assigned to the addSharedElement() method, except on Titanium 8.0.1 and higher where shared elements are no longer required to do transitions.

See "Material design activity transitions in Android" in the main description of Titanium.UI.Window for more information.

Default: If not specified uses `activityEnterTransition`.


# activitySharedElementEnterTransition CREATION ONLY

Availability
5.2.0
activitySharedElementEnterTransition :Number

The type of enter transition used when animating shared elements between two activities.

Activity B's shared element enter transition determines how shared elements animate from A to B. Applicable for Android 5.0 and above. This value will be ignored if animated is set to false. See "Material design activity transitions in Android" in the main description of Titanium.UI.Window for more information.

Default: Defaults to android platform's [move](https://github.com/android/platform_frameworks_base/blob/lollipop-release/core/res/res/transition/move.xml) transition.


# activitySharedElementExitTransition CREATION ONLY

Availability
5.2.0
activitySharedElementExitTransition :Number

The type of exit transition used when animating shared elements between two activities.

Activity A's shared element exit transition animates shared elements before they transition from A to B Applicable for Android 5.0 and above. This value will be ignored if animated is set to false. See "Material design activity transitions in Android" in the main description of Titanium.UI.Window for more information.

Default: Defaults to android platform's [move](https://github.com/android/platform_frameworks_base/blob/lollipop-release/core/res/res/transition/move.xml) transition.


# activitySharedElementReenterTransition CREATION ONLY

Availability
5.2.0
activitySharedElementReenterTransition :Number

The type of reenter transition used when animating shared elements between two activities.

Activity A's shared element reenter transition animates shared elements after they have transitioned from B to A. Applicable for Android 5.0 and above. This value will be ignored if animated is set to false. See "Material design activity transitions in Android" in the main description of Titanium.UI.Window for more information.

Default: Defaults to android platform's [move](https://github.com/android/platform_frameworks_base/blob/lollipop-release/core/res/res/transition/move.xml) transition.


# activitySharedElementReturnTransition CREATION ONLY

Availability
5.2.0
activitySharedElementReturnTransition :Number

The type of return transition used when animating shared elements between two activities.

Activity B's shared element return transition determines how shared elements animate from B to A. Applicable for Android 5.0 and above. This value will be ignored if animated is set to false. See "Material design activity transitions in Android" in the main description of Titanium.UI.Window for more information.

Default: Defaults to android platform's [move](https://github.com/android/platform_frameworks_base/blob/lollipop-release/core/res/res/transition/move.xml) transition.


# allowUserCustomization

Availability
0.9
9.2.0
allowUserCustomization :Boolean

Allow the user to reorder tabs in the tab group using the Edit button on the More tab.

Set to false to prevent tab reordering.

Default: true


# apiName READONLY

Availability
3.2.0
3.2.0
9.2.0
apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.


# autoAdjustScrollViewInsets

Availability
3.1.3
9.2.0
autoAdjustScrollViewInsets :Boolean

Specifies whether or not the view controller should automatically adjust its scroll view insets.

When the value is true, it allows the view controller to adjust its scroll view insets in response to the screen areas consumed by the status bar, navigation bar, toolbar and tab bar.

The default behavior assumes that this is false. Must be specified before opening the window.


# autoTabTitle

Availability
11.0.0
autoTabTitle :Boolean

If set to true it will automatically set the actionbar title to the current tabs window title.

Default: false


# backButtonTitle

Availability
0.9
9.2.0
backButtonTitle :String

Title for the back button. This is only valid when the window is a child of a tab.


# backButtonTitleImage

Availability
0.9
9.2.0
backButtonTitleImage :String | Titanium.Blob

The image to show as the back button. This is only valid when the window is a child of a tab.


# backgroundColor

Availability
0.9
0.9
9.2.0
backgroundColor :String | Titanium.UI.Color

Background color of the window, as a color name or hex triplet.

On Android, to specify a semi-transparent background, set the alpha value using the opacity property before opening the window.

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

Default: Transparent


# barColor

Availability
8.0.1
0.9
9.2.0
barColor :String | Titanium.UI.Color

Default navigation bar color (typically for the More tab), as a color name or hex triplet.

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

A value of transparent results in a semi-opaque black bar style.


# barImage

Availability
0.9
9.2.0
barImage :String

Background image for the nav bar, specified as a URL to a local image.

The behavior of this API on iOS has changed from version 3.2.0. Previous versions of the SDK created a custom image view and inserted it as a child of the navigation bar. The titanium sdk now uses the native call to set the background image of the navigation bar. You can set it to a 1px transparent png to use a combination of barColor and hideShadow:true.


# bubbleParent

Availability
3.0.0
3.0.0
9.2.0
bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true


# center

Availability
0.9
0.9
9.2.0
center :Point

View's center position, in the parent view's coordinates.

This is an input property for specifying where the view should be positioned, and does not represent the view's calculated position.

Defaults to undefined.


# clipMode

Availability
3.3.0
9.2.0
clipMode :Number

View's clipping behavior.

Setting this to CLIP_MODE_ENABLED enforces all child views to be clipped to this views bounds. Setting this to CLIP_MODE_DISABLED allows child views to be drawn outside the bounds of this view. When set to CLIP_MODE_DEFAULT or when this property is not set, clipping behavior is inferred. See section on iOS Clipping Behavior in Titanium.UI.View.

Defaults to undefined. Behaves as if set to CLIP_MODE_DEFAULT.


# closed READONLY

Availability
9.1.0
9.1.0
9.2.0
closed :Boolean

Determines whether this Window is closed.

Default: true


# editButtonTitle

Availability
0.9
9.2.0
editButtonTitle :String

Title for the edit button on the More tab.


# elevation

Availability
5.0.0
elevation :Number

Base elevation of the view relative to its parent in pixels.

The elevation of a view determines the appearance of its shadow. Higher elevations produce larger and softer shadows.

Note: The elevation property only works on Titanium.UI.View objects. Many Android components have a default elevation that cannot be modified. For more information, see Google design guidelines: Elevation and shadows.


# exitOnClose

Availability
0.9
exitOnClose :Boolean

Boolean value indicating if the application should exit when closing the tab group, whether via Android back button or the close method.

Starting in 3.4.2 you can set this property at any time. In earlier releases you can only set this as a createTabGroup({...}) option.

Default: True if tab group is opened on top of the root activity. False otherwise.


# extendEdges

Availability
3.1.3
9.2.0
extendEdges :Array<Number>

An array of supported values specified using the EXTEND_EDGE constants in Titanium.UI.

This is only valid for windows hosted by navigation controllers or tab bar controllers. This property is used to determine the layout of the window within its parent view controller. For example if the window is specified to extend its top edge and it is hosted in a navigation controller, then the top edge of the window is extended underneath the navigation bar so that part of the window is obscured. If the navigation bar is opaque (translucent property on window is false), then the top edge of the window will only extend if includeOpaqueBars is set to true.

The default behavior is to assume that no edges are to be extended. Must be specified before opening the window.


# extendSafeArea CREATION ONLY

Availability
7.5.0
6.3.0
9.2.0
extendSafeArea :Boolean

Specifies whether the screen insets/notches are allowed to overlap the window's content or not.

If set true, then the contents of the window will be extended to fill the whole screen and allow the system's UI elements (such as a translucent status-bar) and physical obstructions (such as the iPhone X rounded corners and top sensor housing) to overlap the window's content. In this case, it is the app developer's responsibility to position views so that they're unobstructed. On Android, you can use the safeAreaPadding property after the window has been opened to layout your content within the insets.

If set false, then the window's content will be laid out within the safe-area and its child views will be unobstructed. For example, you will not need to position a view below the top status-bar.

Read more about the safe-area layout-guide in the Human Interface Guidelines.

Default: `false` on Android, `true` on iOS.


# filterTouchesWhenObscured

Availability
9.3.0
filterTouchesWhenObscured :Boolean

Discards touch related events if another app's system overlay covers the view.

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.

Setting this property to true causes touch related events (including "click") to not be fired if a system overlay overlaps the view.

Default: false


# flagSecure CREATION ONLY

Availability
3.3.0
flagSecure :Boolean

Treat the content of the window as secure, preventing it from appearing in screenshots or from being viewed on non-secure displays.

When the value is true, preventing it from appearing in screenshots or from being viewed on non-secure displays.

Default: false


# focused READONLY

Availability
9.1.0
9.1.0
9.2.0
focused :Boolean

Determines whether this TextArea has focus.

Default: false


# fullscreen

Availability
0.9
0.9
9.2.0
fullscreen :Boolean

Boolean value indicating if the window is fullscreen.

A fullscreen window occupies all of the screen space, hiding the status bar. Must be specified at creation time or in the options dictionary passed to the open method.

On iOS the behavior of this property has changed. Starting from 3.1.3, if this property is undefined then the property is set to the value for UIStatusBarHidden defined in tiapp.xml. If that is not defined it is treated as explicit false. On earlier versions, opening a window with this property undefined would not effect the status bar appearance.

Default: false


# hiddenBehavior

Availability
6.1.0
hiddenBehavior :Number

Sets the behavior when hiding an object to release or keep the free space

If setting hiddenBehavior to HIDDEN_BEHAVIOR_GONE it will automatically release the space the view occupied. For example: in a vertical layout the views below the object will move up when you hide an object with hiddenBehavior:Titanium.UI.HIDDEN_BEHAVIOR_GONE.

Defaults to Titanium.UI.HIDDEN_BEHAVIOR_INVISIBLE.

This API can be assigned the following constants:

# hidesBackButton

Availability
8.0.0
7.5.0
9.2.0
hidesBackButton :Boolean

Set this to true to hide the back button of navigation bar.

When this property is set to true, the navigation window hides its back button.

Default: false


# hidesBarsOnSwipe CREATION ONLY

Availability
6.0.0
9.2.0
hidesBarsOnSwipe :Boolean

Set this to true to hide the navigation bar on swipe.

When this property is set to true, an upward swipe hides the navigation bar and toolbar. A downward swipe shows both bars again. If the toolbar does not have any items, it remains visible even after a swipe.

Default: false


# hidesBarsOnTap CREATION ONLY

Availability
6.0.0
9.2.0
hidesBarsOnTap :Boolean

Set this to true to hide the navigation bar on tap.

When the value of this property is true, the navigation controller toggles the hiding and showing of its navigation bar and toolbar in response to an otherwise unhandled tap in the content area.

Default: false


# hidesBarsWhenKeyboardAppears CREATION ONLY

Availability
6.0.0
9.2.0
hidesBarsWhenKeyboardAppears :Boolean

Set this to true to hide the navigation bar when the keyboard appears.

When this property is set to true, the appearance of the keyboard causes the navigation controller to hide its navigation bar and toolbar.

Default: false


# hideShadow

Availability
3.2.0
9.2.0
hideShadow :Boolean

Set this to true to hide the shadow image of the navigation bar.

This property is only honored if a valid value is specified for the barImage property.

Default: false


# hidesSearchBarWhenScrolling

Availability
8.1.0
9.2.0
hidesSearchBarWhenScrolling :Boolean

A Boolean value indicating whether the integrated search bar is hidden when scrolling any underlying content.

When the value of this property is true, the search bar is visible only when the scroll position equals the top of your content view. When the user scrolls down, the search bar collapses into the navigation bar. Scrolling back to the top reveals the search bar again. When the value of this property is false, the search bar remains regardless of the current scroll position. You must set showSearchBarInNavBar or showSearchBarInNavBar property for this property to have any effect.

Default: true


# homeIndicatorAutoHidden

Availability
7.3.0
9.2.0
homeIndicatorAutoHidden :Boolean

Boolean value indicating whether the system is allowed to hide the visual indicator for returning to the Home screen.

Set this value true, if you want the system to determine when to hide the indicator. Set this value false, if you want the indicator shown at all times. The system takes your preference into account, but setting true is no guarantee that the indicator will be hidden.

Default: false


# horizontalMotionEffect

Availability
7.3.0
9.2.0
horizontalMotionEffect :MinMaxOptions

Adds a horizontal parallax effect to the view

Note that the parallax effect only happens by tilting the device so results can not be seen on Simulator. To clear all motion effects, use the <Titanium.UI.clearMotionEffects> method.


# id

Availability
0.9
0.9
9.2.0
id :String

View's identifier.

The id property of the Ti.UI.View represents the view's identifier. The identifier string does not have to be unique. You can use this property with getViewById method.


# includeOpaqueBars

Availability
3.1.3
9.2.0
includeOpaqueBars :Boolean

Specifies if the edges should extend beyond opaque bars (navigation bar, tab bar, toolbar).

By default edges are only extended to include translucent bars. However if this is set to true, then edges are extended beyond opaque bars as well.

The default behavior assumes that this is false. Must be specified before opening the window.


# keepScreenOn

Availability
0.9
keepScreenOn :Boolean

Determines whether to keep the device screen on.

When true the screen will not power down. Note: enabling this feature will use more power, thereby adversely affecting run time when on battery. For iOS look at idleTimerDisabled.

Default: false


# largeTitleDisplayMode

Availability
6.3.0
9.2.0
largeTitleDisplayMode :Number

The mode to use when displaying the title of the navigation bar.

Automatically use the large out-of-line title based on the state of the previous item in the navigation bar. An item with largeTitleDisplayMode = Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_AUTOMATIC will show or hide the large title based on the request of the previous navigation item. If the first item pushed is set to Automatic, then it will show the large title if the navigation bar has largeTitleEnabled = true.

Default: Titanium.UI.iOS.LARGE_TITLE_DISPLAY_MODE_AUTOMATIC


# largeTitleEnabled

Availability
6.3.0
9.2.0
largeTitleEnabled :Boolean

A Boolean value indicating whether the title should be displayed in a large format.

When set to true, the navigation bar will use a larger out-of-line title view when requested by the current navigation item. To specify when the large out-of-line title view appears, see largeTitleDisplayMode.

Default: false


# leftNavButton

Availability
0.9
9.2.0
leftNavButton :Titanium.UI.View

View to show in the left nav bar area.

In an Alloy application you can specify this property with a <LeftNavButton> element inside the <Window> element, for example:

<Alloy>
    <TabGroup>
        <Tab>
            <Window class="container">
                <LeftNavButton platform=ios>
                    <Button title="Back" onClick="closeWindow" />
                </LeftNavButton>
            </Window>
        </Tab>
    </TabGroup>
</Alloy>

# leftNavButtons

Availability
3.3.0
9.2.0
leftNavButtons :Array<Titanium.UI.View>

An Array of views to show in the left nav bar area.


# lifecycleContainer

Availability
3.6.0

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.


modal :Boolean

Indicates to open a modal window or not.

Set to true to create a modal window.

Must be specified at creation time or in the dictionary passed to the open method.

In the user interface, a modal window is a window that blocks the main application UI until the modal window is dismissed. A modal window requires the user to interact with it to resume the normal flow of the application.

See the "Modal Windows" section for platform-specific information.

Default: false


navBarHidden :Boolean

Hides the navigation bar (true) or shows the navigation bar (false).

# iOS Platform Notes

Since Titanium SDK 6.0.0, you can use this property to hide and show the property as well.

Using this property, the navigation bar will be hidden or shown animated by default. Please note that this property will only take effect if the window is used inside a Titanium.UI.NavigationWindow and will be ignored otherwise. If you want to hide or show the navigation without an animation, use t he methods showNavBar and hideNavBar with the second parameter to specify the animation:

// "myWindow" is a Ti.UI.Window inside a Ti.UI.NavigationWindow
myWindow.hideNavBar(true, {animated: false});

# Android Platform Notes

Since Release 3.3.0, due to changes to support the appcompat library, this property has no effect. By default, the action bar is always displayed. To hide the action bar, see the Android Action Bar guide.

Default: false


navigationWindow :Titanium.UI.NavigationWindow

The Titanium.UI.NavigationWindow instance hosting this window.

Returns the navigation window that hosts this window. Returns null if the window is not hosted by a navigation window.


navTintColor :String | Titanium.UI.Color

The tintColor to apply to the navigation bar (typically for the More tab).

This property is a direct correspondant of the tintColor property of NavigationBar on iOS.

Default: null


# onBack

Availability
0.9
onBack :Callback<void>

Callback function that overrides the default behavior when the user presses the Back button.

This was separated from the androidback event. You need to define this callback if you explicitly want to override the back button behavior.


# orientation READONLY

Availability
0.9
3.0.0
9.2.0
orientation :Number

Current orientation of the window.

To determine the current orientation of the device, see orientation, instead.

See the discussion of the orientationModes property for more information on how the screen orientation is determined.


# orientationModes

Availability
0.9
0.9
9.2.0
orientationModes :Array<Number>

Array of supported orientation modes, specified using the orientation constants defined in Titanium.UI.

Note: Using the orientationModes property to force the orientation of non-modal windows is considered a bad practice and will not be supported, including forcing the orientation of windows inside a NavigationWindow or TabGroup.

To restrict this window to a certain set of orientations, specify one or more of the orientation constants LANDSCAPE_LEFT, LANDSCAPE_RIGHT, PORTRAIT, UPSIDE_PORTRAIT.

orientationModes must be set before opening the window.

To determine the current orientation of the window, see orientation. To determine the current orientation of the device, see orientation. To be notified when the device's current orientation changes, add a listener for the orientationchange event.

# Android Orientation Modes

On Android, orientation behavior is dependent on the Android SDK level of the device itself. Devices running Android 2.3 and above support "sensor portait mode" and "sensor landscape mode," in these modes, the device is locked into either a portrait or landscape orientation, but can switch between the normal and reverse orientations (for example, between PORTRAIT and UPSIDE_PORTRAIT).

In addition, the definition of portrait or landscape mode can vary based on the physical design of the device. For example, on some devices LANDSCAPE_LEFT represents the top of the device being at the 270 degree position but other devices may (based on camera position for example) treat this position as LANDSCAPE_RIGHT. In general, applications for Android that need to be aware of orientation should try and limit their orientation logic to handling either portrait or landscape rather than worrying about the reverse modes. This approach will allow the orientation modes to adopt a more natural feel for the specific device.

The following list breaks down the orientation behavior on Android based on the contents of the orientationModes array:

  1. Empty array. Enables orientation to be fully controlled by the device sensor.

  2. Array includes one or both portrait modes and one or both landscape modes. Enables full sensor control (identical to an empty array).

  3. Array contains PORTRAIT and UPSIDE_PORTRAIT. On Android 2.3 and above, enables sensor portrait mode. This means the screen will shift between both portrait modes according to the sensor inside the device.

    On Android versions below 2.3, locks screen orientation in normal portrait mode.

  4. Array contains LANDSCAPE_LEFT and LANDSCAPE_RIGHT. On Android 2.3 and above, enables sensor landscape mode. This means the screen will shift between both landscape modes according to the sensor inside the device.

    On Android versions below 2.3, locks screen orientation in normal landscape mode.

  5. Array contains only PORTRAIT. Locks screen orientation to normal portrait mode.

  6. Array contains only LANDSCAPE_LEFT. Locks screen orientation to normal landscape mode.

  7. Array contains only UPSIDE_PORTRAIT. On Android 2.3 and above, locks screen in reverse portrait mode.

    On Android versions below 2.3, results are undefined.

  8. Array contains only LANDSCAPE_RIGHT. On Android 2.3 and above, locks screen in reverse landscape mode.

    On Android versions below 2.3, results are undefined.

Default: empty array


# overrideCurrentAnimation CREATION ONLY

Availability
3.3.0
overrideCurrentAnimation :Boolean

When on, animate call overrides current animation if applicable.

If this property is set to false, the animate call is ignored if the view is currently being animated.

Defaults to undefined but behaves as false


# paddingBottom

Availability
10.1.0
paddingBottom :Number | String

Bottom padding of bottom navigation

When using TABS_STYLE_BOTTOM_NAVIGATION you can set the padding to have a floating bottom navigation


# paddingLeft

Availability
10.1.0
paddingLeft :Number | String

Left padding of bottom navigation

When using TABS_STYLE_BOTTOM_NAVIGATION you can set the padding to have a floating bottom navigation


# paddingRight

Availability
10.1.0
paddingRight :Number | String

Right padding of bottom navigation

When using TABS_STYLE_BOTTOM_NAVIGATION you can set the padding to have a floating bottom navigation


# previewContext

Availability
5.1.0

The preview context used in the 3D-Touch feature "Peek and Pop".

Preview context to present the "Peek and Pop" of a view. Use an configured instance of Titanium.UI.iOS.PreviewContext here.

Note: This property can only be used on devices running iOS9 or later and supporting 3D-Touch. It is ignored on older devices and can manually be checked using forceTouchSupported.


# pullBackgroundColor

Availability
3.3.0
9.2.0
pullBackgroundColor :String | Titanium.UI.Color

Background color of the wrapper view when this view is used as either pullView or headerPullView.

Defaults to undefined. Results in a light grey background color on the wrapper view.


# rect READONLY

Availability
2.0.0
2.0.0
9.2.0

The bounding box of the view relative to its parent, in system units.

The view's bounding box is defined by its size and position.

The view's size is rect.width x rect.height. The view's top-left position relative to its parent is (rect.x , rect.y).

On Android it will also return rect.absoluteX and 'rect.absoluteY' which are relative to the main window.

The correct values will only be available when layout is complete. To determine when layout is complete, add a listener for the postlayout event.


# rightNavButton

Availability
0.9
9.2.0
rightNavButton :Titanium.UI.View

View to show in the right nav bar area.

In an Alloy application you can specify this property with a <RightNavButton> element in the <Window> element, for example:

<Alloy>
    <TabGroup>
        <Tab>
            <Window class="container">
                <RightNavButton platform=ios>
                    <Button title="Back" onClick="closeWindow" />
                </RightNavButton>
            </Window>
        </Tab>
    </TabGroup>
</Alloy>

# rightNavButtons

Availability
3.3.0
9.2.0
rightNavButtons :Array<Titanium.UI.View>

An Array of views to show in the right nav bar area.


# rotation

Availability
5.4.0
12.3.0
rotation :Number

Clockwise 2D rotation of the view in degrees.

Translation values are applied to the static post layout value.


# rotationX

Availability
5.4.0
rotationX :Number

Clockwise rotation of the view in degrees (x-axis).

Translation values are applied to the static post layout value.


# rotationY

Availability
5.4.0
rotationY :Number

Clockwise rotation of the view in degrees (y-axis).

Translation values are applied to the static post layout value.


# safeAreaPadding READONLY

Availability
7.5.0
8.0.0
9.2.0
safeAreaPadding :Padding

The padding needed to safely display content without it being overlapped by the screen insets and notches.

When setting extendSafeArea to true, the system's insets such as a translucent status bar, translucent navigation bar, and/or camera notches will be allowed to overlay on top of the window's content. In this case, it is the app developer's responsibility to prevent these insets from overlapping key content such as buttons. This property provides the amount of space needed to be added to the left, top, right, and bottom edges of the window root view to do this.

This property won't return values greater than zero until the window has been opened. It is recommended that you read this property via a postlayout event listener since the padding values can change when when the app's orientation changes or when showing/hiding the action bar.

If the extendSafeArea property is set false, then the returned padding will be all zeros since the root content will be positioned between all insets.

Below is an example on how to set up a safe-area view container using this property.

// Set up a window with a translucent top status bar and translucent nav bar.
// This will only work on Android 4.4 and newer OS versions.
var win = Ti.UI.createWindow({
    extendSafeArea: true,
    theme: 'Theme.Titanium.NoTitleBar',
    windowFlags: Ti.UI.Android.FLAG_TRANSLUCENT_NAVIGATION | Ti.UI.Android.FLAG_TRANSLUCENT_STATUS
});

// Set up a safe-area view to be layed out between the system insets.
// You should use this as a container for child views.
var safeAreaView = Ti.UI.createView({
    backgroundColor: 'green'
});
win.add(safeAreaView);
win.addEventListener('postlayout', function() {
    // Update the safe-area view's dimensions after every 'postlayout' event.
    safeAreaView.applyProperties(win.safeAreaPadding);
});

// Open the window.
win.open();

# scaleX

Availability
5.4.0
scaleX :Number

Scaling of the view in x-axis in pixels.

Translation values are applied to the static post layout value.


# scaleY

Availability
5.4.0
scaleY :Number

Scaling of the view in y-axis in pixels.

Translation values are applied to the static post layout value.


# shadowImage

Availability
3.1.0
9.2.0
shadowImage :String

Image of the shadow placed between the tab bar and the content area.

The tabsBackgroundImage property must also be set in order for this to take effect.


# shiftMode

Availability
8.0.0
shiftMode :Number

Determines whether the TABS_STYLE_BOTTOM_NAVIGATION uses shiftMode.

In Android BottomNavigationView uses shiftMode by default. This mode changes unselected tabs' properties - makes the title invisible and reduces the icon's dimensions by half.

This property allows the user to choose whether they would use this design behavior.

Default is 1 (true) to show title only when the tab is selected. Selected tab will be bigger. Set it to 0 (false) to show all titles and make the buttons the same size. Set it to 2 hide all titles and make the buttons the same size. Title stays hidden for active tabs.

NOTE: This property only affects TabGroups with the TABS_STYLE_BOTTOM_NAVIGATION.

Default: 1


# size READONLY

Availability
0.9
0.9
9.2.0
size :Dimension

The size of the view in system units.

Although property returns a Dimension dictionary, only the width and height properties are valid. The position properties--x and y--are always 0.

To find the position and size of the view, use the rect property instead.

The correct values will only be available when layout is complete. To determine when layout is complete, add a listener for the postlayout event.


# smoothScrollOnTabClick

Availability
3.6.0
smoothScrollOnTabClick :Boolean

Boolean value indicating if changing pages by tab clicks is animated.

If true, when clicking the tab the page transition is animated, false otherwise.

Default: true


# splitActionBar CREATION ONLYDEPRECATED

Availability
3.6.0
splitActionBar :Boolean

DEPRECATED SINCE 6.2.0

Deprecated in AppCompat theme. The same behaviour can be achived by using Toolbar.

Boolean value to enable split action bar.

splitActionBar must be set before opening the window. This property indicates if the window should use a split action bar


# statusBarStyle

Availability
3.1.3
9.2.0
statusBarStyle :Number

The status bar style associated with this window.

Sets the status bar style when this window has focus. This is now the recommended way to control the status bar style on the application.

If this value is undefined, the value is set to UIStatusBarStyle defined in tiapp.xml. If that is not defined it defaults to DEFAULT.


# style CREATION ONLY

Availability
8.0.0
style :Number

Property defining which style for the TabGroup to be used.

Since 8.0.0 Titanium has introduce a new style to be used for the TabGroup component.

For backwards compatibility not taking advantage of this property results in using the default style which is similar to the ActionBar Tabs style but sticking to the Material design Guidelines.

TABS_STYLE_DEFAULT is the style that was used in Titanium prior to 8.0.0.GA. It displays the TabGroup with a list of Tabs at the top of the screen.

TABS_STYLE_BOTTOM_NAVIGATION is a style that displays the TabGroup with a list of Tabs in a controller at the bottom of the screen. The recommended usage of this style is for items count between three and five: (https://material.io/design/components/bottom-navigation.html#usage) In Android it is limited to supporting a maximum number of five tabs. You can use paddingLeft, paddingRight, paddingBottom to create a floating bottom navigation. If you want to change the radius or background color you'll need to create /app/platform/android/res/drawable/titanium_rounded_corners.xml and set it to

<?xml version="1.0" encoding="UTF-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android">
    <solid android:color="#FFFFFF" />
    <corners android:radius="7dp" />
</shape>

# sustainedPerformanceMode

Availability
7.0.0