HSceneManager

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.ocap.ui
Class HSceneManager

    java.lang.Object
      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 `HScene`s (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 `HScene`s of the default `HGraphicsDevice` of the calling application.
`HSceneBinding[]` | `getHSceneOrder(HGraphicsDevice device)` Gets the set of scene bindings that correspond with the visible `HScene`s 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 `HScene`s 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 `HScene`s 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)

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

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