net.rim.device.api.media
Class MediaKeyListener

java.lang.Object
  net.rim.device.api.media.MediaKeyListener

All Implemented Interfaces:

MediaActionHandler, KeyListener, KeypadListener

public abstract class MediaKeyListener
extends Object
implements KeyListener, MediaActionHandler

An implementation of KeyListener that maps key events to media actions identical to those implemented by the built-in media player. The implementations of the KeyListener methods in this class translate the key presses into media actions and invoke mediaAction() accordingly. If the key presses do not map to a media action then the key presses are not consumed by the KeyListener methods. Also, if the invocation of mediaAction() does not consume the media action then the KeyListener method that invoked mediaAction() will not consume it either.

The intention of MediaKeyListener is to allow applications to have their logic to respond to media actions in a single place. Applications would create a concrete subclass of this class that implements the methods defined in MediaActionHandler. Then, an instance of that class can be registered as a KeyListener either by using Application.addKeyListener() or Screen.addKeyListener(), which will handle media key presses while the application is in the foreground. Then, the same instance of MediaKeyListener can be registered using Application.addMediaActionHandler() in order to respond to media key presses while in the background, as well as media actions from other sources.

Not all of the media actions defined in MediaActionHandler are generated by MediaKeyListener. Only those that have a dedicated key or combinations of keys are actually generated.

Key Mappings

The exact mappings from key presses to media actions vary, depending on the hardware keys that are available and other factors about the device. On all devices, the "volume up" and "volume down" keys generate MEDIA_ACTION_VOLUME_UP and MEDIA_ACTION_VOLUME_DOWN, respectively. Also, the "mute" key generates MEDIA_ACTION_PLAYPAUSE_TOGGLE.

On devices without "media keys" (that is, Keypad.hasMediaKeys() returns false) pressing-and-holding the "volume up" and "volume down" keys generates MEDIA_ACTION_NEXT_TRACK and MEDIA_ACTION_PREV_TRACK, respectively. On devices with media keys the "forward" and "backward" keys are instead used to generate these media actions, respectively, and pressing-and-holding the volume keys does not generate any media action.

Every effort is made to process key presses on keyDown(), since this generally leads to a better user experience; however, this is not always possible when a key's meaning is overloaded, and in these cases the media actions are generated on keyUp() instead. For example, on devices where pressing-and-holding the "volume" keys generates next/previous track actions the volume actions are generated on keyUp() and the next/previous track actions are generated on keyRepeat(). Also, on BlackBerry models that use the "mute" key to toggle standby mode, the play/pause media action is generated on keyUp() instead of keyDown() as the keyDown() or keyRepeat() may be used to toggle standby mode, in which case we do not want to also generate a media action.

See Also:

Application.addMediaActionHandler(MediaActionHandler)

Since:

BlackBerry API 5.0.0

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

Fields inherited from interface net.rim.device.api.media.MediaActionHandler

MEDIA_ACTION_CUSTOM_OFFSET, MEDIA_ACTION_FAST_FORWARD, MEDIA_ACTION_INVALID, MEDIA_ACTION_MUTE, MEDIA_ACTION_MUTE_TOGGLE, MEDIA_ACTION_NEXT_TRACK, MEDIA_ACTION_PAUSE, MEDIA_ACTION_PLAY, MEDIA_ACTION_PLAYPAUSE_TOGGLE, MEDIA_ACTION_PREV_TRACK, MEDIA_ACTION_REWIND, MEDIA_ACTION_STOP, MEDIA_ACTION_UNMUTE, MEDIA_ACTION_UNPAUSE, MEDIA_ACTION_VOLUME_DOWN, MEDIA_ACTION_VOLUME_UP, SOURCE_BACKGROUND_KEY, SOURCE_BLUETOOTH_HEADSET, SOURCE_CUSTOM_OFFSET, SOURCE_FOREGROUND_KEY, SOURCE_INVALID, SOURCE_WIRED_HEADSET

Constructor Summary

MediaKeyListener()
Creates a new instance of MediaKeyListener.

MediaKeyListener(int mediaActionSource)
Creates a new instance of MediaKeyListener.

MediaKeyListener(int mediaActionSource, Object mediaActionContext)
Creates a new instance of MediaKeyListener.

Method Summary
Object	getMediaActionContext() Returns the value that will be specified as the "context" argument to mediaAction().
int	getMediaActionSource() Returns the value that will be specified as the "source" argument to mediaAction().
boolean	keyChar(char character, 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.
boolean	mediaAction(int action) Invokes mediaAction(int, int, Object) with the current source and context.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.rim.device.api.media.MediaActionHandler

mediaAction

Constructor Detail

MediaKeyListener

public MediaKeyListener()

Creates a new instance of MediaKeyListener. This constructor simply invokes MediaKeyListener.MediaKeyListener(int) with mediaActionSource==SOURCE_FOREGROUND_KEY.

See Also:

MediaActionHandler.SOURCE_FOREGROUND_KEY

Since:

BlackBerry API 5.0.0

MediaKeyListener

public MediaKeyListener(int mediaActionSource)

Creates a new instance of MediaKeyListener. This constructor simply invokes MediaKeyListener.MediaKeyListener(int, Object) with the specified mediaActionSource and mediaActionContext==null.

Parameters:

mediaActionSource - the value for "source" to specify to mediaAction() when it is invoked from this object (see MediaActionHandler.mediaAction(int, int, Object) for details).

Since:

BlackBerry API 5.0.0

MediaKeyListener

public MediaKeyListener(int mediaActionSource,
                        Object mediaActionContext)

Creates a new instance of MediaKeyListener.

Parameters:

mediaActionSource - the value for "source" to specify to mediaAction() when it is invoked from this object (see MediaActionHandler.mediaAction(int, int, Object) for details).

mediaActionContext - the value for "context" to specify to mediaAction() when it is invoked from this object; may be null.

Since:

BlackBerry API 5.0.0

Method Detail

getMediaActionContext

public Object getMediaActionContext()

Returns the value that will be specified as the "context" argument to mediaAction(). This method returns the value that was either explicitly specified to or implicitly chosen by the constructor.

This method may be overridden by subclasses and whatever value is returned when invoked just prior to each invocation of mediaAction() will be specified to mediaAction().

Returns:

the media action context that is to be specified to mediaAction() when invoked from this object.

See Also:

MediaKeyListener.getMediaActionSource(), MediaKeyListener.mediaAction(int)

Since:

BlackBerry API 5.0.0

getMediaActionSource

public int getMediaActionSource()

Returns the value that will be specified as the "source" argument to mediaAction(). This method returns the value that was either explicitly specified to or implicitly chosen by the constructor.

This method may be overridden by subclasses and whatever value is returned when invoked just prior to each invocation of mediaAction() will be specified to mediaAction().

Returns:

the media action source that is to be specified to mediaAction() when invoked from this object.

See Also:

MediaKeyListener.getMediaActionContext(), MediaKeyListener.mediaAction(int)

Since:

BlackBerry API 5.0.0

keyChar

public boolean keyChar(char character,
                       int status,
                       int time)

Description copied from interface: KeyListener

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.

Specified by:

keyChar in interface KeyListener

Parameters:

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

Since:

BlackBerry API 5.0.0

keyDown

public boolean keyDown(int keycode,
                       int time)

Description copied from interface: KeyListener

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.

Specified by:

keyDown in interface KeyListener

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.

Since:

BlackBerry API 5.0.0

keyRepeat

public boolean keyRepeat(int keycode,
                         int time)

Description copied from interface: KeyListener

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

Specified by:

keyRepeat in interface KeyListener

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.

Since:

BlackBerry API 5.0.0

keyStatus

public boolean keyStatus(int keycode,
                         int time)

Description copied from interface: KeyListener

Invoked when the ALT or SHIFT status has changed.

Specified by:

keyStatus in interface KeyListener

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.

Since:

BlackBerry API 5.0.0

keyUp

public boolean keyUp(int keycode,
                     int time)

Description copied from interface: KeyListener

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

Specified by:

keyUp in interface KeyListener

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.

Since:

BlackBerry API 5.0.0

mediaAction

public boolean mediaAction(int action)

Invokes mediaAction(int, int, Object) with the current source and context. This method invokes MediaKeyListener.getMediaActionSource() and MediaKeyListener.getMediaActionContext() and then invokes MediaActionHandler.mediaAction(int, int, Object) with the specified action and the source and context returned from the methods, respectively.

Parameters:

action - the "action" to specify to mediaAction(int, int, Object).

Returns:

the value returned from mediaAction(int, int, Object) when invoked with the specified action and the source and context returned from getMediaActionSource() and getMediaActionContext(), respectively.

Since:

BlackBerry API 5.0.0