JWAVE Graphics

This chapter explains how client applications can display graphics returned from PV-WAVE. The following JWAVE classes are used in graphical client applications:

• JWaveView

• Viewable

• JWaveCanvas

These classes are described in this chapter and in the Javadoc reference for JWAVE. For information on Javadoc, see Using the JWAVE Javadoc Reference.

Returning Graphics to the Client

In Example 1-1 on page 14 we demonstrated a simple JWAVE application that returned a numerical result to the client. To accomplish this, we used a JWaveExecute object. The JWaveExecute class provides methods for setting and getting parameters (and data) and executing JWAVE wrapper functions on the server; however, a JWaveExecute object can only retrieve numerical and string data returned from the client. If you want your client to retrieve graphical information from the server, then you must use a JWaveView object.

The JWaveView class is a subclass of the JWaveExecute class. Unlike JWaveExecute, JWaveView gets a Viewable object from the server. The Viewable object is returned by the JWAVE wrapper function automatically if the wrapper created some graphics (such as with the PLOT command). The JWaveCanvas class simply provides a canvas for displaying a Viewable object.

Figure 4-1 shows a typical JWAVE scenario where graphical data is created on the server and returned to the client.

---

TIP: In this example, data is physically returned from the server to the client. A more efficient method of handling the data is with a data proxy object. For more information on data proxies, see Chapter 6, Managing Data.

---

Example 4-1 shows the basic client methods needed to display a Viewable object returned from a JWAVE wrapper function. Remember that if the JWAVE wrapper generates graphics (for example, if the wrapper calls the PLOT procedure), then the wrapper automatically returns a Viewable object to the client application. The client application can then display the Viewable object with a JWaveCanvas object.

Example 4-1 JWaveCanvas used to display a Viewable object

// The JWaveCanvas object will display the Viewable object. 
myCanvas = new JWaveCanvas(); 
// Create a JWaveView object for the myWrapper wrapper function. 
myJWV = new JWaveView("myWrapper");
// Set the size of the Viewable object. 
myJWV.setViewSize( myCanvas.getSize() );
try { 
    // Execute the JWAVE wrapper function. 
    myJWV.execute();
    // Specify the Viewable object to be displayed in this canvas.
    // The setViewable method also repaints the canvas with the 
specified 
    // Viewable object. 
    myCanvas.setViewable( myJWV.getViewable() );
} catch (JWaveException ignore) { }

Example 4-2 lists a Java client program that displays a 2D plot generated by PV-WAVE. Example 4-3 lists the JWAVE wrapper that creates the 2D plot.

---

TIP: Example 4-2 (the client Java program) is similar to (but a simplified version of) the demonstration program ViewTest.java, which you can find in:

---

(UNIX)VNI_DIR/classes/jwave_demos/tests

(Windows)VNI_DIR\classes\jwave_demos\tests

The actual code for Example 4-2, SimpleView.java, can be found in:

(UNIX)VNI_DIR/classes/jwave_demos/doc_examples

(Windows)VNI_DIR\classes\jwave_demos\doc_examples

Example 4-3, SIMPLE_VIEW (the JWAVE wrapper), can be found in:

(UNIX)VNI_DIR/jwave-3_0/lib/user/simple_view.pro

(Windows)VNI_DIR\jwave-3_0\lib\user\simple_view.pro

where VNI_DIR is the main Visual Numerics installation directory.

Again, the key classes used in the client Java program are:

• JWaveView class Extension of the JWaveExecute class, used for graphics.

• JWaveCanvas class Creates a canvas to display a Viewable object.

• Viewable class Contains any graphics returned from PV-WAVE.

Figure 4-2 shows the plot that is displayed on the client.

import com.visualnumerics.jwave.*;
import java.awt.*;
import java.awt.event.*;

public class SimpleView {

   public static void main(String[] argsNotUsed) {
      SimpleView me = new SimpleView();
   }


   /** Construct application */
   public SimpleView() {

            Frame f = new Frame("Simple JWaveView Example");

            // so Exit button (window menu) will work
            f.addWindowListener( new WindowAdapter() {
                    public void windowClosing(WindowEvent e) {
                          System.exit(0);
                    }
          } );

      // Add a JWaveCanvas to the frame
      f.setSize(300,300);
      viewCanvas = new JWaveCanvas();
      f.add(viewCanvas);

      f.setVisible(true);

      // Make the plot, fill the canvas
      doPlot();
        }

