HSceneChangeRequestHandler

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
Interface HSceneChangeRequestHandler

    public interface HSceneChangeRequestHandler

Interface to be implemented by a privileged application in order to handle requests (1) to add an `HScene` not currently displayed, (2) remove an `HScene` currently displayed, (3) change the positions of `HScene`s on the screen, (4) move an `HScene` in the `HScene` z-order of an `HGraphicsDevice`, (5) move AWT focus between `HScene` containment hierarchies, and (6) generate notifications of changes of the assignment of AWT focus to an `HScene` containment hierarchy.

Since:
  OCAP 1.0 I12 (ECN 0694)

Field Summary
`static int` | `FOCUS_DEFERRED` Constant that may be returned by `testFocusChange(org.ocap.ui.HSceneBinding, org.ocap.ui.HSceneBinding)`.
`static int` | `FOCUS_DENIED` Constant that may be returned by `testFocusChange(org.ocap.ui.HSceneBinding, org.ocap.ui.HSceneBinding)`.
`static int` | `FOCUS_GRANTED` Constant that may be returned by `testFocusChange(org.ocap.ui.HSceneBinding, org.ocap.ui.HSceneBinding)`.

Method Summary
`void` | `focusChanged(HSceneBinding newScene, HSceneBinding oldScene)` Notify handler of changes in current assignment of AWT focus.
`int` | `testFocusChange(HSceneBinding newScene, HSceneBinding oldScene)` Tests whether reassignment (or removal) of AWT focus to (from) an `HScene` is to be allowed or not.
`boolean` | `testMove(HSceneBinding move, HSceneBinding[] currentScenes)` Tests whether an `HScene` move (or size change) request is to be allowed or not.
`HSceneBinding[]` | `testOrder(HSceneBinding reorder, HSceneBinding[] currentScenes, int currentOrder, int newOrder)` Tests if an `HScene` z-order change request can be made or not.

Field Detail

### FOCUS_DENIED

    static final int FOCUS_DENIED

  Constant that may be returned by `testFocusChange(org.ocap.ui.HSceneBinding, org.ocap.ui.HSceneBinding)`. Indicates that the focus request should be denied.

  See Also:
    Constant Field Values

### FOCUS_GRANTED

    static final int FOCUS_GRANTED

  Constant that may be returned by `testFocusChange(org.ocap.ui.HSceneBinding, org.ocap.ui.HSceneBinding)`. Indicates that the focus request should be granted.

  See Also:
    Constant Field Values

### FOCUS_DEFERRED

    static final int FOCUS_DEFERRED

  Constant that may be returned by `testFocusChange(org.ocap.ui.HSceneBinding, org.ocap.ui.HSceneBinding)`. Indicates that the focus request should be deferred.

  See Also:
    Constant Field Values

Method Detail

### testMove

    boolean testMove(HSceneBinding move,
                     HSceneBinding[] currentScenes)

  Tests whether an `HScene` move (or size change) request is to be allowed or not. Called when an `HScene` is to be moved within the `HScreen` or to be resized, i.e., if the `HScreenRectangle` of the represented `HScene` would be changed in position or size.

  Parameters:
    `move` - the `HSceneBinding` that designates the screen rectangle of the affected `HScene`, and which SHALL be an entry of `currentScenes`.
    `currentScenes` - the `HSceneBinding`s that correspond to the existing visible `HScene`s (and their current screen rectangles) including the affected `HScene`. In this context, an `HScene` is considered visible if `HScene.isVisible()` returns `true`.
  Returns:
    `true` if the move can be made, otherwise returns `false`.
  Since:
    OCAP 1.0 I12 (ECN 0694)

