org.havi.ui

Class HScreen

java.lang.Object

org.havi.ui.HScreen

public class HScreen
extends Object

This class describes the final output composition of a device. It ties together all the (MPEG) video decoders, all the graphics sub-systems and backgrounds which are all combined together before finally being displayed. A platform with two independent displays would support two instances of this class. Where a device outputs audio closely bound with video, that audio output can also be represented through this class.

Since an HScreen represents a single video output signal from a device, all the devices which contribute to that signal must have certain properties in common. It is not possible to select conflicting configurations for different devices on the same HScreen - for example having a video device whose logical output has a 4:3 picture aspect ratio and a graphics device whose logical output has a 16:9 picture aspect ratio. This specification intentionally does not define configurations, or which configurations would be conflicting, since these are essentially region or market dependent.

The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

Parameter	Description	Default value	Set method	Get method
None.

Default parameter values not exposed in the constructors

Description	Default value	Set method	Get method
None.

Method Summary

Methods

Modifier and Type	Method and Description
HBackgroundConfiguration	getBestConfiguration(HBackgroundConfigTemplate[] hbcta) Returns an HBackgroundConfiguration from an HBackgroundDevice which is present on this HScreen that best matches at least one of the specified HBackgroundConfigTemplates, or null if this is not possible.
HGraphicsConfiguration	getBestConfiguration(HGraphicsConfigTemplate[] hgcta) Returns an HGraphicsConfiguration from an HGraphicsDevice which is present on this HScreen that best matches at least one of the specified HGraphicsConfigTemplates.
HVideoConfiguration	getBestConfiguration(HVideoConfigTemplate[] hvcta) Returns an HVideoConfiguration from an HVideoDevice which is present on this HScreen that best matches at least one of the specified HVideoConfigTemplates.
HScreenConfiguration[]	getCoherentScreenConfigurations(HScreenConfigTemplate[] hscta) Return a coherent set of HScreenConfigurations matching a set of templates.
HBackgroundDevice	getDefaultHBackgroundDevice() Return the default background device for this screen.
HGraphicsDevice	getDefaultHGraphicsDevice() Return the default graphics device for this screen.
static HScreen	getDefaultHScreen() Returns the default HScreen for this application.
HVideoDevice	getDefaultHVideoDevice() Return the default video device for this screen.
HBackgroundDevice[]	getHBackgroundDevices() Returns a list of background devices for this screen.
HGraphicsDevice[]	getHGraphicsDevices() Returns a list of graphics devices for this screen.
static HScreen[]	getHScreens() Returns all HScreens in this system.
HVideoDevice[]	getHVideoDevices() Returns a list of video device for this screen.
boolean	setCoherentScreenConfigurations(HScreenConfiguration[] hsca) Modify the settings for a set of HScreenDevices, based on their HScreenConfigurations supplied.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getHScreens

public static HScreen[] getHScreens()

Returns all HScreens in this system.

Returns:

an array of HScreens representing all HScreens in this system.

getDefaultHScreen

public static HScreen getDefaultHScreen()

Returns the default HScreen for this application. For systems where an application is associated with audio or video which is started before the application starts, this method will return the HScreen where that associated audio / video is being output.

Returns:

the default HScreen for this application.

getHVideoDevices

public HVideoDevice[] getHVideoDevices()

Returns a list of video device for this screen. For systems where an application is associated with video started before the application starts, the first entry in the array returned will be the video device where that video is being output.

Returns:

an array of HVideoDevice objects or null if none exist.

getDefaultHVideoDevice

public HVideoDevice getDefaultHVideoDevice()

Return the default video device for this screen. Note that the HVideoDevice is the default device for rendering video, but it may not be capable of displaying graphics / mixing it with graphics concurrently.

Returns:

an HVideoDevice object or null if none exist.

getBestConfiguration

public HVideoConfiguration getBestConfiguration(HVideoConfigTemplate[] hvcta)

Returns an HVideoConfiguration from an HVideoDevice which is present on this HScreen that best matches at least one of the specified HVideoConfigTemplates. If this is not possible, null is returned.

Equally best in this sense means that the configurations satisfy an equal number of preferences with priorities PREFERRED and PREFERRED_NOT and all preferences with priorities REQUIRED and REQUIRED_NOT. If there are such equally best configurations, the one which is returned by this method is an implementation dependent selection from among those which are equally best.

Configurations are chosen according to the following algorithm, based on the priority as supplied to setPreference. Configurations must:

1. satisfy ALL the preferences whose priority was REQUIRED
2. satisfy NONE of the preferences whose priority was REQUIRED_NOT
3. satisfy as many as possible of the preferences whose priority was PREFERRED.
4. satisfy as few as possible of the preferences whose priority was PREFERRED_NOT.

Preferences whose priority was DONT_CARE are ignored.

This method returns null if no configuration exists that satisfies all REQUIRED and REQUIRED_NOT priorities.

Parameters:

hvcta - - the array of HVideoConfigTemplate objects to choose from.

Returns:

an HVideoConfiguration object that is the best matching configuration possible, or null if no HVideoConfiguration object passes the criteria.

getHGraphicsDevices

public HGraphicsDevice[] getHGraphicsDevices()

Returns a list of graphics devices for this screen.

Returns:

an array of HGraphicsDevices or null if none exist.

getDefaultHGraphicsDevice

public HGraphicsDevice getDefaultHGraphicsDevice()

Return the default graphics device for this screen. Note that the HGraphicsDevice is the default device for rendering graphics, but it may not be capable of displaying video / mixing it with graphics concurrently.

Returns:

the default graphics device for this screen or null if none exist.

getBestConfiguration

