|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface MultiScreenConfigurableContext
This interface provides a set of tools for accomplishing the following:
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);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
;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.
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. |
Field Detail |
---|
static final int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE
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.
HScreen
,
HScreenDevice
,
Constant Field Valuesstatic final int CONFIGURABLE_SCREEN_PARAMETER_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.
HScreen
,
Constant Field Valuesstatic final int CONFIGURABLE_SCREEN_PARAMETER_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:
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" ) );
HScreen
,
HScreenDevice
,
HBackgroundDevice
,
HVideoDevice
,
HGraphicsDevice
,
Constant Field Valuesstatic final int CONFIGURABLE_SCREEN_PARAMETER_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.
HScreen
,
HScreenRectangle
,
Constant Field Valuesstatic final int CONFIGURABLE_SCREEN_PARAMETER_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.
HScreen
,
Constant Field Valuesstatic final int CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT
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.
HScreen
,
VideoOutputPort
,
Constant Field Valuesstatic final int CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT
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.
HScreen
,
ServiceContext
,
Constant Field Valuesstatic final int CONFIGURABLE_SCREEN_PARAMETER_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.
HScreen
,
Constant Field Valuesstatic final int CONFIGURABLE_SCREEN_PARAMETER_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.
HScreen
,
Constant Field ValuesMethod Detail |
---|
boolean isConfigurableParameter(int parameter)
parameter
- a configurable screen parameter enumeration
value as defined above.
parameter
on this screen, then returns true
;
otherwise, returns false
.boolean hasDiscreteParameterSpace(int parameter) throws IllegalArgumentException
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(..)
.
parameter
- a configurable screen parameter enumeration
value as defined above.
parameter
on this screen, then returns true
;
otherwise, returns false
, in which case all values
of the value type space are supported (or approximated).
IllegalArgumentException
- if
isConfigurableParameter(parameter)
returns
false
.Object[] getDiscreteParameterSpace(int parameter) throws IllegalArgumentException
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.
parameter
- a configurable screen parameter enumeration
value as defined above.
IllegalArgumentException
- if
isConfigurableParameter(parameter)
or
hasDiscreteParameterSpace(parameter)
returns
false
.void setVisible(boolean visible) throws SecurityException, IllegalStateException
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).
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
.
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.void setZOrder(int order) throws SecurityException, IllegalStateException
Cause this logical HScreen
to change its z-order
among other logical HScreen
s mapped to the same
display HScreen
.
order
- a positive integer value indicating the new z-order to
assign to this logical HScreen
.
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.void setZOrder(HScreenDevice[] devices) throws SecurityException, IllegalArgumentException, IllegalStateException
Atomically set the z-order of the specified set of
HScreenDevice
within this screen where the following
constraints apply:
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;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.
devices
- an ordered array of HScreenDevice
instances that are associated with this screen.
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.void addAudioSources(HScreenDevice[] devices, boolean mixWithAudioFocus) throws SecurityException, IllegalArgumentException, IllegalStateException
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.
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.
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.void removeAudioSources(HScreenDevice[] devices) throws SecurityException, IllegalArgumentException, IllegalStateException
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.
devices
- either null
or a non-empty set of
HScreenDevice
instances.
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
.void assignAudioFocus() throws SecurityException, IllegalStateException
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).
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.void addOutputPorts(VideoOutputPort[] ports, boolean removeExisting) throws SecurityException, IllegalStateException
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.
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;
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.void removeOutputPorts(VideoOutputPort[] ports) throws SecurityException, IllegalArgumentException, IllegalStateException
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.
ports
- either null
or a non-empty array of
VideoOutputPort
instances.
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
.void setDisplayScreen(HScreen screen) throws SecurityException, IllegalStateException
Associates this logical HScreen
with a display
HScreen
.
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
.
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
.void setDisplayArea(HScreenRectangle rect) throws SecurityException, IllegalStateException
Associates this logical HScreen
with an area (extent) of
its associated display HScreen
.
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
.
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
.boolean checkServiceContextCompatibility(ServiceContext context) throws SecurityException, IllegalArgumentException
Determine if application may assign ServiceContext
to this
HScreen
and if the specified ServiceContext
is
compatible with presentation on this HScreen
.
context
- a valid ServiceContext
instance.
ServiceContext
instance can be assigned to this
HScreen
. If it can be assigned, true
is
returned; otherwise, false
is returned.
SecurityException
- if the calling thread has
not been granted MonitorAppPermission("multiscreen.context")
.
IllegalArgumentException
- if the specified
ServiceContext
is not valid.void addServiceContexts(ServiceContext[] contexts, boolean associateDefaultDevices) throws SecurityException, IllegalStateException
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:
HVideoDevice
of the screen, then background based
player content from that service context 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.
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.
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
.void removeServiceContexts(ServiceContext[] contexts) throws SecurityException, IllegalArgumentException, IllegalStateException
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.
contexts
- either null
or a non-empty array of
ServiceContext
instances.
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
.void setMultiScreenConfiguration(MultiScreenConfiguration configuration, Dictionary serviceContextAssociations) throws SecurityException, IllegalArgumentException, IllegalStateException
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.
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.
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.MultiScreenConfiguration
,
MonitorAppPermission
void requestMultiScreenConfigurationChange(MultiScreenConfiguration configuration, Dictionary serviceContextAssociations) throws SecurityException, IllegalArgumentException, IllegalStateException
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).
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.
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.MultiScreenConfiguration
,
MonitorAppPermission
ResourceClient getClient()
HScreen
instance.
getClient
in interface ResourceProxy
ResourceClient
instance or
null
if the underlying screen and screen resources
associated with this HScreen
are not reserved.boolean reserveScreen(ResourceClient client, Object requestData)
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
.
client
- a ResourceClient
instance.requestData
- either null
or an Object
instance that implements the java.rmi.Remote
interface.
true
if underlying resources of screen were
successfully reserved, otherwise false
.Remote
void releaseScreen()
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.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |