This guide explains the difference between tap, touch, and multitouch and how to handle the events associated with each method.
If you're new to Corona and haven't yet explored basic screen interactivity and events, please begin by reading the Basic Interactivity and Event Detection guide.
Tap events are the most basic form of screen interactivity. Essentially, a tap is represented by the user touching the screen and lifting off at the same approximate point. The tap event is considered successful only if the user touches and releases at that point.
In Corona, you can listen for tap events by registering a
"tap" event listener on most common display objects:
local function myTapListener( event ) --code executed when the button is tapped print( "object tapped = "..tostring(event.target) ) --'event.target' is the tapped object return true end local myButton = display.newRect( 100, 100, 200, 50 ) myButton:addEventListener( "tap", myTapListener ) --add a "tap" listener to the object
event properties returned from a tap include:
event.target — reference to the object that was tapped.
event.name — string value of
event.numTaps — the number of taps on the screen. The default delay between what is considered the next tap in sequence is
0, but this time can be adjusted with the system.setTapDelay() function.
event.y — the x and y position of the tap, in content coordinates.
Unlike touch events, the tap event does not include a
phase property — the tap is a singular action involving both a touch and release, so you don't need to handle the phase in any special manner.
Touch events provide for a much greater level of screen interactivity. Using touch events, you can detect when the user first touches the screen and when the touch is lifted off the screen. You can also track the motion of the touch as it moves around the screen. To accomplish this, Corona offers the
event.phase property in one of four states:
"began"— indicates that a touch has started on the screen.
"moved"— indicates that a touch has moved on the screen.
"ended"— indicates that a touch has been lifted from the screen.
"cancelled"— indicates that the system cancelled tracking of the touch (not to be confused with
In Corona, you can listen for touch events by registering a
"touch" event listener on most common display objects:
local function myTouchListener( event ) if ( event.phase == "began" ) then --code executed when the button is touched print( "object touched = "..tostring(event.target) ) --'event.target' is the touched object elseif ( event.phase == "moved" ) then --code executed when the touch is moved over the object print( "touch location in content coordinates = "..event.x..","..event.y ) elseif ( event.phase == "ended" ) then --code executed when the touch lifts off the object print( "touch ended on object "..tostring(event.target) ) end return true --prevents touch propagation to underlying objects end local myButton = display.newRect( 100, 100, 200, 50 ) myButton:addEventListener( "touch", myTouchListener ) --add a "touch" listener to the object
The event properties returned from a touch include:
event.id — a unique identifier that distinguishes between multiple touches across different touch events. See Multitouch below for more details.
event.target — reference to the object that was touched.
event.name — string value of
event.phase — the phase of the touch as described above.
event.time — the time in milliseconds since the start of the application, accessible from within the touch listener function.
event.y — the x and y position of the touch, in content coordinates.
event.yStart — the x and y position of the touch from the
"began" phase of the touch sequence, in content coordinates.
Enabling multitouch in an app lets you detect and handle multiple user touches on the screen at the same time.
Because multitouch is disabled by default, you must first enable it via the system.activate() function. Note that multitouch functionality is only available if you test on an actual device — it will not function in the Corona Simulator.
system.activate( "multitouch" )
With multitouch enabled, listen for touch events by registering a
"touch" event listener on the object(s), exactly as described in Touch Detection above. Then, compare the
event.id property to determine which specific touch event sequence is being returned.
system.activate( "multitouch" ) local myRectangle = display.newRect( 0, 0, 320, 480 ) local function multitouchListener( event ) print( "Phase: "..event.phase ) print( "Location: "..event.x..","..event.y ) print( "Unique touch ID: "..tostring(event.id) ) print( "----------" ) return true end myRectangle:addEventListener( "touch", multitouchListener )