Type Function Library widget.* Return value SegmentedControlWidget Revision Release 2024.3703 Keywords widget, segment, segmentedControl, control See also SegmentedControlWidget
Creates a SegmentedControlWidget object.
To conserve texture memory, a SegmentedControlWidget can only be created from an image sheet.
The SegmentedControlWidget object does not support scaling nor changing of the width/height via .width or .height.
The SegmentedControlWidget object does not support changing the anchorX or anchorY properties after creation.
widget.newSegmentedControl( options )
This function takes a single argument, options
, which is a table that accepts the following parameters:
String. An optional identification to assign to the segmented control. Default is widget_segmentedControl
.
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.
Numbers. The left and top position where the widget will be created. If specified, these values override the x
and y
parameters.
Number. The width of each segment in pixels (all segments must be of equal width). Default is 50
.
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" }
Number. The segment that will be active upon the initial creation. Default is the first segment.
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
.
Number. Font size (in pixels) for the segment labels. Default is 12
.
String. Font used for the segment labels. Default is native.systemFont.
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 } }
Boolean. If set to true
, the button label will appear embossed (inset effect).
Numbers. Optional x and y offsets for the segment labels. For example, labelYOffset = -8
will shift the labels 8 pixels up from default.
The segmented control widget can be visually customized using 7 frames from an image sheet. As shown in the following example, 6 of these frames can be used to assemble an inactive and active state for each segment. The inactive frames consist of the left cap (red), the middle span (green), and the right cap (yellow). The active frames consist of a left cap (orange), a middle span (blue), and a right cap (purple).
Depending on the width of the segments, the left and right caps remain at the size stated in the image sheet while the middle frames (green or blue) stretch to fill the remaining width of each segment.
Optionally, the segmented control accepts dividers between each segment, shown as the dark blue bar in this example. If defined, dividers overlay the other frames and are distributed evenly across the entire span of the segmented control. If you do not want dividers to appear, simply omit the three associated properties in the widget declaration.
→ |
ImageSheet. The image sheet object for the segmented control.
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.
Numbers. The inactive and active frames for the left end caps.
Numbers. The inactive and active frames for the middle spans.
Numbers. The inactive and active frames for the right end caps.
Number. The frame index for the divider frame. Omit this if you don't want dividers to be shown.
Numbers. The width/height of the divider frame. These are required if dividerFrame
is defined.
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 } )
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 } )