This quick tip tutorial will teach you how to respond to key application lifecycle events like suspension, termination, and resumption. Read on to learn more!

This brief tutorial will explain how to help iOS users put your Corona SDK apps into the OS background. It will also demonstrate how to test sending an application into the background from the Corona SDK simulator.

Let's get a basic project set up. Put this in your main.lua file.

----- main.lua -----

-- hide the status bar
display.setStatusBar( display.HiddenStatusBar )

-- setup a solid background
local background = display.newRect(0, 0, display.contentWidth, display.contentHeight)
background:setFillColor(191, 69, 66)

We will use a simple config.lua file.

 
application = {
	content = {
		width = 320,
		height = 480, 
		scale = "letterBox",
		fps = 30,
	}
}

Now that we have a basic project set up, let's talk about how iOS works with the Corona SDK. By default, the Corona SDK does not allow applications to be put into the background. Rather, the standard behaviour is to quit the application entirely. When a user resumes a paused corona app, the app will completely restart unless we change the default settings. Open your build.settings file (If it doesn't exist yet, create it). Add this line:

UIApplicationExitsOnSuspend = false,

Mine now looks something like this now:

settings =
{
    orientation =
    {
        default = "portait",
        supported =
        {
            "portrait"
        }
    },
    iphone = {
        plist = {
            UIApplicationExitsOnSuspend = false,        
        },
    }
}

Now, when a user resumes the application, it will return to the point at which it left off. This can sometimes break things in the code. Timers can get off track and animations can freeze up; so, we need a way to manage the application when it is running in the background. Fortunately we have access to the "applicationSuspend" event. iOS will tell CoronaSDK when the app is suspended. In turn, the Corona SDK will call the "applicationSuspend" event. Let's try this with our demo app.

-- create a function to handle all of the system events
local onSystem = function( event )
	if event.type == "applicationSuspend" then
		print("backgrounded")
	end
end

-- setup a system event listener
Runtime:addEventListener( "system", onSystem )

Here we create a function to handle system events. There are several sytem events, but we are only going to worry about "applicationSuspend" for now. So, if the event that is passed is "applicationSuspend", then we will print out a nice message to the terminal.

Now we need to add the function onSystem() as a listener for all "system" events. Remember to call Runtime:removeEventListener( "system", onSystem ) in your apps if you are cleaning up a scene. Otherwise it will keep waiting for "system" events.

Now let's try it. Load it in the simulator. To test application backgrounding in the simulator, go to Hardware->Suspend in the menu. You can also use the shortcut Command+Down Arrow.

Repeat the process to resume the app. If everything worked correctly, the message "backgrounded" should show up in the terminal.

There are other system events that are useful, too. On top of the "applicationSuspend" events, we also have access to
"applicationStart", "applicationExit", and "applicationResume". As you can probably guess, these fire when the application starts for the first time, exits completely, and resumes after being supsended, respectively.

These events are just as simple to manage as the first. A basic example of all events looks like this (see if you can get them all to fire in the simulator):

-- create a function to handle all of the system events
local onSystem = function( event )
	if event.type == "applicationStart" then
		print("start")
	elseif event.type == "applicationExit" then
		print("exit")
	elseif event.type == "applicationSuspend" then
		print("suspend")
	elseif event.type == "applicationResume" then
		print("resume")
	end
end

-- setup a system event listener
Runtime:addEventListener( "system", onSystem )

Now you should have a good idea of how to handle application suspending in the Corona SDK.

Here is the final code:

----- main.lua -----

-- hide the status bar
display.setStatusBar( display.HiddenStatusBar )

-- setup a solid background
local background = display.newRect(0, 0, display.contentWidth, display.contentHeight)
background:setFillColor(191, 69, 66) 

-- create a function to handle all of the system events
local onSystem = function( event )
	if event.type == "applicationStart" then
		print("start")
	elseif event.type == "applicationExit" then
		print("exit")
	elseif event.type == "applicationSuspend" then
		print("suspend")
	elseif event.type == "applicationResume" then
		print("resume")
	end
end

-- setup a system event listener
Runtime:addEventListener( "system", onSystem )