### RCHART, User Guide

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

### Axis configuration / parameters

- The label
- The ticks
- The scale's labels
- The grid
- Cero position axis
- Closed axis
- Dates
- Second Y axis
- Look of the axis
- X axis on top
- Additional (secondary) axis
- Axis target zones
- Axis label templates

RChart supports 3 axis, a horizontal axis (X) at the bottom of the chart, and 2 vertical axis to the left (Y) and to the right (Y2) of the chart.

#### The label

Each Axis can have an associate label. The label of the following example is "Million $":

The properties of the label are:

- Text: text of the label.
- Font: font used to paint the label.
- Color: color of the label.
- Vertical: if true, the text will be painted vertically (rotated).

The following example paints a blue vertical label with "Serif" font:

Parameters | Description | Equivalent java class/property
YLABEL=Million $ YLABEL_FONT=Serif|BOLD|14 YLABEL_COLOR=0x0000ff YLABEL_VERTICAL=true | Text of label Font of the label Color Rotate text (draw vertically) | chart.YLabel=new VAxisLabel("Million",color,font); see font in label constructor see color in label constructor chart.Ylabel.vertical=true;

#### The ticks

RChart supports 2 kind of ticks:

- small ticks: these are ticks between big ticks, they do not have any label.
- big ticks: these ticks are always displayed with a label.

There are 2 ways you can control the number and position of the ticks in the scale:

Manual: You can use the following parameters to define the spacing between ticks:

- TICK_INTERVALY: distance between small ticks (in axis units).
- BIG_TICK_INTERVALY: Number of small tick between big ticks. Note that these are not axis units, these are number of small ticks.

the default values are:

Parameters | Description | Equivalent java class/property
TICK_INTERVALY=1 BIG_TICK_INTERVALY=5 | Small ticks for each unit of the scale Big ticks (and label) after 5 small ticks. | yAxis.scaleTickInterval=1; yAxis.bigTickInterval=5;

an example is:

Parameters | Description | Equivalent java class/property
TICK_INTERVALY=2 BIG_TICK_INTERVALY=10 | the result will be one big tick after 20 unit (2*10) | yAxis.scaleTickInterval=2; yAxis.bigTickInterval=10;

Automatic: you can also let RChart calculate the value for the tick interval using the following parameters:

- YAXIS_AUTO_TICKS: if not 0 , Rchart will calculate the tick interval for the Y axis. This parameter is used to define the number of desired ticks.
- YAXIS_PREF_TICK_INTERVAL: Only used if AXIS_AUTO_TICKS is true. RChart will use the interval in this list which is more appropiate to get the desired amount of ticks. The default is:

VALUE="0.1|0.5|1|5|10|25|50|100|250|500|1000|5000|10000|50000|100000|500000|1000000"

For example, if your values range from 0 till 300 and the desired number of ticks is 10. RChart will select tick_interval=25 which will result in 12 ticks. See screenshot.

Other ticks parameters

Parameters | Description | Equivalent java class/property
YAXIS_START_WITH_BIG_TICK=false YAXIS_TICKATBASE=false | First tick should be small Ticks should not start at 0 | chart.YAxis.startWithBigTick=false; chart.YAxis.tickAtBase=false;

Parameters | Description | Equivalent java class/property
YAXIS_START_WITH_BIG_TICK=false YAXIS_TICKATBASE=true | First tick should be small Ticks should tart at 0 | chart.YAxis.startWithBigTick=false; chart.YAxis.tickAtBase=true;

If you don't want to have small ticks you can set BIG_TICK_INTERVALY=1. For example:

Parameters | Description | Equivalent java class/property
TICK_INTERVALY=5 BIG_TICK_INTERVALY=1 | One tick every 5 units One big tick (with label) every 1 small ticks (ie. there will be only big ticks) | chart.YAxis.scaleTickInterval=5; chart.YAxis.bigTickInterval=1;

Ticks at irregular interval

The tick interval parameters allows you to define the position of the ticks. These are displayed at fixed intervals only. You can also use the BIG_TICK_INTERVAL_LISTY parameter to define the positions where the big ticks should appear. For example:

Parameters | Description | Equivalent java class/property
TICK_INTERVALY=5 BIG_TICK_INTERVALY=1 BIG_TICK_INTERVAL_LISTY=1|3|7 | One tick every 5 units One big tick (with label) every 1 small ticks (ie. there will be only big ticks) The following big ticks will be missing: 2,4,5,6 | chart.YAxis.scaleTickInterval=5; chart.YAxis.bigTickInterval=1; chart.YAxis.bigTickIntervalList ={1,3,7};

