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

## org.ocap.ui
Interface MultiScreenConfiguration

    public interface MultiScreenConfiguration

The `MultiScreenConfiguration` interface, implemented by an OCAP host platform, provides information on a discrete screen configuration as well as a mechanism for monitoring changes to the screen configuration.

An MSM implementation SHALL support at least one multiscreen configuration whose configuration type is `SCREEN_CONFIGURATION_DISPLAY`.

An MSM implementation SHALL support at least one multiscreen configuration whose configuration type is `SCREEN_CONFIGURATION_NON_PIP`.

If an MSM implementation implements PIP functionality and permits the presentation of a PIP screen during OCAP operation, then the MSM implementation SHALL support the multiscreen configuration `SCREEN_CONFIGURATION_PIP`.

If an MSM implementation implements POP functionality and permits the presentation of a POP screen during OCAP operation, then the MSM implementation SHALL support the multiscreen configuration `SCREEN_CONFIGURATION_POP`.

If an MSM implementation implements PIP, POP, or OVERLAY functionality in a discrete configuration not explicitly specified below by a non-general multiscreen configuration, then the MSM implementation SHALL support one or more multiscreen configurations of configuration type `SCREEN_CONFIGURATION_GENERAL` that represent each such multiscreen configuration.

Since:
  MSM I01
Author:
  Glenn Adams

Field Summary
`static String` | `SCREEN_CATEGORY_DISPLAY` If a display `HScreen` instance is characterized as a non-main screen, then its category is `SCREEN_CATEGORY_DISPLAY`.
`static String` | `SCREEN_CATEGORY_GENERAL` If a logical `HScreen` instance is capable of being configured (e.g., in its size, position, or z-order) such that it may operate in a mode that would have suggested assignment of two or more of the other screen categories, then its category MAY be `SCREEN_CATEGORY_GENERAL`.
`static String` | `SCREEN_CATEGORY_MAIN` If a display or logical `HScreen` instance is characterized as a main screen, then its category is `SCREEN_CATEGORY_MAIN`.
`static String` | `SCREEN_CATEGORY_NONE` If an `HScreen` instance is not associated with any other more specific category, then its category is `SCREEN_CATEGORY_NONE`.
`static String` | `SCREEN_CATEGORY_OVERLAY` If a logical `HScreen` instance is characterized as an overlay screen, then its category is `SCREEN_CATEGORY_OVERLAY`.
`static String` | `SCREEN_CATEGORY_PIP` If a logical `HScreen` instance is characterized as a picture-in-picture (PIP) screen, then its category is `SCREEN_CATEGORY_PIP`.
`static String` | `SCREEN_CATEGORY_POP` If a logical `HScreen` instance is characterized as a picture-outside-picture (POP) screen, then its category is `SCREEN_CATEGORY_POP`.
`static String` | `SCREEN_CONFIGURATION_DISPLAY` If a `MultiScreenConfiguration` is associated with one or more display screens and is a candidate for being used as a per-platform multiscreen configuration, then its configuration type is `SCREEN_CONFIGURATION_DISPLAY`.
`static String` | `SCREEN_CONFIGURATION_GENERAL` If a `MultiScreenConfiguration` cannot be categorized as one of the other predefined screen configuration types, then its configuration type is `SCREEN_CONFIGURATION_GENERAL`.
`static String` | `SCREEN_CONFIGURATION_NON_PIP` If a `MultiScreenConfiguration` is associated with exactly one screen whose category is `SCREEN_CATEGORY_MAIN`, then its configuration type is `SCREEN_CONFIGURATION_NON_PIP`.
`static String` | `SCREEN_CONFIGURATION_PIP` If a `MultiScreenConfiguration` is (1) associated with one logical screen with default z-order of zero mapped to the entire area of a single display screen, and (2) associated with one or more non-intersecting logical screens with default z-order of one mapped to the same display screen, then its configuration type is `SCREEN_CONFIGURATION_PIP`.
`static String` | `SCREEN_CONFIGURATION_POP` If a `MultiScreenConfiguration` is associated with two or more non-intersecting logical screens with default z-order of zero whose default display areas (in union) tile the entire area of a single display screen, then its configuration type is `SCREEN_CONFIGURATION_POP`.

Method Summary
`String` | `getConfigurationType()` Gets the screen configuration type of this configuration.
`HScreen` | `getDefaultServiceContextScreen()` Obtain the default service context association screen of this configuration.
`HScreen[]` | `getScreens()` Gets the set of accessible screens associated with this configuration.
`HScreen[]` | `getScreens(String category)` Obtain all accessible screens with a given category.
`boolean` | `hasOverlayScreen()` Determine if the set of screens associated with this configuration includes an overlay screen, i.e., a screen whose category is `SCREEN_CATEGORY_OVERLAY`.
`boolean` | `isScreenInConfiguration(HScreen screen)` Determine if the underlying resources of a specified screen is represented by an `HScreen` instance included in the set of screens associated with this configuration.
`void` | `setDefaultServiceContextScreen(HScreen screen)` Set the default service context association screen of this configuration.

Field Detail

### SCREEN_CONFIGURATION_DISPLAY

    static final String SCREEN_CONFIGURATION_DISPLAY

  If a `MultiScreenConfiguration` is associated with one or more display screens and is a candidate for being used as a per-platform multiscreen configuration, then its configuration type is `SCREEN_CONFIGURATION_DISPLAY`.

  The initial default screen of a `SCREEN_CONFIGURATION_DISPLAY` configuration SHALL be the first screen returned by `getScreens(SCREEN_CATEGORY_MAIN)`, or, if there is no such categorized screen in the configuration, then the first screen returned by `getScreens()`.

  Since:
    MSM I01
  See Also:
    Constant Field Values

### SCREEN_CONFIGURATION_NON_PIP

    static final String SCREEN_CONFIGURATION_NON_PIP

  If a `MultiScreenConfiguration` is associated with exactly one screen whose category is `SCREEN_CATEGORY_MAIN`, then its configuration type is `SCREEN_CONFIGURATION_NON_PIP`.

  The initial default screen of a `SCREEN_CONFIGURATION_NON_PIP` configuration SHALL be the first screen returned by `getScreens(SCREEN_CATEGORY_MAIN)`.

  A `MultiScreenConfiguration` instance that is categorized as having a `SCREEN_CONFIGURATION_NON_PIP` configuration type SHALL NOT contain more than one display screen.

  Since:
    MSM I01
  See Also:
    Constant Field Values

### SCREEN_CONFIGURATION_PIP

    static final String SCREEN_CONFIGURATION_PIP

  If a `MultiScreenConfiguration` is (1) associated with one logical screen with default z-order of zero mapped to the entire area of a single display screen, and (2) associated with one or more non-intersecting logical screens with default z-order of one mapped to the same display screen, then its configuration type is `SCREEN_CONFIGURATION_PIP`.

  The initial default screen of a `SCREEN_CONFIGURATION_PIP` configuration SHALL be the first screen returned by `getScreens(SCREEN_CATEGORY_MAIN)`, or, if there is no such categorized screen in the configuration, then the first screen returned by `getScreens()`.

  A `MultiScreenConfiguration` instance that is categorized as having a `SCREEN_CONFIGURATION_PIP` configuration type SHALL NOT contain more than one display screen.

  Since:
    MSM I01
  See Also:
    Constant Field Values

### SCREEN_CONFIGURATION_POP

    static final String SCREEN_CONFIGURATION_POP

  If a `MultiScreenConfiguration` is associated with two or more non-intersecting logical screens with default z-order of zero whose default display areas (in union) tile the entire area of a single display screen, then its configuration type is `SCREEN_CONFIGURATION_POP`.

  The initial default screen of a `SCREEN_CONFIGURATION_POP` configuration SHALL be the first screen returned by `getScreens(SCREEN_CATEGORY_POP)`, or, if there is no such categorized screen in the configuration, then the first screen returned by `getScreens()`.

  A `MultiScreenConfiguration` instance that is categorized as having a `SCREEN_CONFIGURATION_POP` configuration type SHALL NOT contain more than one display screen.

  Since:
    MSM I01
  See Also:
    Constant Field Values

