Type Function Library widget.* Return value StepperWidget Revision Release 2024.3703 Keywords widget, stepper, increment, decrement, control See also StepperWidget
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.
To conserve texture memory, a StepperWidget object can only be created from an image sheet.
StepperWidget objects do not support scaling nor changing the width/height via .width or .height.
widget.newStepper( 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 stepper. Default is widget_stepper
.
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.
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.
Number. The initial value at which the stepper begins. Default is 0
.
Number. The minimum value that the stepper can reach. Default is 0
.
Number. The maximum value that the stepper can reach. Default is no limit.
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
.
Number. The number of increments at which the increment speed changes. Default is 5
. The increment speed can be controlled via timerIncrementSpeed
.
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
.
The stepper widget can be visually customized using 5 frames from an image sheet.
ImageSheet. The image sheet object for the stepper.
Number. The default frame used when both the minus and plus sides are active.
Number. The frame used when the stepper reaches its minimum value, indicating no apparent result from a tap on the minus side.
Number. The frame used when the stepper reaches its maximum value, indicating no apparent result from a tap on the plus side.
Number. The frame used to indicate that a tap/hold occurred on the minus side.
Number. The frame used to indicate that a tap/hold occurred on the plus side.
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 } )
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 } )