5
Customizing Chart Elements

When the chart data and axes are formatted properly, you can customize its elements to make it clearer and professional-looking. The following chapter displays the different formatting elements available within JClass Chart, and how they can be used.

Adding Header and Footer Titles

A chart can have two titles, called the header and footer. A title consists of one or more lines of text with an optional border, both of which you can customize. You can also set the text alignment, positioning, colors, and font used for the header or footer.

Title Text and Alignment

Use the Text title property to add, change, or remove text for a title. To enter multiple lines of text, press ENTER between each line.

Use the Adjust title property to specify whether to center, left-justify, or right- justify a multi-line title.

Title Positioning

Use the Left and Top location properties to customize the location of the title. When their respective IsDefault properties are used, the header is centered over the ChartArea and the footer is centered below the ChartArea. See Positioning Chart Elements later in this chapter for more information.

Title Border

Use the BorderType and BorderWidth border properties to customize the title's border. See Using Borders later in this chapter for more information.

Title Colors

Use the Background and Foreground properties to customize background and text colors of a title. See Setting Colors later in this chapter for more information.

Title Font

Use the Font property to customize the font used for a title. See Choosing Fonts later in this chapter for more information.

Using a Legend

A legend shows the visual attributes (or ChartStyle) used for each series in the chart, with text that labels the series. You can customize the series labels, positioning, border, colors and font used for the legend.

The customizable portions of a Legend

Legend Text and Orientation

The legend displays the text contained in the Label property of each Series in a DataView. The IsShowingLegend property of the series determines whether the Series will appear in the Legend.

Use the legend Orientation property to lay out the legend horizontally or vertically.

Legend Positioning

Use the legend Anchor property to specify where to position the legend relative to the ChartArea. You can select from eight compass points around the ChartArea.

Use the Left and Top location properties to fine-tune the positioning. When their IsDefault properties are used, the chart automatically positions the legend. See Positioning Chart Elements later in this chapter for more information.

Legend Border

Use the BorderType and BorderWidth border properties to customize the legend's border. See Using Borders later in this chapter for more information.

Legend Colors

Use the Background and Foreground properties to customize background and text colors of the legend. See Setting Colors later in this chapter for more information.

Legend Font

Use the Font property to customize the font used for the legend. See Choosing Fonts later in this chapter for more information.

Changing ChartStyles

The attributes that define how a series of data looks in the chart are called a ChartStyle. Each series has its own ChartStyle, which you can customize. For example, you can change the fill pattern and color of bars in a bar chart or the symbol used for data points in a plot.

Image illustrating the various types of ChartStyles available

Every ChartStyle has a FillStyle, a LineStyle, and a SymbolStyle. FillStyles are used for bar, stacking bar, area and pie charts. LineStyles and SymbolStyles are used for plots.

FillStyle

Use the Pattern property to set the fill drawing pattern and the Color property to set the fill color for a ChartStyle.

Note: Patterned fills are not currently supported within Java.

LineStyle

Use the Pattern property to set the line drawing pattern, the Width property to set its width, and the Color properties to set the line color for a ChartStyle.

Note: Line patterns are not currently supported within Java.

SymbolStyle

Use the Shape property to set the symbol type, the Size property to set its size, and the Color properties to set the symbol color for a ChartStyle. The valid symbols are shown below:

Valid SymbolStyle properties displayed

Using Borders

Adding a border to part of the chart can help highlight important information, or simply make the chart look more attractive. You can customize the border type and width of the following chart elements:

Header and Footer titles
Legend
ChartArea
each ChartLabel added to the chart.

The valid border types are shown below; you can also specify that no border is used.

The types of border styles available in JClass Chart

Changing a border

Use the BorderType property to set the type of border and the BorderWidth property to set its thickness.

Choosing Fonts

A chart can have more impact when you customize the fonts used for different chart elements. You may also want to change the font size to make an element better fit the overall size of the chart. Any font available when the chart is running can be used. You can set the font for the following chart elements:

Header and Footer titles
Legend
Axis annotation and title
each ChartLabel added to the chart.

Changing Fonts

Use the font properties to set the font, style, and size attributes.

Setting Colors

Color can powerfully enhance a chart's visual impact. You can customize colors using color names, RGB values, or interactively using a color chooser. Each of the following visual elements in the chart has a background and foreground color that you can customize:

the entire chart
Header and Footer titles
Legend
ChartArea
PlotArea (background only)
each ChartLabel added to the chart.

The other chart elements that have color properties are ChartStyles, GridLines, and Markers.

Specifying Colornames

Java provides 13 stock colornames. They are:

black
blue
cyan
darkGray
gray
green
lightGray
magenta
orange
pink
red
white
yellow

Any of these values can be used within a JClass Chart program.

Specifying RGB colors

Alternately, you can specify a color by its RGB components, useful for matching another RGB color. RGB color values combine hexadecimal values for the red, green, and blue components of a color. "00" is the smallest value a component can have; "FF" is the largest value. For example, "#FF00FF" specifies Magenta (a combination of the maximum value for both red and blue with no green). An extensive listing of available RGB colorvalues can be found in Appendix A.

Color Defaults

By default, each Chart element inherits its color from the item in which it is contained. This means that setting the Foreground and Background for Chart will change the Foreground and Background properties of the ChartArea, Header and Footer, but only if these properties were not explicitly set.

Changing Color

Use the Background and Foreground properties to set background and foreground colors.

Positioning Chart Elements

Each of the main chart elements (Header, Footer, Legend, ChartArea, and ChartLabels) has properties that control its position and size. While the chart can automatically control these properties, you can also customize the following:

Positioning of any element
Size of any element.

When the chart controls positioning, it first allows space for the Header, Footer, and Legend, if they exist (size is determined by contents, border, and font). The ChartArea is sized and positioned to fit into the largest remaining rectangular area. Positioning adjusts when other chart properties change. ChartLabels do not figure into the overall Chart layout. Instead, they are positioned above all other Chart elements.

Changing the View Location

Use the Left location property to specify the number of pixels from the edge of the chart to the left edge of the chart element. Use the Top location property to specify the number of pixels from the edge of the chart to the top of the chart element. Left and Top have IsDefault properties that allow the chart to automatically position the element.

Changing Width and Height

Use the Width and Height location properties to specify the width and height of the chart element. These properties have IsDefault properties that allow the chart to automatically size the chart element.

Note that ChartLabels do not have Width and Height properties. Instead, ChartLabel size is adjusted using Right and Bottom.

Adjusting PlotArea Margins

The distance between the edges of the ChartArea and the PlotArea is called a margin. There are separate margins for the top, bottom, left, and right edges. The margins can be left to the default, automatic settings, or they can be customized.

Sample margins settings in two JClass Charts

Setting Margins

Use PlotArea's Top, Bottom, Left, or Right properties to set the value of a margin. When you set a margin value, it remains fixed at that value until you change it or set its IsDefault property.

Using Automatic Margins

Use the IsDefault properties of the Top, Bottom, Left, and Right margin properties to allow the chart to automatically determine appropriate margins.

3D Effect

Bar, stacking bar, and pie charts can be enhanced with a 3D effect. You can set the visual depth and the "elevation angle" of the 3D effect. You can also set the "rotation angle" on bar and stacking bar charts. Depth, Rotation and Elevation are all properties of the ChartArea.

Two JClass Charts illustrating the effects of 3D

3D Depth

Use the Depth property to set the visual depth of the 3D effect, as a percentage of the chart width. The maximum value is 500.

3D Elevation

Use the Elevation property to set the distance above the X-axis for the 3D effect, in degrees. This cannot be higher than 45.

3D Rotation

Use the Rotation property to set the distance right of the Y-axis for the 3D effect, in degrees. This cannot be higher than 45.

Special Bar Chart Properties

A bar chart draws each series as a bar in a cluster. You can customize the sizing and spacing of the clusters for bar and stacking bar charts.

Cluster Overlap

Use the bar ClusterOverlap property to set the amount that bars overlap each other in a cluster. The value represents the percentage of bar overlap, with valid values between -100 and 100.

Two JClass Charts illustrating the effect of different values for ClusterOverlap

Cluster Width

Use the bar ClusterWidth property to set the space used by each bar cluster. The value represents the percentage available space, with valid values between 0 and 100.

