Tab.yml

---
name: Titanium.UI.Tab
summary: A tab instance for a [TabGroup](Titanium.UI.TabGroup).
description: |
    A `TabGroup` tab instance. Each tab includes a button and one or more windows, which 
    holds the "contents" of the tab. Users can select a tab by clicking on the tab button.

    Use the <Titanium.UI.createTab> method or **`<Tab>`** Alloy element to create a tab.

    Use [TabGroup.setActiveTab](Titanium.UI.TabGroup.setActiveTab) to switch between tabs 
    in a tab group. The <Titanium.UI.currentTab> property provides a global reference to 
    the currently active tab. 
    
    The behavior of tabs and tab groups follows the platform's native navigation style, 
    which varies significantly between platforms.

    #### iOS and Mobile Web Platform Implementation Notes

    On iOS and Mobile Web, the tab maintains a stack of windows. On Mobile Web, the tab is
    really just a [NavigationGroup](Titanium.UI.MobileWeb.NavigationGroup). Windows on top 
    of the stack can partially or totally obscure windows lower in the stack.  Calling 
    [open](Titanium.UI.Tab.open) opens a new window on top of the window stack. When a window 
    is closed, either by the user or by code, the window is removed from the stack, making 
    the previous window visible. The root tab window cannot be removed. 
    
    On iOS and Mobile Web the tab controls are generally kept on screen to allow a user to
    navigate inside the app. Tab controls are hidden when the user is performing a modal 
    task (for example, composing a message). In this case, the app should provide a button 
    in the navigation bar to return to the previous screen. On iOS, the window should also 
    be opened as modal. On iOS, The tab controls can also be hidden by opening the new window 
    with [tabBarHidden](Titanium.UI.Window.tabBarHidden) set to `true`.
    
    When closing a tab window in iOS and Mobile Web, you should always use the
    [Tab.close](Titanium.UI.Tab.close) method to ensure that the tab group maintains its 
    navigation state.

    #### Android Platform Implementation Notes

    On Android, the tab does not maintain a stack of windows. 
    Calling [open](Titanium.UI.Tab.open) opens a new, heavyweight window, which 
    by default covers the tab group entirely. This seems quite different from the iOS model,
    but it is the standard model for Android applications. Users can use the **Back** button 
    to close the window and return to the tab group. 

    On Android, tab windows can be closed using either
    [Tab.close](Titanium.UI.Tab.close) or [Window.close](Titanium.UI.Window.close). Since 
    no window stack is maintained, only a single window opened using
    [Tab.open](Titanium.UI.Tab.open) can be closed using `Tab.close`.

    As on iOS, the root tab window cannot be closed.
extends: Titanium.UI.View
since: "0.8"
excludes:
    events: [pinch, keypressed, longclick, twofingertap]
    methods: [add, animate, hide, remove, removeAllChildren, show]
    properties: [accessibilityHidden,accessibilityHint,accessibilityLabel,accessibilityValue,
                 anchorPoint,animatedCenter,backgroundGradient,backgroundLeftCap,
                 backgroundRepeat,backgroundTopCap,borderColor,borderRadius,borderWidth,
                 bottom,center,children,enabled,focusable,height,horizontalWrap,keepScreenOn,
                 layout,left,opacity,rect,right,size,softKeyboardOnFocus,
                 top,transform,visible,width,zIndex]

methods:
  - name: open
    summary: Opens a new window.
    description: On iOS and Mobile Web, the new window is opened as the top window
        in the tab's window stack. On Android, the new window is opened as a new, 
        heavyweight window, obscuring the tab group.
    parameters: 
      - name: window
        summary: Window to open.
        type: Titanium.UI.Window
      - name: options
        summary: |
            Dictionary of display and animation settings to use when opening the window. 
            Identical to the `options` parameter to [Window.open](Titanium.UI.Window.open).
            iOS only supports the **animated** parameter.
        type: Object

  - name: close
    summary: Closes the top-level window for this tab. 
    description: |
        On iOS, this method should be used when closing a window opened from a tab, to
        correctly maintain the iOS tab group's navigation state. Note that the window to 
        be closed **must** be passed in as a parameter:

            myTab.close(tabWin);

        On Android, this method does **not** take a `window` parameter.

            myTab.close();

        On Mobile Web, calling `Tab.close` is identical to calling `close` on
        the tab's current topmost window.

        On Android, if a window has been opened in front of the tab using `Tab.open`, 
        a subsequent call to `Tab.close` is equivalent to calling `close` on that window.
        No window stack is maintained, so only the most-recently opened window on a given
        tab can be closed in this way.

        All platforms accept an optional `options` parameter. The only supported property
        for this dictionary is the `animated` flag, which specifies whether the window
        close should be animated. `animated` is true by default.
    parameters: 
      - name: window
        summary: |
            Window to close. This parameter **must** be omitted on Android.
        type: Titanium.UI.Window

      - name: options
        summary: |
            Dictionary of display and animation settings to use when closing the window. 
            Identical to the `options` parameter to [Window.close](Titanium.UI.Window.close).
            iOS only supports the **animated** parameter.
        type: Object
        optional: true

  - name: setWindow
    summary: Sets the root window that appears in the tab.
    description: |
        You can only use this method to set the tab's root window before the TabGroup containing this tab
        is openened, that is, once the TabGroup is displayed, you cannot change the root window
        that appears in the tab.
    parameters:
      - name: window
        summary: Root window of the tab.
        type: Titanium.UI.Window