### testOrder

    HSceneBinding[] testOrder(HSceneBinding reorder,
                              HSceneBinding[] currentScenes,
                              int currentOrder,
                              int newOrder)

  Tests if an `HScene` z-order change request can be made or not. Called when an `HScene` is to be moved in the z-order, or caused to be added or removed from the z-order. In the case that an `HScene` is being removed from the z-order, the resulting value of this method MAY be ignored by the implementation (e.g., an application's `HScene` is being removed because the application is terminating).

  The following constraints SHALL apply when invoking this method:

  - either (or both) of `currentOrder` or (and) `newOrder` are non-negative;
  - if `currentOrder` is non-negative, then it is a valid index of the array referenced by `currentScenes`;
  - if `currentOrder` is a valid index of `currentScenes` and if `newOrder` is non-negative, then it is a valid index of the array referenced by `currentScenes`.

  Parameters:
    `reorder` - the `HSceneBinding` that designates the the affected `HScene`. If this `HScene` is already present in the `HScene` z-order, then it SHALL appear as an entry of `currentScenes`; otherwise, it SHALL NOT be present in `currentScenes`.
    `currentScenes` - the `HSceneBinding`s that correspond to the existing visible `HScene`s in z-order with the first entry (0) being the front-most `HScene`. In this context, an `HScene` is considered visible if `HScene.isVisible()` returns `true`.
    `currentOrder` - the value -1 if the `HScene` is to be shown due to invocation of `HScene.show()` or `HScene.setVisible(true)`, or, if the `HScene` was already displayed, a non-negative integer denoting the existing position in the `currentScene` array of the `HScene` to move.
    `newOrder` - a non-negative integer designating the new position to which the affected `HScene` is to be moved or -1 if the affected `HScene` is being removed (entirely) from the `HScene` z-order. If the affected `HScene` is being added to the `HScene` z-order then `newOrder` indicates the position at which it is to appear, with all other current `HScene`s to be move down by one position. If `currentOrder` is -1 and the value of `newOrder` is greater than the index of the last valid index of `currentScenes`, then the to be added `HScene` is being requested to be placed rear-most in the `HScene` z-order.
  Returns:
    (1) `null` if the reorder (add/remove) request is permitted as specified by parameters, (2) the value of parameter `currentScenes` if the request must not be performed as specified (i.e., the existing set of current scenes and their current order must be maintained without change), or (3) a new array of `HSceneBinding` instances that is a permutation of the set composed of the elements in (a) `currentScenes` minus `reorder` if `currentOrder` is non-negative and `newOrder` is negative, (b) `currentScenes` plus `reorder` if `currentOrder` is negative and `newOrder` is non-negative, or (c) `currentScenes` if `currentOrder` and `newOrder` are non-negative.
  Since:
    OCAP 1.0.1 (ECN 1103)

### testFocusChange

    int testFocusChange(HSceneBinding newScene,
                        HSceneBinding oldScene)

  Tests whether reassignment (or removal) of AWT focus to (from) an `HScene` is to be allowed or not.

  If an `HSceneChangeRequestHandler` is registered, then an OCAP platform implementation SHALL call this method whenever AWT focus would be initially assigned to a `HScene` container hierarchy, moved between `HScene` container hierarchies, or removed from all `HScene` container hierarchies. If this method returns `false` for some focus state change, then the OCAP platform implementation SHALL NOT complete that change, and must leave AWT focus unchanged.

  An OCAP platform implementation SHALL NOT call this method when moving focus between sub-containers or components within an `HScene` instance.

  An OCAP platform implementation MAY, but need not call (or use the return value from) this method in the case of a platform originated AWT `HScene` focus reassignment; however, in such a case, the platform SHALL in all cases invoke the `focusChanged(..)` method (below) to provide notification of the platform originated `HScene` focus change.

  The following constraint SHALL apply when invoking this method:

  - either (or both) of `newScene` or (and) `oldScene` are not `null`;

  Parameters:
    `newScene` - the `HSceneBinding` that denotes the `HScene` to which focus is to be assigned, or, `null`, in which case focus is not to be assigned to any `HScene`, i.e., left unassigned.
    `oldScene` - the `HSceneBinding` that denotes the `HScene` from which focus is to be removed, or, `null`, in which case focus was not assigned to any `HScene` (immediately prior to invoking this method).
  Returns:
    one of `FOCUS_DENIED`, `FOCUS_GRANTED`, or `FOCUS_DEFERRED`
  Since:
    OCAP 1.0.1 (ECN 1103)

### focusChanged

    void focusChanged(HSceneBinding newScene,
                      HSceneBinding oldScene)

  Notify handler of changes in current assignment of AWT focus.

  Provide notification of changes to the current assignment of AWT focus to some `HScene`. In order to designate such `HScene`, an `HSceneBinding` is used, which uniquely identifies a scene through the combination of an identified application, from `HSceneBinding.getAppAttributes()`, and a graphics screen device, from `HSceneBinding.getGraphicsDevice()`.

  An OCAP platform implementation SHALL NOT call this method when moving focus between sub-containers or components within an `HScene` instance.

  The unique identification referred to above is based on the constraint that a given application have no more than one `HScene` per `HGraphicsDevice`.

  Parameters:
    `newScene` - either (1) an `HSceneBinding` indirectly denoting the new `HScene` to which focus has been assigned or (2) `null` indicating that no `HScene` is now assigned focus (in this application environment).
    `oldScene` - either (1) an `HSceneBinding` indirectly denoting the old (previous) `HScene` from which focus has been removed or (2) `null` indicating that no `HScene` was previously assigned focus (in this application environment).
  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