|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface MultiScreenContext
This interface provides a set of tools for accomplishing the following:
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;HScreen
instance's underlying resource;HScreen
within its
containing MultiScreenConfiguration
;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;HScreenDevice
s within
an HScreen
;ServiceContext
s
associated with an HScreen
;HScreen
s and corresponding VideoOutputPort
instances;HScreenDevice
s whose
generated audio constitute the set of audio sources of an
HScreen
;HScreen
;MultiScreenContext
or certain changes in the
the HScreen
instance that implements this
interface;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.
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 |
---|
static final int SCREEN_TYPE_DISPLAY
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 final int SCREEN_TYPE_LOGICAL
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
Method Detail |
---|
int getScreenType()
HScreen
.
SCREEN_TYPE_DISPLAY
or
SCREEN_TYPE_LOGICAL
.String getID()
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.
HScreen
instance represents in the
implemented scope of uniqueness.HScreen
String getScreenCategory()
HScreen
instance.
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-"
.boolean getVisible()
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).
HScreen
is
marked visible or not on some display HScreen
.int getZOrder()
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.
HScreen
or -1
. If this HScreen
is a logical HScreen
that is not associated with a
display HScreen
, then -1
SHALL be
returned.int getZOrder(HScreenDevice device) throws IllegalArgumentException
Determine the z-order of a specified
HScreenDevice
with an HScreen
where
the following constraints apply:
HBackgroundDevice
is present in this
screen, then the z-order of the rear-most (bottom-most)
HBackgroundDevice
is zero;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;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;HVideoDevice
is greater than
the z-order of any HBackgroundDevice
in this screen;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.
device
- an HScreenDevice
that is associated
with this screen.
HScreenDevice
.
IllegalArgumentException
- if device is not an
HScreenDevice
of this screen.HScreenDevice[] getAudioSources()
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.
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.HScreen getAudioFocus()
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:
HScreen
is a logical screen, then apply
the following ordered sub-rules:
HScreen
is mapped
to a display screen, then apply the following sub-rules:
HScreen
is currently assigned audio focus in
the context of its display screen, then this logical
HScreen
is returned.null
is returned.HScreen
is directly mapped to a video output
port, then this HScreen
is returned.null
is returned.HScreen
is a display screen),
apply the following sub-rules:
HScreen
is returned;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.
HScreen
instance or null
as
described above.MultiScreenConfigurableContext.assignAudioFocus()
VideoOutputPort[] getOutputPorts()
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.
VideoOutputPort
instances. If the returned array is empty, then this HScreen
is not associated with any VideoOutputPort
.HScreen getDisplayScreen()
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.
HScreen
instance or
null
. If null
, then this HScreen
is
not associated with a display HScreen
.HScreenRectangle getDisplayArea()
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.
HScreenRectangle
instance or
null
. If null
, then this HScreen
is not associated with a display HScreen
.ServiceContext[] getServiceContexts()
Obtain the set of ServiceContext
s associated with this
HScreen
to which the calling application is granted
access.
ServiceContext
instances. If the returned array is empty, then this HScreen
is not associated with any accessible ServiceContext
.void addScreenContextListener(MultiScreenContextListener 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.
listener
- a MultiScreenContextListener
instance.void removeScreenContextListener(MultiScreenContextListener 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.
listener
- a MultiScreenContextListener
instance.void addMultiScreenConfigurationListener(MultiScreenConfigurationListener listener) throws IllegalStateException
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.
listener
- a MultiScreenConfigurationListener
instance.
IllegalStateException
- if the type of this screen is not
SCREEN_TYPE_DISPLAY
.MultiScreenConfigurationEvent
,
MultiScreenConfigurationListener
void removeMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
listener
- a MultiScreenConfigurationListener
instance.MultiScreenConfigurationListener
MultiScreenConfiguration[] getMultiScreenConfigurations() throws SecurityException
SCREEN_CONFIGURATION_DISPLAY
).
MultiScreenConfiguration
instances.
SecurityException
- if the calling thread has
not been granted MonitorAppPermission("multiscreen.configuration")
.MultiScreenConfiguration
,
MonitorAppPermission
MultiScreenConfiguration[] getMultiScreenConfigurations(String screenConfigurationType) throws SecurityException, IllegalArgumentException
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.
MultiScreenConfiguration
instances or null
, depending on whether specified
configuration type is supported or not.
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.MultiScreenConfiguration
,
MonitorAppPermission
MultiScreenConfiguration getMultiScreenConfiguration() throws IllegalStateException
MultiScreenConfiguration
instance that applies to this display screen.
IllegalStateException
- if this HScreen
is not a display screen.MultiScreenConfiguration
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |