public class

CategoryAxis

extends NumberAxis
java.lang.Object
   ↳ com.shinobicontrols.charts.Axis<T extends java.lang.Comparable<T>, U>
     ↳ com.shinobicontrols.charts.NumberAxis
       ↳ com.shinobicontrols.charts.CategoryAxis

Class Overview

A CategoryAxis is a subclass of NumberAxis designed to work with discrete data points with no linear correlation between values.

For the purposes of ranges, each data point value for a category axis is represented by an index (generated by the order in which data points are added to the series - but removing duplicates). This determines order and can be used to set ranges.

For example, for three data points with category values of "June", "5" and "Frog", passed to the chart in that order, along a category axis:

  1. June is equivalent to 0.
  2. 5 is equivalent to 1.
  3. Frog is equivalent to 2.
  4. The range of this data is 0 to 2.
  5. Setting a range of 0 to 1 would show June and 5, but not Frog.
The data point values are not sorted and do not need to be members of the same class - their toString() method is called to obtain a suitable string for the category.

Since one cannot interpolate between '5' and a 'Frog', or group 'June' and '5' into an encapsulating value, minor tick marks are disabled on Category Axes.

Major tick marks and labels, if enabled, will be shown for each data point. Setting major or minor tick frequencies will have no effect.

Summary

Public Constructors
CategoryAxis()
Constructs a CategoryAxis.
CategoryAxis(NumberRange range)
Constructs a CategoryAxis with a number range representing the indices.
Public Methods
void addSkipRange(Range<Double> skipRange)
Instructs this axis to exclude the given range from the chart.
void addSkipRanges(List<? extends Range<Double>> skipRanges)
Instructs this axis to exclude the given ranges from the chart.
List<String> getCategories()
A list containing all of the categories across all series linked to this axis.
String getFormattedString(Double value)
Gets a string representing the current value.
boolean requestCurrentDisplayedRange(int minimum, int maximum)
Attempts to set the current visible range, axisRange, to a range with the given minimum and maximum values in line with any restrictions on setting the range, such as allowPanningOutOfMaxRange(boolean) .
boolean requestCurrentDisplayedRange(int minimum, int maximum, boolean animation, boolean bounceAtLimits)
Attempts to set the current visible range, axisRange, to a range with the given minimum and maximum values in line with any restrictions on setting the range, such as allowPanningOutOfMaxRange(boolean) .
void setMajorTickMarkValues(List<Double> values)
Sets a list of values to be used as the major tick mark values for this axis.
[Expand]
Inherited Methods
From class com.shinobicontrols.charts.NumberAxis
From class com.shinobicontrols.charts.Axis
From class java.lang.Object

Public Constructors

public CategoryAxis ()

Constructs a CategoryAxis.

public CategoryAxis (NumberRange range)

Constructs a CategoryAxis with a number range representing the indices.

The range is based upon the index number of each category where 0 is the first category and n is the (n+1)th category, in the order in which the data points are presented to the chart. The index number of a category can be found from the list returned by getCategories() and contains the actual set of categories.

Parameters
range the range representing the indices

Public Methods

public void addSkipRange (Range<Double> skipRange)

Instructs this axis to exclude the given range from the chart. The values inside the range are said to be 'skipped' - this is most commonly used for omitting periods of time on a DateTimeAxis such as weekends or bank holidays. The axis will be updated to reflect the changes. Any data values that fall within a skipped range will not be displayed.

It is possible to add multiple skip ranges to an axis but it should be borne in mind that every time a skip range is added to an axis, a number of internal calculations must be made. Additionally, the chart it belongs to will be instructed to reload its data. As such there are a number of ways to improve the efficiency of such an operation:

  • Add all of the skip ranges in one go by using the addSkipRanges(List) method.
  • Ensure the axis is not connected to a chart when adding the skip ranges (temporarily removing it if necessary).
Doing the above minimizes the number of internal calculations that need to be made and prevents repeated calls to the chart to reload its data.

Attempting to add ranges of zero or negative span will be ignored.

