MultiScreenContext

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 MultiScreenContext

All Known Subinterfaces:
  MultiScreenConfigurableContext

    public interface MultiScreenContext

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

1. distinguishing between `HScreen` instances that are directly associated with a `VideoOutputPort` and those that are indirectly associated with a `VideoOutputPort` through a logical mapping process; i.e., discovering whether an `HScreen` is a display screen or a logical screen;
2. discovering the unique platform identifier of an `HScreen` instance's underlying resource;
3. discovering the category assigned to an `HScreen` within its containing `MultiScreenConfiguration`;
4. discovering the mapping of logical `HScreen`s to display `HScreen`s including the area (extent) on the display `HScreen` where the logical `HScreen` appears, its visibility, and its z-order;
5. discovering the z-order of `HScreenDevice`s within an `HScreen`;
6. discovering the set of `ServiceContext`s associated with an `HScreen`;
7. discovering the association of display `HScreen`s and corresponding `VideoOutputPort` instances;
8. discovering the set of `HScreenDevice`s whose generated audio constitute the set of audio sources of an `HScreen`;
9. discovering the current audio focus assignment of a display `HScreen`;
10. obtaining notification of changes in state of this `MultiScreenContext` or certain changes in the the `HScreen` instance that implements this interface;
11. obtaining notification of changes to the per-display multiscreen configuration of a display screen;
12. discovering the set of per-display multiscreen configurations that may be used with a display screen;
13. obtaining the currently active per-display multiscreen configuration of a display screen;

If an OCAP implementation does not support the OCAP Multiscreen Manager (MSM) Extension and does not otherwise support this interface, then an OCAP application MAY assume that the behavior of an `HScreen` is equivalent to an `HScreen` instance that does implement this interface, `MultiScreenContext`, whose methods would behave as follows:

- `getScreenType()` returns `SCREEN_TYPE_DISPLAY`;
- `getID()` returns a platform dependent (possibly empty) string;
- `getScreenCategory()` returns the string `"main"`;
- `getVisible()` returns `true`;
- `getZOrder()` returns `0`;
- `getZOrder(HScreenDevice device)` returns the array index of device in an array of `HScreenDevice` instances created by concatenating the ordered results of invoking on this `HScreen` instance the methods `HScreen.getHBackgroundDevices()`, then `HScreen.getHVideoDevices()`, then `HScreen.getHGraphicsDevices()`, or throws an `IllegalArgumentException` in case device is not present in this array;
- `getAudioSources()` returns an array of `HScreenDevice` instances created by concatenating the ordered results of invoking on this `HScreen` instance the methods `HScreen.getHBackgroundDevices()`, then `HScreen.getHVideoDevices()`, then `HScreen.getHGraphicsDevices()`;
- `getAudioFocus()` returns this `HScreen` instance;
- `getOutputPorts()` returns an array containing all `VideoOutputPort`s available on the platform;
- `getDisplayScreen()` returns this `HScreen` instance;
- `getDisplayArea()` returns `new HScreenRectangle(0,0,1,1)`;
- `getContexts()` returns an array containing all `ServiceContext`s that are accessible by the current application;

An MSM implementation SHALL support the `MultiScreenContext` interface on every `HScreen` instance.

Since:
  MSM I01
Author:
  Glenn Adams

Field Summary
`static int` | `SCREEN_TYPE_DISPLAY` If an `HScreen` is directly associated with a `VideoOutputPort` and the extent of the `HScreen` is mapped to the extent of the video raster produced from the `VideoOutputPort`, then the type of the `HScreen` is `SCREEN_TYPE_DISPLAY`, and is referred to as a display `HScreen`.
`static int` | `SCREEN_TYPE_LOGICAL` If an `HScreen` is not directly associated with a `VideoOutputPort` or the extent of the `HScreen` is mapped to a sub-region of the video raster produced from some `VideoOutputPort`, then the type of the `HScreen` is `SCREEN_TYPE_LOGICAL`, and is referred to as a logical `HScreen`.

Method Summary
`void` | `addMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)` Add a listener to be notified upon the occurence of multiscreen configuration events that apply to this screen in the case it is a display screen.
`void` | `addScreenContextListener(MultiScreenContextListener listener)` Add screen context listener.
`HScreen` | `getAudioFocus()` Obtain the audio focus screen.
`HScreenDevice[]` | `getAudioSources()` Obtain audio sources of this screen.
`HScreenRectangle` | `getDisplayArea()` Obtain area of the display screen to which this screen is mapped.
`HScreen` | `getDisplayScreen()` Obtain display screen with which this screen is associated.
`String` | `getID()` Obtain a platform dependent unique identifier for the underlying collection of screen resources denoted by this screen, where the scope for uniqueness is no smaller than the set of screens associated with the currently active per-platform multiscreen configuration and all active per-display multiscreen configurations.
`MultiScreenConfiguration` | `getMultiScreenConfiguration()` Obtain the currently active per-display multiscreen configuration for this display screen.
`MultiScreenConfiguration[]` | `getMultiScreenConfigurations()` Obtain set of all per-display multiscreen configurations currently associated with this display screen where the configuration type of any such multiscreen configuration SHALL NOT be `SCREEN_CONFIGURATION_DISPLAY`).
`MultiScreenConfiguration[]` | `getMultiScreenConfigurations(String screenConfigurationType)` Obtain per-display multiscreen configurations of a specific type associated with this display screen.
`VideoOutputPort[]` | `getOutputPorts()` Obtain video ports to which screen is mapped.
`String` | `getScreenCategory()` Obtain the screen category of this `HScreen` instance.
`int` | `getScreenType()` Obtain the type of this `HScreen`.
`ServiceContext[]` | `getServiceContexts()` Obtain service contexts associated with this screen.
`boolean` | `getVisible()` Obtain screen visibility.
`int` | `getZOrder()` Obtain screen z-order.
`int` | `getZOrder(HScreenDevice device)` Obtain screen device z-order within this screen.
`void` | `removeMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)` Remove a listener previously added to be notified upon the occurence of multiscreen configuration events.
`void` | `removeScreenContextListener(MultiScreenContextListener listener)` Remove screen context listener.

Field Detail

### SCREEN_TYPE_DISPLAY

    static final int SCREEN_TYPE_DISPLAY

  If an `HScreen` is directly associated with a `VideoOutputPort` and the extent of the `HScreen` is mapped to the extent of the video raster produced from the `VideoOutputPort`, then the type of the `HScreen` is `SCREEN_TYPE_DISPLAY`, and is referred to as a display `HScreen`.

  Since:
    MSM I01
  See Also:
    Constant Field Values

### SCREEN_TYPE_LOGICAL

    static final int SCREEN_TYPE_LOGICAL

  If an `HScreen` is not directly associated with a `VideoOutputPort` or the extent of the `HScreen` is mapped to a sub-region of the video raster produced from some `VideoOutputPort`, then the type of the `HScreen` is `SCREEN_TYPE_LOGICAL`, and is referred to as a logical `HScreen`. A logical `HScreen` MAY be associated with a display `HScreen`. If a logical `HScreen` is not associated with a display `HScreen`, then a visible or audible manifestation SHALL NOT be produced by any `ServiceContext` associated with the logical `HScreen`.

  Note: A logical `HScreen` that is not associated with a display `HScreen` may be decoding and using content for some purpose other than presentation, e.g., it may be recording the content from a `ServiceContext` for future presentation

  Since:
    MSM I01
  See Also:
    Constant Field Values

Method Detail

### getScreenType

    int getScreenType()

  Obtain the type of this `HScreen`.

  Returns:
    An integer value denoted by `SCREEN_TYPE_DISPLAY` or `SCREEN_TYPE_LOGICAL`.
  Since:
    MSM I01

### getID

    String getID()

  Obtain a platform dependent unique identifier for the underlying collection of screen resources denoted by this screen, where the scope for uniqueness is no smaller than the set of screens associated with the currently active per-platform multiscreen configuration and all active per-display multiscreen configurations. It is implementation dependent whether the scope for screen identifier uniqueness includes other, non-active multiscreen configurations or not.

  A screen identifier SHALL NOT be equal to any screen category returned by `getScreenCategory()`.

  If `S1` and `S2` are instances of `HScreen` in the context of the implemented scope of uniqueness and `MultiScreenManager.sameResources(S1,S2)` returns `false`, then `((MultiScreenContext)S1).getID()` and `((MultiScreenContext)S2).getID()` SHALL NOT return the same (equivalent) string; conversely, if `MultiScreenManager.sameResources(S1,S2)` returns `true`, then `((MultiScreenContext)S1).getID()` and `((MultiScreenContext)S2).getID()` SHALL return the same (equivalent) string.

  Returns:
    A string value denoting the collection of underlying resources this `HScreen` instance represents in the implemented scope of uniqueness.
  Since:
    MSM I01
  See Also:
    `HScreen`

