Setting up Android hardware keys with Corona SDK

Supporting the Android hardware keys is essential for a good user experience. If you don’t support them in your app, you are almost guaranteed to get angry users——and bad reviews.


Unlike the iPhone that only has one “Home” key, which can do many tasks and is completely handled by the operating system, Android devices have 4 different hardware buttons used for navigating the screens: Home, Back, Menu, and Search. Note that although it’s becoming more and more common to see these buttons as icons on a touchscreen, for the sake of simplicity we will still refer to them as “hardware keys.” The new Android release, Ice Cream Sandwich, changes this, as the hardware buttons will officially become virtual keys.
We’ll assign the following functionality to each key:

  • Home key – Leave the app and go back to the home screen. Luckily, we don’t really have to deal with this one since the operating system already takes care of it.
  • Back button – Return to the previous page in the app.
  • Menu button – Show our app menu.
  • Search button – We will not do much with it in this tutorial as it goes for searching, but we will handle the search button press to return a message.

Corona also lets you capture the volume up/down or the D-Pad “up,” “down,” “left,” “right” and “center” buttons available on some Android devices in a similar way. You can find more information at Ansca’s Android key events documentation here.

Lets see how to do this with Corona SDK.

I created a little demo app that captures the Menu, Back, and Search events, where you can navigate between 5 scenes (menu, scene1, scene2, scene2.1 and scene3).

The full code is pretty long, but mostly because each scene is inside a storyboard template. So, let’s look at the part of the code where we handle the button events:

local function onKeyEvent( event )
    local keyname = event.keyName;
    if (event.phase == "up" and (event.keyName=="back" or event.keyName=="menu")) then
            if keyname == "menu" then
            	goToMenuScreen()
            elseif keyname == "back" then
            	goBack();
            elseif keyname == "search" then
            	performSearch();
            end
	end
    return true;
end
 --add the runtime event listener
if system.getInfo( "platformName" ) == "Android" then  Runtime:addEventListener( "key", onKeyEvent ) end

Dissecting the code, “event.phase” is the state of the key (up or down), while “event.keyName” is the name of the key (supported keys are: "back," "menu," "search," "volumeUp," "volumeDown" and D-Pad’s "up," "down," "left," "right").

Download the full code:
AndroidKeys

Please let me know what you think in the comments below!

Comments

  1. I like the helpful info you provide on your articles. I will bookmark your blog and take a look at again here frequently. I am reasonably certain I will learn plenty of new stuff right right here! Best of luck for the following!

  2. Thanks this is the info on android keys I was looking for! By the way, I believe the first comment is spam.

  3. new to corona says:

    Great helpful tutorials , keep it up. Will bookmark

Speak Your Mind

*