JClass Chart

PreviousNextIndex

7

Axis Controls

Creating a New Chart in a Nutshell  Axis Labelling and Annotation Methods  Positioning Axes

Chart Orientation and Axis Direction  Setting Axis Bounds  Customizing Origins

Logarithmic Axes  Titling Axes and Rotating Axis Elements

Adding Gridlines  Adding a Second Axis

JClass Chart can automatically set properties based on the data, so axis numbering and data display usually do not need much customizing. You can however, control any aspect of the chart axes, depending on your requirements. This chapter covers the different axis controls available. If you are developing your chart application using one of the JClass Chart Beans, please refer to Bean Reference, in Chapter 4.

7.1 Creating a New Chart in a Nutshell

  1. If one exists, use an existing chart as a starting point for the new one. The sample charts provided in JCLASS_HOME/examples/chart/ are a good starting point. Load a chart description resembling the new chart.
  2. Load your data into the chart.
  3. Set the chart type.
  4. Annotate and format the axes and data if necessary, described as follows:
    • Axis annotation (Values [default], ValueLabels, PointLabels, TimeLabels)
    • Positioning Axis Annotations
    • Chart Orientation and Axis Direction
    • Setting Axis Bounds
    • Customizing Origins
    • Logarithmic Axes
    • Titling Axes and Rotating Axis Elements
    • Adding Gridlines
    • Adding a Second Axis

7.2 Axis Labelling and Annotation Methods

There are several ways to annotate the chart's axes, each suited to specific situations.

Please note that none of the axis properties discussed in this section apply to Pie charts because Pie charts do not have axes. To annotate a Pie Chart, use Chart Labels; for more information, please see Chart Labels, in Chapter 9.

Whichever annotation method you choose, the chart makes considerable effort to produce the most natural annotation possible, even as the data changes. You can fine-tune this process using axis annotation properties.

User-set annotations support the use of HTML tags. The use of HTML tags overrides the default Font and Color properties of the label.

Please note that HTML labels may not work with PDF, PS, or PCL encoding.

7.2.1 Choosing Annotation Method

A variety of properties combine to determine the annotation that appears on the axes. The JCAxis AnnotationMethod property specifies the method used to annotate the axis. The valid annotation methods are:

JCAxis.VALUE

(default)

The chart chooses appropriate axis annotation automatically (with possible callbacks to a label generator), based on the chart type and the data itself.

JCAxis.
 POINT_LABELS

(X-axis only)

The chart spaces the points based on the X-values and annotates them with text you specify (in the data source) for each point.

JCAxis.
 VALUE_LABELS

The chart annotates the axis with text you define for specific X- or Y-axis coordinates.

JCAxis.
 TIME_LABELS

The chart interprets the X- or Y-values as units of time, automatically choosing time/date annotation based on the starting point and format you specify. Not for Polar, Radar, or Area Radar charts.

Notes:

The following topics discuss setting up and fine-tuning each type of annotation.

7.2.2 Values Annotation

Values annotation produces numeric labelling along an axis, based on the data itself. The chart can produce very natural-looking axis numbering automatically, but you can fine-tune the properties that control this process.

Axis Annotation Increments, Numbering, and Precision

When a JCAxis is instantiated, a pair of JCAnno objects representing default labels and ticks are automatically created and set on the axis. Those default JCAnno objects may be modified, deleted, or augmented with other JCAnno objects.

The following describes the different properties that can be set on a JCAnno object in order to fully customize the labels and tick marks:

Property

Function

startValue Sets the value at which the annotation begins.
stopValue Sets the value where the annotation ends.
incrementValue Sets the increment between annotation along an axis.
innerExtent Defines the space, in pixels, that tick marks extend into the plot area.
outerExtent Defines the space, in pixels, that tick marks extend out of the plot area.
tickColor Determines the color of the tick marks.
drawTicks Determines whether or not the tick marks defined by JCAnno are drawn.
labelExtent Defines the distance, in pixels, of the labels from the axis.
labelColor Determines the color of the labels.
precision Sets the number of decimal places to use when displaying a chart label number. The effect depends on whether it is positive or negative:
  • Positive values add that number of places after the decimal place. For example, a value of 2 displays an annotation of 10 as "10.00".
  • Negative values indicate the minimum number of zeros to use before the decimal place. For example, a value of -2 displays annotation in multiples of 100.
    • drawLabels Determines whether or not the labels defined by JCAnno are drawn.

    When the annotation method for an axis is VALUE_LABELS, POINT_LABELS, or TIME_LABELS, the labels are either user-supplied or internally generated without the use of JCAnno objects. The boolean UseAnnoTicks property of a JCAxis determines how tick marks are drawn in those cases. If UseAnnoTicks is true, tick marks are drawn at the labels. If the value is false, ticks defined by JCAnno objects are drawn instead.

    Using multiple JCAnno objects, an axis can be drawn with major and minor ticks. Labels can be turned on or off for the individual tick series, as can the actual tick marks, enabling further flexibility.

    Figure 20 :  Different tick styles that can be applied to a chart axis.

    Please refer to the AnnoGrid.java example included in the examples/chart/intro package to view different tick marks in a JClass Chart example.

    7.2.3 PointLabels Annotation

    PointLabels annotation displays defined labels along an X-axis. This is useful for annotating the X-axis of any chart for which all series share common X-values. PointLabels are most useful with bar, stacking bar, and pie charts. It is possible to add, remove, and edit PointLabels. In JClass Chart, PointLabels are typically defined with the data.

    Figure 21 :  PointLabels X-axis annotation.

    PointLabels are a collection of labels. The first label applies to the first point, the second label applies to the second point, and so on.

    The labels can also be supplied by setting the PointLabels property of the ChartDataView object for this chart. For example, the following code specifies labels for each of the three points on the X-axis:

    String[] labels = {"Q1", "Q2", "Q3, "Q4"}; c.getChartArea().getXAxis(0).setAnnotationMethod(JCAxis.POINT_LABELS);
    ChartDataView cd = c.getDataView(0);
    ArrayList pLabels = new ArrayList();
    for (int i = 0; i < labels.length; i++) {
      pLabels.add(labels[i]);
    }
    cd.setPointLabels(pLabels);

    For Polar, Radar, and Area Radar charts, if the X-axis annotation is POINT_LABELS and the data is of type array, then a point label is drawn at the outside of the X-axis for each point. (Series labels are used in the legend as usual.)

    7.2.4 ValueLabels Annotation

    ValueLabels annotation displays labels at the axis coordinate specified. This is useful for displaying special text at a specific axis coordinate, or when a type of annotation that the chart does not support is needed, such as scientific notation. You can set the axis coordinate and the text to display for each ValueLabel, and also add and remove individual ValueLabels.

    Figure 22 :  Using ValueLabels to annotate axes.

    Every label displayed on the axis is one ValueLabel. Each ValueLabel has a Value property and a Label property.

    If the AnnotationMethod property is set to JCAxis.VALUE_LABELS, the chart places labels at explicit locations along an axis. The ValueLabels property of JCAxis, which is a ValueLabels collection, supplies this list of Strings and their locations. For example, the following code sets value labels at the locations 10, 20, and 30:

    String[] labels = {"Sales", "Beta Testing", "Documentation",
              "Alpha Testing", "Programming",
              "Production Definition"};
    JCAxis y = c.getChartArea().getYAxis(0);
    y.setAnnotationMethod(JCAxis.VALUE_LABELS);
    JCValueLabel[] valueLabels = new JCValueLabel[labels.length];
    for (int i = 0; i < labels.length; i++) {
       valueLabels[i] = new JCValueLabel(10.0 * (i + 1), labels[i], y);
    }
    y.setValueLabels(valueLabels);

    The ValueLabels collection can be indexed either by subscript or by value:

    JCAxis x = c.getChartArea().getXAxis(0);
    // The following retrieves the second value label
    JCValueLabel v1 = x.getValueLabels(1);
    // The following retrieves the closest label to chart coordinate 2.0
    JCValueLabel v2 = x.getValueLabel(2.0);

    7.2.5 TimeLabels Annotation

    TimeLabels annotation interprets the value data as units of time. The chart calculates and displays a time-axis based on the starting point and format specified. A time-axis is useful for charts that measure something in seconds, minutes, hours, days, weeks, months, or years.

    Figure 23 :  TimeLabels annotating X- and Y-axes.

    Four properties are used to control the display and behavior of TimeLabels:

    Time Unit

    Use the TimeUnit property to specify how to interpret the values in the data. Select either JCAxis.SECONDS, JCAxis.MINUTES, JCAxis.HOURS, JCAxis.WEEKS, JCAxis.MONTHS, or JCAxis.YEARS. For example, when set to JCAxis.YEARS, values that range from 5 to 15 become a time-axis spanning 10 years. By default, TimeUnit is set to JCAxis.SECONDS.

    Time Base

    Use the TimeBase property to set the date and time that the time-axis starts from. Use the Java Date class (java.util.Date) to specify the TimeBase. The default for TimeBase is the current time.

    For example, the following statement sets the starting point to January 15, 1985:

    c.getChartArea().getXAxis(0).setTimeBase(new Date(85,0,15));

    Time Format

    Use the TimeFormat property to specify the text to display at each annotation point. The TimeFormatIsDefault property allows the chart to automatically determine an appropriate format based on the TimeUnit property and the data, so it is often unnecessary to customize the format.

    TimeFormat specifies a time format. You build a time format using the Java time format codes from the java.text.SimpleDateFormat class. The chart displays only the parts of the date/time specified by TimeFormat. The format codes are based on the default Java formatting provided by java.text.

    Symbol

    Meaning

    Presentation

    Example

    G

    era designator

     

    AD

    y

    year

    Number

    1997

    M

    month in year

    Text & Number

    July 07

    d

    day in month

    Number

    10

    h

    hour in am/pm (1 ~12)

    Number

    12

    H

    hour in day (0~23)

    Number

    0

    m

    minute in hour

    Number

    30

    s

    second in minute

    Number

    55

    S

    millisecond

    Number

    978

    E

    day in week

    Text

    Tuesday

    D

    day in year

    Number

    189

    F

    day of week in month

    Number

    2nd Wed in July

    w

    week in year

    Number

    27

    W

    week in month

    Number

    2

    a

    am/pm marker

    Text

    PM

    k

    hour in day (1~24)

    Number

    24

    K

    hour in am/pm (0~11)

    Number

    0

    z

    time zone

    Text

    Pacific Standard Time

    '

    escape for text

    delimiter

     

    ''

    single quote

    Literal

     

    The default for TimeFormat is the same as the default used by Java's SimpleDateFormat class (located in the java.text package).

    Using Date Methods

    The dateToValue() method converts a Java date value into its corresponding axis value (a floating-point value). The valueToDate() method converts a value along an axis to the date that it represents. Note that the axis must already be set as a time label axis.

    Here is a code example showing the dateToValue() method converting a date (in this case, February 2, 1999) to a Y-axis value, and showing the valueToDate() method converting a Y-axis value (in this case, 3.0) to the date that it represents.

    JCAxis y = chart.getChartArea().getYAxis(0);
    Date d = y.valueToDate(3.0);
    double val = y.dateToValue(new Date(99,1,2));

    7.2.6 Custom Axes Labels

    JClass Chart will label axes by default. However, you can also generate custom labels for the axes by implementing the JCLabelGenerator interface. This interface has one method - makeLabel() - that is called when a label is required at a particular value.

    Note that the spokes of Radar and Area Radar charts will be automatically labelled "0", "1", "2", and so forth, unless the X-annotation method is JCAxis.POINT_LABELS.

    To generate custom axes labels, the axis' AnnotationMethod property, which determines how the axis is labelled, must be set to VALUE. Also, the setLabelGenerator() method must be called with the class that implements the JCLabelGenerator interface.

    The number of labels, that is, the number of times makeLabel() is called, depends on the NumSpacing parameter of the axis. Not all labels will be displayed if there is not enough room.

    The makeLabel() method takes two parameters: value (the axis value to be labelled) and precision (the numeric precision to be used).

    class MyLabelGenerator implements JCLabelGenerator
    {
      public Object makeLabel(double value, int precision) {
        int intvalue = (int) value;
        String s = null;
        switch (intvalue) {
          case 1 :
            s = "I";
            break;
          case 2 :
            s = "II";
            break;
          case 3 :
            s = "III";
            break;
          case 4 :
            s = "IV";
            break;
          case 5 :
            s = "V";
            break;
          case 6 :
            s = "VI";
            break;
          case 7 :
            s = "VII";
            break;
          case 8 :
            s = "VIII";
            break;
          case 9 :
            s = "IX";
            break;
          case 10 :
            s = "X";
            break;
          default :
            s = "";
            break;
        }
        return s;
      }
    }

    Note that the user will need to specify the label generator as follows:

    axis.setLabelGenerator(new MyLabelGenerator());

    Also note that JClass Chart calls the makeLabel() method for each needed label (recall that each axis requests needed labels based on its NumSpacing, Min, and Max properties). Thus, if JClass Chart needs n labels, the makeLabel() method is called n times.

    7.3 Positioning Axes

    Use the Placement property to make a specific axis placement or use the PlacementIsDefault property to specify whether the chart is meant to determine axis placement. When making a specific axis placement, the axis may be placed against its partner axis at the partner axis' minimum value, maximum value, origin value, or a user-specified value.

    For example,

    axis.setPlacement(JCAxis.MIN);

    will place the axis against its partner axis' minimum value, and

    axis.setPlacement(otherAxis, 5.0)

    will place the axis against otherAxis at the value 5.0.

    Note: When Placement is set to Origin, changing the axis origin will move the placed axis to the new origin value.

    Figure 24 :  An example of axes positioning; the X-axis is placed against the Y-axis' minimum value.

    Polar Charts - Special Minimum and Maximum Values

    Note that for Polar charts, the X-axis max and min values are fixed, and these fixed values change depending on the angle unit type. The Y-axis max and min values are adjustable, but are constrained to avoid data clipping. The Y-axis min will never be less than zero (unless the Y-axis is reversed). (theta, -r) will be interpreted as (theta+180, r). The Y-axis min will always be at the center unless the axis is reversed, in which case the Y-axis max will be at the center.

    Radar and Area Radar Charts - Minimum Values

    The minimum value for a Y-axis in Radar and Area Radar charts can be negative.

    7.4 Chart Orientation and Axis Direction

    A typical chart draws the X-axis horizontally from left-to-right, and the Y-axes vertically from bottom-to-top. You can reverse the orientation of the entire chart, and/or the direction of each axis.

    7.4.1 Inverting Chart Orientation

    Use the ChartDataView object's Inverted property to change the chart orientation. When set to true, the X-axis is drawn vertically and the Y-axis horizontally for the data view. Any properties set on the X-axis then apply to the vertical axis, and Y-axis properties apply to the horizontal axis.

    Note: To switch the orientation of charts with multiple data views, you must set the Inverted property of each ChartDataView object.

    Figure 25 :  Normal and inverted orientation.

    7.4.2 Changing Axis Direction

    Use the Reversed property of JCAxis to reverse the direction of an axis. By default, Reversed is set to false.

    Figure 26 :  Two charts depicting a normal and reversed Y- axis.

    For Polar charts, data points with positive X-values will be displayed in a counterclockwise direction starting at the origin base. When the XAxis.reversed flag is true, positive X-values will be displayed clockwise.

    7.5 Setting Axis Bounds

    Normally a graph displays all of the data it contains. There are situations where only part of the data is to be displayed. This can be accomplished by fixing axis bounds.

    Min and Max

    Use the Min and Max properties of JCAxis to frame a chart at specific axis values. The MinIsDefault and MaxIsDefault properties allow the chart to automatically determine axis bounds based on the data bounds.

    7.6 Customizing Origins

    The chart can choose appropriate origins for the axes automatically, based on the data. It is also possible to customize how the chart determines the origin, or to directly specify the coordinates of the origin.

    Figure 27 :  Defining origins for X- and Y-axes.

    Origin Placement

    The easiest way to customize an origin is by controlling its placement, using the Axes' OriginPlacement property. It has four possible values: AUTOMATIC, ZERO, MIN, and MAX. When set to AUTOMATIC, the origin is placed at the axis minimum or at zero, if the data contains positive and negative values or is a bar chart. ZERO places the origin at zero. MIN places the origin at the minimum value on the axis. MAX places the origin at the maximum value on axis.

    Origin Coordinates

    When the origin of a coordinate must be set to a value different from the default (0,0), use the Axes' Origin property. The OriginIsDefault property allows the chart to automatically determine the origin coordinate based on the data.

    Note: When an origin coordinate is explicitly set or fixed, the chart ignores the OriginPlacement property.

    7.7 Logarithmic Axes

    Axis annotation is normally interpreted and drawn in a linear fashion. It is also possible to set any axis to be interpreted logarithmically (log base 10), as shown in the following image. Logarithmic axes are useful for charting certain types of scientific data.

    Figure 28 :  Logarithmic X- and Y-axes.

    Because of the nature of logarithmic axes, they impose the following restrictions on the chart:

    Specifying a Logarithmic Axis

    Use the Logarithmic property of JCAxis to make an axis logarithmic.

    Note: Pie charts are not affected by logarithmic axes.

    7.8 Titling Axes and Rotating Axis Elements

    Adding a title to an axis clarifies what is charted along that axis. You can add a title to any axis, and also rotate the title or the annotation along the axis, as shown below.

    Figure 29 :  Rotated axis title and annotation.

    Adding an Axis Title

    Use the Title property to add a title to an axis. It sets the JCAxisTitle object associated with the JCAxis. JCAxisTitle controls the appearance of the axis title. JCAxisTitle's Text property specifies the title text.

    Axis Title Rotation

    Use the Rotation property of JCAxisTitle to set the rotation of the title. Valid values are defined in ChartText: DEG_0 (no rotation), DEG_90 (90 degrees counterclockwise), DEG_180 (180 degrees), and DEG_270 (270 degrees).

    Rotating Axis Annotation

    Use the AnnotationRotation property of JCAxis to rotate the axis annotation to either 90, 180, or 270 degrees clockwise from the horizontal position. 90-degree rotation usually looks best on a right-hand side axis.

    This property can also be used to rotate the annotation at any other specified angle, if it is set to AnnotationRotation.ROTATION_OTHER. The new angle will be determined by the AnnotationRotationAngle property's value. By default, the angle is 0.0 degrees.

    It is important to know that some fonts may not draw properly at an angle; therefore, they might not be visually appealing. If you are using rotated labels, your font choice should be made with care.

    Note: In some cases, rotated labels will overlap. When labels overlap, the visible property for the higher indexed label is cleared, and only the lower indexed label is visible.

    7.9 Adding Gridlines

    Displaying a grid on a chart can make it easier to see the exact value of data points. The spacing between lines on the grid can be defined to determine how a grid is displayed.

    Figure 30 :  JClass Chart illustrating the effects of gridlines.

    Horizontal gridlines are a property of the Y-axis. Vertical gridlines are a property of the X-axis. Set GridVisible to true to display gridlines.

    Note that for Polar charts, Y-gridlines will be circular while X-gridlines will be radial lines from the center to the outside of the plot. For both Radar and Area Radar charts, radar lines are represented by the X-axis gridlines. You may choose normal gridlines (circular) or "webbed" gridlines. For the Y-axis, you may also have gridlines on (default is off).

    Grid Spacing

    Use the GridSpacing property to customize the grid spacing for an axis. The GridSpacingIsDefault property allows the chart to space the grid automatically, drawing a gridline wherever there is annotation. By default, gridlines will correspond with axis annotations.

    Grid Appearance

    Use the grid GridStyle properties to customize the line pattern, thickness, and color of the gridlines. The following code fragment provides a sample of GridStyle and GridVisible used within a program:

      otherXAxis.setGridVisible(true);
      otherXAxis.getGridStyle().getLineStyle().setColor(Color.green);
      otherYAxis.setGridVisible(true);
      otherYAxis.getGridStyle().getLineStyle().setColor(Color.green);

    7.10 Adding a Second Axis

    There are two ways to create a second Y-axis on a chart. The simplest way is to define a numeric relationship between the two Y-axes, as shown in the following illustration. Use this to display a different scale or interpretation of the same graph data.

    Note that for Polar, Radar, and Area Radar charts, there is no second Y-axis.

    Defining Axis Multiplier

    Use the Multiplier property to define the multiplication factor for the second axis. This property is used to generate axis values based on the first axis. The multiplication factor can be positive or negative.

    Using a Constant Value

    Use the Constant axis property to define a value to be added to or subtracted from the axis values generated by Multiplier.

    Figure 31 :  Chart containing multiple Y-axes.

    In some cases, it may be desirable to show two sets of data in the same chart that are plotted against different axes. JClass Chart supports this by allowing each DataView to specify its own XAxis and YAxis. For example, consider a case in which a second data set d2 is to be plotted against its own Y-axis. A JCAxis instance must be created and added to the JCChartArea, as shown:

      // Create a Y-axis and set it vertical
      otherYAxis = new JCAxis();
      otherYAxis.setVertical(true);

      // Add it to the list of Y-axes in the chart area
      c.getChartArea().setYAxis(1, otherYAxis);
      // Add it to the data view
      d2.setYAxis(otherYAxis);

    Hiding the Second Axis

    Set the Visible property to false to remove it from display. By default, it is set to true.

    Other Second-Axis Properties

    All axes have the same features. Any property can be set on any axis.

    PreviousNextIndex