net.rim.device.api.ui
Class Keypad

java.lang.Object
  extended by net.rim.device.api.ui.Keypad

public class Keypad
extends Object

Provides keypad functionality.

See Also:
KeypadListener

Field Summary
static long GUID_KEYPAD_CHANGED
          GUID for global event sent when the current locale changes.
static int HW_LAYOUT_32
          QWERTY keyboard layout (87xx series). 38 keys.
static int HW_LAYOUT_39
          QWERTY keyboard layout (88xx series). 39 keys.
static int HW_LAYOUT_HANDW_RECOGNITION
          Handwritten recognition layout.
static int HW_LAYOUT_ITUT
          Dial pad keyboard layout (**** series). 12 keys.
static int HW_LAYOUT_LEGACY
          Legacy QWERTY keyboard layout (57xx, 58xx series). 30 keys.
static int HW_LAYOUT_PHONE
          QWERTY /w phone keyboard layout (65xx, 67xx, 72xx, 75xx, 77xx series). 34 keys.
static int HW_LAYOUT_REDUCED
          Reduced QW-ER-TY-OP keyboard layout (71xx series). 23 keys.
static int HW_LAYOUT_REDUCED_24
          Reduced QW-ER-TY-OP keyboard layout (81xx series). 24 keys.
static int HW_LAYOUT_TOUCHSCREEN_12
          Dial pad keyboard layout (9500 series). 12 keys.
static int HW_LAYOUT_TOUCHSCREEN_12A
          Portrait Arabic layout (9500 series). 12 keys.
static int HW_LAYOUT_TOUCHSCREEN_12C
          Portrait Chinese WuBiHua/Strokes layout (9500 series). 12 keys.
static int HW_LAYOUT_TOUCHSCREEN_12H
          Landscape Hebrew keyboard layout (9500 series). 12 keys.
static int HW_LAYOUT_TOUCHSCREEN_20J
          Reduced Kana Japanese keyboard layout (9500 series). 20 keys.
static int HW_LAYOUT_TOUCHSCREEN_20JA
          Reduced QW-ER-TY-OP Japanese keyboard layout (9500 series). 20 keys.
static int HW_LAYOUT_TOUCHSCREEN_20K
          Portrait Korean layout (9500 series). 20 keys.
static int HW_LAYOUT_TOUCHSCREEN_20N
          Reduced Numeric and Hexadecimal keyboard layout (9500 series). 20 keys.
static int HW_LAYOUT_TOUCHSCREEN_24
          Reduced QW-ER-TY-OP keyboard layout (9500 series). 24 keys.
static int HW_LAYOUT_TOUCHSCREEN_29
          QWERTY keyboard layout (9500 series). 29 keys.
static int HW_LAYOUT_TOUCHSCREEN_29T
          Landscape Thai keyboard layout (9500 series). 37 keys.
static int HW_LAYOUT_TOUCHSCREEN_35H
          Landscape Hebrew keyboard layout (9500 series). 35 keys.
static int HW_LAYOUT_TOUCHSCREEN_35J
          Landscape Kana Japanese keyboard layout (9500 series). 35 keys.
static int HW_LAYOUT_TOUCHSCREEN_37A
          Landscape Arabic keyboard layout (9500 series). 37 keys.
static int HW_LAYOUT_TOUCHSCREEN_37B
          Landscape Bopomofo keyboard layout (9500 series). 37 keys.
static int KEY_ALT
          ALT key constant.
static int KEY_APPLICATION
          Deprecated. Use KEY_CONVENIENCE_2
static int KEY_BACKLIGHT
          Backlight key constant.
static int KEY_BACKSPACE
          Backspace key constant.
static int KEY_BACKWARD
          Multimedia skip backward key constant.
static int KEY_CAMERA_FOCUS
          Camera auto focus key constant.
static int KEY_CONVENIENCE_1
          Convenience Key 1 constant.
static int KEY_CONVENIENCE_2
          Convenience key 2 constant.
static int KEY_DELETE
          Delete key constant.
static int KEY_END
          End key constant.
static int KEY_ENTER
          Enter key constant.
static int KEY_ESCAPE
          Escape key constant.
static int KEY_FORWARD
          Multimedia skip forward key constant.
static int KEY_LOCK
          Lock device key constant.
static int KEY_MENU
          Menu key constant.
static int KEY_MIDDLE
          Middle key (between SEND and END) constant.
static int KEY_NEXT
          Next key constant.
static int KEY_RIGHT_3
          Third right key constant.
static int KEY_SEND
          Send key constant.
static int KEY_SHIFT_LEFT
          Left-shift key constant.
static int KEY_SHIFT_RIGHT
          Right-shift key constant.
static int KEY_SHIFT_X
          Right-shift/0 key constant.
static int KEY_SPACE
          Space key constant.
static int KEY_SPEAKERPHONE
          Speakerphone toggle key constant.
static int KEY_VOLUME_DOWN
          Volume down key constant.
static int KEY_VOLUME_UP
          Volume up key constant.
 
Method Summary
static char getAltedChar(char ch)
          Retrieves alternate version of specified character.
static int getHardwareLayout()
          Retrieves system keyboard hardware style.
static void getKeyChars(int key, int status, StringBuffer result)
          Retrieves all characters matching specified key and status value from the keymap.
static void getKeyChars(int keycode, StringBuffer result)
          Retrieves all characters matching specified keycode from the keymap.
static int getKeyCode(char ch, int status)
          Performs reverse lookup of key code that corresponds to given char and status.
static Locale getLocale()
          Retrieves this keypad's locale.
static char getUnaltedChar(char ch)
          Retrieves the un-alted version of a character.
static boolean hasCurrencyKey()
          Determines if the device has dedicated Currency key.
static boolean hasMediaKeys()
          Determines if the device has a dedicated media keys.
static boolean hasMuteKey()
          Determines if the device has a dedicated mute key.
static boolean hasSendEndKeys()
          Determines if the device has dedicated SEND/END keys.
static boolean isOnKeypad(char ch)
          Determines if a key is on the keypad.
static boolean isValidKeyCode(int keycode)
          Determines if a keycode is valid in this keymap.
static int key(int keycode)
          Retrieves the key portion of the specified keycode.
static int keycode(char scancode, int status)
          Retrieves keycode, given base character and modifier key state.
static char map(int keycode)
          Retrieves character matching keycode from keymap.
static char map(int key, int status)
          Retrieves character matching specified key from the keymap.
static int status(int keycode)
          Retrieves state of modifier keys, given keycode.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

GUID_KEYPAD_CHANGED

public static final long GUID_KEYPAD_CHANGED
GUID for global event sent when the current locale changes.

See Also:
Constant Field Values

HW_LAYOUT_PHONE

public static final int HW_LAYOUT_PHONE
QWERTY /w phone keyboard layout (65xx, 67xx, 72xx, 75xx, 77xx series). 34 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

HW_LAYOUT_REDUCED

public static final int HW_LAYOUT_REDUCED
Reduced QW-ER-TY-OP keyboard layout (71xx series). 23 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

HW_LAYOUT_REDUCED_24

public static final int HW_LAYOUT_REDUCED_24
Reduced QW-ER-TY-OP keyboard layout (81xx series). 24 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.0

HW_LAYOUT_LEGACY

public static final int HW_LAYOUT_LEGACY
Legacy QWERTY keyboard layout (57xx, 58xx series). 30 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

HW_LAYOUT_32

public static final int HW_LAYOUT_32
QWERTY keyboard layout (87xx series). 38 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

HW_LAYOUT_39

public static final int HW_LAYOUT_39
QWERTY keyboard layout (88xx series). 39 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.3.0

HW_LAYOUT_ITUT

public static final int HW_LAYOUT_ITUT
Dial pad keyboard layout (**** series). 12 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

HW_LAYOUT_TOUCHSCREEN_12

public static final int HW_LAYOUT_TOUCHSCREEN_12
Dial pad keyboard layout (9500 series). 12 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

HW_LAYOUT_TOUCHSCREEN_12C

public static final int HW_LAYOUT_TOUCHSCREEN_12C
Portrait Chinese WuBiHua/Strokes layout (9500 series). 12 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_20K

public static final int HW_LAYOUT_TOUCHSCREEN_20K
Portrait Korean layout (9500 series). 20 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_12A

public static final int HW_LAYOUT_TOUCHSCREEN_12A
Portrait Arabic layout (9500 series). 12 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_29

public static final int HW_LAYOUT_TOUCHSCREEN_29
QWERTY keyboard layout (9500 series). 29 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

HW_LAYOUT_TOUCHSCREEN_24

public static final int HW_LAYOUT_TOUCHSCREEN_24
Reduced QW-ER-TY-OP keyboard layout (9500 series). 24 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

HW_LAYOUT_TOUCHSCREEN_20JA

public static final int HW_LAYOUT_TOUCHSCREEN_20JA
Reduced QW-ER-TY-OP Japanese keyboard layout (9500 series). 20 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_20J

public static final int HW_LAYOUT_TOUCHSCREEN_20J
Reduced Kana Japanese keyboard layout (9500 series). 20 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_20N

public static final int HW_LAYOUT_TOUCHSCREEN_20N
Reduced Numeric and Hexadecimal keyboard layout (9500 series). 20 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_35J

public static final int HW_LAYOUT_TOUCHSCREEN_35J
Landscape Kana Japanese keyboard layout (9500 series). 35 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_37B

public static final int HW_LAYOUT_TOUCHSCREEN_37B
Landscape Bopomofo keyboard layout (9500 series). 37 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_37A

public static final int HW_LAYOUT_TOUCHSCREEN_37A
Landscape Arabic keyboard layout (9500 series). 37 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_29T

public static final int HW_LAYOUT_TOUCHSCREEN_29T
Landscape Thai keyboard layout (9500 series). 37 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_35H

public static final int HW_LAYOUT_TOUCHSCREEN_35H
Landscape Hebrew keyboard layout (9500 series). 35 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_TOUCHSCREEN_12H

public static final int HW_LAYOUT_TOUCHSCREEN_12H
Landscape Hebrew keyboard layout (9500 series). 12 keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

HW_LAYOUT_HANDW_RECOGNITION

public static final int HW_LAYOUT_HANDW_RECOGNITION
Handwritten recognition layout.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

KEY_BACKLIGHT

public static final int KEY_BACKLIGHT
Backlight key constant.

See Also:
Constant Field Values

KEY_BACKSPACE

public static final int KEY_BACKSPACE
Backspace key constant.

See Also:
Constant Field Values

KEY_DELETE

public static final int KEY_DELETE
Delete key constant.

See Also:
Constant Field Values

KEY_ESCAPE

public static final int KEY_ESCAPE
Escape key constant.

See Also:
Constant Field Values

KEY_ENTER

public static final int KEY_ENTER
Enter key constant.

See Also:
Constant Field Values

KEY_SPACE

public static final int KEY_SPACE
Space key constant.

See Also:
Constant Field Values

KEY_SHIFT_RIGHT

public static final int KEY_SHIFT_RIGHT
Right-shift key constant.

See Also:
Constant Field Values

KEY_SHIFT_X

public static final int KEY_SHIFT_X
Right-shift/0 key constant. It is both a shift key as well as the number 0. This dual use key is on the following device series: 62xx, 65xx, 67xx, 72xx, 75xx, and 77xx.

See Also:
Constant Field Values

KEY_ALT

public static final int KEY_ALT
ALT key constant.

The ALT key has no label -- it is the colored key just below the A key and to the left of the Z key.

See Also:
Constant Field Values

KEY_SHIFT_LEFT

public static final int KEY_SHIFT_LEFT
Left-shift key constant.

See Also:
Constant Field Values

KEY_APPLICATION

public static final int KEY_APPLICATION
Deprecated. Use KEY_CONVENIENCE_2
Application key constant.

See Also:
Constant Field Values

KEY_SPEAKERPHONE

