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