Scripting the techexplorer Hypermedia Browser

The GraphIT application

This section describes a fictitious on-line course module for understanding the relationship between equations and their graphical representation. This example puts in practice much of the techexplorer Core Java API as well as leverages many of the connections between executable content in a web page.

We start by focusing on the several components of the GraphIT module: the LaTeX course descriptions, GraphIT applet, GraphITControl applet, and the techexplorer display area. We use two techexplorer windows for formatted LaTeX text that describes the module. The GraphIT applet plots curves and is controlled remotely by the GraphITControl applet. The GraphITControl applet provides our first exposure to techexplorer event listeners, namley the techexplorer event listener interface and inter-applet communication. The techexplorer display region is used to dynamically render the equations as they change.

At the end, we put all the pieces together and try out the full GraphIT application.

The techexplorer event listener Java interface

The techexplorer event listener interface provides the support necessary for the one-to-many dependency between techexplorer and appropriately registered Java objects. A techexplorer listener Java object can be an instance of any Java class that implements a techexplorer listener interface:

• techexplorerListener,
• InstanceListener,
• MouseListener,
• MouseMotionListener,
• KeyListener, and
• FocusListener.

When a techexplorer display area changes state, all the java objects that are registered to listen to a particular event are notified of this change through an interface method. A Java object can register for events by using one of the ibm.techexplorer.techexplorer event listener registration methods:

• addtechexplorerListener( techexplorerListener listener ),
• addMouseListener( MouseListener listener ),
• addMouseMotionListener( MouseMotionListener listener ),
• addKeyListener( KeyListener listener ),
• addFocusListener( FocusListener listener ), and
• addInstanceListener( InstanceListener listener ).

Note: Both ibm.techexplorer.plugin.techexplorerPlugin and ibm.techexplorer.control.techexplorerControl are subclasses of ibm.techexplorer.techexplorer for the techexplorer plug-in and ActiveX control respectively.

The relationship between techexplorer and Java classes that implement a techexplorer listener interface are based on the Observer/Subject paradigm used by the Java 1.1 event model. Java 1.1 is not needed in order to use the techexplorer listener mechanism. More information regarding the techexplorer event listener mechanism can be found in the AWTEvent annotated reference.

To avoid dangling references to techexplorer event listeners, the techexplorerPlugin reflection class provides the listener removal methods

• removetechexplorerListener( techexplorerListener listener ),
• removeMouseListener( MouseListener listener ),
• removeMouseMotionListener( MouseMotionListener listener ),
• removeKeyListener( KeyListener listener ),
• removeFocusListener( FocusListener listener ), and
• removeInstanceListener( InstanceListener listener ).

Be sure to call these methods when event notification is no longer needed or a Java object is to be destroyed. The InstanceListener interface is used to notify Java objects that techexplorer is shutting down. This function can be used by techexplorer listeners to guard against dangling references to a techexplorerPlugin reflection instance.

Current Restriction: In this release, techexplorer Java objects can only listen to events that effect the whole document. However, the ibm.techexplorer.awt.event.MouseEvent has been augmented to provide programmatic access to the Document Object Model tree representation of the document.

Inter-Applet communication

The GraphITControl applet can access the GraphIT applet either by looking it up by name (using getApplet()) or by searching all the applets on the page (using getApplets()). Both getApplet() and getApplets() return handles to an Applet object. The GraphITControl applet uses the Applet object returned by getApplet() to invoke methods in the GraphIT applet. Note that an applet has no name by default. In this example we specify the names for the GraphIT and GraphITControl applet in the HTML code as follows:

<APPLET NAME="GraphIT" ARCHIVE="NpExamples.jar" CODE="GraphIT.class" CODEBASE="Java" WIDTH=300 HEIGHT=300 MAYSCRIPT>
  <PARAM NAME="cabbase" VALUE="AxExamples.cab">
  <PARAM NAME="name" VALUE="graphit">
</APPLET>

<APPLET NAME="GraphITControl" ARCHIVE="NpExamples.jar" CODE="GraphITControl.class" CODEBASE="Java" WIDTH=300 HEIGHT=50 MAYSCRIPT>
  <PARAM NAME="name" VALUE="graphitcontrol">
  <PARAM NAME="graphitname" VALUE="graphit">
  <PARAM NAME="cabbase" VALUE="AxExamples.cab">
</APPLET>

The GraphIT Java Applet

The GraphIT applet plots curves in a framed graph area.

import java.awt.*;
import java.applet.Applet;

public class GraphIT extends Applet {
  ...

  public void setParam( int p ) {
     framedGraphArea.setParam( p );
  } 

  public void setCurve( int curveID ) {
     framedGraphArea.setCurve( curveID );
  } 
}

The techexplorer Equation Display

techexplorer is used to display the current equation that is being ploted by the GraphIT applet. techexplorer sends events to the GraphITControl applet. These events are used to toggle between equations.

The following HTML embeds the techexplorer equation display area in a browser window. Note that the web browser object name for the ActiveX control instance of techexplorer is "GraphControl" and the "GraphPlugin" for the plug-in. This name is used by the GraphITControl applet to obtain a handle to the techexplorerPlugin instance.

<OBJECT NAME="GraphControl" CLASSID="clsid:5AFAB315-AD87-11D3-98BB-002035EFB1A4" WIDTH=300 HEIGHT=100>
   <PARAM NAME="DataType" VALUE="0">
   <PARAM NAME="Data" VALUE="\pagecolor{lightgray}\colorbox{white}{Select:\makebox[1.6in][r]{\color{black}\begin{eqnarray}\color{red}y & \color{red}= & \color{red}\sin(x)\\y & = & \cos(x)\end{eqnarray}}}">

   <EMBED NAME="GraphPlugin" TYPE="application/x-techexplorer"
      TEXDATA="\pagecolor{lightgray}\colorbox{white}{Select:\makebox[1.6in][r]{\color{black}\begin{eqnarray}\color{red}y & \color{red}= & \color{red}\sin(x)\\y & = & \cos(x)\end{eqnarray}}}"
      WIDTH=300 HEIGHT=100 >
   </EMBED>
</OBJECT>

The GraphITControl Java Applet

The GraphITControl applet updates the GraphIT and techexplorer display in response to user input by using the slider mechanism shown below:

For information about obtaining cross web browser handles to the ibm.techexplorer.techexplorer instance revisit our discussion, of the Java Editor applet.

public class GraphITControl extends Applet implements techexplorerListener { 
  private Applet             receiver =	null;
  private String             GraphITAppName   = null;
  private GraphIT            GraphITApp       = null;
  private String             GraphITControlAppName = null;
  private techexplorer       techexplorer     = null;

  ...

  public void setPlugin( techexplorer obj )
  {
     if ( obj instanceof techexplorer )
        techexplorer = obj;
     registerListener();
  }

  public void setControl( AxTchExpRaw obj )
  {
     if ( obj instanceof AxTchExpRaw )
         techexplorer = new techexplorerControl( obj );
     registerListener();
  }

  ...

  public void registerListener()
  {
    techexplorer.addtechexplorerListener( (techexplorerListener)this );
    techexplorer.disableEvents( AWTEvent.MOUSE_EVENT_MASK );
  }

  public void start() {
    GraphITControlAppName = getParameter("name");
    GraphITAppName        = getParameter("graphitname");

    // get a handle to the GraphIT applet
    receiver = getAppletContext().getApplet(GraphITAppName);
  }

  ....

  public void destroy() {
    techexplorer.removetechexplorerListener( (techexplorerListener)this );
  }

  ...

The mouseRelease() event is used to decide which equation is being selected by the user in the techexplorer equation display region. The handleEvent() function monitors user events from the Slider component. Both of these methods causes the GraphIT and techexplorer display area to update. The mouseMoved method is used for MouseMotionEvent demonstration purposes.

The updateAll() function sets the appropriate curveID parameters and makes a request to repaint the GraphITControl area. The Java AWT system will handle this event by calling the update() method. By default, the update() method clears the background and calls the paint() method. The GraphITControl applet uses the paint() method to send a new LaTeX string to the techexplorer display area as well as to call the setParam() and setCurve() functions from the GraphIT applet. The GraphITControl applet uses the following Java classes:

Click here for the whole program. Note that since some browsers do not support Java 1.1, the GraphITControl applet is Java 1.0 compliant.

Try out the Java GraphIT application!