RCHART TUTORIAL, Chapter 11

Copyright 2003, J4L Components (http://www.java4less.com)
Go bak to contents

The Java[TM] API

• Chart creation process.
• The chartLoader.
  
• Exporting the chart to gif , png or jpg.
• Chart Listener (implementing tips and actions)
• Updating the chart
• Recompiling Rchart

Chart creation process

We recommend you to create charts using the parameters provided by RChart Visual Builder, however if you need it you can create charts using the Java[TM] api (see Java[TM] documentation in the Javadoc[TM] subdirectory of your installation).

The process is:

Note about vertical labels: if you want the chart to paint vertical labels you must set a value for the chart.tmpImage propertiy like this:

chart.tmpImage=new java.awt.image.BufferedImage(300,300,java.awt.image.BufferedImage.TYPE_BYTE_INDEXED);

this image is used by RChart for text rotation.

The Bean and the chartLoader

You can use the bean to create your charts using the parameters created by RChart Visual Builder:

import com.java4less.rchart.*;

public class test{
public test() {
}
public static void main(String[] args) {
try {

com.java4less.rchart.JChartBean cha=new com.java4less.rchart.JChartBean();
// Set parameters
cha.setParameter("TITLECHART","Sales 1999");
cha.setParameter("LEGEND_FILL","WHITE");
cha.setParameter("LEGEND_VERTICAL","FALSE");
cha.setParameter("LEGEND_BORDER","0.2|0x0|NORMAL");
cha.setParameter("SERIE_1","Pie");
cha.setParameter("SERIE_TYPE_1","PIE");
cha.setParameter("SERIE_FONT_1","ARIAL|BOLD|12");
cha.setParameter("SERIE_DATA_1","94|48|28");
cha.setParameter("PIE_NAME_1","Products");
cha.setParameter("PIE_NAME_2","Services");
cha.setParameter("PIE_NAME_3","Other");
cha.setParameter("PIE_STYLE_1","RED");
cha.setParameter("PIE_STYLE_2","BLUE");
cha.setParameter("PIE_STYLE_3","GREEN");
cha.setParameter("PIECHART_3D","true");
cha.setParameter("PIE_LABEL_FORMAT","#VALUE# (#PERCENTAGE#)");
cha.setParameter("SERIE_LABELS_1","Products|Services|Other");
cha.setParameter("SERIE_TOGETHER_1","true|false|true");
cha.setParameter("LEGEND_POSITION","TOP");
cha.setParameter("LEGEND_MARGIN","0.3");
cha.setParameter("CHART_BORDER","0.2|0x0|NORMAL");
cha.setParameter("CHART_FILL","0x99cccc");

/* process parameters and create chart*/
cha.buildChart();
cha.setChartSize(300,300);

/* create png file */
cha.saveToFile("chart.png","PNG");
}

catch(Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
}

You can also read the parameters directly from a file:

import com.java4less.rchart.*;

public class test{
public test() {
}
public static void main(String[] args) {
try {

com.java4less.rchart.JChartBean cha=new com.java4less.rchart.JChartBean();
// Set parameters
cha.setDataFile("examples\\piechart3D.txt"); // this can also be a url like http://www.myserver.com

/* process parameters and create chart*/
cha.buildChart();
cha.setChartSize(300,300);

/* create png file */
cha.saveToFile("chart.png","PNG");

}

catch(Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
}

or you can directly use the chartLoader instead of JChartBean:

com.java4less.rchart.chartLoader loader=new com.java4less.rchart.chartLoader(null);

/* load file, use file://*/
loader.loadFromFile("file://c:\\exp\\test\\examples\\piechart3D.txt",true);

/* create chart*/
chart=loader.build(false,false);
/* set size*/
chart.setSize(400,400);
/* create image file */
chart.saveToFile("chart.png","PNG");

In all cases the steps are:

1. Create the bean object or chart loader..
2. Set the parameters or load them from file
3. build the chart

Exporting the chart to gif, png or jpg

RChart can create the following image files: JPG, PNG and GIF. This can be done by executing chart.saveToFile(filename,format), where format can be "JPG", "PNG" of "JPG".

The JPG format is supported by the Java[TM] virtual machine 1.2 or later. The other two formats require you to install a third party package:

• PNG (from Walter Brameld , wbrameld4@yahoo.com): download it from http://209.51.137.74/pngencoder-1.0.jar
• GIF: download gif encoder from http://www.acme.com/resources/classes/Acme.tar.gz

You must download one of those packages and include them in your classpath.

You can also use other encoders, In that case the source code would look mode or less like this:

// create image
java.awt.image.BufferedImage image = new java.awt.image.BufferedImage( chart.getSize().width,chart.getSize().height,java.awt.image.BufferedImage.TYPE_INT_RGB );

java.awt.Graphics imgGraphics = image.createGraphics();

// paint chart on image
chart.paint(imgGraphics );

// open file
java.io.File f=new java.io.File(filename);
f.delete();
java.io.FileOutputStream outb=new java.io.FileOutputStream(f);

// encode image using your encoder
com.company.Enconder encoder= new com.company.Enconder(ChartImage ,outb);
encoder.encodeImage();

Chart Listener (implementing tips and actions)

ChartApplet provides some interative features like tips and html links that are not available in the Chart class. If you need to add this features in your Java[TM] applications you can easily doing by looking at the source code ChartApplet.java.

We now describe how this works:

RChart provides a "ChartListener" interface so that user applications (your application) can access the chart's painting area. Each time the chart is repainted, the following method is executed:

public void paintUserExit(Chart c,Graphics g)

in this method you can paint for example a "tip box" at the current possition of the cursor. For example, the applet does it like this:

g.setColor(loader.tipColor); // set color
g.fillRect(c.currentX,c.currentY-(he*tip.length),wi,he*tip.length); // paint box
g.setColor(loader.tipFontColor); // border
g.drawRect(c.currentX,c.currentY-(he*tip.length),wi,he*tip.length); // paint border

for (int h=0;h<tip.length;h++) // paint string, tips (several lines)
g.drawString(tip[h],c.currentX+2,c.currentY-4-(he*(tip.length-h-1)));

As you can see you can use the Graphics object "g" to paint on the chart area. Before you do this you need to know the current possition of the cursor. The possition is available in the currentX and currentY properties of the chart object (variable c).

To sum up:

1. Your class must implement the ChartListener interface
   
   public class yourClass implements ChartListener
   
   
2. You must set your class as listener of the chart:
   
   chart.setChartListener(yourClass);

If you need to take an action when the user clicks on a point or bar of you chart, then you must add a MouseListener to the chart. Remember that the chart is a Canvas object which will be contained in one of your frames or panels.

The mouseClicked() event will then be triggered when the user clicks on the chart. In this method you must decide what to do:

// find selected/clicked serie
for (int i=0;i<loader.pSeriesNames.length;i++)
if (loader.pSeriesNames[i]!=null)
if (loader.pSeriesNames[i].compareTo(loader.gChart.selectedSerie)==0)

// serie found
if (loader.htmlLinks.length>i)
if (loader.htmlLinks[i]!=null)
if (loader.htmlLinks[i].length>loader.gChart.selectedSeriePoint)
// found html link for the selected point
if (loader.htmlLinks[i][loader.gChart.selectedSeriePoint].length()>0)
try {
// open html link in browser
this.getAppletContext().showDocument(new java.net.URL(loader.htmlLinks[i][loader.gChart.selectedSeriePoint]),loader.htmlLinkTarget);
break;
} catch (Exception e1) {System.out.println(e1.getMessage());}

This code of the applet checks whether the user has clicked on any bar or point. In order to check this, you can use the following properties:

• chart.selectedSerie: name of the selected (clicked) serie, if any
• chart.selectedSeriePoint: selected point (1=first value of the serie, 2=second value and so on).

Updating the chart

ChartApplet has a feature which allows you to update the chart every X second with new data. This feature is however only available in the applet, but it can be also implemented in the Chart class.

If you need to update you chart with new data you have 2 possibilites:

1. Rebuild a whole new chart every time you have new data. This is the way the applet does it.
   
   com.java4less.rchart.chartLoader loader=new com.java4less.rchart.chartLoader(null);

   loader.loadFromFile("file://c:\\examples\\piechart3D.txt",true);
   
   /* create png file */
   loader.build(false,false);
   loader.gChart.setSize(400,400);
   loader.gChart.saveToFile("chart1.png","PNG");
   
   /* updates values and create a new file*/
   loader.setParameter("SERIE_DATA_1","94|48|40");
   loader.build(false,false);
   loader.gChart.saveToFile("chart2.png","PNG");
   

2. Or you can use the the replaceSerie() method of the Plotter to set new values for you serie:
   
   chart.plotters[0].replaceSerie(0,yourDataSerie);
   
   the first 0 means you want to replace a serie in Plotter 0 (normally you only have 1 plotter). The second 0 means you want to replace the first serie in the given plotter.
   
   /* create png file */
   loader.build(false,false);
   loader.gChart.setSize(400,400);
   loader.gChart.saveToFile("chart1.png","PNG");
   
   /* updates values and create a new file*/
   double[] values={94,48,40};
   FillStyle[] styles={new FillStyle(java.awt.Color.red),new FillStyle(java.awt.Color.blue) ,new FillStyle(java.awt.Color.green) };
   String[] labels={"Products","Services","Other"};
   boolean[] detached={true,false,true};
   // create serie
   PieDataSerie newSerie=new PieDataSerie(values,styles,detached,labels);
   // update serie
   loader.gChart.Plotters[0].replaceSerie(0,newSerie);
   loader.gChart.saveToFile("chart2.png","PNG");

We only recomment to use approach 2 if you are going to update values, not change the number of values to plot. In the second case you may need to update the scale or the labels, it depends on your chart.

Recompiling RChart

In order to recompile RChart you can use the mini-chart feature inside RChart Visual Builder, or you can use your favorite Java[TM] IDE.

If you want to compile from the command line you must do it like this:

1. unzip all source code files in a empty directory: rchasr.zip and rchaglsr.zip. Note that you must unzip it with subdirectories, so you will get the source code under "DIRECTORY/com/java4less/rchart".
2. Now execute the following command using "DIRECTORY" as working directory:

   c:\jdk1.4.1\bin\javac -classpath c:\jdk1.4.1\jre\lib\jaws.jar -sourcepath . com/java4less/rchart/*.java
   

   you must replace "c:\jdk1.4.1\" with the correct JDK[TM] directory (it does not have to be version 1.4.1).

   In order to recompile the servlet files you must execute:

   c:\java\jdk1.4.1\bin\javac -classpath c:\tomcat41\common\lib\servlet.jar -sourcepath . RChartServlet.java RChartMapServlet.java

   Note that you need "servlet.jar". This can for example be found in tomcat ("c:\tomcat41\common\lib\servlet.jar");