Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

javax.microedition.agui.event
Class DeviceKeyEvent

java.lang.Object
  java.util.EventObject
      java.awt.AWTEvent
          java.awt.event.ComponentEvent
              java.awt.event.InputEvent
                  java.awt.event.KeyEvent
                      javax.microedition.agui.event.DeviceKeyEvent

All Implemented Interfaces:

java.io.Serializable

public class DeviceKeyEvent

extends java.awt.event.KeyEvent

A device specific event which indicates that a keystroke occurred in a component.

The current set of keys defined in the java.awt.event.KeyEvent reflects the set of keys typically found on desktop computers. However, given the intention of using this profile for consumer and embedded devices, the set of keys that needs to be represented is not always covered by the existing codes.

In existing uses of desktop-centric toolkits, the issue of device-specific keys has been typically addressed by re-using an existing key code for the device-specific code. For example, the 'Send' key on a wireless phone could be represented using VK_F4. In addition to being manufacturer/product specific, this arrangement is also problematic if a newer version of the product includes the key that was re-used. For example, if a new version of the phone is developed with a full keyboard, it may actually include an F4 key. In terms of promoting interoperability and application portability, this arrangement is clearly sub-optimal. Target Devices Since AGUI is specifically targeted at the consumer/embedded space, it is appropriate for this specification to define additional key codes that cover the keys that are typically found on the target devices. The set of keys to be defined should cover a range of devices including:

• Wireless phones
• PDAs
• MP3 players
• Digital Televisions and Set Top Boxes
• DVRs
• Telematics

In addition to making the API more appropriate for these devices, a standard set of key codes will promote application portability across manufacturers and even across device types. Historically, each type of device has included its own set of keys; however, given the current convergence between computers, phones, and other consumer devices, the existence of a common set of keys would be extremely useful.

Existing Standards

This area has been partially addressed by other standards groups such as HAVi (Home Audio Video Interoperability, www.havi.org), but those standards have typically focused on a narrower range of devices. The intention for AGUI is to leverage existing standards wherever possible and build upon them to provide a more complete set of key codes that covers a wider range of devices.

Usage

The keyCode as defined in KeyEvent for instances of DeviceKeyEvent is always VK_UNDEFINED and is set by the constructor. This allows applications to determine that the key event triggered does not correspond to a known key constant as defined in KeyEvent When a new DeviceKeyObject is created, the appropriate deviceKeyCode chosen from the constants in this class must be provided.

When an application receives a KeyEvent on an implementation of AGUI and the keyCode is VK_UNDEFINED, the application should check to see if the type of the object is DeviceKeyEvent (via instanceOf). Then use the methods in DeviceKeyEvent to determine the type of key that was pressed.

See Also:

KeyEvent, Serialized Form

Field Summary

static int	DK_BROWSER Invokes a browser
static int	DK_CALENDAR Invokes calendar functionality
static int	DK_CANCEL Cancels an action
static int	DK_CONTACTS Invokes contact database functionality
static int	DK_EJECT Ejects removable media
static int	DK_END Terminates a voice call
static int	DK_FAST_FORWARD Advances quickly through audio/video media
static int	DK_HOME Brings user to the Home screen
static int	DK_IM Invokes instant messaging functionality
static int	DK_KEYPAD_CAMERA Accesses camera functionality
static int	DK_KEYPAD_CARRIER Invokes carrier-defined functionality
static int	DK_KEYPAD_CLEAR Clears text data
static int	DK_KEYPAD_MENU Invokes a menu of choices for the current context
static int	DK_KEYPAD_VOL_DOWN Decreases audio volume
static int	DK_KEYPAD_VOL_UP Increases audio volume
static int	DK_MEDIA_PLAYER Invokes media player functionality
static int	DK_MESSAGE Invokes messaging functionality
static int	DK_MUTE_MICROPHONE Mutes audio input
static int	DK_MUTE_SPEAKER Mutes audio output
static int	DK_NEXT Selects the next track or scene in audio/video media
static int	DK_OK Accepts an action
static int	DK_PAUSE Pauses playback or recording of audio/video media
static int	DK_PLAY Initiates playback of audio/video media
static int	DK_PREV Selects the previous track or scene in audio/video media
static int	DK_PRINT Produces a hard copy of a document or image
static int	DK_RECORD Initiates recording of audio/video media
static int	DK_REWIND Reverses quickly through audio/video media
static int	DK_SEND Initiates a voice call
static int	DK_SOFTKEY_0 Softkey 0
static int	DK_SOFTKEY_1 Softkey 1
static int	DK_SOFTKEY_2 Softkey 2
static int	DK_SOFTKEY_3 Softkey 3
static int	DK_SOFTKEY_4 Softkey 4
static int	DK_SOFTKEY_5 Softkey 5
static int	DK_SOFTKEY_6 Softkey 6
static int	DK_SOFTKEY_7 Softkey 7
static int	DK_SOFTKEY_8 Softkey 8
static int	DK_SOFTKEY_9 Softkey 9
static int	DK_STOP Stops playback or recording of audio/video media
static int	DK_ZOOM_IN Increases the zoom level of a camera or image viewer
static int	DK_ZOOM_OUT Decreases the zoom level of a camera or image viewer

Fields inherited from class java.awt.event.KeyEvent

CHAR_UNDEFINED, KEY_FIRST, KEY_LAST, KEY_PRESSED, KEY_RELEASED, KEY_TYPED, VK_0, VK_1, VK_2, VK_3, VK_4, VK_5, VK_6, VK_7, VK_8, VK_9, VK_A, VK_ACCEPT, VK_ADD, VK_AGAIN, VK_ALL_CANDIDATES, VK_ALPHANUMERIC, VK_ALT, VK_ALT_GRAPH, VK_AMPERSAND, VK_ASTERISK, VK_AT, VK_B, VK_BACK_QUOTE, VK_BACK_SLASH, VK_BACK_SPACE, VK_BRACELEFT, VK_BRACERIGHT, VK_C, VK_CANCEL, VK_CAPS_LOCK, VK_CIRCUMFLEX, VK_CLEAR, VK_CLOSE_BRACKET, VK_CODE_INPUT, VK_COLON, VK_COMMA, VK_COMPOSE, VK_CONTROL, VK_CONVERT, VK_COPY, VK_CUT, VK_D, VK_DEAD_ABOVEDOT, VK_DEAD_ABOVERING, VK_DEAD_ACUTE, VK_DEAD_BREVE, VK_DEAD_CARON, VK_DEAD_CEDILLA, VK_DEAD_CIRCUMFLEX, VK_DEAD_DIAERESIS, VK_DEAD_DOUBLEACUTE, VK_DEAD_GRAVE, VK_DEAD_IOTA, VK_DEAD_MACRON, VK_DEAD_OGONEK, VK_DEAD_SEMIVOICED_SOUND, VK_DEAD_TILDE, VK_DEAD_VOICED_SOUND, VK_DECIMAL, VK_DELETE, VK_DIVIDE, VK_DOLLAR, VK_DOWN, VK_E, VK_END, VK_ENTER, VK_EQUALS, VK_ESCAPE, VK_EURO_SIGN, VK_EXCLAMATION_MARK, VK_F, VK_F1, VK_F10, VK_F11, VK_F12, VK_F13, VK_F14, VK_F15, VK_F16, VK_F17, VK_F18, VK_F19, VK_F2, VK_F20, VK_F21, VK_F22, VK_F23, VK_F24, VK_F3, VK_F4, VK_F5, VK_F6, VK_F7, VK_F8, VK_F9, VK_FINAL, VK_FIND, VK_FULL_WIDTH, VK_G, VK_GREATER, VK_H, VK_HALF_WIDTH, VK_HELP, VK_HIRAGANA, VK_HOME, VK_I, VK_INPUT_METHOD_ON_OFF, VK_INSERT, VK_INVERTED_EXCLAMATION_MARK, VK_J, VK_JAPANESE_HIRAGANA, VK_JAPANESE_KATAKANA, VK_JAPANESE_ROMAN, VK_K, VK_KANA, VK_KANA_LOCK, VK_KANJI, VK_KATAKANA, VK_KP_DOWN, VK_KP_LEFT, VK_KP_RIGHT, VK_KP_UP, VK_L, VK_LEFT, VK_LEFT_PARENTHESIS, VK_LESS, VK_M, VK_META, VK_MINUS, VK_MODECHANGE, VK_MULTIPLY, VK_N, VK_NONCONVERT, VK_NUM_LOCK, VK_NUMBER_SIGN, VK_NUMPAD0, VK_NUMPAD1, VK_NUMPAD2, VK_NUMPAD3, VK_NUMPAD4, VK_NUMPAD5, VK_NUMPAD6, VK_NUMPAD7, VK_NUMPAD8, VK_NUMPAD9, VK_O, VK_OPEN_BRACKET, VK_P, VK_PAGE_DOWN, VK_PAGE_UP, VK_PASTE, VK_PAUSE, VK_PERIOD, VK_PLUS, VK_PREVIOUS_CANDIDATE, VK_PRINTSCREEN, VK_PROPS, VK_Q, VK_QUOTE, VK_QUOTEDBL, VK_R, VK_RIGHT, VK_RIGHT_PARENTHESIS, VK_ROMAN_CHARACTERS, VK_S, VK_SCROLL_LOCK, VK_SEMICOLON, VK_SEPARATER, VK_SEPARATOR, VK_SHIFT, VK_SLASH, VK_SPACE, VK_STOP, VK_SUBTRACT, VK_T, VK_TAB, VK_U, VK_UNDEFINED, VK_UNDERSCORE, VK_UNDO, VK_UP, VK_V, VK_W, VK_X, VK_Y, VK_Z

