listview-spec-v1.yml

---
name: Titanium.UI
extends: Titanium.Module
methods:
  - name: createListView
    summary: creates a new instance of [View](Titanium.UI.ListView)
    parameters:
      - name: parameters
        type: Dictionary<Titanium.UI.ListView>

  - name: createListSection
    summary: creates a new instance of [Section](Titanium.UI.ListSection)
    parameters:
      - name: parameters
        type: Dictionary<Titanium.UI.ListSection>

properties:
  - name: LIST_ITEM_TEMPLATE_DEFAULT
    summary: A built-in style for an item with a text label (black and left-aligned) and an optional image view on iOS
    description: |
        The text label value binds to 'title' property in data entry and the image value binds to the 'image' property

  - name: LIST_ITEM_TEMPLATE_SETTINGS
    summary: A built-in style for an item with a label on the left side of the cell with left-aligned and black text; on the right side is a label that has smaller blue text and is right-aligned
    description: |
        The text label value binds to 'title' property in a data entry. Small text label value binds to 'subtitle' property in a data entry.
    platforms: [iphone, ipad]

  - name: LIST_ITEM_TEMPLATE_CONTACTS
    summary: A built-in style for a item with a label on the left side of the cell with text that is right-aligned and blue; on the right side of the cell is another label with smaller text that is left-aligned and black
    description: |
        The text label value binds to 'title' property in a data entry. Small text label value binds to 'subtitle' property in a data entry
    platforms: [iphone, ipad]

  - name: LIST_ITEM_TEMPLATE_SUBTITLE
    summary: A built-in style for a item with a left-aligned label across the top and a left-aligned label below it in smaller gray text
    description: |
        The text label value binds to 'title' property in a data entry. Small text label value binds to 'subtitle' property in a data entry
    platforms: [iphone, ipad]

  - name: LIST_ACCESSORY_TYPE_NONE
    summary: ...
    platforms: [iphone, ipad]

  - name: LIST_ACCESSORY_TYPE_CHECKMARK
    summary: ...
    description: |
      You use a checkmark when a touch on a row results in the selection of that item. This kind of table view is known as a selection list, and it is analogous to a pop-up list. Selection lists can limit selections to one row, or they can allow multiple rows with checkmarks.
    platforms: [iphone, ipad]

  - name: LIST_ACCESSORY_TYPE_DETAIL
    summary: ...
    description: |
      You use the detail disclosure button when selecting a cell results in a detail view of that item.
    platforms: [iphone, ipad]

  - name: LIST_ACCESSORY_TYPE_DISCLOSURE
    summary: ...
    description: |
      You use the disclosure indicator when selecting a cell results in the display of another table view reflecting the next level in the data model hierarchy.
    platforms: [iphone, ipad]

examples:
  - title: Example
    example: |
        Complete example
            
            

---
name: Titanium.UI.ListView
extends: Titanium.UI.View
events:
  - name: itemclick
    summary: Fired when a list row is clicked by the user.
    properties:

      - name: section
        type: Titanium.UI.ListSection

      - name: sectionIndex
        type: Number

      - name: itemIndex
        type: Number

      - name: itemId
        summary: The value of the itemId bound to the view that generated the event
        type: string

      - name: bindId
        summary: The bind id of the control that generated this event, if one exists
        type: String

      - name: accessoryClicked
        type: Boolean
        platforms: [iphone, ipad]

# All other events with custom data

    properties:

      - name: section
        type: Titanium.UI.ListSection

      - name: sectionIndex
        type: Number

      - name: itemIndex
        type: Number

      - name: itemId
        summary: The value of the itemId bound to the view that generated the event
        type: string

      - name: bindId
        summary: The bind id of the control that generated this event, if one exists
        type: String

properties:

# New properties

  - name: templates
    type: Dictionary<ItemTemplate>
    summary: Holds mappings between item style names and their definitions

  - name: sections
    type: Array<Titanium.UI.ListSection>
    summary: Holds a list of available sections

  - name: defaultItemTemplate
    type: String

