HScreen

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

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

## 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
`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
`equals, 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.

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

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