Parameters
skipRange the range to be excluded from the chart on this axis

public void addSkipRanges (List<? extends Range<Double>> skipRanges)

Instructs this axis to exclude the given ranges from the chart. The values inside the ranges are said to be 'skipped' - this is most commonly used for omitting periods of time on a DateTimeAxis such as weekends or bank holidays. The axis will be updated to reflect the changes. Any data values that fall within a skipped range will not be displayed.

Adding a list of skip ranges altogether, instead of doing so one at a time, can be more efficient and improve data loading time. Similarly, it is more efficient to add the skip ranges while the axis is not connected to a chart as it avoids repeated data reload requests. Consider temporarily removing the axis from the chart while you add the skip ranges, or adding the skip ranges before the axis is given to the chart.

Attempting to add ranges of zero or negative span will be ignored.

Parameters
skipRanges the ranges to be excluded from the chart on this axis

public List<String> getCategories ()

A list containing all of the categories across all series linked to this axis. The list can be used to link data point values to integer values.

This list is read-only. Attempts to add, remove or replace the contents of the list will result in an UnsupportedOperationException being thrown.

Returns
  • a read-only list containing all categories across all series linked to this axis

public String getFormattedString (Double value)

Gets a string representing the current value. This is a convenience method which you may use to format values as the axis does. It can also be overridden in derived classes if you have an advanced customization scenario. The default behavior is to take the string value supplied with the series data, and you need not call this implementation in your override.

Parameters
value The value to set
Returns
  • The formatted tick mark label string

public boolean requestCurrentDisplayedRange (int minimum, int maximum)

Attempts to set the current visible range, axisRange, to a range with the given minimum and maximum values in line with any restrictions on setting the range, such as allowPanningOutOfMaxRange(boolean) . This overload takes account the axis's isAnimationEnabled() and isBouncingAtLimitsEnabled() state.

For a CategoryAxis the first category has a nominal value of '0' and the nth value, 'n-1', and so the minimum and maximum values are specified numerically. For convenience this method lets you specify the minimum and maximum values as integers (using requestCurrentDisplayedRange(T, T) would require doubles).

Parameters
minimum the minimum value to be displayed
maximum the maximum value to be displayed
Returns
  • Whether or not the operation was successful. True if the axis range has been set to (or is currently animating towards) the values you requested. False if the values have been limited by default or data ranges.

public boolean requestCurrentDisplayedRange (int minimum, int maximum, boolean animation, boolean bounceAtLimits)

Attempts to set the current visible range, axisRange, to a range with the given minimum and maximum values in line with any restrictions on setting the range, such as allowPanningOutOfMaxRange(boolean) . This overload allows you to explicitly set whether to animate the transition to the new range or not, and it ignores the axis's isAnimationEnabled() and isBouncingAtLimitsEnabled() state.

Parameters
minimum the minimum value to be displayed
maximum the maximum value to be displayed
animation whether or not to animate the range change
bounceAtLimits Whether or not to allow the range change animation to temporarily go beyond the limits set
Returns
  • Whether or not the operation was successful. True if the axis range has been set to (or is currently animating towards) the values you requested. False if the values have been limited by default or data ranges.

public void setMajorTickMarkValues (List<Double> values)

Sets a list of values to be used as the major tick mark values for this axis. Calling this method with a non-null list will restrict the displayed tick marks to only those with the values in the list; no other values will be displayed. Subsequently calling this method with null will cause the tick marks to be automatically calculated as per usual. If called after the chart has already been rendered you must call redrawChart() for the new values to take effect.

The values can be specified in any order but will be displayed in ascending order along the axis. Any duplicates in the list will be removed. If the list contains null for any of its elements an java.lang.IllegalArgumentException will be thrown.

Custom major tick mark values cannot be set on a CategoryAxis. Any attempt to do so will be ignored. Also note that enabling grid stripes with custom tick mark values is not supported and may lead to some undesired visual effects.

Parameters
values the list of tick mark values to show on this axis