widget.newSpinner()

Type Function
Library widget.*
Return value SpinnerWidget
Revision Release 2024.3703
Keywords widget, spinner, activity, indicator
See also SpinnerWidget

Overview

Creates a SpinnerWidget object.

Gotchas

Syntax

widget.newSpinner( 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 spinner. Default is widget_spinner.

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. If you are using the default theme, these values are set automatically.

Methods

object:start()

object:stop()

Single Frame Construction

A basic spinner can be built using one frame from an image sheet. The image will rotate by a specified delta angle on each increment of the specified time.

sheet (required)

ImageSheet. The image sheet object for the spinner.

startFrame (required)

Number. The starting frame index of the spinner animation sequence (the index of the sole frame from the sheet).

deltaAngle (optional)

Number. The delta angle by which the spinner rotates per time increment (see incrementEvery below). For example, if you specify 30, the spinner will rotate 30 degrees per increment.

incrementEvery (optional)

Number. The delay for each rotation iteration of the spinner, in milliseconds.

Multi-Frame Construction

An animated spinner can be built using multiple frames from an image sheet. This spinner type will loop through the frame sequence over a specified time.

sheet (required)

ImageSheet. The image sheet object for the spinner.

startFrame (required)

Number. The starting frame index of the spinner animation sequence (the first frame in its animation sequence).

count (required)

Number. The total frame count of the spinner animation sequence.

time (optional)

Number. The time for one complete loop of the spinner animation, in milliseconds. Default is 1000.

Examples

Single Frame
local widget = require( "widget" )

-- Image sheet options and declaration
-- For testing, you may copy/save the image under "Single Frame Construction" above
local options = {
    width = 128,
    height = 128,
    numFrames = 1,
    sheetContentWidth = 128,
    sheetContentHeight = 128
}
local spinnerSingleSheet = graphics.newImageSheet( "widget-spinner-single.png", options )

-- Create the widget
local spinner = widget.newSpinner(
    {
        width = 128,
        height = 128,
        sheet = spinnerSingleSheet,
        startFrame = 1,
        deltaAngle = 10,
        incrementEvery = 20
    }
)

spinner:start()
Multi-Frame
local widget = require( "widget" )

-- Image sheet options and declaration
-- For testing, you may copy/save the image under "Multi-Frame Construction" above
local options = {
    width = 128,
    height = 128,
    numFrames = 4,
    sheetContentWidth = 512,
    sheetContentHeight = 128
}
local spinnerMultiSheet = graphics.newImageSheet( "widget-spinner-multi.png", options )

-- Create the widget
local spinner = widget.newSpinner(
    {
        width = 128,
        height = 128,
        sheet = spinnerMultiSheet,
        startFrame = 1,
        count = 4,
        time = 800
    }
)

spinner:start()