HScreenConfigTemplate

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 HScreenConfigTemplate

    java.lang.Object
      org.havi.ui.HScreenConfigTemplate

Direct Known Subclasses:
  HBackgroundConfigTemplate, HGraphicsConfigTemplate, HVideoConfigTemplate

    public abstract class HScreenConfigTemplate

extends Object

This class describes a configuration of a screen device in terms of various properties and their importance to the application. It is used to request a valid instance of a configuration conforming to the description provided. Sub-classes of this define additional constants which may be used for additional properties. Those classes can be sub-classed in turn to add further properties by systems using the HAVi UI.

In the event of conflicting preferences between HScreenConfigTemplates (for example where a configuration is requested which conflicts with an existing configuration) the following rules shall be applied in all cases.

- Where all the conflicting preferences have priority `PREFERRED`, `PREFERRED_NOT` or `DONT_CARE`, the conflicting preferences shall be discarded from the template.
- Where all the conflicting preferences have priority `REQUIRED` or `REQUIRED_NOT`, the method concerned shall fail.
- In situations other than the above, all preferences with priority `PREFERRED`, `PREFERRED_NOT` or `DONT_CARE` shall be discarded. If there is still a conflict after this, the method concerned shall fail.

Several preferences in this class are required to be not filled in by the platform in templates generated by the platform. This shall mean:

- the object for this preference (if there is one) is set to `null`
- the priority for this preference is set to DONT_CARE

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.

See Also:
  `HBackgroundConfigTemplate`, `HGraphicsConfigTemplate`, `HVideoConfigTemplate`

Field Summary
`static int` | `DONT_CARE` A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that the presence or absence of this feature in the `HScreenConfiguration` does not matter.
`static int` | `FLICKER_FILTERING` A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports flicker filtering (if it supports an interlaced screen).
`static int` | `INTERLACED_DISPLAY` A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports an interlaced display.
`static int` | `PIXEL_ASPECT_RATIO` A value for use in the preference field of the `setPreference`, `getPreferenceObject` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports the pixel aspect ratio, as specified in a Dimension object which indicates the (relative) x, y pixel aspect ratio.
`static int` | `PIXEL_RESOLUTION` A value for use in the preference field of the `setPreference`, `getPreferenceObject` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports the pixel resolution, as specified in a Dimension object which indicates the pixel resolution of (the area of) the graphics device (as specified using the `SCREEN_RECTANGLE` preference).
`static int` | `PREFERRED` A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that this feature is desired in the `HScreenConfiguration`.
`static int` | `PREFERRED_NOT` A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that this feature is desired not to be present in the `HScreenConfiguration`.
`static int` | `REQUIRED` A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that this feature is required in the `HScreenConfiguration`.
`static int` | `REQUIRED_NOT` A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that this feature is required not to be present in the `HScreenConfiguration`.
`static int` | `SCREEN_RECTANGLE` A value for use in the preference field of the `setPreference`, `getPreferenceObject` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports presentation on a particular on-screen area, as specified in an `HScreenRectangle` object
`static int` | `VIDEO_GRAPHICS_PIXEL_ALIGNED` A value for use in the preference field of the `setPreference`, `getPreferenceObject` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports the display of video streams and graphics with aligned pixels of the same size.
`static int` | `ZERO_BACKGROUND_IMPACT` A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration should have zero impact on already displayed backgrounds.
`static int` | `ZERO_GRAPHICS_IMPACT` A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration should have zero impact on already running graphical applications.
`static int` | `ZERO_VIDEO_IMPACT` A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration should have zero impact on already running video streams.

Constructor Summary
`HScreenConfigTemplate()` Creates an `HScreenConfigTemplate` object.

Method Summary
`Object` | `getPreferenceObject(int preference)` Return the preference object for the specified preference.
`int` | `getPreferencePriority(int preference)` Return the priority for the specified preference.
`void` | `setPreference(int preference, int priority)` Set the indicated preference to have the specified priority.
`void` | `setPreference(int preference, Object object, int priority)` Set the indicated preference (and associated value object) to have the specified priority.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### REQUIRED

    public static final int REQUIRED

  A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that this feature is required in the `HScreenConfiguration`. If this feature is not available, do not select the `HScreenConfiguration` object.

  See Also:
    Constant Field Values

### PREFERRED

    public static final int PREFERRED

  A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that this feature is desired in the `HScreenConfiguration`. A selection with this feature is preferred over a selection that does not include this feature, although both selections can be considered valid matches.

  See Also:
    Constant Field Values

### DONT_CARE

    public static final int DONT_CARE

  A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that the presence or absence of this feature in the `HScreenConfiguration` does not matter. Preferences with this priority play no part in the selection procedure.

  See Also:
    Constant Field Values

### PREFERRED_NOT

    public static final int PREFERRED_NOT

  A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that this feature is desired not to be present in the `HScreenConfiguration`. A selection without this feature is preferred over a selection that does not include this feature, although both selections can be considered valid matches.

  See Also:
    Constant Field Values

### REQUIRED_NOT

    public static final int REQUIRED_NOT

  A value for use in the priority field of the `setPreference(int, int)` and `getPreferencePriority(int)` methods in the `HScreenConfigTemplate` that indicates that this feature is required not to be present in the `HScreenConfiguration`. If this feature is available, do not select the `HScreenConfiguration` object.

  See Also:
    Constant Field Values

### ZERO_BACKGROUND_IMPACT

    public static final int ZERO_BACKGROUND_IMPACT

  A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration should have zero impact on already displayed backgrounds. If used with the `REQUIRED` priority, this means no changes shall be made. If used with the `PREFERRED` priority, this means changes may be made but should be minimized.

  The `PREFERRED_NOT` and `REQUIRED_NOT` priorities may be ignored in the selection of an `HScreenConfiguration` for this preference type.

  This preference is used by the platform as a constraint in selecting configurations. Templates generated by the platform and then returned to applications (e.g. from a `getConfigTemplate` method) shall not have this preference filled in by the platform.

  See Also:
    Constant Field Values

### ZERO_GRAPHICS_IMPACT

    public static final int ZERO_GRAPHICS_IMPACT

  A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration should have zero impact on already running graphical applications. If used with the `REQUIRED` priority, this means no changes shall be made. If used with the `PREFERRED` priority, this means changes may be made but should be minimized.

  The `PREFERRED_NOT` and `REQUIRED_NOT` priorities may be ignored in the selection of an `HScreenConfiguration` for this preference type.

  This preference is used by the platform as a constraint in selecting configurations. Templates generated by the platform and then returned to applications (e.g. from a `getConfigTemplate` method) shall not have this preference filled in by the platform.

  See Also:
    Constant Field Values

### ZERO_VIDEO_IMPACT

    public static final int ZERO_VIDEO_IMPACT

  A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration should have zero impact on already running video streams. If used with the `REQUIRED` priority, this means no changes shall be made. If used with the `PREFERRED` priority, this means changes may be made but should be minimized.

  The `PREFERRED_NOT` and `REQUIRED_NOT`. priorities may be ignored in the selection of an `HScreenConfiguration` for this preference type.

  This preference is used by the platform as a constraint in selecting configurations. Templates generated by the platform and then returned to applications (e.g. from a `getConfigTemplate` method) shall not have this preference filled in by the platform.

  See Also:
    Constant Field Values

### INTERLACED_DISPLAY

    public static final int INTERLACED_DISPLAY

  A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports an interlaced display.

  See Also:
    Constant Field Values

### FLICKER_FILTERING

    public static final int FLICKER_FILTERING

  A value for use in the preference field of the `setPreference` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports flicker filtering (if it supports an interlaced screen).

  See Also:
    Constant Field Values

### VIDEO_GRAPHICS_PIXEL_ALIGNED

    public static final int VIDEO_GRAPHICS_PIXEL_ALIGNED

  A value for use in the preference field of the `setPreference`, `getPreferenceObject` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports the display of video streams and graphics with aligned pixels of the same size. Alignment of the origins of the two pixel coordinate spaces is explicitly not required. Where a video device is moving the video relative to the screen in real time (e.g. implementing pan and scan), graphics configurations shall only support this feature where the implementation of the graphics device can track the position changes in the video device automatically.

  If this preference is set and used to request an `HVideoConfiguration` then an `HGraphicsConfiguration` shall be used as the preference object. If it is set and used to request an `HGraphicsConfiguration` then an `HVideoConfiguration` shall be used as the preference object. Requesting an `HVideoConfiguration` which is VIDEO_GRAPHICS_PIXEL_ALIGNED with another `HVideoConfiguration` shall fail unless the system concerned supports two `HVideoDevice` objects which can support this exact feature.

  This preference is used by the platform as a constraint in selecting configurations. Templates generated by the platform and then returned to applications (e.g. from a `getConfigTemplate` method) shall not have this preference filled in by the platform.

  See Also:
    Constant Field Values

### PIXEL_ASPECT_RATIO

    public static final int PIXEL_ASPECT_RATIO

  A value for use in the preference field of the `setPreference`, `getPreferenceObject` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports the pixel aspect ratio, as specified in a Dimension object which indicates the (relative) x, y pixel aspect ratio.

  Instances of `HScreenConfigTemplate` generated by the platform and returned to applications (e.g. from `getConfigTemplate` shall have this preference set to a platform specific value with the `REQUIRED` priority.

  See Also:
    Constant Field Values

### PIXEL_RESOLUTION

    public static final int PIXEL_RESOLUTION

  A value for use in the preference field of the `setPreference`, `getPreferenceObject` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports the pixel resolution, as specified in a Dimension object which indicates the pixel resolution of (the area of) the graphics device (as specified using the `SCREEN_RECTANGLE` preference).

  Instances of `HScreenConfigTemplate` generated by the platform and returned to applications (e.g. from `getConfigTemplate` shall have this preference set to a platform specific value with the `REQUIRED` priority.

  See Also:
    Constant Field Values

### SCREEN_RECTANGLE

    public static final int SCREEN_RECTANGLE

  A value for use in the preference field of the `setPreference`, `getPreferenceObject` and `getPreferencePriority` methods in the `HScreenConfigTemplate` that indicates that the device configuration supports presentation on a particular on-screen area, as specified in an `HScreenRectangle` object

  Use of this value with an `HScreenRectangle` object other than the identity rectangle `[0, 0 -> 1, 1]` implies scaling of the presentation to fit within the specified HScreenRectangle.

  Platforms not supporting such scaling at all or choosing to expose such scaling through other APIs should only return `HScreenConfigTemplates` with the `HScreenRectangle` `[0, 0 -> 1, 1]` for the SCREEN_RECTANGLE preference.

  Instances of `HScreenConfigTemplate` generated by the platform and returned to applications (e.g. from `getConfigTemplate` shall have this preference set to a platform specific value with the `REQUIRED` priority.

  See Also:
    Constant Field Values

Constructor Detail

### HScreenConfigTemplate

    public HScreenConfigTemplate()

  Creates an `HScreenConfigTemplate` object. See the class description for details of constructor parameters and default values.

Method Detail

### setPreference

    public void setPreference(int preference,
                              int priority)

  Set the indicated preference to have the specified priority. If the preference has been previously set, then the previous priority for the preference shall be overwritten.

  Attributes that are not filled in a template (through `setPreference(int, int)`), shall have the priority `DONT_CARE`. Any configuration always satisfies these attributes.

  Parameters:
    `preference` - the preference to be indicated. Valid values for an `HScreenConfigTemplate` are: `ZERO_GRAPHICS_IMPACT`, `ZERO_BACKGROUND_IMPACT`, `ZERO_VIDEO_IMPACT`, `INTERLACED_DISPLAY` and `FLICKER_FILTERING`.

    Subclasses may add further valid values. An IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of `HScreenConfigTemplate`

    `priority` - the priority of the preference. Valid values are: `REQUIRED`, `PREFERRED`, `DONT_CARE`, `PREFERRED_NOT` and `REQUIRED_NOT`.

    If `priority` is not a valid priority as defined here a java.lang.IllegalArgumentException will be thrown.

### setPreference

    public void setPreference(int preference,
                              Object object,
                              int priority)

  Set the indicated preference (and associated value object) to have the specified priority. If the preference has been previously set, then the previous object and priority shall be overwritten.

  Attributes that are not filled in a template (through `setPreference(int, int)`), shall have the priority `DONT_CARE`. Any configuration always satisfies these attributes.

  An application which wishes to remove a preference from an existing template (e.g. one generated by the platform) may call this method with null for the object parameter.

  Parameters:
    `preference` - the preference to be indicated. Valid values for an `HScreenConfigTemplate` are: `VIDEO_GRAPHICS_PIXEL_ALIGNED`, `PIXEL_ASPECT_RATIO`, `PIXEL_RESOLUTION` and `SCREEN_RECTANGLE`.

    Subclasses may add further valid values. An IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of `HScreenConfigTemplate`

    `object` - the Object associated with the given preference, or `null`.
    `priority` - the priority of the preference. Valid values include: `REQUIRED`, `PREFERRED`, `DONT_CARE`, `PREFERRED_NOT` and `REQUIRED_NOT`.

    If `priority` is not a valid priority as defined here a java.lang.IllegalArgumentException will be thrown.

### getPreferencePriority

    public int getPreferencePriority(int preference)

  Return the priority for the specified preference.

  Individual properties in the ConfigTemplate can then be examined using the getPreferencePriority and getPreferenceObject methods -- features that are implemented will return `REQUIRED`, features that are not implemented will return `REQUIRED_NOT`.

  Parameters:
    `preference` - the preference to be indicated. Valid values for an `HScreenConfigTemplate` are: `ZERO_BACKGROUND_IMPACT`, `ZERO_GRAPHICS_IMPACT`, `ZERO_VIDEO_IMPACT`, `INTERLACED_DISPLAY`, `FLICKER_FILTERING`, `VIDEO_GRAPHICS_PIXEL_ALIGNED`, `PIXEL_ASPECT_RATIO`, `PIXEL_RESOLUTION` and `SCREEN_RECTANGLE`.

    Subclasses may add further valid values. An IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of `HScreenConfigTemplate`

  Returns:
    the priority for the specified preference.

### getPreferenceObject

    public Object getPreferenceObject(int preference)

  Return the preference object for the specified preference.

  Instances of `HScreenConfigTemplate` which have not had this preference set shall return null for this object. Note that instances constructed by the platform and returned to applications are required to have all preferences (except where explicitly identified) set by the platform before it is returned.

  Parameters:
    `preference` - the preference to be indicated. Valid values for an `HScreenConfigTemplate` are: `VIDEO_GRAPHICS_PIXEL_ALIGNED`, `PIXEL_ASPECT_RATIO`, `PIXEL_RESOLUTION` and `SCREEN_RECTANGLE`.

    Subclasses may add further valid values. A IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of `HScreenConfigTemplate`, or if `preference` does not have an associated value object.

  Returns:
    the preference object for the specified preference.

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

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