Events are the foundation of interactive applications in Corona. They're used to trigger responses in your app like a tap on the screen, detection of a specific system event, completion of a timer, collision of two physical bodies, etc. Events are detected using the object:addEventListener() method which directs Corona to track (listen for) the associated event within a listener function. See the Registering Events section for details.
Runtime events are dispatched to the global Runtime listener. These events are not directed at any particular object; rather, they are broadcast to all interested listeners. Common Runtime events include the following:
enterFrame events (documentation) occur at the
lateUpdate events (documentation) occur at the
enterFrame event and right before the rendering process.
system events (documentation) are dispatched when certain external events occur, such as when the device suspends or exits the application.
resize events (documentation) occur when the width or height of the app's view has been changed.
orientation events (documentation) occur when the device orientation changes from portrait to landscape or
windowState events (documentation) occur when the application window is sent to background or activated again (Win32 and macOS only).
The following code shows how an app can respond to
local function onSystemEvent( event ) local eventType = event.type if ( eventType == "applicationStart" ) then -- Occurs when the application is launched and all code in "main.lua" is executed elseif ( eventType == "applicationExit" ) then -- Occurs when the user or OS task manager quits the application elseif ( eventType == "applicationSuspend" ) then -- Perform all necessary actions for when the device suspends the application, i.e. during a phone call elseif ( eventType == "applicationResume" ) then -- Perform all necessary actions for when the app resumes from a suspended state elseif ( eventType == "applicationOpen" ) then -- Occurs when the application is asked to open a URL resource (Android and iOS only) end end Runtime:addEventListener( "system", onSystemEvent )
Local events are typically sent to a single listener and are not broadcast to the global Runtime. Common local events include the following:
touch events occur when the user touches the device screen. See the Tap/Touch/Multitouch guide for more information.
timer events occur when a running timer completes its duration.
Listeners can be either functions or table/display objects.
When a function listener is invoked, it is passed a table representing the event:
local myListener = function( event ) print( "Listener called with event of type: " .. event.name ) end Runtime:addEventListener( "touch", myListener ) Runtime:addEventListener( "enterFrame", myListener )
Sometimes a function listener is not convenient because certain variables are not in scope when the listener is invoked. In these situations, table listeners should be used. Table listeners must have an instance method with a name corresponding to the event name:
-- Assumes "myClass" and "myClass:new()" already exist function myClass:enterFrame( event ) print( "enterFrame called at time: " .. event.time ) end function myClass:touch( event ) print( "touch occurred at: " .. event.x .. "," .. event.y ) end local myObject = myClass:new() Runtime:addEventListener( "touch", myObject ) Runtime:addEventListener( "enterFrame", myObject )
As illustrated in each example above, events are dispatched to event listeners which are written as basic functions. An
event argument is always dispatched to the function.
local function myTouchListener( event ) print( "Touch X location" .. event.x ) print( "Touch Y location" .. event.y ) end local myButton = display.newRect( 100, 100, 200, 50 ) myButton:addEventListener( "touch", myTouchListener )
Notice how the
event argument passed to the
myTouchListener function contains both
y properties that represent the point on the screen where the touch occurred. Properties associated with the
event argument are unique to each event type — please refer to the Events API documentation for details.
Events can be registered using the object:addEventListener() method. Just pass the string name of the event type and the name of the event listener function that should handle it.
-- Standard touch listener on an object myButton:addEventListener( "touch", myTouchListener ) -- Runtime "system" event listener Runtime:addEventListener( "system", onSystemEvent )
As shown above, two types of event listeners can be created with the
object:addEventListener() method: listeners attached to display objects and listeners attached to the global Runtime.
When you create a display object and add a local touch event listener to it, you essentially point to a block of code via reference to the function. This code resides in its own memory and it persists after the display object is removed. When that occurs, there's no way to sense future events on the object, so the local event listener is effectively removed for you. You don't need to explicitly remove it.
Runtime event listeners, on the other hand, must be removed when you're finished using them. Otherwise, they'll continue to run because the Runtime event is global. Not only will this cause a memory leak, but if any functions executing in the Runtime attempt to reference object(s) that no longer exist, the program will crash. See Removing Event Listeners below for more information.
Most listeners, with the exception of Runtime listeners like
"enterFrame", will be removed automatically when the associated object is removed, for example when you call object:removeSelf() or display.remove(). However, you may need to explicitly remove an event listener without removing the object.
Removing an event listener is done using the
This function is called in the same exact manner as
object:addEventListener(). For example, if you want to stop listening for touch events on the
myButton object, remove the listener as follows:
myButton:removeEventListener( "touch", myTouchListener )
Both the type and function name are required to remove the associated listener, because it's possible to assign multiple listeners of the same type to a single object. For instance, you could have two (or more) different listener functions assigned to the
"touch" event of the
myButton display object. Therefore, when calling
object:removeEventListener(), you need to specify the type of event you want to stop listening for, as well as the listener function that was previously assigned to that event.