### RCHART, User Guide

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

### Configuration objects

- Label markup language
- Target zones
- Notes
- Format of the values

#### Label markup language

RChart provides several properties and parameters to define the text to be used as title, labels for the axis , labels for the values and other. It also provides a way to select the color and font to be used in each case.
Starting with version 2.1 you can also use the label markup language to define the appearance of the labels. The language allows you to:

- modify the font and color of parts of the label
- rotate the label
- define the aligment
- add images to the label
- add a border to the label
- modify the position of the label
- and more

The language is made of tags which are inserted in the label's text and processed by RChart before rendering the text. The format of the tags is:

@tagname attributename1='value' attributename2='value' ....@

Tags start with the character @, followed by the tagname and one or more attributes. Each attribute is made of the attribute name followed by the equal (=) sign and the value enclosed in single quotes ( ' ). Most tags have only 1 attribute , called value. Tags must end with the character @.

There are 2 kind of tags:

- global tags: these tags should appear only once in the text and will be applied to the whole label. For example, the rotation and alignment tags are global tags.
- local tags: these tags can appear several times in the text and will change the current value of a given property. For example the color and the font are local tags, which can be changed as many times as needed.

The following table shows all available tags

Tag name (and type) | Attributes | Description and example
name (global) | value | Name of the label (optional). The name can be used in java code to identify which label has been clicked. You can use chart.selectedLabel.getName() to read the name of the clicked label.
tip (global) | value | Tip of the label (optional)
background (global) | value | Background color of the label. Example: @background value='RED'@
border (global) | value | Line style of the border. Example: @border value='1|BLACK|NORMAL'@
clickinfo (global) | value | Additional information. It is normally used to hold a html link which will be opened when the user clicks on the label. You can use chart.selectedLabel.getClickInfo() to read the value of the property in your java code.
rotation (global) | value | Use this tag to rotate the label. Valid values are: 0,45,90,180 and 270. For example: @rotation value='90'@
position (global) | value | Use this tag to change the default position of the label. You can define the position using axis units, pixels or percentages. For example: @position value='10px,20px'@ will paint the label at pixel (10,20). @position value='10%,20%'@ and the size of the chart is 200x200, it will paint the label at pixel (20,40). @position value='10,20'@ will paint at position 10 according to the X axis and at position 20 according to the Y axis. You can also use the signs + / - to defined a relative position. For example: @position value='+10px,+0px'@ will paint the label ten pixels to the right of the default position.
align (global) | value | Use this tag to change the alignment of the text and images in the label. Valid values are LEFT, CENTER and RIGHT.
size (global) | value | Use this tag to change the size of the label (see also position tag)
anchor (global) | value line | The tag allows you to paint a line from the label to an "anchor" point. The value attribute contains the position of the point and the line attibute the style of the line. For example: @ANCHOR value='1,2' line='1|GREY|DOTS'@
margin (global) | value | The margin allows to increase the distance between the text in the label and the border. A margin of 3 pixels is defined as: @margin value='3'@
color (local) | value | Use this tag to select the current font color. The new color will be applied to the text after the font tag only. For example: @color value='RED'@
font (local) | value | The font is used to change the current font. The new font will be applied to the text after the font tag only. For example: @font value="arial|PLAIN|10'@
image (local) | value | Adds an image to the label. For example: @image value='myImage.gif'@
\n |  | You can use the string \n (in java code defined as "\\n" ) to create a new line in your text.

The following table includes some examples and the resulting image:

Name | Code | Result
Changes of fonts in the label. | @align value='CENTER'@Survey Results\n@Font value='Arial|PLAIN|9'@Coffee machine Customer Satisfaction survey\nconducted by two independent consultants |
Changes of colors in the label. | @position value='15%,12%'@@font value='Arial|BOLD|12'@@color value='RED'@London @color value='BLACK'@/ @color value='BLUE'@Paris |
Rotation of the text | @position value='72%,20%'@@rotation value='90'@@font value='Arial|BOLD|14'@Weather statistics |
Border and background | @position value='30%,90%'@@size value='0px,22px'@@border value='1|BLACK|NORMAL'@@background value='WHITE'@@font value='Arial|BOLD|12'@ Last year |
Adding line to anchor point | @position value='0px,94%'@@size value='100%,6%'@ @background value='0x33ccff'@Copyright J4L Examples |
Adding an image | @image value='rain.gif'@\n\nRainy |
Setting size and position | @position value='0px,94%'@@size value='100%,6%'@ @background value='0x33ccff'@Copyright J4L Examples |

Note: there are two parameters; SERIE_LABEL_TEMPLATE_* and *AXIS_TEMPLATE which are used to define the label of the value in the chart and the axis. These label must contain the literal #value# which will be replace at runtime with the value to be plotted.

#### Target zones

Target zones are used in line and bar charts to remark a range of values in the plotter area. The follwing screenshot shows a chart with 2 target zones:

- a vertical target zone which expand from the third value to the fifth value of the X Axis (Saturday till Monday). The target zone is used to remark a weekend.
- a horizontal target zone which marks the "Profitability threshold" at position 30 of the Y axis.

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

CHART_TARGET_ZONE_*=<start value>;<end value>;<line style>;<fill style>;<label>;<orientation>

where:

- <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
- <orientation>: TRUE (for vertical) and FALSE (for horizontal).

The 2 zones in the example above are defined as:

Parameters | Equivalent java class/property
CHART_TARGET_ZONE_1=3;5;1|BLACK|NORMAL;LIGHTBLUE|0.5;@font value='ARIAL|PLAIN|12'@@Position value=',-25px'@Weekend;TRUE CHART_TARGET_ZONE_2=30;;2|RED|NORMAL;;@Position value='15%,-25px'@@font value='ARIAL|ITALIC|12'@Profitability threshold;FALSE Note: you can also use % instead of absolute values: CHART_TARGET_ZONE_2=30%;;2|RED|NORMAL ..... will create a target zone at position 30% of the Y axis (if vertical, or x axis if horizontal). | String value="3;5;1|BLACK|NORMAL;LIGHTBLUE|0.5;@........"; chart.addTargetZone( TargetZone.createFromString(value)); OR TargetZone zone=new TargetZone(3,5, IConstants.UNIT_USER, IConstants.UNIT_USER); zone.style= new LineStyle(1,GraphicsProvider.getColor(ChartColor.BLACK), LineStyle.LINE_NORMAL); zone.fillStyle=new FillStyle(GraphicsProvider.getColor(ChartColor.LIGHTBLUE),0.5); zone.label="@font value='ARIAL|PLAIN|12'@@Position value=',-25px'@Weekend": zone.vertical= true; if you have no end position you use: TargetZone zone=new TargetZone( 3, TargetZone.DISABLED, IConstants.UNIT_USER, IConstants.UNIT_USER);

#### Notes

Notes are chart labels which you define using the label markup language. The label includes always the position tag since notes have no default position and you must specify it.

The following example shows a chart note:

Notes are created using the CHART_NOTE* parameter(where * is a counter starting at 1).

Parameters | Equivalent java class/property
CHART_NOTE1=@image value='warning.PNG'@ @ANCHOR value='1,2' line='1|GREY|DOTS'@ @position value='15%,15%'@Manual tunning\n performed at 6:00 | String note="=@image value='warning.P......"; chart.addNote(note);

#### Format of the values

When you create a linechart or barchart you will normally display the values next to the bar , point or line.

The format of the values can be configured using several parameters:

- SERIE_FORMAT_*: indicates the format of the numeric values in the chart. The default is: "#####.##". (use 0 to indicate a digit, # to indicate a digit or empty and . for the decimal separator)
- SERIE_DATA_LABELS_*: is a list ( | separated) of user defined labels which will be painted instead of the value itself. For example, if you are plotting the values "SERIE_DATA_1=1|2|3" you could use as labels "SERIE_LABEL_TEMPLATE_1=one|two|three".
- SERIE_LABEL_TEMPLATE_*: the template allows you so add markup language tags to the value. The string #value# will be replaced by the value to be plotted. For example, the following parameter:
  SERIE_LABEL_TEMPLATE_1=@background value='WHITE'@@border value='1|BLACK|NORMAL'@ #value#
  will produce the labels as seen in the screenshot below.
  where * is the number of the serie

The following table shows the equivalent java properties for the parameters:

Parameters | Equivalent java class/property
SERIE_FORMAT_1=#### SERIE_DATA_LABELS_1=one|two|three SERIE_LABEL_TEMPLATE_1=@background value='WHITE'@@border value='1|BLACK|NORMAL'@ #value# | dataSerie.valueFormat="####"; dataSerie.dataLabels=new String[] {"one","two","three"}; dataSerie.labelTemplate="@background value='WHITE'@@border value='1|BLACK|NORMAL'@ #value#";