net.rim.device.api.system
Interface KeyListener

All Superinterfaces:

KeypadListener

All Known Implementing Classes:

MediaKeyListener, TextSpinBoxField

public interface KeyListener
extends KeypadListener

The listener interface for receiving keyboard events.

In order to support different locales in the future, apps should use the keyChar notification to determine which characters a user has pressed. Although in English there is a high correspondence between keys and characters, in other languages there might not be. For example, using hirgana or katakana maps, it would often take two keys to generate one character.

Example

 public class KeyListenerImplementation implements KeyListener
 {    
     // Implement methods in the KeyListener interface for handling keyboard events:
     public boolean keyChar( char key, int status, int time ) 
     {
         if ( key == Characters.ENTER ) 
         {
             //...
         }
         
         return false;
     }
     
     public boolean keyDown(int keycode, int time) 
     {
         return false;
     }
 
     public boolean keyRepeat(int keycode, int time) 
     {
         return false;
     }
     
     public boolean keyStatus(int keycode, int time) 
     {
         return false;
     }
     
     public boolean keyUp(int keycode, int time) 
     {
         return false;
     }    
 }

 class KeyListenerDemo extends MainScreen
 {
     public KeyListenerDemo()
     {
         //This adds our custom KeyListener, KeyListenerImplementation, to this class
         addKeyListener(new KeyListenerImplementation());
     }
 }
 

Field Summary

Fields inherited from interface net.rim.device.api.system.KeypadListener

STATUS_ALT, STATUS_ALT_LOCK, STATUS_CAPS_LOCK, STATUS_FOUR_WAY, STATUS_KEY_HELD_WHILE_ROLLING, STATUS_NOT_FROM_KEYPAD, STATUS_SHIFT, STATUS_SHIFT_LEFT, STATUS_SHIFT_RIGHT, STATUS_TRACKWHEEL

Method Summary
boolean	keyChar(char key, int status, int time) Invoked when a sequence of zero or more keyDowns generates a character.
boolean	keyDown(int keycode, int time) Invoked when a key has been pressed.
boolean	keyRepeat(int keycode, int time) Invoked when a key has been repeated.
boolean	keyStatus(int keycode, int time) Invoked when the ALT or SHIFT status has changed.
boolean	keyUp(int keycode, int time) Invoked when a key has been released.

Method Detail

keyChar

boolean keyChar(char key,
                int status,
                int time)

Invoked when a sequence of zero or more keyDowns generates a character.

Most applications will want to use this function over the others. It will be invoked when a character is generated.

Parameters:

key - Character generated, after any effects of the ALT or SHIFT keys and any complex keyboard mappings.

status - Status of the ALT, SHIFT and CAPS LOCK keys.

time - Number of milliseconds since the device was turned on.

Returns:

True if the event was consumed.

keyDown

boolean keyDown(int keycode,
                int time)

Invoked when a key has been pressed.

Using Keypad.key(keycode) gets the key pressed; alphabetic keys are always upper case. Using keypad.status(keycode) gets the modifier key status at the time of the keypress.

Applications such as games will want to use this funtion as it provides information about which key was actually pressed, regardless of locale and any key mappings applied.

Parameters:

keycode - Key scan code of the character shown, before any effects of the ALT or SHIFT keys.

time - Number of milliseconds since the device was turned on.

Returns:

True if the event was consumed.

keyUp

boolean keyUp(int keycode,
              int time)

Invoked when a key has been released.

Using Keypad.key(keycode) gets the key pressed; alphabetic keys are always upper case. Using Keypad.key(keycode) gets the modifier key status at the time of the keypress.

Note that keyUp events are disabled by default for performance reasons, and must be explicitly enabled via Application.enableKeyUpEvents(boolean).

Parameters:

keycode - Key scan code of the character shown, before any effects of the ALT or SHIFT keys.

time - Number of milliseconds since the device was turned on.

Returns:

True if the event was consumed.

keyRepeat

boolean keyRepeat(int keycode,
                  int time)

Invoked when a key has been repeated. Similar to keyDown.

Parameters:

keycode - Key scan code of the character shown, before any effects of the ALT or SHIFT keys.

time - Number of milliseconds since the device was turned on.

Returns:

True if the event was consumed.

keyStatus

boolean keyStatus(int keycode,
                  int time)

Invoked when the ALT or SHIFT status has changed.

Parameters:

keycode - Key scan code of the character shown, before any effects of the ALT or SHIFT keys.

time - Number of milliseconds since the device was turned on.

Returns:

True if the event was consumed.