4
Building a Chart

Building a chart is quite easy. The chart can automatically set properties based on the data, so axis numbering and data display usually do not need much customization.

Creating a New Chart in a Nutshell

If one exists, use an existing chart as a starting point for the new one. The sample charts provided as part of the JClass Chart package are a good starting point. Load a chart description resembling the new chart.
Load your data into the chart.
Set the chart type.
Annotate and format the axes and data if necessary, as described by the following tasks:
- Annotating with Values (default)
- Annotating with ValueLabels
- Annotating with PointLabels
- Annotating with TimeLabels
- Positioning Axis Annotations
- Chart Orientation and Axis Direction
- Setting Axis Bounds
- Customizing Origins
- Logarithmic Axes
- Titling Axes and Rotating Axis Elements
- Adding Grid Lines
- Adding a Second Axis.

Axis Annotation Overview

The annotations along each axis are an extremely important part of any chart. JClass Chart can annotate any axis with numbers based on data (Values), or with text you supply to be displayed at a specific coordinate (ValueLabels). The X-axis can also be annotated with text for each point in the data (PointLabels), or with automatically-generated time values (TimeLabels).

Whichever annotation method you choose for each axis, the JClass Chart takes considerable effort to automatically produce the most natural annotation possible, even as chart data changes. It is also possible to change annotation properties in order to fine-tune this process.

Note: Pie charts do not have axes. None of the properties discussed in this section apply to pie charts.

Values Annotation

Perhaps the most common type of annotation, Values automatically generates numeric annotation based on the data itself. Values annotation can be used for any axis, with any chart type, and with any data layout. Values work best with plot or scatterplot chart-types.

See Annotating with Values later in this chapter for details on using Values annotation.

ValueLabels Annotation

ValueLabels are a very flexible type of annotation, displaying the defined text at a specific axis coordinate. This is useful for labelling specific coordinates, or to add annotations of a type that the chart does not provide, such as scientific notation. ValueLabels annotation can be used for any axis, with any chart type, and with any data layout. ValueLabels work best with plot or scatterplot chart-types.

See Annotating with ValueLabels later in this chapter for details on setting up ValueLabels.

PointLabels Annotation

PointLabels displays text you define at each point along the axis. It is the only way to annotate the axis of bar and stacking bar charts. PointLabels annotation can be used with any chart type. PointLabels must be used with Array formatted data.

See Annotating with PointLabels later in this chapter for details on setting up PointLabels.

TimeLabels Annotation

TimeLabels automatically generates axis annotations along a time scale, based on the data and using the starting point and format you specify. This is useful for charts that measure something in seconds, minutes, hours, days, weeks, months, or years. TimeLabels annotation can be used for the X-axis of any form of data layout. TimeLabels work best with plot or scatterplot chart-types.

See Annotating with TimeLabels later in this chapter for details on setting up TimeLabels.

Choosing Annotation Method

Use the axis AnnotationMethod property to specify the method used to annotate an axis. The button beside this property displays a dialog of properties that apply to the current annotation method. The valid values for AnnotationMethod include:

JCAxis.VALUE - axis annotations are generated by chart, with possible callbacks to a label generator
JCAxis.VALUE_LABELS - axis annotations are taken from a list of value labels provided by the user. (Note that a value label is a label that is to appear at a particular value along the axis)
JCAxis.POINT_LABELS - axis annotations come from the data source in the form of point labels i.e. labels associated with particular data points
JCAxis.TIME_LABELS - chart generates time/date/labels based on the TimeUnit, TimeBase and TimeFormat properties.

JCAxis.VALUE is the default value for AnnotationMethod.

Note: setAnnotationMethod(JCAxis.POINT_LABELS) is only valid for an X-axis. An X-axis is defined as an axis that is referenced in the collection of X-axes in JCChartArea. This means that a new JCAxis instance that has not yet been added to JCChartArea will not be considered an X-axis.

Annotating with Values

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.

See Values Annotation earlier in this chapter for an Overview of Axis Annotation.

Note: The X-axis of bar and stacking bar charts cannot use Values annotation.

Numbering Precision

Use the Precision axis property to set the number of decimal places to use when displaying each number. The PrecisionIsDefault property allows the chart to automatically determine precision based on the data. The effect of Precision 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.

The default value of Precision is calculated from the data supplied.

Numbering and Ticking Increments

Use the NumSpacing axis property to set the increment between labels along an axis. The NumSpacingIsDefault property allows the chart to automatically determine the increment.

Use the TickSpacing axis property to set the increment between ticks along an axis. This should generally divide equally into NumSpacing on axes using Values annotation. The TickSpacingIsDefault property allows the chart to automatically determine the increment. Note that if AnnotationMethod property is set to POINT_LABELS, tick lines appear at point values.

Annotating with ValueLabels

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, such as scientific notation, is needed. You can set the axis coordinate and the text to display for each ValueLabel, and also add and remove individual ValueLabels.

JClass Chart illustrating the effects of ValueLabel annotation

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

Use the Value property to set the axis coordinate to display the label. Use the Label property to specify the text to display. Set AnnotationMethod to ValueLabels for an axis and click the button beside that property to display the dialog.

See ValueLabels Annotation earlier in this chapter for an overview of Axis Annotation.

Annotating with PointLabels

PointLabels annotation displays defined labels along the axis. This is useful for annotating the axis of any chart using Array data layout, including 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

JClass Chart depicting several PointLabels

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.

See PointLabels Annotation earlier in this chapter for an overview of Axis Annotation.

Annotating with TimeLabels

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.

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

JCAxis.
TimeBase
TimeFormat
AnnotationMethod

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 starting point that the time-axis is measured from. Use the Java Date class (java.util.Date) to specify the TimeBase. The default for TimeBase is the current time.

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 special format codes. The chart displays only the parts of the date/time specified by Format. The following lists all of the valid format codes:

%a	Weekday name, abbreviated
%A	Weekday name
%b	Month name, abbreviated
%B	Month name
%c	Appropriate date/time representation
%d	Day of month (01 to 31)
%H	Hour (0 to 23)
%I	Hour (0 to 12)
%m	Month number (01 to 12)
%M	Minute of hour (00 to 59)
%p	AM or PM
%S	Seconds (00 to 61)
%U	Week number of year (00 to 53), Sunday first day of week 1
%w	Weekday number (0 to 6), Sunday = 0
%x	Appropriate date representation
%X	Appropriate time representation
%y	Year number within century (00 to 99)
%Y	Year

Listing of all valid time format codes

The default for TimeFormat is calculated based on the value for TimeUnit.

See TimeLabels Annotation earlier in this chapter for an overview of Axis Annotation.

Positioning Axis Annotations

Axis annotation typically appears beside its axis. This may be a problem on charts with an origin that is not at the axis minimum or maximum. The chart can automatically determine where to place annotation in different situations, depending on the chart type. If this does not give the desired results, specify where to place the annotation for each axis.

JClass Chart displaying X- and Y-axes set to Min

Specifying Annotation Placement

Use the AnnotationPlacement property to specify annotation placement for an axis. Use the AnnotationPlacementIsDefault property to specify whether the chart determines the annotation placement. When AnnotationPlacementIsDefault is set to true, annotations on plot charts are placed at the origin; on bar and stacking bar charts they are placed at the end of the axis closest to the origin. You can also explicitly place annotations at the origin, the axis minimum, or the axis maximum.

Note: In some cases, JClass may change the AnnotationPlacement. For example, AnnotationPlacement for the Y-axis is ignored on bar and stacking bar charts and plot and area charts when using PointLabels annotation.

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.

Chart Orientation

Use the IsInverted property of ChartDataView to change the chart orientation. When set to true, the X-axis is drawn vertically and the Y-axis are drawn horizontally for the data view. Any properties set on the X-axis apply to the vertical axis, and Y-axis properties apply to the horizontal axis.

Note: The IsInverted property is associated with a single DataView.

Two JClass Charts depicting different orientations

Axis Direction

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

The X-axis can only be reversed on plot and area charts not using PointLabels axis annotation.

Two JClass Charts depicting normal and reversed X- and Y- axes

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.

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.

JClass Chart displaying customized X- and Y- origins

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, and 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.

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.

JClass Chart depicting logarithmic data

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

any data that is less than or equal to zero is not graphed (it is treated as a data hole), since a logarithmic axis only handles data values that are greater than zero. For the same reason, axis and data minimum/maximum bounds and origin properties cannot be set to zero or less.
axis numbering increment, ticking increment, and precision properties have no effect when the axis is logarithmic.
the X-axis of bar, stacking bar, and pie charts cannot be logarithmic.
the annotation method for the X-axis cannot be PointLabels or TimeLabels.

Specifying a Logarithmic Axis

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

Note: Pie charts are not affected by logarithmic axes.

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.

JClass Chart containing two axis legends

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.

Axis Title Rotation

Use the Rotation property of JCAxisTitle to set the orientation of the Title. There are four available values: DEG_0 (zero rotation), DEG_90 (rotate title 90 degrees), DEG_180 (rotate title 180 degrees), and DEG_270 (rotate title 270 degrees).

Axis Title Text

Use the Text property of JCAxisTitle for an axis to set the text of the title. The text can be either a regular string, or a JCString. For more information on JCStrings, see Appendix B.

Rotating Axis Annotation

Use the AnnotationRotation property of JCAxis to rotate the axis annotation to either 90 or 270 degrees counterclockwise. 270-degree rotation usually looks best on the Y-axis.

Adding Grid Lines

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.

JClass Chart illustrating the effects of grid lines

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

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 GridIsShowing used within a program:

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

Adding a Second Axis

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

JClass 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:

  // Make an x axis 
  otherYAxis = new JCAxis();
  // Make sure it is a vertical axis
  otherYAxis.setIsVertical(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);

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.

Hiding the Second Axis

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

Other Second-Axis Properties

Properties for the second axis can be customized, including AnnotationMethod, Min, Max, IsLogarithmic, NumMethod, NumSpacing, and Title.

4 Building a Chart