transition.to()

Type Function
Library transition.*
Return value Table
Revision Release 2022.3683
Keywords easing, animation, transition, tween, interpolation
See also Transitions (guide)
easing

Overview

Animates (transitions) a display object using an optional easing algorithm. Use this to move, rotate, fade, or scale an object over a specific period of time.

This function returns a reference corresponding to the transition/animation of the object target.

Please see the Transitions guide for usage information.

Syntax

transition.to( target, params )
target (required)

Table. Any object that behaves like a table, for example display objects.

params (required)

Table. A table that specifies the properties of the transition — see the next section for details.

Parameter Reference

The params table includes the properties of target that should be interpolated.

time (optional)

Number. Specifies the duration of the transition in milliseconds. By default, the duration is 500 milliseconds.

iterations (optional)

Number. Specifies the number of iterations for which the transition will repeat. By default, the iteration value is 1.

tag (optional)

String. Specifies the transition tag. The transition library can pause, resume, or cancel transitions sharing the same tag.

transition (optional)

Function. Specifies the easing interpolation method. Default is linear.

delay (optional)

Number. Specifies the delay, in milliseconds, before the transition begins. Default is 0.

delta (optional)

Boolean. Specifies whether non-control parameters are interpreted as final ending values or as changes in value. The default is false.

onStart (optional)

Listener. Listener function to be called before the transition begins. This function will receive a reference to the associated object as its sole argument.

onComplete (optional)

Listener. Listener function to be called after the transition completes. This function will receive a reference to the associated object as its sole argument.

onPause (optional)

Listener. Listener function to be called when the transition is paused. This function will receive a reference to the associated object as its sole argument.

onResume (optional)

Listener. Listener function to be called when the transition is resumed. This function will receive a reference to the associated object as its sole argument.

onCancel (optional)

Listener. Listener function to be called when the transition is cancelled. This function will receive a reference to the associated object as its sole argument.

onRepeat (optional)

Listener. Listener function to be called when the transition completes an iteration in a repeat cycle. This function will receive a reference to the associated object as its sole argument.

x (optional)

Number. Moves the target from its current x coordinate to another.

y (optional)

Number. Moves the target from its current y coordinate to another.

rotation (optional)

Number. Rotates the target from its current angle to another.

alpha (optional)

Number. Fades the target from its current alpha value to another.

xScale (optional)

Number. Scales the target to a specific x ratio.

yScale (optional)

Number. Scales the target to a specific y ratio.

size (optional)

Number. Applies only if the target is a TextObject created via display.newText(). This will transition the font size of the text object.

width (optional)

Number. Resizes the target from its current width to another.

height (optional)

Number. Resizes the target from its current height to another.

x1, y1, x2, y2, x3, y3, x4, y4 (optional)

Numbers. Applies only if the target is a RectPath, applicable to a ShapeObject. These properties control the quadrilateral distortion of the target.

[filterParameter] (optional)

Number. Applicable only if the target is a fill.effect applied to a ShapeObject. In this case, [filterParameter] indicates an effect property associated with the specific filter effect, for example ShapeObject.fill.effect.intensity. See the Filters, Generators, Composites guide for which filter parameters apply to each filter.

Examples

local square = display.newRect( 0, 0, 100, 100 )

local w,h = display.contentWidth, display.contentHeight

local function listener1( obj )
    print( "Transition 1 completed on object: " .. tostring( obj ) )
end
 
local function listener2( obj )
    print( "Transition 2 completed on object: " .. tostring( obj ) )
end
 
-- (1) move square to bottom right corner; subtract half side-length
transition.to( square, { time=1500, alpha=0, x=(w-50), y=(h-50), onComplete=listener1 } )
 
-- (2) fade square back in after 2.5 seconds
transition.to( square, { time=500, delay=2500, alpha=1.0, onComplete=listener2 } )