Axis Labeling

Understanding Categorical Axes and Labeling

By default, a categorical axis (X-axis) is labeled with tag numbers (1,2,3...) on every tick mark. You can improve the chart's readability by assigning meaningful information to tick marks in the categorical axis. The Label property can be used for this purpose. This property receives the appropriate tick mark index to label, as follows:


Axis axis = chart1.getAxisX();
axis.getLabel().setItem(0, "January");
axis.getLabel().setItem(1, "February");
axis.getLabel().setItem(2, "March");
...

Note: If you populated the chart from a database, these labels are automatically assigned from text fields in the query. For more information on populating charts with data coming from a database please refer to the "Passing Data" section earlier in this manual.

By default, Chart FX will calculate the number of labels that can be displayed according to the chart size and will hide some labels if all cannot be shown. There are some properties and techniques that will help you fit more labels on a categorical axis.

Just like a numerical axis, a categorical axis supports the Step property to control how often labels are shown in the axis. For example, when a Step of 3 is set to a categorical axis, labels will be placed on positions 3,6,9 and so on. The FirstLabel property works in a similar way, only that it forces the first label to be placed on an specific tick mark. For example, if a FirstLabel is set to 1, then X-axis labels will be shown at positions 1,4,7 and so on. The Step and FirstLabel properties can be set as follows:


chart1.getAxisX().setLabelValue((short) 3);
chart1.getAxisX().setStep((short) 3);

You can also make room for more labels if you rotate them 90 degrees using the LabelAngle property as follows:


chart1.getAxisX().setLabelAngle((short) 90);

Or you can make the labels staggered, using the Style property as follows:


chart1.getAxisX().setStyle(chart1.getAxisX().
getStyle() | AxisStyle.SHOW_2_LEVELS);

Note: The Style is a flag property that requires the bitwise operator (OR) to add or remove settings from the property. For more information, please refer to the AxisX.Style property in the Chart FX for Java Javadoc API.

The AxisX and AxisY objects support a myriad of properties that can be used to customize labels such as font, gridlines, tick marks, colors, axis styles, label rotation and other special effects. For more information, please refer to the Axis object in the Chart FX for Java Javadoc API where all the properties are listed and described.

Custom Labeling a Numerical Axis

Assigning custom labels to a categorical axis is as simple as using the Label property supported by the Axis object. However, there's a trick to using custom labels on a numerical axis that is best described using a real case scenario. For example, assume there is a numerical axis ranging from 0 to 100 with a step of 20.

You'll end up with a chart with 6 tick marks on the axis (0, 20, 40, 60, 80 and 100). If this chart is to be used to display "customer satisfaction" ratings where:


0 = Very poor
20 = Poor
40 = Average
60 = Good
80 = Very Good
100 = Excellent

The numerical axis will then display numbers that have no meaning to the user in this context. The following code will let you replace the numbers with labels:


Axis axis = chart1.getAxisY();
axis.getLabel().setItem(0, "Very Poor");
axis.getLabel().setItem(1, "Poor");
axis.getLabel().setItem(2, "Average");
axis.getLabel().setItem(3, "Good");
axis.getLabel().setItem(4, "Very Good");
axis.getLabel().setItem(5, "Excellent");

However, in a numerical axis the index specified in the Label property does not truly identify where the label should be placed. The LabelValue property allows you to specify where those labels should be placed in a numerical axis, so if you specify a LabelValue of 20 as follows:


chart1.getAxisY().setLabelValue((short) 20);

Each label will be placed exactly where you intended it to be on the numerical axis as depicted in the following figure: