HSceneFactory

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 HSceneFactory

    java.lang.Object
      org.havi.ui.HSceneFactory

    public class HSceneFactory

extends Object

The `HSceneFactory` class provides a generic mechanism for an application to request `HScene` resources from a (conceptual) window management system. The `HSceneFactory` is the single entry to potentially multiple HGraphicsDevice centric window management policies.

The `HSceneFactory` class provides an opaque interface between any application (or window) management scheme and the Java application, itself.

Note that only one `HScene` per `HGraphicsDevice` can be acquired at any one time for each application.

`HScenes` follow the design pattern of the `java.awt.Window` class. They are not a scarce resource on the platform. On platforms which only support one `HScene` being visible at one time the current `HScene` both loses the input focus and is hidden (e.g. iconified) when another application successfully requests the input focus. Two `java.awt.event.WindowEvent` events, with ids `WINDOW_DEACTIVATED` and `WINDOW_ICONIFIED`, shall be generated and sent to the `HScene` which has lost the focus and the `isShowing` method for that HScene shall return false.

The constraints on the sizing and positioning of the `HScene` returned by the methods are dependent on the platform-specific `HScene` support. The three scenarios are defined below:

#### Platforms Supporting a Full Multi-Window System

Platforms where windows may obscure each other shall allow applications to create `HScene` objects which are fully within the area of the supporting `HGraphicsDevice` without any restriction on size or location. Whether successful creation of HScenes which are wholly or partially outside the area of the HGraphicsDevice is supported is implementation dependent.

#### Platforms Supporting a Single Window System

Platforms supporting a simple "full-screen" view on a single application at any one time are required to allow applications to create HScenes which cover the full area of the supporting HGraphicsDevice. HScenes matching this description shall be returned as the default `HScene` for the supporting `HGraphicsDevice`. It is implementation dependent whether requests to create HScene objects which cover less than the full area of the supporting HGraphicsDevice succeed and if they succeed, what the consequences are of their being displayed.

#### Platforms Supporting a Restricted Multi-Window System

Platforms supporting a "paned" system where each application occupies an area on-screen that is always visible make fewer guarantees to applications. When an `HScene` is created on such a system, the platform shall return an HScene which, if visible at that time, would cover as much as possible of the requested area of the supporting HGraphicsDevice considering all other visible HScenes at that time. HScenes which are not visible at this time shall not be considered when fixing the location & size of the new HScene. HScenes which are visible at this time shall not be effected by the creation of the new HScene.

When `setVisible(true)` is called on such an `HScene`, the platform shall attempt to make the HScene visible using its currently set position and size. If this would conflict with HScenes which are already visible (e.g. because of changes between when the HScene was created and when `setVisible` was called) then the call to `setVisible` shall fail silently. Applications are responsible for testing for failure using the `isVisible` method. The HScenes of already visible applications shall not be impacted by this method call.

The above text specifies the relationship between an `HScene` and its supporting `HGraphicsDevice` . This specification intentionally does not define minimum requirements for HGraphicsDevices or for their relationship with other HScreenDevices of any type.

Calling `resizeScene` for an `HScene` shall apply the same policies as described above for newly created HScenes when deciding whether the method call is possible.

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.

Method Summary
`void` | `dispose(HScene scene)` This method allows an application to dispose of its `HScene`, indicating that the application has no further need for user interaction (i.e.
`HScene` | `getBestScene(HSceneTemplate hst)` Returns an `HScene` that best corresponds to the input `HSceneTemplate`, or null if such an `HScene` cannot be generated.
`HSceneTemplate` | `getBestSceneTemplate(HSceneTemplate hst)` Returns an `HSceneTemplate` that is closest to to the input `HSceneTemplate` and corresponds to an HScene which could be successfully created on this platform at the time that this method is called.
`HScene` | `getDefaultHScene()` Create the default `HScene` for the default `HScreen` for this application.
`HScene` | `getDefaultHScene(HScreen screen)` Create the default `HScene` for this `HScreen`.
`HScene` | `getFullScreenScene(HGraphicsDevice device)` Create a full-screen `HScene` on the specified `HGraphicsDevice` or null if such an `HScene` cannot be generated.
`static HSceneFactory` | `getInstance()` Returns an `HSceneFactory` object to an application.
`HSceneTemplate` | `resizeScene(HScene hs, HSceneTemplate hst)` Resizes an `HScene` so that it best corresponds to the input `HSceneTemplate`, or remains unchanged if it cannot be so resized.

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

Method Detail

### getInstance

    public static HSceneFactory getInstance()

  Returns an `HSceneFactory` object to an application.

  Returns:
    an `HSceneFactory` object to an application. Note that repeated invocations of this method should return the same object (reference).

### getBestSceneTemplate

    public HSceneTemplate getBestSceneTemplate(HSceneTemplate hst)

  Returns an `HSceneTemplate` that is closest to to the input `HSceneTemplate` and corresponds to an HScene which could be successfully created on this platform at the time that this method is called.

  Note that since some platforms may support more than one concurrent application there is no guarantee that the values returned by this method would actually match those of a subsequently requested `HScene`, using the same template.

  Note that conflict may occur between properties in the `HSceneTemplate` and the `HGraphicsConfigTemplate` corresponding to the currently active `HGraphicsConfiguration`. In the event of conflict between properties which are PREFERRED or UNNECESSARY, the properties concerned shall be ignored and the default will prevail. In the event of conflict between properties which are REQUIRED, this method shall fail and return null.

  Parameters:
    `hst` - The `HSceneTemplate` properties that the `HScene` should satisfy.
  Returns:
    an `HSceneTemplate` that best corresponds to the input `HSceneTemplate`.

### getBestScene

    public HScene getBestScene(HSceneTemplate hst)

  Returns an `HScene` that best corresponds to the input `HSceneTemplate`, or null if such an `HScene` cannot be generated.

  Note that conflict may occur between properties in the `HSceneTemplate` and the `HGraphicsConfigTemplate` corresponding to the currently active `HGraphicsConfiguration`. In the event of conflict between properties which are PREFERRED or UNNECESSARY, the properties concerned shall be ignored and the default will prevail. In the event of conflict between properties which are REQUIRED, this method shall fail and return null.

  Parameters:
    `hst` - the HSceneTemplate to match against
  Returns:
    the `HScene` that matches the properties as specified in the `HSceneTemplate`, or null if they cannot be satisfied, or if no further `HScenes` are available for this application.

### resizeScene

    public HSceneTemplate resizeScene(HScene hs,
                                      HSceneTemplate hst)
                               throws IllegalStateException

  Resizes an `HScene` so that it best corresponds to the input `HSceneTemplate`, or remains unchanged if it cannot be so resized.

  Parameters:
    `hs` - the `HScene` to be resized.
    `hst` - the `HSceneTemplate` which denotes the new size / location. Only size location options in the `HSceneTemplate` will be considered.
  Returns:
    an `HSceneTemplate` that indicates the `HScene` properties after (possible) resizing.
  Throws:
    `IllegalStateException` - if the `HScene` had previously been disposed.

### getDefaultHScene

    public HScene getDefaultHScene(HScreen screen)

  Create the default `HScene` for this `HScreen`. This shall use the `HGraphicsConfiguration` returned by calling

       screen.getDefaultHGraphicsDevice().getDefaultConfiguration()

  Parameters:
    `screen` - the screen for which the `HScene` should be returned.
  Returns:
    the default `HScene` for this `HScreen`. If the application has already obtained an `HScene` for this `HScreen`, then that HScene is returned.

### getDefaultHScene

    public HScene getDefaultHScene()

  Create the default `HScene` for the default `HScreen` for this application. This shall be identical to calling

       org.havi.ui.HSceneFactory.getDefaultHScene(org.havi.ui.HScreen.getDefaultHScreen())

  Returns:
    the default `HScene` for the default `HScreen`. If the application has already obtained an `HScene` for the default `HScreen`, then that HScene is returned.

### getFullScreenScene

    public HScene getFullScreenScene(HGraphicsDevice device)

  Create a full-screen `HScene` on the specified `HGraphicsDevice` or null if such an `HScene` cannot be generated.

  Parameters:
    `device` - the graphics device with which to create the `HScene`. This is obtained through a `HGraphicsConfigTemplate` / `HGraphicsConfiguration` sequence as described in the document for these classes.
  Returns:
    a created full-screen `HScene` or null if this is not possible.

### dispose

    public void dispose(HScene scene)

  This method allows an application to dispose of its `HScene`, indicating that the application has no further need for user interaction (i.e. its resources may be released to the system, for future garbage collection). After `dispose()` has been called the application may then acquire another `HScene`.

  Parameters:
    `scene` - the `HScene` to be disposed of.
  See Also:
    `HScene`, `HScene.dispose()`

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

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