TableView.yml

---
name: Titanium.UI.TableView
summary: A Table View allows you to create a scrollable table of content in a list-based fashion.
description: |
     A table view can contain a set of [TableViewRow](Titanium.UI.TableViewRow)s, each displaying 
     an item of data. The default `TableViewRow` has properties for adding text, as well as 
     optional images on the left and right sides, and various system-provided indicators, 
     such as check marks. Table view rows can also be fully customized by adding child views, 
     such as labels, buttons, or image views.

     When adding rows to a table view, each row can be passed as a 
     [TableViewRow](Titanium.UI.TableViewRow) object, or as dictionary specifying 
     the properties for a table row, in which case the `TableView` will create 
     `TableViewRow` objects as needed. 
     
     Use the <Titanium.UI.createTableView> method to create a table view.
extends: Titanium.UI.View
since: "0.8"
excludes:
    events: [ 'singletap', 'dblclick', 'doubletap', 'longclick', 'longpress', 'twofingertap', 'pinch', 'swipe' ] 
methods:
  - name: appendRow
    summary: Appends one or more rows to the table.
    description: |
        Appends a single row or an array of rows to the end of the table.
        Each row can be passed as a [TableViewRow](Titanium.UI.TableViewRow) object,
        or as dictionary specifying the properties for a table row, in which case
        the `TableView` will create `TableViewRow` objects as needed.

        On iOS, the row(s) can be inserted with animation by specifying a `properties`
        parameter.
    parameters:
      - name: row
        summary: If appending a single row, this should contain only the row being appended.
            If appending multiple rows, this should be an array of the rows being appended.
        type: [Titanium.UI.TableViewRow, Dictionary<Titanium.UI.TableViewRow>, Array<Titanium.UI.TableViewRow>, Array<Dictionary<Titanium.UI.TableViewRow>>]
      - name: properties
        summary: Animation properties, only used on iOS.
        type: TableViewAnimationProperties
        optional: true
  - name: deleteRow
    summary: Deletes an existing row.
    description: |
        On iOS, the row can be deleted with animation by specifying a `properties`
        parameter.
    parameters:
      - name: row
        summary: Index of the row to delete.
        type: Number
      - name: properties
        summary: Animation properties. Only used on iOS.
        type: TableViewAnimationProperties
        optional: true
  - name: deselectRow
    summary: Programmatically deselects a row.
    parameters:
      - name: row
        summary: Row index to deselect.
        type: Number
    platforms: [iphone,ipad]
  - name: insertRowAfter
    summary: Inserts a row after another row.
    description: |
        The row can be passed as a [TableViewRow](Titanium.UI.TableViewRow) object,
        or as dictionary specifying the properties for a table row, in which case
        the `TableView` will create a `TableViewRow` object as needed.

        On iOS, the row(s) can be inserted with animation by specifying a `properties`
        parameter.
    parameters:
      - name: index
        summary: Index of the row to insert after.
        type: Number
      - name: row
        summary: Row to insert.
        type: [Titanium.UI.TableViewRow, Dictionary<Titanium.UI.TableViewRow>]
      - name: properties
        summary: Animation properties. Only used on iOS.
        type: TableViewAnimationProperties
        optional: true
  - name: insertRowBefore
    summary: Inserts a row before another row.
    description: |
        The row can be passed as a [TableViewRow](Titanium.UI.TableViewRow) object,
        or as dictionary specifying the properties for a table row, in which case
        the `TableView` will create a `TableViewRow` object as needed.

        On iOS, the row(s) can be inserted with animation by specifying a `properties`
        parameter.
    parameters:
      - name: index
        summary: Index of the row to insert before.
        type: Number
      - name: row
        summary: Row to insert.
        type: [Titanium.UI.TableViewRow, Dictionary<Titanium.UI.TableViewRow>]
      - name: properties
        summary: Animation properties. Only used on iOS.
        type: TableViewAnimationProperties
        optional: true
  - name: scrollToIndex
    summary: Scrolls the table view to ensure that the specified row is on screen.
    description: |
        On iOS, specify a <TableViewAnimationProperties> object to control the position that
        the selected row is scrolled to, and whether scrolling is animated.
    parameters:
      - name: index
        summary: Row index to scroll to.
        type: Number
      - name: properties
        summary: Animation properties. Only used on iOS.
        type: TableViewAnimationProperties
        optional: true
  - name: scrollToTop
    summary: Scrolls the table to a specific top position where 0 is the topmost y position in the table view.
    description: |
        The behavior of this method is platform-specific.

        On Android, the `top` value is interpreted as a row index that should be scrolled 
        to the top of the screen. The table will not scroll the last row of data higher than
        the bottom of the screen. If there is less than one screenful of data below the 
        specified row, the table doesn't scroll the specified row all the way to the top.
        If the table has less than one screenful of data total, it does not scroll at all.

        On iOS, the `top` value is interpreted as a pixel offset between the top of the top
        row of data and the top of the table view. So a `top` value of 0 scrolls the list to
        the top. A positive value scrolls it down, and a negative value scrolls the list up
        above the first item.

        On iOS, specify a <TableViewAnimationProperties> object with `animated` set to `false` to 
        disable the scrolling animation.
    parameters:
      - name: top
        summary: Y position for the top of the table view.
        type: Number
      - name: properties
        summary: Animation properties. Only used on iOS. 
        type: TableViewAnimationProperties
        optional: true
  - name: selectRow
    summary: Programmatically selects a row.
    parameters:
      - name: row
        summary: Row index to select.
        type: Number
    platforms: [iphone, ipad]
  - name: setData
    summary: Sets the data in the table.
    description: |
        Each row can be passed either as a `TableViewRow` object, 
        or as a dictionary of `TableViewRow` properties.

        `setData` can also be used to add [TableViewSection](Titanium.UI.TableViewSection)s to a 
        table view.
    parameters:
      - name: data
        summary: Array of rows (or sections).
        type: [ Array<Titanium.UI.TableViewRow>, Array<Dictionary<Titanium.UI.TableViewRow>>, Array<Titanium.UI.TableViewSection> ]
      - name: properties
        summary: Animation properties. Only used on iOS.
        type: TableViewAnimationProperties
  - name: updateRow
    summary: Updates an existing row, optionally with animation
    parameters:
      - name: index
        summary: Index of the row to update.
        type: Number
      - name: row
        summary: Row data to update.
        type: Titanium.UI.TableViewRow
      - name: properties
        summary: Animation properties. Only used on iOS.
        type: TableViewAnimationProperties
events:
  - name: click
    summary: Fired when a table row is deleted by the user.
    platform: [android, iphone, ipad]
    properties:
      - name: index
        summary: Row index.
        type: Number
      - name: section
        summary: Table view section object, if the deleted row is contained in a section.
        type: Titanium.UI.TableViewSection
      - name: detail
        summary: Boolean to indicate if the right area was clicked.
      - name: searchMode
        summary: Boolean to indicate if the table is in search mode.
      - name: rowData
        summary: Dictionary containing the properties set on the row.
        type: Dictionary<Titanium.UI.TableViewRow>
      - name: y
        summary: Y coordinate of the event, in the `source` view's coordinates.
      - name: x
        summary: X coordinate of the event, in the `source` view's coordinates.
      - name: globalPoint
        summary: Dictionary with properties `x` and `y` describing the location of the event in screen coordinates.
        platforms: [iphone, ipad]
        type: Point
        deprecated:
            since: "1.8.0"
      - name: row
        summary: Table view row object.
        type: Titanium.UI.TableViewRow
  - name: delete
    summary: Fired when a table row is deleted by the user.
    platform: [iphone, ipad]
    properties:
      - name: index
        summary: Row index.
        type: Number
      - name: section
        summary: Table view section object, if the deleted row is contained in a section.
        type: Titanium.UI.TableViewSection
      - name: detail
        summary: Boolean to indicate if the right area was clicked.
      - name: searchMode
        summary: Boolean to indicate if the table is in search mode.
      - name: rowData
        summary: Dictionary containing the properties set on the row.
        type: Dictionary<Titanium.UI.TableViewRow>
      - name: y
        summary: Y coordinate of the event, in the `source` view's coordinates.
      - name: x
        summary: X coordinate of the event, in the `source` view's coordinates.
      - name: globalPoint
        summary: Dictionary with properties `x` and `y` describing the location of the event in screen coordinates.
        platforms: [iphone, ipad]
        type: Point
        deprecated:
            since: "1.8.0"
      - name: row
        summary: Table view row object.
        type: Titanium.UI.TableViewRow
  - name: move
    summary: Fired when a table row is moved by the user.
    platform: [iphone, ipad]
    properties:
      - name: index
        summary: Row index.
        type: Number
      - name: section
        summary: Table view section object, if the deleted row is contained in a section.
        type: Titanium.UI.TableViewSection
      - name: detail
        summary: Boolean to indicate if the right area was clicked.
      - name: searchMode
        summary: Boolean to indicate if the table is in search mode.
      - name: rowData
        summary: Dictionary containing the properties set on the row.
        type: Dictionary<Titanium.UI.TableViewRow>
      - name: y
        summary: Y coordinate of the event, in the `source` view's coordinates.
      - name: x
        summary: X coordinate of the event, in the `source` view's coordinates.
      - name: globalPoint
        summary: Dictionary with properties `x` and `y` describing the location of the event in screen coordinates.
        platforms: [iphone, ipad]
        type: Point
        deprecated:
            since: "1.8.0"
      - name: row
        summary: Table view row object.
        type: Titanium.UI.TableViewRow
  - name: scroll
    summary: Fired when the table view is scrolled.
    properties:
      - name: firstVisibleItem
        summary: Row index of the topmost visible row in the view.
        platforms: [android, mobileweb]
      - name: visibleItemCount
        summary: Number of rows currently visible in the view.
        platforms: [android, mobileweb]
      - name: contentOffset
        summary: Dictionary with `x` and `y` properties containing the content offset.
        platforms: [iphone, ipad, mobileweb]
        type: Point
      - name: totalItemCount
        summary: Total number of rows in the view.
        platforms: [android, mobileweb]
      - name: y
        summary: Y coordinate of the event, in the `source` view's coordinates.
        type: Number
        platforms: [android, iphone, ipad]
      - name: x
        summary: X coordinate of the event, in the `source` view's coordinates.
        platforms: [android, iphone, ipad]
      - name: contentSize
        summary: Dictionary with `width` and `height` properties containing the size of the content (regardless of the display size in the case of scrolling).
        platforms: [iphone, ipad, mobileweb]
        type: Dictionary
      - name: globalPoint
        summary: a dictionary with properties x and y describing the point of the event in screen coordinates
        platforms: [iphone, ipad]
        type: Point
        deprecated:
            since: "1.8.0"
      - name: size
        summary: Dictionary with `width` and `height` properties containing the size of the visible table view
        type: Dictionary
  - name: scrollEnd
    summary: fired when the table view stops scrolling
    properties:
      - name: contentOffset
        summary: Dictionary with `x` and `y` properties containing the content offset.
        platforms: [iphone, ipad, mobileweb]
        type: Point
      - name: y
        summary: Y coordinate of the event, in the `source` view's coordinates.
        platforms: [android, iphone, ipad]
        type: Number
      - name: x
        summary: X coordinate of the event, in `source` view's coordinates.
        platforms: [android, iphone, ipad]
        type: Number
      - name: contentSize
        summary: Dictionary with `width` and `height` properties containing the size of the content (regardless of the display size in the case of scrolling).
        platforms: [iphone, ipad, mobileweb]
        type: Dictionary
      - name: globalPoint
        summary: a dictionary with properties x and y describing the point of the event in screen coordinates
        platforms: [iphone, ipad]
        type: Point
        deprecated:
            since: "1.8.0"
      - name: size
        summary: Dictionary with `width` and `height` properties containing the size of the visible table view.
        type: Dictionary
