skip to main content
Charts > Programmer's documentation > Developing with the JViews Charts SDK > Scales > Computing Scale Graduation
 
Computing Scale Graduation
The IlvStepsDefinition abstract class
The base class used to represent a scale steps definition is the IlvStepsDefinition abstract class. This class defines how scale steps are computed and how steps values are translated into a label. For more information, see Computing scale steps.
By default, a scale automatically creates a scale definition when it is constructed. You can also specify by hand the steps definition a scale should use, by means of the IlvScale.setStepsDefinition method.
Standard numerical values
The IlvDefaultStepsDefinition class provides a default numbering of numeric steps. The steps and substeps values are defined by:
*a step unit, which corresponds to the value between two consecutive steps,
*a substep unit, which corresponds to the value between two consecutive substeps.
The step and substep unit values are either automatically computed at run time or explicitly set by means of the setStepUnit and setSubStepUnit methods. Calling one of these methods disables the automatic steps calculation mode for the corresponding unit.
The steps labels are computed according to a number format, instance of java.text.NumberFormat. By default, the format to use is automatically computed by the steps definition. You can disable the automatic format calculation by manually specify the number format to use by means of the following method:
 
IlvDefaultStepsDefinition.setNumberFormat()
The IlvScale natively supports this default steps definition class. The method setStepUnit provides a shortcut to the methods setStepUnit and setSubStepUnit on the IlvStepsDefinition object
Time values
The IlvTimeStepsDefinition class provides a default numbering for time values. The steps values are defined by a step unit, expressed as a time value. This time unit is an instance of the IlvTimeUnit class, and default implementations are provided to handle one of the following predefined units:
 
IlvTimeUnit.SECOND
IlvTimeUnit.MINUTE
IlvTimeUnit.HOUR
IlvTimeUnit.DAY
IlvTimeUnit.WEEK
IlvTimeUnit.MONTH
IlvTimeUnit.QUARTER
IlvTimeUnit.YEAR
IlvTimeUnit.DECADE
IlvTimeUnit.CENTURY
Besides these predefined time units, the JViews Charts package provides a specialized IlvTimeUnit subclass, the IlvMultipleTimeUnit class, that allows you to define new time units as a multiple of predefined time units.
For example, the following code creates a time unit equal to 15 minutes:
 
IlvTimeUnit unit = new IlvMultipleTimeUnit(IlvTimeUnit.MINUTE, 15);
The IlvMultipleTimeUnit class can also be used to easily change the default implementation of a predefined IlvTimeUnit subclass. This new implementation is not obtained by subclassing but by defining a new IlvMultipleTimeUnit. This new multiple time unit must be based on the predefined unit to modify, with a multiplier factor of 1, and must override the proper methods.
For example, the following code shows how to modify the default format string of the IlvTimeUnit.MONTH class so that it returns the full month name instead of the abbreviated form:
 
IlvTimeUnit monthUnit =
    new IlvMultipleTimeUnit(IlvTimeUnit.MONTH, 1) {
        public String getFormatString() {
            return “MMMMM”;
        }
    };
The step unit is either automatically computed at run time or explicitly set by means of the setUnit method. In the latter case, the automatic time unit calculation mode is disabled.
Time units chosen during the automatic unit calculation process must be specified to the time steps definition by means of the IlvTimeStepsDefinition.setAutoUnits method. This method takes an IlvTimeUnit array as a parameter that contains all the units to consider. By default, all predefined units are taken into account.
The following code shows how to replace the predefined month unit by a new month unit in the automatic unit calculation process constraining the units from hour to month:
 
IlvTimeUnit[] autoUnits = {
    IlvTimeUnit.HOUR,
    IlvTimeUnit.DAY,
    IlvTimeUnit.WEEK,
    monthUnit
};
timeStepsDefinition.setAutoUnits(autoUnits);
The step labels are computed using a java.text.DateFormat instance. This format is dependent on the current time unit and is performed in the computeLabel method.
The IlvScale natively supports the IlvTimeStepsDefinition class. The method setTimeUnit installs an IlvTimeStepsDefinition instance, if needed, and provides a shortcut to the setUnit method on the IlvTimeStepsDefinition object.
Displaying categories
The IlvCategoryStepsDefinition class provides a default numbering for scales displaying categories.
The steps are computed so that there is one step for each category and one substep between two consecutive categories. The steps labels are computed to display either the categories number or the data labels of a data set.
The IlvScale natively supports the IlvCategoryStepsDefinition class. The method setCategory installs an IlvCategoryStepsDefinition instance.
Displaying logarithmic scales
The IlvLogarithmicStepsDefinition class provides a default numbering for scales with a logarithmic axis transformer.
The IlvScale natively supports the IlvLogarithmicStepsDefinition class. The method setLogarithmic installs an IlvLogarithmicStepsDefinition instance and also sets the axis transformer that is applied to data points to a logarithmic one.
The shorthand methods
To specify which data type the scale is handling, and which steps definition class to use, the IlvScale class provides the following methods:
*setStepUnit
Handles numerical values and uses an IlvDefaultStepsDefinition instance.
*setTimeUnit
Handles time values and uses an IlvTimeStepsDefinition instance.
*setCategory
Handles categories and uses an IlvCategoryStepsDefinition instance.
*setLogarithmic
Handles logarithmic values and uses an IlvLogarithmicStepsDefinition instance. This method also sets the axis transformer that is applied to data points to a logarithmic one.
Computing scale steps
The scale steps are computed according to a step unit. The step unit is defined as the increment between two consecutive steps, and its value depends on the data type the scale is handling: numerical value or time unit (as a day, a week, and so on).
The IlvStepsDefinition class provides an iterator-like API to iterate through the graduations in a step-by-step way by means of the following methods:
*nextStep
Returns the step value that immediately follows the specified value.
*previousStep
Returns the previous step value immediately before the specified value.
*incrementStep
Increments the specified step.
NOTE The two last methods are abstract and are implemented by subclasses, depending on their data type.
Translating steps values into a label
Scale steps values are translated into string by the scale steps definition. The translation depends on the concrete implementations of the IlvStepsDefinition class and is performed by means of the computeLabel method.

Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.