MultiScreenConfigurableContext

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.ocap.ui
Interface MultiScreenConfigurableContext

All Superinterfaces:
  MultiScreenContext, ResourceProxy

    public interface MultiScreenConfigurableContext

extends MultiScreenContext, ResourceProxy

This interface provides a set of tools for accomplishing the following:

1. modifying the mapping of logical `HScreen`s to display `HScreen`s including the area (extent) on the display `HScreen` where a logical `HScreen` appears, its visibility, and its z-order (among other `HScreen`s);
2. modifying the z-order of `HScreenDevice`s within an `HScreen`;
3. modifying the set of `ServiceContext`s associated with an `HScreen`;
4. modifying the association of display `HScreen`s and corresponding `VideoOutputPort` instances;
5. modifying the set of `HScreenDevice`s whose generated audio constitute the set of audio sources of an `HScreen`;
6. modifying the current audio focus assignment of a display `HScreen`;
7. reserving and releasing reservation of underlying screen and screen device resources;
8. obtaining a reference to current resource client that has reserved screen and its underlying resources;
9. establishing the currently active per-display multiscreen configuration of a display `HScreen`;

If an `HScreen` instance may be exposed to an OCAP application and if that `HScreen` is configurable with respect to the functionality defined by this interface, then an MSM implementation SHALL support the `MultiScreenConfigurableContext` interface on every such `HScreen` instance.

An MSM implementation MAY support this interface on an `HScreen` instance that is not configurable with respect to the functionality defined by this interface.

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 `IllegalStateException` to be raised, as described under each method defined below.

Since:
  MSM I01
Author:
  Glenn Adams
See Also:
  `MultiScreenContext`, `ResourceProxy`

Field Summary
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS` Configurable parameter identifying configurability of audio focus.
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE` Configurable parameter identifying configurability of audio source(s).
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER` Configurable parameter identifying configurability of screen device z-order.
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA` Configurable parameter identifying configurability of screen's associated display area.
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN` Configurable parameter identifying configurability of screen's associated display screen.
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT` Configurable parameter identifying configurability of screen's associated output port(s).
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT` Configurable parameter identifying configurability of screen's associated service context(s).
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY` Configurable parameter identifying configurability of screen's visibility.
`static int` | `CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER` Configurable parameter identifying configurability of screen's z-order.

Fields inherited from interface org.ocap.ui.MultiScreenContext
`SCREEN_TYPE_DISPLAY, SCREEN_TYPE_LOGICAL`

Method Summary
`void` | `addAudioSources(HScreenDevice[] devices, boolean mixWithAudioFocus)` Add audio source(s) for this screen.
`void` | `addOutputPorts(VideoOutputPort[] ports, boolean removeExisting)` Add video output port(s) to which screen is mapped.
`void` | `addServiceContexts(ServiceContext[] contexts, boolean associateDefaultDevices)` Add service context(s) to this screen.
`void` | `assignAudioFocus()` Assign audio focus to this screen.
`boolean` | `checkServiceContextCompatibility(ServiceContext context)` Test compatibility of service context with screen.
`ResourceClient` | `getClient()` Obtain the resource client that currently holds the reservation on the underlying screen and screen resources associated with this `HScreen` instance.
`Object[]` | `getDiscreteParameterSpace(int parameter)` Obtain the discrete, (sub)set of values of of the value type space of a configurable parameter.
`boolean` | `hasDiscreteParameterSpace(int parameter)` Determine if a supported configurable parameter has a discrete or continuously variable value space.
`boolean` | `isConfigurableParameter(int parameter)` Determine if configurable parameter is supported as configurable (as opposed to fixed) by the platform implementation for some screen.
`void` | `releaseScreen()` Atomically release underlying resources of screen.
`void` | `removeAudioSources(HScreenDevice[] devices)` Remove audio source(s) for this screen.
`void` | `removeOutputPorts(VideoOutputPort[] ports)` Remove video output port(s) to which screen is mapped.
`void` | `removeServiceContexts(ServiceContext[] contexts)` Remove service context(s) from screen.
`void` | `requestMultiScreenConfigurationChange(MultiScreenConfiguration configuration, Dictionary serviceContextAssociations)` Request that the currently active multiscreen configuration for this display screen be changed.
`boolean` | `reserveScreen(ResourceClient client, Object requestData)` Atomically reserve underlying resources of this screen.
`void` | `setDisplayArea(HScreenRectangle rect)` Set area of display screen to which logical screen is mapped.
`void` | `setDisplayScreen(HScreen screen)` Associate logical screen with display screen.
`void` | `setMultiScreenConfiguration(MultiScreenConfiguration configuration, Dictionary serviceContextAssociations)` Set currently active multiscreen configuration for this display screen (i.e., choose among the set of subsets of logical screens that may be associated with this display screen at a given time).
`void` | `setVisible(boolean visible)` Set screen visibility.
`void` | `setZOrder(HScreenDevice[] devices)` Set the screen device z-order within this screen for a set of screen devices.
`void` | `setZOrder(int order)` Set screen z-order.

Methods inherited from interface org.ocap.ui.MultiScreenContext
`addMultiScreenConfigurationListener, addScreenContextListener, getAudioFocus, getAudioSources, getDisplayArea, getDisplayScreen, getID, getMultiScreenConfiguration, getMultiScreenConfigurations, getMultiScreenConfigurations, getOutputPorts, getScreenCategory, getScreenType, getServiceContexts, getVisible, getZOrder, getZOrder, removeMultiScreenConfigurationListener, removeScreenContextListener`

Field Detail

### CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE

    static final int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE

  Configurable parameter identifying configurability of audio source(s).

  Configuration of the audio source(s) of a screen is accomplished by using the `addAudioSources(..)` and `removeAudioSources(..)` methods defined by this interface.

  If the `HScreen` instance referenced by this interface supports configuration of its audio source(s), then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE)` SHALL return `true`.

  If `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE)` returns `true`, then `getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE)` SHALL return a value of type `HScreenDevice[]`, 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.

  Since:
    MSM I01
  See Also:
    `HScreen`, `HScreenDevice`, Constant Field Values

### CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS

    static final int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS

  Configurable parameter identifying configurability of audio focus.

  Configuration of the audio focus of a screen is accomplished by using the `assignAudioFocus(..)` method defined by this interface.

  If the `HScreen` instance referenced by this interface supports configuration of its audio source(s), then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS)` SHALL return `true`.

  If `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS)` returns `true`, then `getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS)` SHALL return a value of type `HScreen[]`, where each entry in the value array is an accessible screen that can serve as an audio focus screen.

  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.

  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.

  Since:
    MSM I01
  See Also:
    `HScreen`, Constant Field Values

### CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER

    static final int CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER

  Configurable parameter identifying configurability of screen device z-order.

  Configuration of device z-order of a screen is accomplished by using the `setZOrder(HScreenDevice[])` method defined by this interface.

  If the `HScreen` instance referenced by this interface supports configuration of the z-order of its screen device(s), then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER)` SHALL return `true`.

  If `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER)` returns `true`, then `getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER)` SHALL return a value of type `HScreenDevice[][]`, 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).

  Example:

  The following assumptions apply:

  1. screen has one background device (B1), one video device (V1), and two graphics devices (G1 and G2);
  2. two orderings of graphics devices are supported: (1) B1<V1<G1<G2 and (2) B1<V1<G2<G1;

       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" ) );

  Since:
    MSM I01
  See Also:
    `HScreen`, `HScreenDevice`, `HBackgroundDevice`, `HVideoDevice`, `HGraphicsDevice`, Constant Field Values

### CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA

    static final int CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA

  Configurable parameter identifying configurability of screen's associated display area.

  Configuration of the display area of a (logical) screen is accomplished by using the `setDisplayArea(HScreenRectangle)` method defined by this interface.

  If the `HScreen` instance referenced by this interface is a display screen, then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA)` SHALL return `false`; otherwise, if this logical screen supports configuration of its display area, then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA)` SHALL return `true`.

  If `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA)` returns `true`, then `getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA)` SHALL return a value of type `HScreenRectangle[]`, where each entry in the value array is a supported display area.

  Since:
    MSM I01
  See Also:
    `HScreen`, `HScreenRectangle`, Constant Field Values

### CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN

    static final int CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN

  Configurable parameter identifying configurability of screen's associated display screen.

  Configuration of the display screen of a (logical) screen is accomplished by using the `setDisplayScreen(HScreen)` method defined by this interface.

  If the `HScreen` instance referenced by this interface is a display screen, then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN)` SHALL return `false`; otherwise, if this logical screen supports configuration of its display screen, then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN)` SHALL return `true`.

  If `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN)` returns `true`, then `getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN)` SHALL return a value of type `HScreen[]`, where each entry in the value array is an accessible display screen to which this logical screen MAY be mapped.

  Since:
    MSM I01
  See Also:
    `HScreen`, Constant Field Values

### CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT

    static final int CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT

  Configurable parameter identifying configurability of screen's associated output port(s).

  Configuration of the output port(s) of a screen is accomplished by using the `addOutputPorts(..)` and `removeOutputPorts(..)` methods defined by this interface.

  If the `HScreen` instance referenced by this interface supports configuration of its video output port(s), then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT)` SHALL return `true`.

  If `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT)` returns `true`, then `getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT)` SHALL return a value of type `VideoOutputPort[]`, where each entry in the value array is an accessible video output port to which this screen may be directly mapped.

  Since:
    MSM I01
  See Also:
    `HScreen`, `VideoOutputPort`, Constant Field Values

### CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT

    static final int CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT

  Configurable parameter identifying configurability of screen's associated service context(s).

  Configuration of the service context(s) of a screen is accomplished by using the `addServiceContexts(..)` and `removeServiceContexts(..)` methods defined by this interface, and by using the `swapServiceContexts(..)` and `moveServiceContexts(..)` methods defined by `MultiScreenManager`.

  If the `HScreen` instance referenced by this interface supports configuration of its output port(s), then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT)` SHALL return `true`.

  If `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT)` returns `true`, then `getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT)` SHALL return a value of type `ServiceContext[]`, where each entry in the value array is an accessible service context that can be associated with this screen.

  Since:
    MSM I01
  See Also:
    `HScreen`, `ServiceContext`, Constant Field Values

### CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY

    static final int CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY

  Configurable parameter identifying configurability of screen's visibility.

  Configuration of the visibility of a screen is accomplished by using the `setVisible(boolean)` method defined by this interface.

  If the `HScreen` instance referenced by this interface supports configuration of its visibility, then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY)` SHALL return `true`, but `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY)` SHALL return `false`, implying that if visibility is configurable, then a continuous parameter space (i.e., both `true` and `false`) applies.

  Since:
    MSM I01
  See Also:
    `HScreen`, Constant Field Values

### CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER

    static final int CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER

  Configurable parameter identifying configurability of screen's z-order.

  Configuration of the z-order of a screen is accomplished by using the `setZOrder(int)` method defined by this interface.

  If the `HScreen` instance referenced by this interface supports configuration of its z-order (with respect to other screens within its multiscreen configuration), then `isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER)` SHALL return `true`.

  If `hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER)` returns `true`, then `getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER)` SHALL return a value of type `Integer[]`, where each value entry `v` in the value array is such that `v.intValue()` returns a supported z-order index for this screen in the context of this screen's multiscreen configuration.

  Since:
    MSM I01
  See Also:
    `HScreen`, Constant Field Values

Method Detail

### isConfigurableParameter

    boolean isConfigurableParameter(int parameter)

  Determine if configurable parameter is supported as configurable (as opposed to fixed) by the platform implementation for some screen.

  Parameters:
    `parameter` - a configurable screen parameter enumeration value as defined above.
  Returns:
    If the platform implementation supports either continuous or discrete variation of the specified `parameter` on this screen, then returns `true`; otherwise, returns `false`.
  Since:
    MSM I01

### hasDiscreteParameterSpace

    boolean hasDiscreteParameterSpace(int parameter)
                                      throws IllegalArgumentException

  Determine if a supported configurable parameter has a discrete or continuously variable value space.

  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 `getDiscreteParameterSpace(..)`.

  Parameters:
    `parameter` - a configurable screen parameter enumeration value as defined above.
  Returns:
    If the platform implementation supports a discrete, (sub)set of values of of the value type space of the specified `parameter` on this screen, then returns `true`; otherwise, returns `false`, in which case all values of the value type space are supported (or approximated).
  Throws:
    `IllegalArgumentException` - if `isConfigurableParameter(parameter)` returns `false`.
  Since:
    MSM I01

### getDiscreteParameterSpace

    Object[] getDiscreteParameterSpace(int parameter)
                                       throws IllegalArgumentException

  Obtain the discrete, (sub)set of values of of the value type space of a configurable parameter.

  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.

  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.

  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 `MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGING` event and the completion of dispatching the corresponding `MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGED` event.

  Parameters:
    `parameter` - a configurable screen parameter enumeration value as defined above.
  Returns:
    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 `isConfigurableParameter(parameter)` or `hasDiscreteParameterSpace(parameter)` returns `false`.
  Since:
    MSM I01

### setVisible

    void setVisible(boolean visible)
                    throws SecurityException,
                           IllegalStateException

  Set screen visibility.

  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).

  Parameters:
    `visible` - a boolean value indicating whether this logical `HScreen` or the logical screens mapped to this display `HScreen` should be made visible or hidden (non-visible) on its associated display `HScreen`.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalStateException` - if the visibility for this `HScreen` cannot be changed, e.g., if the platform uses a permanent visibility setting.
  Since:
    MSM I01

### setZOrder

    void setZOrder(int order)
                   throws SecurityException,
                          IllegalStateException

  Set screen z-order.

  Cause this logical `HScreen` to change its z-order among other logical `HScreen`s mapped to the same display `HScreen`.

  Parameters:
    `order` - a positive integer value indicating the new z-order to assign to this logical `HScreen`.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalStateException` - if this `HScreen`'s type is not `SCREEN_TYPE_LOGICAL` or if the z-order for this `HScreen` cannot be changed, e.g., if the platform uses a permanent z-order setting.
  Since:
    MSM I01

### setZOrder

    void setZOrder(HScreenDevice[] devices)
                   throws SecurityException,
                          IllegalArgumentException,
                          IllegalStateException

  Set the screen device z-order within this screen for a set of screen devices.

  Atomically set the z-order of the specified set of `HScreenDevice` within this screen where the following constraints apply:

  - if an `HBackgroundDevice` is present in the specified set of devices, then it (1) precedes any `HVideoDevice` contained in the set of devices and (2) precedes any `HGraphicsDevice` contained in the set of devices;
  - if an `HVideoDevice` is present in the specified set of devices, then it precedes any `HGraphicsDevice` contained in the set of devices;

  If no exception is thrown by this method, then the set of specified `HScreenDevice` instances will be ordered such that `MultiScreenContext.getZOrder(HScreenDevice)` 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.

  If fewer than the entire set of `HScreenDevice` instances associated with this screen is provided in the `devices` argument, then the resulting relative order of unspecified devices with respect to specified devices is not defined, except that the constraints defined by `MultiScreenContext.getZOrder(HScreenDevice)` SHALL apply to the total ordering of devices in this screen after this method returns.

  Parameters:
    `devices` - an ordered array of `HScreenDevice` instances that are associated with this screen.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalArgumentException` - if `device` is not an `HScreenDevice` of this screen.
    `IllegalStateException` - if (1) the z-order for the specified `HScreenDevice` 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

### addAudioSources

    void addAudioSources(HScreenDevice[] devices,
                         boolean mixWithAudioFocus)
                         throws SecurityException,
                                IllegalArgumentException,
                                IllegalStateException

  Add audio source(s) for this screen.

  Add one or more `HScreenDevice` instances to the set of audio sources from which presented audio is selected (and mixed) for the purpose of audio presentation from this screen.

  If a specified audio source is already designated as an audio source for this screen, but `mixWithAudioFocus` differs from that specified when it was added as an audio source, then the new `mixWithAudioFocus` value applies.

  Parameters:
    `devices` - a non-empty array of `HScreenDevice` instances, where each such instance contributes to a mixed, audio presentation from this screen.
    `mixWithAudioFocus` - if `true`, then the specified screen devices contribute (mix) audio to (with) any audio output associated with any video output port with which this screen is associated (directly or indirectly) regardless of whether or not this screen is assigned audio focus; if `false`, then they contribute audio only when this screen is assigned audio focus.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalArgumentException` - if `devices` is not a non-empty array or some entry of `devices` is not an `HScreenDevice` of this screen.
    `IllegalStateException` - if (1) the audio sources for this `HScreen` cannot be changed, e.g., if the platform uses a permanent audio source setting for screen devices in this screen, or (2) if multiple audio sources are specified and audio mixing is not supported.
  Since:
    MSM I01

### removeAudioSources

    void removeAudioSources(HScreenDevice[] devices)
                            throws SecurityException,
                                   IllegalArgumentException,
                                   IllegalStateException

  Remove audio source(s) for this screen.

  Removes all or some non-empy set of specific `HScreenDevice` instances from the set of audio sources of this `HScreen`. If `devices` is `null`, then all audio sources are removed.

  Parameters:
    `devices` - either `null` or a non-empty set of `HScreenDevice` instances.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalArgumentException` - if `devices` is not `null` and some `HScreenDevice` entry is not associated with this `HScreen` instance.
    `IllegalStateException` - if a specified `HScreenDevice` used as an audio source for this `HScreen` cannot be changed, e.g., if the platform uses a permanent association of audio sources with the specified `HScreenDevice`.
  Since:
    MSM I01

### assignAudioFocus

    void assignAudioFocus()
                          throws SecurityException,
                                 IllegalStateException

  Assign audio focus to this screen.

  At any given time, a display screen SHALL assign audio focus to itself or or exactly one logical screen that maps to it (the display screen). When audio focus is (newly) assigned to a logical screen of a display screen and that logical screen does not currently have audio focus assigned to it, then audio focus SHALL be removed from any other logical screen that is mapped to that display screen and assigned instead to the newly assigned logical screen.

  If no logical screen is mapped to a given display screen or no logical screen mapped to a given display screen is assigned audio focus, then the display screen SHALL assign itself audio focus (by default). Audio focus MAY be explicitly assigned to a display screen by using this method on a display screen instance.

  The audio focus screen of a display screen is the screen whose currently selected audio sources are assigned to be rendered on all (implied) audio presentation devices of all video output ports to which the display screen is mapped. If the screen to which audio focus is assigned has no audio source, i.e., has an empty set of audio sources, then audio (as produced by or potentially produced by the OCAP platform) SHALL NOT be rendered by any (implied) audio presentation device of all video output ports to which the display screen is mapped.

  Note: Each distinct display screen may have a distinct logical screen to which audio focus is assigned for the purpose of rendering audio of the display screen (and its collection of mapped logical screens).

  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalStateException` - if audio focus cannot be assigned to this `HScreen` or the current audio focus cannot be changed.
  Since:
    MSM I01

### addOutputPorts

    void addOutputPorts(VideoOutputPort[] ports,
                        boolean removeExisting)
                        throws SecurityException,
                               IllegalStateException

  Add video output port(s) to which screen is mapped.

  If this `HScreen` is a logical screen rather than a display screen, then it SHALL be considered to function as equivalent to a display screen for the purpose of mapping to the specified video output port(s); i.e., the logical screen is treated as if it were a main display screen on its own accord.

  Parameters:
    `ports` - a non-empty array of `VideoOutputPort` instances.
    `removeExisting` - if `true`, then remove association with existing screen (if such association exists) before adding to new screen;
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalStateException` - if (1) the specified `VideoOutputPort` is already associated with a different `HScreen` and `removeExisting` is not `true`, (2) this `HScreen` cannot be mapped to some specified `VideoOutputPort` due to some platform specific hardware constraint, or (3) the set of `VideoOutputPort` instances to which this `HScreen` is mapped cannot be changed, e.g., if the platform uses a permanent association with a specific set of `VideoOutputPort` instances.
  Since:
    MSM I01

### removeOutputPorts

    void removeOutputPorts(VideoOutputPort[] ports)
                           throws SecurityException,
                                  IllegalArgumentException,
                                  IllegalStateException

  Remove video output port(s) to which screen is mapped.

  Removes all or some non-empty set of specific `VideoOutputPort` instances from the set of video output ports to which this `HScreen` is mapped. If `ports` is `null`, then all video output ports associations are removed.

  Parameters:
    `ports` - either `null` or a non-empty array of `VideoOutputPort` instances.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalArgumentException` - if `ports` is not `null` and some `VideoOutputPort` entry is not associated with this `HScreen` instance.
    `IllegalStateException` - if a specified `VideoOutputPort` for this `HScreen` cannot be changed, e.g., if the platform uses a permanent association with the specified `VideoOutputPort`.
  Since:
    MSM I01

### setDisplayScreen

    void setDisplayScreen(HScreen screen)
                          throws SecurityException,
                                 IllegalStateException

  Associate logical screen with display screen.

  Associates this logical `HScreen` with a display `HScreen`.

  Parameters:
    `screen` - a display `HScreen` instance or `null`. If `null`, and if this method executes without an exception, then upon return, this logical `HScreen` is no longer associated with a display `HScreen`.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalStateException` - if (1) this `HScreen`'s type is not `SCREEN_TYPE_LOGICAL`, (2) the specified `screen` is not `null` and its screen type is not `SCREEN_TYPE_DISPLAY`, or (3) the display `HScreen` associated with this logical `HScreen` cannot be changed, e.g., if the platform uses a permanent association with a specific display `HScreen`.
  Since:
    MSM I01

### setDisplayArea

    void setDisplayArea(HScreenRectangle rect)
                        throws SecurityException,
                               IllegalStateException

  Set area of display screen to which logical screen is mapped.

  Associates this logical `HScreen` with an area (extent) of its associated display `HScreen`.

  Parameters:
    `rect` - an `HScreenRectangle` instance specifying the area on the display `HScreen` associated with this logical `HScreen` that SHALL correspond to the extent of this logical `HScreen`.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalStateException` - if (1) this `HScreen`'s type is not `SCREEN_TYPE_LOGICAL` or (2) the area of the display `HScreen` associated with this logical `HScreen` cannot be changed, e.g., if the platform uses a permanent association with a specific area of the associated display `HScreen`.
  Since:
    MSM I01

### checkServiceContextCompatibility

    boolean checkServiceContextCompatibility(ServiceContext context)
                                             throws SecurityException,
                                                    IllegalArgumentException

  Test compatibility of service context with screen.

  Determine if application may assign `ServiceContext` to this `HScreen` and if the specified `ServiceContext` is compatible with presentation on this `HScreen`.

  Parameters:
    `context` - a valid `ServiceContext` instance.
  Returns:
    A boolean value indicating if the specified `ServiceContext` instance can be assigned to this `HScreen`. If it can be assigned, `true` is returned; otherwise, `false` is returned.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalArgumentException` - if the specified `ServiceContext` is not valid.
  Since:
    MSM I01

### addServiceContexts

    void addServiceContexts(ServiceContext[] contexts,
                            boolean associateDefaultDevices)
                            throws SecurityException,
                                   IllegalStateException

  Add service context(s) to this screen.

  Add one or more `ServiceContext` instances to the set of service contexts associated with this `HScreen` in order to permit background, video, and graphics content from these `ServiceContext` instances to be presented on the `HScreen`'s respective screen devices.

  If a specified service context is already associated with the underlying screen represented by this interface, then that service context is not multiply associated with this screen, but the existing association remains intact; that is, a given service context SHALL be associated with a given (underlying) screen either once or not at all.

  If more than one non-abstract service context is associated with a given screen, and if multiple video sources from the background based players of these multiple non-abstract service contexts are associated with a given `HVideoDevice` instance of the given screen, then the background based player from these multiple service contexts whose video content is to be displayed is determined according to the following ordered rules:

  1. If the owning application of one of the associated non-abstract service contexts holds a reservation on a given `HVideoDevice` of the screen, then background based player content from that service context is designated for presentation on that video device;
  2. Otherwise, the background based player of the associated non-abstract service context whose application is assigned the highest priority is designated for presentation on that video device;

  If, after applying the above rules, multiple background based players of a given application are designated for presentation on a video device, then the player that was most recently started is given priority for video presentation.

  Parameters:
    `contexts` - a non-empty array of `ServiceContext` instances.
    `associateDefaultDevices` - if `true`, then associate default screen devices of this screen with all `ServiceMediaHandler` instances currently associated with the specified `ServiceContext` instances; otherwise, if `false`, then do not perform this association with default screen devices.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalStateException` - if some specified `ServiceContext` for this `HScreen` cannot be changed, e.g., if the platform uses a permanent association with a specific `ServiceContext`.
  Since:
    MSM I01

### removeServiceContexts

    void removeServiceContexts(ServiceContext[] contexts)
                               throws SecurityException,
                                      IllegalArgumentException,
                                      IllegalStateException

  Remove service context(s) from screen.

  Remove all or some non-empty set of specific `ServiceContext` instances from the set of service contexts associated with this `HScreen`. If `contexts` is `null`, then all service contexts are removed.

  Parameters:
    `contexts` - either `null` or a non-empty array of `ServiceContext` instances.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.context")`.
    `IllegalArgumentException` - if `contexts` is not `null` and some `ServiceContext` entry is not associated with this `HScreen` instance.
    `IllegalStateException` - if a specified `ServiceContext` cannot be changed, e.g., if the platform uses a permanent association with a specified `ServiceContext`.
  Since:
    MSM I01

