# Titanium.UI.TableView

A table view is used to present information, organized in sections and rows, in a vertically-scrolling view.

Availability
0.8
0.8
9.2.0
4.1.0

# Overview

Android iOS Windows
Android iOS Windows

A TableView object is a container for Titanium.UI.TableViewSection objects that are, in turn, containers for Titanium.UI.TableViewRow objects.

Use the Titanium.UI.createTableView method or <TableView> Alloy element to create a TableView.

Also see the TableViews guide (opens new window).

# Creating Tables

There are few approaches to creating and using TableView object.

The simplest approach is to pass dictionaries of TableViewRow properties, such as backgroundColor, Titanium.UI.TableViewRow.color, and Titanium.UI.TableViewRow.title, to the Titanium.UI.createTableView method, which causes the rows to be implictly created, added to a single Titanium.UI.TableViewSection, and then added to the TableView. Refer to the "Simple Table View with Basic Rows" example.

For more control over the layout of each row, however, Titanium.UI.TableViewRow objects can be created explicitly using the Titanium.UI.createTableViewRow method. Child views, such as Titanium.UI.Label, Titanium.UI.ImageView, and Titanium.UI.Button, may be added to each row. When one or more Titanium.UI.TableViewRow are added to the table view, a single Titanium.UI.TableViewSection is automatically created to hold the rows. See the "Table View with Composite Layout" example.

Lastly, sets of rows may be explicitly created and added to a their own Titanium.UI.TableViewSection objects, which are then added to a TableView, to enable the rows to be organized. Headers and footers titles or views must be configured in order for the sections to be visible.

# Tables and Scroll Views

As a table view inherently scrolls, it creates a very poor user experience when one contains other scrolling views, such as a Titanium.UI.ScrollableView or Titanium.UI.TextArea. Thus, this layout is strongly discouraged.

# TextFields in Tables with SOFT_INPUT_ADJUST_PAN (Android)

When a Titanium.UI.TextField is placed in a row near the bottom of a TableView, in a window that is configured with Titanium.UI.Android.SOFT_INPUT_ADJUST_PAN, it is expected for the text field to automatically move to a visible position after it is focused and the software keyboard displayed. However, due to a known problem caused by native Android's ListView behavior, the keyboard is likely to completely obscure the text field.

To mitigate this, a ScrollView may be used instead of a table view, as demonstrated in the Titanium.UI.ScrollView, "Scroll View as a Table View", example.

# Known Issues

There are known issues with the sections property and associated methods added in Release 3.0:

  • On iOS, the first two arguments to the updateSection method are reversed. (TIMOB-12625 (opens new window)). This issue has been addressed in Release 3.3.0 of the Titanium SDK

# Row Editing and Moving Modes

Table views have an editing and a moving mode that may be activated to using their respective Titanium.UI.TableView.editing and Titanium.UI.TableView.moving properties. These allow rows to be deleted or re-ordered by the user, depending on each row's Titanium.UI.TableViewRow.editable and Titanium.UI.TableViewRow.moveable property that are either explicitly set or inherited from the table.

There are two UI controls available for deleting table view rows, depending on the combination of editing and moving modes enabled:

  • "red icon delete" - a circular red icon is displayed on the left-hand side of a row, which reveals a delete button on the right-hand side of that row when clicked.
  • "swipe delete" - without either of the table editing or moving modes enabled, a left or right swipe gesture on a row reveals a delete button on the right-hand side of the row.

Note that because the operating system handles the functionality of the swipe delete, the OS will capture swipe events and not bubble the event to Titanium listeners. As such, if you rely on swipe events, you must not set editing to true on such rows, and simulate the functionality you need.

When editable and moveable properties are set on the table view, they are known as inherited, whereas when set on a row, they are known as explicit. As their resulting behavior may not follow their literal meaning, depending on the combination of editing and moving modes that are enabled, a detailed description of the behavior follows.

With editing:false and moving:true:

  • For red icon delete and swipe delete, inherited and explicit editable properties may be set.
  • Inherited moveable property is always true. Explicit moveable property may be set.

With editing:true and moving:false:

  • For red icon delete and swipe delete, inherited editable property is always true. Explicit editable property may be set.
  • Inherited and explicit moveable properties may be set.

With editing:false and moving: false:

  • For red icon delete, inherited and explicit editable properties always false. For swipe delete, inherited and explicit editable properties may be set.
  • Inherited moveable property is always false.

With editing:true and moving:true:

  • For red icon delete and swipe delete, inherited and explicit editable properties may be set.
  • Inherited moveable property is always true. Explicit moveable property may be set.

# Examples

# Simple Table View

Create a basic table view.

Ti.UI.backgroundColor = 'white';
var win = Ti.UI.createWindow();

var tableData = [ {title: 'Apples'}, {title: 'Bananas'}, {title: 'Carrots'}, {title: 'Potatoes'} ];

var table = Ti.UI.createTableView({
  data: tableData
});
win.add(table);
win.open();

# Table View Sections

Create a table with three sections, each with two rows. Add two sections to the table before and one after it is rendered. This sample only works on Release 3.0 and later.

Ti.UI.backgroundColor = 'white';
var win = Ti.UI.createWindow();

var sectionFruit = Ti.UI.createTableViewSection({ headerTitle: 'Fruit' });
sectionFruit.add(Ti.UI.createTableViewRow({ title: 'Apples' }));
sectionFruit.add(Ti.UI.createTableViewRow({ title: 'Bananas' }));

var sectionVeg = Ti.UI.createTableViewSection({ headerTitle: 'Vegetables' });
sectionVeg.add(Ti.UI.createTableViewRow({ title: 'Carrots' }));
sectionVeg.add(Ti.UI.createTableViewRow({ title: 'Potatoes' }));

var table = Ti.UI.createTableView({
  data: [sectionFruit, sectionVeg]
});

win.add(table);
win.open();

var sectionFish = Ti.UI.createTableViewSection({ headerTitle: 'Fish' });
sectionFish.add(Ti.UI.createTableViewRow({ title: 'Cod' }));
sectionFish.add(Ti.UI.createTableViewRow({ title: 'Haddock' }));

// Prior to Release 3.0, you can only add and remove sections by setting the data property
// table.data = [ sectionFish, sectionFruit, sectionVeg ];
// Due to a known issue, TIMOB-12616, the section access methods and sections
// property should not be used on iOS with Release 3.0.x.
table.insertSectionBefore(0, sectionFish);

# Table View with Composite Layout

Create a table of rows that contain a custom child-view layout.

var win = Ti.UI.createWindow({
  backgroundColor: 'black',
  title: 'TableView Demo'
});

// generate random number, used to make each row appear distinct for this example
function randomInt(max){
  return Math.floor(Math.random() * max) + 1;
}

var IMG_BASE = 'images/';
var defaultFontSize = Ti.Platform.name === 'android' ? 16 : 14;

var tableData = [];

for (var i=1; i<=20; i++){
  var row = Ti.UI.createTableViewRow({
    className:'forumEvent', // used to improve table performance
    selectedBackgroundColor:'white',
    rowIndex:i, // custom property, useful for determining the row during events
    height:110
  });

  var imageAvatar = Ti.UI.createImageView({
    image: IMG_BASE + 'custom_tableview/user.png',
    left:10, top:5,
    width:50, height:50
  });
  row.add(imageAvatar);

  var labelUserName = Ti.UI.createLabel({
    color:'#576996',
    font:{fontFamily:'Arial', fontSize:defaultFontSize+6, fontWeight:'bold'},
    text:'Fred Smith ' + i,
    left:70, top: 6,
    width:200, height: 30
  });
  row.add(labelUserName);

  var labelDetails = Ti.UI.createLabel({
    color:'#222',
    font:{fontFamily:'Arial', fontSize:defaultFontSize+2, fontWeight:'normal'},
    text:'Replied to post with id ' + randomInt(1000) + '.',
    left:70, top:44,
    width:360
  });
  row.add(labelDetails);

  var imageCalendar = Ti.UI.createImageView({
    image:IMG_BASE + 'custom_tableview/eventsButton.png',
    left:70, bottom: 2,
    width:32, height: 32
  });
  row.add(imageCalendar);

  var labelDate = Ti.UI.createLabel({
    color:'#999',
    font:{fontFamily:'Arial', fontSize:defaultFontSize, fontWeight:'normal'},
    text:'on ' + randomInt(30) + ' Nov 2012',
    left:105, bottom:10,
    width:200, height:20
  });
  row.add(labelDate);

  tableData.push(row);
}

var tableView = Ti.UI.createTableView({
  backgroundColor:'white',
  data:tableData
});

win.add(tableView);
win.open();

# Alloy XML Markup

Previous table view sections example as an Alloy view.

<Alloy>
    <Window id="win" backgroundColor="white">
        <TableView id="table">
            <TableViewSection id="sectionFruit" headerTitle="Fruit">
                <TableViewRow title="Apple"/>
                <TableViewRow title="Bananas"/>
            </TableViewSection>
            <TableViewSection id="sectionVeg" headerTitle="Vegetables">
                <TableViewRow title="Carrots"/>
                <TableViewRow title="Potatoes"/>
            </TableViewSection>
            <TableViewSection id="sectionFish" headerTitle="Fish">
                <TableViewRow title="Cod"/>
                <TableViewRow title="Haddock"/>
            </TableViewSection>
        </TableView>
    </Window>
</Alloy>

# Properties

# allowsMultipleSelectionDuringEditing

Availability
10.1.0
8.2.0
9.2.0
allowsMultipleSelectionDuringEditing :Boolean

Determines whether multiple items of this table view can be selected at the same time while editing the table.

Default: false


# allowsMultipleSelectionInteraction

Availability
8.2.0
9.2.0
allowsMultipleSelectionInteraction :Boolean

Allows a two-finger pan gesture to automatically transition the table view into editing mode and start selecting rows.

Setting this property to true allows the user to start selecting multiple contiguous rows via a two-finger pan gesture. If the table view is already in editing mode, the user can also select multiple rows via a one-finger pan gesture along the edge of the table that contains editing controls (checkboxes). In order to support this behavior, you must also set allowsMultipleSelectionDuringEditing to true. Once user interaction stops the rowsselected event is fired.

Default: false


# allowsSelection

Availability
8.2.0
9.2.0
allowsSelection :Boolean

Determines whether this table's rows can be selected.

Set to false to prevent rows from being selected.

Default: true


# allowsSelectionDuringEditing

Availability
10.1.0
5.4.0
9.2.0
allowsSelectionDuringEditing :Boolean

Determines whether this table's rows can be selected while editing the table.

Set to true to allow rows to be selected.

Default: false


# backgroundColor

Availability
0.9
0.9
9.2.0
backgroundColor :String | Titanium.UI.Color

Background color of the view, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: transparent on non-iOS platforms, white on the iOS platform


# data

Availability
0.8
0.8
9.2.0

Rows of the table view.


# dimBackgroundForSearch CREATION ONLY

Availability
6.2.0
9.2.0
dimBackgroundForSearch :Boolean

A Boolean indicating whether the underlying content is dimmed during a search.

If you do not want to show the dimmed background when clicking on the search bar, set this property false during creation.

Default: true


# editable

Availability
9.3.0
3.2.0
9.2.0
editable :Boolean

Determines the rows' default editable behavior, which allows them to be deleted by the user when the table is in editing or moving mode.

This property determines the default behavior of child rows, but may be overridden by a row's editable property.

See the Titanium.UI.TableView description section for a full explanation of the TableView's editing and moving modes.

Default: Depends on `editing` and `moving` mode


# editing

Availability
9.3.0
3.2.0
9.2.0
editing :Boolean

Determines whether row editing mode is active.

The editing mode allows rows to be deleted or re-ordered, depending on their editable and moveable settings.

See the Titanium.UI.TableView description section for a full explanation of the TableView's editing and moving modes.

Default: false


# filterAnchored

Availability
3.3.0
3.3.0
9.2.0
filterAnchored :Boolean

Determines whether the search is limited to the start of the string

Set to true to enable case anchored search.

Default: false


# filterAttribute

Availability
0.8
0.8
9.2.0
filterAttribute :String

Filter attribute to be used when searching.

On the Android platform, this property can only be set to Titanium-defined properties of the TableViewRow object, such as title. To search text stored in a different attribute, set the title property of the TableViewRow object to the property to be searched. For example:

var label = Ti.UI.createLabel({text: 'Foobar'}),
var row = Ti.UI.createTableViewRow(title: label.text);
row.add(label);

On the iOS platform, this property can be set to any property on the TableViewRow object, including arbitrary properties set on the object, not only Titanium-defined properties.

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


# filterCaseInsensitive

Availability
0.8
0.8
9.2.0
filterCaseInsensitive :Boolean

Determines whether the search is case insensitive.

Set to false to enable case sensitive search.

Default: true


# footerDividersEnabled CREATION ONLY

Availability
3.3.0
footerDividersEnabled :Boolean

When set to false, the ListView will not draw the divider before the footer view.

Default: undefined but behaves as false


# footerTitle

Availability
0.8
0.8
9.2.0
footerTitle :String

Table view footer title.


# footerView

Availability
0.8
0.8
9.2.0
footerView :Titanium.UI.View

Table view footer as a view that will be rendered instead of a label.

In Alloy you can use a <FooterView> element nested in a <TableView> element:

<Alloy>
    <TableView>
        <FooterView>
            <View backgroundColor="#a00" height="50dp"/>
        </FooterView>
        <TableViewRow><Label>Row 1</Label></TableViewRow>
        <TableViewRow><Label>Row 2</Label></TableViewRow>
    </TableView>
</Alloy>

# headerDividersEnabled CREATION ONLY

Availability
3.3.0
headerDividersEnabled :Boolean

When set to false, the ListView will not draw the divider after the header view.

Default: undefined but behaves as false


# headerPullView

Availability
2.1.0
9.2.0
headerPullView :Titanium.UI.View

View positioned above the first row that is only revealed when the user drags the table contents down.

A headerPullView is a UI control that is often used to provide a convenient way for the user to refresh a table's data. Typically used with the setContentInsets method.

To specify the wrapper color see pullBackgroundColor.

For an example, see the "Pull to refresh" section in the TableViews guide.

Alloy applications can use a <HeaderPullView> element inside a <TableView> element.

<Alloy>
    <TableView>
        <HeaderPullView platform="ios">
            <View class="pull">
                <Label color="#F2F4F4" bottom="25dp">Header pull view</Label>
            </View>
        </HeaderPullView>
    </TableView>
</Alloy>

# headerTitle

Availability
0.8
0.8
9.2.0
headerTitle :String

Table view header title.


# headerView

Availability
0.8
0.8
9.2.0
headerView :Titanium.UI.View

Table view header as a view that will be rendered instead of a label.

In Alloy you can use a <HeaderView> element nested in a <TableView> element:

<Alloy>
    <TableView>
        <HeaderView>
            <View backgroundColor="#a00" height="50dp"/>
        </HeaderView>
        <TableViewRow><Label>Row 1</Label></TableViewRow>
        <TableViewRow><Label>Row 2</Label></TableViewRow>
    </TableView>
</Alloy>

# hideSearchOnSelection

Availability
0.8
9.2.0
hideSearchOnSelection :Boolean

Determines whether the search field should hide on completion.

Set to false to prevent the search field from being hidden when an item in the search results is clicked.

Many standard applications (such as Contacts) have a behavior equivalent to false for this value, but the default is true for legacy reasons.

The Android platform behaves as though this value were false.

Default: true


# index

Availability
0.8
9.2.0
index :Array<TableViewIndexEntry>

Array of objects (with title and index properties) to control the table view index.

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. If the index is -1 the table view will scroll to the top.


# maxClassname CREATION ONLY

Availability
5.2.0
maxClassname :Number

Max number of row class names.

See className for more details. This property will default to 32 when it is set to a number lesser than that.

Default: 32


# maxRowHeight

Availability
0.8
0.8
9.2.0
maxRowHeight :Number

Maximum row height for table view rows.


# minRowHeight

Availability
0.8
0.8
9.2.0
minRowHeight :Number

Minimum row height for table view rows.


# moveable

Availability
9.3.0
3.2.0
9.2.0
moveable :Boolean

Determines the rows' default moveable behavior, which allows them to be re-ordered by the user when the table is in editing or moving mode.

This property determines the default behavior of child rows, but may be overridden by a row's moveable property.

See the Titanium.UI.TableView description section for a full explanation of the TableView's editing and moving modes.

Default: Depends on `editing` and `moving` mode


# moving

Availability
9.3.0
3.2.0
9.2.0
moving :Boolean

Determines whether row moving mode is active.

The moving mode allows rows to be deleted or re-ordered, depending on their editable and moveable settings.

See the Titanium.UI.TableView description section for a full explanation of the TableView's editing and moving modes.

Default: false


# overScrollMode

Availability
3.1.0
overScrollMode :Number

Determines the behavior when the user overscrolls the view.

Default: Titanium.UI.Android.OVER_SCROLL_ALWAYS


# refreshControl

Availability
6.2.0
3.2.0
9.2.0
refreshControl :Titanium.UI.RefreshControl

View positioned above the first row that is only revealed when the user drags the list view contents down.

