widget.newStepper()

id _^(optional)

String. An optional identification to assign to the stepper. Default is widget_stepper.

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 each frame from the image sheet. Set these only if you are using a custom image sheet for the stepper. If you are using the default theme, these values are set automatically.

initialValue _^(optional)

Number. The initial value at which the stepper begins. Default is 0.

minimumValue _^(optional)

Number. The minimum value that the stepper can reach. Default is 0.

maximumValue _^(optional)

Number. The maximum value that the stepper can reach. Default is no limit.

timerIncrementSpeed _^(optional)

Number. The initial speed at which each stepper increment occurs, in milliseconds. Default is 1000. The number of increments at which the speed change occurs can be controlled via changeSpeedAtIncrement.

changeSpeedAtIncrement _^(optional)

Number. The number of increments at which the increment speed changes. Default is 5. The increment speed can be controlled via timerIncrementSpeed.

onPress _^(optional)

Listener. An optional function to be called as soon as a stepper segment is pressed and held. This callback function returns the following event.phase events: increment, decrement, minLimit, and maxLimit.

object:getValue()

object:setValue()

object.value

object.minimumValue

object.maximumValue

sheet _^(required)

ImageSheet. The image sheet object for the stepper.

defaultFrame _^(required)

Number. The default frame used when both the minus and plus sides are active.

noMinusFrame _^(required)

Number. The frame used when the stepper reaches its minimum value, indicating no apparent result from a tap on the minus side.

noPlusFrame _^(required)

Number. The frame used when the stepper reaches its maximum value, indicating no apparent result from a tap on the plus side.

minusActiveFrame _^(required)

Number. The frame used to indicate that a tap/hold occurred on the minus side.

plusActiveFrame _^(required)

Number. The frame used to indicate that a tap/hold occurred on the plus side.

Default

local widget = require( "widget" )

local currentNumber = 0

-- Handle stepper events
local function onStepperPress( event )

    if ( "increment" == event.phase ) then
        currentNumber = currentNumber + 1
    elseif ( "decrement" == event.phase ) then
        currentNumber = currentNumber - 1
    end
    print( currentNumber )
end
        
-- Create the widget
local newStepper = widget.newStepper(
    {
        left = 150,
        top = 200,
        minimumValue = 0,
        maximumValue = 50,
        onPress = onStepperPress
    }
)

Image Sheet

local widget = require( "widget" )

local currentNumber = 0

-- Handle stepper events
local function onStepperPress( event )

    if ( "increment" == event.phase ) then
        currentNumber = currentNumber + 1
    elseif ( "decrement" == event.phase ) then
        currentNumber = currentNumber - 1
    end
    print( currentNumber )
end

-- Image sheet options and declaration
-- For testing, you may copy/save the image under "Visual Customization" above
local options = {
    width = 196,
    height = 100,
    numFrames = 5,
    sheetContentWidth = 980,
    sheetContentHeight = 100
}
local stepperSheet = graphics.newImageSheet( "widget-stepper.png", options )

-- Create the widget
local newStepper = widget.newStepper(
    {
        width = 196,
        height = 100,
        sheet = stepperSheet,
        defaultFrame = 1,
        noMinusFrame = 2,
        noPlusFrame = 3,
        minusActiveFrame = 4,
        plusActiveFrame = 5,
        onPress = onStepperPress
    }
)