OcapScene

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 OcapScene

All Superinterfaces:
  ResourceProxy

    public interface OcapScene

extends ResourceProxy

The `OcapScene` interface is implemented by all `HScene` instances created by an OCAP implementation. This interface provides methods for:

- Unambiguously requesting that a scene move to the `front` or the `back` of the z-order stack for the containing graphics plane.
- Conditionally `yield focus`.
- Conditionally `request focus`.

The front-most position in the z-order stack for the containing graphics plane is considered a scarce resource. The `OcapScene` serves as the proxy for this scarce resource -- as such, this interface extends the `ResourceProxy` interface. The scarce resource may be explicitly requested using the `showToFront` and `showToBack` methods. Existing methods that imply a change of position in the z-order (e.g., `HScene.show()` or `HScene.setVisible(true)`) also imply an ownership request of the scarce resource. Existing methods that hide or `dispose` of a scene imply a release of the scarce resource.

The front-most position in the z-order stack is treated as a scarce resource for the following reasons:

- It is a scarce resource (there is only one such position per graphics plane).
- It implies exclusivity for user interaction:
  - Display exclusivity is given to the front-most scene.
  - Only the front-most scene may have focus.

Note: As there may be multiple graphics planes, each graphics plane will have its own logical resource for the front-most position. Each owner of these resources has equal access to AWT focus and the display. The monitor application is responsible for managing inter-plane interactions via APIs such as the Multiscreen Manager (MSM) Extension or the `HSceneChangeRequestHandler`.

Example usage follows:

     HSceneFactory hsf = HSceneFactory.getInstance();
     HScene hscene = hsf.getDefaultHScene();
     OcapScene oscene = (OcapScene)hscene;
     ResourceClient rc = ...;

     oscene.showToFront(rc);
     hscene.requestFocus();

Author:
  Aaron Kamienski

Method Summary
`HSceneBinding` | `getHSceneBinding()` Return the `HSceneBinding` representing this application scene.
`ResourceServer` | `getResourceServer()` Retrieves the `ResourceServer` object for the scarce resource that is the front-most position in the z-order stack for the containing graphics plane.
`void` | `requestFocusDeferred(Component c)` Requests that this scene or the given component be given the input focus, if no other scene currently has the input focus.
`boolean` | `showToBack(ResourceClient rc)` Makes this scene visible and pushes it to the rear of the z-order stack for the containing graphics plane.
`boolean` | `showToFront(ResourceClient rc)` Makes this scene visible and requests ownership over the scarce resource that is the front-most position in the z-order stack for the containing graphics plane, thereby moving it to the front.
`boolean` | `yieldFocus()` Yield focus to another application, if there is another application that has an outstanding focus request and is eligible to receive focus.
`boolean` | `yieldToBack()` Yield ownership over the front-most position in the z-order stack scarce resource if there is another application that has an outstanding focus request would be eligible to receive focus.

Methods inherited from interface org.davic.resources.ResourceProxy
`getClient`

Method Detail

### showToFront

    boolean showToFront(ResourceClient rc)

  Makes this scene visible and requests ownership over the scarce resource that is the front-most position in the z-order stack for the containing graphics plane, thereby moving it to the front. If the scene is already visible, then this method only requests ownership over the scarce resource. If this scene is already visible and already at the front, then this method has no effect other than changing the `ResourceClient` associated with ownership of the resource.

  If no `ResourceClient` is provided, the implementation will act as if one were provided where `ResourceClient.requestRelease(org.davic.resources.ResourceProxy, java.lang.Object)` always returned `true`.

  If this scene is already visible, then `HScene.show()` and `showToFront(null)` have the same effect.

  Parameters:
    `rc` - the `ResourceClient` to associate with ownership
  Returns:
    `true` if the scarce resource is granted immediately; `false` if the scarce resource is not immediately granted

### showToBack

    boolean showToBack(ResourceClient rc)

  Makes this scene visible and pushes it to the rear of the z-order stack for the containing graphics plane. Invocation of this method represents a deferred request for ownership over the scarce resource that is the front-most position in the z-order stack. If the scene is already visible, then this method only pushes the scene to the rear. If this scene is already visible and already at the rear, then this method has no effect other than changing the `ResourceClient` associated with ownership of the resource.

  If no `ResourceClient` is provided, the implementation will act as if one were provided where `ResourceClient.requestRelease(org.davic.resources.ResourceProxy, java.lang.Object)` always returned `true`.

  If no other scenes are visible, then this method operates identically to `showToFront(org.davic.resources.ResourceClient)`.

  Parameters:
    `rc` - the `ResourceClient` to associate with ownership
  Returns:
    `true` if the scarce resource is granted immediately (i.e., because this is the only visible scene); `false` if the scarce resource is not immediately granted

### getResourceServer

    ResourceServer getResourceServer()

  Retrieves the `ResourceServer` object for the scarce resource that is the front-most position in the z-order stack for the containing graphics plane. Logically, this could be considered the same as the `HGraphicsDevice`, however that is not necessitated by this specification.

  An application may add `ResourceStatusListener`s to the returned `ResourceServer` to listen for `FrontSceneResourceReservedEvent`s and `FrontSceneResourceReleasedEvent`s which indicate that a scene as acquired or released the scarce resource.

  Returns:
    the `ResourceServer` object

### yieldFocus

    boolean yieldFocus()

  Yield focus to another application, if there is another application that has an outstanding focus request and is eligible to receive focus. If this scene (or a sub-component) does not currently have focus, then this method does nothing.

  Returns:
    `true` if focus was yielded

### yieldToBack

    boolean yieldToBack()

  Yield ownership over the front-most position in the z-order stack scarce resource if there is another application that has an outstanding focus request would be eligible to receive focus.

  If this scene is currently in the front-most position, it will be pushed to the back (releasing ownership) if another scene would become eligible to receive focus.

  If this scene is not currently in the front-most position, is not visible, or no other scene would be eligible to receive focus, then this method has no effect.

  This does not affect the `ResourceClient` specified for reservation of the front-most position resource.

  Returns:
    `true` if top-of-stack was yielded

### requestFocusDeferred

    void requestFocusDeferred(Component c)

  Requests that this scene or the given component be given the input focus, if no other scene currently has the input focus. If another scene currently has focus, then the given focus request SHALL be deferred until a later time.

  If the given component is not visible or is not contained within this scene, then this method has no effect. A `null` argument is considered equivalent to this scene.

  Parameters:
    `c` - the component for which focus should be requested
  See Also:
    `Component.requestFocus()`

### getHSceneBinding

    HSceneBinding getHSceneBinding()

  Return the `HSceneBinding` representing this application scene.

  Returns:
    the `HSceneBinding` for this scene

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

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