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:

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:

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