# Titanium.UI.TableViewRow

A table view row is an individual item in a table, organized into table view sections.

Availability

0.9

9.2.0

Extends

Titanium.UI.View

# Overview

Use the Titanium.UI.createTableViewRow method or <TableViewRow> Alloy element to create a table view row.

These may be explicitly added to Titanium.UI.TableViewSection objects, which are applied to a Titanium.UI.TableView. If a table section is not specified, one will be automatically created.

A row's contents can be as simple as a single line of text, or comprised of a completely customized layout of child views.

# Creating Table View Rows

Rows may be created using the properties directly available on the TableViewRow object, to achieve the following:

Row title to display the text content in the row.
Background color and background image.
Images on the left and right sides of the row.
System decorations, such as checkboxes.

Alternatively, custom layouts of multiple lines of text, different fonts, and additional images or controls can be created by adding child views to the row. In this case, the row's title property should not be set.

As events automatically bubble/propogate to parent views, a listener may be placed on the table view to detect events fired from the rows. The benefit is that it is not necessary to explicitly create a listener for every individual row.

See the Titanium.UI.TableView description and examples section for more information about creating table rows.

# Platform Implementation Notes

The top, left and other positional parameters are not used for their usual purposes, because the table view row is automatically positioned by its parent.

On Android, these properties are used to position the content (title) inside the row. For example, setting top to 20 moves the title down from the top of the row.

On iOS, these values have no effect.

Also, note that the selected text color, selectedColor, can only be set on iOS. On Android, the text color does not change when the row is selected.

# Row Swipe Gestures (Android and iOS)

A common requirement is to enable the user to interact with table rows using swipe gestures. As this event is not available for the TableViewRow object, it will not "bubble up" to the TableView, where a Titanium.UI.TableView.swipe is recognized.

A typical solution is to use a standard view as a container, or wrapper, for all each row's child views, because it recognizes Titanium.UI.View.swipe events and allows them to pass to the table. Each child view should have touch events disabled, so that the container view provides a reliable source for these events. Refer to the "Row Swipe Gestures" example for a demonstration.

For iOS, read the Titanium.UI.TableView regarding the interactions between edit modes and swipes.

# Examples

# Simple Table View Row example

Create a table view row containing a red square view.

var row = Titanium.UI.createTableViewRow();
var view = Titanium.UI.createView({
  backgroundColor:'red',
  width: 20, height: 20
});
row.add(view);

# Row Swipe Gestures

Create a table of rows. When a row is swiped, output its ID to the log.

var tableData = [];

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

var table = Ti.UI.createTableView({ objName: 'table' });

for (var i = 0; i <= 20; i++){
  var row = Ti.UI.createTableViewRow({
    className: 'row',
    objName: 'row',
    touchEnabled: true,
    height: 100
  });

  var enabledWrapperView = Ti.UI.createView({
    backgroundColor:'#008FD5',
    objName: 'enabledWrapperView',
    rowID: i,
    width: Ti.UI.FILL, height: '100%'
  });

  var disabledWrapperView = Ti.UI.createView({
    backgroundColor:'#A2E0FF',
    objName: 'disabledWrapperView',
    touchEnabled: false,
    width: 300, height: '80%'
  });
  enabledWrapperView.add(disabledWrapperView);

  var label = Ti.UI.createLabel({
    backgroundColor:'#313F48',
    color: 'white',
    objName: 'label',
    text: i,
    touchEnabled: false,
    left: 0,
    width: 200
  });
  disabledWrapperView.add(label);

  row.add(enabledWrapperView);
  tableData.push(row);
}

table.data = tableData;

table.addEventListener('swipe', function(e){
  if (e.source && e.source.objName !== 'table'){
    Ti.API.info('Row swiped: ' + e.source);
    Ti.API.info('Row swiped: ' + e.source.objName);
    Ti.API.info('Row ID : ' + e.source.rowID);
  }
});

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

# Alloy XML Markup

Previous simple table view row example as an Alloy view.

<Alloy>
    <TableViewRow id="row">
        <View id="view" backgroundColor="red" width="20" height="20"/>
    </TableViewRow>
</Alloy>

# Properties

# accessibilityLabel

Availability

3.0.0

9.2.0

accessibilityLabel :String

A succint label associated with the table row for the device's accessibility service.

See accessibilityLabel description.

# backgroundSelectedColor

Availability

10.0.0

backgroundSelectedColor :String | Titanium.UI.Color

Background color to render when the row is selected, as a color name or hex triplet.

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

# backgroundSelectedImage

Availability

10.0.0

backgroundSelectedImage :String

Background image to render when the row is selected.

For normal views, the selected background is only used if focusable is true.

If backgroundSelectedImage is undefined, and the normal background image backgroundImage is set the normal image is used when this view is selected.

# className

Availability

0.9

className :String

Class name for the row.

A class name represents a unique row layout.

A table view row must have a unique class name if the row layout is unique. However, use the same name for rows that have the same structural layout (even if the content is different) to provide maximum rendering performance.

For example, if some rows include images and some rows do not, you would have two class names, one for image rows and one for plain rows.

This property exists on iOS, but is ignored.

# color

Availability

0.9

9.2.0

color :String | Titanium.UI.Color

Default text color of the row when not selected, as a color name or hex triplet.

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

On Android, the default text color is black if the background color is closer to white otherwise the default text color is white also selectedColor is not supported so the text is always displayed in this color.

# deleteButtonTitle

Availability

0.9

9.2.0

deleteButtonTitle :String

Text to display on the delete button when editable is enabled

When editable is enabled on the TableViewRow, use this property to change the title of the delete button.

# editable

Availability

9.3.0

3.2.0

9.2.0

editable :Boolean

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

If this property is not explicitly set, it will return undefined and the row's editable behavior will be determined by its parent table's editable property.

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

If you want to change the title of the delete button, use the [deleteButtonTitle](Titanium.UI.TableViewRow.deleteButtonTitle] property

Default: undefined

# font

Availability

0.9

9.2.0

font :Font

Font to use for the row title.

Default: System default font.

Availability

0.9

9.2.0

footer :String

DEPRECATED SINCE 10.0.0

Use the footerTitle property instead.

The footer title of the row.

The footer property is used to assign a footer title to a row. It has the same effect as setting the footerTitle property of a Titanium.UI.TableViewSection.

# footerTitle

Availability

10.0.0

footerTitle :String

The footer title of the row.

The footerTitle property is used to assign a footer title to a row. It has the same effect as setting the footerTitle property of a Titanium.UI.TableViewSection.

# hasCheck

Availability

0.9

9.2.0

hasCheck :Boolean

Determines whether a system-provided checkmark is displayed on the right-hand side of the row.

Default: false

# hasChild

Availability

0.9

9.2.0

hasChild :Boolean

Determines whether a system-provided arrow is displayed on the right-hand side of the row.

The hasChild flag is used to indicate to the user that clicking on the row displays more detailed information.

On iOS, this is specifically used when clicking on the row navigates to the next table view in a heirarchy of table views.

Default: false

# hasDetail

Availability

9.3.0

0.9

9.2.0

hasDetail :Boolean

Determines whether a system-provided detail disclosure button is displayed on the right-hand side of the row.

The hasDetail flag is used to indicate to the user that more details are available on the row.

Specifically on iOS the detail disclosure button indicates that clicking on the row results in a detail view of that item.

The detail property in the click event is set to true if the click occurred on the detail button itself, false if the click occurs anywhere else in the row.

For rows that have hasDetail set to false, the detail flag is always false.

Default: false

Availability

0.9

9.2.0

header :String

DEPRECATED SINCE 10.0.0

Use the headerTitle property instead.

The header title of the row.

The header property is used to assign a header title to a row. It has the same effect as setting the headerTitle property of a Titanium.UI.TableViewSection.

# headerTitle

Availability

10.0.0

headerTitle :String

The header title of the row.

The headerTitle property is used to assign a header title to a row. It has the same effect as setting the headerTitle property of a Titanium.UI.TableViewSection.

# indentionLevel

Availability

0.9

9.2.0

indentionLevel :Number

Indention level for the row.

Indentation values greater than 0 indent the row text.

Default: 0

# leftImage

Availability

0.9

9.2.0

leftImage :String

Image to render in the left image area of the row, specified as a local path or URL.

# moveable

Availability

9.3.0

3.2.0

9.2.0

moveable :Boolean

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

If this property is not explicitly set, it will return undefined and the row's moveable behavior will be determined by its parent table's moveable property.

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

Default: undefined

# opacity

Availability

0.9

opacity :Number

Opacity of this view, from 0.0 (transparent) to 1.0 (opaque). Defaults to 1.0 (opaque).

To set the opacity of a row on iOS, specify an aRGB value with the <Titanium.UI.TableViewRow.backgroundColor> property.

# rightImage

Availability

0.9

9.2.0

rightImage :String

Image to render in the right image area of the row, specified as a local path or URL.

# selectedBackgroundColor DEPRECATED

Availability

0.9

9.2.0

selectedBackgroundColor :String | Titanium.UI.Color

DEPRECATED SINCE 10.0.0

This property has been deprecated in favor of backgroundSelectedColor.

Background color to render when the row is selected, as a color name or hex triplet.

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

# selectedBackgroundImage DEPRECATED

Availability

0.9

9.2.0

selectedBackgroundImage :String

DEPRECATED SINCE 10.0.0

This property has been deprecated in favor of backgroundSelectedImage.

Background image to render when the row is selected.

# selectedColor

Availability

0.9

9.2.0

selectedColor :String | Titanium.UI.Color

Color of the row text when the row is selected, as a color name or hex triplet.

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

# selectionStyle

Availability

10.1.0

5.4.0

9.2.0

selectionStyle :Number

Selection style constant to control the selection color.

Specify one of the constants from <Titanium.UI.SELECTION_STYLE_*>.

# title

Availability

0.9

9.2.0

title :String

Text to display on the row.

Do not specify if using views as children of the row.

# Events

# click

Availability

0.9

9.2.0

Fired when a table row is clicked by the user.

There is a subtle difference between singletap and click events.

A singletap event is generated when the user taps the screen briefly without moving their finger. This gesture will also generate a click event.

However, a click event can also be generated when the user touches, moves their finger, and then removes it from the screen.

On Android, a click event can also be generated by a trackball click.

Properties

Name	Type	Description
detail	Boolean	Indicates whether the detail button was clicked. Only `true` if `row.hasDetail` is `true` and the detail button was clicked.
index	Number	Row index.
row	Titanium.UI.TableViewRow	Table view row object.
rowData	Dictionary<Titanium.UI.TableViewRow>	Dictionary containing the properties set on the row.
searchMode	Boolean	Boolean to indicate if the table is in search mode.
section	Titanium.UI.TableViewSection	Table view section object, if the clicked row is contained in a section.
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.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# touchcancel

Availability

0.9

9.2.0

Fired when a touch gesture is interrupted by the device.

Generated in various circumstances, including an incoming call to allow the UI to clean up state.

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
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.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# touchend

Availability

0.9

9.2.0

Fired when a touch gesture is complete.

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.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# touchstart

Availability

0.9

9.2.0

Fired as soon as the device detects a touch gesture against this 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.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# Titanium.UI.TableViewRow

# Overview

# Creating Table View Rows

# Platform Implementation Notes

# Row Swipe Gestures (Android and iOS)

# Examples

# Simple Table View Row example

# Row Swipe Gestures

# Alloy XML Markup

# Properties

# accessibilityLabel

# backgroundSelectedColor

# backgroundSelectedImage

# className

# color

# deleteButtonTitle

# editable

# font

# footer DEPRECATED

# footerTitle

# hasCheck

# hasChild

# hasDetail

# header DEPRECATED

# headerTitle

# indentionLevel

# leftImage

# moveable

# opacity

# rightImage

# selectedBackgroundColor DEPRECATED

# selectedBackgroundImage DEPRECATED

# selectedColor

# selectionStyle

# title

# Events

# click

Properties

# touchcancel

Properties

# touchend

Properties

# touchstart

Properties