org.dvb.media
Interface ComponentBasedPlayerControl

All Superinterfaces:
javax.media.Control

public interface ComponentBasedPlayerControl
extends javax.media.Control

The presence of this Control on a Player indicates that the Player can be used as either a background Player or a component-based Player. Players for broadcast streaming formats that do not provide this control will always return null from their getVisualComponent() method.

A Player that provides this control must continue to provide an instance of it (not necessarily the same instance) after any transitions from background to component-based modes and vice-versa.


Method Summary
 boolean releaseVisualComponent()
          Transition the associated Player from a component-based Player to a background Player.
 void swapVideoComponent(javax.media.Player other)
          Swap the presentation of the video for this JMF player and another Player between a component and the background.
 
Methods inherited from interface javax.media.Control
getControlComponent
 

Method Detail

releaseVisualComponent

boolean releaseVisualComponent()
                               throws java.lang.IllegalStateException
Transition the associated Player from a component-based Player to a background Player. Also releases the ownership of the visual component to allow other applications to acquire it.

The calling application must own the visual component - i.e. it must have obtained a non-null visual component through Player.getVisualComponent() on the Player associated with this control.

If the application has called paint() on that visual component, then this method transitions the Player from a component-based Player to a background Player, and releases the visual component. Otherwise, the Player is still a background Player so this method merely releases the visual component.

If this call transitions the Player from a component-based Player to a background Player, then the video is intially sized and positioned as close to the last location of the visual component as possible, given the limitations exposed after the transition by org.dvb.media.BackgroundVideoPresentationControl .getClosestMatch() or (equivalently) javax.tv.media.AWTVideoSizeControl.checkSize().

After the transition, applications shall re-acquire the list of JMF controls for the player. It is implementation dependent whether any previous JMF controls are re-used. Applications shall not use any previous JMF controls which are not in the new list of JMF controls.

The application should ensure that the visual component is removed from the AWT hierarchy before making this call. After this call, interoperable applications should not make any calls to the visual component aquired before this call. However, such calls will not affect the Player in any way. (For example, calling paint() on that visual component will not cause the Player to become a component-based player). The appearence of the visual component if it is displayed after this call is implementation-dependant.

Future calls to Player.getVisualComponent() will return a visual component that is different from the visual component returned before this call.

Returns:
true iff the Player has changed from component-based to background mode.
Throws:
java.lang.IllegalStateException - If the calling application does not own the visual component.

swapVideoComponent

void swapVideoComponent(javax.media.Player other)
Swap the presentation of the video for this JMF player and another Player between a component and the background.

Parameters:
other - the other player to use in the swap
Throws:
java.lang.IllegalArgumentException - if both this player and the other player are background players or if both this player and the other player are component players or if the calling application does not have a reference to the java.awt.Component used in the swap or if either player is not presenting video
Since:
MHP 1.1.3