|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.media.MediaKeyListener
public abstract class MediaKeyListener
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.
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.
Application.addMediaActionHandler(MediaActionHandler)
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 |
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 |
---|
public MediaKeyListener()
MediaKeyListener
. This constructor simply invokes
MediaKeyListener.MediaKeyListener(int)
with mediaActionSource==SOURCE_FOREGROUND_KEY.
MediaActionHandler.SOURCE_FOREGROUND_KEY
public MediaKeyListener(int mediaActionSource)
MediaKeyListener
. This constructor simply invokes
MediaKeyListener.MediaKeyListener(int, Object)
with the specified mediaActionSource and
mediaActionContext==null.
mediaActionSource
- the value for "source" to specify to mediaAction() when it is
invoked from this object (see MediaActionHandler.mediaAction(int, int, Object)
for
details).public MediaKeyListener(int mediaActionSource, Object mediaActionContext)
MediaKeyListener
.
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.Method Detail |
---|
public Object getMediaActionContext()
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().
MediaKeyListener.getMediaActionSource()
,
MediaKeyListener.mediaAction(int)
public int getMediaActionSource()
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().
MediaKeyListener.getMediaActionContext()
,
MediaKeyListener.mediaAction(int)
public boolean keyChar(char character, int status, int time)
KeyListener
Most applications will want to use this function over the others. It will be invoked when a character is generated.
keyChar
in interface KeyListener
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.
public boolean keyDown(int keycode, int time)
KeyListener
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.
keyDown
in interface KeyListener
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.
public boolean keyRepeat(int keycode, int time)
KeyListener
keyRepeat
in interface KeyListener
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.
public boolean keyStatus(int keycode, int time)
KeyListener
keyStatus
in interface KeyListener
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.
public boolean keyUp(int keycode, int time)
KeyListener
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)
.
keyUp
in interface KeyListener
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.
public boolean mediaAction(int action)
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.
action
- the "action" to specify to mediaAction(int, int, Object).
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.