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

# Class Chart3D

java.lang.Object
org.jfree.chart3d.Chart3D

All Implemented Interfaces:
  `Serializable`, `EventListener`, `ChartElement`, `Drawable3D`, `Plot3DChangeListener`, `ChartStyleChangeListener`

public class Chart3D extends Object implements Drawable3D, ChartElement, Plot3DChangeListener, ChartStyleChangeListener, 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
Description
`static final double`
`DEFAULT_PROJ_DIST`
The default projection distance.
`static final String`
`INTERACTIVE_ELEMENT_TYPE`
The key for a property that stores the interactive element type.
`static final String`
`SERIES_KEY`
The key for a property that stores the series key.

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`void`
`addChangeListener(Chart3DChangeListener listener)`
Registers a listener to receive notification of changes to the chart.
`RenderingInfo`
`draw(Graphics2D g2, Rectangle2D bounds)`
Draws the chart to the specified output target.
`boolean`
`equals(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).
`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.
`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.
`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 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(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(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(RenderingHints hints)`
Sets the rendering hints for the chart.
`void`
`setStyle(ChartStyle style)`
Sets (and applies) the specified chart style.
`void`
`setTitle(String title)`
Sets the chart title and sends a `Chart3DChangeEvent` to all registered listeners.
`void`
`setTitle(String title, Font font, 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 Details

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

### Chart3D

public Chart3D(String title, 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(String title, 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 Details

### getID

public String getID()
Returns the chart id.

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

### setID

public void setID(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(org.jfree.chart3d.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(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(String title, Font font, 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(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 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(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(org.jfree.chart3d.legend.LegendBuilder)`
  - `setLegendAnchor(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(Anchor2D)`

### getLegendAnchor

public Anchor2D getLegendAnchor()
Returns the legend anchor.

Returns:
  The legend anchor (never `null`).
See Also:
  - `setLegendAnchor(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(Anchor2D)` and `setLegendOrientation(Orientation)` methods.

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

### getRenderingHints

public 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(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(Graphics2D g2, 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(Object obj)
Tests this chart for equality with an arbitrary object.

Overrides:
  `equals` in class `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 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`).