Scale Labels
General properties
The following table shows the properties defined by the IlvScale class related to the scale labels.
Property | Methods | Default Value |
Label color | getLabelColor setLabelColor | foreground |
Label offset | getLabelOffset setLabelOffset | 3 |
Label rotation | getLabelRotation setLabelRotation | 0 |
Label visible | isLabelVisible setLabelVisible | true |
Skip labels when overlapping | isSkippingLabel setSkippingLabel | false |
Label format | getLabelFormat setLabelFormat | null |
Label color
The color used to draw the scale labels is defined by the labelColor property and by default equals the scale foreground color.
Label offset
Labels are drawn next to the tick marks spaced from a given offset expressed in pixels. This offset is defined by the labelOffset property and is set to 3 by default.
Label rotation
Steps labels can be rotated from a given rotation angle whose value is expressed in degrees and clockwise oriented. This angle is defined by the
labelRotation property and is set to
0 by default. You can change it by means of the
setLabelRotation method.
Label visibility
The labels can be visible or hidden depending on the value of the labelVisible property. By default, the property is set to true.
Skipping labels when overlapping
Depending on the values and on the way labels are formatted, it may occur that steps labels overlap each other because of the text length. To prevent this, the
IlvScale class provides an automatic mechanism that computes the number of steps to skip between each label so that they do not overlap. This mechanism is defined by the
skippingLabel property and is disabled by default.
Defining the label format
Steps values are displayed in a scale as a formatted text computed from a value format. This format is defined by the
labelFormat property. By default, the
labelFormat property is set to
null and the steps labels are computed from the steps values by the scale steps definition object invoking its
computeLabel method.
To set another value format, use the method:
IlvScale.setLabelFormat(IlvValueFormat)
To change the way labels are computed, override the method:
IlvScale.computeLabel(double)
Example: specifying a customized value format using the API
This example illustrates how an IlvValueFormat can be used to handle discrete time series as categories. Indeed, while an IlvTimeScaleDefinition and the IlvTimeUnit are particularly well-suited for continuous time series, it is better to use the default steps definition of a scale when dealing with discrete time series to have a category-like step numbering and labeling.
For this purpose, you will write the CategoryTimeFormat class, your own IlvValueFormat implementation. This class will convert a data point index into a corresponding date and format it accordingly.
To do so, the class needs to know:
For the date conversion:
The time origin from which an index is converted into a date.
The time step of the categories
For the label formatting:
The format (a pattern as defined by the
java.text.DateFormat class) used to convert the date into a string.
For example, with a time origin equals to 01/01/2000 and a time step corresponding to a year, the index 0 will be converted into 01/01/2000, the index 1 into 01/01/2001, the index 2 into 01/01/2002 and so on, that is:
new date = origin + 'index' time step.
Base on these requirements, the corresponding Java™ class is:
private static class CategoryTimeFormat implements IlvValueFormat
{
private int step;
private Calendar cal = (Calendar)Calendar.getInstance().clone();
private SimpleDateFormat fmt = new SimpleDateFormat();
private Date origin;
/**
* Initialize a new <code>CategoryTimeFormat</code>.
* @param origin The origin of the categories.
* @param step The step of the categories. Should be a valid
* Calendar field value.
* @param unit An optional time unit used to format the label. If
* null, the default format is used.
*/
public CategoryTimeFormat(Date origin, int step, IlvTimeUnit unit)
{
this.origin = origin;
this.step = step;
// set the format pattern, if specified.
if (unit != null)
fmt.applyPattern(unit.getFormatString());
}
/**
* Formats the specified value into a string.
*/
public String formatValue(double value)
{
// compute the date corresponding to the given index.
cal.setTime(origin);
cal.add(step, (int)value);
return fmt.format(cal.getTime());
}
}
A sample application using this class is shown below. The application displays a bar chart of the average precipitation from 1980 to 1990. The data model represents a discrete time series. In other words, data is arranged along the x-axis by time categories. That means that the data series contains y-values only, the x-values of the data set will be computed according to the data point indices. In order to compute the date corresponding to a category index, we will use a CategoryTimeFormat instance to compute x-scale labels. Since the series is distributed year by year, from 1980 to 1990, we configure the CategoryTimeFormat with a time origin equals to 1980 and a time step of a year.
Furthermore, we also want to display the y-scale labels as "<step value> cm". To do so, we set a an IlvValueFormat that append the " cm" string to the string representation of the step values.
Here is the source code of the application (note that we have removed the comments from the original source code to ease reading):
import ilog.views.chart.*;
import ilog.views.chart.data.*;
import ilog.views.chart.renderer.IlvSingleBarRenderer;
import javax.swing.JFrame;
import java.text.*;
import java.util.*;
public class ScaleLabelsExample
{
public static void main(String[] args)
{
final double[] yvalues = {30,80,55,91,125,53,61,98,74, 61};
IlvDataSet dataSet = new IlvDefaultDataSet("Series A", yvalues);
IlvChart chart = new IlvChart();
chart.setHeaderText("Average Precipitation");
chart.addRenderer(new IlvSingleBarRenderer(), dataSet);
chart.getYAxis(0).setDataMin(0);
//-- Handle scales labels.
IlvScale xscale = chart.getXScale();
// We set a CategoryTimeFormat on the x-scale to handle the data
// point indices as "time categories".
Calendar cal = Calendar.getInstance();
cal.set(1980, 0, 1);
xscale.setLabelFormat(new CategoryTimeFormat(cal.getTime(),
Calendar.YEAR,
IlvTimeUnit.YEAR));
// We also set a custom IlvValueFormat on the y-scale so that
// labels are displayed as: value + " cm".
IlvScale yscale = chart.getYScale(0);
yscale.setLabelFormat(new IlvValueFormat() {
private NumberFormat numformat = NumberFormat.getInstance();
public String formatValue(double value) {
return numformat.format(value) + " cm";
}
});
// the gui
JFrame frame = new JFrame("Scales Labelling");
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
frame.getContentPane().add(chart);
frame.setSize(400,300);
frame.setVisible(true);
}
You can see the result in the following figure:
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.
