GrapherGUI Tutorial

Bo Shi

Ocean Engineering, Vortical flow lab

GrapherGUI is a Java library that allows you to quickly develop graphing utilities. You provide the mathematical functions and the parameters, and the user interface is handled by the library. With only a few lines of code, a Java application or Applet like the one shown below can be created. This document is designed to be a quick tutorial and introductory document to the GrapherGUI package. For more detailed documentation, refer to the source documentation.


Table of Contents
1. A Simple Example
1.1. Step by Step
1.2. The init() Method
1.3. Creating a Function
2. Important Classes
2.1. Overview
2.2. GUI and Graph
2.3. Function
2.3.1. f()
2.3.2. farray()
2.3.3. Example
2.4. AnimationManager
3. Compiling Your Work
3.1. Files
3.2. Compiling
3.3. Alternative Organizational Schemes
3.4. Packaging
4. Advanced Topics
4.1. Code Documentation
4.2. Creating a Standalone Application
4.3. Java and C/C++
4.3.1. The Java Portion
4.3.2. The C portion
4.3.3. The Code
4.4. Java and Fortran
5. Source Files

1. A Simple Example

1.1. Step by Step

The following steps describes the process of creating a graphing tool using GrapherGUI. In the directory where the GrapherGUI library is located, create a file classname.java where classname is an arbitrary name for your application.

  1. Create a SliderMatrix object.

  2. Create up to ten classes which extend the Function class.

  3. Create a GUI object.

  4. Add the GUI object to the Applet

1.2. The init() Method

Web.java creates an Applet. To create a standalone program that does not require a browser to run, minor changes are required. Consult this section. The source code to Web.java can be found here. Following is a description of the important lines of code.

To use the classes provided in the GrapherGUI library, include the package.

import GrapherGUI.*;
			

The class that we have here is called Web. The naming of the class is arbitary. Because we wish to compile this program as an Applet, our main class must extend Applet. When a class extends from Applet, the init() method is required. This is where all the work will be done. Within init(), we need to create instances of the objects described in the previous section.

public class Web extends Applet {   
    public void init() {     
		// ... insert code here ...
    } 
}
			

If you wish to use parameters in your functions, declare a SliderMatrix object. You can add as many parameters as you need and any given function does not have to use all (or any) of the existing parameters. Internally, SliderMatrix keeps a list of ParameterPanel objects. The following is an image of what a ParameterPanel looks like:

The constructor for SliderMatrix takes an integer which will be the maximum number of parameters that can be added. In order to make a parameter available to your functions, you need to use the add() method in the SliderMatrix class. add() takes six parameters:

  1. Minumum parameter value

  2. Maximum parameter value

  3. Starting value

  4. Number of separators on the slider bar

  5. Filename of the image file associated with the parameter (this can be null)

  6. String name associated with parameter (this will be displayed if the image file is null or cannot be found)

Remember that you may only use JPEF, GIF, and PNG (on newer Java VMs). The path to the images is relative to the directory where your main JAR or .class file is located. Take a look at the following 3 lines of code. It declares a SliderMatrix object which stores the values of the parameters. The integer three is passed to the constructor, indicating that a maximum of three (less, possibly) will be used.
SliderMatrix sm = new SliderMatrix(3);

sm.add(-10.0, 10.0, 0.0, 4, "param_h.jpg", "h");
sm.add(5.0, 15.0, 5.0, 4, "param_g.jpg", "g");
			
As you can see, only two are declared. The first is the parameter h. The first two parameters indicate the range of values h can take; [-10,10] in this case. Zero will be the starting value and the slider bar will be divided into 4 sections. This is purely cosmetic and does not effect the behavior of the slider bar. "param_h.jpg" is the image file which is associated with this image and finally, "h" is the string name for this parameter.

We then declare our function objects. This will be covered in another section.

MyFunc1 f1 = new MyFunc1();
MyFunc2 f2 = new MyFunc2();
			

