org.ocap.ui
Class HSceneManager

java.lang.Object
  extended by org.ocap.ui.HSceneManager

public abstract class HSceneManager
extends Object

This class represents a platform manager component that allows a privileged application to register a handler to process requested HScene changes within an HGraphicsDevice composited with all HScenes (of that HGraphicsDevice). In addition, HScene z-ordering, default scene, and current focus assignment can be queried using this manager.

Since:
OCAP 1.0 I12 (ECN 0694)

Method Summary
 HSceneBinding getAppDefaultHScene(AppID id)
          Gets an HSceneBinding that permits determining the default HScene of an identified application if that application possesses a default HScene.
 int getAppHSceneLocation()
          Gets the HScene z-order location for the calling application's default HScene.
 int getAppHSceneLocation(HScene scene)
          Gets the HScene z-order location for the specified HScene.
 HSceneBinding[] getAppHScenes(AppID id)
          Obtain an array of HSceneBinding instances that denote the current HScene instances of an identified application.
 HSceneBinding getHSceneFocus()
          Obtain an HSceneBinding that permits determining the HScene (of this application environment) to which AWT focus is assigned.
 HSceneBinding[] getHSceneOrder()
          Gets the set of scene bindings that correspond with the visible HScenes of the default HGraphicsDevice of the calling application.
 HSceneBinding[] getHSceneOrder(HGraphicsDevice device)
          Gets the set of scene bindings that correspond with the visible HScenes of the specified HGraphicsDevice.
static HSceneManager getInstance()
          Obtain the singleton instance of HSceneManager, where this instance appears to behave (from an accessible state perspective) as if it were scoped to the platform (and not the calling application).
 boolean sameScene(HSceneBinding sb1, HSceneBinding sb2)
          Determine if two HSceneBinding instances refer to the same underlying scene.
 void setHSceneChangeRequestHandler(HSceneChangeRequestHandler handler)
          Allow an application establish itself as the HScene change request handler.
 void transferHSceneFocus(HGraphicsDevice device)
          Request transfer (or removal) of AWT focus to (from) the front-most HScene of the given graphics device.
 void transferHSceneFocus(HSceneBinding binding)
          Request transfer (or removal) of AWT focus to (from) a specific HScene (of this application environment).
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static HSceneManager getInstance()
Obtain the singleton instance of HSceneManager, where this instance appears to behave (from an accessible state perspective) as if it were scoped to the platform (and not the calling application).

Returns:
The HSceneManager.
Since:
OCAP 1.0 I12 (ECN 0694)

setHSceneChangeRequestHandler

public void setHSceneChangeRequestHandler(HSceneChangeRequestHandler handler)
                                   throws SecurityException
Allow an application establish itself as the HScene change request handler. If a handler is already registered when this method is called, it is replaced with the specified handler.

Parameters:
handler - either (1) an HSceneChangeRequestHandler to be queried regarding changes to HScene z-ordering, as well as changes regarding default focus assignment, or (2) null, in which case the current handler is removed.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("handler.resource").
Since:
OCAP 1.0 I12 (ECN 0694)

getHSceneOrder

public HSceneBinding[] getHSceneOrder()
                               throws SecurityException
Gets the set of scene bindings that correspond with the visible HScenes of the default HGraphicsDevice of the calling application.

If the calling application is assigned a default graphics screen, then this method SHALL return the same value as getHSceneOrder(HScreen.getDefaultHScreen().getDefaultHGraphicsDevice()); otherwise, it SHALL return an empty array.

Returns:
array of HSceneBinding instances corresponding to visible HScene instances of the calling application's default HGraphicsDevice in z-order, where visible means scene.isVisible() returns true.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("handler.resource").
Since:
OCAP 1.0.1 (ECN 1103)

getHSceneOrder

public HSceneBinding[] getHSceneOrder(HGraphicsDevice device)
                               throws SecurityException
Gets the set of scene bindings that correspond with the visible HScenes of the specified HGraphicsDevice.

The array of return scene bindings is ordered such that the first entry (0) corresponds to the front-most visible HScene in the HScene z-order for the specified HGraphicsDevice, and the last entry corresponds to the rear-most visible HScene.

If the specified graphics device is associated with a screen that is not associated with a display screen or an output port or is not enabled for display on an output port, then an empty array SHALL be returned.

Parameters:
device - an HGraphicsDevice
Returns:
array of HSceneBinding instances corresponding to visible HScene instances of the specified HGraphicsDevice in z-order, where visible means scene.isVisible() returns true.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("handler.resource").
Since:
OCAP 1.0.1 (ECN 1103)

getAppHSceneLocation

public int getAppHSceneLocation()
Gets the HScene z-order location for the calling application's default HScene. Applications can call this to determine where in the z-order of an HGraphicsDevice instance their default HScene is located.

Returns:
the value -1 if the application has never obtained a reference to its default HScene (implying that the application has no user interface); otherwise, return the same value as getAppHSceneLocation(HSceneFactory.getDefaultHScene()).
Since:
OCAP 1.0 I12 (ECN 0694)

getAppHSceneLocation

public int getAppHSceneLocation(HScene scene)
Gets the HScene z-order location for the specified HScene. Applications can call this to determine where in the z-order of an HGraphicsDevice a specific HScene is located.

Parameters:
scene - an HScene instance for which to obtain the z-order location within the HGraphicsDevice instance with which the HScene is associated.
Returns:
an integer designating the HScene z-order location for the specified HScene. The value is ordered increasing in z-order where 0 is front-most and all other values are in increasing order below the front-most HScene. A value of -1 is returned if the HScene has not been ordered or if it is not visible, where visible is defined as scene.isVisible() returning true.
Since:
OCAP 1.0.1 (ECN 1103)

getAppDefaultHScene

public HSceneBinding getAppDefaultHScene(AppID id)
                                  throws SecurityException
Gets an HSceneBinding that permits determining the default HScene of an identified application if that application possesses a default HScene.

Invocation of this method SHALL NOT cause the creation of or association of a default HScene with an application.

Parameters:
id - an AppID instance denoting an OCAP application.
Returns:
either (1) an HSceneBinding (indirectly) denoting the default HScene assigned to the identified application or (2) null indicating that the application no longer exists in the application database, has terminated, or is not (currently) assigned a default HScene.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("handler.resource").
Since:
OCAP 1.0.1 (ECN 1103)

getAppHScenes

public HSceneBinding[] getAppHScenes(AppID id)
                              throws SecurityException
Obtain an array of HSceneBinding instances that denote the current HScene instances of an identified application.

Invocation of this method SHALL NOT cause the creation of or association of an HScene with an application.

Parameters:
id - an AppID instance denoting an OCAP application.
Returns:
either (1) a non-empty array of HSceneBinding instances that (indirectly) denote the HScene instances assigned to the identified application or (2) null indicating that the application no longer exists in the application database, has terminated, or is not (currently) assigned any HScene.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("handler.resource").
Since:
OCAP 1.0.1 (ECN 1103)

getHSceneFocus

public HSceneBinding getHSceneFocus()
Obtain an HSceneBinding that permits determining the HScene (of this application environment) to which AWT focus is assigned.

If the calling application has not been granted MonitorAppPermission("handler.resource"), then this method SHALL return null if AWT focus is assigned to an HScene that is not owned by the calling application.

Returns:
either (1) an HSceneBinding (indirectly) denoting the HScene to which AWT focus is assigned or (2) null indicating that AWT focus is not assigned to any HScene (in this application environment) or the calling application does not have MonitorAppPermission("handler.resource") in the circumstances described above.
Since:
OCAP 1.0.1 (ECN 1103)

transferHSceneFocus

public void transferHSceneFocus(HSceneBinding binding)
                         throws SecurityException
Request transfer (or removal) of AWT focus to (from) a specific HScene (of this application environment).

If this transfer (or removal) request is fulfilled, then this fulfillment MAY be asynchronous with respect to invocation of this method; furthermore, fulfillment may not occur if the platform state or some other condition otherwise prevents changing AWT focus.

A request to assign AWT focus to an application that is not in a running state or to an HScene that is not focusable SHALL NOT be fulfilled.

Upon the successful transfer (or removal) of focus to (from) some HScene by this method or by the platform (independently of this method), the focusChanged() method SHALL be invoked on a registered HSceneChangeRequestHandler instance.

Parameters:
binding - either (1) an HSceneBinding which uniquely identifies an HScene to which AWT focus assignment is requested or (2) null, indicating that AWT focus assignment is requested to be removed from all HScene instances (of this application environment).
Throws:
SecurityException - if the caller does not have MonitorAppPermission("handler.resource").
Since:
OCAP 1.0.1 (ECN 1103)

transferHSceneFocus

public void transferHSceneFocus(HGraphicsDevice device)
                         throws SecurityException
Request transfer (or removal) of AWT focus to (from) the front-most HScene of the given graphics device.

If this transfer (or removal) request is fulfilled, then this fulfillment MAY be asynchronous with respect to invocation of this method; furthermore, fulfillment may not occur if the platform state or some other condition otherwise prevents changing AWT focus.

A request to assign AWT focus to a graphics device that does not have an eligible HScene SHALL NOT be fulfilled.

Upon the successful transfer (or removal) of focus to (from) some HScene by this method or by the platform (independently of this method), the focusChanged() method SHALL be invoked on a registered HSceneChangeRequestHandler instance.

Parameters:
device - either (1) an HGraphicsDevice which identifies the screen device to which focus should be transferred or (2) null, indicating that AWT focus assignment is requested to be removed from all HScene instances (of this application environment).
Throws:
SecurityException - if the caller does not have MonitorAppPermission("handler.resource").
Since:
OCAP 1.0.1 (ECN 1118)

sameScene

public boolean sameScene(HSceneBinding sb1,
                         HSceneBinding sb2)
Determine if two HSceneBinding instances refer to the same underlying scene.

Parameters:
sb1 - an HSceneBinding instance.
sb2 - an HSceneBinding instance.
Returns:
if sb1 and sb2 denote the same underlying scene, then return true; otherwise, return false.
Since:
OCAP 1.0.1 (ECN 1103)