|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface MediaActionHandler
An interface to be implemented by objects that are able to handle actions common to media
players. Objects that implement this interface can register to be notified of media actions, such
as media key presses while in the background and button presses on wired or Bluetooth headsets,
using Application.addMediaActionHandler(MediaActionHandler). Also, there is an abstract
implementation of this class, MediaKeyListener, which can be
added as a KeyListener to an application to map key presses to media actions while in the
foreground.
The implementation of MediaActionHandler.mediaAction(int, int, Object) is to respond to the specified
action. The meaning of the boolean return value, whether or not the action was "consumed", is
implementation specific. For example, media actions that are dispatched from background key
presses ignore this value and MediaKeyListener uses this value to determine whether or not to
consume the key press that resulted in the media action. In general, this method should
unconditionally return true.
The MEDIA_ACTION_ constants represent the different actions that could potentially be specified to the mediaAction() method. A "media action" is something that a media player could reasonably respond to, such as play, pause, volume change, or change track. In general, the mediaAction() method should simply discard unrecognized media actions and return true.
If an application wishes to define its own media actions for its own use then ensure that the
integers assigned to these "custom" actions are greater than or equal to
MediaActionHandler.MEDIA_ACTION_CUSTOM_OFFSET. See the documentation of the MEDIA_ACTION_CUSTOM_OFFSET for
details and rationale.
The SOURCE_ constants represent the different sources from which invocations of mediaAction() can originate. The "source" parameter of mediaAction() will be equal to one of the SOURCE_ constants defined in this interface, and can optionally be used to handle a media action differently based on its source.
If an application wishes to define its own media action sources for its own use then ensure that
the integers assigned to these "custom" sources are greater than or equal to
MediaActionHandler.SOURCE_CUSTOM_OFFSET. See the documentation of the SOURCE_CUSTOM_OFFSET for details and
rationale.
The mediaAction() method has a generic Object parameter named "context". This parameter can be
used by custom media actions that need to specify some sort of contextual information in order
for the most appropriate action to be taken. Consider a "change track" media action; in this case
the context object might be an Integer whose value is the track number to change to. Also, more
advanced media action sources, such as MediaActionHandler.SOURCE_WIRED_HEADSET and
MediaActionHandler.SOURCE_BLUETOOTH_HEADSET, have their own "context" classes, instances of which are
specified to mediaAction() when media actions are generated from those sources.
For an application to respond to media key presses while in the foreground, it should implement KeyListener and register that KeyListener either with the screen of the media player or the Application instance. It can then map the key presses to media actions and invoke mediaAction() on the MediaActionHandler implementation. To use the same mappings as the built-in media player, use MediaKeyListener.
The system maintains a "stack" of applications that have registered at least one MediaActionHandler via Application.addMediaActionHandler(). When a media action occurs, such as from a background media key press or a button press on a wired or Bluetooth headset, then only the MediaActionHandler instances registered with the application on the top of the stack are notified; all MediaActionHandler instances for other applications are not notified. All MediaActionHandler instances registered with the application on the top of the stack are notified, regardless of their return value from mediaAction(); this is different from KeyListeners, where the first KeyListener to consume a key event by returning true will prevent that event from being posted to KeyListeners that would have otherwise been notified after it.
An application is moved to the top of the stack when it is brought to the foreground. When an
application exits or removes its last MediaActionHandler then it is removed from the stack. Also,
MIDlets that have enabled "media player mode" (see MediaBehaviourControl) are present in
the stack as well, as if they had registered a MediaActionHandler, and are removed from the stack
if they disable media player mode.
If a MediaActionHandler is registered via Application.addMediaActionHandler() then it will be
notified of media key presses that occur while the application is in the background. If the
application that happens to be in the foreground consumes a media key press then it will
not be posted as a media action to media action handlers. Invocations of mediaAction()
resulting from background key presses will have source==MediaActionHandler.SOURCE_BACKGROUND_KEY and
context==null.
The system implements this functionality by specifying all unconsumed media key presses to an instance of MediaKeyListener, whose mediaAction() method simply posts the media action to the MediaActionHandlers registered with the application on the top of the stack. Therefore, the key mappings implemented by MediaKeyListener are those that are dispatched as media actions. These mappings cannot be configured.
For MIDlets, similar behaviour can be achieved using MediaBehaviourControl.
If a MediaActionHandler is registered via Application.addMediaActionHandler() then it will be
notified of button presses of a wired headset connected to the BlackBerry smartphone and
Bluetooth headsets that are paired with the BlackBerry smartphone. When mediaAction() is invoked
from one of these sources then either MediaActionHandler.SOURCE_WIRED_HEADSET or
MediaActionHandler.SOURCE_BLUETOOTH_HEADSET will be specified as the "source" parameter, respectively, and
the "context" parameter will be an instance of an appropriate context object. See the
documentation for the SOURCE_ constants for details about the context objects.
Note that media actions from all sources are generated regardless of the audio path through which an application may be playing audio. Therefore, it is the application's responsibility to discard media actions that are deemed to have come from an irrelevant source. For example, suppose an application is playing audio through a wired headset and the user presses the "volume up" button on a paired Bluetooth headset; the application may choose to discard the media action since it came from the Bluetooth headset when the audio is playing through the wired headset, but this logic must be implemented by the application, if desired.
MediaKeyListener,
Application.addMediaActionHandler(MediaActionHandler),
KeyListener| Field Summary | ||
|---|---|---|
static int |
MEDIA_ACTION_CUSTOM_OFFSET
The offset for custom media actions. |
|
static int |
MEDIA_ACTION_FAST_FORWARD
Media action to fast forward the current track. |
|
static int |
MEDIA_ACTION_INVALID
Invalid media action. |
|
static int |
MEDIA_ACTION_MUTE
Media action to mute the audio of playback. |
|
static int |
MEDIA_ACTION_MUTE_TOGGLE
Media action to toggle muting of the playback. |
|
static int |
MEDIA_ACTION_NEXT_TRACK
Media action to skip to the next track. |
|
static int |
MEDIA_ACTION_PAUSE
Media action to pause playback. |
|
static int |
MEDIA_ACTION_PLAY
Media action to begin playback. |
|
static int |
MEDIA_ACTION_PLAYPAUSE_TOGGLE
Media action to switch between "play" and "pause" mode. |
|
static int |
MEDIA_ACTION_PREV_TRACK
Media action to skip back to the previous track, or the beginning of the current track if playback is beyond a certain point of playback in the current track. |
|
static int |
MEDIA_ACTION_REWIND
Media action to rewind the current track. |
|
static int |
MEDIA_ACTION_STOP
Media action to stop the playback. |
|
static int |
MEDIA_ACTION_UNMUTE
Media action to unmute the audio of playback. |
|
static int |
MEDIA_ACTION_UNPAUSE
Media action to un-pause playback. |
|
static int |
MEDIA_ACTION_VOLUME_DOWN
Media action to decrease the volume. |
|
static int |
MEDIA_ACTION_VOLUME_UP
Media action to increase the volume. |
|
static int |
SOURCE_BACKGROUND_KEY
A media action source indicating that a media action was generated from a key press while the application was in the background. |
|
static int |
SOURCE_BLUETOOTH_HEADSET
A media action source indicating that a media action was generated from a Bluetooth headset that is paired with the BlackBerry smartphone. |
|
static int |
SOURCE_CUSTOM_OFFSET
The offset for custom media action sources. |
|
static int |
SOURCE_FOREGROUND_KEY
A media action source indicating that a media action was generated from a key press while the application was the foreground application. |
|
static int |
SOURCE_INVALID
Invalid media action source. |
|
static int |
SOURCE_WIRED_HEADSET
A media action source indicating that a media action was generated from a wired headset that is plugged into the BlackBerry smartphone. |
|
| Method Summary | ||
|---|---|---|
boolean |
mediaAction(int action,
int source,
Object context)
Invoked to handle a media action. |
|
| Field Detail |
|---|
static final int MEDIA_ACTION_INVALID
static final int MEDIA_ACTION_PLAYPAUSE_TOGGLE
Suggested Usage: When this action is specified to mediaAction() then if the player is paused it should resume playback and if it is currently in the middle of playback it should pause the playback. If media playback is "stopped" or has not started then playback should begin, moving into the "playing" state.
MediaActionHandler.MEDIA_ACTION_PLAY,
MediaActionHandler.MEDIA_ACTION_PAUSE,
MediaActionHandler.MEDIA_ACTION_STOP,
Constant Field Valuesstatic final int MEDIA_ACTION_VOLUME_UP
MediaActionHandler.MEDIA_ACTION_VOLUME_DOWN,
Constant Field Valuesstatic final int MEDIA_ACTION_VOLUME_DOWN
MediaActionHandler.MEDIA_ACTION_VOLUME_UP,
Constant Field Valuesstatic final int MEDIA_ACTION_NEXT_TRACK
Suggested Usage: If the implementation is playing items in a sequence, it should stop playing the current item and go to the beginning of the next one. If playback is paused or stopped then it should go to the next item and begin playback. If the last item in the sequence is currently being played then this action should do nothing.
MediaActionHandler.MEDIA_ACTION_PREV_TRACK,
Constant Field Valuesstatic final int MEDIA_ACTION_PREV_TRACK
Suggested Usage: If an item is currently being played then the implementation should go back to the beginning of that item and begin playback there. If playing or paused near the beginning of an item (eg. within the first 2 seconds) then it should go to the beginning of the previous song in the sequence and begin playback from the beginning. If playback is currently paused then the exact same steps should be taken and playback should begin. If at the beginning of the first track in the sequence then it should just go back to the beginning of that item and begin playback.
MediaActionHandler.MEDIA_ACTION_NEXT_TRACK,
Constant Field Valuesstatic final int MEDIA_ACTION_PLAY
Suggested Usage: This action should begin playback of the media. If paused, then playback should be resumed and if stopped playback should begin. If playback is already in progress then this action should do nothing.
MediaActionHandler.MEDIA_ACTION_PLAYPAUSE_TOGGLE,
MediaActionHandler.MEDIA_ACTION_PAUSE,
MediaActionHandler.MEDIA_ACTION_UNPAUSE,
MediaActionHandler.MEDIA_ACTION_STOP,
Constant Field Valuesstatic final int MEDIA_ACTION_PAUSE
Suggested Usage: This action should pause playback of the media. If playback is already paused or otherwise not playing then this action should do nothing.
MediaActionHandler.MEDIA_ACTION_UNPAUSE,
MediaActionHandler.MEDIA_ACTION_PLAYPAUSE_TOGGLE,
MediaActionHandler.MEDIA_ACTION_PLAY,
MediaActionHandler.MEDIA_ACTION_STOP,
Constant Field Valuesstatic final int MEDIA_ACTION_MUTE_TOGGLE
Suggested Usage: If supported, this action should toggle muting of the audio regardless of whether or not playback is in progress. If the audio is not muted then this action should be identical to MEDIA_ACTION_MUTE; otherwise, it should be identical to MEDIA_ACTION_UNMUTE.
MediaActionHandler.MEDIA_ACTION_MUTE,
MediaActionHandler.MEDIA_ACTION_UNMUTE,
Constant Field Valuesstatic final int MEDIA_ACTION_MUTE
Suggested Usage: Regardless of whether or not audio playback is in progress, the volume should be brought down to zero and the current volume saved, so that when unmute occurs the original volume can be restored. If the audio is already muted then this action should do nothing.
MediaActionHandler.MEDIA_ACTION_MUTE_TOGGLE,
MediaActionHandler.MEDIA_ACTION_UNMUTE,
Constant Field Valuesstatic final int MEDIA_ACTION_UNMUTE
Suggested Usage: Regardless of whether or not audio playback is in progress, the volume should be unmuted. If the volume is already unmuted then this action should do nothing. However, if the volume was muted then the volume should be restored to the level that it was at prior to the mute action occurring.
MediaActionHandler.MEDIA_ACTION_MUTE_TOGGLE,
MediaActionHandler.MEDIA_ACTION_MUTE,
Constant Field Valuesstatic final int MEDIA_ACTION_STOP
Suggested Usage: If playback is currently in progress then it should stop. The position in the current item of playback should not be remembered, and the next play action should start at the beginning of the current item in playback. If playback is already stopped or not in progress for some other reason then this action should do nothing.
MediaActionHandler.MEDIA_ACTION_PLAYPAUSE_TOGGLE,
MediaActionHandler.MEDIA_ACTION_PLAY,
MediaActionHandler.MEDIA_ACTION_PAUSE,
MediaActionHandler.MEDIA_ACTION_UNPAUSE,
Constant Field Valuesstatic final int MEDIA_ACTION_UNPAUSE
Suggested Usage: If the current playback is paused then this action should cause the playback to resume. Otherwise, this action should have no effect. This action is different from MEDIA_ACTION_PLAY because it only resumes playback if it was paused, not if it was stopped.
MediaActionHandler.MEDIA_ACTION_PAUSE,
MediaActionHandler.MEDIA_ACTION_PLAYPAUSE_TOGGLE,
MediaActionHandler.MEDIA_ACTION_PLAY,
MediaActionHandler.MEDIA_ACTION_STOP,
Constant Field Valuesstatic final int MEDIA_ACTION_REWIND
Suggested Usage: If the implementation is playing an item, or playback is paused, it should start rewinding the current item. If playback is stopped then this action should do nothing.
MediaActionHandler.MEDIA_ACTION_FAST_FORWARD,
Constant Field Valuesstatic final int MEDIA_ACTION_FAST_FORWARD
Suggested Usage: If the implementation is playing an item, or playback is paused, it should start fastforwarding the current item. If playback is stopped then this action should do nothing.
MediaActionHandler.MEDIA_ACTION_REWIND,
Constant Field Valuesstatic final int MEDIA_ACTION_CUSTOM_OFFSET
The code below demonstrates creating custom media actions using this constant.
public class MyMediaPlayer implements MediaActionHandler {
public static final int MEDIA_ACTION_CLOSE = MEDIA_ACTION_CUSTOM_OFFSET;
public static final int MEDIA_ACTION_OPEN = MEDIA_ACTION_CUSTOM_OFFSET + 1;
...
}
static final int SOURCE_INVALID
static final int SOURCE_BACKGROUND_KEY
static final int SOURCE_FOREGROUND_KEY
static final int SOURCE_BLUETOOTH_HEADSET
The context object of actions generated by this source will be instances of
BluetoothHeadsetMediaActionContext.
static final int SOURCE_WIRED_HEADSET
The context object of actions generated by this source will be instances of
WiredHeadsetMediaActionContext.
static final int SOURCE_CUSTOM_OFFSET
The code below demonstrates creating custom media action sources using this constant.
public class MyMediaPlayer implements MediaActionHandler {
public static final int SOURCE_SCREEN1 = SOURCE_CUSTOM_OFFSET;
public static final int SOURCE_SCREEN2 = SOURCE_CUSTOM_OFFSET + 1;
...
}
| Method Detail |
|---|
boolean mediaAction(int action,
int source,
Object context)
If the specified action is recognized then true should be returned to indicate that the action was consumed. Otherwise, if the action was not recognized, then false should be returned. Note that if the media action is recognized but has no meaning in the context when this method was invoked (eg. "volume up" action was received when volume is already at the maximum level) then this method should still consume the event.
action - the media action to handle; will be one of the MEDIA_ACTION_ constants defined
in this class or custom media actions whose values begin at
MediaActionHandler.MEDIA_ACTION_CUSTOM_OFFSET.source - an integer identifying the source of this action; will be one of the SOURCE_
constants defined in this class or a custom media action source whose values begin at
MediaActionHandler.SOURCE_CUSTOM_OFFSET.context - an object providing additional contextual information about the media action
to perform; may be null; the actual type that is provided depends both on the action and the
source of the action.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal