Low-Level API for Events in Canvases

If the application needs to handle key events in its Canvas, it must override the Canvas methods keyPressed, keyReleased, and keyRepeated. When a key is pressed, the keyPressed method is called with the key code. If the key is held down long enough to repeat, the keyRepeated method is called for each repeated keyCode. When the key is released, the keyReleased method is called. Some devices might not support repeating keys, and if not, the keyRepeated method is never called. The application can check the availability of repeat actions by calling the method Canvas.hasRepeatEvents.

MIDP target devices are required to support the ITU-T telephone keys. Key codes are defined in the Canvas class for the digits 0 through 9, *, and #. Although an implementation may provide additional keys, applications relying on these keys may not be portable. For portable applications, the action key mappings described below should be used whenever possible, since other key codes are device-specific.

The Canvas class has methods for handling portable action events (also known as game actions) from the low-level user interface. The API defines a set of action events: UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, and GAME_D. The device maps the action events to suitable key codes on the device; multiple keys may map to each game action. For example, a device with four navigation keys and a SELECT key in the middle could use those keys for mapping the action events, but it may also use the keys on the numeric keypad (such as 2, 4, 5, 6, and 8).

An application should determine the appropriate action for a given key code by calling the method Canvas.getGameAction. If the logic of the application is based on the values returned by this method, the application is portable and runs regardless of the keypad design.

The mapping between keys and the abstract action events does not change during the execution of an application. One of the device-specific key codes mapped to a particular action can be retrieved with the method Canvas.getKeyCode. However, since several keys may be mapped to a single action, comparing key events to these key codes is not recommended and Canvas.getGameAction should be used instead.

The Canvas class has methods that the application can override to handle pointer events. Pointer events are events that are generated from a pointing device such as a stylus. If the application needs to handle pointer events, it must override and implement the methods pointerPressed, pointerReleased, and pointerDragged.

Not all MIDP target devices support pointer events, and therefore the pointer methods might never be called. The application can check whether the pointer and pointer motion events are available by calling Canvas.hasPointerEvents and Canvas.hasPointerMotionEvents