RCHART for .NET, User Guide

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

The API

Chart creation process

We recommend you to create charts using the parameters however if you need it you can create charts using the api (see documentation in the api subdirectory of your installation).

The process is:

1. Import RChart assembly

[C#]
using J4L.RChart;

[VB.NET]
Imports J4L.RChart;
2. Create the title [C#]
Title title=new Title("Sales (thousands $)");

[VB.NET]
dim mytitle as Title = new Title("Sales (thousands $)")
3. Create the axis you need (depends on the chart)

[C#]
Axis XAxis=new Axis(Axis.HORIZONTAL,new Scale());
Axis YAxis=new Axis(Axis.VERTICAL,new Scale());
XAxis.scale.min=0;
YAxis.scale.min=0;
.....

[VB.NET]
dim XAxis as Axis=new Axis(Axis.HORIZONTAL,new Scale())
dim YAxis as Axis=new Axis(Axis.VERTICAL,new Scale())
XAxis.scale.min=0
YAxis.scale.min=0
.....
4. Create the legend [C#]
Legend l=new Legend();
l.addItem("Products",new FillStyle(Color.Blue)); l.addItem("Services",new FillStyle(Color.Green));

[VB.NET]
dim l as Legend=new Legend()
l.addItem("Products",new FillStyle(Color.Blue))
l.addItem("Services",new FillStyle(Color.Green))
5. Create the axis labels

[C#]
XLabel= new HAxisLabel("",Color.Blue,new Font(new FontFamily("Arial"),14);

YLabel= new VAxisLabel("Brutto",Color.Black,new Font(new FontFamily("Arial"),14);


[VB.NET]
dim XLabel as HAxisLabel= new HAxisLabel("",Color.Blue,new Font(new FontFamily("Arial"),14))

dim YLabel as VAxisLabel= new VAxisLabel("Brutto",Color.Black,new Font(new FontFamily("Arial"),14))

 

6. create the plotter (or plotters if you combine lines and bars) [C#]
LinePlotter3D plot=new LinePlotter3D();


[VB.NET]
dim plot as LinePlotter3D=new LinePlotter3D()
7. create the chart and set properties (labels,legend) [C#]
Chart chart=new Chart(title,plot,XAxis,YAxis);
chart.XLabel=XLabel;
chart.YLabel=YLabel;
chart.legend=l;


[VB.NET]
dim mychart as Chart=new Chart(mytitle,plot,XAxis,YAxis)
mychart.XLabel=XLabel
mychart.YLabel=YLabel
mychart.legend=l
8. create the data series [C#]
RValue[] d1={RValue(1),RValue(1),RValue(3),RValue(3.5),RValue(5),RValue(4),RValue(2)};
LineDataSerie data1= new LineDataSerie(d1,new LineStyle(1,Color.Blue,LineStyle.LINE_NORMAL));


[VB.NET]
dim d1 as RValue()={RValue(1),RValue(1),RValue(3),RValue(3.5),RValue(5),RValue(4),RValue(2)}
dim data1 as LineDataSerie= new LineDataSerie(d1,new LineStyle(1,Color.Blue,LineStyle.LINE_NORMAL))
9. add serie to chart [C#]
chart.addSerie(data1);


[VB.NET]
mychart.addSerie(data1)
   

 

 

The chartLoader

You can use the ChartLoader to create your charts using the parameters:

[c#]

// define variable
ChartLoader chartLoader= new ChartLoader();
// set chart parameters
chartLoader.setParameter("TITLECHART","Sales 2002");
chartLoader.setParameter("XLABEL","Month");
chartLoader.setParameter("YLABEL","Million $");
chartLoader.setParameter("XSCALE_MIN","0");
chartLoader.setParameter("XSCALE_MAX","5.5");
chartLoader.setParameter("YSCALE_MIN","-15");
chartLoader.setParameter("BIG_TICK_INTERVALX","1");
chartLoader.setParameter("BIG_TICK_INTERVALY","10"); chartLoader.setParameter("XAXIS_LABELS","June|July|Aug.|Sept.|Oct.|Nov.|Dec."); chartLoader.setParameter("CERO_XAXIS","LINE");
chartLoader.setParameter("YAXIS_INTEGER","TRUE");
chartLoader.setParameter("SERIE_1","Products");
chartLoader.setParameter("SERIE_2","Services");
chartLoader.setParameter("SERIE_TYPE_1","BAR");
chartLoader.setParameter("SERIE_TYPE_2","BAR");
chartLoader.setParameter("SERIE_FONT_1","Arial|PLAIN|8");
chartLoader.setParameter("SERIE_FONT_2","Arial|PLAIN|8");
chartLoader.setParameter("SERIE_DATA_1","12|43|50|45|30");
chartLoader.setParameter("SERIE_DATA_2","-10|41|48|39|36");
chartLoader.setParameter("SERIE_BORDER_TYPE_1","RAISED"); chartLoader.setParameter("SERIE_BORDER_TYPE_2","RAISED");
chartLoader.setParameter("SERIE_BAR_STYLE_1","ff00");
chartLoader.setParameter("SERIE_BAR_STYLE_2","ff");
chartLoader.setParameter("BARCHART_BARSPACE","1");
chartLoader.setParameter("LEFT_MARGIN","0.15");
chartLoader.setParameter("CHART_FILL","ffcc00");
chartLoader.setParameter("SERIE_NEGATIVE_STYLE_2","RED");
chartLoader.setParameter("YLABEL_VERTICAL","TRUE");
// create chart
Chart chart=chartLoader.buildChart();

[VB.NET]

' define variable
dim chartLoader as ChartLoader = new ChartLoader()
' set chart parameters
chartLoader.setParameter("TITLECHART","Sales 2002")
chartLoader.setParameter("XLABEL","Month")
chartLoader.setParameter("YLABEL","Million $")
chartLoader.setParameter("XSCALE_MIN","0")
chartLoader.setParameter("XSCALE_MAX","5.5")
chartLoader.setParameter("YSCALE_MIN","-15")
chartLoader.setParameter("BIG_TICK_INTERVALX","1")
chartLoader.setParameter("BIG_TICK_INTERVALY","10") chartLoader.setParameter("XAXIS_LABELS","June|July|Aug.|Sept.|Oct.|Nov.|Dec.")
chartLoader.setParameter("CERO_XAXIS","LINE")
chartLoader.setParameter("YAXIS_INTEGER","TRUE")
chartLoader.setParameter("SERIE_1","Products")
chartLoader.setParameter("SERIE_2","Services")
chartLoader.setParameter("SERIE_TYPE_1","BAR")
chartLoader.setParameter("SERIE_TYPE_2","BAR")
chartLoader.setParameter("SERIE_FONT_1","Arial|PLAIN|8")
chartLoader.setParameter("SERIE_FONT_2","Arial|PLAIN|8")
chartLoader.setParameter("SERIE_DATA_1","12|43|50|45|30")
chartLoader.setParameter("SERIE_DATA_2","-10|41|48|39|36")
chartLoader.setParameter("SERIE_BORDER_TYPE_1","RAISED") chartLoader.setParameter("SERIE_BORDER_TYPE_2","RAISED")
chartLoader.setParameter("SERIE_BAR_STYLE_1","ff00")
chartLoader.setParameter("SERIE_BAR_STYLE_2","ff")
chartLoader.setParameter("BARCHART_BARSPACE","1")
chartLoader.setParameter("LEFT_MARGIN","0.15")
chartLoader.setParameter("CHART_FILL","ffcc00")
chartLoader.setParameter("SERIE_NEGATIVE_STYLE_2","RED")
chartLoader.setParameter("YLABEL_VERTICAL","TRUE")
' create chart
dim mychart as Chart mychart=chartLoader.buildChart()

 

You can also read the parameters directly from a file:

[c#]

// define variable
ChartLoader chartLoader= new ChartLoader();
// set chart parameters
chartLoader.loadFromFile("params.txt",true);
// create chart
Chart chart=chartLoader.buildChart();

In all cases the steps are:

  1. Create a 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 "JPEG", "PNG" of "GIF".

[c#]

// define variable
ChartLoader chartLoader= new ChartLoader();
// set chart parameters
chartLoader.loadFromFile("params.txt",true);
// create chart
Chart chart=chartLoader.buildChart();
chart.saveToFile("chart.gif","GIF");

 

Chart Listener (implementing actions)

If you want to receive an event when the user click on one of the bars or points you must catch the Chart.EVENT_POINT_CLICKED event in the ChartListener interface.

The EVENT_POINT_CLICKED allows you to implement actions when the user clicks on a part of the chart. This can for example be used for implementing drill down charts (see our example, ChartViewer.cs). The first parameter of the chartEvent() method is the chart the event is triggered for. The following chart properties are normally used in the event handler:

  1. Chart.selectedSeriePoint: index of the point in the serie.
  2. Chart.selectedSerie: Selected serie (DataSerie object).
  3. Chart.selectedLabel: if the user clicked on a label.

You must set the listener like this:

chart.addChartListener(yourListener);

Instead of implementing your own listener you can extend the ChartAdapter class and overrride the methods you need. For example:

[c#]

class MyChartAdapter:ChartAdapter {

public MyChartAdapter() { }

public override void chartEvent(Chart c,int type) {

if (type==Chart.EVENT_POINT_CLICKED)
MessageBox.Show("You just clicked on series "+ c.selectedSerie.name.ToUpper() + " point "+ (c.selectedSeriePoint+1));

}
}

 

Updating the chart

 

The sample application ChartViewer.cs includes a realtime chart example which will be updated every 2 seconds. The following section explains the how to create such charts. The code below will enable the automatic chart update:

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

    myChart.autoRebuild=true;

    and the chart will be rebuilt automatically.

  2. Or you can use the 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 recommend using the API if you are going to update values only, 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

In order to recompile RChart you can use the following command:

csc.exe /unsafe /reference:system.dll /reference:system.data.dll /reference:System.Drawing.dll /reference:System.Windows.Forms.dll /target:library /out:rchart11.dll /nologo /debug- ODBCSource.cs Axis.cs AxisLabel.cs AssemblyInfo.cs ChartMapWebControl.cs BarDataSerie.cs BarPlotter3D.cs Chart.cs ChartComponent.cs ChartListener.cs ChartLoader.cs CurvePlotter.cs Legend.cs LineDataSerie.cs LinePlotter3D.cs LinePlotter.cs LogScale.cs MaxMinDataSerie.cs PieDataSerie.cs Plotter.cs RadarPlotter.cs RMatrix.cs Scale.cs Title.cs Vector.cs FillStyle.cs DataSerie.cs LineStyle.cs BarPlotter.cs PiePlotter.cs HAxisLabel.cs VAxisLabel.cs Polygon.cs Util.cs RValue.cs ChartControl.cs ChartWebControl.cs EventListener.cs AxisTargetZone.cs TargetZone.cs IFloatingObject.cs IConstants.cs TagObject.cs TagParser.cs ChartLabel.cs ChartAdapter.cs

If you just want to recompile the example application:

csc.exe /unsafe /reference:system.dll /reference:system.data.dll /reference:System.Drawing.dll /reference:System.Windows.Forms.dll /reference:rchart11.dll /out:chartviewer11.exe /nologo /debug- Main.cs ChartViewer.cs