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

Methods

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

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