# Titanium.UI.TabGroup

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

This property affects the tint of selected tab icons.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

Set to false to prevent tab reordering.

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

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

• HIDDEN_BEHAVIOR_INVISIBLE. Keeps the space and just hides the object (default).
• HIDDEN_BEHAVIOR_GONE. Releases the space and hides the object.

Defaults to Titanium.UI.HIDDEN_BEHAVIOR_INVISIBLE.

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

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.

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.

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

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

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.

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.

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.

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.

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.

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

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.

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.

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>

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.

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.

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

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

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

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

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.

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.

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

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

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

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

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.

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.

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>

Translation values are applied to the static post layout value.

Translation values are applied to the static post layout value.

Translation values are applied to the static post layout value.

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

Translation values are applied to the static post layout value.

Translation values are applied to the static post layout value.

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

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.

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.

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

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

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.

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>

Performance can fluctuate dramatically for long-running apps, because the system throttles system-on-chip engines as device components reach their temperature limits. This fluctuation presents a moving target for app developers creating high-performance, long-running apps.

Setting this feature to true will set sustained performance mode for the corresponding window. If property is undefined then it defaults to false.

Note: This feature is only available on supported devices. The functionality is experimental and subject to change in future releases. See Android docs for further info.