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:

  • Field Details

  • 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:

    • 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

      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:

    • 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

      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:

    • 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

      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:

    • 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

      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:

    • getLegendAnchor

      public Anchor2D getLegendAnchor()
      Returns the legend anchor.
      Returns:
      The legend anchor (never null).
      See Also:

    • 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:

    • 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

      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:

    • 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

      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:

    • 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

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

    • 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).