com.orsoncharts.plot

## Class CategoryPlot3D

- java.lang.Object
- - com.orsoncharts.plot.AbstractPlot3D
  - - com.orsoncharts.plot.CategoryPlot3D

- All Implemented Interfaces:
    Axis3DChangeListener, ChartElement, Dataset3DChangeListener, Plot3D, Renderer3DChangeListener, java.io.Serializable, java.util.EventListener

      public class CategoryPlot3D
      extends AbstractPlot3D
      implements Axis3DChangeListener, Renderer3DChangeListener, java.io.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 com.orsoncharts.plot.AbstractPlot3D

      `autoAdjustDimensions, dimensions`

  - ### Constructor Summary

    Constructors
    Constructor and 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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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(java.lang.Object obj)` Tests this plot for equality with an arbitrary object.
    `java.lang.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.
    `java.awt.Paint` | `getGridlinePaintForColumns()` Returns the paint used to draw the grid lines for the column axis, if they are visible.
    `java.awt.Paint` | `getGridlinePaintForRows()` Returns the paint used to draw the gridlines for the row axis, if they are visible.
    `java.awt.Paint` | `getGridlinePaintForValues()` Returns the paint for the gridlines associated with the value axis.
    `java.awt.Stroke` | `getGridlineStrokeForColumns()` Returns the stroke for the gridlines associated with the column axis.
    `java.awt.Stroke` | `getGridlineStrokeForRows()` Returns the stroke for the gridlines associated with the row axis.
    `java.awt.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.
    `java.util.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).
    `java.lang.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(java.awt.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(java.awt.Paint paint)` Sets the paint used for the row axis gridlines and sends a `Plot3DChangeEvent` to all registered listeners.
    `void` | `setGridlinePaintForValues(java.awt.Paint paint)` Sets the paint used for the value axis gridlines and sends a `Plot3DChangeEvent` to all registered listeners.
    `void` | `setGridlineStrokeForColumns(java.awt.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(java.awt.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(java.awt.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(java.lang.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 com.orsoncharts.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 Detail

    - #### 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 Detail

    - #### 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(com.orsoncharts.axis.CategoryAxis3D)`, `setValueAxis(com.orsoncharts.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 java.awt.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(java.awt.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 java.awt.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(java.awt.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 java.awt.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(java.awt.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 java.awt.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(java.awt.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 java.awt.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(java.awt.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 java.awt.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(java.awt.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 java.lang.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(java.lang.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 java.util.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 java.lang.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(java.lang.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.