### SCREEN_CONFIGURATION_GENERAL

    static final String SCREEN_CONFIGURATION_GENERAL

  If a `MultiScreenConfiguration` cannot be categorized as one of the other predefined screen configuration types, then its configuration type is `SCREEN_CONFIGURATION_GENERAL`.

  The initial default screen of a `SCREEN_CONFIGURATION_GENERAL` configuration SHALL be the first screen returned by `getScreens(SCREEN_CATEGORY_MAIN)`, or, if there is no such categorized screen in the configuration, then the first screen returned by `getScreens()`.

  A `MultiScreenConfiguration` instance that is categorized as having a `SCREEN_CONFIGURATION_GENERAL` configuration type SHALL NOT contain more than one display screen.

  Since:
    MSM I01
  See Also:
    Constant Field Values

### SCREEN_CATEGORY_NONE

    static final String SCREEN_CATEGORY_NONE

  If an `HScreen` instance is not associated with any other more specific category, then its category is `SCREEN_CATEGORY_NONE`.

  A `MultiScreenConfiguration` instance that is categorized as having a `SCREEN_CONFIGURATION_NONE` configuration type SHALL NOT contain more than one display screen.

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

### SCREEN_CATEGORY_DISPLAY

    static final String SCREEN_CATEGORY_DISPLAY

  If a display `HScreen` instance is characterized as a non-main screen, then its category is `SCREEN_CATEGORY_DISPLAY`. A display screen assigned this category SHALL NOT be populated by an `HBackgroundDevice` or an `HVideoDevice`, but MAY be populated by one or more `HGraphicsDevice` instances that serve as overlays.

  A display `HScreen` instance that is categorized as `SCREEN_CATEGORY_DISPLAY` has the exceptional property that its `HGraphicsDevice` instances, if any exist, SHALL overlay all logical screens mapped to the display screen. This property SHALL hold even though `MultiScreenContext.getZOrder()` returns `0` for any display screen.

  Note: The exceptional property described above is intended to support (1) legacy device scenarios where a closed caption overlay appears over all other content, and (2) configurations where, rather than treating an overlay screen as a separate logical screen, an overlay screen is considered as an integral `HGraphicsDevice` of the display screen.

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

### SCREEN_CATEGORY_MAIN

    static final String SCREEN_CATEGORY_MAIN

  If a display or logical `HScreen` instance is characterized as a main screen, then its category is `SCREEN_CATEGORY_MAIN`. A logical screen assigned this category SHALL be mapped to the full area of some display screen and SHALL be assigned a default z-order of 0.

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

### SCREEN_CATEGORY_PIP

    static final String SCREEN_CATEGORY_PIP

  If a logical `HScreen` instance is characterized as a picture-in-picture (PIP) screen, then its category is `SCREEN_CATEGORY_PIP`. A logical screen assigned this category SHALL NOT be mapped to the full area of some display screen; SHALL NOT be assigned a screen z-order of 0; and SHALL co-exist in a configuration to which some screen is assigned the category `SCREEN_CATEGORY_MAIN`.

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

### SCREEN_CATEGORY_POP

    static final String SCREEN_CATEGORY_POP

  If a logical `HScreen` instance is characterized as a picture-outside-picture (POP) screen, then its category is `SCREEN_CATEGORY_POP`. A logical screen assigned this category SHALL NOT be mapped to the full area of some display screen; SHALL NOT co-exist in a configuration to which some screen is assigned the category `SCREEN_CATEGORY_MAIN`; and SHALL co-exist in a configuration to which some other screen is assigned the category `SCREEN_CATEGORY_POP`.

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

### SCREEN_CATEGORY_OVERLAY

    static final String SCREEN_CATEGORY_OVERLAY

  If a logical `HScreen` instance is characterized as an overlay screen, then its category is `SCREEN_CATEGORY_OVERLAY`. A logical screen assigned this category SHALL be mapped to the full area of some display screen; SHALL be assigned a default z-order greater than any screen associated with one of the following categories: `SCREEN_CATEGORY_MAIN`, `SCREEN_CATEGORY_PIP`, and `SCREEN_CATEGORY_POP`; and SHALL NOT contain a background or an explicit video plane (`HVideoDevice`).

  Notwithstanding the above, an overlay screen MAY make use of the resources of an implied video plane (`HVideoDevice`) for the purpose of presenting component based video in (one of) its graphics plane(s).

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

### SCREEN_CATEGORY_GENERAL

    static final String SCREEN_CATEGORY_GENERAL

  If a logical `HScreen` instance is capable of being configured (e.g., in its size, position, or z-order) such that it may operate in a mode that would have suggested assignment of two or more of the other screen categories, then its category MAY be `SCREEN_CATEGORY_GENERAL`. A logical screen assigned this category SHALL NOT be constrained in size, position, z-order, or other configurable properties except to the extent that the terminal device places intrinsic limitations on one (or more) configurable properties.

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

Method Detail

### getConfigurationType

    String getConfigurationType()

  Gets the screen configuration type of this configuration. If more than one non-general configuration type may apply or if the configuration type is unknown or cannot be determined, then the value `SCREEN_CONFIGURATION_GENERAL` SHALL be returned.

  Returns:
    A String that is either (1) an element of the enumeration { `SCREEN_CONFIGURATION_DISPLAY`, `SCREEN_CONFIGURATION_NON_PIP`, `SCREEN_CONFIGURATION_PIP`, `SCREEN_CONFIGURATION_POP`, `SCREEN_CONFIGURATION_GENERAL` }, or (2) a string value that denotes a platform-dependent configuration type and that starts with the prefix `"x-"`.
  Since:
    MSM I01

### getScreens

    HScreen[] getScreens()

  Gets the set of accessible screens associated with this configuration.

  The underlying resources of a given `HScreen` instance returned by this method MAY be shared with an `HScreen` instance included in another multiscreen configuration; however, those shared resources SHALL be active in no more than one multiscreen configuration at a given time. The order of entries in the returned array of `HScreen` instances is implementation dependent.

  Given the values of any two distinct entries of the returned array, `S1` and `S2`, and given the singleton instance of the `MultiScreenManager`, `MSM`, then the following constraints apply during the interval between the time when this method returns and the time when a `MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGING` event is generated and dispatched:

  - `MSM.isEmptyScreen(S1)` SHALL be `false`;
  - `MSM.isEmptyScreen(S2)` SHALL be `false`;
  - `MSM.sameResources(S1,S2)` SHALL be `false`;

  If invoked by an application that does not have `MonitorAppPermission("multiscreen.configuration")` then the screens of this configuration that are not associated with a `ServiceContext` instance accessible by the application SHALL NOT be returned; otherwise, all accessible screens of this configuration SHALL be returned.

  Over the course of an application's lifecycle, and except as constrained below, an MSM implementation MAY add screens to or remove screens from a multiscreen configuration, in which case it SHALL generate a `MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_SCREEN_ADDED` or `MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_SCREEN_REMOVED` event, respectively.

  A screen SHALL NOT be added to or removed from a multiscreen configuration that is the currently active per-platform multiscreen configuration or some currently active per-display multiscreen configuration.

  Note: The MSM implementation must wait until a multiscreen configuration is no longer the currently active multiscreen configuration in order to add or remove screens from that configuration.

  During any time interval in which no `MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_SCREEN_ADDED` or `MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_SCREEN_REMOVED` event is generated, the set of returned `HScreen` instances and the order of these returned instances SHALL not change from the perspective of a given application.

  An MSM implementation SHALL not remove nor generate a `MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_SCREEN_REMOVED` event that would have the effect of removing (or reporting the removal) from this multiscreen configuration an `HScreen` instance whose underlying resources represent the same underlying resources of some non-destroyed application's default `HScreen` instance.

  Returns:
    A (possible empty) `HScreen` array.
  Since:
    MSM I01
  See Also:
    `MultiScreenManager`, `MultiScreenConfigurationEvent`, `HScreen`, `MonitorAppPermission`, `ServiceContext`

### getScreens

    HScreen[] getScreens(String category)

  Obtain all accessible screens with a given category.

  This method, `getScreens(String)`, SHALL function identically to the method `getScreens()` except as follows:

  - If `category` is not `null`, then return only those screens assigned the specified category, or, if no such screen exists, then return an empty `HScreen` array; otherwise, if `category` is `null`, then return the same value as `getScreens()`.

  Parameters:
    `category` - one of the following values: (1) `null`, (2) an element of the following enumeration: { `SCREEN_CATEGORY_NONE`, `SCREEN_CATEGORY_DISPLAY`, `SCREEN_CATEGORY_MAIN`, `SCREEN_CATEGORY_PIP`, `SCREEN_CATEGORY_POP`, `SCREEN_CATEGORY_OVERLAY`, `SCREEN_CATEGORY_GENERAL` }, or (3) a platform-dependent string value not pre-defined as a screen category but that MAY be returned by `getScreenCategory(HScreen)`.
  Returns:
    A (possibly empty) `HScreen` array.
  Since:
    MSM I01

### hasOverlayScreen

    boolean hasOverlayScreen()

  Determine if the set of screens associated with this configuration includes an overlay screen, i.e., a screen whose category is `SCREEN_CATEGORY_OVERLAY`.

  Returns:
    `true` if `getScreens(SCREEN_CATEGORY_OVERLAY)` would return a non-empty array; otherwise, returns `false`.
  Since:
    MSM I01
  See Also:
    `HScreen`

### getDefaultServiceContextScreen

    HScreen getDefaultServiceContextScreen()
                                           throws SecurityException

  Obtain the default service context association screen of this configuration.

  The default service context association screen of a multiscreen configuration is the screen with which `ServiceContext` instances are associated when the configuration becomes active in case that no more specific information is available to determine how to associate a `ServiceContext` instance with a screen.

  The following constraints apply:

  1. if this multiscreen configuration is a per-platform display multiscreen configuration, then the default service context association screen SHALL be a screen associated with the per-display multiscreen configuration of some display screen associated with this multiscreen configuration;
  2. otherwise, if this multiscreen configuration is a per-display multiscreen configuration, then the default service context association screen SHALL be a display screen or a logical screen associated with this multiscreen configuration.

  Returns:
    an `HScreen` instance that serves as the default service context screen for this configuration.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.configuration")`.
  Since:
    MSM I01

### setDefaultServiceContextScreen

    void setDefaultServiceContextScreen(HScreen screen)
                                        throws SecurityException,
                                               IllegalArgumentException

  Set the default service context association screen of this configuration.

  The default service context association screen of a multiscreen configuration is the screen with which `ServiceContext` instances are associated when the configuration becomes active in case that no more specific information is available to determine how to associate a `ServiceContext` instance with a screen.

  Parameters:
    `screen` - an `HScreen` instance to be designated as the default service context association screen for this multiscreen configuration.
  Throws:
    `SecurityException` - if the calling thread has not been granted `MonitorAppPermission("multiscreen.configuration")`.
    `IllegalArgumentException` - if the constraints specified above under `getDefaultServiceContextScreen()` are not satisfied.
  Since:
    MSM I01
  See Also:
    `HScreen`

### isScreenInConfiguration

    boolean isScreenInConfiguration(HScreen screen)

  Determine if the underlying resources of a specified screen is represented by an `HScreen` instance included in the set of screens associated with this configuration.

  Parameters:
    `screen` - an `HScreen` instance.
  Returns:
    `true` if the underlying resources specified screen is represented by an `HScreen` instance included in this configuration; otherwise, `false`.
  Since:
    MSM I01
  See Also:
    `HScreen`

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

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