CategoryAxis

23.9.1 Overview

A category axis is used as the domain axis in a CategoryPlot. Categories are displayed at regular intervals along the axis, with a gap before the first category (the lower margin), a gap after the last category (the upper margin) and a gap between each category (the category margin).

lowerMargin CATEGORY 1

upperMargin categoryMargin

Category Axis

CATEGORY 2 CATEGORY N

Figure 23.3: The CategoryAxis margins

The axis will usually display a label for each category. There are a range of options for controlling the position, alignment and rotation of the labels—these are described in section 23.9.5.

23.9.2 Constructor

There is a single constructor:

public CategoryAxis(String label);

Creates a new category axis with the specified label. If you prefer no axis label, you can use null for the label argument.

23.9.3 Attributes

The attributes maintained by the CategoryAxis class are listed in Table 23.3.

These attributes are in addition to those inherited from the Axis class (see section23.2.3for details).

Attribute: Description:

lowerMargin The margin that appears before the first category, ex-pressed as a percentage of the overall axis length (defaults to 0.05 or five percent).

upperMargin The margin that appears after the last category, expressed as a percentage of the overall axis length (defaults to 0.05 or five percent).

categoryMargin The margin between categories, expressed as a percentage of the overall axis length (to be distributed between N-1 gaps, where N is the number of categories). The default value is 0.20 (twenty percent).

categoryLabelPositionOffset The offset between the axis line and the category labels.

categoryLabelPositions A structure that defines label positioning information for each possible axis location (the axis may be located at the top, bottom, left or right of the plot).

Table 23.3: Attributes for the CategoryAxis class The following default values are used:

Default: Value:

DEFAULT AXIS MARGIN 0.05 (5 percent).

DEFAULT CATEGORY MARGIN 0.20 (20 percent).

23.9.4 Setting Axis Margins

To set the lower margin for the axis:

public void setLowerMargin(double margin);

Sets the lower margin for the axis and sends anAxisChangeEventto all registered listeners. The margin is a percentage of the axis length (for example, 0.05 for a five percent margin).

To set the upper margin for the axis:

public void setUpperMargin(double margin);

Sets the upper margin for the axis and sends anAxisChangeEventto all registered listeners. The margin is a percentage of the axis length (for example, 0.05 for a five percent margin).

To set the margin between categories:

public void setCategoryMargin(double margin);

Sets the category margin for the axis and sends anAxisChangeEventto all registered listeners. The margin is a percentage of the axis length (for example, 0.20 for a twenty percent margin). The overall margin is distributed over N-1 gaps where N is the number of categories displayed on the axis.

23.9.5 Category Label Positions

To set the position of the category labels:

public void setCategoryLabelPositions(CategoryLabelPositions positions);

Sets the attribute that controls the position, alignment and rotation of the category labels along the axis.

TheCategoryLabelPositionsclass is just a structure containing four instances of theCategoryLabelPositionclass. When the axis needs to determine where it is going to draw the category labels, it will select one of those instances depending on the current location of the axis (at the top, bottom, left or right of the plot). It is the attributes of theCategoryLabelPosition object that ultimately determine where the labels are drawn.

• the first attribute is an anchor point relative to a notional category rect-angle that is computed by the axis (see figure23.4).Within this rectangle, an anchor point is specified using theRectangleAnchorclass.

Category Axis

CATEGORY 2 CATEGORY N

Category 1 Label Rectangle

Figure 23.4: A category label rectangle

• the second attribute is a text anchor, which defines a point on the category label which is aligned with the anchor point on within the category rect-angle mentioned previously. This is specified using the TextBlockAnchor

class. Try running theDrawStringDemoclass in the JFreeChart distribution to see how the anchor is used to align text to a point on the screen.

• the final two attributes are a rotation anchor point and a rotation an-gle. These are applied once the label text has been positioned using the previous two attributes.

23.9.6 Category Label Tool Tips

It is possible to specify tooltips for the labels along the category axis. This can be useful if you want to use short category names, but have the opportunity to display a longer description. To add a tool tip:

public void addCategoryLabelToolTip(Comparable category, String tooltip);

Adds a tooltip for the specified category.

To remove a tool tip:

public void removeCategoryLabelToolTip(Comparable category);

Removes the tooltip for the specified category.

To remove all tool tips:

public void clearCategoryLabelToolTips();

Removes all category label tool tips.

This feature is not supported by other axis types yet.

23.9.7 Other Methods

To control whether or not a line is drawn for the axis:

public void setAxisLineVisible(boolean visible);

Sets the flag that controls whether or not a line is drawn for the axis. Of-ten, this isn’t required because theCategoryPlotdraws an outline around itself by default. However, sometimes the plot will have no outline OR the axis may be offset from the plot.

23.9.8 Internals

In JFreeChart, axes are owned/managed by a plot. The plot is responsible for assigning drawing space to all of the axes in a plot, which it does by first asking the axes to estimate the space they require (primarily for the axis labels). The following method is used:

public AxisSpace reserveSpace(Graphics2D g2, Plot plot, Rectangle2D plotArea, RectangleEdgeedge, AxisSpace space);

Updates the axis space to allow room for this axis to be drawn.

When reserving space, the axis needs to determine the tick marks along the axis, which it does via the following method:

public List refreshTicks(Graphics2D g2, AxisState state, Rectangle2D plotArea, Rectangle2D dataArea, RectangleEdge edge);

Returns a list of the ticks along the axis.

After the plot has estimated the space required for each axis, it then computes the “data area” and draws all the axes around the edges of this area:

public AxisState draw(Graphics2D g2, double cursor, Rectangle2D plotArea, Rectangle2D dataArea, RectangleEdge edge);

Draws the axis along a specific edge of the data area. The cursor is a mea-sure of how far from the edge of the data area the axis should be drawn (another axis may have been drawn along the same edge already, for ex-ample) and the plot area is the region inside which all the axes should fit (it contains the data area).

For a given rectangular region in Java2D space, the axis can be used to calculate an x-coordinate or a y-coordinate (depending on which edge of the rectangle the axis is aligned) for the start, middle or end of a particular category on the axis:

public double getCategoryJava2DCoordinate(CategoryAnchor anchor, int category, int categoryCount, Rectangle2D area, RectangleEdgeedge);

Returns the x- or y-coordinate (in Java2D space) of the specified category.

23.9.9 Cloning and Serialization

This class isCloneableandSerializable.

23.9.10 Notes

Some points to note:

• tick marks are not supported by this axis (yet).