JChart v1.1 documentation

What's JChart?

JChart is a good piece of code by Roberto Piola ;-) ; it was born as an applet for displaying some data on a web page, in a manner similar to what gnuplot does on any machine (and M$ Excel does on a PC): histograms, plots, and so on.

In the following, I manipulated the code and I extended it, reducing the core of JChart to a reusable component, and obtaining an applet and a stand-alone application as by-products. The data can be passed as a file name, as a data structure or as an URL, and they can be visualized in several alternative ways.

Using JChart

The component classes are released in Java byte-code form for personal use; if you need them for commercial use, or if you need a modified version, you should contact me.

Support site

The official support site for JChart is http://www.ilpiola.it/roberto/jchart.

The component

The main class is JChart, a descendant of Panel; usually, in order to use it, you should instantiate it by passing to the constructor a reference to the data file and the parameters for the visualization, and then you'll have to add() it to a frame, a dialog box...

The basic constructor is:

  JChart(JChartDataset dataset,
         String title,
         int width,
         int height,
         int leftborder,
         int lowerborder,
         int rigtborder,
         int upperborder,
         String type, 
         String xaxis,
         String yaxis,
         Font labelfont, 
         Font titlefont, 
         Font axisfont, 
         int barsize;
         int labelserie,
         int printvalues,
         int minyatzero,
         Color backgroundcolor,
         Color axiscolor,
         Color labelcolor,
         Color[] linecolor,
         boolean showxextremes,
         boolean showyextremes
         )

dataset: is a structure filled with data (see forward)
title: is a title for the chart (it may be null)
width,height: are the dimension for the plotting area
leftborder,lowerborder,rigtborder,upperborder: are the distances from the border of the canvas to the border of the chart
type: can be one of "HISTOGRRAM", "PIE", "LINES", "POINTS", "LINEPOINTS"
xaxis,yaxis: are the labels for the axis
labelfont,titlefont,axisfont: are the fonts that will be used for the different parts of the chart
barsize: it represents the width of bars in a histogram, expressed as a percentage of the available space (usually, a value between 50 and 80 is a good choice
labelserie: when using more than one series of data, labelserie will select which serie will be used for labeling the columns; use 0 for none/all
printvalues: if it is 1, then the values will be printed on top of the bars; otherwise, set it at 0
minyatzero: if it is 0, then the x axis will be positioned at y=0; otherwise, it will be plot either at the bottom of the graph (ath the minimum y) or at y=0
backgroundcolor,axiscolor,labelcolor: colors to be used around the graph...
linecolor: this array must hold as many colors as there are data series to be plotted (for LINES, POINTS and LINESPOINTS), or as many colors you want to use for the PIE
showxextremes,showyextremes: these flags tell JChart whether placing labels with the values at the extremes of the axis or not

In addition to that, some other useful constructors are provided:

  JChart(String filename,
         int ncolumns,
         String title,
         ...
         )

that parses a file, expecting to find ncolumns columns of data in it (see the format of the input file, a bit later).

  JChart(URL url,
         int ncolumns,
         String title,
         ...
         )

the same, but on the network... the URL can open a remote file on a web server or can start with a GET method a cgi-bin that retrieves and pumps the data.

  JChart(InputStream is,
         int ncolumns,
         String title,
         ...
         )

the abstract version...

The format of the input files

The input files/streams are simple text files, containing columns of numbers separated by simple spaces, e.g.:

Each column can be regarded as a series of data (to be plotted as a different line in LINES, POINTS, LINEPOINTS graphs).

The JChartDataset structure

It was intended for internal use only, but if you want to REALLY use it, it is a container for a linked list of JChartDatasetElement, each of which contains a vector of floats...

class JChartDataset
{
  JChartDatasetElement dati; /* the data chain */
  int nelem; /* the length of the chain */
  int ncolumns; /* the number of columns */
  ...
}

class JChartDatasetElement
{
  float dato[]; /* the data */
  String lbl; /* a label */
  JChartDatasetElement next;
  ...
}

If you want to use it, you need to extend it with some other constructor; for this reason, the source code is included.

The application

Please take a look at the included application, JChartTest.java, for a simple example of an application that uses JChart: it simply accepts three arguments: a file name, the number of columns that JChart should expect in it and a chart type, and then displays a window with a chart and a Dismiss button.

The applet

The applet, JChartApplet.java, is slightly more complex, since it parses a set of PARAM tags:

Please refer to the demo page for an example.