This block of code creates the actual user interface. The interface needs to know the visible range in cartesian coordinates (in this case, the domain is [-2,2] and the range is [-3,10]). The first argument in the constructor for a GUI object is a SliderMatrix object which contains the information about parameters. The second argument takes an AnimationManager object. Don't worry about the details. For now, we will just cover the basics.

GUI gui = new GUI(sm, null, -2.0, 2.0, -3.0, 10.0);
			
The GUI constructor takes 5 arguments:

  1. The SliderMatrix to use for the program

  2. The AnimationManager object. This can be null if you do not want to animate your functions

  3. Minumum x value on the graph

  4. Maximum x value on the graph

  5. Minumum y value on the graph

  6. Maximum y value on the graph

In order to display the functions you have created, use the addFunction() method. This takes one argument of type Function. Remember to initialize your function first before setting it.

gui.addFunction(f1);
gui.addFunction(f2);
			

If you would like to use an icon to label the axes on the graph, use the setAxesIcons() method. This method takes the filenames of the two icons you have. The first argument takes the image file for the independent axes and the second is for the dependent axes.

gui.setAxesIcons("axis_x.jpg", "axis_y.jpg");
			

The GUI class extends from JPanel, so it can be treated as such. To add the GUI to the Applet window, use the add() method in the Applet class.

add(gui);
			

1.3. Creating a Function

In this section, we will run through the creation of a very simple class which inherits from the built-in Function class. You will need to do this for each function you wish to plot. Here's the code for the very simple function x^3 * h / g

class MyFunc1 extends Function {
    public short type() {
        return Function.FCNTYPE_SINGLEVAL;
    }

	public Color color() {
		return Color.green;
	}

    public String name() {
        return "Test";
    }

    public double f(double x, SliderMatrix p) {
        double g, h;

        try {
            g = p.val("g");
            h = p.val("h");
        } catch (Error e) {
            return 0.0;
        }

        return x * x * x * h / g;
    }

    public void farray(
            double minx,
            double maxx,
            int density,
            double[] a,
            double[] b,
            SliderMatrix p) {}
}
			

We have five methods defined, four of which are required. All of them interact with the internal classes. This class is not required to only contain these methods; you can add however many helper methods you wish.

public short type() {
	return Function.FCNTYPE_SINGLEVAL;
}
			
The type() method tells GrapherGUI how you are going to define a function. This method should always only be one line long, as its only job should be to return a short integer. Two return values are predefined for you in Function. These are FCNTYPE_SINGLEVAL and FCNTYPE_FARRAY. Our type() method tells the program that this function uses f() to define the function.

public Color color() {
	return Color.green;
}
			
This method overrides a default method in Function. You can use one of a dozen or so built in colors (red, green, blue, etc) or you can define a RGB (color definition based on separate red-green-blue values) color to return:
return (new Color(255, 0, 255));
			
The above defines the color magenta. The values range from 0-255. There are other available constructors to choose from. You may omit this method from your class definition. If you do, the function will take on the default blue color.

public String name() {
	return "Test";
}
			
This is the identifying string that will show up in the legend.

This is where we actually define the function. f() takes two arguments, an independent variable x and a SliderMatrix which contains parameter information. It should return the dependent value for f(x)

public double f(double x, SliderMatrix p) {
	/* Declare any parameters you will need for this function
	 * before you try to extract them.
	 */
	double g, h;

	try {
		/* Since the val() method in SliderMatrix throws an error if
		 * it cannot find the parameter you specify, you need to catch
		 * that error.  The try-catch control structure does this.
		 */
		g = p.val("g");  // get parameter "g"
		h = p.val("h");  // get parameter "h"
	}
	catch (Error e) {
		/* All error handling should go within this block.
		 */
		return 0.0;
	}

	/* After you have extracted the current value of the parameters
	 * required for calculating this function, and handled all errors
	 * that have occurred, you need to write the code that calculates
	 * the dependent value:
	 *
	 * (here, since our function is very simple, we have just placed
	 * the function in one line.  You can use as much space as you
	 * like as long as you return the value in the end)
	 */
	return x * x * x * h / g;
}
			

Now you should be able to construct a simple plotting program just by cutting and pasting the code snippets in this tutorial. For more advanced techniques, read on.