Module org.jfree.chart3d
Package org.jfree.chart3d.axis

# Class StandardCategoryAxis3D

java.lang.Object
org.jfree.chart3d.axis.AbstractAxis3D
org.jfree.chart3d.axis.StandardCategoryAxis3D

All Implemented Interfaces:
  `Serializable`, `EventListener`, `Axis3D`, `CategoryAxis3D`, `ChartElement`, `MarkerChangeListener`

public class StandardCategoryAxis3D extends AbstractAxis3D implements CategoryAxis3D, Serializable
An axis that displays categories.
NOTE: This class is serializable, but the serialization format is subject to change in future releases and should not be relied upon for persisting instances of this class.

See Also:
  - Serialized Form

## Field Summary

### Fields inherited from class org.jfree.chart3d.axis.AbstractAxis3D

`DEFAULT_LABEL_COLOR, DEFAULT_LABEL_FONT, DEFAULT_LABEL_OFFSET, DEFAULT_LINE_COLOR, DEFAULT_LINE_STROKE, DEFAULT_TICK_LABEL_COLOR, DEFAULT_TICK_LABEL_FONT`

## Constructor Summary

Constructors
Constructor
Description
`StandardCategoryAxis3D()`
Default constructor.
`StandardCategoryAxis3D(String label)`
Creates a new axis with the specified label.

## Method Summary

Modifier and Type
Method
Description
`protected String`
`axisStr()`
Returns "row" if the axis has been configured as a row axis, "column" if the axis has been configured as a column axis, and the empty string ("") if the axis has not yet been configured.
`void`
`configureAsColumnAxis(CategoryPlot3D plot)`
Configures the axis to be used as a column axis for the specified plot.
`void`
`configureAsRowAxis(CategoryPlot3D plot)`
Configures the axis to be used as a row axis for the specified plot.
`void`
`draw(Graphics2D g2, Point2D pt0, Point2D pt1, Point2D opposingPt, List<TickData> tickData, RenderingInfo info, boolean hinting)`
Draws the axis between the two points `pt0` and `pt1` in Java2D space.
`boolean`
`equals(Object obj)`
Tests this instance for equality with an arbitrary object.
`List<MarkerData>`
`generateMarkerData()`
Generates and returns a list of marker data items for the axis.
`List<TickData>`
`generateTickDataForColumns(CategoryDataset3D dataset)`
Generates the tick data for the axis (assumes the axis is being used as the row axis).
`List<TickData>`
`generateTickDataForRows(CategoryDataset3D dataset)`
Generates the tick data for the axis (assumes the axis is being used as the row axis).
`double`
`getCategoryValue(Comparable<?> category)`
Returns the value for the specified category, or `Double.NaN` if the category is not registered on the axis.
`double`
`getCategoryWidth()`
Returns the width of a single category in the units of the axis range.
`double`
`getLowerMargin()`
Returns the margin to leave at the lower end of the axis, as a percentage of the axis length.
`CategoryMarker`
`getMarker(String key)`
Returns the marker with the specified key, if there is one.
`Map<String,CategoryMarker>`
`getMarkers()`
Returns a new map containing the markers that are assigned to this axis.
`int`
`getMaxTickLabelLevels()`
Returns the maximum number of offset levels for the category labels on the axis.
`Range`
`getRange()`
Returns the range for the axis.
`double`
`getTickLabelFactor()`
Returns the tick label factor.
`CategoryLabelGenerator`
`getTickLabelGenerator()`
Returns the tick label generator for the axis.
`double`
`getTickLabelOffset()`
Returns the offset between the tick marks and the tick labels.
`LabelOrientation`
`getTickLabelOrientation()`
Returns the orientation for the tick labels.
`double`
`getTickMarkLength()`
Returns the tick mark length (in Java2D units).
`Paint`
`getTickMarkPaint()`
Returns the paint used to draw the tick marks, if they are visible.
`Stroke`
`getTickMarkStroke()`
Returns the stroke used to draw the tick marks, if they are visible.
`double`
`getUpperMargin()`
Returns the margin to leave at the upper end of the axis, as a percentage of the axis length.
`boolean`
`isColumnAxis()`
Returns `true` if this axis has been configured as a column axis for the plot that it belongs to, and `false` otherwise.
`boolean`
`isFirstCategoryHalfWidth()`
Returns `true` if the first category on the axis should occupy half the normal width, and `false` otherwise.
`boolean`
`isInverted()`
Returns `true` if the axis inverts the order of the data items, and `false` otherwise.
`boolean`
`isLastCategoryHalfWidth()`
Returns `true` if the last category on the axis should occupy half the normal width, and `false` otherwise.
`boolean`
`isRowAxis()`
Returns `true` if this axis has been configured as a row axis for the plot that it belongs to, and `false` otherwise.
`void`
`receive(ChartElementVisitor visitor)`
Receives a `ChartElementVisitor`.
`void`
`setFirstCategoryHalfWidth(boolean half)`
Sets the flag that controls whether the first category on the axis occupies a full or half width, and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setInverted(boolean inverted)`
Sets the flag that controls whether or not the axis inverts the order of the data items and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setLastCategoryHalfWidth(boolean half)`
Sets the flag that controls whether the last category on the axis occupies a full or half width, and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setLowerMargin(double margin)`
Sets the margin to leave at the lower end of the axis and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setMarker(String key, CategoryMarker marker)`
Sets the marker for the specified key and sends a change event to all registered listeners.
`void`
`setMaxTickLabelLevels(int levels)`
Sets the maximum number of offset levels for the category labels on the axis and sends a change event to all registered listeners.
`void`
`setRange(double lowerBound, double upperBound)`
Sets the range for the axis and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setRange(Range range)`
Sets the range for the axis and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setTickLabelFactor(double factor)`
Sets the tick label factor and sends a change event to all registered listeners.
`void`
`setTickLabelGenerator(CategoryLabelGenerator generator)`
Sets the tick label generator for the axis and sends a change event to all registered listeners.
`void`
`setTickLabelOffset(double offset)`
Sets the offset between the tick marks and the tick labels and sends a `Axis3DChangeEvent` to all registered listeners.
`void`
`setTickLabelOrientation(LabelOrientation orientation)`
Sets the orientation for the tick labels and sends a change event to all registered listeners.
`void`
`setTickMarkLength(double length)`
Sets the tick mark length (in Java2D units) and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setTickMarkPaint(Paint paint)`
Sets the paint used to draw the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setTickMarkStroke(Stroke stroke)`
Sets the stroke used to draw the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.
`void`
`setUpperMargin(double margin)`
Sets the margin to leave at the upper end of the axis and sends an `Axis3DChangeEvent` to all registered listeners.
`double`
`translateToWorld(double value, double length)`
Translates a value on the axis to the equivalent coordinate in the 3D world used to construct a model of the chart.