### getScreenCategory

    String getScreenCategory()

  Obtain the screen category of this `HScreen` instance.

  Returns:
    A String that is either (1) an element of the following enumeration of constants defined by `MultiScreenConfiguration`: { `SCREEN_CATEGORY_DISPLAY`, `SCREEN_CATEGORY_MAIN`, `SCREEN_CATEGORY_PIP`, `SCREEN_CATEGORY_POP`, `SCREEN_CATEGORY_OVERLAY`, `SCREEN_CATEGORY_GENERAL` }, or (2) a string value that denotes a platform-dependent screen category and that starts with the prefix `"x-"`.
  Since:
    MSM I01

### getVisible

    boolean getVisible()

  Obtain screen visibility.

  Determine whether this `HScreen` is marked as visible for presentation on some display `HScreen`, where "visible" is defined as producing a raster signal to a `VideoOutputPort`, whether or not the `VideoOutputPort` is enabled or disabled. A display `HScreen` SHALL remain marked as visible. A logical `HScreen` MAY be visible or hidden (not visible).

  Returns:
    A boolean value indicating whether this `HScreen` is marked visible or not on some display `HScreen`.
  Since:
    MSM I01

### getZOrder

    int getZOrder()

  Obtain screen z-order.

  Determine the z-order of this `HScreen`. An display `HScreen` SHALL always return a z-order of zero. A logical `HScreen` MAY be assigned a z-order of 1 or greater, unless it is not associated with a display `HScreen`, in which case its z-order is -1.

  A greater z-order denotes a more front-most (top-most) order among a set of `HScreen` instances.

  Returns:
    A value indicating the z-order of this `HScreen` or `-1`. If this `HScreen` is a logical `HScreen` that is not associated with a display `HScreen`, then `-1` SHALL be returned.
  Since:
    MSM I01

### getZOrder

    int getZOrder(HScreenDevice device)
                  throws IllegalArgumentException

  Obtain screen device z-order within this screen.

  Determine the z-order of a specified `HScreenDevice` with an `HScreen` where the following constraints apply:

  - if an `HBackgroundDevice` is present in this screen, then the z-order of the rear-most (bottom-most) `HBackgroundDevice` is zero;
  - if no `HBackgroundDevice` is present in this screen and if an `HVideoDevice` is present in this screen, then the z-order of the rear-most (bottom-most) `HVideoDevice` is zero;
  - if no `HBackgroundDevice` and no `HVideoDevice` is present in this screen and if an `HGraphicsDevice` is present in this screen, then the z-order of the rear-most (bottom-most) `HGraphicsDevice` is zero;
  - the z-order of an `HVideoDevice` is greater than the z-order of any `HBackgroundDevice` in this screen;
  - the z-order of an `HGraphicsDevice` is greater than the z-order of any `HVideoDevice` in this screen;

  A greater z-order denotes a more front-most (top-most) order among a set of `HScreenDevice` instances within an `HScreen` instance.

  Each distinct set of underlying screen devices represented as an `HScreen` instance constitutes a distinct z-ordering; i.e., given multiple `HScreen` instances representing distinct underlying screens, the set of z-order values assigned to the underlying screen device resources of these screens may reuse the same z-order indices.

  Parameters:
    `device` - an `HScreenDevice` that is associated with this screen.
  Returns:
    A non-negative value indicating the z-order of the specified `HScreenDevice`.
  Throws:
    `IllegalArgumentException` - if device is not an `HScreenDevice` of this screen.
  Since:
    MSM I01

### getAudioSources

    HScreenDevice[] getAudioSources()

  Obtain audio sources of this screen.

  Obtain the set of `HScreenDevice` from which presented audio is selected (and mixed) for the purpose of audio presentation from this screen.

  The default set of audio sources of a screen consists of all `HScreenDevice` instances association with the screen.

  The order of entries in the array returned by this method is not defined by this specification and SHALL be considered implementation dependent.

  Returns:
    A reference to an (possibly empty) array of `HScreenDevice` instances, where each such instance contributes to a mixed, audio presentation from this screen, or, if this screen does not support mixed audio, then at most one entry will be present in the returned array.
  Since:
    MSM I01

### getAudioFocus

    HScreen getAudioFocus()

  Obtain the audio focus screen.

  The audio focus screen of this `HScreen` is determined according to the following ordered rules, where the first rule that applies is used and others are ignored:

  1. If this `HScreen` is a logical screen, then apply the following ordered sub-rules:
     1. If this logical `HScreen` is mapped to a display screen, then apply the following sub-rules:
        1. If this logical `HScreen` is currently assigned audio focus in the context of its display screen, then this logical `HScreen` is returned.
        2. Otherwise (not currently assigned audio focus in its display screen), `null` is returned.
     2. Otherwise (not mapped to a display screen), if this logical `HScreen` is directly mapped to a video output port, then this `HScreen` is returned.
     3. Otherwise (not mapped to a display screen and not directly mapped to a video output port), `null` is returned.
  2. Otherwise (this `HScreen` is a display screen), apply the following sub-rules:
     1. If some logical screen that is mapped to this display screen is assigned audio focus, then that logical `HScreen` is returned;
     2. Otherwise (no logical screen is mapped to this display screen or no logical screen mapped to this display screen is assigned audio focus), then return this display `HScreen`.

  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.

  Returns:
    an `HScreen` instance or `null` as described above.
  Since:
    MSM I01
  See Also:
    `MultiScreenConfigurableContext.assignAudioFocus()`

### getOutputPorts

    VideoOutputPort[] getOutputPorts()

  Obtain video ports to which screen is mapped.

  Obtain the set of `VideoOutputPort`s associated with this `HScreen`. If this `HScreen`'s type is `SCREEN_TYPE_DISPLAY`, then the `VideoOutputPort` instances associated with this display screen SHALL be returned. If this `HScreen`'s type is `SCREEN_TYPE_LOGICAL` and this `HScreen` is associated with a display `HScreen`, then the `VideoOutputPort` instances associated with that display `HScreen` SHALL be returned. If this `HScreen`'s type is `SCREEN_TYPE_LOGICAL` and this `HScreen` is not associated with a display `HScreen`, then an empty array SHALL be returned.

  Returns:
    A reference to an array of `VideoOutputPort` instances. If the returned array is empty, then this `HScreen` is not associated with any `VideoOutputPort`.
  Since:
    MSM I01

### getDisplayScreen

    HScreen getDisplayScreen()

  Obtain display screen with which this screen is associated.

  Obtain the display `HScreen` associated with this `HScreen`. If this `HScreen`'s type is `SCREEN_TYPE_DISPLAY`, then a reference to this `HScreen` SHALL be returned. If this `HScreen`'s type is `SCREEN_TYPE_LOGICAL` and this `HScreen` is associated with a display `HScreen`, then that display `HScreen` SHALL be returned. If this `HScreen`'s type is `SCREEN_TYPE_LOGICAL` and this `HScreen` is not associated with a display `HScreen`, then the value `null` SHALL be returned.

  Returns:
    A reference to a display `HScreen` instance or `null`. If `null`, then this `HScreen` is not associated with a display `HScreen`.
  Since:
    MSM I01

### getDisplayArea

    HScreenRectangle getDisplayArea()

  Obtain area of the display screen to which this screen is mapped.

  Obtain the area (extent) of this `HScreen`. If this `HScreen`'s type is `SCREEN_TYPE_DISPLAY`, then an `HScreenRectangle` whose value is equal to `HScreenRectangle(0,0,1,1)` SHALL be returned. If this `HScreen`'s type is `SCREEN_TYPE_LOGICAL` and this `HScreen` is associated with a display `HScreen`, then the area (extent) occupied by this logical `HScreen` on its associated display `HScreen` SHALL be returned. If this `HScreen`'s type is `SCREEN_TYPE_LOGICAL` and this `HScreen` is not associated with a display `HScreen`, then the value `null` SHALL be returned.

  Returns:
    A reference to an `HScreenRectangle` instance or `null`. If `null`, then this `HScreen` is not associated with a display `HScreen`.
  Since:
    MSM I01

### getServiceContexts

    ServiceContext[] getServiceContexts()

  Obtain service contexts associated with this screen.

  Obtain the set of `ServiceContext`s associated with this `HScreen` to which the calling application is granted access.

  Returns:
    A reference to an array of `ServiceContext` instances. If the returned array is empty, then this `HScreen` is not associated with any accessible `ServiceContext`.
  Since:
    MSM I01