### setMultiScreenConfiguration

    void setMultiScreenConfiguration(MultiScreenConfiguration configuration,
                                     Dictionary serviceContextAssociations)
                                     throws SecurityException,
                                            IllegalArgumentException,
                                            IllegalStateException

  Set currently active multiscreen configuration for this display screen (i.e., choose among the set of subsets of logical screens that may be associated with this display screen at a given time).

  If the specified `configuration` is the current configuration for this display screen, then, unless `SecurityException` applies, return from this method without producing any side effect.

  If the specified `configuration` is not the current configuration for this display screen and if `SecurityException`, `IllegalStateException`, and `IllegalStateException` do not apply, then perform the synchronous display multiscreen configuration change processing defined in the OCAP Multiscreen Manager (MSM) Extension specification.

  If a `serviceContextAssociations` argument is specified (i.e., not `null`), then any `ServiceContext` instance that is accessible to the invoking application SHALL be associated with either no screen or the applicable screen(s) in the specified (new) multiscreen configuration. If no association matches some accessible `ServiceContext`, if some accessible `ServiceContext` instance is not present in the specified associations, or if it is present but no such applicable screen exists in the new multiscreen configuration, then the `ServiceContext` instance SHALL be associated with the default service context association screen of the specified multiscreen configuration, i.e., the screen returned by `configuration.getDefaultServiceContextScreen()`.

  For the purpose of matching accessible `ServiceContext` instances whose references appear as keys in a specified `serviceContextAssociations` dictionary, the virtual method `equals(Object)` on these keys SHALL be used, in which case it is assumed that this method behaves identically to the default implementation of `Object.equals(Object)`.

  Note: In the context of a given application instance, the MSM host implementation should maintain a one-to-one relationship between `ServiceContext` instances exposed to that application and collections of underyling service context resources. If the MSM host implementation fails to maintain this relationship, then when consulting a `serviceContextAssociations` dictionary, the MSM implemenation may consider two distinct collections of underlying service context resources to be the same service context, e.g., if at different times, a single `ServiceContext` instance references distinct underlying collections of resources, or may consider a single collection of underlying service context resources to be two distinct service contexts, e.g., if at a given time, two distinct `ServiceContext` instances reference the same underlying collection of resources.

  The state of the decoder format conversion (DFC) component of a video pipeline being used to process video associated with a service context that is implicitly swapped or moved between screens by this method SHALL NOT be affected by performance of this method.

  Parameters:
    `configuration` - a `MultiScreenConfiguration` instance to become the currently active per-display multiscreen configuration for this display screen.
    `serviceContextAssociations` - if not `null`, then a `Dictionary` instance whose keys are `ServiceContext` instances and whose values are `String` instances, where the string values are defined as follows: (1) if the string value is `"-"`, then no screen applies (in which case a matching service context is not associated with any screen after the configuration change), (2) otherwise, if the string value is `"*"`, then all screens of the new screen configuration apply, (3) otherwise, if the string value is a screen identifier as returned by `MultiScreenContext.getID()`, then that screen applies, (4) otherwise, if the string value is a screen category as returned by `MultiScreenContext.getScreenCategory()`, then any screen of the new configuration with that category applies, (5) otherwise, if the string value is a semicolon separated list of screen identifiers, then each screen of the new configuration with a matching identifier applies, (6) otherwise, if the string value is a semicolon separated list of screen categories, then each screen of the new configuration with a matching category applies, (7) otherwise, if the string value is a semicolon separated list of screen identifiers or screen categories, then each screen of the new configuration with a matching identifier or category applies, (8) otherwise, the default service context association screen of the new configfuration applies.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.configuration")`.
    `IllegalArgumentException` - if `configuration` is not one of this (display) screen's multiscreen configurations as would be returned by `MultiScreenContext.getMultiScreenConfigurations()`.
    `IllegalStateException` - if this screen is not a display screen or if the MSM implementation (1) does not permit activation of the specified multiscreen configuration, (2) if this method was previously called and the change processing steps are not yet complete, or (3) if activation is not otherwise permitted at the time of method invocation.
  Since:
    MSM I01
  See Also:
    `MultiScreenConfiguration`, `MonitorAppPermission`

### requestMultiScreenConfigurationChange

    void requestMultiScreenConfigurationChange(MultiScreenConfiguration configuration,
                                               Dictionary serviceContextAssociations)
                                               throws SecurityException,
                                                      IllegalArgumentException,
                                                      IllegalStateException

  Request that the currently active multiscreen configuration for this display screen be changed.

  If the specified `configuration` is the current configuration for this display screen, then, unless `SecurityException` applies, return from this method without producing any side effect.

  If the specified `configuration` is not the current display configuration and if `SecurityException`, `IllegalArgumentException`, and `IllegalStateException` do not apply, then initiate an asynchronous change to the current multiscreen configuration, where the semantics of `setMultiScreenConfiguration()` apply except that this method SHALL return immediately after `MultiScreenConfiguration.MULTI_SCREEN_CONFIGURATION_CHANGING` is generated (but before it is dispatched).

  Parameters:
    `configuration` - a `MultiScreenConfiguration` instance to become the currently active screen configuration.
    `serviceContextAssociations` - either `null` or a `Dictionary` instance whose keys are `ServiceContext` instances and whose values are `String` instances, with semantics as defined by `setMultiScreenConfiguration(..)` above.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.configuration")`.
    `IllegalArgumentException` - if `configuration` is not one of this (display) screen's multiscreen configurations as would be returned by `MultiScreenContext.getMultiScreenConfigurations()`.
    `IllegalStateException` - if this screen is not a display screen or (1) if the MSM implementation does not permit activation of the specified multiscreen configuration, (2) if this method was previously called and the change processing steps are not yet complete, or (3) if activation is not otherwise permitted at the time of method invocation.
  Since:
    MSM I01
  See Also:
    `MultiScreenConfiguration`, `MonitorAppPermission`

### getClient

    ResourceClient getClient()

  Obtain the resource client that currently holds the reservation on the underlying screen and screen resources associated with this `HScreen` instance.

  Specified by:
    `getClient` in interface `ResourceProxy`
  Returns:
    a `ResourceClient` instance or `null` if the underlying screen and screen resources associated with this `HScreen` are not reserved.
  Since:
    MSM I01

### reserveScreen

    boolean reserveScreen(ResourceClient client,
                          Object requestData)

  Atomically reserve underlying resources of this screen.

  Reserving a screen SHALL be considered equivalent to reserving all `HScreenDevice` instances associated with the screen, except that when the screen is reserved using this method, individual `HScreenDevice` instances SHALL not be released without first releasing all `HScreenDevice` instances and all underlying screen resources of this screen.

  If when reserving a screen, some `HScreenDevice` of the screen is already reserved by another application, then that reservation must be successfully released (by the MSM implementation) prior to granting reservation to the screen; and, if it is not or cannot be released, then an attempt to reserve the screen SHALL fail (i.e., this method returns `false`).

  If when reserving a screen, some `HScreenDevice` of the screen is already reserved by the reserving application, then that reservation SHALL be implicitly subsumed by the successful reservation of the entire screen.

  If an attempt to reserve a screen using this method succeeds, i.e., returns `true`, then the `getClient()` method of all `HScreenDevice` instances of the screen SHALL return the same value as the `getClient()` method defined by this interface (as implemented by the concrete implementation of `HScreen`).

  If this screen was previously unreserved and invocation of this method results in it becoming reserved, then, prior to returning from this method, a `MultiScreenResourceEvent.MULTI_SCREEN_RESOURCE_SCREEN_RESERVED` event SHALL be generated.

  If the calling application already holds a reservation on this screen and if the specified `client` and `requestData` arguments are identical to those specified when the calling application was previously granted the reservation, then this method SHALL have no side effect and return `true`. However, if the calling application already holds a reservation on this screen but either the specified `client` or `requestData` argument differs from those specified when the calling application was previously granted the reservation, then (1) the specified `client` and `requestData` SHALL replace those previously specified, (2) the calling application SHALL retain the reservation, and (3) this method SHALL return `true`.

  Parameters:
    `client` - a `ResourceClient` instance.
    `requestData` - either `null` or an Object instance that implements the `java.rmi.Remote` interface.
  Returns:
    `true` if underlying resources of screen were successfully reserved, otherwise `false`.
  Since:
    MSM I01
  See Also:
    `Remote`

### releaseScreen

    void releaseScreen()

  Atomically release underlying resources of screen.

  If the calling application does not hold a reservation on this screen, then this method SHALL have no side effect.

  If this screen was previously reserved and invocation of this method results in it being no longer reserved (i.e., becoming unreserved), then, prior to returning from this method, a `MultiScreenResourceEvent.MULTI_SCREEN_RESOURCE_SCREEN_RELEASED` event SHALL be generated.

  Since:
    MSM I01

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD