net.rim.device.api.media
Interface MediaActionHandler

All Known Implementing Classes:
MediaKeyListener

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.

Implementation Details

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.

Media Actions

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.

Media Action Sources

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.

Media Action Context

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.

Media Actions from Foreground Key Presses

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 Stack of Media Action Handler Applications

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.

Media Actions from Background Key Presses

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.

Media Actions from Bluetooth and Wired Headsets

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.

See Also:
MediaKeyListener, Application.addMediaActionHandler(MediaActionHandler), KeyListener
Since:
BlackBerry API 5.0.0

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

MEDIA_ACTION_INVALID

static final int MEDIA_ACTION_INVALID
Invalid media action. This constant is defined for programming reasons, so that an integer variable can be assigned a value that does not map to any valid action, similar to "null" for reference types. This action should not be specified to any methods defined in this interface, as it has no meaning.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_PLAYPAUSE_TOGGLE

static final int MEDIA_ACTION_PLAYPAUSE_TOGGLE
Media action to switch between "play" and "pause" mode.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_PLAY, MediaActionHandler.MEDIA_ACTION_PAUSE, MediaActionHandler.MEDIA_ACTION_STOP, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_VOLUME_UP

static final int MEDIA_ACTION_VOLUME_UP
Media action to increase the volume.

See Also:
MediaActionHandler.MEDIA_ACTION_VOLUME_DOWN, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_VOLUME_DOWN

static final int MEDIA_ACTION_VOLUME_DOWN
Media action to decrease the volume.

See Also:
MediaActionHandler.MEDIA_ACTION_VOLUME_UP, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_NEXT_TRACK

static final int MEDIA_ACTION_NEXT_TRACK
Media action to skip to the 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.

See Also:
MediaActionHandler.MEDIA_ACTION_PREV_TRACK, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_PREV_TRACK

static final 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.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_NEXT_TRACK, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_PLAY

static final int MEDIA_ACTION_PLAY
Media action to begin playback.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_PLAYPAUSE_TOGGLE, MediaActionHandler.MEDIA_ACTION_PAUSE, MediaActionHandler.MEDIA_ACTION_UNPAUSE, MediaActionHandler.MEDIA_ACTION_STOP, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_PAUSE

static final int MEDIA_ACTION_PAUSE
Media action to pause playback.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_UNPAUSE, MediaActionHandler.MEDIA_ACTION_PLAYPAUSE_TOGGLE, MediaActionHandler.MEDIA_ACTION_PLAY, MediaActionHandler.MEDIA_ACTION_STOP, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_MUTE_TOGGLE

static final int MEDIA_ACTION_MUTE_TOGGLE
Media action to toggle muting of the playback.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_MUTE, MediaActionHandler.MEDIA_ACTION_UNMUTE, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_MUTE

static final int MEDIA_ACTION_MUTE
Media action to mute the audio of playback.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_MUTE_TOGGLE, MediaActionHandler.MEDIA_ACTION_UNMUTE, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_UNMUTE

static final int MEDIA_ACTION_UNMUTE
Media action to unmute the audio of playback.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_MUTE_TOGGLE, MediaActionHandler.MEDIA_ACTION_MUTE, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_STOP

static final int MEDIA_ACTION_STOP
Media action to stop the playback.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_PLAYPAUSE_TOGGLE, MediaActionHandler.MEDIA_ACTION_PLAY, MediaActionHandler.MEDIA_ACTION_PAUSE, MediaActionHandler.MEDIA_ACTION_UNPAUSE, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_UNPAUSE

static final int MEDIA_ACTION_UNPAUSE
Media action to un-pause playback.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_PAUSE, MediaActionHandler.MEDIA_ACTION_PLAYPAUSE_TOGGLE, MediaActionHandler.MEDIA_ACTION_PLAY, MediaActionHandler.MEDIA_ACTION_STOP, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_REWIND

static final int MEDIA_ACTION_REWIND
Media action to rewind the current track.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_FAST_FORWARD, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_FAST_FORWARD

static final int MEDIA_ACTION_FAST_FORWARD
Media action to fast forward the current track.

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.

See Also:
MediaActionHandler.MEDIA_ACTION_REWIND, Constant Field Values
Since:
BlackBerry API 5.0.0

MEDIA_ACTION_CUSTOM_OFFSET

static final int MEDIA_ACTION_CUSTOM_OFFSET
The offset for custom media actions. If an implementation wishes to extend the list of media actions then this constant's value should be used as the minimum value for those custom actions. Doing so ensures that if actions are added to this interface in the future their integer values will not conflict with those of the custom actions.

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;

     ...

 }
 

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

SOURCE_INVALID

static final int SOURCE_INVALID
Invalid media action source. This constant is defined for programming reasons, so that an integer variable can be assigned a value that does not map to any valid source, similar to "null" for reference types.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

SOURCE_BACKGROUND_KEY

static final 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. This is the source that is specified to a MediaActionHandler registered via Application.addMediaActionHandler(MediaActionHandler) for key presses.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

SOURCE_FOREGROUND_KEY

static final 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. This is the default source that is specified to MediaKeyListener.mediaAction().

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

SOURCE_BLUETOOTH_HEADSET

static final 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.

The context object of actions generated by this source will be instances of BluetoothHeadsetMediaActionContext.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

SOURCE_WIRED_HEADSET

static final 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.

The context object of actions generated by this source will be instances of WiredHeadsetMediaActionContext.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

SOURCE_CUSTOM_OFFSET

static final int SOURCE_CUSTOM_OFFSET
The offset for custom media action sources. If an implementation wishes to extend the list of media action sources then this constant's value should be used as the minimum value for those custom sources. Doing so ensures that if sources are added to this interface in the future their integer values will not conflict with those of the custom actions.

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;

     ...

 }
 

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Method Detail

mediaAction

boolean mediaAction(int action,
                    int source,
                    Object context)
Invoked to handle a media action.

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.

Parameters:
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.
Returns:
true if the media action was recognized to indicate that it was consumed; false otherwise.
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.