Fields inherited from class java.awt.event.InputEvent

ALT_DOWN_MASK, ALT_GRAPH_DOWN_MASK, ALT_GRAPH_MASK, ALT_MASK, BUTTON1_DOWN_MASK, BUTTON1_MASK, BUTTON2_DOWN_MASK, BUTTON2_MASK, BUTTON3_DOWN_MASK, BUTTON3_MASK, CTRL_DOWN_MASK, CTRL_MASK, META_DOWN_MASK, META_MASK, SHIFT_DOWN_MASK, SHIFT_MASK

Fields inherited from class java.awt.event.ComponentEvent

COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN

Fields inherited from class java.awt.AWTEvent

ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK

Fields inherited from class java.util.EventObject

source

Constructor Summary

DeviceKeyEvent(java.awt.Component source, int id, long when, int modifiers, int deviceKeyCode, char keyChar)
Constructs a DeviceKeyEvent object.

Method Summary

int	getDeviceKeyCode() Returns the integer device keyCode associated with this event

Methods inherited from class java.awt.event.KeyEvent

getKeyChar, getKeyCode, getKeyModifiersText, getKeyText, isActionKey, paramString, setKeyChar, setKeyCode, setSource

Methods inherited from class java.awt.event.InputEvent

consume, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown

Methods inherited from class java.awt.event.ComponentEvent

getComponent

Methods inherited from class java.awt.AWTEvent

getID, toString

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DK_KEYPAD_MENU

public static final int DK_KEYPAD_MENU

Invokes a menu of choices for the current context

See Also:

Constant Field Values

DK_KEYPAD_VOL_UP

public static final int DK_KEYPAD_VOL_UP

Increases audio volume

See Also:

Constant Field Values

DK_KEYPAD_VOL_DOWN

public static final int DK_KEYPAD_VOL_DOWN

Decreases audio volume

See Also:

Constant Field Values

DK_MUTE_SPEAKER

public static final int DK_MUTE_SPEAKER

Mutes audio output

See Also:

Constant Field Values

DK_MUTE_MICROPHONE

public static final int DK_MUTE_MICROPHONE

Mutes audio input

See Also:

Constant Field Values

DK_KEYPAD_CAMERA

public static final int DK_KEYPAD_CAMERA

Accesses camera functionality

See Also:

Constant Field Values

DK_KEYPAD_CLEAR

public static final int DK_KEYPAD_CLEAR

Clears text data

See Also:

Constant Field Values

DK_KEYPAD_CARRIER

public static final int DK_KEYPAD_CARRIER

Invokes carrier-defined functionality

See Also:

Constant Field Values

DK_SEND

public static final int DK_SEND

Initiates a voice call

See Also:

Constant Field Values

DK_END

public static final int DK_END

Terminates a voice call

See Also:

Constant Field Values

DK_MESSAGE

public static final int DK_MESSAGE

Invokes messaging functionality

See Also:

Constant Field Values

DK_OK

public static final int DK_OK

Accepts an action

See Also:

Constant Field Values

DK_CANCEL

public static final int DK_CANCEL

Cancels an action

See Also:

Constant Field Values

DK_PLAY

public static final int DK_PLAY

Initiates playback of audio/video media

See Also:

Constant Field Values

DK_RECORD

public static final int DK_RECORD

Initiates recording of audio/video media

See Also:

Constant Field Values

DK_STOP

public static final int DK_STOP

Stops playback or recording of audio/video media

See Also:

Constant Field Values

DK_PAUSE

public static final int DK_PAUSE

Pauses playback or recording of audio/video media

See Also:

Constant Field Values

DK_NEXT

public static final int DK_NEXT

Selects the next track or scene in audio/video media

See Also:

Constant Field Values

DK_PREV

public static final int DK_PREV

Selects the previous track or scene in audio/video media

See Also:

Constant Field Values

DK_FAST_FORWARD

public static final int DK_FAST_FORWARD

Advances quickly through audio/video media

See Also:

Constant Field Values

DK_REWIND

public static final int DK_REWIND

Reverses quickly through audio/video media

See Also:

Constant Field Values

DK_ZOOM_IN

public static final int DK_ZOOM_IN

Increases the zoom level of a camera or image viewer

See Also:

Constant Field Values

DK_ZOOM_OUT

public static final int DK_ZOOM_OUT

Decreases the zoom level of a camera or image viewer

See Also:

Constant Field Values

DK_PRINT

public static final int DK_PRINT

Produces a hard copy of a document or image

See Also:

Constant Field Values

DK_EJECT

public static final int DK_EJECT

Ejects removable media

See Also:

Constant Field Values

DK_CALENDAR

public static final int DK_CALENDAR

Invokes calendar functionality

See Also:

Constant Field Values

DK_CONTACTS

public static final int DK_CONTACTS

Invokes contact database functionality

See Also:

Constant Field Values

DK_BROWSER

public static final int DK_BROWSER

Invokes a browser

See Also:

Constant Field Values

DK_SOFTKEY_0

public static final int DK_SOFTKEY_0

Softkey 0

See Also:

Constant Field Values

DK_SOFTKEY_1

public static final int DK_SOFTKEY_1

Softkey 1

See Also:

Constant Field Values

DK_SOFTKEY_2

public static final int DK_SOFTKEY_2

Softkey 2

See Also:

Constant Field Values

DK_SOFTKEY_3

public static final int DK_SOFTKEY_3

Softkey 3

See Also:

Constant Field Values

DK_SOFTKEY_4

public static final int DK_SOFTKEY_4

Softkey 4

See Also:

Constant Field Values

DK_SOFTKEY_5

public static final int DK_SOFTKEY_5

Softkey 5

See Also:

Constant Field Values

DK_SOFTKEY_6

public static final int DK_SOFTKEY_6

Softkey 6

See Also:

Constant Field Values

DK_SOFTKEY_7

public static final int DK_SOFTKEY_7

Softkey 7

See Also:

Constant Field Values

DK_SOFTKEY_8

public static final int DK_SOFTKEY_8

Softkey 8

See Also:

Constant Field Values

DK_SOFTKEY_9

public static final int DK_SOFTKEY_9

Softkey 9

See Also:

Constant Field Values

DK_HOME

public static final int DK_HOME

Brings user to the Home screen

See Also:

Constant Field Values

DK_MEDIA_PLAYER

public static final int DK_MEDIA_PLAYER

Invokes media player functionality

See Also:

Constant Field Values

DK_IM

public static final int DK_IM

Invokes instant messaging functionality

See Also:

Constant Field Values

Constructor Detail

DeviceKeyEvent

public DeviceKeyEvent(java.awt.Component source,
                      int id,
                      long when,
                      int modifiers,
                      int deviceKeyCode,
                      char keyChar)

Constructs a DeviceKeyEvent object.

Note: calls to getKeyCode() will always return VK_UNDEFINED.

Note that passing in an invalid id results in unspecified behavior.

Parameters:

source - - the Component that originated the event

id - - an integer identifying the type of event

when - - a long integer that specifies the time the event occurred

modifiers - - the modifier keys down during event (shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.

deviceKeyCode - - the integer code for the device key code as defined in DeviceKeyCode such as DK_REWIND

keyChar - - the Unicode character generated by this event, or CHAR_UNDEFINED (for key-pressed and key-released events which do not map to a valid Unicode character)

Throws:

java.lang.IllegalArgumentException - - if id is KEY_TYPED and keyChar is CHAR_UNDEFINED; or if id is KEY_TYPED and keyCode is not VK_UNDEFINED

Method Detail

getDeviceKeyCode

public int getDeviceKeyCode()

Returns the integer device keyCode associated with this event