Capturing soft key input
Modified
10 October 2011
Requirements
Prerequisite knowledge
Familiarity with ActionScript 3.
Additional Requirements
- A mobile device supporting Android 2.2 or higher.
- Android SDK
User level
Intermediate
Required products
- Flash Builder (Download trial)
- Flash Professional CS5 (Download trial)
Sample files
In Adobe AIR applications, an event is dispatched when a specific activity happens. For example, Adobe AIR generates a keyboard event whenever you press or release a key on the keyboard. Each key is identified by a unique key code. Adobe AIR extends this support to the soft keys used on mobile devices, such as Back, Menu, and Search.
In this article, you will learn about handling soft key events.
Handling soft key events
When you press any of the soft keys, the NativeApplication object dispatches the keyboard event, KeyboardEvent.KEY_DOWN. Similarly, when you release the key, the NativeApplication object dispatches the event, KeyboardEvent.KEY_UP. You can handle these events and provide the appropriate behavior for these keys when you develop an application.
For example, consider a mobile application in which you have a collection of records. When you press the Back key, you want to display the previous record in the collection. By default, when you press the Back key on an Android device, an Adobe AIR application moves to the background and the phone reactivates the previously active application. Handling the keyboard events that are generated from pressing the Back key allows you to prevent this default behavior and program the application to behave in the way you want.
Note: You must handle the keyDown event when you want to cancel the default behavior of the BACK key. The keyUp event is too late in the event chain.
You can listen for keyboard events on the NativeApplication object. Use the following statement to add a listener for the keyDown event:
NativeApplication.nativeApplication.addEventListener(KeyboardEvent.KEY_DOWN,checkKeypress);
In the following example, the checkKeypress function illustrates how you can test the dispatched KeyboardEvent object to determine which key was pressed. The function uses a switch statement to provide specific behavior for the soft key that is pressed. Other key presses are ignored.
public function CheckKeypress(event:KeyboardEvent):void
{
switch (event.keyCode)
{
case Keyboard.BACK:
event.preventDefault();
trace("Back key is pressed.");
break;
case Keyboard.MENU:
trace("Menu key is pressed.");
break;
case Keyboard.SEARCH:
trace("Search key is pressed.");
break;
}
}
When designing your application, it is very important to handle the soft keys in a way that is consistent with the native applications on the platform. Otherwise, users may become frustrated when your application doesn't respond in the way they expect. For example, on the Android platform, the Back key is used to return to a previous view of the application until you reach the initial view. From the initial view, another press of the Back key deactivates the current application and reactivates the previous application or the phone Home screen. In an Adobe AIR application, you must keep track of the application state in order to emulate this native behavior. If you do nothing, the Back key will deactivate your application, no matter what state or view it is in.
The Home soft key
A keyboard event is not dispatched when the Home key is pressed. Your application is deactivated and this cannot be prevented. However, the NativeApplication object does dispatch a deactivate event. In the deactivate event handler, you should take the following actions to save battery power and to prepare for possible termination:
- Save application state
- Remove event listeners from the Accelerometer and Geolocation objects
- Stop audio playback
- Throttle the application frame rate
Note: AIR automatically throttles the frame rate of background applications to four frames-per-second. You can save even more battery power by setting the frame rate to .01, if your application does not have any persistent network connections.
To restore an application, you can use either the activate event or the invoke event. An activate event is dispatched when your application is brought back to the foreground, but not when your app is launched initially. An invoke event is dispatched when your application is brought to the foreground and also when it is launched initially.
Where to go from here
In this article, you learned about handling soft key events. For more information, refer to Basics of handlingevents in the online documentation.
