widget.newTableView() takes a single argument, options, which is a Lua table that accepts specific parameters. Please read over Properties and Methods section before using this widget, and study the example above.

 
bgColor
table. This table should have the red, green, blue, and alpha channels for the color of the rectangle to be placed behind the tableView. Default is white:
{ 255, 255, 255, 255 }

 
hideBackground
[Requires build 2012.721 or later] boolean (true/false). If you set this parameter to false, the background of the tableView widget will be hidden (but still receive touches).

 
left, top
numbers. The left and top coordinate in which the tableView will be placed upon creation. The default value for both is 0.

 
width, height
numbers. The width represents the maximum width that rows will be rendered. The height represents the total height of the tableView. The default values are the full width and height of the screen. Remember, if you set a height, you must provide a matching bitmap mask so the tableView is cropped correctly. Read this tutorial to learn how to create a bitmap mask for use with tableViews and scrollViews.

 
topPadding, bottomPadding
numbers. These are numbers that represent the number of pixels from the top and bottom of the tableView in which rows will stop when you reach the top/bottom of the list. The default value for both is 0.

 
renderThresh
number. This is the pixel amount to the top and bottom of the tableView in which rows are rendered and de-rendered. If for whatever reason you're able to see the rows being de-rendered, you should increase this value from the default of 150. In most cases, you should never have to touch this.

 
friction
number. This determines how fast the rows travel when they are flicked up or down. The default value is 0.935, which should be sufficient for most cases. In previous versions of this widget, you were not able to set this property, but we realized there may be times you want the "flick speed" to be faster or slower.

 
maxVelocity
[Requires build 2012.721 or later] number. Use this to limit the maximum scrolling speed of the TableView widget. The default value is 10.

 
maskFile
string. If you set a custom height, you need to specify the maskFile parameter, which is the filename of the bitmap mask which will be used on your tableView. Read this tutorial to learn how to create a bitmap mask for use with tableViews and scrollViews.

Properties and Methods

 
view
NOTE: As of build 2012.721, there is no longer a .view property. The widget IS the display object.. If you need to do something with the widget's display object (such as place the button into a display group), you need to do so using the object's .view property. Example:

    -- Only applies to builds prior to 2012.721:
 
    -- WRONG, will produce error:
    myGroup:insert( list )
        
    -- CORRECT: access display group with .view property
    myGroup:insert( list.view )

 
view.content
This is the display group that represent the content that holds all the display objects of every row. The rows table is accessed from view.content.rows

 
isLocked
boolean (true/false). If set to true, the tableView will be prevented from scrolling.

 
tableView:insertRow( [params] )
This method is used for inserting rows into the tableView (see example for usage demonstration). This function accepts the following parameters:

id (string, can be used to identify row)
width, height (numbers)
rowColor, lineColor (tables with r, g, b, a values)
isCategory (boolean, true/false - will cause row to "stick" to top of tableView)
listener build 2012.721 (function - see Row Events section)
onEvent (function - see Row Events section)
onRender (function - see Row Events section)

 
tableView:deleteRow( rowOrIndex )
Use this method to delete specific row by index number, or by passing the actual row table (if in an event listener, that would be event.target).

 
tableView:getScrollPosition()
NOTE: If you're using build 2012.721 or later, this method is no longer available. It has been replaced with getContentPosition(). This will return the current yPosition of the tableView content. This is mostly used to mark a position of the tableView, and then scroll to that stored position using the scrollToY() method. Since tableViews can't be rotated, it's recommended you use this function to mark the content position, destroy the tableView, then recreate it in the correct position (orientation?) and use scrollToY() to return it to it's previous position.

 
tableView:getContentPosition()
[Requires build 2012.721 or later] See getScrollPosition() (above).

 
tableView:scrollToY( yPosition, timeInMs )
Make tableView scroll to a specific y position (Note: this will most-likely be a negative number). This method is normally used after the getScrollPosition() method. timeInMs is the time in milliseconds it will take to scroll to the desired position. If you want the scrolling to be instantaneous (no effect), set timeInMs to 0. The default value for timeInMs is 1500.

 
tableView:scrollToIndex( index, timeInMs )
Make tableView scroll to a specific row that has the index position 'index'. The top of the row will be at the top position of the tableView (plus topPadding, if any). timeInMs is the time in milliseconds it will take to scroll to the desired position. If you want the scrolling to be instantaneous (no effect), set timeInMs to 0. The default value for timeInMs is 1500.

Row Events

When you call the insertRow() method with your tableView, you pass a table of parameters. Two of the parameters are onEvent and onRender, which correspond to your touch listener (onEvent) for that specific row item, and the render listener (onRender) which is responsible for creating the row's visual elements (all controlled by you). Please see the example for basic usage demonstration.

When you create your event listeners, they will have a table passed as the first argument, which includes the following keys:

 
event.name
For onRender listeners, this will be "tableView_onRender", and for onEvent listeners, it will be "tableView_onEvent".

 
event.tableView
NOTE: If using build 2012.721 or later, use event.parent instead. This is a reference to the tableView widget object that the row belongs to (onRender, onEvent)

 
event.parent
[Requires build 2012.721 or later] Direct reference to the tableView that the row belongs to.

1
2
3
4

event.background</strong>
[<strong>Requires build 2012.721 or later</strong>] Direct reference to the background rectangle for the row.
 
<code> 

1
2
3
4

event.line</strong>
[<strong>Requires build 2012.721 or later</strong>] Direct reference to the vector line object for the row (appears at the bottom of the row, used to help visually separate it from other rows).
 
<code> 

 
event.view
This is a reference to the display group that holds all of the row's display objects. If you create a display object for a specific row in your onRender listener (such as a text object, or an image), you MUST insert those objects into the event.view group or they will not get rendered properly, and may even cause memory leaks (see example for usage).

 
event.phase
For onEvent listeners, the event.phase will either be "press" or "release". For onEvent listeners, you should always test for a phase, and return true on success. As build 2011.701, two are available: "leftSwipe" and "rightSwipe". As of build 2012.721, another phase has been added: "tap"

 
event.index
This is a number that represent's the row's position in the tableView. For instance, if the first row item triggered the onRender or onEvent callback listener, the event.index would be 1.

Removing the widget:

This widget can be removed in the same manner as any other display object, by using display.remove() or the removeSelf() method. Example:

    display.remove( list )
    list = nil
        
    -- or...
        
    list:removeSelf()
    list = nil
        
    -- IMPORTANT NOTE:
    -- Don't forget to set the reference variable to nil! (as shown above)