animation.cancel()

Type Function
Return value none
Revision Release 2024.3703
Keywords animation, tween, timeline, interpolation, cancel
See also Animation — Tweens and Timelines (guide)
Tween
Timeline

Overview

The animation.cancel() function will cancel the following, depending on the passed parameter:

Important

Calls to this method which target specific child tweens within a Timeline are ignored. Timeline tweens are controlled/owned by the parent timeline, so you should cancel the timeline itself via this method or object:cancel().

Syntax

animation.cancel()
animation.cancel( tweenObject )
animation.cancel( displayObject )
animation.cancel( tagName )
animation.cancel( timelineObject )
tweenObject (optional)

Tween. The specific Tween to cancel.

displayObject (optional)

DisplayObject. The display object upon which all associated tweens will be cancelled.

tagName (optional)

String. The tag name; all tweens with this tag will be cancelled.

timelineObject (optional)

Timeline. The specific Timeline to cancel.

Examples

All Tweens/Timelines
local object1 = display.newRect( 50, 50, 100, 100 )
local object2 = display.newRect( 50, 150, 100, 100 )

local tween1 = animation.to( object1, { y=300 }, { time=400 } )
local tween2 = animation.to( object2, { y=400 }, { time=200 } )

-- Sometime later, cancel all tweens and timelines
animation.cancel()
Specific Tween
local object1 = display.newRect( 50, 50, 100, 100 )
local object2 = display.newRect( 50, 150, 100, 100 )

local tween1 = animation.to( object1, { y=300 }, { time=400 } )
local tween2 = animation.to( object2, { y=400 }, { time=200 } )

-- Sometime later, cancel a specific tween
animation.cancel( tween1 )
Display Object Tweens
local object1 = display.newRect( 50, 50, 100, 100 )

local tween1 = animation.to( object1, { y=300 }, { time=2000 } )
local tween2 = animation.to( object1, { rotation=90 }, { time=1000, delay=1000 } )

-- Sometime later, cancel all tweens on the object
animation.cancel( object1 )
Tagged Tweens
local object1 = display.newRect( 50, 50, 100, 100 )
local object2 = display.newRect( 50, 150, 100, 100 )

local tween1 = animation.to( object1, { y=300 }, { time=400, tag="tweenTag" } )
local tween2 = animation.to( object2, { y=400 }, { time=200, tag="tweenTag" } )

-- Sometime later, cancel all tweens with the tag "tweenTag"
animation.cancel( "tweenTag" )