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
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
Charts can have simple titles or composite titles (anything that can be constructed as a
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.
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:
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
addChangeListener
(Chart3DChangeListener listener) Registers a listener to receive notification of changes to the chart.draw
(Graphics2D g2, Rectangle2D bounds) Draws the chart to the specified output target.boolean
Tests this chart for equality with an arbitrary object.protected void
Sends aChart3DChangeEvent
to all registered listeners.boolean
Returns a flag that indicates whether or not anti-aliasing is used when the chart is drawn.Returns the background painter (an object that is responsible for filling the background area before charts are rendered).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).Returns the dimensions of the 3D object.boolean
Returns the flag that controls whether or not element hints will be added to theGraphics2D
output when the chart is rendered.getID()
Returns the chart id.Returns the legend anchor.Returns the legend builder.Returns the orientation for the legend.getPlot()
Returns the plot, which manages the dataset, the axes (if any), the renderer (if any) and other attributes related to plotting data.double
Returns the projection distance.Returns the collection of rendering hints for the chart.getStyle()
Returns the chart style.getTitle()
Returns the chart title.Returns the title anchor.Sets the offset in 2D-space for the rendering of the chart.Returns the view point.boolean
isNotify()
Returns a flag that controls whether or not change events are sent to registered listeners.void
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 aChart3DChangeEvent
, 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 theelement
, 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 aChart3DChangeEvent
to all registered listeners.void
setChartBoxColor
(Color color) Sets the chart box color and sends aChart3DChangeEvent
to all registered listeners.void
setElementHinting
(boolean hinting) Sets the flag that controls whether or not element hints will be added to theGraphics2D
output when the chart is rendered and sends a change event to all registered listeners.void
Sets the chart id.void
setLegendAnchor
(Anchor2D anchor) Sets the legend anchor and sends aChart3DChangeEvent
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 aChart3DChangeEvent
to all registered listeners.void
setLegendPosition
(Anchor2D anchor, Orientation orientation) Sets the legend position (both the anchor point and the orientation) and sends aChart3DChangeEvent
to all registered listeners.void
setNotify
(boolean notify) Sets a flag that controls whether or not listeners receiveChart3DChangeEvent
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
Sets the chart title and sends aChart3DChangeEvent
to all registered listeners.void
Sets the chart title and sends aChart3DChangeEvent
to all registered listeners.void
setTitle
(TableElement title) Sets the chart title and sends aChart3DChangeEvent
to all registered listeners.void
setTitleAnchor
(Anchor2D anchor) Sets the title anchor and sends aChart3DChangeEvent
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
Called to inform that a chart change event has occurred.
-
Field Details
-
DEFAULT_PROJ_DIST
The default projection distance.- Since:
- 1.2
- See Also:
-
INTERACTIVE_ELEMENT_TYPE
The key for a property that stores the interactive element type.- Since:
- 1.3
- See Also:
-
SERIES_KEY
The key for a property that stores the series key. This is used to store the series key on theTableElement
representing a legend item, and also on a correspondingRenderedElement
after chart rendering (in theRenderingInfo
).- Since:
- 1.3
- See Also:
-
-
Constructor Details
-
Chart3D
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:
-
Chart3D
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
Returns the chart id.- Returns:
- The chart id (possibly
null
). - Since:
- 1.3
-
setID
Sets the chart id.- Parameters:
id
- the id (null
permitted).- Since:
- 1.3
-
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 ofStandardRectanglePainter
that paints the background white.- Returns:
- The background painter (possibly
null
). - See Also:
-
setBackground
Sets the background painter and sends aChart3DChangeEvent
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 useStandardRectanglePainter
. To fill the background with a gradient paint, useGradientRectanglePainter
.- Parameters:
background
- the background painter (null
permitted).- See Also:
-
getTitle
Returns the chart title. ATableElement
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
Sets the chart title and sends aChart3DChangeEvent
to all registered listeners. This is a convenience method that constructs the requiredTableElement
under-the-hood.- Parameters:
title
- the title (null
permitted).
-
setTitle
Sets the chart title and sends aChart3DChangeEvent
to all registered listeners. This is a convenience method that constructs the requiredTableElement
under-the-hood.- Parameters:
title
- the title (null
not permitted).font
- the font (null
not permitted).color
- the foreground color (null
not permitted).
-
setTitle
Sets the chart title and sends aChart3DChangeEvent
to all registered listeners. You can set the title tonull
, in which case there will be no chart title.- Parameters:
title
- the title (null
permitted).
-
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
Sets the title anchor and sends aChart3DChangeEvent
to all registered listeners. There is aTitleAnchor
class providing some useful default anchors.- Parameters:
anchor
- the anchor (null
not permitted).- See Also:
-
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
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 isColor.WHITE
.- Returns:
- The chart box color (never
null
). - See Also:
-
setChartBoxColor
Sets the chart box color and sends aChart3DChangeEvent
to all registered listeners. Bear in mind thatPiePlot3D
does not display a chart box, so this attribute will be ignored for pie charts.- Parameters:
color
- the color (null
not permitted).- See Also:
-
getDimensions
Returns the dimensions of the 3D object.- Specified by:
getDimensions
in interfaceDrawable3D
- Returns:
- The dimensions (never
null
).
-
getViewPoint
Returns the view point.- Specified by:
getViewPoint
in interfaceDrawable3D
- Returns:
- The view point (never
null
).
-
setViewPoint
Sets the view point.- Specified by:
setViewPoint
in interfaceDrawable3D
- Parameters:
viewPoint
- the view point (null
not permitted).
-
getProjDistance
Returns the projection distance. The default value isDEFAULT_PROJ_DIST
, higher numbers flatten out the perspective and reduce distortion in the projected image.- Specified by:
getProjDistance
in interfaceDrawable3D
- Returns:
- The projection distance.
- Since:
- 1.2
-
setProjDistance
Sets the projection distance and sends a change event to all registered listeners.- Specified by:
setProjDistance
in interfaceDrawable3D
- Parameters:
dist
- the distance.- Since:
- 1.2
-
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 interfaceDrawable3D
- Returns:
- The offset (never
null
).
-
setTranslate2D
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 interfaceDrawable3D
- Parameters:
offset
- the new offset (null
not permitted).
-
getLegendBuilder
Returns the legend builder. The default value is an instance ofStandardLegendBuilder
. If the legend builder isnull
, no legend will be displayed for the chart.- Returns:
- The legend builder (possibly
null
). - See Also:
-
setLegendBuilder
Sets the legend builder and sends a change event to all registered listeners. When the legend builder isnull
, no legend will be displayed on the chart.- Parameters:
legendBuilder
- the legend builder (null
permitted).- See Also:
-
getLegendAnchor
Returns the legend anchor.- Returns:
- The legend anchor (never
null
). - See Also:
-
setLegendAnchor
Sets the legend anchor and sends aChart3DChangeEvent
to all registered listeners. There is aLegendAnchor
class providing some useful default anchors.- Parameters:
anchor
- the anchor (null
not permitted).- See Also:
-
getLegendOrientation
Returns the orientation for the legend.- Returns:
- The orientation (never
null
). - Since:
- 1.1
-
setLegendOrientation
Sets the legend orientation and sends aChart3DChangeEvent
to all registered listeners.- Parameters:
orientation
- the orientation (null
not permitted).- Since:
- 1.1
-
setLegendPosition
Sets the legend position (both the anchor point and the orientation) and sends aChart3DChangeEvent
to all registered listeners. This is a convenience method that calls both thesetLegendAnchor(Anchor2D)
andsetLegendOrientation(Orientation)
methods.- Parameters:
anchor
- the anchor (null
not permitted).orientation
- the orientation (null
not permitted).- Since:
- 1.1
-
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
Sets the rendering hints for the chart. These will be added (using theGraphics2D.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 usegetRenderingHints().put(key, value)
.- Parameters:
hints
- the rendering hints (null
not permitted).- Since:
- 1.1
- See Also:
-
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
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:
-
getElementHinting
Returns the flag that controls whether or not element hints will be added to theGraphics2D
output when the chart is rendered. The default value isfalse
.- Returns:
- A boolean.
- Since:
- 1.3
-
setElementHinting
Sets the flag that controls whether or not element hints will be added to theGraphics2D
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
Returns the chart style.- Returns:
- The chart style (never
null
). - Since:
- 1.2
-
setStyle
Sets (and applies) the specified chart style.- Parameters:
style
- the chart style (null
not permitted).- Since:
- 1.2
-
draw
Draws the chart to the specified output target.- Specified by:
draw
in interfaceDrawable3D
- Parameters:
g2
- the output target (null
not permitted).bounds
- the bounds (null
not permitted).- Returns:
- Information about the items rendered.
-
receive
Receives a visitor. The visitor is first directed to the plot, then the visit is completed for the chart.- Specified by:
receive
in interfaceChartElement
- Parameters:
visitor
- the visitor.- Since:
- 1.2
-
equals
Tests this chart for equality with an arbitrary object. -
plotChanged
Receives notification of a plot change event, refreshes the 3D model (world) and passes the event on, wrapped in aChart3DChangeEvent
, to all registered listeners.- Specified by:
plotChanged
in interfacePlot3DChangeListener
- Parameters:
event
- the plot change event.
-
styleChanged
Description copied from interface:ChartStyleChangeListener
Called to inform that a chart change event has occurred.- Specified by:
styleChanged
in interfaceChartStyleChangeListener
- Parameters:
event
- the event.
-
addChangeListener
Registers a listener to receive notification of changes to the chart.- Parameters:
listener
- the listener (null
not permitted).
-
removeChangeListener
Deregisters a listener so that it no longer receives notification of changes to the chart.- Parameters:
listener
- the listener (null
not permitted).
-
notifyListeners
Notifies all registered listeners that the chart has been modified.- Parameters:
event
- information about the change event.
-
isNotify
Returns a flag that controls whether or not change events are sent to registered listeners.- Returns:
- A boolean.
- See Also:
-
setNotify
Sets a flag that controls whether or not listeners receiveChart3DChangeEvent
notifications.- Parameters:
notify
- a boolean.- See Also:
-
fireChangeEvent
Sends aChart3DChangeEvent
to all registered listeners. -
renderedElementToString
Returns a string representing theelement
, primarily for debugging purposes.- Parameters:
element
- the element (null
not permitted).- Returns:
- A string (never
null
).
-