Module org.jfree.chart3d
Package org.jfree.chart3d.plot

# Class CategoryPlot3D

java.lang.Object
org.jfree.chart3d.plot.AbstractPlot3D
org.jfree.chart3d.plot.CategoryPlot3D

All Implemented Interfaces:
  `Serializable`, `EventListener`, `Axis3DChangeListener`, `ChartElement`, `Dataset3DChangeListener`, `Plot3D`, `Renderer3DChangeListener`

public class CategoryPlot3D extends AbstractPlot3D implements Axis3DChangeListener, Renderer3DChangeListener, Serializable
A 3D plot with two category axes (x and z) and a numerical y-axis that can display data from a `CategoryDataset3D`.
The plot implements several listener interfaces so that it can receive notification of changes to its dataset, axes and renderer. When change events are received, the plot passes on a `Plot3DChangeEvent` to the `Chart3D` instance that owns the plot. This event chain is the mechanism that ensures that charts are repainted whenever the dataset changes, or when changes are made to the configuration of any chart component.
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.plot.AbstractPlot3D

`autoAdjustDimensions, dimensions`

## Constructor Summary

Constructors
Constructor
Description
`CategoryPlot3D(CategoryDataset3D dataset, CategoryRenderer3D renderer, CategoryAxis3D rowAxis, CategoryAxis3D columnAxis, ValueAxis3D valueAxis)`
Creates a new plot with the supplied dataset, renderer and axes.

## Method Summary

Modifier and Type
Method
Description
`void`
`axisChanged(Axis3DChangeEvent event)`
Receives notification that one of the axes has been changed.
`void`
`compose(World world, double xOffset, double yOffset, double zOffset)`
Adds 3D objects representing the current data for the plot to the specified world.
`void`
`datasetChanged(Dataset3DChangeEvent event)`
Receives notification of a change to the dataset and handles this by adjusting the plot dimensions (according to the setting of the `autoAdjustDimensions` flag), reconfiguring the axes, and propagating a `Plot3DChangeEvent`.
`boolean`
`equals(Object obj)`
Tests this plot for equality with an arbitrary object.
`String`
`generateToolTipText(ItemKey itemKey)`
Returns the tool tip text for the specified data item, or `null` if no tool tip is required.
`CategoryAxis3D`
`getColumnAxis()`
Returns the column axis.
`CategoryDataset3D`
`getDataset()`
Returns the dataset for the chart.
`Paint`
`getGridlinePaintForColumns()`
Returns the paint used to draw the grid lines for the column axis, if they are visible.
`Paint`
`getGridlinePaintForRows()`
Returns the paint used to draw the gridlines for the row axis, if they are visible.
`Paint`
`getGridlinePaintForValues()`
Returns the paint for the gridlines associated with the value axis.
`Stroke`
`getGridlineStrokeForColumns()`
Returns the stroke for the gridlines associated with the column axis.
`Stroke`
`getGridlineStrokeForRows()`
Returns the stroke for the gridlines associated with the row axis.
`Stroke`
`getGridlineStrokeForValues()`
Returns the stroke for the gridlines associated with the value axis.
`boolean`
`getGridlinesVisibleForColumns()`
Returns `true` if gridlines are shown for the column axis and `false` otherwise.
`boolean`
`getGridlinesVisibleForRows()`
Returns `true` if gridlines are shown for the column axis and `false` otherwise.
`boolean`
`getGridlinesVisibleForValues()`
Returns `true` if gridlines are shown for the column axis and `false` otherwise.
`List<LegendItemInfo>`
`getLegendInfo()`
Returns a list containing legend item info, typically one item for each series in the chart.
`CategoryLabelGenerator`
`getLegendLabelGenerator()`
Returns the legend label generator, an object that converts key values in the dataset into corresponding strings for presentation in the chart.
`CategoryRenderer3D`
`getRenderer()`
Returns the renderer (very often you will need to cast this to a specific class to make customisations).
`CategoryAxis3D`
`getRowAxis()`
Returns the row axis.
`CategoryItemLabelGenerator`
`getToolTipGenerator()`
Returns the tool tip generator.
`ValueAxis3D`
`getValueAxis()`
Returns the value axis (the vertical axis in the plot).
`Double`
`getYDimensionOverride()`
Returns the y-dimension override.
`void`
`receive(ChartElementVisitor visitor)`
Accepts a visitor for the plot.
`void`
`rendererChanged(Renderer3DChangeEvent event)`
Receives notification that the renderer has been modified in some way.
`void`
`setAutoAdjustDimensions(boolean auto)`
Sets the flag that controls whether the plot's dimensions are automatically calculated and, if `true`, sends a change event to all registered listeners.
`void`
`setColumnAxis(CategoryAxis3D axis)`
Sets the column axis and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setDataset(CategoryDataset3D dataset)`
Sets the dataset and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setDimensions(Dimension3D dimensions)`
Sets the dimensions (in 3D space) for the plot, resets the `autoAdjustDimensions` flag to `false`, and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlinePaintForColumns(Paint paint)`
Sets the paint used to draw the grid lines for the column axis, if they are visible, and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlinePaintForRows(Paint paint)`
Sets the paint used for the row axis gridlines and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlinePaintForValues(Paint paint)`
Sets the paint used for the value axis gridlines and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlineStrokeForColumns(Stroke stroke)`
Sets the stroke used to draw the grid lines for the column axis, if they are visible, and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlineStrokeForRows(Stroke stroke)`
Sets the stroke used to draw the gridlines for the row axis, if they are visible, and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlineStrokeForValues(Stroke stroke)`
Sets the stroke used to draw the grid lines for the value axis, if they are visible, and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlinesVisibleForColumns(boolean visible)`
Sets the flag that controls whether or not gridlines are shown for the column axis and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlinesVisibleForRows(boolean visible)`
Sets the flag that controls whether or not gridlines are shown for the row axis and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setGridlinesVisibleForValues(boolean visible)`
Sets the flag that controls whether or not gridlines are shown for the value axis and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setLegendLabelGenerator(CategoryLabelGenerator generator)`
Sets the legend label generator and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setRenderer(CategoryRenderer3D renderer)`
Sets the renderer and sends a change event to all registered listeners.
`void`
`setRowAxis(CategoryAxis3D axis)`
Sets the row axis and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setToolTipGenerator(CategoryItemLabelGenerator generator)`
Sets the tool tip generator and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setValueAxis(ValueAxis3D axis)`
Sets the value axis and sends a `Plot3DChangeEvent` to all registered listeners.
`void`
`setYDimensionOverride(Double dim)`
Sets the y-dimension override and, if the `autoAdjustDimensions` flag is set, recalculates the dimensions and sends a `Plot3DChangeEvent` to all registered listeners.

### Methods inherited from class org.jfree.chart3d.plot.AbstractPlot3D

`addChangeListener, fireChangeEvent, getChart, getDimensions, isAutoAdjustDimensions, isNotify, notifyListeners, removeChangeListener, setChart, setNotify`

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

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

## Constructor Details

### CategoryPlot3D

public CategoryPlot3D(CategoryDataset3D dataset, CategoryRenderer3D renderer, CategoryAxis3D rowAxis, CategoryAxis3D columnAxis, ValueAxis3D valueAxis)
Creates a new plot with the supplied dataset, renderer and axes.

Parameters:
  `dataset` - the dataset (`null` not permitted).
  `renderer` - the renderer (`null` not permitted).
  `rowAxis` - the row axis (`null` not permitted).
  `columnAxis` - the column axis (`null` not permitted).
  `valueAxis` - the value axis (`null` not permitted).

## Method Details

### setAutoAdjustDimensions

public void setAutoAdjustDimensions(boolean auto)
Sets the flag that controls whether the plot's dimensions are automatically calculated and, if `true`, sends a change event to all registered listeners.

Parameters:
  `auto` - the new flag value.
Since:
  1.2

### setDimensions

public void setDimensions(Dimension3D dimensions)
Sets the dimensions (in 3D space) for the plot, resets the `autoAdjustDimensions` flag to `false`, and sends a `Plot3DChangeEvent` to all registered listeners.

Parameters:
  `dimensions` - the dimensions (`null` not permitted).
See Also:
  - `Plot3D.getDimensions()`

### getDataset

public CategoryDataset3D getDataset()
Returns the dataset for the chart.

Returns:
  The dataset (never `null`).

### setDataset

public void setDataset(CategoryDataset3D dataset)
Sets the dataset and sends a `Plot3DChangeEvent` to all registered listeners. When you call this method, the axes will be reconfigured for the new data.

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

### getRenderer

public CategoryRenderer3D getRenderer()
Returns the renderer (very often you will need to cast this to a specific class to make customisations).

Returns:
  The renderer (never `null`).

### setRenderer

public void setRenderer(CategoryRenderer3D renderer)
Sets the renderer and sends a change event to all registered listeners.

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

### getRowAxis

public CategoryAxis3D getRowAxis()
Returns the row axis.

Returns:
  The row axis.

### setRowAxis

public void setRowAxis(CategoryAxis3D axis)
Sets the row axis and sends a `Plot3DChangeEvent` to all registered listeners. The row axis is equivalent to the z-axis.

Parameters:
  `axis` - the row axis (`null` not permitted).

### getColumnAxis

public CategoryAxis3D getColumnAxis()
Returns the column axis.

Returns:
  The column axis (never `null`).

### setColumnAxis

public void setColumnAxis(CategoryAxis3D axis)
Sets the column axis and sends a `Plot3DChangeEvent` to all registered listeners.

Parameters:
  `axis` - the new axis (`null` not permitted).
See Also:
  - `setRowAxis(org.jfree.chart3d.axis.CategoryAxis3D)`
  - `setValueAxis(org.jfree.chart3d.axis.ValueAxis3D)`

### getValueAxis

public ValueAxis3D getValueAxis()
Returns the value axis (the vertical axis in the plot).

Returns:
  The value axis (never `null`).

### setValueAxis

public void setValueAxis(ValueAxis3D axis)
Sets the value axis and sends a `Plot3DChangeEvent` to all registered listeners.

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

### getGridlinesVisibleForRows

public boolean getGridlinesVisibleForRows()
Returns `true` if gridlines are shown for the column axis and `false` otherwise. The default value is `false`.

Returns:
  A boolean.

### setGridlinesVisibleForRows

public void setGridlinesVisibleForRows(boolean visible)
Sets the flag that controls whether or not gridlines are shown for the row axis and sends a `Plot3DChangeEvent` to all registered listeners.

Parameters:
  `visible` - the new flag value.

### getGridlinePaintForRows

public Paint getGridlinePaintForRows()
Returns the paint used to draw the gridlines for the row axis, if they are visible.

Returns:
  The paint (never `null`).

### setGridlinePaintForRows

public void setGridlinePaintForRows(Paint paint)
Sets the paint used for the row axis gridlines and sends a `Plot3DChangeEvent` to all registered listeners.

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

### getGridlineStrokeForRows

public Stroke getGridlineStrokeForRows()
Returns the stroke for the gridlines associated with the row axis. The default value is `BasicStroke(0.5f, BasicStroke.CAP_ROUND, BasicStroke.JOIN_ROUND, 1f, new float[] { 3f, 3f }, 0f)`.

Returns:
  The stroke (never `null`).

### setGridlineStrokeForRows

public void setGridlineStrokeForRows(Stroke stroke)
Sets the stroke used to draw the gridlines for the row axis, if they are visible, and sends a `Plot3DChangeEvent` to all registered listeners.

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

### getGridlinesVisibleForColumns

public boolean getGridlinesVisibleForColumns()
Returns `true` if gridlines are shown for the column axis and `false` otherwise. The default value is `false`.

Returns:
  A boolean.

### setGridlinesVisibleForColumns

public void setGridlinesVisibleForColumns(boolean visible)
Sets the flag that controls whether or not gridlines are shown for the column axis and sends a `Plot3DChangeEvent` to all registered listeners.

Parameters:
  `visible` - the new flag value.

### getGridlinesVisibleForValues

public boolean getGridlinesVisibleForValues()
Returns `true` if gridlines are shown for the column axis and `false` otherwise. The default value is `true`.

Returns:
  A boolean.

### setGridlinesVisibleForValues

public void setGridlinesVisibleForValues(boolean visible)
Sets the flag that controls whether or not gridlines are shown for the value axis and sends a `Plot3DChangeEvent` to all registered listeners.

Parameters:
  `visible` - the new flag value.

### getGridlinePaintForValues

public Paint getGridlinePaintForValues()
Returns the paint for the gridlines associated with the value axis. The default value is `Color.WHITE`.

Returns:
  The paint for value axis gridlines (never `null`).

### setGridlinePaintForValues

public void setGridlinePaintForValues(Paint paint)
Sets the paint used for the value axis gridlines and sends a `Plot3DChangeEvent` to all registered listeners.

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

### getGridlineStrokeForValues

public Stroke getGridlineStrokeForValues()
Returns the stroke for the gridlines associated with the value axis. The default value is `BasicStroke(0.5f, BasicStroke.CAP_ROUND, BasicStroke.JOIN_ROUND, 1f, new float[] { 3f, 3f }, 0f)`.

Returns:
  The stroke (never `null`).

### setGridlineStrokeForValues

public void setGridlineStrokeForValues(Stroke stroke)
Sets the stroke used to draw the grid lines for the value axis, if they are visible, and sends a `Plot3DChangeEvent` to all registered listeners.

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

### getGridlinePaintForColumns

public Paint getGridlinePaintForColumns()
Returns the paint used to draw the grid lines for the column axis, if they are visible. The default value is `Color.WHITE`.

Returns:
  The paint (never `null`).

### setGridlinePaintForColumns

public void setGridlinePaintForColumns(Paint paint)
Sets the paint used to draw the grid lines for the column axis, if they are visible, and sends a `Plot3DChangeEvent` to all registered listeners.

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

### getGridlineStrokeForColumns

public Stroke getGridlineStrokeForColumns()
Returns the stroke for the gridlines associated with the column axis. The default value is `BasicStroke(0.5f, BasicStroke.CAP_ROUND, BasicStroke.JOIN_ROUND, 1f, new float[] { 3f, 3f }, 0f)`.

Returns:
  The stroke (never `null`).

### setGridlineStrokeForColumns

public void setGridlineStrokeForColumns(Stroke stroke)
Sets the stroke used to draw the grid lines for the column axis, if they are visible, and sends a `Plot3DChangeEvent` to all registered listeners.

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

### getLegendLabelGenerator

public CategoryLabelGenerator getLegendLabelGenerator()
Returns the legend label generator, an object that converts key values in the dataset into corresponding strings for presentation in the chart.

Returns:
  The legend label generator (never `null`).
Since:
  1.2

### setLegendLabelGenerator

public void setLegendLabelGenerator(CategoryLabelGenerator generator)
Sets the legend label generator and sends a `Plot3DChangeEvent` to all registered listeners.

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

### getYDimensionOverride

public Double getYDimensionOverride()
Returns the y-dimension override. The default value is `null`, which means that when the plot dimensions are automatically calculated, the height of the plot will be set to the greater of the width and the depth.

Returns:
  The y-dimension override (possibly `null`).
Since:
  1.2

### setYDimensionOverride

public void setYDimensionOverride(Double dim)
Sets the y-dimension override and, if the `autoAdjustDimensions` flag is set, recalculates the dimensions and sends a `Plot3DChangeEvent` to all registered listeners.

Parameters:
  `dim` - the new y-dimension override (`null` permitted).
Since:
  1.2

### getToolTipGenerator

public CategoryItemLabelGenerator getToolTipGenerator()
Returns the tool tip generator. This is an object that calculates and returns a string (that will be used as the tool tip) for any given data value in the dataset.

Returns:
  The tool tip generator (possibly `null`).
Since:
  1.3

### setToolTipGenerator

public void setToolTipGenerator(CategoryItemLabelGenerator generator)
Sets the tool tip generator and sends a `Plot3DChangeEvent` to all registered listeners.

Parameters:
  `generator` - the new generator (`null` permitted).
Since:
  1.3

### getLegendInfo

public List<LegendItemInfo> getLegendInfo()
Returns a list containing legend item info, typically one item for each series in the chart. This is intended for use in the construction of a chart legend.

Specified by:
  `getLegendInfo` in interface `Plot3D`
Returns:
  A list containing legend item info (possibly empty but never `null`).

### compose

public void compose(World world, double xOffset, double yOffset, double zOffset)
Description copied from interface: `Plot3D`
Adds 3D objects representing the current data for the plot to the specified world. After the world has been populated (or constructed) in this way, it is ready for rendering.

Specified by:
  `compose` in interface `Plot3D`
Parameters:
  `world` - the world (`null` not permitted).
  `xOffset` - the x-offset.
  `yOffset` - the y-offset.
  `zOffset` - the z-offset.

### generateToolTipText

public String generateToolTipText(ItemKey itemKey)
Description copied from class: `AbstractPlot3D`
Returns the tool tip text for the specified data item, or `null` if no tool tip is required.

Specified by:
  `generateToolTipText` in interface `Plot3D`
Specified by:
  `generateToolTipText` in class `AbstractPlot3D`
Parameters:
  `itemKey` - the item key (`null` not permitted).
Returns:
  The tool tip text (possibly `null`).

### receive

public void receive(ChartElementVisitor visitor)
Accepts a visitor for the plot. This method first calls the `receive()` method for each of the plot's axes and the renderer, then performs the visitor's function on the plot. This is a general purpose mechanism, but the main use is to apply chart style changes across all the elements of a chart.

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

### equals

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

Overrides:
  `equals` in class `AbstractPlot3D`
Parameters:
  `obj` - the object (`null` permitted).
Returns:
  A boolean.

### datasetChanged

public void datasetChanged(Dataset3DChangeEvent event)
Receives notification of a change to the dataset and handles this by adjusting the plot dimensions (according to the setting of the `autoAdjustDimensions` flag), reconfiguring the axes, and propagating a `Plot3DChangeEvent`.

Specified by:
  `datasetChanged` in interface `Dataset3DChangeListener`
Overrides:
  `datasetChanged` in class `AbstractPlot3D`
Parameters:
  `event` - the change event.

### axisChanged

public void axisChanged(Axis3DChangeEvent event)
Receives notification that one of the axes has been changed. This will trigger a `Plot3DChangeEvent` that will usually cause the chart to be repainted.

Specified by:
  `axisChanged` in interface `Axis3DChangeListener`
Parameters:
  `event` - the change event.

### rendererChanged

public void rendererChanged(Renderer3DChangeEvent event)
Receives notification that the renderer has been modified in some way. This will trigger a `Plot3DChangeEvent` that will usually cause the chart to be repainted.

Specified by:
  `rendererChanged` in interface `Renderer3DChangeListener`
Parameters:
  `event` - information about the event.