x3d
Interface Browser

public abstract interface Browser

Basic browser interface to the X3D browser from any application. Individual X3D browser must implement this interface.

A number of the methods in this application can 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:

1.02

Author:

Holger Grahn, Kristof Nast-Kolb, Andrea Fasce, Bitmanagement Software

Field Summary

static java.lang.String	PROPERTY_BOUNDBACKGROUND Properties: the currently bound Viewpoint (returns node handle)
static java.lang.String	PROPERTY_BOUNDNAVIGATIONINFO Properties: the currently bound Viewpoint (returns node handle)
static java.lang.String	PROPERTY_BOUNDVIEWPOINT Properties: the currently bound Viewpoint (returns node handle)
static java.lang.String	PROPERTY_HEADLIGHT Properties: headlight on/off (returns Boolean true/false)
static java.lang.String	PROPERTY_NAME Properties: name of the browser
static java.lang.String	PROPERTY_PROFILE Properties: supported profile of the browser The browser should return the profile and if available all additional profile components that it supports for example "coreX3D navigation=VRML97,scripting=Java"
static java.lang.String	PROPERTY_VERSION Properties: version of the browser

Method Summary

void	addAWTObserver(EventObserver observer) Add an observer for AWT events.
void	addBrowserObserver(EventObserver observer) Add an observer for browser events.
void	addBrowserScriptObserver(java.lang.String scriptmethod) Add a javascript observer for browser events.
void	addFieldScriptObserver(java.lang.String node, java.lang.String field, java.lang.String scriptmethod) Add a javascript observer for a field with read capability (EventOut or ExposedField) the observer object will be notified of any changes to this field The javascript method should be done this way: function javascriptmethod(type,nodename,fieldname) where type - the event type nodename - the name of the node that launched this event (in case of a browser event it's null) fieldname - the name of the field that launched this event (in case of a browser event it's null)
void	addRoute(Node fromNode, java.lang.String fromEventOut, Node toNode, java.lang.String toEventIn) Add a route between two nodes
void	beginUpdate() Lock the output from the external interface to the browser as the code is about to begin a series of updates.
Node[]	createX3DFromString(java.lang.String x3dString) Parse the given string and turn this into a list of X3D nodes.
void	createX3DFromURL(java.lang.String url, EventObserver observer, java.lang.Object userData) Create and load X3D from the given URL.
void	deleteRoute(Node fromNode, java.lang.String fromEventOut, Node toNode, java.lang.String toEventIn) Delete a route between two nodes
void	endUpdate() Release the output of events from the external interface into the X3D browser.
float[]	getCamera() Get the current position and orientation of the camera
Node	getNode(java.lang.String name) Get a DEF node by name.
java.lang.String	getNodeField(java.lang.String node, java.lang.String event) get node eventout by string, usable from script
java.lang.Object	getProperty(java.lang.String name) Get a browser property.
Node[]	getWorld() Get the current root nodes.
java.lang.String	getWorldURL() Get the fully qualified URL of the currently loaded world.
void	loadURL(java.lang.String url) Load the URL as the new root of the scene.
PickInfo	pick(int info, float[] from, float[] direction) Send a ray and get information about the geometry that was hit by the ray specified by start point and direction.
PickInfo	pick(int info, int mousex, int mousey) Send a ray and get information about the geometry that was hit by the ray specified by a mouse position.
void	removeAWTObserver(EventObserver observer) Remove an observer for AWT browser events.
void	removeBrowserObserver(EventObserver observer) Remove an observer for browser events.
void	removeBrowserScriptObserver(java.lang.String scriptmethod) Remove a javascript observer for browser events.
void	removeFieldScriptObserver(java.lang.String node, java.lang.String field, java.lang.String scriptmethod) Remove a javascript observer for changes in this field. the observer has been added before with addObserver
void	replaceWorld(Node[] nodes) Replace the current world with the given nodes.
boolean	setNodeField(java.lang.String node, java.lang.String event, java.lang.String value) set node eventin from string, usable from script