Two JClass Charts illustrating the effects of different values for ClusterWidth

The 100Percent property is used to determine whether a stacking bar chart will be shown on an axis ranging from 0 to 100 percent.

Special Pie Chart Properties

Pie charts are quite different from the other chart types you can use. They do not have the concept of a two-dimensional grid or axes. Pie charts also introduce a special category called Other, into which all data values below a certain threshold are grouped. You can customize properties of the Other slice and other properties unique to pie charts.

Building the Other Slice

Pie charts are often more effective if unimportant values are grouped into an Other category. Use the pie ThresholdMethod property to select the grouping method to use. SLICECUTOFF is useful when you know the data value that should be grouped into the Other slice. PIE_PERCENTILE is useful when you want a certain percentage of the pie to be devoted to the Other slice.

Use the ThresholdValue property to specify the value used for the ThresholdMethod.

Three JClass Charts illustrating how the Other slice can be used

Use the MinSlices property to fine-tune the number of slices displayed before the Other slice. For example, when set to 5, the chart tries to display 5 slices before grouping data into the Other slice.

Other Slice Style and Label

The OtherStyle property allows access to the ChartStyle used to render the Other slice. Use FillStyle's Pattern and Color properties to define the appearance of the Other slice.

Use the OtherLabel property to change the label of the Other slice.

Pie Ordering

Use the SortOrder property to specify whether to display slices largest-to-smallest, smallest-to-largest, or the order they appear in the data.

Exploded Pie Slices

It is possible to have individual slices of a pie "explode" (i.e. detach itself from the rest of the pie) when a user clicks on the slice. The slice "implodes" (i.e. re-joins the rest of the pie) if the user click on it again.

Two properties of JCPieChartFormat are responsible for this function: ExplodeList and ExplodeOffset.

ExplodeList specifies a list of exploded pie slice in the pie charts. It takes pts as a parameter, which is composed of an array of Point objects. Each point object contains the data point index (pie number) in the x value and the series number (slice index) in the y value, specifying the pie slice to explode. To explode the Other slice, the series number should be OTHER_SLICE. If null, no slices are exploded.

ExplodeOffset specifies the distance a slice is exploded from the center of a pie chart. It takes off as a parameter, which is the explode offset value.

The following code sample shows how ExplodeList and ExplodeOffset can be used. First, the list of exploded pie slices is set:

     Point[] exList = new Point[3];
     exList[0] = new Point(0, 0);
     exList[1] = new Point(1, 5);
     exList[2] = new Point(2, JCPieChartFormat.OTHER_SLICE);
     pcf.setExplodeList(exList);
     pcf.setExplodeOffset(10);

Given a pick event, the picked pie slice explodes or implodes the picked slice, depending on whether or not it is already exploded.

public void pick(JCPickEvent e)
{
	JCDataIndex di = e.getPickResult();
	if (di == null) return;
	Object obj = di.getObject();
	ChartDataView vw = di.getDataView();
	ChartDataViewSeries srs = di.getSeries();
	int slice = di.getSeriesIndex();
	int pt = di.getPoint();
	int dist = di.getDistance();
	if (vw != null && slice != -1) {
		JCPieChartFormat pcf = vw.getPieChartFormat();
		Point[] exList = pcf.getExplodeList();
		if (exList == null) return;
		// implode existing exploded slices
		for (int i = 0; i < exList.length; i++) {
			if ((exList[i].x == pt) && (exList[i].y == slice)) {
				Point[] newList = new Point[exList.length - 1];
				for (int j = 0; j < i; j++)
					newList[j] = exList[j];
				for (int j = i; j < newList.length; j++)
					newList[j] = exList[j + 1];
				pcf.setExplodeList(newList);
				vw.setChanged(true);
				return;
			}
		}
		// explode new slice
		Point[] newList = new Point[exList.length + 1];
		for (int j = 0; j < exList.length; j++)
			newList[j] = exList[j];
		newList[exList.length] = new Point(pt, slice);
		pcf.setExplodeList(newList);
		vw.setChanged(true);
	}
}

The full code for this program can be found in the explode.class pie chart demonstration program that comes with JClass Chart.

For more information on pick, see "Using Pick and Unpick".

5 Customizing Chart Elements