widget.newTableView()

Type Function
Library widget.*
Return value TableView
Revision Current Public Release (2014.2189)
Keywords widget, tableview, lists, listview
See also TableViewWidget

Overview

Creates a TableView object.

Gotchas

The TableView widget contains a mask which constrains its view to the defined width and height. There is a nested masking limit of three on all platforms, so be careful when nesting other masked objects inside a TableView. Other display objects that contain masks include display.newContainer, display.newText, display.newEmbossedText, widget.newScrollView, and any other masked image, masked vector object, or masked display group.

The TableView widget does not support scaling.

Syntax

widget.newTableView( options )

This function takes a single argument, options, which is a table that accepts the following parameters:

id (optional)

String. An optional identification string to assign to the table view. Default is widget_tableView.

x / y (optional)

Numbers. Coordinates for the widget's x and y center point. These values will be overridden by left and top if those values are defined.

left / top (optional)

Numbers. The left and top position where the widget will be created. If specified, these values override the x and y parameters.

width / height (optional)

Numbers. The width and height of the table view.

friction (optional)

Number. Determines how fast the content travels when it is flicked up or down. The default value is 0.972.

maxVelocity (optional)

Number. Limits the maximum scrolling speed of the table view. The default value is 2.

isLocked (optional)

Boolean. If set to true, the table view will be locked, meaning it cannot be scrolled vertically.

isBounceEnabled (optional)

Boolean. If set to false, the table view will simply stop scrolling when it reaches the upper or lower limit. Default is true.

rowTouchDelay (optional)

Number. Specifies the delay, in milliseconds, until the row touch event is propagated.

onRowRender (optional)

Listener. The function used to listen for TableView row rendering events. This function is called when a row is added via object:insertRow(), when all visible rows are re-rendered via object:reloadData(), or when an off-screen row moves back on screen. In this function, event.row is a reference to the row that was rendered.

onRowTouch (optional)

Listener. The function used to listen for TableView touch/tap events. In this listener function, the event.phase values include "tap", "press", "release", "swipeLeft", and "swipeRight". In addition, event.target is a reference to the row that was interacted with and event.target.index is the index number of that row.

listener (optional)

Listener. The function used to listen for TableView motion/scroll events. In this listener function, event.phase returns the expected touch interaction phases of "began", "moved", or "ended". In addition, the scroll limit in either direction can be detected by event.limitReached. If this occurs, event.direction returns either "up" or "down" depending on the direction the table view was moving when the limit was reached.

Methods

Visual Options

The table view widget can be visually customized using the following parameters within the options table:

noLines (optional)

Boolean. If set to true, lines will not separate individual rows. The default value is false.

backgroundColor (optional)

Table. Table containing the RGB+A background color setting. Default is white.

backgroundColor = { 0.8, 0.8, 0.8 }
hideBackground (optional)

Boolean. If true, the background of the table view will be hidden, but it still receives touches.

hideScrollBar (optional)

Boolean. If set to true, the scroll bar will not appear for the table view.

scrollBarOptions (optional)

Table. Table containing the image sheet specifications for a custom scroll bar. Customizing the scroll bar requires 3 frames from an image sheet. Each frame needs to be a square of equal size. These frames represent the top of the bar (red), the middle of the bar (green), and the bottom of the bar (yellow).

Inside the scrollBarOptions table, you must specify 4 required parameters: sheet, topFrame, middleFrame, and bottomFrame.

scrollBarOptions = {
    sheet = scrollBarSheet,  --reference to the image sheet
    topFrame = 1,            --number of the "top" frame
    middleFrame = 2,         --number of the "middle" frame
    bottomFrame = 3          --number of the "bottom" frame
}
topPadding / bottomPadding (optional)

Numbers. These numbers represent the number of pixels from the top and bottom of the table view at which the content will stop when it reaches the respective limit. The default value for both is 0.

Inserting Rows

When you create a table view, it simply creates an empty region of the specified width and height. The actual rows are "rendered" via the object:insertRow() function.

To accomplish this, some basic setup is required. First, write a target listener function to render new rows, for example:

local function onRowRender( event )

    -- Get reference to the row group
    local row = event.row

    -- Cache the row "contentWidth" and "contentHeight" because the row bounds can change as children objects are added
    local rowHeight = row.contentHeight
    local rowWidth = row.contentWidth

    local rowTitle = display.newText( row, "Row " .. row.index, 0, 0, nil, 14 )
    rowTitle:setFillColor( 0 )

    -- Align the label left and vertically centered
    rowTitle.anchorX = 0
    rowTitle.x = 0
    rowTitle.y = rowHeight * 0.5
end

Next, specify the function in the onRowRender parameter of the table view declaration. At this point, you can call object:insertRow() to insert a new row, or execute the call in a loop to render several rows at once. Please refer to the usage examples below.

Examples

Basic TableView
local widget = require( "widget" )

-- The "onRowRender" function may go here (see example under "Inserting Rows", above)

-- Create the widget
local tableView = widget.newTableView
{
    left = 200,
    top = 200,
    height = 330,
    width = 300,
    onRowRender = onRowRender,
    onRowTouch = onRowTouch,
    listener = scrollListener
}

-- Insert 40 rows
for i = 1, 40 do
    -- Insert a row into the tableView
    tableView:insertRow{}
end
TableView with Category Rows
local widget = require( "widget" )

-- The "onRowRender" function may go here (see example under "Inserting Rows", above)

-- Create the widget
local tableView = widget.newTableView
{
    left = 200,
    top = 200,
    height = 330,
    width = 300,
    onRowRender = onRowRender,
    onRowTouch = onRowTouch,
    listener = scrollListener
}

-- Insert 40 rows
for i = 1, 40 do

    local isCategory = false
    local rowHeight = 36
    local rowColor = { default={ 1, 1, 1 }, over={ 1, 0.5, 0, 0.2 } }
    local lineColor = { 0.5, 0.5, 0.5 }

    -- Make some rows categories
    if ( i == 1 or i == 21 ) then
        isCategory = true
        rowHeight = 40
        rowColor = { default={ 0.8, 0.8, 0.8, 0.8 } }
        lineColor = { 1, 0, 0 }
    end

    -- Insert a row into the tableView
    tableView:insertRow(
        {
            isCategory = isCategory,
            rowHeight = rowHeight,
            rowColor = rowColor,
            lineColor = lineColor
        }
    )
end
TableView with Custom Scroll Bar
local widget = require( "widget" )

-- The "onRowRender" function may go here (see example under "Inserting Rows", above)

-- Create image sheet for custom scroll bar
local scrollBarOpt = {
    width = 20,
    height = 20,
    numFrames = 3,
    sheetContentWidth = 20,
    sheetContentHeight = 60
}
local scrollBarSheet = graphics.newImageSheet( "scrollBar.png", scrollBarOpt )

-- Create the widget
local tableView = widget.newTableView
{
    left = 200,
    top = 200,
    height = 330,
    width = 300,
    onRowRender = onRowRender,
    onRowTouch = onRowTouch,
    listener = scrollListener,
    scrollBarOptions = {
        sheet = scrollBarSheet,
        topFrame = 1,
        middleFrame = 2,
        bottomFrame = 3
    }
}

-- Insert 40 rows
for i = 1, 40 do

    -- Insert a row into the tableView
    tableView:insertRow(
        {
            isCategory = false,
            rowHeight = 36,
            rowColor = { default={ 1, 1, 1 }, over={ 1, 0.5, 0, 0.2 } },
            lineColor = { 0.5, 0.5, 0.5 }
        }
    )
end