001    /* ===========================================================
002     * JFreeChart : a free chart library for the Java(tm) platform
003     * ===========================================================
004     *
005     * (C) Copyright 2000-2011, by Object Refinery Limited and Contributors.
006     *
007     * Project Info:  http://www.jfree.org/jfreechart/index.html
008     *
009     * This library is free software; you can redistribute it and/or modify it
010     * under the terms of the GNU Lesser General Public License as published by
011     * the Free Software Foundation; either version 2.1 of the License, or
012     * (at your option) any later version.
013     *
014     * This library is distributed in the hope that it will be useful, but
015     * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016     * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017     * License for more details.
018     *
019     * You should have received a copy of the GNU Lesser General Public
020     * License along with this library; if not, write to the Free Software
021     * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022     * USA.
023     *
024     * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025     * Other names may be trademarks of their respective owners.]
026     *
027     * ---------------
028     * JFreeChart.java
029     * ---------------
030     * (C) Copyright 2000-2009, by Object Refinery Limited and Contributors.
031     *
032     * Original Author:  David Gilbert (for Object Refinery Limited);
033     * Contributor(s):   Andrzej Porebski;
034     *                   David Li;
035     *                   Wolfgang Irler;
036     *                   Christian W. Zuckschwerdt;
037     *                   Klaus Rheinwald;
038     *                   Nicolas Brodu;
039     *                   Peter Kolb (patch 2603321);
040     *
041     * NOTE: The above list of contributors lists only the people that have
042     * contributed to this source file (JFreeChart.java) - for a list of ALL
043     * contributors to the project, please see the README.txt file.
044     *
045     * Changes (from 20-Jun-2001)
046     * --------------------------
047     * 20-Jun-2001 : Modifications submitted by Andrzej Porebski for legend
048     *               placement;
049     * 21-Jun-2001 : Removed JFreeChart parameter from Plot constructors (DG);
050     * 22-Jun-2001 : Multiple titles added (original code by David Berry, with
051     *               reworkings by DG);
052     * 18-Sep-2001 : Updated header (DG);
053     * 15-Oct-2001 : Moved data source classes into new package
054     *               com.jrefinery.data.* (DG);
055     * 18-Oct-2001 : New factory method for creating VerticalXYBarChart (DG);
056     * 19-Oct-2001 : Moved series paint and stroke methods to the Plot class (DG);
057     *               Moved static chart creation methods to new ChartFactory
058     *               class (DG);
059     * 22-Oct-2001 : Renamed DataSource.java --> Dataset.java etc. (DG);
060     *               Fixed bug where chart isn't registered with the dataset (DG);
061     * 07-Nov-2001 : Fixed bug where null title in constructor causes
062     *               exception (DG);
063     *               Tidied up event notification code (DG);
064     * 17-Nov-2001 : Added getLegendItemCount() method (DG);
065     * 21-Nov-2001 : Set clipping in draw method to ensure that nothing gets drawn
066     *               outside the chart area (DG);
067     * 11-Dec-2001 : Added the createBufferedImage() method, taken from the
068     *               JFreeChartServletDemo class (DG);
069     * 13-Dec-2001 : Added tooltips (DG);
070     * 16-Jan-2002 : Added handleClick() method (DG);
071     * 22-Jan-2002 : Fixed bug correlating legend labels with pie data (DG);
072     * 05-Feb-2002 : Removed redundant tooltips code (DG);
073     * 19-Feb-2002 : Added accessor methods for the backgroundImage and
074     *               backgroundImageAlpha attributes (DG);
075     * 21-Feb-2002 : Added static fields for INFO, COPYRIGHT, LICENCE, CONTRIBUTORS
076     *               and LIBRARIES.  These can be used to display information about
077     *               JFreeChart (DG);
078     * 06-Mar-2002 : Moved constants to JFreeChartConstants interface (DG);
079     * 18-Apr-2002 : PieDataset is no longer sorted (oldman);
080     * 23-Apr-2002 : Moved dataset to the Plot class (DG);
081     * 13-Jun-2002 : Added an extra draw() method (DG);
082     * 25-Jun-2002 : Implemented the Drawable interface and removed redundant
083     *               imports (DG);
084     * 26-Jun-2002 : Added another createBufferedImage() method (DG);
085     * 18-Sep-2002 : Fixed issues reported by Checkstyle (DG);
086     * 23-Sep-2002 : Added new contributor (DG);
087     * 28-Oct-2002 : Created main title and subtitle list to replace existing title
088     *               list (DG);
089     * 08-Jan-2003 : Added contributor (DG);
090     * 17-Jan-2003 : Added new constructor (DG);
091     * 22-Jan-2003 : Added ChartColor class by Cameron Riley, and background image
092     *               alignment code by Christian W. Zuckschwerdt (DG);
093     * 11-Feb-2003 : Added flag to allow suppression of chart change events, based
094     *               on a suggestion by Klaus Rheinwald (DG);
095     * 04-Mar-2003 : Added small fix for suppressed chart change events (see bug id
096     *               690865) (DG);
097     * 10-Mar-2003 : Added Benoit Xhenseval to contributors (DG);
098     * 26-Mar-2003 : Implemented Serializable (DG);
099     * 15-Jul-2003 : Added an optional border for the chart (DG);
100     * 11-Sep-2003 : Took care of listeners while cloning (NB);
101     * 16-Sep-2003 : Changed ChartRenderingInfo --> PlotRenderingInfo (DG);
102     * 22-Sep-2003 : Added nullpointer checks.
103     * 25-Sep-2003 : Added nullpointer checks too (NB).
104     * 03-Dec-2003 : Legends are now registered by this class instead of using the
105     *               old constructor way (TM);
106     * 03-Dec-2003 : Added anchorPoint to draw() method (DG);
107     * 08-Jan-2004 : Reworked title code, introducing line wrapping (DG);
108     * 09-Feb-2004 : Created additional createBufferedImage() method (DG);
109     * 05-Apr-2004 : Added new createBufferedImage() method (DG);
110     * 27-May-2004 : Moved constants from JFreeChartConstants.java back to this
111     *               class (DG);
112     * 25-Nov-2004 : Updates for changes to Title class (DG);
113     * 06-Jan-2005 : Change lookup for default background color (DG);
114     * 31-Jan-2005 : Added Don Elliott to contributors (DG);
115     * 02-Feb-2005 : Added clearSubtitles() method (DG);
116     * 03-Feb-2005 : Added Mofeed Shahin to contributors (DG);
117     * 08-Feb-2005 : Updated for RectangleConstraint changes (DG);
118     * 28-Mar-2005 : Renamed Legend --> OldLegend (DG);
119     * 12-Apr-2005 : Added methods to access legend(s) in subtitle list (DG);
120     * 13-Apr-2005 : Added removeLegend() and removeSubtitle() methods (DG);
121     * 20-Apr-2005 : Modified to collect chart entities from titles and
122     *               subtitles (DG);
123     * 26-Apr-2005 : Removed LOGGER (DG);
124     * 06-Jun-2005 : Added addLegend() method and padding attribute, fixed equals()
125     *               method (DG);
126     * 24-Nov-2005 : Removed OldLegend and related code - don't want to support
127     *               this in 1.0.0 final (DG);
128     * ------------- JFREECHART 1.0.x ---------------------------------------------
129     * 27-Jan-2006 : Updated version number (DG);
130     * 07-Dec-2006 : Added some missing credits (DG);
131     * 17-Jan-2007 : Added Darren Jung to contributor list (DG);
132     * 05-Mar-2007 : Added Sergei Ivanov to the contributor list (DG);
133     * 16-Mar-2007 : Modified initial legend border (DG);
134     * 22-Mar-2007 : New methods for text anti-aliasing (DG);
135     * 16-May-2007 : Fixed argument check in getSubtitle(), copy list in
136     *               get/setSubtitles(), and added new addSubtitle(int, Title)
137     *               method (DG);
138     * 05-Jun-2007 : Add change listener to default legend (DG);
139     * 04-Dec-2007 : In createBufferedImage() methods, make the default image type
140     *               BufferedImage.TYPE_INT_ARGB (thanks to Klaus Rheinwald) (DG);
141     * 05-Dec-2007 : Fixed bug 1749124 (not registering as listener with
142     *               TextTitle) (DG);
143     * 23-Apr-2008 : Added new contributor (Diego Pierangeli) (DG);
144     * 16-May-2008 : Added new contributor (Michael Siemer) (DG);
145     * 19-Sep-2008 : Check for title visibility (DG);
146     * 18-Dec-2008 : Use ResourceBundleWrapper - see patch 1607918 by
147     *               Jess Thrysoee (DG);
148     * 19-Mar-2009 : Added entity support - see patch 2603321 by Peter Kolb (DG);
149     * 19-May-2009 : Fixed FindBugs warnings, patch by Michal Wozniak (DG);
150     * 29-Jun-2009 : Check visibility flag in main title (DG);
151     *
152     */
153    
154    package org.jfree.chart;
155    
156    import java.awt.AlphaComposite;
157    import java.awt.BasicStroke;
158    import java.awt.Color;
159    import java.awt.Composite;
160    import java.awt.Font;
161    import java.awt.Graphics2D;
162    import java.awt.Image;
163    import java.awt.Paint;
164    import java.awt.RenderingHints;
165    import java.awt.Shape;
166    import java.awt.Stroke;
167    import java.awt.geom.AffineTransform;
168    import java.awt.geom.Point2D;
169    import java.awt.geom.Rectangle2D;
170    import java.awt.image.BufferedImage;
171    import java.io.IOException;
172    import java.io.ObjectInputStream;
173    import java.io.ObjectOutputStream;
174    import java.io.Serializable;
175    import java.net.URL;
176    import java.util.ArrayList;
177    import java.util.Arrays;
178    import java.util.Iterator;
179    import java.util.List;
180    import java.util.ResourceBundle;
181    
182    import javax.swing.ImageIcon;
183    import javax.swing.UIManager;
184    import javax.swing.event.EventListenerList;
185    
186    import org.jfree.JCommon;
187    import org.jfree.chart.block.BlockParams;
188    import org.jfree.chart.block.EntityBlockResult;
189    import org.jfree.chart.block.LengthConstraintType;
190    import org.jfree.chart.block.LineBorder;
191    import org.jfree.chart.block.RectangleConstraint;
192    import org.jfree.chart.entity.EntityCollection;
193    import org.jfree.chart.entity.JFreeChartEntity;
194    import org.jfree.chart.event.ChartChangeEvent;
195    import org.jfree.chart.event.ChartChangeListener;
196    import org.jfree.chart.event.ChartProgressEvent;
197    import org.jfree.chart.event.ChartProgressListener;
198    import org.jfree.chart.event.PlotChangeEvent;
199    import org.jfree.chart.event.PlotChangeListener;
200    import org.jfree.chart.event.TitleChangeEvent;
201    import org.jfree.chart.event.TitleChangeListener;
202    import org.jfree.chart.plot.CategoryPlot;
203    import org.jfree.chart.plot.Plot;
204    import org.jfree.chart.plot.PlotRenderingInfo;
205    import org.jfree.chart.plot.XYPlot;
206    import org.jfree.chart.title.LegendTitle;
207    import org.jfree.chart.title.TextTitle;
208    import org.jfree.chart.title.Title;
209    import org.jfree.chart.util.ResourceBundleWrapper;
210    import org.jfree.data.Range;
211    import org.jfree.io.SerialUtilities;
212    import org.jfree.ui.Align;
213    import org.jfree.ui.Drawable;
214    import org.jfree.ui.HorizontalAlignment;
215    import org.jfree.ui.RectangleEdge;
216    import org.jfree.ui.RectangleInsets;
217    import org.jfree.ui.Size2D;
218    import org.jfree.ui.VerticalAlignment;
219    import org.jfree.ui.about.Contributor;
220    import org.jfree.ui.about.Licences;
221    import org.jfree.ui.about.ProjectInfo;
222    import org.jfree.util.ObjectUtilities;
223    import org.jfree.util.PaintUtilities;
224    
225    /**
226     * A chart class implemented using the Java 2D APIs.  The current version
227     * supports bar charts, line charts, pie charts and xy plots (including time
228     * series data).
229     * <P>
230     * JFreeChart coordinates several objects to achieve its aim of being able to
231     * draw a chart on a Java 2D graphics device: a list of {@link Title} objects
232     * (which often includes the chart's legend), a {@link Plot} and a
233     * {@link org.jfree.data.general.Dataset} (the plot in turn manages a
234     * domain axis and a range axis).
235     * <P>
236     * You should use a {@link ChartPanel} to display a chart in a GUI.
237     * <P>
238     * The {@link ChartFactory} class contains static methods for creating
239     * 'ready-made' charts.
240     *
241     * @see ChartPanel
242     * @see ChartFactory
243     * @see Title
244     * @see Plot
245     */
246    public class JFreeChart implements Drawable,
247                                       TitleChangeListener,
248                                       PlotChangeListener,
249                                       Serializable,
250                                       Cloneable {
251    
252        /** For serialization. */
253        private static final long serialVersionUID = -3470703747817429120L;
254    
255        /** Information about the project. */
256        public static final ProjectInfo INFO = new JFreeChartInfo();
257    
258        /** The default font for titles. */
259        public static final Font DEFAULT_TITLE_FONT
260                = new Font("SansSerif", Font.BOLD, 18);
261    
262        /** The default background color. */
263        public static final Paint DEFAULT_BACKGROUND_PAINT
264                = UIManager.getColor("Panel.background");
265    
266        /** The default background image. */
267        public static final Image DEFAULT_BACKGROUND_IMAGE = null;
268    
269        /** The default background image alignment. */
270        public static final int DEFAULT_BACKGROUND_IMAGE_ALIGNMENT = Align.FIT;
271    
272        /** The default background image alpha. */
273        public static final float DEFAULT_BACKGROUND_IMAGE_ALPHA = 0.5f;
274    
275        /**
276         * Rendering hints that will be used for chart drawing.  This should never
277         * be <code>null</code>.
278         */
279        private transient RenderingHints renderingHints;
280    
281        /** A flag that controls whether or not the chart border is drawn. */
282        private boolean borderVisible;
283    
284        /** The stroke used to draw the chart border (if visible). */
285        private transient Stroke borderStroke;
286    
287        /** The paint used to draw the chart border (if visible). */
288        private transient Paint borderPaint;
289    
290        /** The padding between the chart border and the chart drawing area. */
291        private RectangleInsets padding;
292    
293        /** The chart title (optional). */
294        private TextTitle title;
295    
296        /**
297         * The chart subtitles (zero, one or many).  This field should never be
298         * <code>null</code>.
299         */
300        private List subtitles;
301    
302        /** Draws the visual representation of the data. */
303        private Plot plot;
304    
305        /** Paint used to draw the background of the chart. */
306        private transient Paint backgroundPaint;
307    
308        /** An optional background image for the chart. */
309        private transient Image backgroundImage;  // todo: not serialized yet
310    
311        /** The alignment for the background image. */
312        private int backgroundImageAlignment = Align.FIT;
313    
314        /** The alpha transparency for the background image. */
315        private float backgroundImageAlpha = 0.5f;
316    
317        /** Storage for registered change listeners. */
318        private transient EventListenerList changeListeners;
319    
320        /** Storage for registered progress listeners. */
321        private transient EventListenerList progressListeners;
322    
323        /**
324         * A flag that can be used to enable/disable notification of chart change
325         * events.
326         */
327        private boolean notify;
328    
329        /**
330         * Creates a new chart based on the supplied plot.  The chart will have
331         * a legend added automatically, but no title (although you can easily add
332         * one later).
333         * <br><br>
334         * Note that the  {@link ChartFactory} class contains a range
335         * of static methods that will return ready-made charts, and often this
336         * is a more convenient way to create charts than using this constructor.
337         *
338         * @param plot  the plot (<code>null</code> not permitted).
339         */
340        public JFreeChart(Plot plot) {
341            this(null, null, plot, true);
342        }
343    
344        /**
345         * Creates a new chart with the given title and plot.  A default font
346         * ({@link #DEFAULT_TITLE_FONT}) is used for the title, and the chart will
347         * have a legend added automatically.
348         * <br><br>
349         * Note that the {@link ChartFactory} class contains a range
350         * of static methods that will return ready-made charts, and often this
351         * is a more convenient way to create charts than using this constructor.
352         *
353         * @param title  the chart title (<code>null</code> permitted).
354         * @param plot  the plot (<code>null</code> not permitted).
355         */
356        public JFreeChart(String title, Plot plot) {
357            this(title, JFreeChart.DEFAULT_TITLE_FONT, plot, true);
358        }
359    
360        /**
361         * Creates a new chart with the given title and plot.  The
362         * <code>createLegend</code> argument specifies whether or not a legend
363         * should be added to the chart.
364         * <br><br>
365         * Note that the  {@link ChartFactory} class contains a range
366         * of static methods that will return ready-made charts, and often this
367         * is a more convenient way to create charts than using this constructor.
368         *
369         * @param title  the chart title (<code>null</code> permitted).
370         * @param titleFont  the font for displaying the chart title
371         *                   (<code>null</code> permitted).
372         * @param plot  controller of the visual representation of the data
373         *              (<code>null</code> not permitted).
374         * @param createLegend  a flag indicating whether or not a legend should
375         *                      be created for the chart.
376         */
377        public JFreeChart(String title, Font titleFont, Plot plot,
378                          boolean createLegend) {
379    
380            if (plot == null) {
381                throw new NullPointerException("Null 'plot' argument.");
382            }
383    
384            // create storage for listeners...
385            this.progressListeners = new EventListenerList();
386            this.changeListeners = new EventListenerList();
387            this.notify = true;  // default is to notify listeners when the
388                                 // chart changes
389    
390            this.renderingHints = new RenderingHints(
391                    RenderingHints.KEY_ANTIALIASING,
392                    RenderingHints.VALUE_ANTIALIAS_ON);
393    
394            this.borderVisible = false;
395            this.borderStroke = new BasicStroke(1.0f);
396            this.borderPaint = Color.black;
397    
398            this.padding = RectangleInsets.ZERO_INSETS;
399    
400            this.plot = plot;
401            plot.addChangeListener(this);
402    
403            this.subtitles = new ArrayList();
404    
405            // create a legend, if requested...
406            if (createLegend) {
407                LegendTitle legend = new LegendTitle(this.plot);
408                legend.setMargin(new RectangleInsets(1.0, 1.0, 1.0, 1.0));
409                legend.setFrame(new LineBorder());
410                legend.setBackgroundPaint(Color.white);
411                legend.setPosition(RectangleEdge.BOTTOM);
412                this.subtitles.add(legend);
413                legend.addChangeListener(this);
414            }
415    
416            // add the chart title, if one has been specified...
417            if (title != null) {
418                if (titleFont == null) {
419                    titleFont = DEFAULT_TITLE_FONT;
420                }
421                this.title = new TextTitle(title, titleFont);
422                this.title.addChangeListener(this);
423            }
424    
425            this.backgroundPaint = DEFAULT_BACKGROUND_PAINT;
426    
427            this.backgroundImage = DEFAULT_BACKGROUND_IMAGE;
428            this.backgroundImageAlignment = DEFAULT_BACKGROUND_IMAGE_ALIGNMENT;
429            this.backgroundImageAlpha = DEFAULT_BACKGROUND_IMAGE_ALPHA;
430    
431        }
432    
433        /**
434         * Returns the collection of rendering hints for the chart.
435         *
436         * @return The rendering hints for the chart (never <code>null</code>).
437         *
438         * @see #setRenderingHints(RenderingHints)
439         */
440        public RenderingHints getRenderingHints() {
441            return this.renderingHints;
442        }
443    
444        /**
445         * Sets the rendering hints for the chart.  These will be added (using the
446         * Graphics2D.addRenderingHints() method) near the start of the
447         * JFreeChart.draw() method.
448         *
449         * @param renderingHints  the rendering hints (<code>null</code> not
450         *                        permitted).
451         *
452         * @see #getRenderingHints()
453         */
454        public void setRenderingHints(RenderingHints renderingHints) {
455            if (renderingHints == null) {
456                throw new NullPointerException("RenderingHints given are null");
457            }
458            this.renderingHints = renderingHints;
459            fireChartChanged();
460        }
461    
462        /**
463         * Returns a flag that controls whether or not a border is drawn around the
464         * outside of the chart.
465         *
466         * @return A boolean.
467         *
468         * @see #setBorderVisible(boolean)
469         */
470        public boolean isBorderVisible() {
471            return this.borderVisible;
472        }
473    
474        /**
475         * Sets a flag that controls whether or not a border is drawn around the
476         * outside of the chart.
477         *
478         * @param visible  the flag.
479         *
480         * @see #isBorderVisible()
481         */
482        public void setBorderVisible(boolean visible) {
483            this.borderVisible = visible;
484            fireChartChanged();
485        }
486    
487        /**
488         * Returns the stroke used to draw the chart border (if visible).
489         *
490         * @return The border stroke.
491         *
492         * @see #setBorderStroke(Stroke)
493         */
494        public Stroke getBorderStroke() {
495            return this.borderStroke;
496        }
497    
498        /**
499         * Sets the stroke used to draw the chart border (if visible).
500         *
501         * @param stroke  the stroke.
502         *
503         * @see #getBorderStroke()
504         */
505        public void setBorderStroke(Stroke stroke) {
506            this.borderStroke = stroke;
507            fireChartChanged();
508        }
509    
510        /**
511         * Returns the paint used to draw the chart border (if visible).
512         *
513         * @return The border paint.
514         *
515         * @see #setBorderPaint(Paint)
516         */
517        public Paint getBorderPaint() {
518            return this.borderPaint;
519        }
520    
521        /**
522         * Sets the paint used to draw the chart border (if visible).
523         *
524         * @param paint  the paint.
525         *
526         * @see #getBorderPaint()
527         */
528        public void setBorderPaint(Paint paint) {
529            this.borderPaint = paint;
530            fireChartChanged();
531        }
532    
533        /**
534         * Returns the padding between the chart border and the chart drawing area.
535         *
536         * @return The padding (never <code>null</code>).
537         *
538         * @see #setPadding(RectangleInsets)
539         */
540        public RectangleInsets getPadding() {
541            return this.padding;
542        }
543    
544        /**
545         * Sets the padding between the chart border and the chart drawing area,
546         * and sends a {@link ChartChangeEvent} to all registered listeners.
547         *
548         * @param padding  the padding (<code>null</code> not permitted).
549         *
550         * @see #getPadding()
551         */
552        public void setPadding(RectangleInsets padding) {
553            if (padding == null) {
554                throw new IllegalArgumentException("Null 'padding' argument.");
555            }
556            this.padding = padding;
557            notifyListeners(new ChartChangeEvent(this));
558        }
559    
560        /**
561         * Returns the main chart title.  Very often a chart will have just one
562         * title, so we make this case simple by providing accessor methods for
563         * the main title.  However, multiple titles are supported - see the
564         * {@link #addSubtitle(Title)} method.
565         *
566         * @return The chart title (possibly <code>null</code>).
567         *
568         * @see #setTitle(TextTitle)
569         */
570        public TextTitle getTitle() {
571            return this.title;
572        }
573    
574        /**
575         * Sets the main title for the chart and sends a {@link ChartChangeEvent}
576         * to all registered listeners.  If you do not want a title for the
577         * chart, set it to <code>null</code>.  If you want more than one title on
578         * a chart, use the {@link #addSubtitle(Title)} method.
579         *
580         * @param title  the title (<code>null</code> permitted).
581         *
582         * @see #getTitle()
583         */
584        public void setTitle(TextTitle title) {
585            if (this.title != null) {
586                this.title.removeChangeListener(this);
587            }
588            this.title = title;
589            if (title != null) {
590                title.addChangeListener(this);
591            }
592            fireChartChanged();
593        }
594    
595        /**
596         * Sets the chart title and sends a {@link ChartChangeEvent} to all
597         * registered listeners.  This is a convenience method that ends up calling
598         * the {@link #setTitle(TextTitle)} method.  If there is an existing title,
599         * its text is updated, otherwise a new title using the default font is
600         * added to the chart.  If <code>text</code> is <code>null</code> the chart
601         * title is set to <code>null</code>.
602         *
603         * @param text  the title text (<code>null</code> permitted).
604         *
605         * @see #getTitle()
606         */
607        public void setTitle(String text) {
608            if (text != null) {
609                if (this.title == null) {
610                    setTitle(new TextTitle(text, JFreeChart.DEFAULT_TITLE_FONT));
611                }
612                else {
613                    this.title.setText(text);
614                }
615            }
616            else {
617                setTitle((TextTitle) null);
618            }
619        }
620    
621        /**
622         * Adds a legend to the plot and sends a {@link ChartChangeEvent} to all
623         * registered listeners.
624         *
625         * @param legend  the legend (<code>null</code> not permitted).
626         *
627         * @see #removeLegend()
628         */
629        public void addLegend(LegendTitle legend) {
630            addSubtitle(legend);
631        }
632    
633        /**
634         * Returns the legend for the chart, if there is one.  Note that a chart
635         * can have more than one legend - this method returns the first.
636         *
637         * @return The legend (possibly <code>null</code>).
638         *
639         * @see #getLegend(int)
640         */
641        public LegendTitle getLegend() {
642            return getLegend(0);
643        }
644    
645        /**
646         * Returns the nth legend for a chart, or <code>null</code>.
647         *
648         * @param index  the legend index (zero-based).
649         *
650         * @return The legend (possibly <code>null</code>).
651         *
652         * @see #addLegend(LegendTitle)
653         */
654        public LegendTitle getLegend(int index) {
655            int seen = 0;
656            Iterator iterator = this.subtitles.iterator();
657            while (iterator.hasNext()) {
658                Title subtitle = (Title) iterator.next();
659                if (subtitle instanceof LegendTitle) {
660                    if (seen == index) {
661                        return (LegendTitle) subtitle;
662                    }
663                    else {
664                        seen++;
665                    }
666                }
667            }
668            return null;
669        }
670    
671        /**
672         * Removes the first legend in the chart and sends a
673         * {@link ChartChangeEvent} to all registered listeners.
674         *
675         * @see #getLegend()
676         */
677        public void removeLegend() {
678            removeSubtitle(getLegend());
679        }
680    
681        /**
682         * Returns the list of subtitles for the chart.
683         *
684         * @return The subtitle list (possibly empty, but never <code>null</code>).
685         *
686         * @see #setSubtitles(List)
687         */
688        public List getSubtitles() {
689            return new ArrayList(this.subtitles);
690        }
691    
692        /**
693         * Sets the title list for the chart (completely replaces any existing
694         * titles) and sends a {@link ChartChangeEvent} to all registered
695         * listeners.
696         *
697         * @param subtitles  the new list of subtitles (<code>null</code> not
698         *                   permitted).
699         *
700         * @see #getSubtitles()
701         */
702        public void setSubtitles(List subtitles) {
703            if (subtitles == null) {
704                throw new NullPointerException("Null 'subtitles' argument.");
705            }
706            setNotify(false);
707            clearSubtitles();
708            Iterator iterator = subtitles.iterator();
709            while (iterator.hasNext()) {
710                Title t = (Title) iterator.next();
711                if (t != null) {
712                    addSubtitle(t);
713                }
714            }
715            setNotify(true);  // this fires a ChartChangeEvent
716        }
717    
718        /**
719         * Returns the number of titles for the chart.
720         *
721         * @return The number of titles for the chart.
722         *
723         * @see #getSubtitles()
724         */
725        public int getSubtitleCount() {
726            return this.subtitles.size();
727        }
728    
729        /**
730         * Returns a chart subtitle.
731         *
732         * @param index  the index of the chart subtitle (zero based).
733         *
734         * @return A chart subtitle.
735         *
736         * @see #addSubtitle(Title)
737         */
738        public Title getSubtitle(int index) {
739            if ((index < 0) || (index >= getSubtitleCount())) {
740                throw new IllegalArgumentException("Index out of range.");
741            }
742            return (Title) this.subtitles.get(index);
743        }
744    
745        /**
746         * Adds a chart subtitle, and notifies registered listeners that the chart
747         * has been modified.
748         *
749         * @param subtitle  the subtitle (<code>null</code> not permitted).
750         *
751         * @see #getSubtitle(int)
752         */
753        public void addSubtitle(Title subtitle) {
754            if (subtitle == null) {
755                throw new IllegalArgumentException("Null 'subtitle' argument.");
756            }
757            this.subtitles.add(subtitle);
758            subtitle.addChangeListener(this);
759            fireChartChanged();
760        }
761    
762        /**
763         * Adds a subtitle at a particular position in the subtitle list, and sends
764         * a {@link ChartChangeEvent} to all registered listeners.
765         *
766         * @param index  the index (in the range 0 to {@link #getSubtitleCount()}).
767         * @param subtitle  the subtitle to add (<code>null</code> not permitted).
768         *
769         * @since 1.0.6
770         */
771        public void addSubtitle(int index, Title subtitle) {
772            if (index < 0 || index > getSubtitleCount()) {
773                throw new IllegalArgumentException(
774                        "The 'index' argument is out of range.");
775            }
776            if (subtitle == null) {
777                throw new IllegalArgumentException("Null 'subtitle' argument.");
778            }
779            this.subtitles.add(index, subtitle);
780            subtitle.addChangeListener(this);
781            fireChartChanged();
782        }
783    
784        /**
785         * Clears all subtitles from the chart and sends a {@link ChartChangeEvent}
786         * to all registered listeners.
787         *
788         * @see #addSubtitle(Title)
789         */
790        public void clearSubtitles() {
791            Iterator iterator = this.subtitles.iterator();
792            while (iterator.hasNext()) {
793                Title t = (Title) iterator.next();
794                t.removeChangeListener(this);
795            }
796            this.subtitles.clear();
797            fireChartChanged();
798        }
799    
800        /**
801         * Removes the specified subtitle and sends a {@link ChartChangeEvent} to
802         * all registered listeners.
803         *
804         * @param title  the title.
805         *
806         * @see #addSubtitle(Title)
807         */
808        public void removeSubtitle(Title title) {
809            this.subtitles.remove(title);
810            fireChartChanged();
811        }
812    
813        /**
814         * Returns the plot for the chart.  The plot is a class responsible for
815         * coordinating the visual representation of the data, including the axes
816         * (if any).
817         *
818         * @return The plot.
819         */
820        public Plot getPlot() {
821            return this.plot;
822        }
823    
824        /**
825         * Returns the plot cast as a {@link CategoryPlot}.
826         * <p>
827         * NOTE: if the plot is not an instance of {@link CategoryPlot}, then a
828         * <code>ClassCastException</code> is thrown.
829         *
830         * @return The plot.
831         *
832         * @see #getPlot()
833         */
834        public CategoryPlot getCategoryPlot() {
835            return (CategoryPlot) this.plot;
836        }
837    
838        /**
839         * Returns the plot cast as an {@link XYPlot}.
840         * <p>
841         * NOTE: if the plot is not an instance of {@link XYPlot}, then a
842         * <code>ClassCastException</code> is thrown.
843         *
844         * @return The plot.
845         *
846         * @see #getPlot()
847         */
848        public XYPlot getXYPlot() {
849            return (XYPlot) this.plot;
850        }
851    
852        /**
853         * Returns a flag that indicates whether or not anti-aliasing is used when
854         * the chart is drawn.
855         *
856         * @return The flag.
857         *
858         * @see #setAntiAlias(boolean)
859         */
860        public boolean getAntiAlias() {
861            Object val = this.renderingHints.get(RenderingHints.KEY_ANTIALIASING);
862            return RenderingHints.VALUE_ANTIALIAS_ON.equals(val);
863        }
864    
865        /**
866         * Sets a flag that indicates whether or not anti-aliasing is used when the
867         * chart is drawn.
868         * <P>
869         * Anti-aliasing usually improves the appearance of charts, but is slower.
870         *
871         * @param flag  the new value of the flag.
872         *
873         * @see #getAntiAlias()
874         */
875        public void setAntiAlias(boolean flag) {
876    
877            Object val = this.renderingHints.get(RenderingHints.KEY_ANTIALIASING);
878            if (val == null) {
879                val = RenderingHints.VALUE_ANTIALIAS_DEFAULT;
880            }
881            if (!flag && RenderingHints.VALUE_ANTIALIAS_OFF.equals(val)
882                || flag && RenderingHints.VALUE_ANTIALIAS_ON.equals(val)) {
883                // no change, do nothing
884                return;
885            }
886            if (flag) {
887                this.renderingHints.put(RenderingHints.KEY_ANTIALIASING,
888                                        RenderingHints.VALUE_ANTIALIAS_ON);
889            }
890            else {
891                this.renderingHints.put(RenderingHints.KEY_ANTIALIASING,
892                                        RenderingHints.VALUE_ANTIALIAS_OFF);
893            }
894            fireChartChanged();
895    
896        }
897    
898        /**
899         * Returns the current value stored in the rendering hints table for
900         * {@link RenderingHints#KEY_TEXT_ANTIALIASING}.
901         *
902         * @return The hint value (possibly <code>null</code>).
903         *
904         * @since 1.0.5
905         *
906         * @see #setTextAntiAlias(Object)
907         */
908        public Object getTextAntiAlias() {
909            return this.renderingHints.get(RenderingHints.KEY_TEXT_ANTIALIASING);
910        }
911    
912        /**
913         * Sets the value in the rendering hints table for
914         * {@link RenderingHints#KEY_TEXT_ANTIALIASING} to either
915         * {@link RenderingHints#VALUE_TEXT_ANTIALIAS_ON} or
916         * {@link RenderingHints#VALUE_TEXT_ANTIALIAS_OFF}, then sends a
917         * {@link ChartChangeEvent} to all registered listeners.
918         *
919         * @param flag  the new value of the flag.
920         *
921         * @since 1.0.5
922         *
923         * @see #getTextAntiAlias()
924         * @see #setTextAntiAlias(Object)
925         */
926        public void setTextAntiAlias(boolean flag) {
927            if (flag) {
928                setTextAntiAlias(RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
929            }
930            else {
931                setTextAntiAlias(RenderingHints.VALUE_TEXT_ANTIALIAS_OFF);
932            }
933        }
934    
935        /**
936         * Sets the value in the rendering hints table for
937         * {@link RenderingHints#KEY_TEXT_ANTIALIASING} and sends a
938         * {@link ChartChangeEvent} to all registered listeners.
939         *
940         * @param val  the new value (<code>null</code> permitted).
941         *
942         * @since 1.0.5
943         *
944         * @see #getTextAntiAlias()
945         * @see #setTextAntiAlias(boolean)
946         */
947        public void setTextAntiAlias(Object val) {
948            this.renderingHints.put(RenderingHints.KEY_TEXT_ANTIALIASING, val);
949            notifyListeners(new ChartChangeEvent(this));
950        }
951    
952        /**
953         * Returns the paint used for the chart background.
954         *
955         * @return The paint (possibly <code>null</code>).
956         *
957         * @see #setBackgroundPaint(Paint)
958         */
959        public Paint getBackgroundPaint() {
960            return this.backgroundPaint;
961        }
962    
963        /**
964         * Sets the paint used to fill the chart background and sends a
965         * {@link ChartChangeEvent} to all registered listeners.
966         *
967         * @param paint  the paint (<code>null</code> permitted).
968         *
969         * @see #getBackgroundPaint()
970         */
971        public void setBackgroundPaint(Paint paint) {
972    
973            if (this.backgroundPaint != null) {
974                if (!this.backgroundPaint.equals(paint)) {
975                    this.backgroundPaint = paint;
976                    fireChartChanged();
977                }
978            }
979            else {
980                if (paint != null) {
981                    this.backgroundPaint = paint;
982                    fireChartChanged();
983                }
984            }
985    
986        }
987    
988        /**
989         * Returns the background image for the chart, or <code>null</code> if
990         * there is no image.
991         *
992         * @return The image (possibly <code>null</code>).
993         *
994         * @see #setBackgroundImage(Image)
995         */
996        public Image getBackgroundImage() {
997            return this.backgroundImage;
998        }
999    
1000        /**
1001         * Sets the background image for the chart and sends a
1002         * {@link ChartChangeEvent} to all registered listeners.
1003         *
1004         * @param image  the image (<code>null</code> permitted).
1005         *
1006         * @see #getBackgroundImage()
1007         */
1008        public void setBackgroundImage(Image image) {
1009    
1010            if (this.backgroundImage != null) {
1011                if (!this.backgroundImage.equals(image)) {
1012                    this.backgroundImage = image;
1013                    fireChartChanged();
1014                }
1015            }
1016            else {
1017                if (image != null) {
1018                    this.backgroundImage = image;
1019                    fireChartChanged();
1020                }
1021            }
1022    
1023        }
1024    
1025        /**
1026         * Returns the background image alignment. Alignment constants are defined
1027         * in the <code>org.jfree.ui.Align</code> class in the JCommon class
1028         * library.
1029         *
1030         * @return The alignment.
1031         *
1032         * @see #setBackgroundImageAlignment(int)
1033         */
1034        public int getBackgroundImageAlignment() {
1035            return this.backgroundImageAlignment;
1036        }
1037    
1038        /**
1039         * Sets the background alignment.  Alignment options are defined by the
1040         * {@link org.jfree.ui.Align} class.
1041         *
1042         * @param alignment  the alignment.
1043         *
1044         * @see #getBackgroundImageAlignment()
1045         */
1046        public void setBackgroundImageAlignment(int alignment) {
1047            if (this.backgroundImageAlignment != alignment) {
1048                this.backgroundImageAlignment = alignment;
1049                fireChartChanged();
1050            }
1051        }
1052    
1053        /**
1054         * Returns the alpha-transparency for the chart's background image.
1055         *
1056         * @return The alpha-transparency.
1057         *
1058         * @see #setBackgroundImageAlpha(float)
1059         */
1060        public float getBackgroundImageAlpha() {
1061            return this.backgroundImageAlpha;
1062        }
1063    
1064        /**
1065         * Sets the alpha-transparency for the chart's background image.
1066         * Registered listeners are notified that the chart has been changed.
1067         *
1068         * @param alpha  the alpha value.
1069         *
1070         * @see #getBackgroundImageAlpha()
1071         */
1072        public void setBackgroundImageAlpha(float alpha) {
1073    
1074            if (this.backgroundImageAlpha != alpha) {
1075                this.backgroundImageAlpha = alpha;
1076                fireChartChanged();
1077            }
1078    
1079        }
1080    
1081        /**
1082         * Returns a flag that controls whether or not change events are sent to
1083         * registered listeners.
1084         *
1085         * @return A boolean.
1086         *
1087         * @see #setNotify(boolean)
1088         */
1089        public boolean isNotify() {
1090            return this.notify;
1091        }
1092    
1093        /**
1094         * Sets a flag that controls whether or not listeners receive
1095         * {@link ChartChangeEvent} notifications.
1096         *
1097         * @param notify  a boolean.
1098         *
1099         * @see #isNotify()
1100         */
1101        public void setNotify(boolean notify) {
1102            this.notify = notify;
1103            // if the flag is being set to true, there may be queued up changes...
1104            if (notify) {
1105                notifyListeners(new ChartChangeEvent(this));
1106            }
1107        }
1108    
1109        /**
1110         * Draws the chart on a Java 2D graphics device (such as the screen or a
1111         * printer).
1112         * <P>
1113         * This method is the focus of the entire JFreeChart library.
1114         *
1115         * @param g2  the graphics device.
1116         * @param area  the area within which the chart should be drawn.
1117         */
1118        public void draw(Graphics2D g2, Rectangle2D area) {
1119            draw(g2, area, null, null);
1120        }
1121    
1122        /**
1123         * Draws the chart on a Java 2D graphics device (such as the screen or a
1124         * printer).  This method is the focus of the entire JFreeChart library.
1125         *
1126         * @param g2  the graphics device.
1127         * @param area  the area within which the chart should be drawn.
1128         * @param info  records info about the drawing (null means collect no info).
1129         */
1130        public void draw(Graphics2D g2, Rectangle2D area, ChartRenderingInfo info) {
1131            draw(g2, area, null, info);
1132        }
1133    
1134        /**
1135         * Draws the chart on a Java 2D graphics device (such as the screen or a
1136         * printer).
1137         * <P>
1138         * This method is the focus of the entire JFreeChart library.
1139         *
1140         * @param g2  the graphics device.
1141         * @param chartArea  the area within which the chart should be drawn.
1142         * @param anchor  the anchor point (in Java2D space) for the chart
1143         *                (<code>null</code> permitted).
1144         * @param info  records info about the drawing (null means collect no info).
1145         */
1146        public void draw(Graphics2D g2,
1147                         Rectangle2D chartArea, Point2D anchor,
1148                         ChartRenderingInfo info) {
1149    
1150            notifyListeners(new ChartProgressEvent(this, this,
1151                    ChartProgressEvent.DRAWING_STARTED, 0));
1152            
1153            EntityCollection entities = null;
1154            // record the chart area, if info is requested...
1155            if (info != null) {
1156                info.clear();
1157                info.setChartArea(chartArea);
1158                entities = info.getEntityCollection();
1159            }
1160            if (entities != null) {
1161                entities.add(new JFreeChartEntity((Rectangle2D) chartArea.clone(),
1162                        this));
1163            }
1164    
1165            // ensure no drawing occurs outside chart area...
1166            Shape savedClip = g2.getClip();
1167            g2.clip(chartArea);
1168    
1169            g2.addRenderingHints(this.renderingHints);
1170    
1171            // draw the chart background...
1172            if (this.backgroundPaint != null) {
1173                g2.setPaint(this.backgroundPaint);
1174                g2.fill(chartArea);
1175            }
1176    
1177            if (this.backgroundImage != null) {
1178                Composite originalComposite = g2.getComposite();
1179                g2.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER,
1180                        this.backgroundImageAlpha));
1181                Rectangle2D dest = new Rectangle2D.Double(0.0, 0.0,
1182                        this.backgroundImage.getWidth(null),
1183                        this.backgroundImage.getHeight(null));
1184                Align.align(dest, chartArea, this.backgroundImageAlignment);
1185                g2.drawImage(this.backgroundImage, (int) dest.getX(),
1186                        (int) dest.getY(), (int) dest.getWidth(),
1187                        (int) dest.getHeight(), null);
1188                g2.setComposite(originalComposite);
1189            }
1190    
1191            if (isBorderVisible()) {
1192                Paint paint = getBorderPaint();
1193                Stroke stroke = getBorderStroke();
1194                if (paint != null && stroke != null) {
1195                    Rectangle2D borderArea = new Rectangle2D.Double(
1196                            chartArea.getX(), chartArea.getY(),
1197                            chartArea.getWidth() - 1.0, chartArea.getHeight()
1198                            - 1.0);
1199                    g2.setPaint(paint);
1200                    g2.setStroke(stroke);
1201                    g2.draw(borderArea);
1202                }
1203            }
1204    
1205            // draw the title and subtitles...
1206            Rectangle2D nonTitleArea = new Rectangle2D.Double();
1207            nonTitleArea.setRect(chartArea);
1208            this.padding.trim(nonTitleArea);
1209    
1210            if (this.title != null && this.title.isVisible()) {
1211                EntityCollection e = drawTitle(this.title, g2, nonTitleArea,
1212                        (entities != null));
1213                if (e != null) {
1214                    entities.addAll(e);
1215                }
1216            }
1217    
1218            Iterator iterator = this.subtitles.iterator();
1219            while (iterator.hasNext()) {
1220                Title currentTitle = (Title) iterator.next();
1221                if (currentTitle.isVisible()) {
1222                    EntityCollection e = drawTitle(currentTitle, g2, nonTitleArea,
1223                            (entities != null));
1224                    if (e != null) {
1225                        entities.addAll(e);
1226                    }
1227                }
1228            }
1229    
1230            Rectangle2D plotArea = nonTitleArea;
1231    
1232            // draw the plot (axes and data visualisation)
1233            PlotRenderingInfo plotInfo = null;
1234            if (info != null) {
1235                plotInfo = info.getPlotInfo();
1236            }
1237            this.plot.draw(g2, plotArea, anchor, null, plotInfo);
1238    
1239            g2.setClip(savedClip);
1240    
1241            notifyListeners(new ChartProgressEvent(this, this,
1242                    ChartProgressEvent.DRAWING_FINISHED, 100));
1243        }
1244    
1245        /**
1246         * Creates a rectangle that is aligned to the frame.
1247         *
1248         * @param dimensions  the dimensions for the rectangle.
1249         * @param frame  the frame to align to.
1250         * @param hAlign  the horizontal alignment.
1251         * @param vAlign  the vertical alignment.
1252         *
1253         * @return A rectangle.
1254         */
1255        private Rectangle2D createAlignedRectangle2D(Size2D dimensions,
1256                Rectangle2D frame, HorizontalAlignment hAlign,
1257                VerticalAlignment vAlign) {
1258            double x = Double.NaN;
1259            double y = Double.NaN;
1260            if (hAlign == HorizontalAlignment.LEFT) {
1261                x = frame.getX();
1262            }
1263            else if (hAlign == HorizontalAlignment.CENTER) {
1264                x = frame.getCenterX() - (dimensions.width / 2.0);
1265            }
1266            else if (hAlign == HorizontalAlignment.RIGHT) {
1267                x = frame.getMaxX() - dimensions.width;
1268            }
1269            if (vAlign == VerticalAlignment.TOP) {
1270                y = frame.getY();
1271            }
1272            else if (vAlign == VerticalAlignment.CENTER) {
1273                y = frame.getCenterY() - (dimensions.height / 2.0);
1274            }
1275            else if (vAlign == VerticalAlignment.BOTTOM) {
1276                y = frame.getMaxY() - dimensions.height;
1277            }
1278    
1279            return new Rectangle2D.Double(x, y, dimensions.width,
1280                    dimensions.height);
1281        }
1282    
1283        /**
1284         * Draws a title.  The title should be drawn at the top, bottom, left or
1285         * right of the specified area, and the area should be updated to reflect
1286         * the amount of space used by the title.
1287         *
1288         * @param t  the title (<code>null</code> not permitted).
1289         * @param g2  the graphics device (<code>null</code> not permitted).
1290         * @param area  the chart area, excluding any existing titles
1291         *              (<code>null</code> not permitted).
1292         * @param entities  a flag that controls whether or not an entity
1293         *                  collection is returned for the title.
1294         *
1295         * @return An entity collection for the title (possibly <code>null</code>).
1296         */
1297        protected EntityCollection drawTitle(Title t, Graphics2D g2,
1298                                             Rectangle2D area, boolean entities) {
1299    
1300            if (t == null) {
1301                throw new IllegalArgumentException("Null 't' argument.");
1302            }
1303            if (area == null) {
1304                throw new IllegalArgumentException("Null 'area' argument.");
1305            }
1306            Rectangle2D titleArea;
1307            RectangleEdge position = t.getPosition();
1308            double ww = area.getWidth();
1309            if (ww <= 0.0) {
1310                return null;
1311            }
1312            double hh = area.getHeight();
1313            if (hh <= 0.0) {
1314                return null;
1315            }
1316            RectangleConstraint constraint = new RectangleConstraint(ww,
1317                    new Range(0.0, ww), LengthConstraintType.RANGE, hh,
1318                    new Range(0.0, hh), LengthConstraintType.RANGE);
1319            Object retValue = null;
1320            BlockParams p = new BlockParams();
1321            p.setGenerateEntities(entities);
1322            if (position == RectangleEdge.TOP) {
1323                Size2D size = t.arrange(g2, constraint);
1324                titleArea = createAlignedRectangle2D(size, area,
1325                        t.getHorizontalAlignment(), VerticalAlignment.TOP);
1326                retValue = t.draw(g2, titleArea, p);
1327                area.setRect(area.getX(), Math.min(area.getY() + size.height,
1328                        area.getMaxY()), area.getWidth(), Math.max(area.getHeight()
1329                        - size.height, 0));
1330            }
1331            else if (position == RectangleEdge.BOTTOM) {
1332                Size2D size = t.arrange(g2, constraint);
1333                titleArea = createAlignedRectangle2D(size, area,
1334                        t.getHorizontalAlignment(), VerticalAlignment.BOTTOM);
1335                retValue = t.draw(g2, titleArea, p);
1336                area.setRect(area.getX(), area.getY(), area.getWidth(),
1337                        area.getHeight() - size.height);
1338            }
1339            else if (position == RectangleEdge.RIGHT) {
1340                Size2D size = t.arrange(g2, constraint);
1341                titleArea = createAlignedRectangle2D(size, area,
1342                        HorizontalAlignment.RIGHT, t.getVerticalAlignment());
1343                retValue = t.draw(g2, titleArea, p);
1344                area.setRect(area.getX(), area.getY(), area.getWidth()
1345                        - size.width, area.getHeight());
1346            }
1347    
1348            else if (position == RectangleEdge.LEFT) {
1349                Size2D size = t.arrange(g2, constraint);
1350                titleArea = createAlignedRectangle2D(size, area,
1351                        HorizontalAlignment.LEFT, t.getVerticalAlignment());
1352                retValue = t.draw(g2, titleArea, p);
1353                area.setRect(area.getX() + size.width, area.getY(), area.getWidth()
1354                        - size.width, area.getHeight());
1355            }
1356            else {
1357                throw new RuntimeException("Unrecognised title position.");
1358            }
1359            EntityCollection result = null;
1360            if (retValue instanceof EntityBlockResult) {
1361                EntityBlockResult ebr = (EntityBlockResult) retValue;
1362                result = ebr.getEntityCollection();
1363            }
1364            return result;
1365        }
1366    
1367        /**
1368         * Creates and returns a buffered image into which the chart has been drawn.
1369         *
1370         * @param width  the width.
1371         * @param height  the height.
1372         *
1373         * @return A buffered image.
1374         */
1375        public BufferedImage createBufferedImage(int width, int height) {
1376            return createBufferedImage(width, height, null);
1377        }
1378    
1379        /**
1380         * Creates and returns a buffered image into which the chart has been drawn.
1381         *
1382         * @param width  the width.
1383         * @param height  the height.
1384         * @param info  carries back chart state information (<code>null</code>
1385         *              permitted).
1386         *
1387         * @return A buffered image.
1388         */
1389        public BufferedImage createBufferedImage(int width, int height,
1390                                                 ChartRenderingInfo info) {
1391            return createBufferedImage(width, height, BufferedImage.TYPE_INT_ARGB,
1392                    info);
1393        }
1394    
1395        /**
1396         * Creates and returns a buffered image into which the chart has been drawn.
1397         *
1398         * @param width  the width.
1399         * @param height  the height.
1400         * @param imageType  the image type.
1401         * @param info  carries back chart state information (<code>null</code>
1402         *              permitted).
1403         *
1404         * @return A buffered image.
1405         */
1406        public BufferedImage createBufferedImage(int width, int height,
1407                                                 int imageType,
1408                                                 ChartRenderingInfo info) {
1409            BufferedImage image = new BufferedImage(width, height, imageType);
1410            Graphics2D g2 = image.createGraphics();
1411            draw(g2, new Rectangle2D.Double(0, 0, width, height), null, info);
1412            g2.dispose();
1413            return image;
1414        }
1415    
1416        /**
1417         * Creates and returns a buffered image into which the chart has been drawn.
1418         *
1419         * @param imageWidth  the image width.
1420         * @param imageHeight  the image height.
1421         * @param drawWidth  the width for drawing the chart (will be scaled to
1422         *                   fit image).
1423         * @param drawHeight  the height for drawing the chart (will be scaled to
1424         *                    fit image).
1425         * @param info  optional object for collection chart dimension and entity
1426         *              information.
1427         *
1428         * @return A buffered image.
1429         */
1430        public BufferedImage createBufferedImage(int imageWidth,
1431                                                 int imageHeight,
1432                                                 double drawWidth,
1433                                                 double drawHeight,
1434                                                 ChartRenderingInfo info) {
1435    
1436            BufferedImage image = new BufferedImage(imageWidth, imageHeight,
1437                    BufferedImage.TYPE_INT_ARGB);
1438            Graphics2D g2 = image.createGraphics();
1439            double scaleX = imageWidth / drawWidth;
1440            double scaleY = imageHeight / drawHeight;
1441            AffineTransform st = AffineTransform.getScaleInstance(scaleX, scaleY);
1442            g2.transform(st);
1443            draw(g2, new Rectangle2D.Double(0, 0, drawWidth, drawHeight), null,
1444                    info);
1445            g2.dispose();
1446            return image;
1447    
1448        }
1449    
1450        /**
1451         * Handles a 'click' on the chart.  JFreeChart is not a UI component, so
1452         * some other object (for example, {@link ChartPanel}) needs to capture
1453         * the click event and pass it onto the JFreeChart object.
1454         * If you are not using JFreeChart in a client application, then this
1455         * method is not required.
1456         *
1457         * @param x  x-coordinate of the click (in Java2D space).
1458         * @param y  y-coordinate of the click (in Java2D space).
1459         * @param info  contains chart dimension and entity information
1460         *              (<code>null</code> not permitted).
1461         */
1462        public void handleClick(int x, int y, ChartRenderingInfo info) {
1463    
1464            // pass the click on to the plot...
1465            // rely on the plot to post a plot change event and redraw the chart...
1466            this.plot.handleClick(x, y, info.getPlotInfo());
1467    
1468        }
1469    
1470        /**
1471         * Registers an object for notification of changes to the chart.
1472         *
1473         * @param listener  the listener (<code>null</code> not permitted).
1474         *
1475         * @see #removeChangeListener(ChartChangeListener)
1476         */
1477        public void addChangeListener(ChartChangeListener listener) {
1478            if (listener == null) {
1479                throw new IllegalArgumentException("Null 'listener' argument.");
1480            }
1481            this.changeListeners.add(ChartChangeListener.class, listener);
1482        }
1483    
1484        /**
1485         * Deregisters an object for notification of changes to the chart.
1486         *
1487         * @param listener  the listener (<code>null</code> not permitted)
1488         *
1489         * @see #addChangeListener(ChartChangeListener)
1490         */
1491        public void removeChangeListener(ChartChangeListener listener) {
1492            if (listener == null) {
1493                throw new IllegalArgumentException("Null 'listener' argument.");
1494            }
1495            this.changeListeners.remove(ChartChangeListener.class, listener);
1496        }
1497    
1498        /**
1499         * Sends a default {@link ChartChangeEvent} to all registered listeners.
1500         * <P>
1501         * This method is for convenience only.
1502         */
1503        public void fireChartChanged() {
1504            ChartChangeEvent event = new ChartChangeEvent(this);
1505            notifyListeners(event);
1506        }
1507    
1508        /**
1509         * Sends a {@link ChartChangeEvent} to all registered listeners.
1510         *
1511         * @param event  information about the event that triggered the
1512         *               notification.
1513         */
1514        protected void notifyListeners(ChartChangeEvent event) {
1515            if (this.notify) {
1516                Object[] listeners = this.changeListeners.getListenerList();
1517                for (int i = listeners.length - 2; i >= 0; i -= 2) {
1518                    if (listeners[i] == ChartChangeListener.class) {
1519                        ((ChartChangeListener) listeners[i + 1]).chartChanged(
1520                                event);
1521                    }
1522                }
1523            }
1524        }
1525    
1526        /**
1527         * Registers an object for notification of progress events relating to the
1528         * chart.
1529         *
1530         * @param listener  the object being registered.
1531         *
1532         * @see #removeProgressListener(ChartProgressListener)
1533         */
1534        public void addProgressListener(ChartProgressListener listener) {
1535            this.progressListeners.add(ChartProgressListener.class, listener);
1536        }
1537    
1538        /**
1539         * Deregisters an object for notification of changes to the chart.
1540         *
1541         * @param listener  the object being deregistered.
1542         *
1543         * @see #addProgressListener(ChartProgressListener)
1544         */
1545        public void removeProgressListener(ChartProgressListener listener) {
1546            this.progressListeners.remove(ChartProgressListener.class, listener);
1547        }
1548    
1549        /**
1550         * Sends a {@link ChartProgressEvent} to all registered listeners.
1551         *
1552         * @param event  information about the event that triggered the
1553         *               notification.
1554         */
1555        protected void notifyListeners(ChartProgressEvent event) {
1556    
1557            Object[] listeners = this.progressListeners.getListenerList();
1558            for (int i = listeners.length - 2; i >= 0; i -= 2) {
1559                if (listeners[i] == ChartProgressListener.class) {
1560                    ((ChartProgressListener) listeners[i + 1]).chartProgress(event);
1561                }
1562            }
1563    
1564        }
1565    
1566        /**
1567         * Receives notification that a chart title has changed, and passes this
1568         * on to registered listeners.
1569         *
1570         * @param event  information about the chart title change.
1571         */
1572        public void titleChanged(TitleChangeEvent event) {
1573            event.setChart(this);
1574            notifyListeners(event);
1575        }
1576    
1577        /**
1578         * Receives notification that the plot has changed, and passes this on to
1579         * registered listeners.
1580         *
1581         * @param event  information about the plot change.
1582         */
1583        public void plotChanged(PlotChangeEvent event) {
1584            event.setChart(this);
1585            notifyListeners(event);
1586        }
1587    
1588        /**
1589         * Tests this chart for equality with another object.
1590         *
1591         * @param obj  the object (<code>null</code> permitted).
1592         *
1593         * @return A boolean.
1594         */
1595        public boolean equals(Object obj) {
1596            if (obj == this) {
1597                return true;
1598            }
1599            if (!(obj instanceof JFreeChart)) {
1600                return false;
1601            }
1602            JFreeChart that = (JFreeChart) obj;
1603            if (!this.renderingHints.equals(that.renderingHints)) {
1604                return false;
1605            }
1606            if (this.borderVisible != that.borderVisible) {
1607                return false;
1608            }
1609            if (!ObjectUtilities.equal(this.borderStroke, that.borderStroke)) {
1610                return false;
1611            }
1612            if (!PaintUtilities.equal(this.borderPaint, that.borderPaint)) {
1613                return false;
1614            }
1615            if (!this.padding.equals(that.padding)) {
1616                return false;
1617            }
1618            if (!ObjectUtilities.equal(this.title, that.title)) {
1619                return false;
1620            }
1621            if (!ObjectUtilities.equal(this.subtitles, that.subtitles)) {
1622                return false;
1623            }
1624            if (!ObjectUtilities.equal(this.plot, that.plot)) {
1625                return false;
1626            }
1627            if (!PaintUtilities.equal(
1628                this.backgroundPaint, that.backgroundPaint
1629            )) {
1630                return false;
1631            }
1632            if (!ObjectUtilities.equal(this.backgroundImage,
1633                    that.backgroundImage)) {
1634                return false;
1635            }
1636            if (this.backgroundImageAlignment != that.backgroundImageAlignment) {
1637                return false;
1638            }
1639            if (this.backgroundImageAlpha != that.backgroundImageAlpha) {
1640                return false;
1641            }
1642            if (this.notify != that.notify) {
1643                return false;
1644            }
1645            return true;
1646        }
1647    
1648        /**
1649         * Provides serialization support.
1650         *
1651         * @param stream  the output stream.
1652         *
1653         * @throws IOException  if there is an I/O error.
1654         */
1655        private void writeObject(ObjectOutputStream stream) throws IOException {
1656            stream.defaultWriteObject();
1657            SerialUtilities.writeStroke(this.borderStroke, stream);
1658            SerialUtilities.writePaint(this.borderPaint, stream);
1659            SerialUtilities.writePaint(this.backgroundPaint, stream);
1660        }
1661    
1662        /**
1663         * Provides serialization support.
1664         *
1665         * @param stream  the input stream.
1666         *
1667         * @throws IOException  if there is an I/O error.
1668         * @throws ClassNotFoundException  if there is a classpath problem.
1669         */
1670        private void readObject(ObjectInputStream stream)
1671            throws IOException, ClassNotFoundException {
1672            stream.defaultReadObject();
1673            this.borderStroke = SerialUtilities.readStroke(stream);
1674            this.borderPaint = SerialUtilities.readPaint(stream);
1675            this.backgroundPaint = SerialUtilities.readPaint(stream);
1676            this.progressListeners = new EventListenerList();
1677            this.changeListeners = new EventListenerList();
1678            this.renderingHints = new RenderingHints(
1679                    RenderingHints.KEY_ANTIALIASING,
1680                    RenderingHints.VALUE_ANTIALIAS_ON);
1681    
1682            // register as a listener with sub-components...
1683            if (this.title != null) {
1684                this.title.addChangeListener(this);
1685            }
1686    
1687            for (int i = 0; i < getSubtitleCount(); i++) {
1688                getSubtitle(i).addChangeListener(this);
1689            }
1690            this.plot.addChangeListener(this);
1691        }
1692    
1693        /**
1694         * Prints information about JFreeChart to standard output.
1695         *
1696         * @param args  no arguments are honored.
1697         */
1698        public static void main(String[] args) {
1699            System.out.println(JFreeChart.INFO.toString());
1700        }
1701    
1702        /**
1703         * Clones the object, and takes care of listeners.
1704         * Note: caller shall register its own listeners on cloned graph.
1705         *
1706         * @return A clone.
1707         *
1708         * @throws CloneNotSupportedException if the chart is not cloneable.
1709         */
1710        public Object clone() throws CloneNotSupportedException {
1711            JFreeChart chart = (JFreeChart) super.clone();
1712    
1713            chart.renderingHints = (RenderingHints) this.renderingHints.clone();
1714            // private boolean borderVisible;
1715            // private transient Stroke borderStroke;
1716            // private transient Paint borderPaint;
1717    
1718            if (this.title != null) {
1719                chart.title = (TextTitle) this.title.clone();
1720                chart.title.addChangeListener(chart);
1721            }
1722    
1723            chart.subtitles = new ArrayList();
1724            for (int i = 0; i < getSubtitleCount(); i++) {
1725                Title subtitle = (Title) getSubtitle(i).clone();
1726                chart.subtitles.add(subtitle);
1727                subtitle.addChangeListener(chart);
1728            }
1729    
1730            if (this.plot != null) {
1731                chart.plot = (Plot) this.plot.clone();
1732                chart.plot.addChangeListener(chart);
1733            }
1734    
1735            chart.progressListeners = new EventListenerList();
1736            chart.changeListeners = new EventListenerList();
1737            return chart;
1738        }
1739    
1740    }
1741    
1742    /**
1743     * Information about the JFreeChart project.  One instance of this class is
1744     * assigned to <code>JFreeChart.INFO</code>.
1745     */
1746    class JFreeChartInfo extends ProjectInfo {
1747    
1748        /**
1749         * Default constructor.
1750         */
1751        public JFreeChartInfo() {
1752    
1753            // get a locale-specific resource bundle...
1754            String baseResourceClass
1755                    = "org.jfree.chart.resources.JFreeChartResources";
1756            ResourceBundle resources = ResourceBundleWrapper.getBundle(
1757                    baseResourceClass);
1758    
1759            setName(resources.getString("project.name"));
1760            setVersion(resources.getString("project.version"));
1761            setInfo(resources.getString("project.info"));
1762            setCopyright(resources.getString("project.copyright"));
1763            setLogo(null);  // load only when required
1764            setLicenceName("LGPL");
1765            setLicenceText(Licences.getInstance().getLGPL());
1766    
1767            setContributors(Arrays.asList(
1768                new Contributor[]{
1769                    new Contributor("Eric Alexander", "-"),
1770                    new Contributor("Richard Atkinson",
1771                            "richard_c_atkinson@ntlworld.com"),
1772                    new Contributor("David Basten", "-"),
1773                    new Contributor("David Berry", "-"),
1774                    new Contributor("Chris Boek", "-"),
1775                    new Contributor("Zoheb Borbora", "-"),
1776                    new Contributor("Anthony Boulestreau", "-"),
1777                    new Contributor("Jeremy Bowman", "-"),
1778                    new Contributor("Nicolas Brodu", "-"),
1779                    new Contributor("Jody Brownell", "-"),
1780                    new Contributor("David Browning", "-"),
1781                    new Contributor("Soren Caspersen", "-"),
1782                    new Contributor("Chuanhao Chiu", "-"),
1783                    new Contributor("Brian Cole", "-"),
1784                    new Contributor("Pascal Collet", "-"),
1785                    new Contributor("Martin Cordova", "-"),
1786                    new Contributor("Paolo Cova", "-"),
1787                    new Contributor("Greg Darke", "-"),
1788                    new Contributor("Mike Duffy", "-"),
1789                    new Contributor("Don Elliott", "-"),
1790                    new Contributor("David Forslund", "-"),
1791                    new Contributor("Jonathan Gabbai", "-"),
1792                    new Contributor("David Gilbert",
1793                            "david.gilbert@object-refinery.com"),
1794                    new Contributor("Serge V. Grachov", "-"),
1795                    new Contributor("Daniel Gredler", "-"),
1796                    new Contributor("Hans-Jurgen Greiner", "-"),
1797                    new Contributor("Joao Guilherme Del Valle", "-"),
1798                    new Contributor("Aiman Han", "-"),
1799                    new Contributor("Cameron Hayne", "-"),
1800                    new Contributor("Martin Hoeller", "-"),
1801                    new Contributor("Jon Iles", "-"),
1802                    new Contributor("Wolfgang Irler", "-"),
1803                    new Contributor("Sergei Ivanov", "-"),
1804                    new Contributor("Adriaan Joubert", "-"),
1805                    new Contributor("Darren Jung", "-"),
1806                    new Contributor("Xun Kang", "-"),
1807                    new Contributor("Bill Kelemen", "-"),
1808                    new Contributor("Norbert Kiesel", "-"),
1809                    new Contributor("Peter Kolb", "-"),
1810                    new Contributor("Gideon Krause", "-"),
1811                    new Contributor("Pierre-Marie Le Biot", "-"),
1812                    new Contributor("Arnaud Lelievre", "-"),
1813                    new Contributor("Wolfgang Lenhard", "-"),
1814                    new Contributor("David Li", "-"),
1815                    new Contributor("Yan Liu", "-"),
1816                    new Contributor("Tin Luu", "-"),
1817                    new Contributor("Craig MacFarlane", "-"),
1818                    new Contributor("Achilleus Mantzios", "-"),
1819                    new Contributor("Thomas Meier", "-"),
1820                    new Contributor("Jim Moore", "-"),
1821                    new Contributor("Jonathan Nash", "-"),
1822                    new Contributor("Barak Naveh", "-"),
1823                    new Contributor("David M. O'Donnell", "-"),
1824                    new Contributor("Krzysztof Paz", "-"),
1825                    new Contributor("Eric Penfold", "-"),
1826                    new Contributor("Tomer Peretz", "-"),
1827                    new Contributor("Diego Pierangeli", "-"),
1828                    new Contributor("Xavier Poinsard", "-"),
1829                    new Contributor("Andrzej Porebski", "-"),
1830                    new Contributor("Viktor Rajewski", "-"),
1831                    new Contributor("Eduardo Ramalho", "-"),
1832                    new Contributor("Michael Rauch", "-"),
1833                    new Contributor("Cameron Riley", "-"),
1834                    new Contributor("Klaus Rheinwald", "-"),
1835                    new Contributor("Dan Rivett", "d.rivett@ukonline.co.uk"),
1836                    new Contributor("Scott Sams", "-"),
1837                    new Contributor("Michel Santos", "-"),
1838                    new Contributor("Thierry Saura", "-"),
1839                    new Contributor("Andreas Schneider", "-"),
1840                    new Contributor("Jean-Luc SCHWAB", "-"),
1841                    new Contributor("Bryan Scott", "-"),
1842                    new Contributor("Tobias Selb", "-"),
1843                    new Contributor("Darshan Shah", "-"),
1844                    new Contributor("Mofeed Shahin", "-"),
1845                    new Contributor("Michael Siemer", "-"),
1846                    new Contributor("Pady Srinivasan", "-"),
1847                    new Contributor("Greg Steckman", "-"),
1848                    new Contributor("Gerald Struck", "-"),
1849                    new Contributor("Roger Studner", "-"),
1850                    new Contributor("Irv Thomae", "-"),
1851                    new Contributor("Eric Thomas", "-"),
1852                    new Contributor("Rich Unger", "-"),
1853                    new Contributor("Daniel van Enckevort", "-"),
1854                    new Contributor("Laurence Vanhelsuwe", "-"),
1855                    new Contributor("Sylvain Vieujot", "-"),
1856                    new Contributor("Ulrich Voigt", "-"),
1857                    new Contributor("Jelai Wang", "-"),
1858                    new Contributor("Mark Watson", "www.markwatson.com"),
1859                    new Contributor("Alex Weber", "-"),
1860                    new Contributor("Matthew Wright", "-"),
1861                    new Contributor("Benoit Xhenseval", "-"),
1862                    new Contributor("Christian W. Zuckschwerdt",
1863                            "Christian.Zuckschwerdt@Informatik.Uni-Oldenburg.de"),
1864                    new Contributor("Hari", "-"),
1865                    new Contributor("Sam (oldman)", "-"),
1866                }
1867            ));
1868    
1869            addLibrary(JCommon.INFO);
1870    
1871        }
1872    
1873        /**
1874         * Returns the JFreeChart logo (a picture of a gorilla).
1875         *
1876         * @return The JFreeChart logo.
1877         */
1878        public Image getLogo() {
1879    
1880            Image logo = super.getLogo();
1881            if (logo == null) {
1882                URL imageURL = this.getClass().getClassLoader().getResource(
1883                        "org/jfree/chart/gorilla.jpg");
1884                if (imageURL != null) {
1885                    ImageIcon temp = new ImageIcon(imageURL);
1886                        // use ImageIcon because it waits for the image to load...
1887                    logo = temp.getImage();
1888                    setLogo(logo);
1889                }
1890            }
1891            return logo;
1892    
1893        }
1894    
1895    }