J4L-CHART for Ruby

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


Axis configuration / parameters

 

J4L-Chart 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:

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

Parameters
Description
Equivalent Ruby class/property

YLABEL=Million $
YLABEL_FONT=Serif|BOLD|14
YLABEL_COLOR=#0000ff
YLABEL_VERTICAL=true

Text of label
Font of the label
Color
Rotate text (draw vertically)


chart.yLabel=J4LChart::VAxisLabel.new("Million",color,font)
see font in label constructor
see color in label constructor
chart.ylabel.vertical=true

 

The ticks

J4L-Chart supports 2 kind of ticks:

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:

the default values are:

Parameters
Description
Equivalent Ruby 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 Ruby 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 J4L-Chart calculate the value for the tick interval using the following parameters:

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. J4L-Chart will select tick_interval=25 which will result in 12 ticks. See screenshot.

 

Other ticks parameters

Parameters
Description
Equivalent Ruby 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 Ruby 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 Ruby 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 Ruby 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 Ruby 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 "%.2d" will always display 2 decimal digits. The format uses the following format:

%[width][.precision]specifier

where

See documentation of the ruby sprintf function for a complete list of format options.

Parameters
Description
Equivalent Ruby class/property

YAXIS_LABEL_FORMAT=%.1d

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 Ruby class/property

YAXIS_INTEGER=true

Do not use decimal values in labels of the ticks.

chart.yAxis.integerScale=true

 

 

Parameters
Description
Equivalent Ruby 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 Ruby 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 Ruby class/property

XAXIS_VERTICAL_LABELS=TRUE
or
XAXIS_ROTATE_LABELS=90

Rotate labels

chart.xAxis.rotateLabels

 

The grid

J4L-Chart will by default no display a grid:

 

however you can add the grid with the following parameters:

Parameters
Description
Equivalent Ruby class/property

XAXIS_GRID=0.2|#ffffff|DASHED
YAXIS_GRID=0.2|#ffffff|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 Ruby class/property

XAXIS_GRID=0.2|#ffffff|DASHED
YAXIS_GRID=0.2|#ffffff|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 Ruby class/property

XAXIS_GRID=0.2|#ffffff|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 Ruby class/property

YAXIS_FILL_GRID=#E0E0E0
LINECHART_BACK=WHITE

Grid filling (grey)
Plotter background

axis.gridFillStyle= J4LChart::FillStyle.new( J4LChart::GraphicsProvider.getcolor( "#E0E0E0") )

linePlotter.back=J4LChart::FillStyle.new( J4LChart::GraphicsProvider.getcolor( J4LChart::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 Ruby class/property

CERO_XAXIS=LINE
CERO_XAXIS_STYLE=0.2|#000000|NORMAL

Draw line at Y axis, position 0
Style of line

chart.xAxis.ceroAxis=J4LChart::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 Ruby class/property

CERO_XAXIS=SCALE

Draw scale at Y axis position 0

chart.xAxis.ceroAxis= J4LChart::CEROAXIS_SCALE

 

Closed axis

 

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

Parameters
Description
Equivalent Ruby 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:

Parameters
Description
Equivalent Ruby 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 Ruby 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 Ruby 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 Ruby 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 Ruby 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 Ruby class/property

YAXIS_STYLE=2|#0000ff|NORMAL
YAXIS_FONT=Serif|BOLD|10
YAXIS_FONT_COLOR=#cc3300

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:

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

Parameters
Description
Equivalent Ruby class/property

XAXIS_BAR_STYLE=BAR
XAXIS_BAR_WIDTH=12 (default)
XAXIS_FILLING=#33cccc

Style of the axis
Font of labels
Color of labels

axis.barStyle=J4LChart::BAR_STYLE_BAR
axis.barWidth=12
axis.barFilling= J4LChart::FillStyle.new( J4LChart::GraphicsProvider.getcolor( "#33cccc") ))

 

 

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 Ruby 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 Ruby 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=J4LChart::Axis.new(J4LChart::VERTICAL,J4LChart::Scale.new())
y_1axis.scale.min=0
y_1axis.scale.max=20
y_1axis.barStyle=J4LChart::BAR_STYLE_BAR
y_1axis.barFilling= J4LChart::FillStyle.new( J4LChart::GraphicsProvider.getcolor( J4LChart::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 Ruby 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:

The 2 zones in the example above are defined as:

Parameters
Equivalent Ruby 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

value="0%;30%;;RED;@rotation valu........"
axis.addTargetZone( J4LChart::AxisTargetZone.createFromString(value))

OR

zone= J4LChart::AxisTargetZone.new(0,30, J4LChart::UNIT_PERCENTAGE,  J4LChart::UNIT_PERCENTAGE)
zone.fillStyle=J4LChart::FillStyle.new( J4LChart::GraphicsProvider.getColor(J4LChart::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 Ruby 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#"