de.jreality.plugin
Class JRViewer

java.lang.Object
  extended by de.jreality.plugin.JRViewer

public class JRViewer
extends Object

JRViewer is the default viewer of jReality. It replaces the older viewers: ViewerVR and ViewerApp.

The simplest way to use the JRViewer is to call the static method

        JRViewer.display(SceneGraphNode node);
 

Any JRViewer is a composition of Plugins. There are static add* methods to add bunches of related plugins. To get a virtual reality JRViewer with a movable avatar you may call the convenient static method

        JRViewer v=JRViewer.createJRViewerVR(SceneGraphNode contentNode);
        v.startup();
 
This is a shortcut for
        JRViewer v = new JRViewer();
 
        v.addBasicUI();
        v.addVRSupport();
        v.addContentSupport(ContentType.TerrainAligned);
        v.registerPlugin(new ContentAppearance());
        v.registerPlugin(new ContentTools());
        v.setContent(SceneGraphNode contentNode);
 
        v.startup();
 

Behind the scenes

The JRViewer is the jReality front end to the SimpleController. It implements convenient methods to register jReality related plugins and delegates other methods directly to the controller. The controller may be accessed directly via getController().

Plugin properties

The SimpleController, which works behind the scenes of the JRViewer, allows Plugins to read and save properties. These properties are read from and saved to a file at startup and shutdown via XStream.

When SimpleController#shutdown() is called (from the main windows closing method or from a plugin that implements ShutdownFlavor) the user gets the chance to decide where the properties are saved. The decisions are saved via the java preferences API (see setPropertiesResource(Class, String). If nothing else is specified the SimpleController tries to read the plugin properties from

 
                System.getProperty("user.home") + "/.jrworkspace/default_simple.xml"
 
and saves the user decisions in the preferences node of the package of the SimpleController.

Besides the name (and path) of the properties file the user may choose

The user may cancel the dialog, which also cancels the shutdown process.

It is recommended that applications call

                setPropertiesResource(MyClass.class,"propertiesFileName")
 
before calling startup(). Then the controller loads the plugin properties from this resource. After deployment this resource may most likely only be opened for reading, which has the effect that it will only be used to call setPropertiesInputStream(InputStream) and the properties file will retain its default value or whatever it is set to via setPropertiesFile(File).

When loading properties the availability of a properties file is checked in the following order

  1. the user properties file (from the java preferences), when loadFromUserPropertyFile is true
  2. the propertiesInputStream
  3. the propertiesFile
When saving properties the availability of a properties file for output is checked in the following order
  1. the user properties file (from the java preferences)
  2. the propertiesFile
The user is prompted when askBeforeSaveOnExit is true or both files above can't be opened for writing.

Note to Eclipse developers: if you change the path of the file to save the properties into in the dialog at shutdown to point to the source folder and DISABLE the load from this file check box, then the resource will be accessed to load the properties (and the situation after deployment is always tested) and the source folder file is used to save (which then may be included in version control). In order to trigger copying of the source folder file to the bin folder one may add a do nothing builder which has "Refresh resources upon completion" enabled and make sure that the "Filtered resources" do not filter this file.

Author:
sechelmann, pinkall, weissmann, peters

Nested Class Summary
static class JRViewer.ContentType
           
 
Constructor Summary
JRViewer()
          Create a JRViewer with default scene and lights.
JRViewer(boolean addLights)
          Create a JRViewer with default scene.
JRViewer(JrScene s)
          create a JRViewer with a custom scene.
 
Method Summary
 void addAudioSupport()
          Audio plug-ins.
 void addBasicUI()
          Basic UI support: scene graph inspector, bean shell, menu bar, view menu (with display options and background color), export menu, camera settings menu, and properties menu.
 void addContentSupport(JRViewer.ContentType type)
          Registers one of the predefined content plug-ins
 void addContentUI()
          Registers advanced content tools.
 void addVRSupport()
          Virtual reality support.
