widget.newSegmentedControl()

类型 函数
库 widget.*
返回值 SegmentedControlWidget
修订 版本 2024.3703
关键词 widget, segment, segmentedControl, control
另请参阅 SegmentedControlWidget

概述

创建一个 SegmentedControlWidget 对象。

注意事项

语法

widget.newSegmentedControl( options )

此函数接受一个参数 options，它是一个包含以下参数的表：

id (可选)

字符串。要分配给分段控件的可选标识。默认为 widget_segmentedControl。

x, y (可选)

数字。控件x 和 y 中心点的坐标。如果定义了 left 和 top 值，则这些值将被覆盖。

left, top (可选)

数字。将在其中创建控件的左侧和顶部位置。如果指定，这些值将覆盖 x 和 y 参数。

segmentWidth (可选)

数字。每个段的宽度（以像素为单位）（所有段的宽度必须相等）。默认为 50。

segments (必填)

表。逗号分隔字符串的表，定义了段总数和每个段上显示的标签。例如

segments = { "Item 1", "Item 2", "Item 3", "Item 4" }
defaultSegment (可选)

数字。初始创建时将处于活动状态的段。默认为第一个段。

onPress (可选)

侦听器。按下某个段时要调用的可选函数。回调函数不需要测试 event.phase，因为它只接受 began。

属性

object.segmentLabel

object.segmentNumber

方法

object:setActiveSegment()

基本视觉选项

labelSize (可选)

数字。段标签的字体大小（以像素为单位）。默认为 12。

labelFont (可选)

字符串。段标签使用的字体。默认为 native.systemFont。

labelColor (可选)

表。包含两个 RGB+A 颜色设置的表，分别用于非活动（default）和活动（over）状态。

labelColor = { default={ 1, 1, 1 }, over={ 0, 0, 0, 0.5 } }
emboss (可选)

布尔值。如果设置为 true，则按钮标签将显示为浮雕（嵌入效果）。

labelXOffset, labelYOffset (可选)

数字。段标签的可选 x 和 y 偏移量。例如，labelYOffset = -8 会将标签从默认位置向上移动 8 个像素。

视觉定制

可以使用 图像表单 中的 7 个帧来自定义分段控件的视觉效果。如下例所示，可以使用其中 6 个帧为每个段组装非活动和活动状态。非活动帧由左端盖（红色）、中间跨度（绿色）和右端盖（黄色）组成。活动帧由左端盖（橙色）、中间跨度（蓝色）和右端盖（紫色）组成。

根据段的宽度，左端盖和右端盖保持图像表单中规定的尺寸，而中间帧（绿色或蓝色）将拉伸以填充每个段的剩余宽度。

可选地，分段控件接受每个段之间的分隔线，在本例中显示为深蓝色条。如果已定义，分隔线将覆盖其他帧，并均匀分布在分段控件的整个跨度上。如果您不希望显示分隔线，只需在控件声明中省略三个关联的属性即可。

 → 
sheet (必填)

ImageSheet。分段控件的 图像表单 对象。

segmentFrameWidth, segmentFrameHeight (必填)

数字。主段帧（端盖和中间跨度）的宽度/高度。所有这些帧应具有相同的宽度和高度。

leftSegmentFrame, leftSegmentSelectedFrame (必填)

数字。左端盖的非活动和活动帧。

middleSegmentFrame, middleSegmentSelectedFrame (必填)

数字。中间跨度的非活动和活动帧。

rightSegmentFrame, rightSegmentSelectedFrame (必填)

数字。右端盖的非活动和活动帧。

dividerFrame (可选)

数字。分隔线帧的帧索引。如果您不希望显示分隔线，请省略此项。

dividerFrameWidth, dividerFrameHeight (可选)

数字。分隔线帧的宽度/高度。如果定义了 dividerFrame，则这些是必需的。

示例

默认
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
    }
)