### Methods inherited from class org.jfree.chart3d.axis.AbstractAxis3D

`addChangeListener, drawAxisLabel, fireChangeEvent, getLabel, getLabelColor, getLabelFont, getLabelOffset, getLineColor, getLineStroke, getTickLabelColor, getTickLabelFont, getTickLabelsVisible, hashCode, isVisible, markerChanged, notifyListeners, removeChangeListener, setLabel, setLabelColor, setLabelFont, setLabelOffset, setLineColor, setLineStroke, setTickLabelColor, setTickLabelFont, setTickLabelsVisible, setVisible`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.jfree.chart3d.axis.Axis3D

`addChangeListener, getLabelColor, getLabelFont, getTickLabelColor, getTickLabelFont, isVisible, removeChangeListener, setLabelColor, setLabelFont, setTickLabelColor, setTickLabelFont, setVisible`

## Constructor Details

### StandardCategoryAxis3D

public StandardCategoryAxis3D()
Default constructor.

### StandardCategoryAxis3D

public StandardCategoryAxis3D(String label)
Creates a new axis with the specified label.

Parameters:
  `label` - the axis label (`null` permitted).

## Method Details

### isRowAxis

public boolean isRowAxis()
Returns `true` if this axis has been configured as a row axis for the plot that it belongs to, and `false` otherwise.

Specified by:
  `isRowAxis` in interface `CategoryAxis3D`
Returns:
  A boolean.
Since:
  1.3

### isColumnAxis

public boolean isColumnAxis()
Returns `true` if this axis has been configured as a column axis for the plot that it belongs to, and `false` otherwise.

Specified by:
  `isColumnAxis` in interface `CategoryAxis3D`
Returns:
  A boolean.
Since:
  1.3

### getRange

public Range getRange()
Returns the range for the axis. By convention, the category axes have a range from 0.0 to 1.0.

Specified by:
  `getRange` in interface `Axis3D`
Returns:
  The range.

### setRange

public void setRange(double lowerBound, double upperBound)
Sets the range for the axis and sends an `Axis3DChangeEvent` to all registered listeners.

Specified by:
  `setRange` in interface `Axis3D`
Parameters:
  `lowerBound` - the lower bound.
  `upperBound` - the upper bound.

### setRange

public void setRange(Range range)
Sets the range for the axis and sends an `Axis3DChangeEvent` to all registered listeners. Note that changing the range for the category axis will have no visible effect.

Specified by:
  `setRange` in interface `Axis3D`
Parameters:
  `range` - the range (`null` not permitted).

### getLowerMargin

public double getLowerMargin()
Returns the margin to leave at the lower end of the axis, as a percentage of the axis length. The default is `0.05` (five percent).

Returns:
  The lower margin.

### setLowerMargin

public void setLowerMargin(double margin)
Sets the margin to leave at the lower end of the axis and sends an `Axis3DChangeEvent` to all registered listeners.

Parameters:
  `margin` - the margin.

### getUpperMargin

public double getUpperMargin()
Returns the margin to leave at the upper end of the axis, as a percentage of the axis length. The default is `0.05` (five percent).

Returns:
  The lower margin.

### setUpperMargin

public void setUpperMargin(double margin)
Sets the margin to leave at the upper end of the axis and sends an `Axis3DChangeEvent` to all registered listeners.

Parameters:
  `margin` - the margin.

### isFirstCategoryHalfWidth

public boolean isFirstCategoryHalfWidth()
Returns `true` if the first category on the axis should occupy half the normal width, and `false` otherwise.

Returns:
  A boolean.
See Also:
  - `setFirstCategoryHalfWidth(boolean)`

### setFirstCategoryHalfWidth

public void setFirstCategoryHalfWidth(boolean half)
Sets the flag that controls whether the first category on the axis occupies a full or half width, and sends an `Axis3DChangeEvent` to all registered listeners. There are some renderers where the charts look better when half-widths are used (for example, `AreaRenderer3D`).

Parameters:
  `half` - half width?
See Also:
  - `setLastCategoryHalfWidth(boolean)`

### isLastCategoryHalfWidth

public boolean isLastCategoryHalfWidth()
Returns `true` if the last category on the axis should occupy half the normal width, and `false` otherwise.

Returns:
  A boolean.
See Also:
  - `setLastCategoryHalfWidth(boolean)`

### setLastCategoryHalfWidth

public void setLastCategoryHalfWidth(boolean half)
Sets the flag that controls whether the last category on the axis occupies a full or half width, and sends an `Axis3DChangeEvent` to all registered listeners. There are some renderers where the charts look better when half-widths are used (for example, `AreaRenderer3D`).

Parameters:
  `half` - half width?
See Also:
  - `setFirstCategoryHalfWidth(boolean)`

### getTickMarkLength

public double getTickMarkLength()
Returns the tick mark length (in Java2D units). The default value is `3.0`.

Returns:
  The tick mark length.

### setTickMarkLength

public void setTickMarkLength(double length)
Sets the tick mark length (in Java2D units) and sends an `Axis3DChangeEvent` to all registered listeners. You can set the length to `0.0` if you don't want any tick marks on the axis.

Parameters:
  `length` - the length (in Java2D units).

### getTickMarkPaint

public Paint getTickMarkPaint()
Returns the paint used to draw the tick marks, if they are visible. The default value is `Color.GRAY`.

Returns:
  The paint used to draw the tick marks (never `null`).

### setTickMarkPaint

public void setTickMarkPaint(Paint paint)
Sets the paint used to draw the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.

Parameters:
  `paint` - the paint (`null` not permitted).

### getTickMarkStroke

public Stroke getTickMarkStroke()
Returns the stroke used to draw the tick marks, if they are visible. The default value is `new BasicStroke(0.5f)`.

Returns:
  The stroke used to draw the tick marks (never `null`).

### setTickMarkStroke

public void setTickMarkStroke(Stroke stroke)
Sets the stroke used to draw the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.

Parameters:
  `stroke` - the stroke (`null` not permitted).

### getTickLabelGenerator

public CategoryLabelGenerator getTickLabelGenerator()
Returns the tick label generator for the axis. This is an object that is responsible for creating the category labels on the axis. You can plug in your own instance to take full control over the generation of category labels.

Returns:
  The tick label generator for the axis (never `null`).
Since:
  1.2

### setTickLabelGenerator

public void setTickLabelGenerator(CategoryLabelGenerator generator)
Sets the tick label generator for the axis and sends a change event to all registered listeners.

Parameters:
  `generator` - the generator (`null` not permitted).
Since:
  1.2

### getTickLabelOffset

public double getTickLabelOffset()
Returns the offset between the tick marks and the tick labels. The default value is `5.0`.

Returns:
  The offset between the tick marks and the tick labels (in Java2D units).

### setTickLabelOffset

public void setTickLabelOffset(double offset)
Sets the offset between the tick marks and the tick labels and sends a `Axis3DChangeEvent` to all registered listeners.

Parameters:
  `offset` - the offset.

### getTickLabelOrientation

public LabelOrientation getTickLabelOrientation()
Returns the orientation for the tick labels. The default value is `LabelOrientation.PARALLEL`.

Returns:
  The orientation for the tick labels (never `null`).
Since:
  1.2

### setTickLabelOrientation

public void setTickLabelOrientation(LabelOrientation orientation)
Sets the orientation for the tick labels and sends a change event to all registered listeners.

Parameters:
  `orientation` - the orientation (`null` not permitted).
Since:
  1.2

### getMaxTickLabelLevels

public int getMaxTickLabelLevels()
Returns the maximum number of offset levels for the category labels on the axis. The default value is 3.

Returns:
  The maximum number of offset levels.
Since:
  1.2

### setMaxTickLabelLevels

public void setMaxTickLabelLevels(int levels)
Sets the maximum number of offset levels for the category labels on the axis and sends a change event to all registered listeners.

Parameters:
  `levels` - the maximum number of levels.
Since:
  1.2

### getTickLabelFactor

public double getTickLabelFactor()
Returns the tick label factor. The default value is `1.4`.

Returns:
  The tick label factor.
Since:
  1.2

### setTickLabelFactor

public void setTickLabelFactor(double factor)
Sets the tick label factor and sends a change event to all registered listeners.

Parameters:
  `factor` - the new factor (should be at least 1.0).
Since:
  1.2

### getMarker

public CategoryMarker getMarker(String key)
Returns the marker with the specified key, if there is one.

Specified by:
  `getMarker` in interface `CategoryAxis3D`
Parameters:
  `key` - the key (`null` not permitted).
Returns:
  The marker (possibly `null`).
Since:
  1.2

### setMarker

public void setMarker(String key, CategoryMarker marker)
Sets the marker for the specified key and sends a change event to all registered listeners. If there is an existing marker it is replaced (and the axis will no longer listen for change events on the previous marker).

Parameters:
  `key` - the key that identifies the marker (`null` not permitted).
  `marker` - the marker (`null` permitted).
Since:
  1.2

### getMarkers

public Map<String,CategoryMarker> getMarkers()
Returns a new map containing the markers that are assigned to this axis.

Returns:
  A map.
Since:
  1.2

### getCategoryWidth

public double getCategoryWidth()
Returns the width of a single category in the units of the axis range.

Specified by:
  `getCategoryWidth` in interface `CategoryAxis3D`
Returns:
  The width of a single category.

### configureAsRowAxis

public void configureAsRowAxis(CategoryPlot3D plot)
Configures the axis to be used as a row axis for the specified plot. This method is for internal use, you should not call it directly.

Specified by:
  `configureAsRowAxis` in interface `CategoryAxis3D`
Parameters:
  `plot` - the plot (`null` not permitted).

### configureAsColumnAxis

public void configureAsColumnAxis(CategoryPlot3D plot)
Configures the axis to be used as a column axis for the specified plot. This method is for internal use, you won't normally need to call it directly.

Specified by:
  `configureAsColumnAxis` in interface `CategoryAxis3D`
Parameters:
  `plot` - the plot (`null` not permitted).

### getCategoryValue

public double getCategoryValue(Comparable<?> category)
Returns the value for the specified category, or `Double.NaN` if the category is not registered on the axis.

Specified by:
  `getCategoryValue` in interface `CategoryAxis3D`
Parameters:
  `category` - the category (`null` not permitted).
Returns:
  The value.

### translateToWorld

public double translateToWorld(double value, double length)
Translates a value on the axis to the equivalent coordinate in the 3D world used to construct a model of the chart.

Specified by:
  `translateToWorld` in interface `Axis3D`
Parameters:
  `value` - the value along the axis.
  `length` - the length of one side of the 3D box containing the model.
Returns:
  A coordinate in 3D space.

### draw

public void draw(Graphics2D g2, Point2D pt0, Point2D pt1, Point2D opposingPt, List<TickData> tickData, RenderingInfo info, boolean hinting)
Draws the axis between the two points `pt0` and `pt1` in Java2D space.

Specified by:
  `draw` in interface `Axis3D`
Specified by:
  `draw` in class `AbstractAxis3D`
Parameters:
  `g2` - the graphics target (`null` not permitted).
  `pt0` - the starting point for the axis (`null` not permitted).
  `pt1` - the ending point for the axis (`null` not permitted).
  `opposingPt` - a point on the opposite side of the line from the labels (`null` not permitted).
  `tickData` - the tick data, contains positioning anchors calculated by the 3D engine (`null` not permitted).
  `info` - an object to be populated with rendering info (`null` permitted).
  `hinting` - perform element hinting?

### axisStr

protected String axisStr()
Returns "row" if the axis has been configured as a row axis, "column" if the axis has been configured as a column axis, and the empty string ("") if the axis has not yet been configured.

Specified by:
  `axisStr` in class `AbstractAxis3D`
Returns:
  A string (never `null`).
Since:
  1.3

### generateTickDataForRows

public List<TickData> generateTickDataForRows(CategoryDataset3D dataset)
Generates the tick data for the axis (assumes the axis is being used as the row axis). The dataset is passed as an argument to provide the opportunity to incorporate dataset-specific info into tick labels (for example, a row label might show the total for that row in the dataset) ---whether or not this is used depends on the axis implementation.

Specified by:
  `generateTickDataForRows` in interface `CategoryAxis3D`
Parameters:
  `dataset` - the dataset (`null` not permitted).
Returns:
  The tick data.
Since:
  1.2

### generateTickDataForColumns

public List<TickData> generateTickDataForColumns(CategoryDataset3D dataset)
Generates the tick data for the axis (assumes the axis is being used as the row axis). The dataset is passed as an argument to provide the opportunity to incorporate dataset-specific info into tick labels (for example, a row label might show the total for that row in the dataset) ---whether or not this is used depends on the axis implementation.

Specified by:
  `generateTickDataForColumns` in interface `CategoryAxis3D`
Parameters:
  `dataset` - the dataset (`null` not permitted).
Returns:
  The tick data.
Since:
  1.2

### generateMarkerData

public List<MarkerData> generateMarkerData()
Generates and returns a list of marker data items for the axis.

Specified by:
  `generateMarkerData` in interface `CategoryAxis3D`
Returns:
  A list of marker data items (never `null`).

### receive

public void receive(ChartElementVisitor visitor)
Receives a `ChartElementVisitor`. This method is part of a general mechanism for traversing the chart structure and performing operations on each element in the chart. You will not normally call this method directly.

Specified by:
  `receive` in interface `ChartElement`
Specified by:
  `receive` in class `AbstractAxis3D`
Parameters:
  `visitor` - the visitor (`null` not permitted).
Since:
  1.2

### equals

public boolean equals(Object obj)
Tests this instance for equality with an arbitrary object.

Overrides:
  `equals` in class `AbstractAxis3D`
Parameters:
  `obj` - the object to test against (`null` not permitted).
Returns:
  A boolean.

### isInverted

public boolean isInverted()
Returns `true` if the axis inverts the order of the data items, and `false` otherwise.

Specified by:
  `isInverted` in interface `Axis3D`
Returns:
  A boolean.
Since:
  1.5

### setInverted

public void setInverted(boolean inverted)
Sets the flag that controls whether or not the axis inverts the order of the data items and sends an `Axis3DChangeEvent` to all registered listeners.

Specified by:
  `setInverted` in interface `Axis3D`
Parameters:
  `inverted` - the new flag value.
Since:
  1.5