8.1 Application Interface

THE FOLLOWING SECTIONS DESCRIBE THE METHODS OF THE APPLICATION INTERFACE.

8.1.1 getState() : State

The Hosted Application returns its current state to the caller.

This method may be called at any time.

Note: 1. A Hosting System may use this method as an alternative to tracking Hosted Application state changes reported by the notifyStateChanged() method call.

2. A Hosting System may use this method to determine if a Hosted Application is still in operation (i.e., did not die without calling the notifyStateChanged() method with an EXIT state).

8.1.2 setState(newState : State) : boolean

The Hosting System requests that the Hosted Application switch to the newState.

The Hosted Application returns TRUE from the method if the Hosted Application received the request, and the requested state change is allowed in the state diagram. Otherwise, the method returns FALSE. A return value of TRUE does not indicate that the state of the Hosted Application has changed to the newState; it merely indicates that the requested state change is valid, and will be made at the soonest opportunity. Once the Hosted Application switches to the requested state, it shall inform the Hosting System through the notifyStateChanged() method of the Host interface.

Note: The asynchronous response to a state change is intended to minimize blocking the Hosting System while waiting for a potentially time-consuming state change in the application.

The Hosted Application shall ignore any setState() and return TRUE when the Hosted Application is already in requested state (i.e., this is a repeated call with the same state).

If the Hosted Application receives a second setState() request for a different state prior to completing a previous request, then the Hosted Application shall abort or ignore the previous request, and begin processing the latest request.

This method may be called at any time, however may not have any effect (other than a return of FALSE) if the requested new state is not an allowed transition from the current state.

8.1.3 bringToFront(requestedScreenArea : Rectangle) : boolean

By calling this method, the Hosting System is asking the Hosted Application to take whatever steps are needed to make its GUI visible as the topmost window, and to gain focus.

If possible, the Hosted Application shall resize and reposition itself to the requestedScreenArea. If requestedScreenArea is missing or null, the Hosted Application may retain its current size and location on the screen.

The method returns TRUE if the Hosted Application received the request and will act on it. Otherwise it returns FALSE.

A Hosted Application shall act on this method if the Hosted Application is in the IDLE or INPROGRESS state. A Hosted Application is not required to act on this method if the Hosted Application is not in the IDLE or INPROGRESS state.

A Hosted Application that has no GUI (e.g. a headless analysis application), where becoming visible and gaining focus has no meaning, shall always return TRUE from this method.