JXGraph provides a component which can display one or more plots on top of a graduated background (or grid.)
To help analyze the plots, this component allows the user to pan the view by left-clicking and dragging the mouse around. Using the mouse wheel, the user is also able to zoom in and out. Clicking the middle button resets the view to its original position.
All user input can be disabled by calling {@link #setInputEnabled(boolean)} and passing false. This does not preventsubclasses from registering their own event listeners, such as mouse or key listeners.
Whenever a new instance of this component is created, the grid boundaries, or view, must be defined. The view is comprised of several elements whose descriptions are the following:
The default constructor defines a view bounds by -1.0 and +1.0 on both axis, and centered on an origin at (0, 0).
To simplify the API, the origin can be read and written with a Point2D instance (see {@link #getOrigin()} and{@link #setOrigin(Point2D)}.)
Likewise, the view can be read and written with a Rectangle2D instance (see {@link #getView()} and{@link #setView(Rectangle2D)}.) In this case, you need not to define the maximum boundaries of the view. Instead, you need to set the origin of the rectangle as the minimum boundaries. The width and the height of the rectangle define the distance between the minimum and maximum boundaries. For instance, to set the view to minX=-1.0, maxX=1.0, minY=-1.0 and maxY=1.0 you can use the following rectangle:
new Rectangle2D.Double(-1.0d, -1.0d, 2.0d, 2.0d);
You can check the boundaries by calling Rectangle2D.getMaxX() and Rectangle2D.getMaxY() once your rectangle has been created.
Alternatively, you can set the view and the origin at the same time by calling the method {@link #setViewAndOrigin(Rectangle2D)}. Calling this method will set the origin so as to center it in the view defined by the rectangle.
By default, the component defines a spacing of 0.2 units between two major grid lines. It also defines 4 minor grid lines between two major grid lines. The spacing between major grid lines and the number of minor grid lines can be accessed through the getters {@link #getMajorX()}, {@link #getMajorY()}, {@link #getMinorCountX()} and{@link #getMinorCountY()}.
You can change the number of grid lines at runtime by calling the setters {@link #setMajorX(double)}, {@link #setMajorY(double)}, {@link #setMinorCountX(int)} and {@link #setMinorCountY(int)}.
Although it provides sensible defaults, this component lets you change its appearance in several ways. It is possible to modify the colors of the graph by calling the setters {@link #setAxisColor(Color)}, {@link #setMajorGridColor(Color)} and {@link #setMinorGridColor(Color)}.
You can also enable or disable given parts of the resulting graph by calling the following setters:
The following code snippet creates a new graph centered on (0, 0), bound to the view [-1.0 1.0 -1.0 1.0], with a major grid line every 0.5 units and a minor grid line count of 5:
Point2D origin = new Point2D.Double(0.0d, 0.0d); Rectangle2D view = new Rectangle2D.Double(-1.0d, 1.0d, 2.0d, 2.0d); JXGraph graph = new JXGraph(origin, view, 0.5d, 5, 0.5d, 5);
A plot is defined by a mathematical transformation that, given a value on the graph's X axis, returns a value on the Y axis. The component draws the result by plotting a spot of color at the coordinates defined by (X, f(X)) where f() is the aforementionned mathematical transformation. Given the following transformation:
f(X) = X * 2.0
For X=1.0, the component will show a spot of color at the coordinates (1.0, 2.0).
Every plot drawn by the component must be a subclass of {@link JXGraph.Plot}. This abstract public class defines a single method to be implemented by its children:
public double compute(double value)
The previous example can be defined by a concrete JXGraph.Plot as follow:
class TwiceTheValuePlot extends JXGraph.Plot { public double compute(double value) { return value * 2.0d; } } Most of the time though, a plot requires supplementary parameters. For instance, let's define the X axis of your graph as the mass of an object. To compute the weight of the object given its mass, you need to use the acceleration of gravity (w=m*g where g is the acceleration.) To let the user modify this last parameter, to compute his weight at the surface of the moon for instance, you need to add a parameter to your plot.
While JXGraph.Plot does not give you an API for such a purpose, it does define an event dispatching API (see {@link JXGraph#firePropertyChange(String,double,double)}.) Whenever a plot is added to the graph, the component registers itself as a property listener of the plot. If you take care of firing events whenever the user changes a parameter of your plot, the graph will automatically update its display. While not mandatory, it is highly recommended to leverage this API.
To add a plot to the graph, simply call the method {@link #addPlots(Color,JXGraph.Plot)}. You can use it to add one or more plots at the same time and associate them with a color. This color is used when drawing the plots:
JXGraph.Plot plot = new TwiceTheValuePlot(); graph.addPlots(Color.BLUE, plot);
These two lines will display our previously defined plot in blue on screen. Removing one or several plots is as simple as calling the method {@link #removePlots(JXGraph.Plot)}. You can also remove all plots at once with {@link #removeAllPlots()}.
If you need to add more information on the graph you need to extend it and override the method {@link #paintExtra(Graphics2D)}. This method has a default empty implementation and is called after everything has been drawn. Its sole parameter is a reference to the component's drawing surface, as configured by {@link #setupGraphics(Graphics2D)}. By default, the setup method activates antialising but it can be overriden to change the drawing surface. (Translation, rotation, new rendering hints, etc.)
To properly draw on the graph you will need to perform a translation between the graph's coordinates and the screen's coordinates. The component defines 4 methods to assist you in this task:
If you have defined a graph view centered on the origin (0, 0), the origin of the graph will be at the exact center of the screen. That means the world coordinates (0, 0) are equivalent to the pixel coordinates (width / 2, height / 2). Thus, calling xPositionToPixel(0.0d) would give you the same value as the expression getWidth() / 2.0d.
Converting from world coordinates to pixel coordinates is mostly used to draw the result of a mathematical transformation. Converting from pixel coordinates to world coordinates is mostly used to get the position in the world of a mouse event.
@see JXGraph.Plot @author Romain Guy | |