public static final int KEY_SPEAKERPHONE
Speakerphone toggle key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

KEY_RIGHT_3

public static final int KEY_RIGHT_3
Third right key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

KEY_SEND

public static final int KEY_SEND
Send key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

KEY_END

public static final int KEY_END
End key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

KEY_MIDDLE

public static final int KEY_MIDDLE
Middle key (between SEND and END) constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.0

KEY_CONVENIENCE_1

public static final int KEY_CONVENIENCE_1
Convenience Key 1 constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.0

KEY_CONVENIENCE_2

public static final int KEY_CONVENIENCE_2
Convenience key 2 constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.0

KEY_NEXT

public static final int KEY_NEXT
Next key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

KEY_CAMERA_FOCUS

public static final int KEY_CAMERA_FOCUS
Camera auto focus key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

KEY_VOLUME_UP

public static final int KEY_VOLUME_UP
Volume up key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.0

KEY_VOLUME_DOWN

public static final int KEY_VOLUME_DOWN
Volume down key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.0

KEY_MENU

public static final int KEY_MENU
Menu key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.0

KEY_LOCK

public static final int KEY_LOCK
Lock device key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

KEY_FORWARD

public static final int KEY_FORWARD
Multimedia skip forward key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

KEY_BACKWARD

public static final int KEY_BACKWARD
Multimedia skip backward key constant.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Method Detail

getAltedChar

public static char getAltedChar(char ch)
Retrieves alternate version of specified character.

Invoke this method to retrieve the character produced through pressing the ALT key in combination with your specified character. If the character cannot be alted, then 0 is returned.

For example, these are true on a RIM 5800 device:

   getAltedChar('W') == '2'
   getAltedChar('2') == '\u0000'
 

And, these are true on a RIM 6700 device:

   getAltedChar('W') == '1'
   getAltedChar('1') == '\u0000'
 

Note: to get the alted version of a key, use Keypad.map(Keypad.key(keycode), KeypadListener.STATUS_ALT).

Parameters:
ch - Character for which to derive alternate version.
Returns:
Alternate version of provided character.
See Also:
Keypad.getUnaltedChar(char)

getLocale

public static Locale getLocale()
Retrieves this keypad's locale.

Returns:
Locale keypad is using.

getUnaltedChar

public static char getUnaltedChar(char ch)
Retrieves the un-alted version of a character.

Invoke this method to retrieve the character produced through not pressing the ALT key in combination with your specified character. If the character cannot be unalted, then 0 is returned.

For example, these are true on a RIM 5800 device:

   getUnaltedChar('W') == '\u0000'
   getUnaltedChar('2') == 'W'
 

And, these are true on a RIM 6700 device:

   getUnaltedChar('W') == '\u0000'
   getUnaltedChar('1') == 'W'
 

Note: to get the alted version of a key, use Keypad.map(Keypad.key(keycode), KeypadListener.STATUS_ALT).

Parameters:
ch - Character for which to derive alternate version.
Returns:
Alternate version of provided character.
See Also:
Keypad.getAltedChar(char)
Since:
BlackBerry API 3.6.0

map

public static char map(int keycode)
Retrieves character matching keycode from keymap.

Invoke this method to retrieve a specific character from this keymap, given its keycode.

Parameters:
keycode - Keycode of key.
Returns:
Character in keymap associated with keycode. If the specified keycode represents a non-base alphabetic character on the device, then the value returned is undefined.

map

public static char map(int key,
                       int status)
Retrieves character matching specified key from the keymap.

Invoke this method to retrieve a specific character from this keymap, given a particular key and status value.

Parameters:
key - The key.
status - Status value for key; this consists of the state of the various modifier keys.
Returns:
Character in keymap associated with the key and modifier keys. If the specified keycode represents a non-base alphabetic character on the device, then the value returned is undefined.

getKeyChars

public static void getKeyChars(int key,
                               int status,
                               StringBuffer result)
Retrieves all characters matching specified key and status value from the keymap.

Parameters:
key - The key.
status - The status value for the key; this consists of the state of the various modifier keys.
result - A buffer to keep resulting characters associated with specified key and status value. The method first clears the buffer then concatenates resulting characters to the cleared buffer. If the specified key and status value represent a non-base alphabetic character on the device (a given keycode is not presented in the current mapping table) then the buffer content is overwritten with Unicode NUL character '' and set to length 1, representing the fact that the value returned is undefined.
See Also:
Keypad.getKeyCode(char ch, int status), Keypad.map(int key, int status)
Since:
BlackBerry API 5.0.0

getKeyChars

public static void getKeyChars(int keycode,
                               StringBuffer result)
Retrieves all characters matching specified keycode from the keymap.

Parameters:
keycode - Keycode of key.
result - A buffer to keep resulting characters associated with specified keycode. The method first clears the buffer then concatenates resulting characters to the cleared buffer. If the specified keycode represents a non-base alphabetic character on the device (a given keycode is not presented in the current mapping table) then the buffer content is overwritten with Unicode NUL character '' and set to length 1, representing the fact that the value returned is undefined.
See Also:
Keypad.getKeyCode(char ch, int status), Keypad.map(int keycode)
Since:
BlackBerry API 5.0.0

key

public static int key(int keycode)
Retrieves the key portion of the specified keycode.

Parameters:
keycode - Keycode for a key.
Returns:
Key portion of the keycode.

getHardwareLayout

public static int getHardwareLayout()
Retrieves system keyboard hardware style.

Returns:
Identifier for system hardware keyboard style, one of the HW_LAYOUT_* constants
Since:
BlackBerry API 4.1.0

getKeyCode

public static int getKeyCode(char ch,
                             int status)
Performs reverse lookup of key code that corresponds to given char and status. This can be used in Field.keyChar(char character, int status, int time) event callbacks to obtain original keycode.

Parameters:
ch - Character that would be generated by current input map with resulting keycode and given status
status - Status value for key
Returns:
Keycode Simple key code (no 16 bit shift and composition with status value) that corresponds to given char and status
See Also:
Keypad.map(int key, int status)
Since:
BlackBerry API 4.2.0

status

public static int status(int keycode)
Retrieves state of modifier keys, given keycode.

Invoke this method to retrieve the state modifier keys must be in to produce a particular key code.

Parameters:
keycode - Keycode for which you want to infer the modifier key state.
Returns:
Mask indiciating the state of the modifier keys.

isOnKeypad

public static boolean isOnKeypad(char ch)
Determines if a key is on the keypad.

Parameters:
ch - Character key to verify.
Returns:
True if on this keypad; otherwise, false.
Since:
BlackBerry API 3.6.0

isValidKeyCode

public static boolean isValidKeyCode(int keycode)
Determines if a keycode is valid in this keymap.

Parameters:
keycode - Keycode you want to check.
Returns:
True if keycode exists in this keymap; otherwise, false.

keycode

public static int keycode(char scancode,
                          int status)
Retrieves keycode, given base character and modifier key state.

Invoke this method to retrieve a particular keycode, given the base character and state of the modifier keys.

Return result is the direct composition of scancode and status values. The method does not invoke any keypad/language specific facilities for composition.

Parameters:
scancode - Base character.
status - State of the modifier keys.
Returns:
Keycode for the key.

hasSendEndKeys

public static boolean hasSendEndKeys()
Determines if the device has dedicated SEND/END keys.

Returns:
True if the device has dedicated SEND/END keys; otherwise, false.
Since:
BlackBerry API 4.0.0

hasCurrencyKey

public static boolean hasCurrencyKey()
Determines if the device has dedicated Currency key.

Returns:
True if the device has dedicated Currency key; otherwise, false.
Since:
BlackBerry API 4.2.1

hasMuteKey

public static boolean hasMuteKey()
Determines if the device has a dedicated mute key.

Returns:
True if the device has a dedicated mute key; otherwise, false.
Since:
BlackBerry API 5.0.0

hasMediaKeys

public static boolean hasMediaKeys()
Determines if the device has a dedicated media keys.

Returns:
True if the device has a dedicated media keys; otherwise, false.
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.