RCHART, User Guide

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

The Chart API


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 API (see the Java documentation in the javadoc subdirectory of your installation).

The process is:

1. Import RChart package import com.java4less.rchart.*;
import com.java4less.rchart.gc.*;
2. Create the title Title title=new Title("Sales (thousands $)")
3. Create the axis you need (depends on the chart, for example piecharts do not have axis) com.java4less.rchart.Axis XAxis=new Axis(Axis.HORIZONTAL,new Scale());
com.java4less.rchart.Axis YAxis=new Axis(Axis.VERTICAL,new Scale());
4. Create the legend Legend l=new Legend();
l.addItem("Products",new FillStyle( GraphicsProvider.getColor(ChartColor.BLUE)) ));
l.addItem("Services",new FillStyle( GraphicsProvider.getColor(ChartColor.GREEN)) ));
5. Create the axis labels

XLabel= new HAxisLabel("", GraphicsProvider.getColor(ChartColor.BLUE)), GraphicsProvider.getFont("Arial",ChartFont.BOLD,14));

YLabel= new VAxisLabel("Brutto", GraphicsProvider.getColor(ChartColor.BLACK)),new GraphicsProvider.getFont("Arial",ChartFont.BOLD,14));

6. create the plotter (or plotters if you combine lines and bars) LinePlotter3D plot=new LinePlotter3D();
7. create the chart and set properties (labels,legend) com.java4less.rchart.Chart chart=new Chart(title,plot,XAxis,YAxis);
8. create the data series double[] d1={1,1,3,3.5,5,4,2};
LineDataSerie data1= new LineDataSerie(d1,new LineStyle(0.2f, GraphicsProvider.getColor(ChartColor.BLUE)) ,LineStyle.LINE_NORMAL));
9. add serie to chart chart.addSerie(data1);



The ChartLoader

You can use the chart loader to create the charts using the parameters created by RChart Visual Builder in this way:

import com.java4less.rchart.*;

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

ChartLoader loader=new ChartLoader();
// Set parameters
loader.setParameter("TITLECHART","Sales 1999");
loader.setParameter("PIE_LABEL_FORMAT","#VALUE# (#PERCENTAGE#)");

/* process parameters and create chart*/
Chart chart=loader.buildChart(false,false);

/* create png file */

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 {

ChartLoader loader=new ChartLoader();
// Set parameters
loader.setDataFile("examples\\piechart3D.txt"); // this can also be a url like http://www.myserver.com or file:///....

/* process parameters and create chart*/
Chart chart=loader.buildChart(false,true); // true means read data file

/* create png file */


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


In all cases the steps are:

  1. Create the chart loader
  2. Set the parameters or load them from file
  3. build the chart
  4. export the chart to an image file or display it using a Chart Viewer (see next sections)


Displaying the chart (Chart viewer)

RChart includes ready to use classes for displaying charts in Java applications. There are 3 different Chart Viewer for Swing , SWT and AWT:



Exporting the chart to gif, png , jpg or bmp

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


If you are using AWT or Swing you can use the GIF, JPG and PNG format.
The JPG format is supported by Sun's java virtual machine 1.2 or later. The other two formats require you to install a third party package:

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 like this:

// create image
java.awt.image.BufferedImage image = new java.awt.image.BufferedImage( chart.getWidth(),chart.getHeight(),java.awt.image.BufferedImage.TYPE_INT_RGB );

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

// paint chart on image
ChartGraphics chartGraphics=GraphicsProvider.getGraphics(imgGraphics)
chart.paint( chartGraphics );

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

// encode image using your encoder
com.company.Enconder encoder= new com.company.Enconder(image ,outb); // encode the image to the output stream


If you are using SWT, you can use the JPG, GIF and BMP formats. No external packages are required.


Updating the chart and realtime updates

There is a way to force RChart to rebuild itself every X seconds. In this way you can create charts that will get updated with realtime data. For example you can let RChart read new data from a given URL or file every 5 seconds. Look at the same application provided with the product to see a complete working example.

The following example shows how to let RChart be updated every 5 seconds and load new data from a given URL.

Chart chart=cloader.build(false,false);

ChartViewer chartViewer=new ChartViewer(shell,SWT.NONE);


// set up realtime update
chart.msecs=5000; // update every 5 seconds
chart.reloadFrom="http://www.myserver.com/newdata.html"; // get new data from this url
chart.startUpdater(); // start update thread


Each time the chart gets updated by the updater thread, RChart will trigger 2 events which can be catched by ChartListeners. These events are:

There are 2 ways for updating the values in your chart (normally inside the EVENT_BEFORE_UPDATE event handler):

  1. If you have used the ChartLoader to create your chart you can rebuild the same Chart object after you have changed some of the parameters. For example:

    // set new parameters, for example update values in serie 1
    myChart.loader.setParameter("SERIE_DATA_1","10|20|30 ....");

    // rebuild chart
    // this is not required inside the EVENT_BEFORE_UPDATE event handler

    myChart.loader.build(myChart,false,false); // since we pass the chart as first parameter, the loader will not create a new Chart object but it will rebuild the existing one

    Note: if you are setting the new parameters inside the EVENT_BEFORE_UPDATE event, you should not rebuild the chart yourself, instead you must set:


    and the chart will be rebuilt automatically.

  2. Or you can use the Java API to change the values in the chart. There are 2 methods specifically designed for this:

    - Plotter.replaceSerie();
    - DataSerie.replaceYvalueAt();

    You can change a given value in the data series using the following code:

    myChart.plotters[0].getSerie(0).replaceYValueAt(1,newValue); // replace second value in serie 0

    or you can replace the whole series:


    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.

    Note: if you are changing the chart inside the EVENT_BEFORE_UPDATE event, you should disable the automatic chart rebuild with:


    otherwise RChart would rebuild the chart using the original ChartLoader's parameters and your changes would be overwritten.

    We only recomment to use the Java API 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 and would be easier rebuilding the whole chart.

Recompiling RChart

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. Note that you must unzip it with subdirectories, so you will get the source code under "DIRECTORY/src/com/java4less/rchart".
  2. Now you must edit the following file:


    and modify the following lines:

    SET JDKHOME=C:\java\jdk
    SET SWT_JAR=C:\java\swt\org.eclipse.swt.win32_3.0.0\ws\win32\swt.jar

    JDKHOME must point to your JDK installation directory abd SWT_JAR must point to the swt.jar file.