properties:
  - name: active
    summary: |
        `true` if this tab is active, `false` if it is not. 
    description: |
         The tab can be activated by setting the property, but since this property is 
         platform-specific, using [TabGroup.setActiveTab](Titanium.UI.TabGroup.setActiveTab) 
         is recommended instead.
    type: Boolean
    platforms: [iphone, ipad, mobileweb]

  - name: activeIcon
    summary: Icon URL for this tab when active.
    description: |
         iOS 5.0 and later only.

         If unspecified, iOS uses a tint color to indicate the active tab. See
         [icon](Titanium.UI.Tab.icon) for more information.

         If the icon provided is larger than [30 pixels (60 pixels in the retina variant)]
         (https://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/MobileHIG/IconsImages/IconsImages.html),
         this image will be scaled to fit.

         On iOS prior to 5.0, the default tint color is always used and this property
         remains unset.
    type: String
    platforms: [iphone, ipad]
    since: "3.1.0"
    osver: {ios: {min: "5.0"}}

  - name: backgroundColor
    summary: Sets the color of the tab when it is inactive.
    description: For information about color values, see the "Colors" section of <Titanium.UI>.
    platforms: [android, mobileweb]
    since: {android: 3.0.0}

  - name: backgroundDisabledColor
    platforms: [mobileweb]

  - name: backgroundDisabledImage
    platforms: [mobileweb]

  - name: backgroundFocusedColor
    summary: Sets the color of the tab when it is focused.
    description: |
        On the Android platform, this sets the color of the active tab.

        For information about color values, see the "Colors" section of <Titanium.UI>.
    platforms: [android, mobileweb]
    since: {android: 3.0.0}

  - name: backgroundFocusedImage
    platforms: [mobileweb]

  - name: backgroundImage
    platforms: [mobileweb]

  - name: backgroundSelectedImage
    platforms: [mobileweb]

  - name: badge
    summary: Badge value for this tab. `null` indicates no badge.
    type: String
    platforms: [iphone,ipad]

  - name: badgeColor
    summary: |
        If this item displays a badge, this color will be used for the badge's background. 
        If set to null, the default background color will be used 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: icon
    summary: Icon URL for this tab.
    description: |
        #### iOS Tab Icons

        On iOS, tab icons are usually white with a transparent background. The system uses
        a transparent tint color to indicate whether the tab is active or inactive. In the
        inactive state, the tint color is based on the tab bar's color
        [tabsBackgroundColor](Titanium.UI.TabGroup.tabsBackgroundColor), which defaults
        to black. In the active state, the tint color is usually blue. Prior to Titanium
        3.1, there was no way to override the default active icon tint.
        
        Titanium 3.1 introduced some new ways to customize tab icons, which are supported
        in iOS 5.0 and above:

        *   You can specify the active tab's tint color as
        [activeTabIconTint](Titanium.UI.TabGroup.activeTabIconTint).

        *   You can set separate icon images for the active and inactive states. If
        [activeIcon](Titanium.UI.Tab.activeIcon) is set, then `icon` is used in the
        inactive state, and `activeIcon` is used in the active state. **No default tint
        is applied to either icon.**

         If the icon provided is larger than [30 pixels (60 pixels in the retina variant)]
         (https://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/MobileHIG/IconsImages/IconsImages.html),
         this image will be scaled to fit if used with activeIcon, and cropped at the bottom
         otherwise.
    type: String

  - name: iconInsets
    summary: The icon inset or outset for each edge.
    description: | 
        Use this property for example to center an icon without providing a title. To do that, set the
        insets to `{top:6}` and/or `{left:6}`. The `right` and `bottom` are calculated internally to prevent the
        icon from mutating.
    since: "5.2.0"
    default: All insets are zero.
    type: TabIconInsets
    platforms: [iphone,ipad]

  - name: iconIsMask
    summary: Defines if the icon property of the tab must be used as a mask. This property is applicable on iOS 7 and greater. 
    description: |
        When this property is true, the color data of the image specified as the icon is ignored and the image is used as an alpha mask. 
        When this is false, the color data of the image is preserved.
    type: [Boolean]
    since: "3.1.3"
    default: true
    osver: {ios: {min: "7.0"}}
    platforms: [iphone,ipad]
    
  - name: activeIconIsMask
    summary: Defines if the active icon property of the tab must be used as a mask. This property is applicable on iOS 7 and greater. 
    description: |
        This is the equivalent of the [iconIsMask](Titanium.UI.Tab.iconIsMask) property, but for the active icon. When this is true, the active icon is 
        tinted with the color specified in [tabsTintColor](Titanium.UI.TabGroup.tabsTintColor). When this is false the image is rendered as is, though the 
        title of the tab is still tinted. 
    type: [Boolean]
    since: "3.1.3"
    default: true
    osver: {ios: {min: "7.0"}}
    platforms: [iphone,ipad]
    
  - name: title
    summary: Title for this tab.
    type: String

  - name: titleid
    summary: Key identifying a string from the locale file to use for the tab title. Only one of `title` or `titleid` should be specified.
    type: String

  - 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. If not defined, it will use the default tint color.
    type: String
    since: "4.1.0"
    osver: {ios: {min: "5.0"}}
    platforms: [iphone,ipad]

  - 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. If not defined, it will use the default tint color.
    type: String
    since: "4.1.0"
    osver: {ios: {min: "5.0"}}
    platforms: [iphone,ipad]

  - name: touchEnabled
    platforms: [mobileweb]

  - name: window
    summary: Root-level tab window.  All tabs must have at least one root-level tab window.
    type: Titanium.UI.Window
    availability: creation

events: 
  - name: blur
    summary: Fired when the tab loses focus.
    deprecated:
        since: "5.2.0"
        notes: Use <Titanium.UI.Tab.unselected> 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: Current active tab object.
        type: Titanium.UI.Tab
      - name: previousTab
        summary: Previous active tab object.
        type: Titanium.UI.Tab
    platforms: [android, iphone, ipad, mobileweb]

  - name: unselected
    summary: Fired when the tab is no longer selected.
    since: {android: "3.5.1 ",  iphone: "5.2.0", ipad: "5.2.0"}
    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: Current active tab object.
        type: Titanium.UI.Tab
      - name: previousTab
        summary: Previous active tab object.
        type: Titanium.UI.Tab
    platforms: [android, iphone, ipad, mobileweb]

  - name: click
    summary: Fired when this tab is clicked in the tab group.
    exclude-platforms: [iphone, ipad]

  - name: dblclick
    platforms: [mobileweb]

  - name: doubletap
    platforms: [mobileweb]

  - name: focus
    summary: Fired when the tab gains focus.
    deprecated:
        since: "5.2.0"
        notes: Use <Titanium.UI.Tab.selected> 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: Current active tab object.
        type: Titanium.UI.Tab
      - name: previousTab
        summary: Previous active tab object.
        type: Titanium.UI.Tab
    platforms: [android, iphone, ipad, mobileweb]

  - name: selected
    summary: Fired when the tab is selected.
    since: {android: "3.5.1 ",  iphone: "5.2.0", ipad: "5.2.0"}
    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: Current active tab object.
        type: Titanium.UI.Tab
      - name: previousTab
        summary: Previous active tab object.
        type: Titanium.UI.Tab
    platforms: [android, iphone, ipad, mobileweb]

  - name: longpress
    platforms: [mobileweb]

  - name: postlayout
    platforms: [mobileweb]

  - name: selected
    summary: Fired when the tab is selected.
    platforms: [android]
    since: "3.6.0"

  - name: singletap
    platforms: [mobileweb]

  - name: swipe
    platforms: [mobileweb]

  - name: touchcancel
    platforms: [mobileweb]

  - name: touchend
    platforms: [mobileweb]

  - name: touchmove
    platforms: [mobileweb]

  - name: touchstart
    platforms: [mobileweb]

  - name: unselected
    summary: Fired when the tab is unselected.
    platforms: [android]
    since: "3.6.0"

examples:
  - title: Simple Tab Example
    example: |
        
        In this example, we create a simple tab and add it to a tab group.
        
            var mywin = Titanium.UI.createWindow({title: "Hello"});
            var tab = Titanium.UI.createTab({
            	window:mywin,
            	title:'Hello',
            	icon:'myicon.png'
            });
            tabGroup.addTab(tab);

  - title: Alloy XML Markup
    example: |
        Previous example an an Alloy view.

            <Alloy>
                <TabGroup id="tabGroup">
                    <Tab id="tab" title="Hello" icon="myicon.png">
                        <Window id="mywin" title="Hello"/>
                    </Tab>
                 </TabGroup>
            </Alloy>

---
name: TabIconInsets
summary: Dictionary to specify edge insets for <Titanium.UI.Tab.iconInsets>.
since: "5.2.0"
platforms: [iphone, ipad]
properties:
  - name: top 
    summary: Top inset.
    type: Number

  - name: left
    summary: Left inset.
    type: Number