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 and Mobile Web, 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/Mobile Web-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/library/ios/documentation/userexperience/conceptual/mobilehig/Bars.html#//apple_ref/doc/uid/TP40006556-CH12-SW52).

extends: Titanium.UI.View
since: "0.9"
excludes:
    methods: [add, remove, removeAllChildren]
    properties: [accessibilityHidden,accessibilityHint,accessibilityLabel,accessibilityValue,
                 anchorPoint,animatedCenter,backgroundColor,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:
  - 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]
    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.
    platforms: [iphone, ipad, mobileweb]

  - 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]
    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"
        notes: Use <Titanium.UI.Tab.focus> 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"
        notes: Use <Titanium.UI.Tab.blur> 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, mobileweb]
    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: 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]
    
  - 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
    platforms: [iphone, ipad]
    
  - name: translucent
    summary: Boolean value indicating if the nav bar (typically for the **More** tab), is translucent.
    platforms: [iphone, ipad]
    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]
    type: titleAttributesParams

  - name: navTintColor
    summary: The tintColor to apply to the navigation bar (typically for the **More** tab). This property is applicable on iOS 7 and greater. 
    description: |
        This property is a direct correspondant of the tintColor property of NavigationBar on iOS.
    type: [String]
    since: "3.3.0"
    default: null
    osver: {ios: {min: "7.0"}}
    platforms: [iphone,ipad]
    
  - name: editButtonTitle
    summary: Title for the edit button on the **More** tab.
    type: String
    platforms: [iphone, ipad]
    
  - 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](http://developer.android.com/reference/android/view/Window.html#setSoftInputMode(int)).
    type: Number
    constants: Titanium.UI.Android.SOFT_INPUT_ADJUST_*
    availability: creation
    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.

        On iOS 5.0 or later, this property applies to all states and tabs, not just inactive
        tabs. Furthermore, the inactive tab icons without activeIcon will be tinted this color;
        property is ignored on earlier versions of iOS.
    type: String
    since: {android: "3.0.0", iphone: "3.0.0", ipad: "3.0.0", mobileweb: "2.0.0"}
    osver: {ios: {min: "5.0"}}
    platforms: [android, iphone, ipad, mobileweb]
    
  - name: tabsTintColor
    summary: The tintColor to apply to the tabs. This property is applicable on iOS 7 and greater. 
    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 on iOS7.
    type: [String]
    since: "3.1.3"
    default: null
    osver: {ios: {min: "7.0"}}
    platforms: [iphone,ipad]

  - name: title
    summary: Title for this tabGroup.
    type: String
    since: '3.3.0'
    platforms: [android]  
 
  - name: tabsBackgroundImage
    summary: Default background image for tabs.
    description: |
        On Mobile Web, a tab's [backgroundImage](Titanium.UI.Tab.backgroundImage) property takes precedence if set.
        
        On iOS, requires iOS 5.0 or later; ignored on earlier versions.
    type: String
    platforms: [mobileweb, iphone, ipad]
    since: { mobileweb: "2.0.0", 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
    since: 6.1.0
    osver: {ios: {min: "10.0"}}
    platforms: [iphone, ipad]

  - name: shadowImage
    summary: Image of the shadow placed between the tab bar and the content area.
    description: |
        On iOS, requires iOS 6.0 or later; ignored on earlier versions. TabsBackgroundImage
        must also be set in order for this to take effect.
    type: String
    platforms: [iphone,ipad]
    since: { iphone: "3.1.0", ipad: "3.1.0" }
    osver: {ios: {min: "6.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>.
        On iOS, requires iOS 5.0 or later; ignored on earlier versions.
    type: String
    since: {iphone: "3.1.0", ipad: "3.1.0" }
    osver: {ios: {min: "5.0"}}
    platforms: [iphone, ipad]
    
  - name: tabsBackgroundDisabledColor
    summary: Default background disabled 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 [backgroundDisabledColor](Titanium.UI.Tab.backgroundDisabledColor) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: tabsBackgroundDisabledImage
    summary: Default background disabled image for tabs.
    description: |
        A tab's [backgroundDisabledImage](Titanium.UI.Tab.backgroundDisabledImage) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: tabsBackgroundFocusedColor
    summary: Default background focused 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 [backgroundFocusedColor](Titanium.UI.Tab.backgroundFocusedColor) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: tabsBackgroundFocusedImage
    summary: Default background focused image for tabs.
    description: |
        A tab's [backgroundFocusedImage](Titanium.UI.Tab.backgroundFocusedImage) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - 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, mobileweb]
    since: {android: "3.0.0", mobileweb: "2.0.0"}
    
  - name: tabsBackgroundSelectedImage
    summary: Default background selected image for tabs.
    description: |
        A tab's [backgroundSelectedImage](Titanium.UI.Tab.backgroundSelectedImage) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: activeTabBackgroundColor
    summary: Default background color for the active tab, 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.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: activeTabBackgroundImage
    summary: Default background image for the active tab.
    description: |
        On Mobile Web, a tab's [backgroundImage](Titanium.UI.Tab.backgroundImage) property takes precedence if set.
    type: String
    platforms: [mobileweb, iphone, ipad]
    since: { mobileweb: "2.0.0", iphone: "3.1.0", ipad: "3.1.0" }
    osver: {ios: {min: "5.0"}}
    
  - name: activeTabBackgroundDisabledColor
    summary: Default background disabled color for the active tab, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>. 
        
        A tab's [backgroundDisabledColor](Titanium.UI.Tab.backgroundDisabledColor) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: activeTabBackgroundDisabledImage
    summary: Default background disabled image for the active tab.
    description: |
        A tab's [backgroundDisabledImage](Titanium.UI.Tab.backgroundDisabledImage) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: activeTabBackgroundFocusedColor
    summary: Default background focused color for the active tab, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>. 
        
        A tab's [backgroundFocusedColor](Titanium.UI.Tab.backgroundFocusedColor) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: activeTabBackgroundFocusedImage
    summary: Default background focused image for the active tab.
    description: |
        A tab's [backgroundFocusedImage](Titanium.UI.Tab.backgroundFocusedImage) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: activeTabBackgroundSelectedColor
    summary: Default background selected color for the active tab, 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: [mobileweb]
    since: "2.0.0"
    
  - name: activeTabBackgroundSelectedImage
    summary: Default background selected image for the active tab.
    description: |
        A tab's [backgroundSelectedImage](Titanium.UI.Tab.backgroundSelectedImage) property takes 
        precedence if set.
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: tabDividerColor
    summary: Color of the divider between tabs, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>. 
    type: String
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: tabDividerWidth
    summary: Width of the divider between tabs.
    description: |
        This width is relative to the tabgroup's parent. Can be either a float value or 
        a dimension string (for example, `'50%'` or `75dp`).
    type: [Number, String]
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: tabHeight
    summary: Height of the tabs.
    description: |
        This height is relative to the tabgroup's parent. Can be either a float value or 
        a dimension string (for example, `'50%'` or `'75dp'`).
    type: [Number, String]
    platforms: [mobileweb]
    since: "2.0.0"
    
  - name: tabsAtBottom
    summary: |
        Determines whether the tabs should be positioned at the top rather than the bottom of the 
        screen.
    description: Set to `false` to position tabs at the top of the screen.
    type: Boolean
    default: true
    platforms: [mobileweb]
    since: "2.0.0"

examples:
  - title: Alloy XML Markup
    example: |
        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>

  - title: Classic Titanium Example
    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();