net.rim.device.api.system
Interface KeyListener

All Superinterfaces:
KeypadListener

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

 class KeyListenerDemo extends MainScreen implements KeyListener
 {
     public KeyListenerDemo()
     {
         addKeyListener(this);        
     }
     
     // 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;
     }    
 }
 


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

public 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

public 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.

keyRepeat

public 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

public 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.

keyUp

public 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.



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.