Transitions

This guide discusses how to use the Corona transition library to move, rotate, fade, or scale a display object/group over a specific period of time.

Library Features

Basic Transitions

A basic transition can be initiated using one of these functions:

The first argument in either function, target, is the display object or group that you wish to transition. The second argument, params, is a table of key-value pairs. Inside this table, specify the appropriate control parameters for the transition:

Control Description
time Specifies the duration of the transition in milliseconds.
delay Specifies the delay, in milliseconds, before the transition begins. Default is 0 (none).
delta Specifies whether the final object properties are specific values or changes in value. The default is nil meaning false.
iterations The number of times (integer) that the transition should repeat. 0 or -1 will cause the transition to repeat forever.
tag String value which allows you to categorize transitions and control them together. See Controlling Transitions.
transition Specifies the easing function used for the transition. See Easing Functions.

To affect the final object properties, the following methods are available. In the params table, specify each appropriate property along with its final value.

Method Properties (key) Description
move x, y Moves an object from its current x/y coordinate to another.
rotate rotation Rotates an object from its current angle to another.
fade alpha Fades an object from its current alpha value to another.
scale xScale, yScale Scales an object to a specific x ratio or y ratio.
font size size Applies only if the target is a TextObject. This will transition the font size of the text object.
resize width, height Resizes an object from its current width/height to another.
distort x1, y1, x2, y2, x3, y3, x4, y4 Applies only if the target is a RectPath, applicable to a ShapeObject. These properties control the quadrilateral distortion of the target.
fill effect (various) Applicable only if the target is a fill.effect applied to a ShapeObject. In this case, the property (key) indicates an effect property associated with the specific filter effect, for example ShapeObject.fill.effect.intensity. See the Effects Guide for which filter parameters apply to each filter.

Note that transitions support the full range of transition events listed below. These flags will trigger the specified listener function when that event occurs on the transition. When invoked, the object reference is passed to the listener function as the sole parameter. Please see Transition Events for details.

Event Description
onStart Listener function called when the transition begins.
onComplete Listener function called after the transition completes.
onPause Listener function called when an active transition is paused.
onResume Listener function called when a paused transition is resumed.
onCancel Listener function called when an active transition is cancelled.
onRepeat Listener function called when an active transition has completed an iteration cycle.

Examples

  1. The following transition moves an object from its current position to the y coordinate of 100 over the timespan of 2000 milliseconds. In this case, the y value is the specific value in content area coordinates.
transition.to( myObject, { time=2000, y=100 } )
  1. To apply a property value as a change relative to the object's starting value, simply set the delta property to true. In the following example, the object will move down 100 pixels from its starting y position. Note that the same principle can be applied to any property change.
transition.to( myObject, { time=2000, y=100, delta=true } )
  1. The next transition moves an object from its current position to the y coordinate of 400 over the timespan of 2000 milliseconds. It repeats 4 times using the iterations parameter and an elastic interpolation effect is applied with the transition parameter.
transition.to( myObject, { time=2000, y=400, iterations=4, transition=easing.outElastic } )
  1. Transitions can also be combined using just one transition call. For example, if you want to rotate an object 45 degrees, scale it vertically to 200%, and fade its alpha to 50%, you do not need to make three separate transition calls. Instead, just declare all three property changes in the params table:
transition.to( myObject, { time=2000, rotation=45, yScale=2, alpha=0.5 } )
Important

Some objects will not behave as you may expect during or following a transition. For instance, many widgets do not support scaling or post-declaration resizing, so you should not attempt to perform an xScale, yScale, width, or height transition upon them. Another example is physics bodies: if you scale or resize the physics object using a transition, the actual physics body will not scale along with that transition.

If in doubt, check the documentation associated with the object or library to confirm that it doesn't have any property restrictions related to transitions.

Controlling Transitions

Transitions can be paused, resumed, or cancelled before completion. The parameter passed to the control function determines the scope of the action.

Pause

Transitions can be paused with the transition.pause() and transition.pauseAll() functions. These only affect transitions that are running.

With the transition.pause() function, you can control which specific transitions to pause by what parameter you use.

Parameter Scope
(none) Pauses all running transitions.
transition reference Pauses a specific running transition.
object reference Pauses all running transitions on a specific object.
tag name (string) Pauses all running transitions sharing the same tag name.

Resume

Transitions can be resumed with the transition.resume() and transition.resumeAll() functions. These only affect transitions that are paused.

With the transition.resume() function, you can control which specific transitions to resume by what parameter you use.

Parameter Scope
(none) Resumes all paused transitions.
transition reference Resumes a specific paused transition.
object reference Resumes all paused transitions on a specific object.
tag name (string) Resumes all paused transitions sharing the same tag name.

Cancel

Transitions can be cancelled with the transition.cancel() and transition.cancelAll() functions. Note that the transition(s) will stop in place — they will not revert to their beginning state or skip to the end state. These functions only effects transitions that are currently running or paused.

With the transition.cancel() function, you can control which specific transitions to cancel by what parameter you use.

Parameter Scope
(none) Cancels all running/paused transitions.
transition reference Cancels a specific running/paused transition.
object reference Cancels all running/paused transitions on a specific object.
tag name (string) Cancels all running/paused transitions sharing the same tag name.
Important

If you accidentally pass a reference to a display object into transition.pause(), transition.resume() or transition.cancel() after the display object has already been removed, then the argument will be nil. This is the same passing no argument into the function, which will result in all transitions being paused, resumed or cancelled (depending on the function).

In order to avoid this default behaviour, you can include the following line of code in your project after requiring the transition library:

transition.ignoreEmptyReference = true

If set transition.ignoreEmptyReference to true (default is false), then passing nil or no argument into these three functions will be ignored and nothing will happen. You can always use transition.pauseAll(), transition.resumeAll() and transition.cancelAll() to control all transitions.

Easing Functions

By default, transitions occur on a consistent, linear rate of change from the starting value to the ending value. However, you may wish to use an easing effect to achieve a different result, for example, to make an object move quickly at the start and gradually slow down as it reaches its destination. This behavior can be achieved using the easing library functions in conjunction with the transition call.

To set an easing effect on a transition, simply provide the transition key in the params table with a value equal to one of the easing library functions:

--transition the object out with quadratic interpolation
transition.to( myObject, { time=2000, y=100, transition=easing.outQuad } )

--transition the object in, then back out, with exponential interpolation
transition.to( myObject, { time=2000, y=100, transition=easing.inOutExpo } )

Transition Events

Corona supports a full range of transition events, including:

To trigger an event response from a transition, add the desired event key(s) to the params table along with the listener function(s) which should be called:

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

local function completeListener ( obj )
    --when this function is invoked, the object reference is passed instead of an 'event' table
    print( "Transition completed on object: " .. tostring( obj ) )
end

transition.to( myObject, { time=2000, alpha=0, onComplete=completeListener } )
Important

If you remove or clear a transitioning object from memory, and the transition has an onComplete event, the listener will still be invoked even though the object no longer exists on the screen. Other transition events may even crash the program if the object has been prematurely removed. Thus, it's good practice to cancel all transitions on a specific object before removing it. Passing the object reference to transition.cancel() is useful for this purpose.

In a wider scope, you may consider using transition.cancel() with no params to cancel all transitions before exiting a Composer scene or clearing a module.

Convenience Functions

Corona provides several convenience functions which let you perform simple transitions with recognizable names. The following function accept the object/group to transition as the first parameter and, like standard transitions, a params table containing key-values appropriate to the transition type.

Function Description
transition.blink() Repeatedly oscillates the alpha value of an object in and out over the timespan.
transition.dissolve() Performs a dissolve transition between two display objects.
transition.fadeIn() Fades an object to alpha of 1.0 over the specified time.
transition.fadeOut() Fades an object to alpha of 0.0 over the specified time.
transition.moveBy() Moves an object by the specified x and y coordinate amount over a specified time.
transition.moveTo() Moves an object to the specified x and y coordinates over a specified time.
transition.scaleBy() Scales an object by the specified xScale and yScale amounts over a specified time.
transition.scaleTo() Scales an object to the specified xScale and yScale amounts over a specified time.