   /** Canvas on which to draw */
   JWaveCanvas viewCanvas;

   /** Make plot on canvas */
   public void doPlot() {

      try {
                  // Use SIMPLE_VIEW wrapper function
                  JWaveView command = new JWaveView("SIMPLE_VIEW");

                  // Set view size same as canvas
                  command.setViewSize( viewCanvas.getSize() );

                // Set some colors and parameters
                command.setNamedColor("BACKGROUND", Color.white);
                command.setNamedColor("COLOR", Color.black);

                command.setParam("GRIDSTYLE", 1); // dotted lines for grid
                command.setParam("TICKLEN", 0.5); // full grid
                command.setParam("Y", 500); // Number of data points

                // Execute the command
                command.execute();

                // Retrieve the Viewable and give it to the JWaveCanvas
                // JWaveCanvas repaints when it gets a new Viewable
                viewCanvas.setViewable( command.getViewable() );

                // Close connection, as we are done with the session
                command.getConnection().shutdown();

      } catch (Exception e) {
                  System.out.println(e);
      }
        }
}

FUNCTION SIMPLE_VIEW, client_data
   ; Retrieve parameter data
   n = GETPARAM(client_data, 'Y', /Value, Default = 100)
   grid = GETPARAM(client_data, 'GRIDSTYLE', /Value, Default = 0)
   tick = GETPARAM(client_data, 'TICKLEN', /Value, Default = 0.2)
   back = GET_NAMED_COLOR('BACKGROUND', Default = '000000'xL)
   fore = GET_NAMED_COLOR('COLOR', Default = 'ffffff'xL)
   ; Generate some "data" - n points
   vals = RANDOMN(seed, n)
   ; Make the plot
   PLOT, vals, Ticklen = tick, GridStyle = grid, $
     Background = back, Color = fore
      ; Return the data (default data name DATA).
      ; Note that this data is returned in addition to the Viewable 
object.
   RETURN, vals
END

Resizing Graphics

The Viewable class supports resizing of the Viewable object. The default resize behavior is NOT_RESIZEABLE. This means that the Viewable object will always be drawn at its "natural" size (as generated by PV-WAVE), regardless of the size of the Component it is drawn into.

You may want to use Viewable.setPreferredResizeMode with either RESIZEABLE or PRESERVE_ASPECT if your Component is resizable. These modes allow the Viewable object to draw a scaled version of the plot into any size Component. The PRESERVE_ASPECT will resize the Viewable object, but only as much as is possible while maintaining the original (as generated by PV-WAVE) aspect ratio of the Viewable object.

Coordinate System Transformations

The Viewable class also supports coordinate system transforms. PV-WAVE automatically communicates the data coordinates and 3D transform used to generate the plot, and a Viewable object can use these to do coordinate transforms.

The two methods transformToPoint and transformToData can be used to transform between the plot's data coordinates and a java.awt.Point object.

For example, to print the data coordinates where a user clicks on the plot, you might do the following:

  double[] d = myViewable.transformToData( theClickPoint ); 
  System.out.println( "Click at ("+ d[0] +", "+ d[1] +")" );

You can determine the boundary of the data area (usually, this boundary is the plot's axes) using the getDataBounds method. For example, to determine if a Point object is inside the plot bounds:

 if ( myViewable.getDataBounds().contains( myPoint ) ) { ... }

Note that (due to lossy conversion) the transformToData method is only useful for plots with 2D data coordinates (that is, X vs. Y plots). To test for this condition, use the has2DCoordinates method.

(UNIX)VNI_DIR/classes/jwave_demos/tests

(Windows)VNI_DIR\classes\jwave_demos\tests

Demonstration Programs

You can find other demonstration JWAVE graphics applications in:

(UNIX)VNI_DIR/classes/jwave_demos

(Windows)VNI_DIR\classes\jwave_demos

Summary

This chapter introduced the primary graphics classes for JWAVE. You can read more about these classes and their methods in the JWAVE Javadoc reference. For information on Javadoc, see Using the JWAVE Javadoc Reference.