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 HScenes 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 HSceneBindings that correspond to the existing visible HScenes (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:

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 HSceneBindings that correspond to the existing visible HScenes 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 HScenes 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:

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)