public HGraphicsConfiguration getBestConfiguration(HGraphicsConfigTemplate[] hgcta)

Returns an HGraphicsConfiguration from an HGraphicsDevice which is present on this HScreen that best matches at least one of the specified HGraphicsConfigTemplates. If this is not possible this method will attempt to construct an HEmulatedGraphicsConfiguration where the emulated configuration best matches one of the specified HGraphicsConfigTemplates. If this is not possible, null is returned.

Equally best in this sense means that the configurations satisfy an equal number of preferences with priorities PREFERRED and PREFERRED_NOT and all preferences with priorities REQUIRED and REQUIRED_NOT. If there are such equally best configurations, the one which is returned by this method is an implementation dependent selection from among those which are equally best.

Configurations are chosen according to the following algorithm, based on the priority as supplied to setPreference. Configurations must:

1. satisfy ALL the preferences whose priority was REQUIRED
2. satisfy NONE of the preferences whose priority was REQUIRED_NOT
3. satisfy as many as possible of the preferences whose priority was PREFERRED.
4. satisfy as few as possible of the preferences whose priority was PREFERRED_NOT.

Preferences whose priority was DONT_CARE are ignored.

This method returns null if no configuration exists that satisfies all REQUIRED and REQUIRED_NOT priorities.

Parameters:

hgcta - - the array of HGraphicsConfigTemplate objects to choose from.

Returns:

an HGraphicsConfiguration object that is the best matching configuration possible, or null if no HGraphicsConfiguration or HEmulatedGraphicsConfiguration object passes the criteria.

getHBackgroundDevices

public HBackgroundDevice[] getHBackgroundDevices()

Returns a list of background devices for this screen.

Returns:

an array of HBackgroundDevices or null if none exist.

getDefaultHBackgroundDevice

public HBackgroundDevice getDefaultHBackgroundDevice()

Return the default background device for this screen.

Returns:

the default background device for this screen or null if none exist.

getBestConfiguration

public HBackgroundConfiguration getBestConfiguration(HBackgroundConfigTemplate[] hbcta)

Returns an HBackgroundConfiguration from an HBackgroundDevice which is present on this HScreen that best matches at least one of the specified HBackgroundConfigTemplates, or null if this is not possible.

Equally best in this sense means that the configurations satisfy an equal number of preferences with priorities PREFERRED and PREFERRED_NOT and all preferences with priorities REQUIRED and REQUIRED_NOT. If there are such equally best configurations, the one which is returned by this method is an implementation dependent selection from among those which are equally best.

Configurations are chosen according to the following algorithm, based on the priority as supplied to setPreference. Configurations must:

1. satisfy ALL the preferences whose priority was REQUIRED
2. satisfy NONE of the preferences whose priority was REQUIRED_NOT
3. satisfy as many as possible of the preferences whose priority was PREFERRED.
4. satisfy as few as possible of the preferences whose priority was PREFERRED_NOT.

Preferences whose priority was DONT_CARE are ignored.

This method returns null if no configuration exists that satisfies all REQUIRED and REQUIRED_NOT priorities.

Parameters:

hbcta - the array of HBackgroundConfiguration objects to choose from, represented as an array of HBackgroundConfiguration objects.

Returns:

an HBackgroundConfiguration object that is the best matching configuration possible, or null if no HBackgroundConfiguration passes the criteria.

getCoherentScreenConfigurations

public HScreenConfiguration[] getCoherentScreenConfigurations(HScreenConfigTemplate[] hscta)

Return a coherent set of HScreenConfigurations matching a set of templates. One HScreenConfiguration will be returned for each HScreenConfigTemplate provided as input. The class of the returned objects will correspond to the class of the templates provided as input - where an HGraphicsConfigTemplate is provided as input, an HGraphicsConfiguration shall be returned. Where an HVideoConfigTemplate is provided as input, an HVideoConfiguration shall be returned. If more than one template of the same type is provided then the configurations returned must be on different devices but presented on the same screen. If more templates of one type are provided than there are devices of that type in the system, this function will return null.

Coherent means that all the required properties are respected in all of the templates provided and that a configuration can be returned for each template provided.

Conflicts between templates are resolved as discussed in the description of HScreenConfigTemplate.

Parameters:

hscta - an array of objects describing desired / required configurations. If a zero-length array is passed this function will throw a java.lang.IllegalArgumentException.

Returns:

an array of non-null objects describing a coherent set of screen device configurations or null if no such coherent set is possible.

setCoherentScreenConfigurations

public boolean setCoherentScreenConfigurations(HScreenConfiguration[] hsca)
                                        throws SecurityException,
                                               HPermissionDeniedException,
                                               HConfigurationException

Modify the settings for a set of HScreenDevices, based on their HScreenConfigurations supplied. Settings should be modified atomically (where possible) or should not be modified if the HScreenConfigurations can be determined to be conflicting a priori, i.e. are not "coherent", or would cause an exception to be thrown.

Parameters:

hsca - the array of configurations that should be applied atomically (where possible). If the length of this array is zero a java.lang.IllegalArgumentException will be thrown.

Returns:

A boolean indicating whether all HScreenConfigurations could be applied successfully. If all of the HScreenConfigurations could not be applied successfully, the configuration after this method may not match the configuration of the devices prior to this method being called --- applications should take steps to determine whether a partial change of settings has been made on each device.

Throws:

SecurityException - if the application does not have sufficient rights to set the HScreenConfiguration for any of the devices.

HPermissionDeniedException - if the application does not currently have the right to set the configuration for any of the devices.

HConfigurationException - if the specified HScreenConfiguration[] array is not valid for any of the devices.