Low-Level Event Handling
The low-level UI provides a lot of event-handling options. Commands can be added to a Canvas in order to map soft-keys (physical keys on the keypad that map to labels on the display) just like high-level UI components such as List and Form. However, Canvas also allows for capturing raw key-press events for most of the keys available on the device. The Canvas APIs for monitoring key press activity are as follows:

Event	Description
keyPressed()	This event is called when a physical key on the keypad is pressed.
keyReleased()	This event is called when a pressed key is released.
keyRepeated()	This event is called when a key is held down. This event may not be supported on all platforms. Support of this method can be verified with a call to hasRepeatEvents().

In order to monitor key events, a subclass of Canvas must override one of these methods. An int code corresponding to the key to which the event pertains is passed as a parameter. It is important to understand that key codes are likely to change between platforms, making key event handling another sensitive area of low-level UI portability. For example, on device A, pressing "2" on the keypad may come through as key code 25 but on device B the same key might come through as key code 12. Fortunately, there are tools provided by MIDP to assist in normalizing key press events.

Key Handling Across Devices
Given that key codes can vary across devices, MIDP provides key mappings so that device implementers can map the raw key events into known constant values. The simplest form of this is the numeric key mappings in the Canvas class. There are 10 constant values corresponding to a 10-digit numeric keypad, plus two more for the "*" and "#" keys. So if an application needs to detect when the "6" key is pressed, an application can do something like the following:

public void keyPressed(int code)
{
     if (code == KEY_NUM6)
     {
       System.out.println("Key 6 Pressed!");
     }
}

The catch here is that if a device supports more than a 10-digit keypad, such as an alphanumeric keypad, MIDP does not provide constants to map all the keys. If an application needs to monitor an extended key code range, device-specific key handling may be needed.

In addition to the data-related keys, MIDP provides mapping support for some of the more standard control keys, such as up, down, left, right, and so forth. The method Canvas.getGameAction() can be used within one of the key-handling events to translate a raw key code to one of the following constant values defined in the Canvas class: UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, GAME_D. In some cases, the mapping will work rather well. Many devices have some type of scrolling behavior that maps to the up, down, left and right keys. However, mappings for the FIRE key or the generic GAME_B key may translate in a way that is less than optimal for a particular application.

The following code shows a keyPressed() event translating the FIRE and GAME_B keys, which, for the J2ME Wireless Toolkit, are mapped to the "select" key in the middle of the jog dial and the "3" key, respectively. The following table shows how the game key constant, the actual key (in the wireless toolkit emulator), and the raw key code relate to one another for these two key mappings

Game Constant	Physical Key (J2ME Wireless Toolkit)	Key code value
FIRE	"select" key	-5
GAME_B	"3" key	51

Below is an example showing how the getGameAction() method can be used to make decisions in key-handling events.

public void keyPressed(int code)
{
     int action = getGameAction(code);
     switch (action)
     {
          case FIRE:
          {
               System.out.println("FIRE Pressed!");
               break;
          }
          case GAME_B:
          {
               System.out.println("GAME_B Pressed!");
               break;
          }
     }
}

While the low-level APIs can be challenging to implement, they provide a way for developers to address portability issues that would difficult or impossible otherwise. With some thought and attention to detail, the low-level APIs can be used to create a custom user interface with a unique look and feel catering to a specific application's need. This flexibility does not need to come at the expense of portability either. By making use of font metrics, Canvas screen size methods and key mappings, MIDP applications can take advantage of the low-level APIs while remaining very portable across devices.