3
Customizing Charts

3.1 Using Descriptors to Customize Charts

Chart Builder provides several types of descriptors, including graph type descriptors and axis and grid descriptors, that provide additional control over the appearance of chart elements.

Graph type descriptors provide additional control over the style parameters associated with a particular graph type. For example, for an area chart, the fill and line color can be set independently using the AreaDesc( ) object.

To modify any of the elements associated with a graph type, you first create a new descriptor. Then, you use Chart Builder methods to modify the elements. Finally, you associate the descriptor with a series using the setSeriesGraphic( ) method.

The following code creates a new LineDesc descriptor named markerDescCircle, which adds line markers to a line chart:

LineDesc markerDescCircle = new LineDesc();

markerDescCircle.setMarkerType(LineDesc.MARKER_CIRCLE);

MyAxisCh.setSeriesGraphic("Canada", markerDescCircle);

Axis and grid descriptors control attributes of an axis or a grid. For example, the format of currency can be specified through the use of the NumAxisDesc descriptor.

To modify any attributes associated with an axis or grid, you first create a new descriptor. Then, you use Chart Builder methods to modify the attributes. Finally, you associate it with the chart using the setChartAttributes( ) method.

The following code creates the a new NumAxisDesc descriptor named myNumAxisDesc, which sets a dollar sign ($) as the prefix for the Y-axis labels:

NumAxisDesc myNumAxisDesc = new NumAxisDesc();

myNumAxisDesc.setPrefix("$");

myChart.setChartAttributes(myNumAxisDesc);

Many of the topics in this chapter describe how to use descriptors to change specific attributes of a chart.

3.2 Adding and Modifying Titles, Subtitles, and Footnotes

As shown in some of the examples in Chapter 2, you can specify a title, a subtitle, and a footnote for each chart. These are implemented as part of the ChartLabel subclass of the class Chart. In addition, you can modify the font for each of these components, and you can change their colors.

To specify a title for a chart, you use the getTitle( ) method and supply the title to the setText( ) routine. For example, to specify "U.S. Exports to Canada" as the title, use the following code:

MyAxisChart.getTitle().setText("U.S. Exports to Canada");

To specify a subtitle for a chart, you use the getSubtitle( ) subclass and supply the subtitle to the setText( ) routine. For example, to specify "Reported in Thousands" as the subtitle, use the following code:

MyAxisChart.getSubtitle().setText("Reported in Thousands");

To specify a footnote, you use the getFootnote( ) subclass and supply the footnote to the setText( ) routine. For example, to add a footnote to a chart, use the following code:

MyAxisCh.getFootnote().setText("Source: U.S. Department of Commerce, Census Bureau");

You can alter the font of a title, subtitle, or footnote by using the setFont( ) method with the getTitle( ), getSubtitle( ), or getFootnote( ) method. For example, to specify that the title use a boldface Times font with a size of 16 points, use the following code:

MyAxisCh.getTitle().setFont(new Font("Times", Font.BOLD, 16));

By default, Chart Builder sets the color of the text in charts to black. You can alter the color of the title, subtitle, and footnote by using the setForeground( ) method. This method also alters the color of the labels. For example, to change the color of the foreground items to the standard Java red, use the following code:

MyAxisCh.setForeground(Color.red);

If you specify the attributes for a chart as shown in this section, the chart would appear similar to the one shown in the following figure:

If you add a subtitle and a footnote to a chart, you may need to increase the height of the chart to accommodate the additional elements.

3.3 Modifying the Color of Chart Elements

In addition to modifying the foreground colors as described in Section 3.2, you can modify the colors of many of the chart components, including:

• The background

• The labels

• An X-axis series or Y-axis series

• Individual pie slices

You can use the standard Java colors or you can define your own colors. The following example defines two new colors, lightGray and darkBlue:

static Color lightGray = new Color(216,216,216);

static Color darkBlue = new Color(0,0,150);

Then, you can use the defined colors to set the color of any chart element. The following example uses the preceding definitions to set the plot background to light gray. Then, using the AxisDesc descriptor, it sets the X-axis to dark blue.

MyAxisCh.setPlotBackground(lightGray);

AxisDesc xAxisD = new AxisDesc();

xAxisD.setColor(darkBlue);

MyAxisCh.setChartAttributes(AxisChart.XAXIS, xAxisD);

The following example uses standard Java colors to set the color of the Y-Series:

MyAxisCh.setSeriesColor("Bolivia", Color.yellow);

MyAxisCh.setSeriesColor("Guat", Color.blue);

MyAxisCh.setSeriesColor("Japan", Color.red);

MyAxisCh.setSeriesColor("US", Color.green);

For axis charts, you can set the background, the color of the border (the bounding rectangle) around the chart, and the color of the border around the plot area to blend the chart into the background of your application or HTML page. The following example sets the color of these three elements to white:

MyAxisCh.setBackground(Color.white);

MyAxisCh.setEdgeColor(Color.white);

MyAxisCh.setPlotEdgeColor(Color.white);

The following figure shows an axis chart using these color definitions:

For pie charts, you can define the color of each pie slice with the setBackground( ) method for each pie slice descriptor, as described in Section 2.3. Alternatively, you can let Chart Builder generate the color of each pie slice automatically by using the setAutoSliceColor( ) method. This method requires two parameters. The first parameter specifies the color of the first slice; the second specifies the color of the last slice. The colors of all slices in between are interpolated between the colors of the first and last slice. The following example calls the setAutoSliceColor( ) method:

MyPieCh.setAutoSliceColor(Color.yellow, Color.blue);

In addition, you can set the background and the color of the border (the bounding rectangle) around the chart, as shown in the following example:

MyPieCh.setBackground(Color.white);

MyPieCh.setEdgeColor(Color.white);

The following figure shows a pie chart with the background and color of the border set to white:

The following tables show methods that you can use to change the color of chart elements. Methods that are applicable to both axis charts and pie charts are shown in Table 3-1. Methods that are applicable to axis charts only are shown in Table 3-2. Methods that are applicable to pie charts only are shown in Table 3-3.

Table 3-1 Methods for Setting Colors for All Charts

Table 3-2 shows methods that you use to change the color of the chart elements in axis charts.

Table 3-2 Methods for Setting Colors in Axis Charts

Table 3-3 shows methods you use to change the color of chart elements in pie charts.

Table 3-3 Methods for Setting Colors in Pie Charts

Besides the methods listed in the preceding tables, other methods are described in the API documentation.

3.4 Adding Special Effects

With Chart Builder, you can add special effects to bar charts and pie charts:

• You can add drop shadows or a 3-D effect to bar charts. See Section 3.4.1.

• You can add a 3-D effect to pie charts. See Section 3.4.2.

3.4.1 Adding Special Effects to Bar Charts

With Chart Builder, you can add drop shadows or a 3-D effect to any type of bar chart, including clustered, stacked, and horizontal bar charts.

To add these effects, you use the setBarStyle( ) method of the BarDesc class. Use one of the following values as the parameter to the setBarStyle( ) method:

• STYLE_DROP_SHADOW

• STYLE_EFFECT3D

For example, to add drop shadows to a bar chart, you create a BarDesc descriptor and call the setBarStyle( ) method using the following code:

BarDesc dropBar = new BarDesc();

dropBar.setBarStyle(BarDesc.STYLE_DROP_SHADOW);

MyAxisCh.setSeriesGraphic("Airports",dropBar);

The following figure shows a bar chart with drop shadows:

Description of the illustration bar_string_drop.gif

To add a 3-D effect to a bar chart, use the following code:

BarDesc threeDBar = new BarDesc();

threeDBar.setBarStyle(BarDesc.STYLE_EFFECT3D);

MyAxisCh.setSeriesGraphic("Airports",threeDBar);

The following figure shows a bar chart with a 3-D effect:

Description of the illustration bar_string_3d.gif

3.4.2 Adding Special Effects to Pie Charts

With Chart Builder, you can add 3-D effects to pie charts. To add 3-D effects to a pie chart, you use the setStyleType( ) method of the PieStyleDesc class, passing STYLE_EFFECT_3D as a parameter to the method.

To add 3-D effects to a pie chart, use the following code:

PieStyleDesc style3D = new PieStyleDesc();

style3D.setStyleType(PieStyleDesc.STYLE_EFFECT_3D);

MyPieCh.setChartAttributes(style3D);

The following figure shows a pie chart with 3-D effects:

Description of the illustration pie_example_3d.gif

You can customize the extrusion angle and thickness and perspective distance of a pie chart by using the following methods:

• setExtrusionAngle( )

  This method accepts a double value between 0 and 360. The value represents the degree of the circle. Note that the convention for degrees follows the Java conventions. For example, 0 degrees is due east, 90 degrees is due north. The default value is 315.

