org.web3d.x3d.sai
Interface ExternalBrowser

All Superinterfaces:

Browser

All Known Subinterfaces:

Xj3DBrowser

All Known Implementing Classes:

SAIBrowser

public interface ExternalBrowser
extends Browser

Browser interface that represents the additional abilities an external application is granted to the VRML browser.

A number of the methods in this applicationcan take strings representing URLs. Relative URL strings contained in URL fields of nodes or these method arguments are interpreted as follows:

Relative URLs are treated as per clause B.3.5 of the EAI Java Bindings

Version:

$Revision: 1.3 $

Author:

Justin Couch

Method Summary

void	addBrowserListener(BrowserListener l) Add a listener for browser events.
void	beginUpdate() Lock the output from the external interface to the browser as the code is about to begin a series of updates.
void	dispose() Dispose the resources that are used by this instance.
void	endUpdate() Release the output of events from the external interface into the VRML browser.
void	pauseRender() Pause the render and event cascade evaluation system.
void	removeBrowserListener(BrowserListener l) Remove a listener for browser events.
void	startRender() Start the render and event cascade evaluation system again after a pause or stop.
void	stopRender() Stop the render and event cascade evaluation system completely.

Methods inherited from interface org.web3d.x3d.sai.Browser

createScene, createX3DFromStream, createX3DFromString, createX3DFromURL, firstViewpoint, firstViewpoint, getBrowserProperties, getComponent, getCurrentFrameRate, getCurrentSpeed, getDescription, getExecutionContext, getName, getProfile, getRenderingProperties, getSupportedComponents, getSupportedProfiles, getVersion, importDocument, lastViewpoint, lastViewpoint, loadURL, nextViewpoint, nextViewpoint, previousViewpoint, previousViewpoint, print, println, replaceWorld, setDescription

Method Detail

beginUpdate

void beginUpdate()
                 throws InvalidBrowserException

Lock the output from the external interface to the browser as the code is about to begin a series of updates. No events will be passed to the VRML world. They will be buffered pending release due to a subsequent call to endUpdate.

This call is a nesting call which means subsequent calls to beginUpdate are kept on a stack. No events will be released to the VRML browser until as many endUpdates have been called as beginUpdate.

Throws:

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

endUpdate

void endUpdate()
               throws InvalidBrowserException

Release the output of events from the external interface into the VRML browser. All events posted to this point from the last time that beginUpdate was called are released into the VRML browser for processing at the next available oppourtunity.

This call is a nesting call which means subsequent calls to beginUpdate are kept on a stack. No events will be released to the VRML browser until as many endUpdates have been called as beginUpdate.

If no beginUpdate has been called before calling this method, it has no effect.

Throws:

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

addBrowserListener

void addBrowserListener(BrowserListener l)
                        throws InvalidBrowserException

Add a listener for browser events. Any changes in the browser will be sent to this listener. The order of calling listeners is not guarenteed. Checking is performed on whether the nominated listener is already registered to ensure that multiple registration cannot take place. Therefore it is possible to multiply register the one class instance while only receiving one event.

Parameters:

l - The listener to add.

Throws:

java.lang.NullPointerException - If the provided listener reference is null

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

removeBrowserListener

void removeBrowserListener(BrowserListener l)
                           throws InvalidBrowserException

Remove a listener for browser events. After calling this method, the listener will no longer recieve events from this browser instance. If the listener passed as an argument is not currently registered, the method will silently exit.

Parameters:

l - The listener to remove

Throws:

java.lang.NullPointerException - If the provided listener reference is null

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

dispose

void dispose()

Dispose the resources that are used by this instance. Should be called just prior to leaving the application.

startRender

void startRender()

Start the render and event cascade evaluation system again after a pause or stop. If this is a start after a stop, it should be treated as the world having just been loaded. All scripts and sensors should be told to initialise again. If it is after a pause, the world continues as before as though nothing has happened, except TimeSensors will have their time values updated to reflect the current time and the fraction adjusted accordingly.

pauseRender

void pauseRender()

Pause the render and event cascade evaluation system.

stopRender

void stopRender()

Stop the render and event cascade evaluation system completely. This will trigger the proper shutdown notifications being sent to all nodes and scripts.