Titanium.UI.TableViewRow

viewAndroidiPhoneiPadmacOSsince 0.9

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

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

These may be explicitly added to TableViewSection objects, which are applied to a 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 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 Row Editing and Moving Modes notes on 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 94

accessibilityDisableLongPress

BooleanAndroidsince 12.4.0

Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields 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.

Parameters	Type	Description
point	Point	A point in this view's coordinate system. If this argument is missing an `x` or `y` property, or the properties can not be converted into numbers, an exception will be raised.
destinationView	Titanium.UI.View	View that specifies the destination coordinate system to convert to. If this argument is not a view, an exception will be raised.

Parameters	Type	Description
callback?	Callback<Titanium.Blob>	Function to be invoked upon completion. If non-null, this method will be performed asynchronously. If null, it will be performed immediately.
honorScaleFactor?	Boolean	Determines whether the image is scaled based on scale factor of main screen. (iOS only) When set to true, image is scale factor is honored. When set to false, the image in the blob has the same dimensions for retina and non-retina devices.

Event properties	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.

Event properties	Type	Description
direction	String	Direction of the swipe--either 'left', 'right', 'up', or 'down'.
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.
obscured	Boolean	Returns `true` if the swipe passed through an overlapping window belonging to another app. This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Examples

Simple Table View Row example

Row Swipe Gestures

Alloy XML Markup

Properties 94

Linear and Radial Gradients

Methods 16

Events 9