com.orsoncharts

## Class Chart3D

- java.lang.Object
- - com.orsoncharts.Chart3D

- All Implemented Interfaces:
    ChartElement, Drawable3D, Plot3DChangeListener, ChartStyleChangeListener, java.io.Serializable, java.util.EventListener

      public class Chart3D
      extends java.lang.Object
      implements Drawable3D, ChartElement, Plot3DChangeListener, ChartStyleChangeListener, java.io.Serializable

  A chart object for 3D charts (this is the umbrella object that manages all the components of the chart). The `Chart3DFactory` class provides some factory methods to construct common types of charts.
  All rendering is done via the Java2D API, so this object is able to draw to any implementation of the Graphics2D API (including JFreeSVG for SVG output, and OrsonPDF for PDF output).
  In the step prior to rendering, a chart is composed in a 3D model that is referred to as the "world". The dimensions of this 3D model are measured in "world units" and the overall size is controlled by the plot. You will see some attributes in the API that are specified in "world units", and these can be used to modify how objects are composed within the 3D world model. Once the objects (for example, bars in a bar chart) within the world have been composed, they are projected onto a 2D plane and rendered to the `Graphics2D` target (such as the screen, image, SVG file or PDF file).
  Charts can have simple titles or composite titles (anything that can be constructed as a `TableElement` instance. The `TitleUtils` class contains methods to create a common title/subtitle composite title. This is illustrated in some of the demo applications. The chart title and legend (and also the axis labels) are not part of the 3D world model, they are overlaid on the output after the 3D components have been rendered.
  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:
    `Chart3DFactory`, `Chart3DPanel`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static double` | `DEFAULT_PROJ_DIST` The default projection distance.
    `static java.lang.String` | `INTERACTIVE_ELEMENT_TYPE` The key for a property that stores the interactive element type.
    `static java.lang.String` | `SERIES_KEY` The key for a property that stores the series key.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Chart3D(java.lang.String title, java.lang.String subtitle, Plot3D plot)` Creates a 3D chart for the specified plot using the default chart style.
    `Chart3D(java.lang.String title, java.lang.String subtitle, Plot3D plot, ChartStyle style)` Creates a 3D chart for the specified plot using the supplied style.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addChangeListener(Chart3DChangeListener listener)` Registers a listener to receive notification of changes to the chart.
    `RenderingInfo` | `draw(java.awt.Graphics2D g2, java.awt.geom.Rectangle2D bounds)` Draws the chart to the specified output target.
    `boolean` | `equals(java.lang.Object obj)` Tests this chart for equality with an arbitrary object.
    `protected void` | `fireChangeEvent()` Sends a `Chart3DChangeEvent` to all registered listeners.
    `boolean` | `getAntiAlias()` Returns a flag that indicates whether or not anti-aliasing is used when the chart is drawn.
    `RectanglePainter` | `getBackground()` Returns the background painter (an object that is responsible for filling the background area before charts are rendered).
    `java.awt.Color` | `getChartBoxColor()` Returns the chart box color (the chart box is the visible, open-sided box inside which data is plotted for all charts except pie charts).
    `Dimension3D` | `getDimensions()` Returns the dimensions of the 3D object.
    `boolean` | `getElementHinting()` Returns the flag that controls whether or not element hints will be added to the `Graphics2D` output when the chart is rendered.
    `java.lang.String` | `getID()` Returns the chart id.
    `Anchor2D` | `getLegendAnchor()` Returns the legend anchor.
    `LegendBuilder` | `getLegendBuilder()` Returns the legend builder.
    `Orientation` | `getLegendOrientation()` Returns the orientation for the legend.
    `Plot3D` | `getPlot()` Returns the plot, which manages the dataset, the axes (if any), the renderer (if any) and other attributes related to plotting data.
    `double` | `getProjDistance()` Returns the projection distance.
    `java.awt.RenderingHints` | `getRenderingHints()` Returns the collection of rendering hints for the chart.
    `ChartStyle` | `getStyle()` Returns the chart style.
    `TableElement` | `getTitle()` Returns the chart title.
    `Anchor2D` | `getTitleAnchor()` Returns the title anchor.
    `Offset2D` | `getTranslate2D()` Sets the offset in 2D-space for the rendering of the chart.
    `ViewPoint3D` | `getViewPoint()` Returns the view point.
    `boolean` | `isNotify()` Returns a flag that controls whether or not change events are sent to registered listeners.
    `void` | `notifyListeners(Chart3DChangeEvent event)` Notifies all registered listeners that the chart has been modified.
    `void` | `plotChanged(Plot3DChangeEvent event)` Receives notification of a plot change event, refreshes the 3D model (world) and passes the event on, wrapped in a `Chart3DChangeEvent`, to all registered listeners.
    `void` | `receive(ChartElementVisitor visitor)` Receives a visitor.
    `void` | `removeChangeListener(Chart3DChangeListener listener)` Deregisters a listener so that it no longer receives notification of changes to the chart.
    `static java.lang.String` | `renderedElementToString(RenderedElement element)` Returns a string representing the `element`, primarily for debugging purposes.
    `void` | `setAntiAlias(boolean flag)` Sets a flag that indicates whether or not anti-aliasing is used when the chart is drawn.
    `void` | `setBackground(RectanglePainter background)` Sets the background painter and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setChartBoxColor(java.awt.Color color)` Sets the chart box color and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setElementHinting(boolean hinting)` Sets the flag that controls whether or not element hints will be added to the `Graphics2D` output when the chart is rendered and sends a change event to all registered listeners.
    `void` | `setID(java.lang.String id)` Sets the chart id.
    `void` | `setLegendAnchor(Anchor2D anchor)` Sets the legend anchor and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setLegendBuilder(LegendBuilder legendBuilder)` Sets the legend builder and sends a change event to all registered listeners.
    `void` | `setLegendOrientation(Orientation orientation)` Sets the legend orientation and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setLegendPosition(Anchor2D anchor, Orientation orientation)` Sets the legend position (both the anchor point and the orientation) and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setNotify(boolean notify)` Sets a flag that controls whether or not listeners receive `Chart3DChangeEvent` notifications.
    `void` | `setProjDistance(double dist)` Sets the projection distance and sends a change event to all registered listeners.
    `void` | `setRenderingHints(java.awt.RenderingHints hints)` Sets the rendering hints for the chart.
    `void` | `setStyle(ChartStyle style)` Sets (and applies) the specified chart style.
    `void` | `setTitle(java.lang.String title)` Sets the chart title and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setTitle(java.lang.String title, java.awt.Font font, java.awt.Color color)` Sets the chart title and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setTitle(TableElement title)` Sets the chart title and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setTitleAnchor(Anchor2D anchor)` Sets the title anchor and sends a `Chart3DChangeEvent` to all registered listeners.
    `void` | `setTranslate2D(Offset2D offset)` Sets the offset in 2D-space for the rendering of the chart and sends a change event to all registered listeners.
    `void` | `setViewPoint(ViewPoint3D viewPoint)` Sets the view point.
    `void` | `styleChanged(ChartStyleChangeEvent event)` Called to inform that a chart change event has occurred.

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

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

- - ### Field Detail

    - #### DEFAULT_PROJ_DIST

          public static final double DEFAULT_PROJ_DIST

      The default projection distance.
      Since:
        1.2
      See Also:
        Constant Field Values

    - #### INTERACTIVE_ELEMENT_TYPE

          public static final java.lang.String INTERACTIVE_ELEMENT_TYPE

      The key for a property that stores the interactive element type.
      Since:
        1.3
      See Also:
        Constant Field Values

    - #### SERIES_KEY

          public static final java.lang.String SERIES_KEY

      The key for a property that stores the series key. This is used to store the series key on the `TableElement` representing a legend item, and also on a corresponding `RenderedElement` after chart rendering (in the `RenderingInfo`).
      Since:
        1.3
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Chart3D

          public Chart3D(java.lang.String title,
                         java.lang.String subtitle,
                         Plot3D plot)

      Creates a 3D chart for the specified plot using the default chart style. Note that a plot instance must be used in one chart instance only.
      Parameters:
        `title` - the chart title (`null` permitted).
        `subtitle` - the chart subtitle (`null` permitted).
        `plot` - the plot (`null` not permitted).
      See Also:
        `Chart3DFactory`

    - #### Chart3D

          public Chart3D(java.lang.String title,
                         java.lang.String subtitle,
                         Plot3D plot,
                         ChartStyle style)

      Creates a 3D chart for the specified plot using the supplied style.
      Parameters:
        `title` - the chart title (`null` permitted).
        `subtitle` - the chart subtitle (`null` permitted).
        `plot` - the plot (`null` not permitted).
        `style` - the chart style (`null` not permitted).
      Since:
        1.2

  - ### Method Detail

    - #### getID

          public java.lang.String getID()

      Returns the chart id.
      Returns:
        The chart id (possibly `null`).
      Since:
        1.3

    - #### setID

          public void setID(java.lang.String id)

      Sets the chart id.
      Parameters:
        `id` - the id (`null` permitted).
      Since:
        1.3

    - #### getBackground

          public RectanglePainter getBackground()

      Returns the background painter (an object that is responsible for filling the background area before charts are rendered). The default value is an instance of `StandardRectanglePainter` that paints the background white.
      Returns:
        The background painter (possibly `null`).
      See Also:
        `setBackground(com.orsoncharts.table.RectanglePainter)`

    - #### setBackground

          public void setBackground(RectanglePainter background)

      Sets the background painter and sends a `Chart3DChangeEvent` to all registered listeners. A background painter is used to fill in the background of the chart before the 3D rendering takes place. To fill the background with a color or image, you can use `StandardRectanglePainter`. To fill the background with a gradient paint, use `GradientRectanglePainter`.
      Parameters:
        `background` - the background painter (`null` permitted).
      See Also:
        `getBackground()`

    - #### getTitle

          public TableElement getTitle()

      Returns the chart title. A `TableElement` is used for the title, since it allows a lot of flexibility in the types of title that can be displayed.
      Returns:
        The chart title (possibly `null`).

    - #### setTitle

          public void setTitle(java.lang.String title)

      Sets the chart title and sends a `Chart3DChangeEvent` to all registered listeners. This is a convenience method that constructs the required `TableElement` under-the-hood.
      Parameters:
        `title` - the title (`null` permitted).

    - #### setTitle

          public void setTitle(java.lang.String title,
                               java.awt.Font font,
                               java.awt.Color color)

      Sets the chart title and sends a `Chart3DChangeEvent` to all registered listeners. This is a convenience method that constructs the required `TableElement` under-the-hood.
      Parameters:
        `title` - the title (`null` not permitted).
        `font` - the font (`null` not permitted).
        `color` - the foreground color (`null` not permitted).

    - #### setTitle

          public void setTitle(TableElement title)

      Sets the chart title and sends a `Chart3DChangeEvent` to all registered listeners. You can set the title to `null`, in which case there will be no chart title.
      Parameters:
        `title` - the title (`null` permitted).

    - #### getTitleAnchor

          public Anchor2D getTitleAnchor()

      Returns the title anchor. This controls the position of the title in the chart area.
      Returns:
        The title anchor (never `null`).
      See Also:
        `setTitleAnchor(com.orsoncharts.util.Anchor2D)`

    - #### setTitleAnchor

          public void setTitleAnchor(Anchor2D anchor)

      Sets the title anchor and sends a `Chart3DChangeEvent` to all registered listeners. There is a `TitleAnchor` class providing some useful default anchors.
      Parameters:
        `anchor` - the anchor (`null` not permitted).
      See Also:
        `getTitleAnchor()`

    - #### getPlot

          public Plot3D getPlot()

      Returns the plot, which manages the dataset, the axes (if any), the renderer (if any) and other attributes related to plotting data. The plot is specified via the constructor...there is no method to set a new plot for the chart, instead you need to create a new chart instance.
      Returns:
        The plot (never `null`).

    - #### getChartBoxColor

          public java.awt.Color getChartBoxColor()

      Returns the chart box color (the chart box is the visible, open-sided box inside which data is plotted for all charts except pie charts). The default value is `Color.WHITE`.
      Returns:
        The chart box color (never `null`).
      See Also:
        `setChartBoxColor(java.awt.Color)`

    - #### setChartBoxColor

          public void setChartBoxColor(java.awt.Color color)

      Sets the chart box color and sends a `Chart3DChangeEvent` to all registered listeners. Bear in mind that `PiePlot3D` does not display a chart box, so this attribute will be ignored for pie charts.
      Parameters:
        `color` - the color (`null` not permitted).
      See Also:
        `getChartBoxColor()`

    - #### getDimensions

          public Dimension3D getDimensions()

      Returns the dimensions of the 3D object.
      Specified by:
        `getDimensions` in interface `Drawable3D`
      Returns:
        The dimensions (never `null`).

    - #### getViewPoint

          public ViewPoint3D getViewPoint()

      Returns the view point.
      Specified by:
        `getViewPoint` in interface `Drawable3D`
      Returns:
        The view point (never `null`).

    - #### setViewPoint

          public void setViewPoint(ViewPoint3D viewPoint)

      Sets the view point.
      Specified by:
        `setViewPoint` in interface `Drawable3D`
      Parameters:
        `viewPoint` - the view point (`null` not permitted).

    - #### getProjDistance

          public double getProjDistance()

      Returns the projection distance. The default value is `DEFAULT_PROJ_DIST`, higher numbers flatten out the perspective and reduce distortion in the projected image.
      Specified by:
        `getProjDistance` in interface `Drawable3D`
      Returns:
        The projection distance.
      Since:
        1.2

    - #### setProjDistance

          public void setProjDistance(double dist)

      Sets the projection distance and sends a change event to all registered listeners.
      Specified by:
        `setProjDistance` in interface `Drawable3D`
      Parameters:
        `dist` - the distance.
      Since:
        1.2

    - #### getTranslate2D

          public Offset2D getTranslate2D()

      Sets the offset in 2D-space for the rendering of the chart. The default value is `(0, 0)` but the user can modify it via ALT-mouse-drag in the chart panel, providing an easy way to get improved chart alignment in the panels (especially prior to export to PNG, SVG or PDF).
      Specified by:
        `getTranslate2D` in interface `Drawable3D`
      Returns:
        The offset (never `null`).

    - #### setTranslate2D

          public void setTranslate2D(Offset2D offset)

      Sets the offset in 2D-space for the rendering of the chart and sends a change event to all registered listeners.
      Specified by:
        `setTranslate2D` in interface `Drawable3D`
      Parameters:
        `offset` - the new offset (`null` not permitted).

    - #### getLegendBuilder

          public LegendBuilder getLegendBuilder()

      Returns the legend builder. The default value is an instance of `StandardLegendBuilder`. If the legend builder is `null`, no legend will be displayed for the chart.
      Returns:
        The legend builder (possibly `null`).
      See Also:
        `setLegendBuilder(com.orsoncharts.legend.LegendBuilder)`, `setLegendAnchor(com.orsoncharts.util.Anchor2D)`

    - #### setLegendBuilder

          public void setLegendBuilder(LegendBuilder legendBuilder)

      Sets the legend builder and sends a change event to all registered listeners. When the legend builder is `null`, no legend will be displayed on the chart.
      Parameters:
        `legendBuilder` - the legend builder (`null` permitted).
      See Also:
        `setLegendAnchor(com.orsoncharts.util.Anchor2D)`

    - #### getLegendAnchor

          public Anchor2D getLegendAnchor()

      Returns the legend anchor.
      Returns:
        The legend anchor (never `null`).
      See Also:
        `setLegendAnchor(com.orsoncharts.util.Anchor2D)`

    - #### setLegendAnchor

          public void setLegendAnchor(Anchor2D anchor)

      Sets the legend anchor and sends a `Chart3DChangeEvent` to all registered listeners. There is a `LegendAnchor` class providing some useful default anchors.
      Parameters:
        `anchor` - the anchor (`null` not permitted).
      See Also:
        `getLegendAnchor()`

    - #### getLegendOrientation

          public Orientation getLegendOrientation()

      Returns the orientation for the legend.
      Returns:
        The orientation (never `null`).
      Since:
        1.1

    - #### setLegendOrientation

          public void setLegendOrientation(Orientation orientation)

      Sets the legend orientation and sends a `Chart3DChangeEvent` to all registered listeners.
      Parameters:
        `orientation` - the orientation (`null` not permitted).
      Since:
        1.1

    - #### setLegendPosition

          public void setLegendPosition(Anchor2D anchor,
                                        Orientation orientation)

      Sets the legend position (both the anchor point and the orientation) and sends a `Chart3DChangeEvent` to all registered listeners. This is a convenience method that calls both the `setLegendAnchor(com.orsoncharts.util.Anchor2D)` and `setLegendOrientation(com.orsoncharts.util.Orientation)` methods.
      Parameters:
        `anchor` - the anchor (`null` not permitted).
        `orientation` - the orientation (`null` not permitted).
      Since:
        1.1

    - #### getRenderingHints

          public java.awt.RenderingHints getRenderingHints()

      Returns the collection of rendering hints for the chart.
      Returns:
        The rendering hints for the chart (never `null`).
      Since:
        1.1
      See Also:
        `setRenderingHints(RenderingHints)`

    - #### setRenderingHints

          public void setRenderingHints(java.awt.RenderingHints hints)

      Sets the rendering hints for the chart. These will be added (using the `Graphics2D.addRenderingHints()` method) near the start of the chart rendering. Note that calling this method will replace all existing hints assigned to the chart. If you simply wish to add an additional hint, you can use `getRenderingHints().put(key, value)`.
      Parameters:
        `hints` - the rendering hints (`null` not permitted).
      Since:
        1.1
      See Also:
        `getRenderingHints()`

    - #### getAntiAlias

          public boolean getAntiAlias()

      Returns a flag that indicates whether or not anti-aliasing is used when the chart is drawn.
      Returns:
        The flag.
      Since:
        1.1
      See Also:
        `setAntiAlias(boolean)`

    - #### setAntiAlias

          public void setAntiAlias(boolean flag)

      Sets a flag that indicates whether or not anti-aliasing is used when the chart is drawn.

      Anti-aliasing usually improves the appearance of charts, but is slower.

      Parameters:
        `flag` - the new value of the flag.
      Since:
        1.1
      See Also:
        `getAntiAlias()`

    - #### getElementHinting

          public boolean getElementHinting()

      Returns the flag that controls whether or not element hints will be added to the `Graphics2D` output when the chart is rendered. The default value is `false`.
      Returns:
        A boolean.
      Since:
        1.3

    - #### setElementHinting

          public void setElementHinting(boolean hinting)

      Sets the flag that controls whether or not element hints will be added to the `Graphics2D` output when the chart is rendered and sends a change event to all registered listeners.
      Parameters:
        `hinting` - the new flag value.
      Since:
        1.3

    - #### getStyle

          public ChartStyle getStyle()

      Returns the chart style.
      Returns:
        The chart style (never `null`).
      Since:
        1.2

    - #### setStyle

          public void setStyle(ChartStyle style)

      Sets (and applies) the specified chart style.
      Parameters:
        `style` - the chart style (`null` not permitted).
      Since:
        1.2

    - #### draw

          public RenderingInfo draw(java.awt.Graphics2D g2,
                                    java.awt.geom.Rectangle2D bounds)

      Draws the chart to the specified output target.
      Specified by:
        `draw` in interface `Drawable3D`
      Parameters:
        `g2` - the output target (`null` not permitted).
        `bounds` - the bounds (`null` not permitted).
      Returns:
        Information about the items rendered.

    - #### receive

          public void receive(ChartElementVisitor visitor)

      Receives a visitor. The visitor is first directed to the plot, then the visit is completed for the chart.
      Specified by:
        `receive` in interface `ChartElement`
      Parameters:
        `visitor` - the visitor.
      Since:
        1.2

    - #### equals

          public boolean equals(java.lang.Object obj)

      Tests this chart for equality with an arbitrary object.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the object (`null` not permitted).
      Returns:
        A boolean.

    - #### plotChanged

          public void plotChanged(Plot3DChangeEvent event)

      Receives notification of a plot change event, refreshes the 3D model (world) and passes the event on, wrapped in a `Chart3DChangeEvent`, to all registered listeners.
      Specified by:
        `plotChanged` in interface `Plot3DChangeListener`
      Parameters:
        `event` - the plot change event.

    - #### styleChanged

          public void styleChanged(ChartStyleChangeEvent event)

      Description copied from interface: `ChartStyleChangeListener`
      Called to inform that a chart change event has occurred.
      Specified by:
        `styleChanged` in interface `ChartStyleChangeListener`
      Parameters:
        `event` - the event.

    - #### addChangeListener

          public void addChangeListener(Chart3DChangeListener listener)

      Registers a listener to receive notification of changes to the chart.
      Parameters:
        `listener` - the listener (`null` not permitted).

    - #### removeChangeListener

          public void removeChangeListener(Chart3DChangeListener listener)

      Deregisters a listener so that it no longer receives notification of changes to the chart.
      Parameters:
        `listener` - the listener (`null` not permitted).

    - #### notifyListeners

          public void notifyListeners(Chart3DChangeEvent event)

      Notifies all registered listeners that the chart has been modified.
      Parameters:
        `event` - information about the change event.

    - #### isNotify

          public boolean isNotify()

      Returns a flag that controls whether or not change events are sent to registered listeners.
      Returns:
        A boolean.
      See Also:
        `setNotify(boolean)`

    - #### setNotify

          public void setNotify(boolean notify)

      Sets a flag that controls whether or not listeners receive `Chart3DChangeEvent` notifications.
      Parameters:
        `notify` - a boolean.
      See Also:
        `isNotify()`

    - #### fireChangeEvent

          protected void fireChangeEvent()

      Sends a `Chart3DChangeEvent` to all registered listeners.

    - #### renderedElementToString

          public static java.lang.String renderedElementToString(RenderedElement element)

      Returns a string representing the `element`, primarily for debugging purposes.
      Parameters:
        `element` - the element (`null` not permitted).
      Returns:
        A string (never `null`).