An alternate to the headerPullView property. See Titanium.UI.RefreshControl for usage and examples.


# resultsBackgroundColor CREATION ONLY

Availability
7.3.0
9.2.0
resultsBackgroundColor :String | Titanium.UI.Color

The background color of the search results (iOS-only).

For information about color values, see the "Colors" section of Titanium.UI. Note: A transparent background-color is not officially supported by Apple to prevent that the list of results overlaps with the list view below it.

Default: undefined (behaves as white)


# resultsSeparatorColor CREATION ONLY

Availability
7.3.0
9.2.0
resultsSeparatorColor :String | Titanium.UI.Color

Separator line color between rows inside search results, as a color name or hex triplet (iOS-only).

To make the line invisible, set this property to transparent, or the same value as the backgroundColor property. For information about color values, see the "Colors" section of Titanium.UI.

Default: undefined (behaves as gray)


# resultsSeparatorInsets CREATION ONLY

Availability
7.3.0
9.2.0
resultsSeparatorInsets :HorizontalInsets

The insets for search results separators (applies to all cells & iOS-only).

Cell separators do not extend all the way to the edge of the list view. This property sets the default inset for all cells in the table. Set this to a dictionary with two keys, left specifying inset from left edge and right specifying the inset from the right edge.


# resultsSeparatorStyle CREATION ONLY

Availability
7.3.0
9.2.0
resultsSeparatorStyle :Number

The separator style of the search results (iOS-only).


# rowHeight

Availability
0.8
0.8
9.2.0
rowHeight :Number

Default row height for table view rows.


# rowSeparatorInsets

Availability
5.2.0
9.2.0
rowSeparatorInsets :HorizontalInsets

The insets for table view cells (applies to all cells).

Cell separators do not extend all the way to the edge of the table view. Set this to a dictionary with two keys, left specifying inset from left edge and right specifying the inset from the right edge. This property is only available upon creation of the cells.

For example:

tableView1.rowSeparatorInsets = {
    left: 10,
    right: 10
};

# scrollable

Availability
7.3.0
0.8
9.2.0
scrollable :Boolean

If true, the tableview can be scrolled.

Default: true


# scrollIndicatorStyle

Availability
2.1.0
9.2.0
scrollIndicatorStyle :Number

Style of the scrollbar.

Default: Titanium.UI.iOS.ScrollIndicatorStyle.DEFAULT


# scrollsToTop

Availability
2.1.2
9.2.0
scrollsToTop :Boolean

Controls whether the scroll-to-top gesture is effective.

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 table view. If there are multiple 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.

Default: true


Availability
0.8
0.8
9.2.0

Search field to use for the table view.

In an Alloy application, you can use a <SearchView> or <SearchBar> element inside a <TableView> element.

<Alloy>
    <TableView>
      <!-- search, shorthand with Ti.UI.SearchBar -->
      <SearchBar platform="ios"/>
      <!-- search, shorthand with Ti.UI.Android.SearchView -->
      <SearchView ns="Ti.UI.Android" platform="android"/>
    </TableView>
</Alloy>

# searchAsChild

Availability
3.0.2
searchAsChild :Boolean

Determines whether the Titanium.UI.SearchBar or Titanium.UI.Android.SearchView appears as part of the TableView.

Set to false if the search view will be displayed in the action bar.

Default: true


# searchHidden

Availability
0.8
9.2.0
searchHidden :Boolean

Determines whether the search field is visible.

Set to true to hide the search field.

Default: false (search field visible)


# sectionCount READONLY

Availability
3.0.0
3.0.0
9.2.0
sectionCount :Number

Number of sections in this table view.


# sectionHeaderTopPadding

Availability
10.1.0
10.1.0
sectionHeaderTopPadding :Number

Padding above each section header.

If not set or set to -1, it defaults to an automatic spacing determined by the system.


# sections

Availability
3.1.0
3.0.0
9.2.0
sections :Array<Titanium.UI.TableViewSection>

Sections of this table.

In Release 3.0, this property is read-only on Android.

Due to a known issue, TIMOB-12616, the sections property should not be used for adding sections on iOS.


# separatorColor

Availability
0.8
0.8
9.2.0
separatorColor :String | Titanium.UI.Color

Separator line color between rows, as a color name or hex triplet.

To make the line invisible, set this property to transparent, or the same value as the backgroundColor property.

For information about color values, see the "Colors" section of Titanium.UI.

Default: platform-specific default color


# separatorInsets DEPRECATED

Availability
3.2.0
9.2.0
separatorInsets :HorizontalInsets

DEPRECATED SINCE 5.2.0

Use tableSeparatorInsets instead.

The insets for table view separators (applies to all cells).

Cell separators do not extend all the way to the edge of the table view. This property sets the default inset for all cells in the table. Set this to a dictionary with two keys, left specifying inset from left edge and right specifying the inset from the right edge.

For example:

tableView1.separatorInsets = {
    left: 10,
    right: 10
};

# separatorStyle

Availability
5.2.0
0.8
9.2.0
separatorStyle :Number

Separator style constant.


# showSearchBarInNavBar CREATION ONLY

Availability
8.1.0
9.2.0
showSearchBarInNavBar :Boolean

A Boolean indicating whether search bar will be in navigation bar.

If you want to show the search bar in navigation bar, set this property true during creation. Use the hidesSearchBarWhenScrolling property to control the visibility of the searchbar when scrolling.

Default: false


# showSelectionCheck

Availability
10.1.0
showSelectionCheck :Boolean

Determines whether the selection checkmark is displayed on selected rows.

Default: true


# showVerticalScrollIndicator

Availability
0.8
9.2.0
showVerticalScrollIndicator :Boolean

Determines whether this table view displays a vertical scroll indicator.

Set to false to hide the vertical scroll indicator.

Default: true


# style

Availability
0.8
9.2.0
style :Number

Style of the table view, specified using one of the constants from Titanium.UI.iOS.TableViewStyle.

Style should always be set before setting the data on table view.


# tableSeparatorInsets

Availability
5.2.0
9.2.0
tableSeparatorInsets :HorizontalInsets

The insets for the table view header and footer.

Cell separators do not extend all the way to the edge of the table view. Set this to a dictionary with two keys, left specifying inset from left edge and right specifying the inset from the right edge. If the rowSeparatorInsets is not set, the tableSeparatorInsets will also set the cell insets.

For example:

tableView1.tableSeparatorInsets = {
    left: 10,
    right: 10
};

# touchFeedback

Availability
10.0.0
touchFeedback :Boolean

A material design visual construct that provides an instantaneous visual confirmation of touch point.

Touch feedback is only applied to a view's background.

Default: true

# Methods

# appendRow

Availability
0.8
0.8
9.2.0
appendRow(row[, animation]) void

Appends a single row or an array of rows to the end of the table.

Each row can be passed as a Titanium.UI.TableViewRow object, or as dictionary specifying the properties for a table row, in which case this TableView will create TableViewRow objects as needed.

On iOS, the row(s) can be inserted with animation by specifying a properties parameter.

Parameters

Name Type Description
row Titanium.UI.TableViewRow | Dictionary<Titanium.UI.TableViewRow> | Array<Titanium.UI.TableViewRow> | Array<Dictionary<Titanium.UI.TableViewRow>>

Row or rows to add to the table.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# appendSection

Availability
3.0.0
3.0.0
9.2.0
appendSection(section[, animation]) void

Appends a single section or an array of sections to the end of the table.

Each section can be passed as a Titanium.UI.TableViewSection object, or as dictionary specifying the properties for a table section, in which case this TableView will create TableViewSection objects as needed.

On iOS, the section(s) can be inserted with animation by specifying a properties parameter.

Due to a known issue, TIMOB-12616, this method should not be used for adding sections on iOS.

Parameters

Name Type Description
section Titanium.UI.TableViewSection | Dictionary<Titanium.UI.TableViewSection> | Array<Titanium.UI.TableViewSection> | Array<Dictionary<Titanium.UI.TableViewSection>>

Section or section to add to the table.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# deleteRow

Availability
0.8
0.8
9.2.0
deleteRow(row[, animation]) void

Deletes an existing row.

On iOS, the row can be deleted with animation by specifying a properties parameter. Starting in SDK 3.1.0, the row can be specified using Titanium.UI.TableViewRow on Android and iOS.

Parameters

Name Type Description
row Number | Titanium.UI.TableViewRow

Index of the row to delete, or the row object to delete.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# deleteSection

Availability
3.0.0
3.0.0
9.2.0
deleteSection(section[, animation]) void

Deletes an existing section.

On iOS, the section can be deleted with animation by specifying a properties parameter.

Parameters

Name Type Description
section Number

Index of the section to delete.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# deselectRow

Availability
0.8
9.2.0
deselectRow(row) void

Programmatically deselects a row.

Parameters

Name Type Description
row Number

Row index to deselect.

Returns

Type
void

# insertRowAfter

Availability
0.8
0.8
9.2.0
insertRowAfter(index, row[, animation]) void

Inserts a row after another row.

Each row can be passed as a Titanium.UI.TableViewRow object, or as dictionary specifying the properties for a table row, in which case this TableView will create TableViewRow objects as needed.

On iOS, the row(s) may be inserted with animation by setting the animation parameter.

Parameters

Name Type Description
index Number

Index of the row to insert after.

row Titanium.UI.TableViewRow | Dictionary<Titanium.UI.TableViewRow>

Row to insert.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# insertRowBefore

Availability
0.8
0.8
9.2.0
insertRowBefore(index, row[, animation]) void

Inserts a row before another row.

Each row can be passed as a Titanium.UI.TableViewRow object, or as dictionary specifying the properties for a table row, in which case this TableView will create TableViewRow objects as needed.

On iOS, the row(s) may be inserted with animation by setting the animation parameter.

Parameters

Name Type Description
index Number

Index of the row to insert before.

row Titanium.UI.TableViewRow | Dictionary<Titanium.UI.TableViewRow>

Row to insert.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# insertSectionAfter

Availability
3.0.0
3.0.0
9.2.0
insertSectionAfter(index, section[, animation]) void

Inserts a section after another section.

Each section can be passed as a Titanium.UI.TableViewSection object, or as dictionary specifying the properties for a table section, in which case this TableView will create TableViewSection objects as needed.

On iOS, the section(s) may be inserted with animation by setting the animation parameter.

Due to a known issue, TIMOB-12616, this method should not be used for adding sections on iOS.

Parameters

Name Type Description
index Number

Index of the section to insert after.

section Titanium.UI.TableViewSection | Dictionary<Titanium.UI.TableViewSection>

section to insert.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# insertSectionBefore

Availability
3.0.0
3.0.0
9.2.0
insertSectionBefore(index, section[, animation]) void

Inserts a section before another section.

Each section can be passed as a Titanium.UI.TableViewSection object, or as dictionary specifying the properties for a table section, in which case this TableViewSection will create TableViewSection objects as needed.

On iOS, the section(s) may be inserted with animation by setting the animation parameter.

Due to a known issue, TIMOB-12616, this method should not be used for adding sections on iOS.

Parameters

Name Type Description
index Number

Index of the section to insert before.

section Titanium.UI.TableViewSection | Dictionary<Titanium.UI.TableViewSection>

section to insert.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# scrollToIndex

Availability
0.8
0.8
9.2.0
scrollToIndex(index[, animation]) void

Scrolls the table view to ensure that the specified row is on screen.

On iOS, specify a TableViewAnimationProperties object to control the position that the selected row is scrolled to, and whether scrolling is animated.

Parameters

Name Type Description
index Number

Row index to scroll to.

animation TableViewAnimationProperties

Animation properties.

Returns

Type
void

# scrollToTop

Availability
0.8
0.8
9.2.0
scrollToTop(top[, animation]) void

Scrolls the table to a specific top position where 0 is the topmost y position in the table view.

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 Type Description
top Number

Y position for the top of the table view.

animation TableViewAnimationProperties

Animation properties.

Returns

Type
void

# selectRow

Availability
3.0.0
1.8.2
9.2.0
selectRow(row) void

Programmatically selects a row. In Android, it sets the currently selected item. If in touch mode, the item will not be selected but it will still be positioned appropriately. If the specified selection position is less than 0, then the item at position 0 will be selected.

Parameters

Name Type Description
row Number

Row index to select.

Returns

Type
void

# setContentInsets

Availability
2.1.0
9.2.0
setContentInsets(edgeInsets[, options]) void

Sets this tableview's content insets.

A table view 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 property.

Parameters

Name Type Description
edgeInsets Padding

Sets the distance that the content view is inset from the enclosing scroll view of the table. For example:

setContentInset({ top: 50, bottom: 10, right: 10, left: 10 }, { animated: true });
options AnimatedWithDurationOptions

Determines whether, and how, the content inset change should be animated.

Note that the default here is equivalent to passing in { animated: false }

Returns

Type
void

# setContentOffset

Availability
10.1.0
3.4.0
9.2.0
setContentOffset(contentOffset[, options]) void

Sets the value of the content offset of the table view without animation by default.

Parameters

Name Type Description
contentOffset Point

Dictionary with the properties x, y. The x and y coordinates reposition the top-left point of the scrollable region of the table view.

options AnimatedOptions

Pass in { animated: true } to animate the transition.

Note that the default here is equivalent to passing in { animated: false }

Returns

Type
void

# setData

Availability
0.8
0.8
9.2.0
setData(data[, animation]) void

Sets the data in the table.

Each row can be passed as a Titanium.UI.TableViewRow object, or as dictionary specifying the properties for a table row, in which case this TableView will create TableViewRow objects as needed.

setData can also be used to add Titanium.UI.TableViewSections to a table view.

Parameters

Name Type Description
data Array<Titanium.UI.TableViewRow> | Array<Dictionary<Titanium.UI.TableViewRow>> | Array<Titanium.UI.TableViewSection>

Rows or sections to add to this table.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# setHeaderPullView DEPRECATED

Availability
2.1.0
9.2.0
setHeaderPullView(view) void

DEPRECATED SINCE 10.0.0

Use the headerPullView property instead.

Sets the value of the [Titanium.UI.TableView.headerPullView] property.

Parameters

Name Type Description
view Titanium.UI.View

View to display.

Returns

Type
void

# updateRow

Availability
0.8
0.8
9.2.0
updateRow(index, row, animation) void

Updates an existing row, optionally with animation.

Parameters

Name Type Description
index Number

Index of the row to update.

row Titanium.UI.TableViewRow

Row data to update.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# updateSection

Availability
3.0.0
3.0.0
9.2.0
updateSection(index, section, animation) void

Updates an existing section, optionally with animation.

Known issues:

  • On iOS, event listeners do not fire correctly after table view sections are updated using the updateSection methods. (TIMOB-12616

Parameters

Name Type Description
index Number

Index of the section to update.

section Titanium.UI.TableViewSection

section data to update.

animation TableViewAnimationProperties

Animation properties. (iOS only.)

Returns

Type
void

# Events

# swipe

Availability
2.1.0
2.1.0
9.2.0

Fired when the device detects a swipe gesture (left or right) against the view.

Properties

Name Type Description
direction String

Direction of the swipe, either left or right.

index Number

Row index.

row Titanium.UI.TableViewRow

Table view row object.

rowData Dictionary<Titanium.UI.TableViewRow>

Properties of the row.

When the row is created implicitly using a JavaScript dictionary object, use this property rather than row to access any custom row properties.

Here's an example of creating a row implicitly, which is not the recommended way.

var data = [{title:'Row 1', hasChild:true, color:'red', selectedColor:'#fff', special:'special 1'},];
var table = Ti.UI.createTableView({data: data});
x Number

X coordinate of the event's endpoint from the source view's coordinate system.

y Number

Y coordinate of the event's endpoint from the source view's coordinate system.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# twofingertap

Availability
0.9
9.2.0

Fired when the device detects a two-finger tap against the view.

Properties

Name Type Description
x Number

X coordinate of the event from the source view's coordinate system.

y Number

Y coordinate of the event from the source view's coordinate system.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# touchstart

Availability
0.9
0.9
9.2.0

Fired as soon as the device detects a touch gesture against this view.

On Android and iOS, be aware that a row or table touch event and a table scroll event cannot occur concurrently. If a table begins to scroll during a touch event, the appropriate row or table touchcancel event fire before the scroll event begins.

Properties

Name Type Description
index Number

Row index.

row Titanium.UI.TableViewRow

Table view row object.

rowData Dictionary<Titanium.UI.TableViewRow>

Properties of the row.

When the row is created implicitly using a JavaScript dictionary object, use this property rather than row to access any custom row properties.

Here's an example of creating a row implicitly, which is not the recommended way.

var data = [{title:'Row 1', hasChild:true, color:'red', selectedColor:'#fff', special:'special 1'},];
var table = Ti.UI.createTableView({data: data});
x Number

X coordinate of the event from the source view's coordinate system.

y Number

Y coordinate of the event from the source view's coordinate system.

force Number

The current force value of the touch event. Note: This property only available for iOS devices that support 3D-Touch and run 9.0 or later.

maximumPossibleForce Number

Maximum possible value of the force property. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

altitudeAngle Number

A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0. Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.

timestamp Number

The time (in seconds) when the touch was used in correlation with the system start up. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# touchcancel

Availability