Introduction
The plugin infrastructure has been introduced in v0.4.0 of ZGRViewer, and enables the implementation of add-on modules to ZGRViewer. The first plugin that will be made available is ZGRViewer-MPD that makes it possible to plug a second pointing device (such as a trackball) that allows users to control the zoom level (i.e., the camera altitude) with their non-dominant hand, following bi-manual interaction principles (two-handed input). Such modules are distributed as plugins and are not included in the standard ZGRViewer distribution because they impose strong requirements on the environment (Linux + Java 1.5.0 in the case of the ZGRViewer-MPD plugin). The plugin infrastructure by itself requires Java 1.3.x or later.
The plugin infrastructure makes it possible to:
- drop plugin JAR files in the plugins directory, which are automatically detected and loaded by ZGRViewer, without changing the CLASSPATH variable
- configure plugin settings through ZGRViewer's preferences window (a new tab lists all available plugins, each with a button that triggers the display of the plugin's preferences window)
- load and save plugin settings in ZGRViewer's preferences file (zgrviewer.cfg)
- plugins are then more or less free to extend ZGRViewer in any way they want
Implementing a new plugin
Plugins are required to implement interface net.claribole.zgrviewer.Plugin. All plugin-related classes have to be bundleled in JAR files that must be put in ZGRViewer's plugins directory.
The net.claribole.zgrviewer.Plugin interface defines the following methods:
- public void setApplication(ZGRViewer app)
- Called at plugin instantiation time by ZGRViewer, just to give the plugin a hook to ZGRViewer.
- public void terminate()
- Called by ZGRViewer prior to exit. This method can be empty if the plugin does not have anything to clean up before ZGRViewer exits.
- public void loadPreferences(Hashtable settings)
- Called at plugin instantiation time by ZGRViewer, this method provides the plugin with its settings as they were saved in zgrviewer.cfg, as a Java hashtable whose keys and values are String objects that respectively represent a setting's name and its value (as saved in the XML preferences file). The method can be empty if the plugin has no user settings to offer.
- public Hashtable savePreferences()
- Called by ZGRViewer when saving preferences in the preference window. The plugin should provide settings that should be saved as a Java hashtable similar to the one described above. The method can return null if no settings have to be saved.
- public void showSettings()
- Called by ZGRViewer when the user hits the "Settings..." button associated with the plugin in the "Plugins" tab of the Preferences window. A standard way of implementing this method is to implement a subclass of JFrame that call its constructor from this method. The method can be empty if the plugin has no user settings to offer.
- public String getAuthor()
- Return the plugin's author name (return an empty String object if none).
- public String getName()
- Return the plugin's name (return an empty String object if none).
- public String getVersion()
- Return the plugin's version number (return an empty String object if none).
- public java.net.URL getURL()
- Return the plugin's Website as a URL object (can be null).
A full example of use of ZVTM-MPD is available in the Bi-manual interaction plugin for ZGRViewer.
