widget.newSegmentedControl()

id _^(optional)

String. An optional identification to assign to the segmented control. Default is widget_segmentedControl.

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.

segmentWidth _^(optional)

Number. The width of each segment in pixels (all segments must be of equal width). Default is 50.

segments _^(required)

Table. Table of comma-separated strings which defines the total segment count and the label that appears on each. For example:

segments = { "Item 1", "Item 2", "Item 3", "Item 4" }

defaultSegment _^(optional)

Number. The segment that will be active upon the initial creation. Default is the first segment.

onPress _^(optional)

Listener. An optional function to be called when a segment is pressed. The callback function does not require testing for event.phase since it only honors began.

object.segmentLabel

object.segmentNumber

object:setActiveSegment()

labelSize _^(optional)

Number. Font size (in pixels) for the segment labels. Default is 12.

labelFont _^(optional)

String. Font used for the segment labels. Default is native.systemFont.

labelColor _^(optional)

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

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

emboss _^(optional)

Boolean. If set to true, the button label will appear embossed (inset effect).

labelXOffset, labelYOffset _^(optional)

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

sheet _^(required)

ImageSheet. The image sheet object for the segmented control.

segmentFrameWidth, segmentFrameHeight _^(required)

Numbers. The width/height of the main segment frames (end caps and middle spans). All of these frames should share the same width and height.

leftSegmentFrame, leftSegmentSelectedFrame _^(required)

Numbers. The inactive and active frames for the left end caps.

middleSegmentFrame, middleSegmentSelectedFrame _^(required)

Numbers. The inactive and active frames for the middle spans.

rightSegmentFrame, rightSegmentSelectedFrame _^(required)

Numbers. The inactive and active frames for the right end caps.

dividerFrame _^(optional)

Number. The frame index for the divider frame. Omit this if you don’t want dividers to be shown.

dividerFrameWidth, dividerFrameHeight _^(optional)

Numbers. The width/height of the divider frame. These are required if dividerFrame is defined.

Default

local widget = require( "widget" )

-- Listen for segmented control events      
local function onSegmentPress( event )
    local target = event.target
    print( "Segment Label is:", target.segmentLabel )
    print( "Segment Number is:", target.segmentNumber )
end

-- Create a default segmented control
local segmentedControl = widget.newSegmentedControl(
    {
        left = 50,
        top = 150,
        segmentWidth = 150,
        segments = { "Item 1", "Item 2", "Item 3", "Item 4" },
        defaultSegment = 2,
        onPress = onSegmentPress
    }
)

Image Sheet

local widget = require( "widget" )

-- Listen for segmented control events      
local function onSegmentPress( event )
    local target = event.target
    print( "Segment Label is:", target.segmentLabel )
    print( "Segment Number is:", target.segmentNumber )
end

-- Image sheet options and declaration
-- For testing, you may copy/save the image under "Visual Customization" above
local options = {
    frames = 
    {
        { x=0, y=0, width=40, height=68 },
        { x=40, y=0, width=40, height=68 },
        { x=80, y=0, width=40, height=68 },
        { x=122, y=0, width=40, height=68 },
        { x=162, y=0, width=40, height=68 },
        { x=202, y=0, width=40, height=68 },
        { x=245, y=0, width=4, height=68 }
    },
    sheetContentWidth = 250,
    sheetContentHeight = 68
}
local segmentSheet = graphics.newImageSheet( "widget-segmented-control.png", options )

-- Create a custom segmented control
local segmentedControl = widget.newSegmentedControl(
    {
        left = 50,
        top = 150,
    
        sheet = segmentSheet,
        leftSegmentFrame = 1,
        middleSegmentFrame = 2,
        rightSegmentFrame = 3,
        leftSegmentSelectedFrame = 4,
        middleSegmentSelectedFrame = 5,
        rightSegmentSelectedFrame = 6,
        segmentFrameWidth = 40,
        segmentFrameHeight = 68,

        dividerFrame = 7,
        dividerFrameWidth = 4,
        dividerFrameHeight = 68,
        
        segmentWidth = 90,
        segments = { "Item 1", "Item 2", "Item 3", "Item 4" },
        defaultSegment = 1,
        labelColor = { default={1,1,1,1}, over={1,0.3,0.8,1} },
        onPress = onSegmentPress
    }
)