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
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
The following code shows how an app can respond to system events:
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:
tap and touch events occur when the user touches the device screen. See the Tap/Touch/Multitouch guide for more information.
collision events occur when two physics objects collide. See the Collision Detection guide for more information.
timer events occur when a running timer completes its duration.
audio events can be dispatched when a audio file finishes playing. See the Audio Usage/Functions guide for details.
Local events vary in usage and are discussed further in their
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 x and 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.