HSceneTemplate

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 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
`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
`HSceneTemplate()` Creates a new `HSceneTemplate` 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, 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` 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.

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

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