# Old properties going into v1

  - name: backgroundColor
    summary: Background color of the view, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: String

  - name: footerTitle
    summary: List view footer title.
    type: String

  - name: headerTitle
    summary: List view header title.
    type: String

  - name: scrollIndicatorStyle
    summary: |
        Style of the scrollbar, specified using one of the constants from
        <Titanium.UI.iPhone.ScrollIndicatorStyle>.
    type: Number
    default: <Titanium.UI.iPhone.ScrollIndicatorStyle.DEFAULT>
    platforms: [iphone, ipad]

  - name: willScrollOnStatusTap
    summary: Controls whether the scroll-to-top gesture is effective.
    description: |
        The scroll-to-top gesture is a tap on the status bar; The default value of this property is true.
        This gesture works when you have a single visible list view.
        If there are multiple list views, table views, web views, text areas, and/or scroll views visible,
        you will need to disable (set to false) on the above views you DON'T want this
        behaviour on. The remaining view will then respond to scroll-to-top gesture.
    type: Boolean
    default: true
    platforms: [iphone,ipad]

  - name: sectionCount
    summary: Number of sections in this list view.
    type: Number
    permission: read-only

  - name: showVerticalScrollIndicator
    summary: Determines whether this list view displays a vertical scroll indicator.
    description: Set to `false` to hide the vertical scroll indicator.
    type: Boolean
    default: true

  - name: style
    summary: |
        Style of the list view, specified using one of the constants from
        <Titanium.UI.iPhone.ListViewStyle>.
    description: Style should always be set before setting the `data` on list view.
    type: Number
    platforms: [iphone, ipad]

  - name: rowHeight
    summary: Default row height for list view rows.
    type: Number

methods:

# New methods

  - name: scrollToItem
    summary: Scrolls to a specific item
    parameters:
      - name: sectionIndex
        type: Number

      - name: itemIndex
        type: Number

      - name: animation
        summary: Animation properties. (iOS only.)
        type: ListViewAnimationProperties
        optional: true

  - name: selectItem
    summary: Selects a specific item
    parameters:
      - name: sectionIndex
        type: Number

      - name: itemIndex
        type: Number
    platforms: [iphone, ipad]

# Old methods going into v1

  - name: appendSection
    summary: Appends a single section or an array of sections to the end of the list.
    description: |
        On iOS, the section(s) can be inserted with animation by specifying a `properties` parameter.
    parameters:
      - name: section
        summary: Section or sections to add to the list.
        type: [Titanium.UI.ListSection, Array<Titanium.UI.ListSection>]

      - name: animation
        summary: Animation properties. (iOS only.)
        type: ListViewAnimationProperties
        optional: true

  - name: deleteSectionAt
    summary: Deletes an existing section.
    description: |
        On iOS, the section can be deleted with animation by specifying a `properties` parameter.
    parameters:
      - name: sectionIndex
        summary: Index of the section to delete.
        type: Number

      - name: animation
        summary: Animation properties. (iOS only.)
        type: ListViewAnimationProperties
        optional: true

  - name: insertSectionAt
    summary: Inserts a section or an array of sections at a specific index.
    description: |
        Existing sections at that index and after are pushed down.
        
        On iOS, the section(s) may be inserted with animation by setting the `animation` parameter.
    parameters:
      - name: sectionIndex
        summary: Index of the section to insert before.
        type: Number

      - name: section
        summary: Section or sections to insert.
        type: [Titanium.UI.ListSection, Array<Titanium.UI.ListSection>]

      - name: animation
        summary: Animation properties. (iOS only.)
        type: ListViewAnimationProperties
        optional: true

  - name: replaceSectionAt
    summary: Replaces an existing section, optionally with animation
    parameters:
      - name: sectionIndex
        summary: Index of the section to update.
        type: Number

      - name: section
        summary: section data to update.
        type: Titanium.UI.ListSection

      - name: animation
        summary: Animation properties. (iOS only.)
        type: ListViewAnimationProperties

# Old methods going into v2

  - name: setContentInsets
    summary: Sets this list's content insets.
    description: |
        A list is essentially a scroll view that contains a set of static row views that
        represents the content. Thus, the `setContentInsets` method facilitates a margin, or inset,
        distance between the content and the container scroll view.
        
        Typically used with the [headerPullView](Titanium.UI.ListView.headerPullView) property.
    parameters:
      - name: edgeInsets
        summary: Dictionary to describe the insets.
        type: ListViewEdgeInsets

      - name: animated
        summary: Determines whether, and how, the content inset change should be animated.
        type: ListViewContentInsetOption
        optional: true
    platforms: [iphone, ipad]

---
name: ListViewAnimationProperties
summary: A simple object for specifying the animation properties to use when inserting or deleting sections or cells, or scrolling the list.
description: |
    These properties are only used on iOS. Not all properties apply to all methods.
    
    `animationStyle` does not apply to the `scrollToTop` or `scrollToIndex` methods.
    
    `positon` only applies to the `scrollToIndex` method.
properties:
  - name: animated
    summary: Whether this list change should be animated. Ignored if any `animationStyle` value is specified.
    type: Boolean
    default: true
    
  - name: animationStyle
    summary: Type of animation to use for cell insertions and deletions. One of the animation style constants defined in <Titanium.UI.iPhone.RowAnimationStyle>.
    type: Number
    default: |
        If `animated` is `true` but no `animationStyle` is specified, the style defaults to 
        [FADE](Titanium.UI.iPhone.RowAnimationStyle.FADE).
        
  - name: position
    summary: |
        Specifies what position to scroll the selected cell to. One of the position constants from 
        <Titanium.UI.iPhone.ListViewScrollPosition>.
    type: Number
    default: <Titanium.UI.iPhone.ListViewScrollPosition.NONE>

---
name: Titanium.UI.iPhone.ListViewCellSelectionStyle
summary: |
    A set of constants for the style that can be used for the `selectionStyle` property of 
    <Titanium.UI.ListItem>.
extends: Titanium.Proxy
platforms: [iphone, ipad]
createable: false

properties:
  - name: BLUE
    summary: The cell when selected has a blue background. This is the default value.
    type: Number
    permission: read-only
    
  - name: GRAY
    summary: Then cell when selected has a gray background.
    type: Number
    permission: read-only
    
  - name: NONE
    summary: The cell has no distinct style for when it is selected.
    type: Number
    permission: read-only

---
name: Titanium.UI.iPhone.ListViewScrollPosition
summary: |
    A set of constants for the position value that can be used for the `position` property of 
    <Titanium.UI.ListView> when invoking `scrollToItem`.
extends: Titanium.Proxy
platforms: [iphone, ipad]
createable: false

properties:
  - name: BOTTOM
    summary: The table view scrolls the row of interest to the bottom of the visible table view.
    type: Number
    permission: read-only
    
  - name: MIDDLE
    summary: The table view scrolls the row of interest to the middle of the visible table view.
    type: Number
    permission: read-only
    
  - name: NONE
    summary: The table view scrolls the row of interest to be fully visible with a minimum of movement. If the row is already fully visible, no scrolling occurs. For example, if the row is above the visible area, the behavior is identical to that specified by `TOP`. This is the default.
    type: Number
    permission: read-only
    
  - name: TOP
    summary: The table view scrolls the row of interest to the top of the visible table view.
    type: Number
    permission: read-only

---
name: Titanium.UI.iPhone.ListViewStyle
summary: |
    A set of constants for the style that can be used for the button `style` property of 
    <Titanium.UI.ListView>.
extends: Titanium.Proxy
platforms: [iphone, ipad]
createable: false

properties:
  - name: GROUPED
    summary: |
        A table view whose sections present distinct groups of rows. The section headers and footers 
        do not float.
    type: Number
    permission: read-only
    
  - name: PLAIN
    summary: |
        A plain table view. Any section headers or footers are displayed as inline separators and 
        float when the table view is scrolled.
    type: Number
    permission: read-only

---
name: Titanium.UI.ListSection
extends: Titanium.Proxy
properties:

# Old properties going into v1

  - name: footerTitle
    summary: Title of this section footer.
    description: |
        Using this property and `footerView` together is not supported. Use one or the other.
    type: String

  - name: headerTitle
    summary: Title of this section header.
    description: |
        Using this property and `headerView` together is not supported. Use one or the other.
    type: String

methods:

# New methods

  - name: setItems
    summary: Sets the data entries in list to the list view
    parameters:
      - name: dataItems
        type: Array<ListDataItem>

      - name: animation
        type: Titanium.UI.iPhone.RowAnimationStyle
        optional: true
        platforms: [iphone, ipad]

  - name: appendItems
    summary: Appends the data entries in list to the end of list view
    parameters:
      - name: dataItems
        type: Array<ListDataItem>

      - name: animation
        type: Titanium.UI.iPhone.RowAnimationStyle
        optional: true
        platforms: [iphone, ipad]

  - name: insertItemsAt
    summary: Inserts data entries in list to the list view
    parameters:
      - name: itemIndex
        type: Number

      - name: dataItems
        type: Array<ListDataItem>

      - name: animation
        type: Titanium.UI.iPhone.RowAnimationStyle
        optional: true
        platforms: [iphone, ipad]

  - name: replaceItemsAt
    summary: Removes count entries from index position from the list view, then inserts data entries from list at position
    parameters:
      - name: index
        type: Number

      - name: count
        type: Number

      - name: dataItems
        type: Array<ListDataItem>

      - name: animation
        type: Titanium.UI.iPhone.RowAnimationStyle
        optional: true
        platforms: [iphone, ipad]

  - name: deleteItemsAt
    summary: Removes count entries at index position from the list view
    parameters:
      - name: itemIndex
        type: Number

      - name: count
        type: Number

      - name: animation
        type: Titanium.UI.iPhone.RowAnimationStyle
        optional: true
        platforms: [iphone, ipad]

  - name: getItemAt
    summary: Returns the item entry from the list view section at index.
    returns: ListDataItem
    parameters:
      - name: itemIndex
        type: Number

  - name: updateItemAt
    summary: Updates item entry at index position of list view section
    parameters:
      - name: index
        type: Number

      - name: dataItem
        type: ListDataItem

      - name: animation
        type: Titanium.UI.iPhone.RowAnimationStyle
        optional: true
        platforms: [iphone, ipad]

---
name: Titanium.UI.ListItem
extends: Titanium.Proxy

properties:

# New properties

  - name: itemId
    summary: A user defined string that gets passed from events
    type: String

  - name: accessoryType # One of the constants

# Old properties going into v1

  - name: allowsSelection
    summary: Determines whether this list's rows can be selected.
    description: Set to `false` to prevent rows from being selected.
    type: Boolean
    default: true
    platforms: [iphone, ipad]

  - name: color
    summary: Default text color of the row when not selected, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
        
        On Android, `selectedColor` is not supported, so the text is always displayed in this color.
        
        Only applies to the default template
    type: String

  - name: font
    summary: Font to use for the row title.
    description: |
        Only applies to the default template
    type: Font
    default: System default font.

  - name: image
    summary: Image to render in the image area of the row, specified as a local path or URL.
    description: |
        On iOS the image is on the left, and on Android the image is on the right
    type: String

  - name: title
    summary: Title to set in the text area of the row.
    type: String

  - name: selectionStyle
    summary: Selection style constant to control the selection color.
    description: |
        Specify one of the constants from <Titanium.List.iPhone.ListViewCellSelectionStyle>.
    type: Number
    platforms: [iphone,ipad]

  - name: backgroundColor
    summary: Background color for the list item, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: String

---
name: ItemTemplate
extends: ViewTemplate
excludes: {
    properties: [type, bindId]
}

---
name: ViewTemplate
properties:
  - name: type
    type: String
    summary: The view's class name, e.g. "Ti.UI.View"
    optional: false

  - name: bindId
    type: String
    summary: The view's id (or set of ids) used for data binding

  - name: properties
    type: Dictionary
    summary: Contains key-value pairs of view properties and their values

  - name: events
    type: Dictionary
    summary: Contains key-value pairs of view events and their listeners
    description: |
        Array values are considered as multiple event listeners for that event

  - name: childTemplates
    type: Array<Titanium.UI.ListViewTemplate>
    summary: Contains an array of templates for subviews to be added (in order) as children to this view

---
name: ListDataItem
  - name: template
    type: String
    summary: The cell style ID configured with ListView
    default: Titanium.List.CELL_STYLE_DEFAULT

  - name: properties
    type: Dictionary<Ti.UI.ListItem>
    summary: This is a pseudo bind-id that maps to the item itself. Properties here are applied to the ListItem.

  - name: <insert bindId here> # What is the proper yaml format?
    type: Dictionary
    summary: Specifies the values for data binding
    description: |
        Key-value pairs from the value dictionary will be applied on corresponding cell controls