RCHART, User Guide

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

The Chart API

• Chart creation process
• The ChartLoader
• Displaying the chart (Chart viewer)
  
• Exporting the chart to gif , png or jpg
• Updating the chart and realtime update
• 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 API (see the Java documentation in the javadoc subdirectory of your installation).

The process is:

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("LEGEND_FILL","WHITE");
loader.setParameter("LEGEND_VERTICAL","FALSE");
loader.setParameter("LEGEND_BORDER","0.2|0x0|NORMAL");
loader.setParameter("SERIE_1","Pie");
loader.setParameter("SERIE_TYPE_1","PIE");
loader.setParameter("SERIE_FONT_1","ARIAL|BOLD|12");
loader.setParameter("SERIE_DATA_1","94|48|28");
loader.setParameter("PIE_NAME_1","Products");
loader.setParameter("PIE_NAME_2","Services");
loader.setParameter("PIE_NAME_3","Other");
loader.setParameter("PIE_STYLE_1","RED");
loader.setParameter("PIE_STYLE_2","BLUE");
loader.setParameter("PIE_STYLE_3","GREEN");
loader.setParameter("PIECHART_3D","true");
loader.setParameter("PIE_LABEL_FORMAT","#VALUE# (#PERCENTAGE#)");
loader.setParameter("SERIE_LABELS_1","Products|Services|Other");
loader.setParameter("SERIE_TOGETHER_1","true|false|true");
loader.setParameter("LEGEND_POSITION","TOP");
loader.setParameter("LEGEND_MARGIN","0.3");
loader.setParameter("CHART_BORDER","0.2|0x0|NORMAL");
loader.setParameter("CHART_FILL","0x99cccc");

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

/* create png file */
chart.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 {

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
chart.setSize(300,300);

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

}

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)

• Swing ChartViewer (in com.java4less.rchart.swing): This class is a subclass of JPanel and can be added to any Swing container. The viewer implements the following features:
  • It displays the chart you set with the setChart() method.
  • It implements scroll bars and zoom in/out buttons.
  • It can automatically change the cursor when the pointer moves over a value in the chart.
  • the Chart class will also trigger events and support realtime updates
    
    The following is a very simple Swing java program which uses the chart viewer:
    
    public class SimpleJExample extends JFrame {
    
    JChartViewer chartViewer= new JChartViewer();
    
    
    public SimpleJExample() {
    this.setTitle("RChart for Swing example");
    this.setResizable(false);
    this.getContentPane().setLayout(new java.awt.BorderLayout());
    this.setSize(new Dimension(500,500));
    this.getContentPane().add("Center", chartViewer);
    
    this.doLayout();
    
    // create default chart
    ChartLoader loader=new ChartLoader();
    loader.loadFromFile("examples/lineChart.txt",true);
    chartViewer.setChart(loader.build(false,false));
    this.show();

    }

    }

    
    
    
• SWT ChartViewer (in com.java4less.rchart.swt): This class is a SWT control which can be added to any SWT Control or window. The viewer implements the following features:
  • It displays the chart you set with the setChart() method.
  • It implements scroll bars and zoom in/out buttons.
  • It can automatically change the cursor when the pointer moves over a value in the chart.
  • the Chart class will also trigger events and support realtime updates
    
    The following is a very simple SWT java program which uses the chart viewer:
    
    
    Display display = new Display();
    // set Rchart SWT mode
    GraphicsProvider.setMode(GraphicsProvider.MODE_SWT);
    SwtGraphicsProvider.setDefaultDisplay(display);
    
    
    Shell shell = new Shell(display);
    shell.setSize(300,300);
    shell.setBounds(100,100,400,400);
    
    // create chart
    ChartLoader cloader=new ChartLoader();
    cloader.loadFromFile("areaChart.txt",false); // load chart parameters from file
    Chart chart=cloader.build(false,false);
    
    // create chart viewer and set the chart
    ChartViewer chartViewer=new ChartViewer(shell,SWT.NONE);
    chartViewer.setBounds(0,0,400,400);
    chartViewer.setChart(chart);
    
    shell.open();
    
    
    while(!shell.isDisposed())
    if(!display.readAndDispatch())
    display.sleep();
    display.dispose();
    chart.dispose();
    
    
    
• AWT ChartViewer (in com.java4less.rchart.awt): This class is a subclass of java.awt.Panel and can be added to any AWT container. The viewer implements the following features:
  • It displays the chart you set with the setChart() method.
  • It implements scroll bars and zoom in/out buttons.
  • It can automatically change the cursor when the pointer moves over a value in the chart.
  • the Chart class will also trigger events and support realtime updates.
    
    The following is a very simple AWT java program which uses the chart viewer:

    public class SimpleAwtExample extends Frame {
    
    ChartViewer chartViewer= new ChartViewer();
    
    public static void main(String[] args) {
    SimpleAwtExample demo=new SimpleAwtExample();
    demo.show();
    }
    
    public SimpleAwtExample() {
    this.setTitle("RChart for AWT example");
    this.setResizable(false);
    this.setLayout(new java.awt.BorderLayout());
    this.setSize(new Dimension(500,500));
    this.add("Center", chartViewer);
    this.doLayout();
    
    // create chart
    ChartLoader loader=new ChartLoader();
    loader.loadFromFile("examples/lineChart.txt",true);
    chartViewer.setChart(loader.build(false,false));
    }
    
    }

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".

AWT

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:

• 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 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 );
chartGraphics.dispose();

// 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(image ,outb); // encode the image to the output stream
encoder.encodeImage();

SWT

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.

chartLoader.loadFromFile("file:///c:\\examples\\areaChart.txt",false);
Chart chart=cloader.build(false,false);

ChartViewer chartViewer=new ChartViewer(shell,SWT.NONE);
chartViewer.setBounds(0,0,400,400);
chartViewer.setChart(chart);

shell.open();

// 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

while(!shell.isDisposed())
if(!display.readAndDispatch())
display.sleep();
display.dispose();
chart.dispose();

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

• EVENT_BEFORE_UPDATE: this event can be used by the listeners to set any new or updated parameters.
• EVENT_AFTER_UPDATE: this event is catched by the ChartViewer to refresh the control on the screen after the chart has been updated. Your application will normally not take any action when this event occurs.

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:
   
   myChart.autoRebuild=true;
   
   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:
   
   
   myChart.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.
   
   Note: if you are changing the chart inside the EVENT_BEFORE_UPDATE event, you should disable the automatic chart rebuild with:
   
   myChart.autoRebuild=false;
   
   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:
   
   DIRECTORY/src/recompile.bat
   
   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.