TabGroup.yml

---
name: Titanium.UI.TabGroup
summary: A tabbed group of windows.
description: |
    A tab group can contain one or more [Tab](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 [addTab](Titanium.UI.TabGroup.addTab), and programmatically
    switch to a specific tab using [setActiveTab](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
    [tabs](Titanium.UI.TabGroup.tabs) property, and to switch active tabs by setting the
    [active](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](https://developer.apple.com/ios/human-interface-guidelines/bars/tab-bars/).

extends: Titanium.UI.Window
since: "0.9"
excludes:
    methods: [add, remove, removeAllChildren, replaceAt]
    properties: [accessibilityHidden,accessibilityHint,accessibilityLabel,accessibilityValue,
                 anchorPoint,animatedCenter,backgroundDisabledColor,backgroundDisabledImage,
                 backgroundFocusedColor,backgroundFocusedImage,backgroundGradient,backgroundImage,backgroundLeftCap,
                 backgroundRepeat,backgroundSelectedColor,backgroundSelectedImage,backgroundTopCap,
                 borderColor,borderRadius,borderWidth,bottom,children,enabled,focusable,height,
                 horizontalWrap,layout,left,opacity,right,softKeyboardOnFocus,
                 top,transform,width,zIndex]
    events: [click, dblclick, doubletap, keypressed, longclick, longpress, pinch, postlayout, 
             singletap, swipe, touchcancel, touchend, touchmove, touchstart, twofingertap]

events:
  - name: androidback
    platforms: [android]
    summary: Fired when the back button is pressed by the user.
    description: |
        This event is fired when the current tab group's activity detects
        a back button press by the user to navigate back.

        By default this event would trigger the current activity to be finished
        and removed from the task stack. Subscribing to this event with a listener
        will prevent the default behavior. To finish the activity from your listener
        just call the `close` method of the tab group.
    since: '3.0.0'

  - name: androidcamera
    summary: Fired when the Camera button is released.
    description: |
        Setting a listener disables the default key handling for this button. To restore
        default behavior, remove the listener.
    platforms: [android]
    since: '3.0.0'

  - name: androidfocus
    summary: Fired when the Camera button is half-pressed then released.
    description: |
        Setting a listener disables the default key handling for this button. To restore
        default behavior, remove the listener.
    platforms: [android]
    since: '3.0.0'

  - name: androidsearch
    summary: Fired when the Search button is released.
    description: |
        Setting a listener disables the default key handling for this button. To restore
        default behavior, remove the listener.
    platforms: [android]
    since: '3.0.0'

  - name: androidvoldown
    summary: Fired when the volume down button is released.
    description: |
        Setting a listener disables the default key handling for this button. To restore
        default behavior, remove the listener.
    platforms: [android]
    since: '3.0.0'

  - name: androidvolup
    summary: Fired when the volume up button is released.
    description: |
        Setting a listener disables the default key handling for this button. To restore
        default behavior, remove the listener.
    platforms: [android]
    since: '3.0.0'

  - name: blur
    summary: |
        Fired when this tab group loses focus. On Android, fired when a tab in this tab group
        loses focus.
    description: |
        On Android, this event also fires before putting the activity in the background
        (before the activity enters the pause state).
    platforms: [iphone, ipad, android, macos]
    properties:
      - name: index
        summary: |
            Index of the current active tab. On iOS, a value of `undefined` indicates that the
            **More** tab was the active tab.
        type: Number

      - name: previousIndex
        summary: |
            Index of the previous active tab. On iOS, a value of `undefined` indicates that the
            **More** tab was the previous tab.
        type: Number

      - name: tab
        summary: Active tab.
        type: Titanium.UI.Tab

      - name: previousTab
        summary: |
            Previous active tab. On iOS, a value of `undefined` indicates that the **More** tab was
            the previous tab.
        type: Titanium.UI.Tab

  - name: close
    summary: Fired when the tab group is closed.
    since: {android: "7.1.0"}
    platforms: [iphone, ipad, android, macos]

  - name: focus
    summary: |
        Fired when this tab group gains focus. On Android, fired when a tab in this tab group
        gains focus.
    description: |
        On Android, this event also fires when the activity enters the foreground
        (after the activity enters the resume state).
    platforms: [iphone, ipad, android, macos]
    properties:
      - name: index
        summary: Index of the current active tab.
        type: Number

      - name: previousIndex
        summary: Index of the previous active tab.
        type: Number

      - name: tab
        summary: Active tab.
        type: Titanium.UI.Tab

      - name: previousTab
        summary: Previous active tab.
        type: Titanium.UI.Tab

  - name: open
    summary: Fired when the tab group is opened.

  - name: selected
    summary: |
        Fired when a tab is selected.
    since: "5.1.0"
    platforms: [iphone, ipad]
    deprecated:
        since: "5.2.0"
        removed: "9.0.0"
        notes: Use [Titanium.UI.Tab.focus](Titanium.UI.Tab.focus) event instead.
    properties:
      - name: index
        summary: Index of the current active tab.
        type: Number

      - name: previousIndex
        summary: Index of the previous active tab.
        type: Number

      - name: tab
        summary: Active tab.
        type: Titanium.UI.Tab

      - name: previousTab
        summary: Previous active tab.
        type: Titanium.UI.Tab

  - name: unselected
    summary: |
        Fired when a tab is unselected.
    since: "5.1.0"
    platforms: [iphone, ipad]
    deprecated:
        since: "5.2.0"
        removed: "9.0.0"
        notes: Use [Titanium.UI.Tab.blur](Titanium.UI.Tab.blur) event instead.
    properties:
      - name: index
        summary: |
            Index of the current active tab. On iOS, a value of `undefined` indicates that the
            **More** tab was the active tab.
        type: Number

      - name: previousIndex
        summary: |
            Index of the previous active tab. On iOS, a value of `undefined` indicates that the
            **More** tab was the previous tab.
        type: Number

      - name: tab
        summary: Active tab.
        type: Titanium.UI.Tab

      - name: previousTab
        summary: |
            Previous active tab. On iOS, a value of `undefined` indicates that the **More** tab was
            the previous tab.
        type: Titanium.UI.Tab

methods:
  - name: addTab
    summary: Adds a tab to the tab group.
    parameters:
      - name: tab
        summary: Tab to add.
        type: Titanium.UI.Tab

  - name: close
    summary: Closes the tab group and removes it from the UI.

  - name: disableTabNavigation
    summary: |
        Disable (or re-enable) tab navigation. If tab navigation is disabled, the tabs are hidden and
        the last selected tab window is shown.
    parameters:
      - name: disable
        summary: True to disable tab navigation, false to re-enable the tabs.
        type: Boolean
    platforms: [android]
    since: 3.6.0

  - name: getActiveTab
    summary: Gets the currently-active tab.
    returns:
        type: Titanium.UI.Tab

  - name: open
    summary: Opens the tab group and makes it visible.

  - name: removeTab
    summary: Removes a tab from the tab group.
    platforms: [iphone, ipad, macos]
    parameters:
      - name: tab
        summary: Tab to remove.
        type: Titanium.UI.Tab

  - name: setActiveTab
    summary: Selects the currently active tab in a tab group.
    parameters:
      - name: indexOrObject
        summary: Index or object of the tab to switch to.
        type: [Number, Titanium.UI.Tab]

  - name: getTabs
    summary: Gets all tabs that are managed by the tab group.
    returns:
        type: Array<Titanium.UI.Tab>

properties:
  - name: activeTab
    summary: Active tab.
    type: [Number, Titanium.UI.Tab]

  - name: activity
    summary: |
        Reference to the Android Activity object associated with this tab group.
    description: |
        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.
    platforms: [android]
    since: 3.0.0
    type: Titanium.Android.Activity
    permission: read-only

  - name: allowUserCustomization
    summary: |
        Allow the user to reorder tabs in the tab group using the **Edit** button on the **More**
        tab.
    description: Set to `false` to prevent tab reordering.
    type: Boolean
    default: true
    platforms: [iphone, ipad, macos]

  - name: barColor
    summary: |
        Default navigation bar color (typically for the **More** tab), as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.

        A value of `transparent` results in a semi-opaque black bar style.
    type: [String, Titanium.UI.Color]
    platforms: [iphone, ipad, android, macos]

  - name: translucent
    summary: Boolean value indicating if the nav bar (typically for the **More** tab), is translucent.
    platforms: [iphone, ipad, macos]
    default: true on iOS7 and above, false otherwise.
    type: Boolean
    since: "3.3.0"

  - name: titleAttributes
    summary: Title text attributes of the window to be applied on the **More** tab.
    description: |
        Use this property to specify the color, font and shadow attributes of the title.
    since: "3.3.0"
    platforms: [iphone, ipad, macos]
    type: titleAttributesParams

  - name: titleColor
    summary: Defines the color of the title of tab when it's inactive.
    description: |
        The color of the title of the tab when it's inactive.
    type: [String, Titanium.UI.Color]
    since: {iphone: "9.0.3", ipad: "9.0.3", android: "9.0.3"}
    platforms: [iphone, ipad, android, macos]

  - name: activeTitleColor
    summary: Defines the color of the title of tab when it's active.
    description: |
        The color of the title of the tab when it's active.
    type: [String, Titanium.UI.Color]
    since: {iphone: "9.0.3", ipad: "9.0.3", android: "9.0.3"}
    platforms: [iphone, ipad, android, macos]

  - name: navTintColor
    summary: The tintColor to apply to the navigation bar (typically for the **More** tab).
    description: |
        This property is a direct correspondant of the tintColor property of NavigationBar on iOS.
    type: [String, Titanium.UI.Color]
    since: "3.3.0"
    default: null
    osver: {ios: {min: "7.0"}}
    platforms: [iphone,ipad, macos]

  - name: editButtonTitle
    summary: Title for the edit button on the **More** tab.
    type: String
    platforms: [iphone, ipad, macos]

  - name: exitOnClose
    summary: |
        Boolean value indicating if the application should exit when closing the tab group, whether via Android
        back button or the [close](Titanium.UI.TabGroup.close) method.
    description:  |
        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.
    platforms: [android]
    default: True if tab group is opened on top of the root activity. False otherwise.
    type: Boolean

  - name: swipeable
    summary: |
        Boolean value indicating if tab navigation can be done by swipes, in addition to tab clicks.
    description: |
        On Android, the tabs may be selected by swipes, in addition to clicks. This property may be set at
        tab group creation, or any time later as long as the tab navigation is not disabled.
    platforms: [android]
    since: 3.6.0
    default: true
    type: Boolean

  - name: smoothScrollOnTabClick
    summary: |
        Boolean value indicating if changing pages by tab clicks is animated.
    description: |
        If true, when clicking the tab the page transition is animated, false otherwise.
    platforms: [android]
    since: 3.6.0
    default: true
    type: Boolean

  - name: tabs
    summary: |
        Tabs managed by the tab group.
    type: Array<Titanium.UI.Tab>

  - name: windowSoftInputMode
    summary: |
        Determines how the tab group is treated when a soft input method (such as a virtual keyboard)
        is displayed.
    description: |
        For more information see the official Android API Reference,
        [Window.setSoftInputMode](https://developer.android.com/reference/android/view/Window.html#setSoftInputMode(int)).
    type: Number
    constants: Titanium.UI.Android.SOFT_INPUT_ADJUST_*
    availability: creation
    platforms: [android]

  - name: shiftMode
    summary: Determines whether the [TABS_STYLE_BOTTOM_NAVIGATION](Titanium.UI.Android.TABS_STYLE_BOTTOM_NAVIGATION) uses shiftMode.
    description: |
        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.

        NOTE: This property only affects TabGroups with the [TABS_STYLE_BOTTOM_NAVIGATION](Titanium.UI.Android.TABS_STYLE_BOTTOM_NAVIGATION).
    type: Boolean
    default: true
    since: "8.0.0"
    platforms: [android]

  - name: style
    summary: Property defining which style for the TabGroup to be used.
    description: |
        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_BOTTOM_DEFAULT](Titanium.UI.Android.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](Titanium.UI.Android.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.

    availability: creation
    constants: Titanium.UI.Android.TABS_STYLE_*
    since: "8.0.0"
    type: Number
    platforms: [android]

  - name: tabsBackgroundColor
    summary: Default background color for inactive tabs, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.

        A tab's [backgroundColor](Titanium.UI.Tab.backgroundColor) property takes precedence if set.

        This property applies to all states and tabs, not just inactive tabs. Furthermore, the inactive 
        tab icons without activeIcon will be tinted this color.
    type: [String, Titanium.UI.Color]
    since: {android: "3.0.0", iphone: "3.0.0", ipad: "3.0.0"}
    platforms: [android, iphone, ipad, macos]

  - name: tabsTintColor
    summary: The tintColor to apply to the tabs.
    description: |
        This property is a direct correspondant of the tintColor property of UITabBar on iOS. This effects the
        title and icons rendered in the active tab. When not specified the active icons are tinted with a bright
        blue.
    type: [String, Titanium.UI.Color]
    since: "3.1.3"
    default: null
    platforms: [iphone, ipad, macos]
    deprecated:
        since: "9.0.3"
        notes: Deprecated in favor of [Titanium.UI.TabGroup.tintColor](Titanium.UI.TabGroup.tintColor) or alternatively [Titanium.UI.Tab.tintColor](Titanium.UI.Tab.tintColor).

  - name: tabsTranslucent
    summary: A Boolean value that indicates whether the tab bar is translucent.
    description: |
        When the value of this property is `true`, the tab group adds a translucent effect to its background
        image or tint color. When translucency is enabled, part of the tab bar's underlying content is able
        to show through, although the amount that shows through depends on the rest of the tab bar configuration.
        For example, a background image can wholly or partially obscure the background content. Setting this
        property to NO causes the tab bar to render its bar tint color or background image on top of an opaque backdrop.

        The default value of this property is dependent on the configuration of the tab bar:
          * The default value is `true` when the tab bar does not have a custom background image.
          * The default value is `true` when a custom background image contains any transparency - that is,
            at least one pixel has an alpha value of less than 1.0.
          * The default value is `false` when the custom background image is completely opaque - that is,
            all pixels have an alpha value of 1.0.
    type: Boolean
    since: "6.2.0"
    default: true
    platforms: [iphone, ipad, macos]

  - name: activeTintColor
    summary: The activeTintColor to apply to tabs.
    description: |
        This property affects the tint of selected tab icons.
    type: String
    since: "9.0.3"
    default: null
    platforms: [iphone, ipad, android, macos]

  - name: tintColor
    summary: The tintColor to apply to tabs.
    description: |
        This property affects the tint of unselected tab icons.
    type: String
    since: "9.0.3"
    default: null
    platforms: [iphone, ipad, android, macos]

  - name: title
    summary: Title for this tabGroup.
    type: String
    since: '3.3.0'
    platforms: [android]

  - name: tabsBackgroundImage
    summary: Default background image for tabs.
    type: String
    platforms: [iphone, ipad, macos]
    since: { iphone: "3.1.0", ipad: "3.1.0" }
    osver: {ios: {min: "5.0"}}

  - name: unselectedItemTintColor
    summary: |
        Unselected items in this tab group will be tinted with this color. Setting this value to null
        indicates that the tab group should use its default value instead.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: [String, Titanium.UI.Color]
    since: 6.1.0
    osver: {ios: {min: "10.0"}}
    platforms: [iphone, ipad, macos]
    deprecated:
        since: "9.0.3"
        notes: Deprecated in favor of [Titanium.UI.TabGroup.tintColor](Titanium.UI.TabGroup.tintColor) or alternatively [Titanium.UI.Tab.tintColor](Titanium.UI.Tab.tintColor).

  - name: shadowImage
    summary: Image of the shadow placed between the tab bar and the content area.
    description: |
        The <Titanium.UI.TabGroup.tabsBackgroundImage> property must also be set 
        in order for this to take effect.
    type: String
    platforms: [iphone, ipad, macos]
    since: { iphone: "3.1.0", ipad: "3.1.0" }

  - name: activeTabIconTint
    summary: Color applied to active tabs icons, as a color name or hex triplet, where the tab's activeIcon was not defined.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: [String, Titanium.UI.Color]
    since: {iphone: "3.1.0", ipad: "3.1.0" }
    osver: {ios: {min: "5.0"}}
    platforms: [iphone, ipad, macos]
    deprecated:
        since: "9.0.3"
        notes: Deprecated in favor of [Titanium.UI.TabGroup.activeTintColor](Titanium.UI.TabGroup.activeTintColor) or alternatively [Titanium.UI.Tab.activeTintColor](Titanium.UI.Tab.activeTintColor).

  - name: tabsBackgroundSelectedColor
    summary: Default background selected color for tabs, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.

        A tab's [backgroundSelectedColor](Titanium.UI.Tab.backgroundSelectedColor) property takes
        precedence if set.
    type: String
    platforms: [android]
    since: {android: "3.0.0"}

  - name: activeTabBackgroundImage
    summary: Default background image for the active tab.
    type: String
    platforms: [iphone, ipad, macos]
    since: { iphone: "3.1.0", ipad: "3.1.0" }
    osver: {ios: {min: "5.0"}}

examples:
  - title: Alloy XML Markup
    example: |
        Default Titanium project as an Alloy view.

        ``` xml
        <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>
        ```

  - title: Classic Titanium Example
    example: |
        Simple two-tabbed app.

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