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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
HScreenConfigTemplate() Creates an HScreenConfigTemplate object.

Method Summary

Methods

Modifier and Type	Method and Description
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

clone, equals, finalize, 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.