• setExtrusionThickness( )

  This method accepts a double value greater than 0.0 and less than .30. The default value is .10.

• setPerspectiveDistance( )

  This method accepts a double value greater than or equal to 1.0. The perspective distance influences the shape of the 3-D effect. A smaller perspective distance produces a more exaggerated perspective. The value passed to the method represents the distance of the vanishing point from the center of the pie chart. The default is 10.0, which indicates a vanishing point 10 radii from the center of the pie chart.

The following code, added to the PieStyleDesc descriptor, sets the extrusion angle to 205, the extrusion thickness to .18, and the perspective distance to 50:

style3D.setExtrusionAngle(205);

style3D.setExtrusionThickness(.18);

style3D.setPerspectiveDistance(50);

The following figure shows the resulting pie chart:

Description of the illustration pie_example_3d2.gif

3.5 Customizing the X-Axis

Chart Builder automatically labels the X-axis, saving tedious editing and positioning of the labels. If the array that is loaded into the X-axis is of type String, Chart Builder labels the X-axis with the strings provided in the array. If the array that is loaded into the X-axis is of type Date or Timestamp, Chart Builder labels the X-axis automatically, using the full date or abbreviations depending on the size of the chart. By default, it labels each point of data that you provide.

If you want to control the attributes of the X-axis rather than use the defaults, you can customize it using methods provided by Chart Builder. You can control many of the attributes. You can:

• Replace the automatically generated labels. See Section 3.5.1.

• Omit labels for the axis. See Section 3.5.2.

• Specify minimum and maximum labeling dimensions. See Section 3.5.3.

  You can specify a minimum labeling dimension to avoid labeling small time increments, such as seconds or minutes. You can specify a maximum labeling dimension to avoid labeling large time increments, such as years.

• Set a minimum number of lines for the labels. See Section 3.5.4.

For information about labeling timestamps with points other than those specifically mapped to data values, see Section 4.4.

For information about controlling other attributes, see the API documentation, especially the documentation about the AxisChart and TimeAxisDesc classes. For examples of customizing axis charts, see the axischart subdirectory of the Chart Builder demos directory.

3.5.1 Replacing Label Names

If the array that is loaded into the X-axis is of type String, Chart Builder labels the X-axis with the strings defined by the user in an array in strings. Section 2.2.3 and Section 2.2.5 provide examples of using an array of strings.

If the array that is loaded into the X-axis is of type Date or Timestamp, Chart Builder labels the X-axis automatically, using the full date or abbreviations depending on the size of the chart.

If the X-axis is defined with an array of java.sql.Date, you can replace the automatically generated label names by mapping names you supply to particular timestamps.

To map the names, you call the setUserXLabel( ) method with an array of DateString, as shown in the following example:

MyAxisCh.setXSeries(MonthlyTimestamps);

MyAxisCh.setUserXLabel(new DateString[] {

       new DateString(java.sql.Date.valueOf("2000-09-30"), "Q1"),

       new DateString(java.sql.Date.valueOf("2000-12-31"), "Q2"),

       new DateString(java.sql.Date.valueOf("2001-03-31"), "Q3"),

       new DateString(java.sql.Date.valueOf("2001-06-30"), "Q4")});

The following figure shows a chart that displays the labels defined with the setUserXLabel( ) method:

Description of the illustration userlabel.gif

AxisDesc xAxisD - new AxisDesc();

xAxisD.setDrawLabelOff();

MyAxisCh.setChartAttributes(AxisChart.XAXIS, xAxisD);

3.5.3 Specifying Minimum and Maximum Labeling Dimensions

By default, Chart Builder labels the time axis (X-axis) with the dimensions (such as seconds, days, or years) that are appropriate to the data and fit in the chart. However, you can specify a minimum label dimension to avoid labeling small time increments, such as seconds or minutes. In addition, you can specify a maximum label dimension to avoid labeling large time increments, such as months or years.

To specify a minimum or maximum label dimension, create a TimeAxisDesc descriptor object. Use the descriptor object and the setMinDimension( ) or setMaxDimension( ) method of the TimeAxisDesc class to specify the dimensions. Then, pass the descriptor object to the chart using the setChartAttributes( ) method.

In the following example, the X-axis is populated with timestamps that are in 30-second increments. The setMinDimension( ) method specifies that the axis be labeled with increments no smaller than minutes.