The following parameters allow you to control the length of the ticks. For example, you can remove the small ticks by making its length=0:

Parameters | Description | Equivalent java class/property
YAXIS_TICKPIXELS=0 YAXIS_BIGTICKPIXELS=6 BIG_TICK_INTERVAL_LISTY=1|3|7 YAXIS_START_WITH_BIG_TICK=false | Length of small ticks (0, invisible) Length of big tick | chart.YAxis.tickPixels=0; chart.YAxis.bigTickPixels=6;

#### The scale labels

Labels are always displayed at the big ticks positions. The following parameters allow you to modify the labels.

XAXIS_LABEL_FORMAT. If XAXIS_INTEGER is false, this format will be used to draw the label. For example "#####.00" will always display 2 decimal digits. The format uses the following symbols:

- 0 a digit,
- # a digit, zero shows as absent
- . placeholder for decimal separator
- , placeholder for grouping separator.
- - default negative prefix.

Parameters | Description | Equivalent java class/property
YAXIS_LABEL_FORMAT=#0.0 | Use only 1 decimal digit in the tick labels | chart.YAxis.scaleLabelFormat;

The following parameter will remove the digits right of the decimal separator:

Parameters | Description | Equivalent java class/property
YAXIS_INTEGER=true | Do not use decimal values in labels of the ticks. | chart.YAxis.IntegerScale=true

- You can specify your own text for the labels using:

Parameters | Description | Equivalent java class/property
YAXIS_LABELS=cero|one|two|three|four|five | User defined labels for the big ticks. | chart.YAxis.tickLabels={"cero","one",....};

You can split your labels in sereval lines by using "\n".

Parameters | Description | Equivalent java class/property
XAXIS_VERTICAL_LABELS=false. XAXIS_LABELS=June\n2002|July\n2002|Aug.\n2002| Sept.\n2002|Oct.\n2002|Nov.\n2002|Dec.\n2002 | If "true" the labels will be painted with a 90 degrees rotation. User defined labels (2 lines) | chart.XAxis.rotateLabels; chart.XAxis.tickLabels;

or paint labels vertically (or with any rotation angle):

Parameters | Description | Equivalent java class/property
XAXIS_VERTICAL_LABELS=TRUE or XAXIS_ROTATE_LABELS=90 | Rotate labels | chart.XAxis.rotateLabels;

The grid

RChart will by default no display a grid:

however you can add the grid with the following parameters:

Parameters | Description | Equivalent java class/property
XAXIS_GRID=0.2|0xffffff|DASHED YAXIS_GRID=0.2|0xffffff|DASHED GRIDY=TRUE | Line style of the grid Grid at big ticks only | chart.XAxis.gridStyle; chart.XAxis.bigTicksGrid ;

which let you define the style of the line used for the grid lines.

If you want to get a finer grid you can display the grid at the small tick positions with:

Parameters | Description | Equivalent java class/property
XAXIS_GRID=0.2|0xffffff|DASHED YAXIS_GRID=0.2|0xffffff|DASHED GRIDY=false | Line style of the grid Grid at small ticks | chart.XAxis.gridStyle; chart.XAxis.bigTicksGrid ;

You can of course display lines for 1 axis only, for example:

Parameters | Description | Equivalent java class/property
XAXIS_GRID=0.2|0xffffff|DASHED | Only vertical grid | chart.XAxis.gridStyle;

You can also set an alternate filling for the grid. In the example you see the background alternates white and grey.

Parameters | Description | Equivalent java class/property
YAXIS_FILL_GRID=0xE0E0E0; LINECHART_BACK=WHITE; | Grid filling (grey) Plotter background | axis.gridFillStyle= new FillStyle GraphicsProvider.getColor( "0xE0E0E0") ); linePlotter.back=new FillStyle GraphicsProvider.getColor( ChartColor.WHITE));

Cero position axis

If your scale's minimum value is less than cero, you might want to paint a line at the cero possition to be used as reference by the user.

Parameters | Description | Equivalent java class/property
CERO_XAXIS=LINE CERO_XAXIS_STYLE=0.2|0x00NORMAL | Draw line at Y axis, position 0 Style of line | chart.XAxis.ceroAxis=Axis.CEROAXIS_LINE; chart.XAxis.ceroAxisStyle

You can also define the cero axis to include the ticks (the labels are still painted at the bottom of the chart).

Parameters | Description | Equivalent java class/property
CERO_XAXIS=SCALE | Draw scale at Y axis position 0 | chart.XAxis.ceroAxis=Axis.CEROAXIS_SCALE

Closed axis

The following parameters allows you create a "frame" around the chart.

Parameters | Description | Equivalent java class/property
XAXIS_CLOSED=TRUE YAXIS_CLOSED=TRUE | draw lines at the top and on right of the chart to get a closed box. | chart.XAxis.axisFrame=true; chart.YAxis.axisFrame=true;

Dates

You can use dates as labels for the ticks with the following parameters:

- XAXIS_DATE_FORMAT (default is dd-MMM-yyyy): format of the label. Use "MMM" to display only the month's name.
- XAXIS_DATE_STEP: scale unit. The default is "d" which means 1 unit is 1 day. Other values are "m" (months), "w" (week) , "y" (year), "h" (hours) and "n" (minutes). You can also use "d3" ( 3 days), "m2" (2 months) ....
- XAXIS_INITIAL_DATE: this date will be used as base (first tick) if you want to calculate dates for the tick labels. Incompatible with logarithmic scales.

Parameters | Description | Equivalent java class/property
BIG_TICK_INTERVALX=2 TICK_INTERVALX=1 XAXIS_DATE_STEP=d XAXIS_INITIAL_DATE=01-01-2001 | Ticks Interval Each unit of the scale will stand for a day. Starting date is 01-01-2001 | chart.YAxis.bigTickInterval; chart.YAxis.scaleTickInterval; chart.YAxis.dateStep; chart.YAxis.initialDate ;

will result in the following secuence of ticks/labels

- big tick, label "01-Jan-01"
- small tick, no label
- big tick, label "03-Jan-01"
- small tick, no label
- big tick, label "05-Jan-01"
- .....

Example 1:

Parameters | Description | Equivalent java class/property
XAXIS_DATE_FORMAT=MMM XAXIS_DATE_STEP=m XAXIS_INITIAL_DATE=10-06-2002 | Format of the date (only month name) Every unit stands for 1 months Starting date is 10-06-2002 | chart.YAxis.dateLabelFormat; chart.YAxis.dateStep; chart.YAxis.initialDate ;

Example 2:

Parameters | Description | Equivalent java class/property
XAXIS_DATE_FORMAT=dd-MMM XAXIS_DATE_STEP= d3 XAXIS_INITIAL_DATE=10-10-2001 | Format of the date Every unit stands for 3 days Starting date is 10-10-2001 | chart.YAxis.dateLabelFormat; chart.YAxis.dateStep; chart.YAxis.initialDate ;

Example 3:

Parameters | Description | Equivalent java class/property
XAXIS_DATE_FORMAT=HH:mm XAXIS_DATE_STEP=n30 XAXIS_INITIAL_DATE = "10-10-2001 12:00:00 | Format of the date Every unit stands for 30 minutes Starting date/time is | chart.YAxis.dateLabelFormat; chart.YAxis.dateStep; chart.YAxis.initialDate ;

Second Y Axis

In order to activate the second Y axis you must use:

Y2AXIS =true

then you can define which data serie will use the scale of the second axis (serie 2 is the blue line)

Parameters | Description | Equivalent java class/property
Y2AXIS =true SERIE_SECONDYAXIS_2=TRUE | Activate second/right Y axis Serie 2( the blue line) will use the second Y scale | chart.setY2Scale(cY2Axis); serie.secondYAxis=true;

Look of the axis

The following three parameters define the color and style of the axis

Parameters | Description | Equivalent java class/property
YAXIS_STYLE=2|0xff|NORMAL YAXIS_FONT=Serif|BOLD|10 YAXIS_FONT_COLOR=0xcc3300 | Style of the axis Font of labels Color of labels | chart.YAxis.style; chart.YAxis.DescFont; chart.YAxis.DescColor;

Axis can be painted as a bar (see screenshot below) using the following parameters:

- ?AXIS_BAR_STYLE: style of the axis REGULAR or BAR
- ?AXIS_BAR_WIDTH: width of the bar (the default is 12)
- ?AXIS_FILLING: fill style of the bar

where ? is X, Y , Y2 , X_1 ... and so on

Parameters | Description | Equivalent java class/property
XAXIS_BAR_STYLE=BAR XAXIS_BAR_WIDTH=12 (default) XAXIS_FILLING=0x33cccc | Style of the axis Font of labels Color of labels | axis.barStyle=Axis.BAR_STYLE_BAR; axis.barWidth=12; axis.barFilling= new FillStyle GraphicsProvider.getColor( "0x33cccc") );

X Axis on top

If you want to place the x scale on the top of the chart, instead of on the bottom you can use the following parameters:

Parameters | Description | Equivalent java class/property
XAXIS_ON_TOP=TRUE | Place it on top | chart.XAxis.scaleOnTop;

Note that this is not supported for 3D charts.

Additional (secondary) axis

In addition to the main axis (Y , X and Y2 axis) you can define additional (or secondary) axis which are displayed parallel to the main axis. There is no limit in the number of axis you define other than the space available in your chart. If you create secondary axis you will normally also need to increase the margin reserved for the axis (left , bottom or right margin).

Secondary axis can be enabled with the ?_AXIS parameter where ? can be X_1, X_2 ... for the X axis, Y1_, Y_2 ... for the Y axis and Y2_1, Y2_2 ... for the Y2 axis ( right hand side Y axis).

The following screenshot displays a chart with a secondary Y axis (the blue one):

Parameters | Description | Equivalent java class/property
Y_1AXIS=TRUE Y_1SCALE_MIN=0 Y_1SCALE_MAX=20 Y_1AXIS_BAR_STYLE=BAR Y_1AXIS_FILLING=LIGHTBLUE Y_1AXIS_LABEL=Survey 1 SERIE_SECONDARY_YAXIS_1=1 | Enable secondary axis (blue) define scale Define label for the axis Data series 1 must be plotted using Y_1 axis. | y_1axis=new Axis(Axis.VERTICAL,new Scale()); y_1axis.scale.min=0; y_1axis.scale.max=20; y_1axis.barStyle=Axis.BAR_STYLE_BAR; y_1axis.barFilling= new FillStyle(GraphicsProvider.getColor( ChartColor.LIGHTBLUE) ); y_1axis.label="Survey 1"; yaxis.addAdditionalAxis( y_1axis); // add seconday axis dataSerie.secondaryYAxis=y_1axis;

The parameters SERIE_SECONDARY_XAXIS_* and SERIE_SECONDARY_YAXIS_* are used to specify that a given data serie must be plotted using a secondary axis.

The axis can also be stacked as in the screenshot below using the parameter ?AXIS_STACK_ADDITIONAL=TRUE. As a result the chart gets splitted in 2 areas which can be used to plot 2 charts one on the top of the other:

Parameters | Description | Equivalent java class/property
YAXIS_STACK_ADDITIONAL=TRUE | Stack axis | yaxis.stackAdditionalAxis=true;

If you also create a secondary axis for the X axis and stack them, you will get 4 subcharts as in the screenshot:

Axis Target zones

Axis Target zones are used to remark a range of values in the axis. The following screenshot shows an axis with 2 target areas:

As you can see target zones can be lines or areas (with start and end positions). The ?AXIS_TARGET_ZONE_* parameters are used to add target zones to the charts. The syntax of the parameter is:

?AXIS_TARGET_ZONE_*=<start value>;<end value>;<line style>;<fill style>;<label>

where:

- ? can be X , Y , Y2 , X_1 , X_2 , Y_1, Y_2 and so on.
- * is a counter 1,2,3,4 and so on.
- <start value>: position of the target zone.
- <end value>: (optional) end position of the zone
- <line style>: style of the line for the borders of the zone
- <fill style>: (optional) style for filling the zone
- <label>: (optional) text to be displayed as label

The 2 zones in the example above are defined as:

Parameters | Equivalent java class/property
Y_AXIS_TARGET_ZONE_1=0%;30%;;RED;@rotation value='90'@@color value='RED'@Dissatisfied Y_AXIS_TARGET_ZONE_2=70%;100%;;GREEN;@rotation value='90'@@color value='GREEN'@Satisfied | String value="0%;30%;;RED;@rotation valu........"; axis.addTargetZone( AxisTargetZone.createFromString(value)); OR AxisTargetZone zone=new AxisTargetZone(0,30, IConstants.UNIT_PERCENTAGE, IConstants.UNIT_PERCENTAGE); zone.fillStyle=new FillStyle(GraphicsProvider.getColor(ChartColor.RED)); zone.label="@rotation value='90'@@color value='RED'@Dissatisfied";

Axis label templates

The ?AXIS_TEMPLATE parameter allows you to define a template which will be applied to the labels which must be painted next to the axis ticks. The template must contain the string #value# which will be replaced by the actual value of the tick to be painted.

The following screenshot and table shows an example of use of this parameter:

Parameters | Equivalent java class/property
XAXIS_TEMPLATE=@background value='LIGHTYELLOW'@@position value='+0px,+5px'@@border value='1|BLACK|NORMAL'@ #value# | axis.labelTemplate="@background value='LIGHTYELLOW'@@position value='+0px,+5px'@@border value='1|BLACK|NORMAL'@ #value#";