### addScreenContextListener

    void addScreenContextListener(MultiScreenContextListener listener)

  Add screen context listener.

  Add a listener to be notified upon the occurence of screen context events. If a listener has previously been added and not subsequently removed, then an attempt to add it again SHALL NOT produce a side effect.

  Parameters:
    `listener` - a `MultiScreenContextListener` instance.
  Since:
    MSM I01

### removeScreenContextListener

    void removeScreenContextListener(MultiScreenContextListener listener)

  Remove screen context listener.

  Remove a listener previously addede to be notified upon the occurence of screen context events. If the specified listener is not currently registered as a listener, then an attempt to remove it SHALL NOT produce a side effect.

  Parameters:
    `listener` - a `MultiScreenContextListener` instance.
  Since:
    MSM I01

### addMultiScreenConfigurationListener

    void addMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
                                             throws IllegalStateException

  Add a listener to be notified upon the occurence of multiscreen configuration events that apply to this screen in the case it is a display screen. If a listener has previously been added and not subsequently removed, then an attempt to add it again SHALL NOT produce a side effect.

  Configuration events that apply to a display screen SHALL be restricted to those that affect the complement of logical screens associated with the display screen.

  If an event defined by `MultiScreenConfigurationEvent` is generated, then the MSM implementation SHALL notify each registered screen configuration listener accordingly.

  Parameters:
    `listener` - a `MultiScreenConfigurationListener` instance.
  Throws:
    `IllegalStateException` - if the type of this screen is not `SCREEN_TYPE_DISPLAY`.
  Since:
    MSM I01
  See Also:
    `MultiScreenConfigurationEvent`, `MultiScreenConfigurationListener`

### removeMultiScreenConfigurationListener

    void removeMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)

  Remove a listener previously added to be notified upon the occurence of multiscreen configuration events. If the specified listener is not currently registered as a listener, then an attempt to remove it SHALL NOT produce a side effect.

  Parameters:
    `listener` - a `MultiScreenConfigurationListener` instance.
  Since:
    MSM I01
  See Also:
    `MultiScreenConfigurationListener`

### getMultiScreenConfigurations

    MultiScreenConfiguration[] getMultiScreenConfigurations()
                                                            throws SecurityException

  Obtain set of all per-display multiscreen configurations currently associated with this display screen where the configuration type of any such multiscreen configuration SHALL NOT be `SCREEN_CONFIGURATION_DISPLAY`).

  Returns:
    A non-empty array of `MultiScreenConfiguration` instances.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.configuration")`.
  Since:
    MSM I01
  See Also:
    `MultiScreenConfiguration`, `MonitorAppPermission`

### getMultiScreenConfigurations

    MultiScreenConfiguration[] getMultiScreenConfigurations(String screenConfigurationType)
                                                            throws SecurityException,
                                                                   IllegalArgumentException

  Obtain per-display multiscreen configurations of a specific type associated with this display screen.

  Parameters:
    `screenConfigurationType` - (1) an element of the following enumeration of constants defined by `MultiScreenConfiguration`: { `SCREEN_CONFIGURATION_NON_PIP`, `SCREEN_CONFIGURATION_PIP`, `SCREEN_CONFIGURATION_POP`, `SCREEN_CONFIGURATION_GENERAL` }, or (2) some other platform-dependent value not pre-defined as a multiscreen configuration type.
  Returns:
    An array of `MultiScreenConfiguration` instances or `null`, depending on whether specified configuration type is supported or not.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.configuration")`.
    `IllegalArgumentException` - if `screenConfigurationType` is `SCREEN_CONFIGURATION_DISPLAY`, is not defined, or is otherwise unknown to the platform implemention.
  Since:
    MSM I01
  See Also:
    `MultiScreenConfiguration`, `MonitorAppPermission`

### getMultiScreenConfiguration

    MultiScreenConfiguration getMultiScreenConfiguration()
                                                         throws IllegalStateException

  Obtain the currently active per-display multiscreen configuration for this display screen.

  Returns:
    The currently active per-display `MultiScreenConfiguration` instance that applies to this display screen.
  Throws:
    `IllegalStateException` - if this `HScreen` is not a display screen.
  Since:
    MSM I01
  See Also:
    `MultiScreenConfiguration`

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

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