org.havi.ui

Class HSceneTemplate

java.lang.Object

org.havi.ui.HSceneTemplate

public class HSceneTemplate
extends Object

The HSceneTemplate class is used to obtain an HScene subject to a variety of constraints.

The following constraints are supported:

Preference	Object
GRAPHICS_CONFIGURATION	HGraphicsConfiguration
SCENE_PIXEL_LOCATION	java.awt.Point
SCENE_PIXEL_DIMENSION	java.awt.Dimension
SCENE_SCREEN_LOCATION	HScreenPoint
SCENE_SCREEN_DIMENSION	HScreenDimension

Note that as defined here users must set both a location and a dimension preference to request a given rectangle area. Instances of HSceneTemplate returned by the system will always be fully specified. Therefore, if an application only sets a preference on SCENE_SCREEN_LOCATION the system will fill in SCENE_SCREEN_DIMENSION, SCENE_PIXEL_LOCATION and SCENE_PIXEL_DIMENSION with default values based on the appropriate HGraphicsConfiguration and its associated HGraphicsDevice.

In the event of a conflict between REQUIRED preferences specified in pixel coordinates (SCENE_PIXEL_LOCATION, SCENE_PIXEL_DIMENSION) and normalized screen coordinates (SCENE_SCREEN_LOCATION, SCENE_SCREEN_DIMENSION) the system shall ignore the pixel coordinates and use only the screen coordinate preferences.

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:

HSceneFactory

Field Summary

Fields

Modifier and Type	Field and Description
static int	GRAPHICS_CONFIGURATION A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with a specified HGraphicsConfiguration (corresponding to a particular HGraphicsDevice).
static Dimension	LARGEST_PIXEL_DIMENSION A Dimension object for use in the object field of the setPreference and getPreferenceObject methods in the HSceneTemplate that indicates that the SCENE_PIXEL_DIMENSION feature should be set to its largest possible dimension.
static int	PREFERRED A value for use in the priority field of the setPreference and getPreferencePriority methods in the HSceneTemplate that indicates that this feature is preferred over a selection that does not include this feature, although both selections can be considered valid.
static int	REQUIRED A value for use in the priority field of the setPreference and getPreferencePriority methods in the HSceneTemplate that indicates that this feature is required in the HScene.
static int	SCENE_PIXEL_DIMENSION A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with preferred dimensions in pixels as given by a Dimension object.
static int	SCENE_PIXEL_LOCATION A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with a preferred location in pixels as given by a Point object.
static int	SCENE_SCREEN_DIMENSION A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with preferred dimensions in normalized screen coordinates as given by an HScreenDimension object.
static int	SCENE_SCREEN_LOCATION A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with a preferred location in normalized screen coordinates, as given by an HScreenPoint object.
static int	UNNECESSARY A value for use in the priority field of the setPreference and getPreferencePriority methods in the HSceneTemplate that indicates that this feature is unnecessary in the HScene.

Constructor Summary

Constructors

Constructor and Description
HSceneTemplate() Creates a new HSceneTemplate 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, 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 and getPreferencePriority methods in the HSceneTemplate that indicates that this feature is required in the HScene. If this feature is not available, do not create an HScene object.

See Also:

Constant Field Values

PREFERRED

public static final int PREFERRED

A value for use in the priority field of the setPreference and getPreferencePriority methods in the HSceneTemplate that indicates that this feature is preferred over a selection that does not include this feature, although both selections can be considered valid.

See Also:

Constant Field Values

UNNECESSARY

public static final int UNNECESSARY

A value for use in the priority field of the setPreference and getPreferencePriority methods in the HSceneTemplate that indicates that this feature is unnecessary in the HScene. A selection without this feature is preferred over a selection that includes this feature since it is not used.

See Also:

Constant Field Values

LARGEST_PIXEL_DIMENSION

public static final Dimension LARGEST_PIXEL_DIMENSION

A Dimension object for use in the object field of the setPreference and getPreferenceObject methods in the HSceneTemplate that indicates that the SCENE_PIXEL_DIMENSION feature should be set to its largest possible dimension.

GRAPHICS_CONFIGURATION

public static final int GRAPHICS_CONFIGURATION

A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with a specified HGraphicsConfiguration (corresponding to a particular HGraphicsDevice).

By default the HSceneTemplate creates HScenes on the default HScreen's default HGraphicsDevice with its current HGraphicsConfiguration.

See Also:

Constant Field Values

SCENE_PIXEL_DIMENSION

public static final int SCENE_PIXEL_DIMENSION

A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with preferred dimensions in pixels as given by a Dimension object. If the Dimension object is LARGEST_PIXEL_DIMENSION then the returned HScene should have the largest possible dimensions.

See Also:

Constant Field Values

SCENE_PIXEL_LOCATION

public static final int SCENE_PIXEL_LOCATION

A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with a preferred location in pixels as given by a Point object. The graphics pixels shall correspond to the pixel setting for the HGraphicsDevice settings as indicated by the HGraphicsConfiguration as specified in the HSceneTemplate (or its default value).

See Also:

Constant Field Values

SCENE_SCREEN_DIMENSION

public static final int SCENE_SCREEN_DIMENSION

A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with preferred dimensions in normalized screen coordinates as given by an HScreenDimension object.

See Also:

Constant Field Values

SCENE_SCREEN_LOCATION

public static final int SCENE_SCREEN_LOCATION

A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HSceneTemplate that indicates that the HScene be created with a preferred location in normalized screen coordinates, as given by an HScreenPoint object.

See Also:

Constant Field Values

Constructor Detail

HSceneTemplate

public HSceneTemplate()

Creates a new HSceneTemplate object. See the class description for details of constructor parameters and default values.

Method Detail

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.

By default, the preferences should have an UNNECESSARY priority.

Parameters:

preference - the preference to be indicated. Valid values are: GRAPHICS_CONFIGURATION, SCENE_PIXEL_LOCATION, SCENE_PIXEL_RESOLUTION, SCENE_PIXEL_LOCATION and SCENE_SCREEN_RECTANGLE.

An IllegalArgumentException shall be thrown if the preference is not a valid value as listed above.

object - the Object associated with the given preference.

An IllegalArgumentException shall be thrown if the object is not valid for the preference as specified in the class description.

priority - the priority of the preference. Valid values are: REQUIRED, PREFERRED and UNNECESSARY.

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

getPreferenceObject

public Object getPreferenceObject(int preference)

Return the preference object for the specified preference.

Parameters:

preference - the preference to be indicated.

Returns:

the preference object for the specified preference. Valid values shall be of the following types, or null if no preference object was set:

• An HGraphicsConfiguration object which is returned for the GRAPHICS_CONFIGURATION preference.
• A java.awt.Point object which is returned for the SCENE_PIXEL_LOCATION preference.
• A java.awt.Dimension object which is returned for the SCENE_PIXEL_DIMENSION preference.
• An HScreenPoint object which is returned for the SCENE_SCREEN_LOCATION preference.
• An HScreenDimension object which is returned for the SCENE_SCREEN_DIMENSION preference.

getPreferencePriority

public int getPreferencePriority(int preference)

Return the priority for the specified preference.

Parameters:

preference - the preference to be indicated. Valid values are: GRAPHICS_CONFIGURATION, SCENE_PIXEL_LOCATION, SCENE_PIXEL_RESOLUTION, SCENE_PIXEL_LOCATION and SCENE_SCREEN_RECTANGLE.

Returns:

the priority for the specified preference.