listview-spec.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]

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]

  - name: pull
    summary: Fired when the list view is scrolling beyond the top of the view.
    description: |
        When implementing a pull to refresh, previous designs used a listener on the table
        view, although this generated a lot of events when scrolling elsewhere. This event
        fires only when the list view scrolls. Updating the pullView is the responsibility
        of the developer.
    properties:
      - name: contentOffset
        summary: Dictionary with `x` and `y` properties containing the content offset.
        type: Point
        platforms: [iphone, ipad]

  - name: pullend
    summary: Fired when the list view is pulled beyond the top of the view and the user lifts their finger.
    description: |
        When implementing a pull to refresh, previous designs used a listener on the table
        view, although this generated a lot of events when scrolling elsewhere. This event
        fires only when the list view is no longer being dragged downward due to the user.
        The behavior and what actions taken, as well as updating the pullView is the
        responsibility of the developer.
    properties:
      - name: contentOffset
        summary: Dictionary with `x` and `y` properties containing the content offset.
        type: Point
        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]

# Old properties going into v2

  - name: separatorColor
    summary: Separator line color between rows, as a color name or hex triplet.
    description: |
        To make the line invisible, set this property to `transparent`, or the same value as the
        [backgroundColor](Titanium.UI.ListView.backgroundColor) property.
        
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: String
    default: platform-specific default color

  - name: separatorStyle
    summary: Separator style constant.
    description: |
        Specify one of the
        [ListViewSeparatorStyle](Titanium.List.iPhone.ListViewSeparatorStyle) constants.
        
        For Mobile Web specify one of the
        [ListViewSeparatorStyle](Titanium.List.MobileWeb.ListViewSeparatorStyle) constants.
        
        For Android specify one of the
        [ListViewSeparatorStyle](Titanium.List.Android.ListViewSeparatorStyle) constants.
    type: Number

  - name: allowsSelectionDuringEditing
    summary: Determines whether this list's rows can be selected while editing the list.
    description: Set to `true` to allow rows to be selected.
    type: Boolean
    default: false
    platforms: [iphone, ipad]

  - name: editing
    summary: |
        Determines whether row editing mode is active.
    description: |
        The `editing` mode allows rows to be deleted or re-ordered, depending on their
        [editable](Titanium.UI.ListView.editable) and [moveable](Titanium.UI.ListView.moveable)
        settings.
    type: Boolean
    default: false
    platforms: [iphone, ipad]

  - name: caseInsensitiveSearch
    summary: Determines whether the search is case insensitive.
    description: Set to `false` to enable case sensitive search.
    type: Boolean
    default: true
    platforms: [android, iphone, ipad]
    
  - name: searchView
    summary: Search field to use for the list view.
    type: [Titanium.UI.SearchBar, Titanium.UI.Android.SearchView]
    platforms: [android, iphone, ipad]

  - name: searchText
    summary: Search string to use for the list view. If searchView is used, this is ignored
    type: string
    platforms: [android, iphone, ipad]

  - name: searchViewIsEmbedded
    summary: SearchAsChild done right
    type: boolean
    default: false
    

  - name: footerView
    summary: List view footer as a view that will be rendered instead of a label.
    type: Titanium.UI.View

#Note: iOS 6 has an elegant built-in OS version. This is not it.
  - name: pullView
    summary: |
        View positioned above the first row that is only revealed when the user drags the list contents down.
    description: |
        A `pullView` is a UI control that is often used to provide a convenient way for the
        user to refresh a list's data.  Typically used with the
        [setContentInsets](Titanium.UI.ListView.setContentInsets) method.
    type: Titanium.UI.View
    platforms: [iphone, ipad]

  - name: headerView
    summary: List view header as a view that will be rendered instead of a label.
    type: Titanium.UI.View

  - name: index (rename me) #Still needs renaming. Let's call it Fred.
    summary: Array of objects (with `title` and `index` properties) to control the list view index.
    description: |
        If an index array is specified, an index bar is displayed on the right-hand side of the
        list view. Clicking on a title in the index bar scrolls the list view to the row
        index associated with that title.
    type: Array<ListViewIndexEntry>
    platforms: [iphone, ipad]

  - name: canScroll (previously called scrollable)
    summary: If `true`, the list can be scrolled.
    type: Boolean
    default: true

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

# New methods in v2

# Note. iOS 5 and later allows for, optionally, multiple items to be highlighted. We don't.
  - name: selectItem
    summary: Causes specific items to be highlighted as if being selected. Does not fire an event.
    parameters:
      - name: sectionIndex
        type: Number

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

  - name: deselectItem
    summary: Causes specific items to be no longer be highlighted as if being selected. Does not fire an event.
    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 [pullView](Titanium.UI.ListView.pullView) 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]

---
# v2
name: ListViewIndexEntry
summary: A simple object that represents an index entry in a `List`.
properties:
  - name: title
    summary: Title to display in the index bar for this item.
    type: String
    
  - name: index
    summary: Row index associated with this item.
    type: Number

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

---
# v2
name: ListViewEdgeInsets
summary: The parameter for [setContentInsets](Titanium.UI.ListView.setContentInsets) method.
description: |
    On iOS, the parameter `edgeInsets` can be specified to set the distance(`top`, `bottom`,
    `right`, `left`) that the content view is inset from the enclosing scroll view of the list.
    For example

        setContentInset({top:50,bottom:10,right:10,left:10}, {animated:true})
platforms: [iphone, ipad]

properties:
  - name: top
    summary: Value specifying the top insets for the enclosing scroll view of the list.
    type: Number
    
  - name: left
    summary: Value specifying the left insets for the enclosing scroll view of the list.
    type: Number
    
  - name: right
    summary: Value specifying the right insets for the enclosing scroll view of the list.
    type: Number
    
  - name: bottom
    summary: Value specifying the bottom insets for the enclosing scroll view of the list.
    type: Number

---
#v2
name: ListViewContentInsetOption
summary: Optional parameter for [setContentInsets](Titanium.UI.ListView.setContentInsets) method.
description: |
    On iOS, the optional parameters `animated` and `duration`to enable the animation and duration 
    for animation while the content insets are updated. For example

        setContentInset({top:50,bottom:100}, {animated:true, duration:3000})
optional: true
platforms: [iphone, ipad]

properties:
  - name: animated
    summary: Determines whether the list view's content inset change is animated.
    type: Boolean
    default: false
    
  - name: duration
    summary: The duration in `milleseconds` for animation while the content inset is  being changed.
    type: Number


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

# Old properties going into v2

  - name: footerView
    summary: View to use for this section footer.
    description: |
        Using this property and `footerTitle` together is not supported. Use one or the other.
    type: Titanium.UI.View

  - name: headerView
    summary: View to use for this section header.
    description: |
        Using this property and `headerTitle` together is not supported. Use one or the other.
    type: Titanium.UI.View

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 at index.
    returns: ListDataItem
    parameters:
      - name: itemIndex
        type: Number

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

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: height
    summary: Height for list view item.
    description: |
        On iOS, this is an absolute size only. SIZE, FILL, percentages, and 'auto' are
        unsupported.
    type: Number #Dimension

# Old properties going into v2

  - name: indentionLevel # Is this iOS only?
    summary: Indention level for the row.
    description: Indentation values greater than 0 indent the row text.
    type: Number
    default: 0

  - name: selectedBackgroundColor
    summary: Background color to render when the row is selected, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: String

  - name: selectedBackgroundImage
    summary: Background image to render when the row is selected.
    type: String

  - name: selectedColor
    summary: Color of the row text when the row is selected, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: String
    platforms: [iphone,ipad]

  - 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]

#new properties in v2

  - name: searchableText
    summary: String that is searched
    description: |
        When a list view filters due to searchText or searchView, this is the text that is
        searched.
    type: String

  - name: canMove
    summary: |
        Determines whether the item may be moved by the user during edit mode.
    type: Boolean
    default: false
    platforms: [iphone, ipad]

#For later: Allow for insert as well as delete.
  - name: canEdit
    summary: |
        Determines whether the item may be edited (deleted) by the user during edit mode.
    type: Boolean
    default: false
    platforms: [iphone, ipad]

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

The constants are defined in the wiki spec but not here, so I guess we never got around to reviewing them.

I had proposed that we drop the TYPE from the constant names, since accessoryType: LIST_ACCESSORY_TYPE_CHECKMARK doesn't seem to add anything over accessoryType: LIST_ACCESSORY_CHECKMARK. But probably nto a big deal either way

Are font, title, image, color for default templates only in Titanium.UI.ListItem? (it only lists them as such for two of them)

Also it looks like template is a creation only property in Android, but the spec doesn't say this. Is that correct?

Which Ti SDK version does this refer to? 3.1.0 and up?