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:

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:

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 ResourceStatusListeners to the returned ResourceServer to listen for FrontSceneResourceReservedEvents and FrontSceneResourceReleasedEvents 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