org.havi.ui
Class HSceneTemplate

java.lang.Object
  extended by org.havi.ui.HSceneTemplate

public class HSceneTemplate
extends java.lang.Object

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

The following constraints are supported:

PreferenceObject
GRAPHICS_CONFIGURATIONHGraphicsConfiguration
SCENE_PIXEL_LOCATIONjava.awt.Point
SCENE_PIXEL_DIMENSIONjava.awt.Dimension
SCENE_SCREEN_LOCATIONHScreenPoint
SCENE_SCREEN_DIMENSIONHScreenDimension

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

ParameterDescriptionDefault value Set methodGet method
None.

Default parameter values not exposed in the constructors

DescriptionDefault valueSet method Get method
None.

See Also:
HSceneFactory

Field Summary
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 java.awt.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
HSceneTemplate()
          Creates a new HSceneTemplate object.
 
Method Summary
 java.lang.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, java.lang.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 java.awt.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,
                          java.lang.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 java.lang.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:

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.