com.orsoncharts.renderer.category

## Class BarRenderer3D

- java.lang.Object
- - com.orsoncharts.renderer.AbstractRenderer3D
  - - com.orsoncharts.renderer.category.AbstractCategoryRenderer3D
    - - com.orsoncharts.renderer.category.BarRenderer3D

- All Implemented Interfaces:
    ChartElement, CategoryRenderer3D, Renderer3D, java.io.Serializable
  Direct Known Subclasses:
    StackedBarRenderer3D

      public class BarRenderer3D
      extends AbstractCategoryRenderer3D
      implements java.io.Serializable

  A renderer for creating 3D bar charts from a `CategoryDataset3D` (for use with a `CategoryPlot3D`). For example:
  (refer to `BarChart3DDemo1.java` for the code to generate the above chart).
  There is a factory method to create a chart using this renderer - see `Chart3DFactory.createBarChart(String, String, CategoryDataset3D, String, String, String)`.
  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 interface com.orsoncharts.renderer.Renderer3D

      `TRANSPARENT_COLOR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BarRenderer3D()` Creates a new renderer with default attribute values.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `composeItem(CategoryDataset3D dataset, int series, int row, int column, World world, Dimension3D dimensions, double xOffset, double yOffset, double zOffset)` Constructs and places one item from the specified dataset into the given world.
    `protected void` | `composeItem(double value, double barBase, CategoryDataset3D dataset, int series, int row, int column, World world, Dimension3D dimensions, double xOffset, double yOffset, double zOffset)` Performs the actual work of composing a bar to represent one item in the dataset.
    `protected void` | `drawItemLabels(World world, CategoryDataset3D dataset, KeyedValues3DItemKey itemKey, double xw, double yw, double zw, double basew, boolean inverted)`
    `boolean` | `equals(java.lang.Object obj)` Tests this renderer for equality with an arbitrary object.
    `Range` | `findValueRange(Values3D<? extends java.lang.Number> data)` Returns the range of values that will be required on the value axis to see all the data from the dataset.
    `double` | `getBarXWidth()` Returns the bar width as a percentage of the column width.
    `double` | `getBarZWidth()` Returns the bar width as a percentage of the row width.
    `double` | `getBase()` Returns the base value for the bars.
    `CategoryColorSource` | `getBaseColorSource()` Returns the object used to fetch the color for the base of bars where the base of the bar is "cropped" (on account of the base value falling outside of the bounds of the y-axis).
    `CategoryColorSource` | `getTopColorSource()` Returns the object used to fetch the color for the top of bars where the top of the bar is "cropped" (on account of the data value falling outside of the bounds of the y-axis).
    `void` | `setBarXWidth(double barXWidth)` Sets the the bar width as a percentage of the column width and fires a `Renderer3DChangeEvent`.
    `void` | `setBarZWidth(double barZWidth)` Sets the the bar width as a percentage of the row width and fires a `Renderer3DChangeEvent`.
    `void` | `setBase(double base)` Sets the base value for the bars and fires a `Renderer3DChangeEvent`.
    `void` | `setBaseColorSource(CategoryColorSource source)` Sets the object that determines the color to use for the base of bars where the base value falls outside the axis range, and sends a `Renderer3DChangeEvent` to all registered listeners.
    `void` | `setTopColorSource(CategoryColorSource source)` Sets the object used to fetch the color for the top of bars where the top of the bar is "cropped", and sends a `Renderer3DChangeEvent` to all registered listeners.

    - ### Methods inherited from class com.orsoncharts.renderer.category.AbstractCategoryRenderer3D

      `getColorSource, getItemLabelGenerator, getItemLabelOffsets, getPlot, setColors, setColorSource, setItemLabelGenerator, setItemLabelOffsets, setPlot`

    - ### Methods inherited from class com.orsoncharts.renderer.AbstractRenderer3D

      `addChangeListener, fireChangeEvent, getItemLabelBackgroundColor, getItemLabelColor, getItemLabelFont, getItemLabelPositioning, isNotify, notifyListeners, receive, removeChangeListener, setItemLabelBackgroundColor, setItemLabelColor, setItemLabelFont, setItemLabelPositioning, setNotify`

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

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

    - ### Methods inherited from interface com.orsoncharts.renderer.Renderer3D

      `addChangeListener, removeChangeListener`

    - ### Methods inherited from interface com.orsoncharts.ChartElement

      `receive`

