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. IfreplaceWorld
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 routefromField
- field name of the start nodetoNode
- end node of the routetoField
- 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 routefromField
- field name of the start nodetoNode
- end node of the routetoField
- 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 nodeString
- name of eventInString
- 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 nodeString
- 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 raydirection
- 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 mousemousey
- 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 tofield
- the name of the field of the node to register toscriptmethod
- 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 tofield
- the name of the field of the node to register toscriptmethod
- 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: