widget.newTabBar()

id _^(optional)

String. An optional identification to assign to the tab bar. Default is widget_tabBar.

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 tab bar, in pixels. The default height is 52.

buttons _^(required)

Table. A table that contains sub-tables of parameters/options for the individual tabs that span the bar. Please see Configuring Tab Buttons below.

object:setSelected()

id _^(optional)

String. An optional identification to assign to the tab button. Default is button.

label _^(optional)

String. An optional text label that will appear along the bottom of the tab button area.

labelColor _^(optional)

Table. Table of two RGB+A color settings, one each for the default and over states.

labelColor = { default={ 1, 1, 1 }, over={ 0, 0, 0, 0.5 } }

labelXOffset, labelYOffset _^(optional)

Numbers. Optional x and y offsets for the tab button label. For example, labelYOffset = -8 will shift the label 8 pixels up from default.

font _^(optional)

String. Font used for the tab button label. Default is native.systemFont.

size _^(optional)

Number. Font size (in pixels) for the tab button label. Default is 8.

selected _^(optional)

Boolean. Set this to true to start the tab button in its selected/on state. Only one tab button should be set to selected = true on initialization.

onPress _^(optional)

Function. An optional function to be called when the tab button is pressed. The callback function does not require testing for event.phase since it only honors began.

baseDir _^(optional)

Constant. The base directory where your custom images are located. Default is your project folder (system.ResourceDirectory).

backgroundFile _^(optional)

String. The background image file for the tab bar. This may be designed to be flexible in width/height.

Highlight Overlay

You may configure an optional highlight overlay which will be placed in front of the background but behind the optional button image. Highlight overlays are composed of a left, middle, and right image file, each of which should be designed equal in size. However, if the tab is wider than the collective width of these three image files, the overlay will stretch to fit the width of the tab. In this case, the left and right edge images will remain at their original size, but the middle section will stretch to fill the distance between.

Tab Buttons

Within each sub-table of the buttons table (see Configuring Tab Buttons), you may add additional parameters to visually customize the button. Note that individual buttons can have a unique style according to the specified images.

sheet _^(required)

ImageSheet. The image sheet object for the tab bar.

backgroundFrame _^(optional)

String. The background image frame for the tab bar. This may be designed to be flexible in width/height.

backgroundFrameWidth, backgroundFrameHeight _^(required)

Numbers. The width and height of the background frame.

Highlight Overlay

You may configure an optional highlight overlay which will be placed in front of the background but behind the optional button image. Highlight overlays are composed of a left, middle, and right image frame, each of which should be designed equal in size. However, if the tab is wider than the collective width of these three image frames, the overlay will stretch to fit the width of the tab. In this case, the left and right edge frames will remain at their original size, but the middle section will stretch to fill the distance between.

Tab Buttons

Within each sub-table of the buttons table (see Configuring Tab Buttons), you may add additional parameters to visually customize the button. Note that individual buttons can have a unique style according to the specified frames.

Default

local widget = require( "widget" )

-- Function to handle button events
local function handleTabBarEvent( event )
    print( event.target.id )  -- Reference to button's 'id' parameter
end

-- Configure the tab buttons to appear within the bar
local tabButtons = {
    {
        label = "Tab1",
        id = "tab1",
        selected = true,
        onPress = handleTabBarEvent
    },
    {
        label = "Tab2",
        id = "tab2",
        onPress = handleTabBarEvent
    },
    {
        label = "Tab3",
        id = "tab3",
        onPress = handleTabBarEvent
    }
}

-- Create the widget
local tabBar = widget.newTabBar(
    {
        top = display.contentHeight-120,
        width = display.contentWidth,
        buttons = tabButtons
    }
)

Image Files

local widget = require( "widget" )

-- Function to handle button events
local function handleTabBarEvent( event )
    print( event.target.id )  -- Reference to button's 'id' parameter
end

-- Configure the tab buttons to appear within the bar
local tabButtons = {
    {
        width = 72, 
        height = 120,
        defaultFile = "tabBarIconDef.png",
        overFile = "tabBarIconOver.png",
        label = "Tab1",
        id = "tab1",
        selected = true,
        size = 16,
        labelYOffset = -8,
        onPress = handleTabBarEvent
    },
    {
        width = 72, 
        height = 120,
        defaultFile = "tabBarIconDef.png",
        overFile = "tabBarIconOver.png",
        label = "Tab2",
        id = "tab2",
        size = 16,
        labelYOffset = -8,
        onPress = handleTabBarEvent
    },
    {
        width = 72, 
        height = 120,
        defaultFile = "tabBarIconDef.png",
        overFile = "tabBarIconOver.png",
        label = "Tab3",
        id = "tab3",
        size = 16,
        labelYOffset = -8,
        onPress = handleTabBarEvent
    }
}

-- Create the widget
local tabBar = widget.newTabBar(
    {
        left = 0,
        top = display.contentHeight-120,
        width = 580,
        height = 120,
        backgroundFile = "tabBarBack.png",
        tabSelectedLeftFile = "tabBarSelL.png",
        tabSelectedRightFile = "tabBarSelR.png",
        tabSelectedMiddleFile = "tabBarSelM.png",
        tabSelectedFrameWidth = 40,
        tabSelectedFrameHeight = 120,
        buttons = tabButtons
    }
)

Image Sheet

local widget = require( "widget" )

-- Function to handle button events
local function handleTabBarEvent( event )
    print( event.target.id )  -- Reference to button's 'id' parameter
end

-- Image sheet options and declaration
-- For testing, you may copy/save the image under "Visual Customization: Image Sheet" above
local options = {
    frames =
    {
        { x=4, y=0, width=24, height=120 },
        { x=32, y=0, width=40, height=120 },
        { x=72, y=0, width=40, height=120 },
        { x=112, y=0, width=40, height=120 },
        { x=152, y=0, width=72, height=120 },
        { x=224, y=0, width=72, height=120 }
    },
    sheetContentWidth = 296,
    sheetContentHeight = 120
}
local tabBarSheet = graphics.newImageSheet( "widget-tabbar-sheet.png", options )

-- Configure the tab buttons to appear within the bar
local tabButtons = {
    {
        defaultFrame = 5,
        overFrame = 6,
        label = "Tab1",
        id = "tab1",
        selected = true,
        size = 16,
        labelYOffset = -8,
        onPress = handleTabBarEvent
    },
    {
        defaultFrame = 5,
        overFrame = 6,
        label = "Tab2",
        id = "tab2",
        size = 16,
        labelYOffset = -8,
        onPress = handleTabBarEvent
    },
    {
        defaultFrame = 5,
        overFrame = 6,
        label = "Tab3",
        id = "tab3",
        size = 16,
        labelYOffset = -8,
        onPress = handleTabBarEvent
    }
}

local tabBar = widget.newTabBar(
    {
        sheet = tabBarSheet,
        left = 0,
        top = display.contentHeight-120,
        width = 580,
        height = 120,
        backgroundFrame = 1,
        tabSelectedLeftFrame = 2,
        tabSelectedMiddleFrame = 3,
        tabSelectedRightFrame = 4,
        tabSelectedFrameWidth = 40,
        tabSelectedFrameHeight = 120,
        buttons = tabButtons
    }
)