widget.newStepper()

Type Function
Library widget.*
Return value StepperWidget
Revision Release 2024.3703
Keywords widget, stepper, increment, decrement, control
See also StepperWidget

Overview

Creates a StepperWidget object. The stepper consists of a minus and plus button which can be tapped or held down to decrement/increment a value, for example, the music or sound volume setting in a game.

Gotchas

Syntax

widget.newStepper( options )

This function takes a single argument, options, which is a table that accepts the following parameters:

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.

Functions

Properties

Visual Customization

The stepper widget can be visually customized using 5 frames from an image sheet.

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.

Examples

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