Field Detail

PROPERTY_NAME

public static final java.lang.String PROPERTY_NAME

Properties: name of the browser

PROPERTY_VERSION

public static final java.lang.String PROPERTY_VERSION

Properties: version of the browser

PROPERTY_PROFILE

public static final java.lang.String PROPERTY_PROFILE

Properties: supported profile of the browser The browser should return the profile and if available all additional profile components that it supports for example "coreX3D navigation=VRML97,scripting=Java"

PROPERTY_HEADLIGHT

public static final java.lang.String PROPERTY_HEADLIGHT

Properties: headlight on/off (returns Boolean true/false)

PROPERTY_BOUNDVIEWPOINT

public static final java.lang.String PROPERTY_BOUNDVIEWPOINT

Properties: the currently bound Viewpoint (returns node handle)

PROPERTY_BOUNDBACKGROUND

public static final java.lang.String PROPERTY_BOUNDBACKGROUND

Properties: the currently bound Viewpoint (returns node handle)

PROPERTY_BOUNDNAVIGATIONINFO

public static final java.lang.String PROPERTY_BOUNDNAVIGATIONINFO

Properties: the currently bound Viewpoint (returns node handle)

Method Detail

getProperty

public java.lang.Object getProperty(java.lang.String name)

Get a browser property. The name of the property can be one of the standard properties or any browser specific property

Parameters:

name - the name of the property

Returns:

The property, e.g. a String or a Node

getCamera

public float[] getCamera()
                  throws X3DException

Get the current position and orientation of the camera

Returns:

float[7]: x, y and z value of the position and x, y, z and angle of the orientation

Throws:

X3DException - The browser reference isn't valid anymore

getWorldURL

public java.lang.String getWorldURL()
                             throws X3DException

Get the fully qualified URL of the currently loaded world. This returns the entire URL including any possible arguments that might be associated with a CGI call or similar mechanism. If the initial world is replaced with loadURL then the string will reflect the new URL. If replaceWorld is called then the URL still represents the original world.

Returns:

A string of the URL or null if no world (yet) loaded

Throws:

X3DException - The browser reference isn't valid anymore

See Also:

loadURL(java.lang.String), replaceWorld(x3d.Node[])

replaceWorld

public void replaceWorld(Node[] nodes)
                  throws java.lang.IllegalArgumentException,
                         X3DException

Replace the current world with the given nodes. Replaces the entire contents of the X3D world with the new nodes. Any node references that belonged to the previous world are still valid but no longer form part of the scene graph (unless these nodes are passed to this method). The URL of the world still represents the just unloaded world.

Calling this method causes a SHUTDOWN event followed by an INITIALIZED event to be generated.

Parameters:

nodes - The list of nodes to use as the new root of the world

Throws:

java.lang.IllegalArgumentException - if the nodes are not valid X3D nodes

X3DException - The browser reference isn't valid anymore

getWorld

public Node[] getWorld()
                throws X3DException

Get the current root nodes.

Returns:

The list of nodes representing the toplevel world

Throws:

X3DException - The browser reference isn't valid anymore

loadURL

public void loadURL(java.lang.String url)
             throws java.lang.IllegalArgumentException,
                    X3DException

Load the URL as the new root of the scene. Replaces all the current scene graph with the new world. A non-blocking call that will change the contents at some time in the future.

Generates an immediate SHUTDOWN event and then when the new contents are ready to be loaded, sends an INITIALIZED event.

Parameters:

url - The url of a X3D file.

Throws:

java.lang.IllegalArgumentException - the URL passed to this method is bogus and cannot be translated to usable values

X3DException - The browser reference isn't valid anymore

createX3DFromString

public Node[] createX3DFromString(java.lang.String x3dString)
                           throws java.lang.IllegalArgumentException,
                                  X3DException

Parse the given string and turn this into a list of X3D nodes. Method is a blocking call that won't return until all of the top level nodes defined in the string have been returned.