- - ### Constructor Detail

    - #### BarRenderer3D

          public BarRenderer3D()

      Creates a new renderer with default attribute values.

  - ### Method Detail

    - #### getBase

          public double getBase()

      Returns the base value for the bars. The default value is `0.0`.
      Returns:
        The base value for the bars.
      See Also:
        `setBase(double)`

    - #### setBase

          public void setBase(double base)

      Sets the base value for the bars and fires a `Renderer3DChangeEvent`.
      Parameters:
        `base` - the new base value.
      See Also:
        `getBase()`

    - #### getBarXWidth

          public double getBarXWidth()

      Returns the bar width as a percentage of the column width. The default value is `0.8` (the total width of each column in world units is `1.0`, so the default leaves a small gap between each bar).
      Returns:
        The bar width (in world units).

    - #### setBarXWidth

          public void setBarXWidth(double barXWidth)

      Sets the the bar width as a percentage of the column width and fires a `Renderer3DChangeEvent`.
      Parameters:
        `barXWidth` - the new width.

    - #### getBarZWidth

          public double getBarZWidth()

      Returns the bar width as a percentage of the row width. The default value is `0.8`.
      Returns:
        The bar width.

    - #### setBarZWidth

          public void setBarZWidth(double barZWidth)

      Sets the the bar width as a percentage of the row width and fires a `Renderer3DChangeEvent`.
      Parameters:
        `barZWidth` - the new width.

    - #### getBaseColorSource

          public CategoryColorSource getBaseColorSource()

      Returns the object used to fetch the color for the base of bars where the base of the bar is "cropped" (on account of the base value falling outside of the bounds of the y-axis). This is used to give a visual indication to the end-user that the bar on display is cropped. If this paint source is `null`, the regular series color will be used for the top of the bars.
      Returns:
        A paint source (possibly `null`).

    - #### setBaseColorSource

          public void setBaseColorSource(CategoryColorSource source)

      Sets the object that determines the color to use for the base of bars where the base value falls outside the axis range, and sends a `Renderer3DChangeEvent` to all registered listeners. If you set this to `null`, the regular series color will be used to draw the base of the bar, but it will be harder for the end-user to know that only a section of the bar is visible in the chart. Note that the default base paint source returns `Color.WHITE` always.
      Parameters:
        `source` - the source (`null` permitted).
      See Also:
        `getBaseColorSource()`, `getTopColorSource()`

    - #### getTopColorSource

          public CategoryColorSource getTopColorSource()

      Returns the object used to fetch the color for the top of bars where the top of the bar is "cropped" (on account of the data value falling outside of the bounds of the y-axis). This is used to give a visual indication to the end-user that the bar on display is cropped. If this paint source is `null`, the regular series color will be used for the top of the bars.
      Returns:
        A paint source (possibly `null`).

    - #### setTopColorSource

          public void setTopColorSource(CategoryColorSource source)

      Sets the object used to fetch the color for the top of bars where the top of the bar is "cropped", and sends a `Renderer3DChangeEvent` to all registered listeners.
      Parameters:
        `source` - the source (`null` permitted).
      See Also:
        `getTopColorSource()`, `getBaseColorSource()`

    - #### findValueRange

          public Range findValueRange(Values3D<? extends java.lang.Number> data)

      Returns the range of values that will be required on the value axis to see all the data from the dataset. We override the method to include in the range the base value for the bars.
      Specified by:
        `findValueRange` in interface `CategoryRenderer3D`
      Overrides:
        `findValueRange` in class `AbstractCategoryRenderer3D`
      Parameters:
        `data` - the data (`null` not permitted).
      Returns:
        The range (possibly `null`)

    - #### composeItem

          public void composeItem(CategoryDataset3D dataset,
                                  int series,
                                  int row,
                                  int column,
                                  World world,
                                  Dimension3D dimensions,
                                  double xOffset,
                                  double yOffset,
                                  double zOffset)

      Constructs and places one item from the specified dataset into the given world. This method will be called by the `CategoryPlot3D` class while iterating over the items in the dataset.
      Specified by:
        `composeItem` in interface `CategoryRenderer3D`
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `series` - the series index.
        `row` - the row index.
        `column` - the column index.
        `world` - the world (`null` not permitted).
        `dimensions` - the plot dimensions (`null` not permitted).
        `xOffset` - the x-offset.
        `yOffset` - the y-offset.
        `zOffset` - the z-offset.

    - #### composeItem

          protected void composeItem(double value,
                                     double barBase,
                                     CategoryDataset3D dataset,
                                     int series,
                                     int row,
                                     int column,
                                     World world,
                                     Dimension3D dimensions,
                                     double xOffset,
                                     double yOffset,
                                     double zOffset)

      Performs the actual work of composing a bar to represent one item in the dataset. This method is reused by the `StackedBarRenderer3D` subclass.
      Parameters:
        `value` - the data value (top of the bar).
        `barBase` - the base value for the bar.
        `dataset` - the dataset.
        `series` - the series index.
        `row` - the row index.
        `column` - the column index.
        `world` - the world.
        `dimensions` - the plot dimensions.
        `xOffset` - the x-offset.
        `yOffset` - the y-offset.
        `zOffset` - the z-offset.

    - #### drawItemLabels

          protected void drawItemLabels(World world,
                                        CategoryDataset3D dataset,
                                        KeyedValues3DItemKey itemKey,
                                        double xw,
                                        double yw,
                                        double zw,
                                        double basew,
                                        boolean inverted)

    - #### equals

          public boolean equals(java.lang.Object obj)

      Tests this renderer for equality with an arbitrary object.
      Overrides:
        `equals` in class `AbstractCategoryRenderer3D`
      Parameters:
        `obj` - the object (`null` permitted).
      Returns:
        A boolean.