net.rim.device.api.lcdui.control
Interface MediaBehaviourControl

All Superinterfaces:
Control

public interface MediaBehaviourControl
extends Control

A control that allows MIDlets modify their global behaviour suitable for "media player" applications. When "media player" mode is enabled then the current Canvas will consume key presses of media keys and the MIDlet will be put in the stack of background media action handlers to be candidate to receive notifications of media key presses when in the background. By default, media player mode is not enabled.

Consuming Media Key Presses

When a MIDlet is the foreground application it receives notifications of all presses of media keys via the Canvas methods keyPressed(), keyReleased(), and keyRepeated(). This is true regardless of whether or not the MIDlet has "media player" mode enabled. When a MIDlet is not in media player mode then it is assumed that the presses of media keys are not used by the MIDlet and therefore are posted to background applications as well. However, if media player mode is enabled then the MIDlet will "consume" all presses of media keys, preventing them from being posted to background applications.

This logic exists because there is no way for a MIDlet to indicate whether or not a key press was "consumed" or not. Therefore, the framework will simply assume that the MIDlet did not consume the key press of a media key and post it to background applications. This behaviour allows a media player running in the background to be controlled via media keys when a MIDlet is in the foreground. Therefore, a MIDlet that behaves like a "media player" should enable media player mode so that it will consume media key presses.

Note that in BlackBerry OS versions before 5.0.0 the media keys were consumed by MIDlets, preventing background media players from responding to media key presses. Beginning in 5.0.0 media keys are not consumed by MIDlets unless media player mode is enabled.

Receiving Media Key Presses While In the Background

Another feature that is provided when a MIDlet enables media player mode is that it becomes candidate for receiving media key presses even when in the background. Non-MIDlets would do this by registering a MediaActionHandler via Application.addMediaActionHandler(MediaActionHandler), and that is still possible for a MIDlet to do. But, in order to avoid having to implement MediaActionHandler, a MIDlet with media player mode enabled will automatically have its current Canvas' keyPressed(), keyReleased(), and keyRepeated() methods invoked for media keys even when in the background, just as if it were in the foreground.

Note that if multiple applications are registered as background media key handlers then this MIDlet enters into contention with those other applications and is placed in the stack using the same algorithm as defined in MediaActionHandler.

Obtaining the Instance of MediaBehaviourControl

RIM's implementation of Display implements Controllable and therefore applications can cast the Display instance to Controllable and obtain the MediaBehaviourControl instance using the getControl(String) or getControls() methods defined in Controllable. An example is provided below.

 Controllable controllable = (Controllable) Display.getDisplay(this);
 String controlName = "net.rim.device.api.lcdui.control.MediaBehaviourControl";
 Control control = controllable.getControl(controlName);
 if (control instanceof MediaBehaviourControl) {
     ((MediaBehaviourControl) control).setMediaPlayerModeEnabled(true);
 }
 

Media Player Mode via JAD Attributes

If a MIDlet is installed via a JAD file, then media player mode can be enabled automatically by setting the attribute "RIM-MIDlet-MediaPlayerModeEnabled" to a non-zero value. If the attribute's value is "0" or is absent then media player mode will not be enabled by default. However, if the attribute is present and its value is a string that is not "0" then media player mode will be enabled by default. Enabling media player mode this way has the advantage that only standard APIs, and no RIM extension APIs, need be used.

Note that even if the attribute is present in the JAD, it only influences the initial state of media player mode, and media player mode can still be enabled or disabled at any time by invoking setMediaPlayerModeEnabled(boolean). For convenience, the attribute's name is available in the constant MediaBehaviourControl.JAD_ATTRIBUTE_ENABLED.

Since:
BlackBerry API 5.0.0

Field Summary
static String JAD_ATTRIBUTE_ENABLED
          The JAD attribute that can be used to enable or disable media player mode: "RIM-MIDlet-MediaPlayerModeEnabled".
 
Method Summary
 boolean isMediaPlayerModeEnabled()
          Returns whether or not media player mode is enabled in this MIDlet.
 void setMediaPlayerModeEnabled(boolean enabled)
          Enables or disables media player mode.
 



Field Detail

JAD_ATTRIBUTE_ENABLED

static final String JAD_ATTRIBUTE_ENABLED
The JAD attribute that can be used to enable or disable media player mode: "RIM-MIDlet-MediaPlayerModeEnabled".

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Method Detail

setMediaPlayerModeEnabled

void setMediaPlayerModeEnabled(boolean enabled)
Enables or disables media player mode.

Parameters:
enabled - if true then enable media player mode for this MIDlet; if false then disable media player mode for this MIDlet.
See Also:
MediaBehaviourControl.isMediaPlayerModeEnabled()
Since:
BlackBerry API 5.0.0

isMediaPlayerModeEnabled

boolean isMediaPlayerModeEnabled()
Returns whether or not media player mode is enabled in this MIDlet.

Returns:
true if media player mode is enabled in this MIDlet; false otherwise.
See Also:
MediaBehaviourControl.setMediaPlayerModeEnabled(boolean)
Since:
BlackBerry API 5.0.0





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