Commit a0db5fb0 authored by nshah's avatar nshah

Tagging OCAP MSM stubs used for 1.2.2 Release

parent 2248549c
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" path="src"/>
<classpathentry combineaccessrules="false" exported="true" kind="src" path="/ocap_api"/>
<classpathentry kind="output" path="bin"/>
</classpath>
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>ocap_msm</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.jdt.core.javanature</nature>
</natures>
</projectDescription>
#Fri Oct 19 13:37:09 MDT 2007
eclipse.preferences.version=1
org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5
org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
org.eclipse.jdt.core.compiler.compliance=1.5
org.eclipse.jdt.core.compiler.debug.lineNumber=generate
org.eclipse.jdt.core.compiler.debug.localVariable=generate
org.eclipse.jdt.core.compiler.debug.sourceFile=generate
org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
org.eclipse.jdt.core.compiler.source=1.5
#Fri Oct 19 13:37:09 MDT 2007
eclipse.preferences.version=1
internal.default.compliance=default
package org.ocap.ui;
import java.rmi.Remote;
import java.util.Dictionary;
import javax.tv.service.selection.ServiceContext;
import org.davic.resources.ResourceClient;
import org.davic.resources.ResourceProxy;
import org.havi.ui.HScreen;
import org.havi.ui.HScreenDevice;
import org.havi.ui.HScreenRectangle;
import org.ocap.hardware.VideoOutputPort;
import org.ocap.system.MonitorAppPermission;
/**
* <p>This interface provides a set of tools for accomplishing the
* following:</p>
*
* <ol>
* <li>modifying the mapping of logical <code>HScreen</code>s
* to display <code>HScreen</code>s including the area (extent) on the display
* <code>HScreen</code> where a logical <code>HScreen</code> appears, its
* visibility, and its z-order (among other <code>HScreen</code>s);</li>
* <li>modifying the z-order of <code>HScreenDevice</code>s within
* an <code>HScreen</code>;</li>
* <li>modifying the set of <code>ServiceContext</code>s
* associated with an <code>HScreen</code>;</li>
* <li>modifying the association of display
* <code>HScreen</code>s and corresponding <code>VideoOutputPort</code>
* instances;</li>
* <li>modifying the set of <code>HScreenDevice</code>s whose
* generated audio constitute the set of audio sources of an
* <code>HScreen</code>;</li>
* <li>modifying the current audio focus assignment of a display
* <code>HScreen</code>;</li>
* <li>reserving and releasing reservation of underlying screen and
* screen device resources;</li>
* <li>obtaining a reference to current resource client that has
* reserved screen and its underlying resources;</li>
* <li>establishing the currently active per-display multiscreen
* configuration of a display <code>HScreen</code>;</li>
* </ol>
*
* <p>If an <code>HScreen</code> instance may be exposed to an OCAP
* application and if that <code>HScreen</code> is configurable with
* respect to the functionality defined by this interface, then an
* MSM implementation SHALL support the <code>MultiScreenConfigurableContext</code>
* interface on every such <code>HScreen</code> instance.</p>
*
* <p>An MSM implementation MAY support this interface on an
* <code>HScreen</code> instance that is not configurable with respect
* to the functionality defined by this interface.</p>
*
* <p>A given implementation of this interface is not required to
* support any or all defined configuration changes, but MAY, due to
* hardware or other constraints, support only specific configuration
* changes. If an implementation of this interface does not support a
* specific configuration change, then an attempt to perform that
* change SHALL cause an <code>IllegalStateException</code> to be
* raised, as described under each method defined below.</p>
*
* @author Glenn Adams
* @since MSM I01
*
* @see MultiScreenContext
* @see org.davic.resources.ResourceProxy
**/
public interface MultiScreenConfigurableContext extends MultiScreenContext, ResourceProxy
{
/**
* Configurable parameter identifying configurability of audio
* source(s).
*
* <p>Configuration of the audio source(s) of a screen is accomplished
* by using the <code>addAudioSources(..)</code> and
* <code>removeAudioSources(..)</code> methods defined by this
* interface.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface supports configuration of its audio source(s), then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE)</code>
* SHALL return <code>true</code>.</p>
*
* <p>If
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE)</code>
* returns <code>true</code>, then
* <code>getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE)</code>
* SHALL return a value of type <code>HScreenDevice[]</code>, where
* each entry in the value array is an accessible screen device of
* this screen that can serve as an audio source for this
* screen.</p>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
* @see org.havi.ui.HScreenDevice
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE = 0;
/**
* Configurable parameter identifying configurability of audio
* focus.
*
* <p>Configuration of the audio focus of a screen is accomplished
* by using the <code>assignAudioFocus(..)</code> method defined by
* this interface.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface supports configuration of its audio source(s), then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS)</code>
* SHALL return <code>true</code>.</p>
*
* <p>If
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS)</code>
* returns <code>true</code>, then
* <code>getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS)</code>
* SHALL return a value of type <code>HScreen[]</code>, where each
* entry in the value array is an accessible screen that can serve
* as an audio focus screen.</p>
*
* <p>If this screen is a display screen, then the returned entries
* SHALL be restricted to those logical screens that are currently
* mapped to this display screen that can be assigned audio focus.
* Because a display screen can always be assigned audio focus
* directly (as opposed to assigning audio focus to some logical
* screen mapped to the display screen), the display screen is not
* itself included in the returned entries.</p>
*
* <p>If this screen is a logical screen and if this logical screen
* is mapped to a display screen and is capable of being assigned
* audio focus, then the returned array SHALL contain only this
* screen; otherwise, the returned array SHALL be empty.</p>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS = 1;
/**
* Configurable parameter identifying configurability of screen
* device z-order.
*
* <p>Configuration of device z-order of a screen is accomplished
* by using the <code>setZOrder(HScreenDevice[])</code> method
* defined by this interface.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface supports configuration of the z-order of its screen
* device(s), then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER)</code>
* SHALL return <code>true</code>.</p>
*
* <p>If
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER)</code>
* returns <code>true</code>, then
* <code>getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER)</code>
* SHALL return a value of type <code>HScreenDevice[][]</code>,
* where each entry in the value array is an array of screen devices
* whose order matches a supported z-ordering of those screen
* devices, where the first entry of such an array of screen devices
* is back-most in z-order (i.e., device z-order of zero).</p>
*
* <p><b>Example:</b></p>
*
* <p>The following assumptions apply:</p>
* <ol>
* <li>screen has one background device (B1), one video device (V1), and two graphics
* devices (G1 and G2);</li>
* <li>two orderings of graphics devices are supported:
* (1) B1&lt;V1&lt;G1&lt;G2 and (2) B1&lt;V1&lt;G2&lt;G1;</li>
* </ol>
*
* <pre>
* MultiScreenConfigurableContext msxx = (MultiScreenConfigurableContext) HScreen.getDefaultHScreen();
* Object[] values = msxx.getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER);
* ASSERT ( values != null );
* ASSERT ( values instanceof HScreenDevice[][] );
* ASSERT ( values.length == 2 );
* HScreenDevice[] order1 = (HScreenDevice[]) values[0];
* ASSERT ( order1 != null );
* ASSERT ( order1.length == 4 );
* ASSERT ( order1[0] instanceof HBackgroundDevice );
* ASSERT ( order1[1] instanceof HVideoDevice );
* ASSERT ( order1[2] instanceof HGraphicsDevice );
* ASSERT ( order1[2].getIDstring().equals ( "G1" ) );
* ASSERT ( order1[3] instanceof HGraphicsDevice );
* ASSERT ( order1[2].getIDstring().equals ( "G2" ) );
* HScreenDevice[] order2 = (HScreenDevice[]) values[1];
* ASSERT ( order2 != null );
* ASSERT ( order2.length == 4 );
* ASSERT ( order2[0] instanceof HBackgroundDevice );
* ASSERT ( order2[1] instanceof HVideoDevice );
* ASSERT ( order2[2] instanceof HGraphicsDevice );
* ASSERT ( order2[2].getIDstring().equals ( "G2" ) );
* ASSERT ( order2[3] instanceof HGraphicsDevice );
* ASSERT ( order2[2].getIDstring().equals ( "G1" ) );
* </pre>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
* @see org.havi.ui.HScreenDevice
* @see org.havi.ui.HBackgroundDevice
* @see org.havi.ui.HVideoDevice
* @see org.havi.ui.HGraphicsDevice
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER = 2;
/**
* Configurable parameter identifying configurability of screen's
* associated display area.
*
* <p>Configuration of the display area of a (logical) screen is accomplished
* by using the <code>setDisplayArea(HScreenRectangle)</code> method
* defined by this interface.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface is a display screen, then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA)</code>
* SHALL return <code>false</code>; otherwise, if this logical
* screen supports configuration of its display area, then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA)</code>
* SHALL return <code>true</code>.</p>
*
* <p>If
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA)</code>
* returns <code>true</code>, then
* <code>getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA)</code>
* SHALL return a value of type <code>HScreenRectangle[]</code>,
* where each entry in the value array is a supported display
* area.</p>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
* @see org.havi.ui.HScreenRectangle
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA = 3;
/**
* Configurable parameter identifying configurability of screen's
* associated display screen.
*
* <p>Configuration of the display screen of a (logical) screen is accomplished
* by using the <code>setDisplayScreen(HScreen)</code> method
* defined by this interface.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface is a display screen, then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN)</code>
* SHALL return <code>false</code>; otherwise, if this logical
* screen supports configuration of its display screen, then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN)</code>
* SHALL return <code>true</code>.</p>
*
* <p>If
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN)</code>
* returns <code>true</code>, then
* <code>getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN)</code>
* SHALL return a value of type <code>HScreen[]</code>,
* where each entry in the value array is an accessible display
* screen to which this logical screen MAY be mapped.</p>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN = 4;
/**
* Configurable parameter identifying configurability of screen's
* associated output port(s).
*
* <p>Configuration of the output port(s) of a screen is accomplished
* by using the <code>addOutputPorts(..)</code> and
* <code>removeOutputPorts(..)</code> methods defined by this
* interface.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface supports configuration of its video output port(s), then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT)</code>
* SHALL return <code>true</code>.</p>
*
* <p>If
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT)</code>
* returns <code>true</code>, then
* <code>getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT)</code>
* SHALL return a value of type <code>VideoOutputPort[]</code>, where
* each entry in the value array is an accessible video output port
* to which this screen may be directly mapped.</p>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
* @see org.ocap.hardware.VideoOutputPort
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT = 5;
/**
* Configurable parameter identifying configurability of screen's
* associated service context(s).
*
* <p>Configuration of the service context(s) of a screen is
* accomplished by using the <code>addServiceContexts(..)</code> and
* <code>removeServiceContexts(..)</code> methods defined by
* this interface, and by using the
* <code>swapServiceContexts(..)</code> and
* <code>moveServiceContexts(..)</code> methods defined by
* <code>MultiScreenManager</code>.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface supports configuration of its output port(s), then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT)</code>
* SHALL return <code>true</code>.</p>
*
* <p>If
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT)</code>
* returns <code>true</code>, then
* <code>getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT)</code>
* SHALL return a value of type <code>ServiceContext[]</code>, where
* each entry in the value array is an accessible service context
* that can be associated with this screen.</p>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
* @see javax.tv.service.selection.ServiceContext
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT = 6;
/**
* Configurable parameter identifying configurability of screen's
* visibility.
*
* <p>Configuration of the visibility of a screen is accomplished
* by using the <code>setVisible(boolean)</code> method
* defined by this interface.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface supports configuration of its visibility, then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY)</code>
* SHALL return <code>true</code>, but
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY)</code>
* SHALL return <code>false</code>, implying that if visibility is
* configurable, then a continuous parameter space (i.e., both
* <code>true</code> and <code>false</code>) applies.</p>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY = 7;
/**
* Configurable parameter identifying configurability of screen's
* z-order.
*
* <p>Configuration of the z-order of a screen is accomplished
* by using the <code>setZOrder(int)</code> method
* defined by this interface.</p>
*
* <p>If the <code>HScreen</code> instance referenced by this
* interface supports configuration of its z-order (with respect to
* other screens within its multiscreen configuration), then
* <code>isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER)</code>
* SHALL return <code>true</code>.</p>
*
* <p>If
* <code>hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER)</code>
* returns <code>true</code>, then
* <code>getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER)</code>
* SHALL return a value of type <code>Integer[]</code>,
* where each value entry <code><i>v</i></code> in the value array is such that
* <code><i>v</i>.intValue()</code> returns a supported z-order
* index for this screen in the context of this screen's
* multiscreen configuration.</p>
*
* @since MSM I01
*
* @see org.havi.ui.HScreen
**/
public static final int CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER = 8;
/**
* Determine if configurable parameter is supported as configurable
* (as opposed to fixed) by the platform implementation for some
* screen.
*
* @param parameter a configurable screen parameter enumeration
* value as defined above.
*
* @return If the platform implementation supports either
* continuous or discrete variation of the specified
* <code><i>parameter</i></code> on this screen, then returns <code>true</code>;
* otherwise, returns <code>false</code>.
*
* @since MSM I01
*/
public boolean isConfigurableParameter ( int parameter );
/**
* Determine if a supported configurable parameter has a discrete
* or continuously variable value space.
*
* <p>In the present context, a "continuously" configurable
* parameter means the platform supports or can approximate all
* values of the parameter's value type, while "discrete" means only
* certain, enumerable values of the parameter's value type may be
* used as reported by
* <code>getDiscreteParameterSpace(..)</code>.</p>
*
* @param parameter a configurable screen parameter enumeration
* value as defined above.
*
* @return If the platform implementation supports a discrete,
* (sub)set of values of of the value type space of the specified
* <code><i>parameter</i></code> on this screen, then returns <code>true</code>;
* otherwise, returns <code>false</code>, in which case all values
* of the value type space are supported (or approximated).
*
* @throws IllegalArgumentException if
* <code>isConfigurableParameter(<i>parameter</i>)</code> returns
* <code>false</code>.
*
* @since MSM I01
*/
public boolean hasDiscreteParameterSpace ( int parameter ) throws IllegalArgumentException;
/**
* Obtain the discrete, (sub)set of values of of the value type space
* of a configurable parameter.
*
* <p>The actual runtime type of the array and the array's elements
* returned by this method SHALL be as defined for the specified
* configurable parameter as documented by each configurable
* parameter's specification above.</p>
*
* <p>Unless indicated otherwise by the definition of a specific
* configurable parameter, the order of entries in the array
* returned by this method is not defined by this specification,
* and SHALL be considered implementation dependent by an
* interoperable application.</p>
*
* <p>A set of supported discrete parameters MAY change for a given
* screen and a given configurable parameter over the lifetime of a
* screen based upon the dynamic state of the screen's underlying
* resources; however, such a change, if it occurs, SHALL NOT occur
* outside the time interval between the completion of dispatching
* <code>MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGING</code>
* event and the completion of dispatching the corresponding
* <code>MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGED</code>
* event.</p>
*
* @param parameter a configurable screen parameter enumeration
* value as defined above.
*
* @return an array of object instances, each of
* which denote a discrete value of the specified parameter that is
* supported (or approximatable) by the platform.
*
* @throws IllegalArgumentException if
* <code>isConfigurableParameter(<i>parameter</i>)</code> or
* <code>hasDiscreteParameterSpace(<i>parameter</i>)</code>
* returns
* <code>false</code>.
*
* @since MSM I01
*/
public Object[] getDiscreteParameterSpace ( int parameter ) throws IllegalArgumentException;
/**
* Set screen visibility.
*
* <p>If this screen is a logical screen, then cause it to be marked
* as visible (if previously hidden) or hidden (if previously
* visible); otherwise, if this screen is a display screen, then
* cause all logical screens mapped to this display screen to be
* marked as visible (if previously hidden) or hidden (if previously
* visible).</p>
*
* @param visible a boolean value indicating whether this logical
* <code>HScreen</code> or the logical screens mapped to this
* display <code>HScreen</code> should be made visible or hidden
* (non-visible) on its associated display <code>HScreen</code>.
*
* @throws SecurityException if the calling thread has not been
* granted <code>MonitorAppPermission("multiscreen.context")</code>.
*
* @throws IllegalStateException if the visibility for this
* <code>HScreen</code> cannot be changed, e.g., if the platform
* uses a permanent visibility setting.
*
* @since MSM I01
**/
public void setVisible ( boolean visible ) throws SecurityException, IllegalStateException;
/**
* Set screen z-order.
*
* <p>Cause this logical <code>HScreen</code> to change its z-order
* among other logical <code>HScreen</code>s mapped to the same
* display <code>HScreen</code>.</p>
*
* @param order a positive integer value indicating the new z-order to
* assign to this logical <code>HScreen</code>.
*
* @throws SecurityException if the calling thread has not been
* granted <code>MonitorAppPermission("multiscreen.context")</code>.
*
* @throws IllegalStateException if this <code>HScreen</code>'s
* type is not <code>SCREEN_TYPE_LOGICAL</code> or if the z-order for
* this <code>HScreen</code> cannot be changed, e.g., if the platform uses a
* permanent z-order setting.
*
* @since MSM I01
**/
public void setZOrder ( int order ) throws SecurityException, IllegalStateException;
/**
* Set the screen device z-order within this screen for a
* set of screen devices.
*
* <p>Atomically set the z-order of the specified set of
* <code>HScreenDevice</code> within this screen where the following
* constraints apply:</p>
*
* <ul>
* <li>if an <code>HBackgroundDevice</code> is present in the
* specified set of devices, then it (1) precedes any
* <code>HVideoDevice</code> contained in the set of devices and (2)
* precedes any <code>HGraphicsDevice</code> contained in the set of
* devices;</li>
* <li>if an <code>HVideoDevice</code> is present in the specified
* set of devices, then it precedes any <code>HGraphicsDevice</code>
* contained in the set of devices;</li>
* </ul>
*
* <p>If no exception is thrown by this method, then the set of
* specified <code>HScreenDevice</code> instances will be ordered
* such that
* <code>MultiScreenContext.getZOrder(HScreenDevice)</code> when
* invoked on this screen with any of the specified devices will
* return a z-order index that preserves the relative order of the
* specified devices.</p>
*
* <p>If fewer than the entire set of <code>HScreenDevice</code>
* instances associated with this screen is provided in the
* <code><i>devices</i></code> argument, then the resulting relative order of
* unspecified devices with respect to specified devices is not
* defined, except that the constraints defined by
* <code>MultiScreenContext.getZOrder(HScreenDevice)</code> SHALL
* apply to the total ordering of devices in this screen after this
* method returns.</p>
*
* @param devices an ordered array of <code>HScreenDevice</code>
* instances that are associated with this screen.
*
* @throws SecurityException if the calling thread has not been
* granted <code>MonitorAppPermission("multiscreen.context")</code>.
*
* @throws IllegalArgumentException if <code><i>device</i></code> is not an
* <code>HScreenDevice</code> of this screen.
*
* @throws IllegalStateException if (1) the z-order for the specified
* <code>HScreenDevice</code> cannot be changed, e.g., if the
* platform uses a permanent z-order setting for screen devices in
* this screen, or (2) the order of specified devices does not
* permit the assignment of z-order indices that satisfies the
* above constraints.
*
* @since MSM I01
**/
public void setZOrder ( HScreenDevice[] devices ) throws SecurityException, IllegalArgumentException, IllegalStateException;
/**
* Add audio source(s) for this screen.
*
* <p>Add one or more <code>HScreenDevice</code> instances to the
* set of audio sources from which presented audio is selected (and
* mixed) for the purpose of audio presentation from this
* screen.</p>
*
* <p>If a specified audio source is already
* designated as an audio source for this screen, but
* <code><i>mixWithAudioFocus</i></code> differs from that specified when it was
* added as an audio source, then the new <code><i>mixWithAudioFocus</i></code>