MyAxisCh.setXSeries(Calendar.SECOND, 

    java.sql.Timestamp.valueOf("2001-05-07 09:00:00.000000000"),

    java.sql.Timestamp.valueOf("2001-05-07 09:30:00.000000000"),

    30);


// Create a time axis descriptor object.

TimeAxisDesc MyTimeDesc = new TimeAxisDesc();

// Specify the minimum dimension.

MyTimeDesc.setMinDimension(TimeAxisDesc.MINUTE);

// Set the chart's time axis.

MyAxisCh.setChartAttributes(MyTimeDesc);

In this case, Chart Builder will not label the axis with seconds. Note however, that Chart Builder will use minutes on the label only if they can fit on the axis. The following figure shows the resulting chart:

Description of the illustration mindim.gif

In the following example, the maximum dimension is specified. The setMaxDimension( ) method specifies that the axis be labeled with increments no larger than months.

MyAxisCh.setXSeries(Calendar.MONTH, 

              java.sql.Timestamp.valueOf("1999-01-01 00:00:00.000000000"),

              java.sql.Timestamp.valueOf("2001-01-01 00:00:00.000000000"),

              1);


TimeAxisDesc MyTimeDesc = new TimeAxisDesc();

// Specify the maximum dimension.

MyTimeDesc.setMaxDimension(TimeAxisDesc.MONTH);

MyAxisCh.setChartAttributes(MyTimeDesc);

In this case, Chart Builder will not label the axis with years.

TimeAxisDesc MyTimeDesc = new TimeAxisDesc();

MyTimeDesc.setMinLabelingLines(3);

MyAxisCh.setChartAttributes(MyTimeDesc);

3.6 Customizing the Y-Axis

By default, Chart Builder automatically labels the Y-axis, calculating the attributes, such as the extents and the labeling increments.

However, using methods provided by Chart Builder, you can control many of the attributes of the Y-axis, including the following:

• The extents, which are the minimum and maximum values for the labels for the axis, and the increments between the labels. See Section 3.6.1.

• Whether or not the axis is labeled. See Section 3.6.2.

• The number format, including currency formats and number separators, of the labels. See Section 3.6.3.

For information about setting other attributes, such as the location of the axis labels, the spacing, and the justification, see the API documentation, especially the documentation about the NumAxisDesc and AxisChart classes.

3.6.1 Setting the Extents and Increments

By default, Chart Builder calculates the extents based on the data values loaded into the chart. However, you may want to control the extents, for example, if you want several charts to show the same range in the labels.

To set the minimum extent, you use the setExtentMin( ) method; to set the maximum extent, you use the setExtentMax( ) method. To set both using one method, use the setExtent( ) method. These methods are part of the NumAxisDesc class.

The following example sets the minimum extent of the chart to 5000 and the maximum extent to 20000:

// Allocate a new NumAxisDesc object.

NumAxisDesc yAxisD = new NumAxisDesc();

// Set the minimum extent to 5000.     

yAxisD.setExtentMin(5000);

//Set the maximum extent to 20,000.

yAxisD.setExtentMax(20000);

NyAxisCh.setChartAttributes(yAxisD);

To specify the increments for the labels, you use the setLabelIncrement( ) method of the NumAxisDesc class.

The following example sets the labeling increment to 2500, as well as setting the minimum and maximum extents using the setExtent( ) method:

// Allocate a new NumAxisDesc object.

NumAxisDesc yAxisD = new NumAxisDesc();

yAxisD.setExtent((7500, 20000);

//Set the label increment to 2500.

yAxisD.setLabelIncrement(2500);

MyAxisCh.setChartAttributes(yAxisD);

The following figure shows the resulting chart:

Description of the illustration extent.gif

You can also specify a particular number of labels by using the setNumLabels( ) method. For more information about the NumAxisDesc class, see the API documentation.

MyAxisCh.setYAxisLabelsOff();

3.6.3 Formatting the Numerical Labels

By default, Chart Builder writes the numbers for the Y-axis labels as raw integers or doubles. You can specify a prefix, such as a currency symbol, or a suffix, such as a percent sign (%) for the numbers. In addition, Chart Builder supports other formatting, such as locale-specific formatting, through the setNumberFormat( ) method, which uses the java.text.NumberFormat class.

To add a prefix to the Y-axis labels, use the setPrefix( ) method of the NumAxisDesc class. The following example adds a dollar sign ($) to the label:

NumAxisDesc yAxisD = new NumAxisDesc();

YAxisD.setPrefix("$");

MyAxisCh.setChartAttributes(yAxisD);

Chart Builder adds the prefix to the top label, as shown in the following figure:

Description of the illustration prefix.gif

To add a suffix to the Y-axis labels, use the setSuffix( ) method of the NumAxisDesc class. The following example adds a percent sign (%) to the label:

NumAxisDesc yAxisD = new NumAxisDesc();

YAxisD.setSuffix("%");

MyAxisCh.setChartAttributes(yAxisD);

To further customize the format of the numbers, you can invoke the setNumberFormat( ) method of the NumAxisDesc class. The setNumberFormat( ) method uses the java.text.NumberFormat class. This class provides methods to format numbers, including locale-specific formatting.

To return the default number format for the current locale, use the setNumberFormat( ) method with the NumberFormat.getInstance( ) method, as shown in the following example:

NumAxisDesc yAxisD = new NumAxisDesc();

yAxisD.setNumberFormat(NumberFormat.getInstance());

MyAxisCh.setChartAttributes(yAxisD);

For example, if your system locale is set to FRANCE and the Y-axis is loaded with values such as 255000 and 134678, Chart Builder formats the numbers with the locale-specific separators:

255 000

134 678

To return the default number format for a specified locale, use code similar to the following:

NumAxisDesc yAxisD = new NumAxisDesc();

yAxisD.setNumberFormat(NumberFormat.getInstance(locale.UK));

MyAxisCh.setChartAttributes(yAxisD);

To return the default currency format of the current or specified locale, use the setNumberFormat( ) method with the NumberFormat.getCurrencyInstance( ) method. The following example returns the currency format for the specified locale, the United Kingdom (UK):

NumAxisDesc yAxisD = new NumAxisDesc();

yAxisD.setNumberFormat(NumberFormat.getCurrencyInstance(locale.UK));

MyAxisCh.setChartAttributes(yAxisD);

The following figure shows the Y-axis numbers formatted with the default currency symbol for the United Kingdom:

Description of the illustration locale.gif

3.7 Adding Annotations and Point Labels

Annotations are character strings that highlight or describe specific points of a series. Annotations appear inside a bounding rectangle, with a connector drawn between the rectangle to the series coordinate. Point labels are labels placed at the top of a bar or inside a bar to display the numeric value of the data point. Point labels are valid only with vertical or horizontal bar charts.

You can use annotations to highlight particular points on a chart, such as when the government raises or lowers prime interest rates. To define annotations for axis charts, you use the setSeriesAnnotations( ) method of the AxisChart class.

The following example defines two annotations for a Y-axis series, maps them to specific timestamps, then sets them for the series:

String annotations[] = new String[] {"Split 3:2", Split 2:1"};

java.sql.Date AnnotTimestamps[] = new java.sql.Date[2];

AnnotTimestamps[0] = MonthlyTimestamp[2];

AnnotTimestamps[1] = MonthlyTimestamp[6];

MyAxisCh.setSeriesAnnotations(AnnotTimestamps, annotations);

The following figure shows a line chart with annotations:

For information about adding annotations that pop up when a user takes an action, such as clicking a chart element, see Section 5.1.2.1.

To add point labels to a bar chart, use one of the following methods:

• To add exterior point labels (labels placed outside the bar), use the setSeriesPointLabels( ) method of the AxisChart class, as shown in the following example:

  MyAxisCh.setSeriesPointLabels("usexports");
  
  

  The following figure shows a chart that uses exterior point labels. It also disables the Y-axis labels using the setYAxisLabelsOff( ) method.

  
  Description of the illustration dwell_ext.gif

• To add interior point labels (labels placed within the bar), use the setPointLabelsInterior( ) method of the BarDesc class, as well as the setSeriesPointLabels( ) method, as shown in the following example:

  MyAxisCh.setSeriesPointLabels("usexports");
  
  BarDesc barD2 = new BarDesc();
  
  barD2.setPointLabelsInterior();
  
  MyAxisCh.setSeriesGraphic("usexports", barD2);
  
  

  The following figure shows a horizontal bar chart that uses interior point labels:

  
  Description of the illustration dwell.gif

For more information about adding annotations and point labels to axis charts, see the API documentation, especially the AxisChart and BarDesc classes.