widget.newTabBar() takes a single argument, options, which is a Lua table that accepts the following parameters:

 
width, height
numbers. Set these if you want to use a custom width/height for your tab bar. The default width is equal to display.contentWidth, and the default height is 50.

 
left, top
numbers. This is the position where you want your tab bar to be created. Most iOS apps place the tabBar at the bottom of the screen (which would be display.contentHeight - tabBar.height, or default 50). The default values for left and top are 0, 0.

 
background
string. If you'd rather use a static image for the background of your tab bar, specify the filename to your graphics resource here.

 
baseDir
system folder. If using a background image and need to specify a base directory different from the default (system.ResourceDirectory), you may set this to system.DocumentsDirectory, system.TemporaryDirectory, or system.CachesDirectory).

 
topGradient
gradient object via graphics.newGradient(). If no graphics asset is specified with the 'background' parameter, by default the tabBar background will consist of a gradient for the top half of the background, and a solid color for the bottom. If you want to use a custom gradient for the top-half of the tabBar, create one using graphics.newGradient() and set a reference to it here.

 
bottomFill
table. If no custom graphic is being used, you can optionally set the color of the bottom half of the tabBar. Pass the red, green, blue, and alpha channels in a table. The default is black:
{ 0, 0, 0, 255 }

 
buttons
table. This is a table that will hold all parameters and options for the individual tab buttons. Please see the Buttons Table section below for more information.

Buttons Table

The buttons table is a parameter that is referenced as an option for the tabBar widget. This table should have sub-tables that represent the individual buttons that will be placed on the tabBar.

In the example shown above, tabButtons is the buttons table that has two buttons (see it for further demonstration).

Button Parameters

You can set the following parameters for each button table:

 
id
string. You can set this to be whatever you want. By default this will equal the number that represents the button's index on the tabBar. For instance, the second button would have a default id of 2.

 
up
string. This represents the filename for the 'up'-state icon for this button. This should not be omitted.

 
upWidth, upHeight
[NOTE: Deprecated as of build 2012.721—use width/height instead] numbers. These parameters should be equal to the width and height of your 'up'-state icon for the button. Recommended icon size is 32 x 32.

 
down
string. This represents the filename for the 'down'-state (selected tab) icon for this button. This should not be omitted.

 
downWidth, downHeight
[NOTE: Deprecated as of build 2012.721—use width/height instead]numbers. These parameters should be equal to the width and height of your 'down'-state (selected tab) icon for the button. Recommended icon size is 32 x 32.

 
width, height
numbers. Requires build 2012.721 or higher (and should be used in place of upWidth/upHeight and downWidth/downHeight. These numbers should represent the width and height of the tab button image size. Default is 32 x 32.

 
baseDir
system directory. If the icon graphics for your button are not in system.ResourceDirectory (default), specify the alternate base directory here.

 
label
string. This is the text that will appear below the button's icon. If no label is specified, no text will be shown, and the icon will be shifted down. It is recommended you remain consistent with all buttons on your tab bar (if you set a label for one, you should set one for all).

 
font
string. The font that will be used for your label text, if label text is specified. Default is native.systemFontBold.

 
size
number. The font size (in pixels) for your label text. Default is 10 (in most cases, this should be very small).

 
labelColor
table. This is a table that will hold values that represent the red, green, blue, and alpha channels for the color of your label text. The default is:
{ 124, 124, 124, 255 }

 
cornerRadius
number. When a tab button is selected, a rounded rectangle appears over the button. This parameter sets the roundness of the corners of that rectangle. The default is 4.

 
selected
boolean (true/false). This determines if the button is in it's 'selected' (down) state upon creation. No more than ONE of your buttons should have this parameter set to true when you create your buttons table.

 
onPress
function. This is the listener function that is called when the tab button is pressed.

Event Table

Your onPress event listener can have up to one argument, which will be an event table that holds specific event-related data, which includes:

 
event.name
This will always be "tabButtonPress"

 
event.target
This is a reference to the actual tab button that triggered the event.

 
event.targetParent
This is a reference to the tabBar widget which is the parent of the button that triggered the event.

Properties and Methods:

Below are the individual properties and methods associated with the tabBar widget (not the buttons):

 
pressButton( buttonIndex [, invokeListener] )
Available since build 2011.700. If you need to make a specific button on the tab bar pressed, you can call the pressButton() method and specify the button index you want to be in the "down" state. Optionally, you can invoke the 'onPress' listener for the button at this time (default is false). Example:

    myTabBar:pressButton( 1 )  -- put first button in 'down' state
 
    myTabBar:pressButton( 3, true )  -- 3rd button in down state and invoke onPress listener

 
view
[NOTE: Deprecated as of build 2012.721—the widget is now 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:

    -- prior to build 2012.721:   
 
    -- WRONG, will produce error:
    myGroup:insert( myTabBar )
 
    -- CORRECT: access display group with .view property
    myGroup:insert( myTabBar.view )
 
    - after build 2012.72:
 
    myGroup:insert( myTabBar ) -- correct

 
x, y
numbers. Normally, to access display object properties of the widget, you'd do so by using the .view property of the widget. However, you can optionally use the x/y property shortcut to change the on-screen location of the widget. Example:

    -- move the tabBar to specific location on screen:
    myTabBar.x = 160
    myTabBar.y = 480-25

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( myTabBar )
    myTabBar = nil
 
    -- or...
 
    myTabBar:removeSelf()
    myTabBar = nil
 
    -- IMPORTANT NOTE:
    -- Don't forget to set the reference variable to nil! (as shown above)