static JRViewer createJRViewerVR(SceneGraphNode contentNode)
          Create a JRViewer that displays the provided SceneGraphNode in a virtual reality environment with movable avatar etc.
static SceneShrinkPanel createSceneShrinkPanel(Component c, String title)
          Deprecated. extend SceneShrinkPanel or ViewShrinkPanelPlugin
static Viewer display(SceneGraphNode node)
          Quick display method with encompass
 void encompassEuclidean()
          Call after startup.
 SimpleController getController()
          Returns the controller of this JRViewer which is a SimpleController
static JRViewer getLastJRViewer()
          Returns the last created instance of JRViewer
<T extends Plugin>
T
getPlugin(Class<T> clazz)
          Returns a previously registered plug in instance
 Viewer getViewer()
           
static void main(String[] args)
          Starts the default plug-in viewer
 void registerCustomContent(Content contentPlugin)
          Registers a custom Content plug-in which is an implementation of the abstract class Content
 void registerPlugin(Plugin p)
          Adds a plug-in to this JTViewer's registered plug-ins.
 void registerPlugins(Set<Plugin> pSet)
          Registered a set of plug-ins at once
 void setContent(SceneGraphNode node)
          Sets a content node.
 void setPropertiesFile(File file)
          Sets the properties File of the SimpleController.
 void setPropertiesFile(String filename)
          Sets the properties File of the SimpleController.
 void setPropertiesInputStream(InputStream in)
          Sets the properties InputStream of the SimpleController.
 void setPropertiesResource(Class<?> clazz, String propertiesFileName)
          The provided resource serves 2 purposes: to set the properties File and InputStream via setPropertiesFile(File) (if this resource allows write access) and setPropertiesInputStream(InputStream) (if this resource allows read access), to save and read user decisions about the reading and loading of the property file in a package specific node, via the Java Preferences API.
 void setShowMenuBar(boolean show)
          Show or hide the menu bar
 void setShowPanelSlots(boolean left, boolean right, boolean top, boolean bottom)
          Configures the visibility of the shrink panels slots
 void setShowToolBar(boolean show)
          Show or hide the tool bar
 void startup()
          Starts this JRViewer's controller and installs all registered plug-ins.
 JRootPane startupLocal()
          Starts this JRViewer's controller and installs all registered plug-ins.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JRViewer

public JRViewer()
Create a JRViewer with default scene and lights.


JRViewer

public JRViewer(boolean addLights)
Create a JRViewer with default scene. Flag indicates whether to add the standard lights (plugin Lights) or not.

Parameters:
addLights - if true, standard lights are added.

JRViewer

public JRViewer(JrScene s)
create a JRViewer with a custom scene.

Parameters:
s - the scene
Method Detail

getLastJRViewer

public static JRViewer getLastJRViewer()
Returns the last created instance of JRViewer

Returns:
a JRViewer or null

registerPlugin

public void registerPlugin(Plugin p)
Adds a plug-in to this JTViewer's registered plug-ins. The viewer application is then assembled on startup by these plug-ins.

Parameters:
p -

registerPlugins

public void registerPlugins(Set<Plugin> pSet)
Registered a set of plug-ins at once

Parameters:
pSet - a set of plug-ins

getPlugin

public <T extends Plugin> T getPlugin(Class<T> clazz)
Returns a previously registered plug in instance

Type Parameters:
T -
Parameters:
clazz - the class of the plug-in
Returns:
a plug-in instance or null if no such plug-in was registered

getViewer

public Viewer getViewer()
Returns:
the Viewer of this JRViewer (only works after startup).

setContent

public void setContent(SceneGraphNode node)
Sets a content node. The content node will be added to the scene graph on startup

Parameters:
node -

setPropertiesResource

public void setPropertiesResource(Class<?> clazz,
                                  String propertiesFileName)
The provided resource serves 2 purposes:
  1. to set the properties File and InputStream via setPropertiesFile(File) (if this resource allows write access) and setPropertiesInputStream(InputStream) (if this resource allows read access),
  2. to save and read user decisions about the reading and loading of the property file in a package specific node, via the Java Preferences API.

Parameters:
clazz - the class from which the resource may be obtained, the properties node of the package of this class is used to save the user decisions.
propertiesFileName - name of the resource that contains the plugin properties. This argument may be null, then only the second purpose is served and the properties File and InputStream are NOT set to null and may be set independently.

setPropertiesFile

public void setPropertiesFile(String filename)
Sets the properties File of the SimpleController. This does not overwrite a file chosen by the the user and persisted as user properties.

Parameters:
filename - a file or null
See Also:
setPropertiesResource(Class, String)

setPropertiesFile

public void setPropertiesFile(File file)
Sets the properties File of the SimpleController. This does not overwrite a file chosen by the the user and persisted as user properties.

Parameters:
file - a file or null
See Also:
setPropertiesResource(Class, String)

setPropertiesInputStream

public void setPropertiesInputStream(InputStream in)
Sets the properties InputStream of the SimpleController. If also a properties File is provided the InputStream is used for reading the properties.

Parameters:
in - an InputStream or null
See Also:
setPropertiesResource(Class, String)

getController

public SimpleController getController()
Returns the controller of this JRViewer which is a SimpleController

Returns:
the SimpleController

startup

public void startup()
Starts this JRViewer's controller and installs all registered plug-ins. Not registered but dependent plug-ins will be added automatically.


startupLocal

public JRootPane startupLocal()
Starts this JRViewer's controller and installs all registered plug-ins. Not registered but dependent plug-ins will be added automatically. This method does not open the main window. Instead it returns the root pane.

Returns:
JRootPane with the created viewer

setShowPanelSlots

public void setShowPanelSlots(boolean left,
                              boolean right,
                              boolean top,
                              boolean bottom)
Configures the visibility of the shrink panels slots

Parameters:
left -
right -
top -
bottom -

setShowMenuBar

public void setShowMenuBar(boolean show)
Show or hide the menu bar

Parameters:
show -

setShowToolBar

public void setShowToolBar(boolean show)
Show or hide the tool bar

Parameters:
show -

registerCustomContent

public void registerCustomContent(Content contentPlugin)
Registers a custom Content plug-in which is an implementation of the abstract class Content

Parameters:
contentPlugin - a content plug-in

addContentSupport

public void addContentSupport(JRViewer.ContentType type)
Registers one of the predefined content plug-ins

Parameters:
type - a content enumeration type

addContentUI

public void addContentUI()
Registers advanced content tools. Includes an appearance inspector, transformation tools, and file loaders


addBasicUI

public void addBasicUI()
Basic UI support: scene graph inspector, bean shell, menu bar, view menu (with display options and background color), export menu, camera settings menu, and properties menu.


addVRSupport

public void addVRSupport()
Virtual reality support. A sky box and environment map, a terrain and a movable avatar


addAudioSupport

public void addAudioSupport()
Audio plug-ins. An options panel and audio preferences.


display

public static Viewer display(SceneGraphNode node)
Quick display method with encompass

Parameters:
node -

createJRViewerVR

public static JRViewer createJRViewerVR(SceneGraphNode contentNode)
Create a JRViewer that displays the provided SceneGraphNode in a virtual reality environment with movable avatar etc. (#addBasicUISupport(), #addVRSUpport(), terrain aligned content, ContentAppearance, ContentTools). The created viewer is not started yet, so you need to call startup() on the returned JRViewer.

Parameters:
contentNode - the scene graph component to be displayed or null.
Returns:
the created JRViewer.
See Also:
ViewerVR Manual

encompassEuclidean

public void encompassEuclidean()
Call after startup. Encompasses the view


main

public static void main(String[] args)
Starts the default plug-in viewer

Parameters:
args - no arguments are read

createSceneShrinkPanel

public static SceneShrinkPanel createSceneShrinkPanel(Component c,
                                                      String title)
Deprecated. extend SceneShrinkPanel or ViewShrinkPanelPlugin