properties:
  - name: allowsSelection
    summary: True if the rows can be selected.
    type: Boolean
    default: true
    platforms: [iphone, ipad]
  - name: allowsSelectionDuringEditing
    summary: True if the rows can be selected while editing the table.
    platforms: [iphone, ipad]
    type: Boolean
  - name: data
    summary: Array of objects to be used for the rows of the table view.
    type: [ Array<Titanium.UI.TableViewRow>, Array<Titanium.UI.TableViewSection> ]
  - name: editable
    summary: Allow the user to edit the table view (this must be `true` for swipe-to-delete).
    platforms: [iphone, ipad]
    type: Boolean
    default: false
  - name: editing
    summary: Boolean to control the editing state of the table view.
    platforms: [iphone, ipad]
    type: Boolean
    default: false
  - name: filterAttribute
    summary: Filter attribute to be used when searching. 
    description: |
        This property maps to your data object or a property on the row object. For example,
        if you set `filterAttribute` to `'title'`, the table view shows only those rows that
        contain the current search text in the `title` property.

        Note that the filter is not anchored to the beginning of the string. So typing "ha"
        in the text box will include rows titled 'Harold' and 'Harvard', but also 'Sharon'
        and 'Jonathan'.
    type: String
    platforms: [android, iphone, ipad]
  - name: filterCaseInsensitive
    summary: Boolean to indicate if the search should be case sensitive or case insensitive.
    default: true
    type: Boolean
    platforms: [android, iphone, ipad]
  - name: footerTitle
    summary: Table view footer title.
    type: String
  - name: footerView
    summary: Table view footer as a view that will be rendered instead of a label.
    type: Titanium.UI.View
  - name: headerTitle
    summary: Table view header title.
    type: String
  - name: headerView
    summary: Table view header as a view that will be rendered instead of a label.
    type: Titanium.UI.View
  - name: index
    summary: Array of objects (with `title` and `index` properties) to control the table view index.
    description: |
        If an index array is specified, an index bar is displayed on the right-hand side of the 
        table view. Clicking on a title in the index bar scrolls the table view to the row 
        index associated with that title.
    type: Array<TableViewIndexEntry>
    platforms: [iphone, ipad]
  - name: maxRowHeight
    summary: Maximum row height for table view rows.
    type: Number
  - name: minRowHeight
    summary: Minimum row height for table view rows.
    type: Number
  - name: moving
    summary: Boolean to control the moveable state of the table view.
    platforms: [iphone, ipad]
    type: Boolean
  - name: rowHeight
    summary: Default row height for table view rows.
    type: Number
  - name: scrollable
    summary: If true (default) if tableview can be scrolled
    type: Boolean
    default: true
    platforms: [iphone,ipad]
  - name: search
    summary: Search field to use for the table view.
    type: Titanium.UI.SearchBar
    platforms: [android, iphone, ipad]
  - name: searchHidden
    summary: Boolean to control the visibility of the search field.
    type: Boolean
    default: false (search field visible)
    platforms: [iphone, ipad]
  - name: separatorColor
    summary: Separator color between rows, specified as a hex or named value.
    type: String
    default: platform-specific default color
  - name: separatorStyle
    summary: Separator style constant. For iOS specify one of the [TableViewSeparatorStyle](Titanium.UI.iPhone.TableViewSeparatorStyle) constants.
    platforms: [iphone, ipad, mobileweb]
    type: Number
  - name: showVerticalScrollIndicator
    summary: Whether table view displays vertical scroll indicator
    platforms: [iphone, ipad]
    default: true
    type: Boolean
  - name: style
    summary: Style of the table view, specified using one of the constants from <Titanium.UI.iPhone.TableViewStyle>.
    platforms: [iphone, ipad]
    type: Number
examples:
  - title: Simple Table View with Basic Rows
    example: |
        The most basic example of a table view.
        
            var data = [{title:"Row 1"},{title:"Row 2"}];
            var table = Titanium.UI.createTableView({data:data});
            win.add(table);
        
        
---
name: TableViewAnimationProperties
summary: A simple object for specifying the animation properties to use when inserting or deleting rows, or scrolling the table.
description: |
    These properties are only used on iOS. Not all properties apply to all methods.

    `animationStyle` only applies to row insertions and deletions.

    `positon` only applies to the `scrollToIndex` method.
properties:
  - name: animated
    summary: Whether this table change should be animated.
    type: Boolean
    default: true
  - name: animationStyle
    summary: Type of animation to use for row insertions and deletions. One of the animation style constants defined in <Titanium.UI.iPhone.RowAnimationStyles>.
    type: Number
    default: <Titanium.UI.iPhone.RowAnimationStyles.FADE>
  - name: position
    summary: Specifies what position to scroll the selected row to. One of the position constants from <Titanium.UI.iPhone.TableViewScrollPosition>.
    type: Number
    default: <Titanium.UI.iPhone.TableViewScrollPosition.NONE>

---
name: TableViewIndexEntry
summary: A simple object that represents an index entry in a `TableView`.
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