At the point that this method returns, external files such as textures, sounds and inlines may not have been loaded.

The string may contain all legal X3D syntax. The X3D header line is not required to be present in the string.

Parameters:

x3dString - The string containing X3D string syntax

Returns:

A list of the top level nodes in X3D representation as defined in the parameter

Throws:

java.lang.IllegalArgumentException - If the string does not contain legal X3D syntax or no node instantiations

X3DException - The browser reference isn't valid anymore

createX3DFromURL

public void createX3DFromURL(java.lang.String url,
                             EventObserver observer,
                             java.lang.Object userData)
                      throws java.lang.IllegalArgumentException,
                             X3DException

Create and load X3D from the given URL. The specified observer is called once the Resource has been loaded or in case of errors. The resulting nodes are wrapped into an Group node. The observer gets that node as parameter in the onEvent() method

Parameters:

url - The url of the X3D file.

observer - The observer that gets the notification.

userData - Additional userData that will be passed to the onEvent method, might be null.

Throws:

java.lang.IllegalArgumentException - the URL passed to this method is bogus and cannot be translated to usable values, or no observer specified

X3DException - The browser reference isn't valid anymore

addRoute

public void addRoute(Node fromNode,
                     java.lang.String fromEventOut,
                     Node toNode,
                     java.lang.String toEventIn)
              throws java.lang.IllegalArgumentException

Add a route between two nodes

Parameters:

fromNode - start node of the route

fromField - field name of the start node

toNode - end node of the route

toField - field name of the end node

Throws:

java.lang.IllegalArgumentException -

deleteRoute

public void deleteRoute(Node fromNode,
                        java.lang.String fromEventOut,
                        Node toNode,
                        java.lang.String toEventIn)
                 throws java.lang.IllegalArgumentException

Delete a route between two nodes

Parameters:

fromNode - start node of the route

fromField - field name of the start node

toNode - end node of the route

toField - field name of the end node

Throws:

java.lang.IllegalArgumentException -

getNode

public Node getNode(java.lang.String name)
             throws java.lang.IllegalArgumentException,
                    X3DException

Get a DEF node by name. Nodes given DEF names in the root scene graph are available to be retrieved by this method. DEFed nodes in Inlines, createX3DFromString and createX3DFromURL are not available.

Parameters:

name - The name of the DEF node to retrieve

Returns:

A reference to that node

Throws:

java.lang.IllegalArgumentException - The named node does not exist or is not accessible.

X3DException - The browser reference isn't valid anymore

setNodeField

public boolean setNodeField(java.lang.String node,
                            java.lang.String event,
                            java.lang.String value)

set node eventin from string, usable from script

Parameters:

String - name of node

String - name of eventIn

String - value for eventIn

Returns:

boolean true if successful

getNodeField

public java.lang.String getNodeField(java.lang.String node,
                                     java.lang.String event)

get node eventout by string, usable from script

Parameters:

String - name of node

String - name of eventOut

Returns:

String value of eventOut

beginUpdate

public void beginUpdate()
                 throws X3DException

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 X3D world. They will be buffered pending release due to a subsequent call to endUpdate.

This call is not nested. Additional beginUpdate calls have no effect. The first endUpdate call will release the X3D browser again.

Throws:

X3DException - The browser reference isn't valid anymore

endUpdate

public void endUpdate()
               throws X3DException

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

The call is not nested. This means one call to endUpdate ends all beginUpdate calls.

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.

X3DException - The browser reference isn't valid anymore

pick

public PickInfo pick(int info,
                     float[] from,
                     float[] direction)
              throws java.lang.IllegalArgumentException

Send a ray and get information about the geometry that was hit by the ray specified by start point and direction. The info flag specifies which information should be retrieved. The information is returned in a PickInfo object.

Parameters:

info - flagword that specifies which information should be retrieved The flags are defined in PickInfo.

from - the start point of the ray

direction - the direction of the point

Returns:

The PickInfo object, null if no object is hit

Throws:

java.lang.IllegalArgumentException - invalid ray definition or info flag.

pick

public PickInfo pick(int info,
                     int mousex,
                     int mousey)
              throws java.lang.IllegalArgumentException

Send a ray and get information about the geometry that was hit by the ray specified by a mouse position. The info flag specifies which information should be retrieved. The information is returned in a PickInfo object.

Parameters:

info - flagword that specifies which information should be retrieved The flags are defined in PickInfo.

mousex - the x coordinate of the mouse

mousey - the y coordinate of the mouse

Returns:

The PickInfo object

Throws:

java.lang.IllegalArgumentException - invalid ray definition or info flag.

addBrowserObserver

public void addBrowserObserver(EventObserver observer)
                        throws X3DException

Add an observer for browser events. Any changes in the browser will be sent to this observer. The order in which observers are called is not guarenteed. An observer can only be registered once. This means that multiple registrations are ignored. But it is possible to add different observer for one browser.

Parameters:

observer - The observer to add.

Throws:

X3DException - The browser reference isn't valid anymore

addBrowserScriptObserver

public void addBrowserScriptObserver(java.lang.String scriptmethod)

Add a javascript observer for browser events. Any changes in the browser will be sent to this observer. The order in which observers are called is not guarenteed. An observer can only be registered once. This means that multiple registrations are ignored. But it is possible to add different observer for one browser. The javascript method should be done this way: function javascriptmethod(type,nodename,fieldname) where type - the event type nodename - the name of the node that launched this event (in case of a browser event it's null) fieldname - the name of the field that launched this event (in case of a browser event it's null) also consider that you MUST add a javascript BrowserObserer after the applet has been loaded, so you should something like int your html code where myfunction() is the javascript function that uses addBrowserObserver() Please consider that becouse of efficiency the events START_RENDERING and END_RENDERING won't be send to a script observer.

Parameters:

scriptmethod - The javascript method to add.

removeBrowserObserver

public void removeBrowserObserver(EventObserver observer)
                           throws X3DException

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

Parameters:

observer - The observer to remove

Throws:

X3DException - The browser reference isn't valid anymore

See Also:

removeBrowserScriptObserver

public void removeBrowserScriptObserver(java.lang.String scriptmethod)

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

Parameters:

scriptmethod - The javascript method to remove

See Also:

addFieldScriptObserver

public void addFieldScriptObserver(java.lang.String node,
                                   java.lang.String field,
                                   java.lang.String scriptmethod)

Add a javascript observer for a field with read capability (EventOut or ExposedField)

the observer object will be notified of any changes to this field The javascript method should be done this way: function javascriptmethod(type,nodename,fieldname) where type - the event type nodename - the name of the node that launched this event (in case of a browser event it's null) fieldname - the name of the field that launched this event (in case of a browser event it's null)

Parameters:

node - the name of the node to register to

field - the name of the field of the node to register to

scriptmethod - The javascript method to add

removeFieldScriptObserver

public void removeFieldScriptObserver(java.lang.String node,
                                      java.lang.String field,
                                      java.lang.String scriptmethod)

Remove a javascript observer for changes in this field.

the observer has been added before with addObserver

Parameters:

node - the name of the node to register to

field - the name of the field of the node to register to

scriptmethod - The javascript method to remove

addAWTObserver

public void addAWTObserver(EventObserver observer)
                    throws X3DException

Add an observer for AWT events. Any key, mouse or window events in the browser will be sent to this observer. See Component.handleEvent for details. The order in which observers are called is not guaranteed. An observer can only be registered once. This means that multiple registrations are ignored. But it is possoble to add different observer for one browser.

Parameters:

observer - The observer to add.

Throws:

X3DException - The browser reference isn't valid anymore

removeAWTObserver

public void removeAWTObserver(EventObserver observer)
                       throws X3DException

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

Parameters:

observer - The observer to remove

Throws:

X3DException - The browser reference isn't valid anymore

See Also: