001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2017, 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 * AbstractCategoryItemRenderer.java
029 * ---------------------------------
030 * (C) Copyright 2002-2017, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   Richard Atkinson;
034 *                   Peter Kolb (patch 2497611);
035 *
036 * Changes:
037 * --------
038 * 29-May-2002 : Version 1 (DG);
039 * 06-Jun-2002 : Added accessor methods for the tool tip generator (DG);
040 * 11-Jun-2002 : Made constructors protected (DG);
041 * 26-Jun-2002 : Added axis to initialise method (DG);
042 * 05-Aug-2002 : Added urlGenerator member variable plus accessors (RA);
043 * 22-Aug-2002 : Added categoriesPaint attribute, based on code submitted by
044 *               Janet Banks.  This can be used when there is only one series,
045 *               and you want each category item to have a different color (DG);
046 * 01-Oct-2002 : Fixed errors reported by Checkstyle (DG);
047 * 29-Oct-2002 : Fixed bug where background image for plot was not being
048 *               drawn (DG);
049 * 05-Nov-2002 : Replaced references to CategoryDataset with TableDataset (DG);
050 * 26-Nov 2002 : Replaced the isStacked() method with getRangeType() (DG);
051 * 09-Jan-2003 : Renamed grid-line methods (DG);
052 * 17-Jan-2003 : Moved plot classes into separate package (DG);
053 * 25-Mar-2003 : Implemented Serializable (DG);
054 * 12-May-2003 : Modified to take into account the plot orientation (DG);
055 * 12-Aug-2003 : Very minor javadoc corrections (DB)
056 * 13-Aug-2003 : Implemented Cloneable (DG);
057 * 16-Sep-2003 : Changed ChartRenderingInfo --> PlotRenderingInfo (DG);
058 * 05-Nov-2003 : Fixed marker rendering bug (833623) (DG);
059 * 21-Jan-2004 : Update for renamed method in ValueAxis (DG);
060 * 11-Feb-2004 : Modified labelling for markers (DG);
061 * 12-Feb-2004 : Updated clone() method (DG);
062 * 15-Apr-2004 : Created a new CategoryToolTipGenerator interface (DG);
063 * 05-May-2004 : Fixed bug (948310) where interval markers extend outside axis
064 *               range (DG);
065 * 14-Jun-2004 : Fixed bug in drawRangeMarker() method - now uses 'paint' and
066 *               'stroke' rather than 'outlinePaint' and 'outlineStroke' (DG);
067 * 15-Jun-2004 : Interval markers can now use GradientPaint (DG);
068 * 30-Sep-2004 : Moved drawRotatedString() from RefineryUtilities
069 *               --> TextUtilities (DG);
070 * 01-Oct-2004 : Fixed bug 1029697, problem with label alignment in
071 *               drawRangeMarker() method (DG);
072 * 07-Jan-2005 : Renamed getRangeExtent() --> findRangeBounds() (DG);
073 * 21-Jan-2005 : Modified return type of calculateRangeMarkerTextAnchorPoint()
074 *               method (DG);
075 * 08-Mar-2005 : Fixed positioning of marker labels (DG);
076 * 20-Apr-2005 : Added legend label, tooltip and URL generators (DG);
077 * 01-Jun-2005 : Handle one dimension of the marker label adjustment
078 *               automatically (DG);
079 * 09-Jun-2005 : Added utility method for adding an item entity (DG);
080 * ------------- JFREECHART 1.0.x ---------------------------------------------
081 * 01-Mar-2006 : Updated getLegendItems() to check seriesVisibleInLegend
082 *               flags (DG);
083 * 20-Jul-2006 : Set dataset and series indices in LegendItem (DG);
084 * 23-Oct-2006 : Draw outlines for interval markers (DG);
085 * 24-Oct-2006 : Respect alpha setting in markers, as suggested by Sergei
086 *               Ivanov in patch 1567843 (DG);
087 * 30-Nov-2006 : Added a check for series visibility in the getLegendItem()
088 *               method (DG);
089 * 07-Dec-2006 : Fix for equals() method (DG);
090 * 22-Feb-2007 : Added createState() method (DG);
091 * 01-Mar-2007 : Fixed interval marker drawing (patch 1670686 thanks to
092 *               Sergei Ivanov) (DG);
093 * 20-Apr-2007 : Updated getLegendItem() for renderer change, and deprecated
094 *               itemLabelGenerator, toolTipGenerator and itemURLGenerator
095 *               override fields (DG);
096 * 18-May-2007 : Set dataset and seriesKey for LegendItem (DG);
097 * 17-Jun-2008 : Apply legend shape, font and paint attributes (DG);
098 * 26-Jun-2008 : Added crosshair support (DG);
099 * 25-Nov-2008 : Fixed bug in findRangeBounds() method (DG);
100 * 14-Jan-2009 : Update initialise() to store visible series indices (PK);
101 * 21-Jan-2009 : Added drawRangeLine() method (DG);
102 * 27-Mar-2009 : Added new findRangeBounds() method to account for hidden
103 *               series (DG);
104 * 01-Apr-2009 : Added new addEntity() method (DG);
105 * 09-Feb-2010 : Fixed bug 2947660 (DG);
106 * 02-Jul-2013 : Use ParamChecks (DG);
107 * 08-Apr-2014 : Remove use of ObjectList (DG);
108 * 29-Jul-2014 : Add rendering hints to normalise range lines (DG);
109 * 
110 */
111
112package org.jfree.chart.renderer.category;
113
114import java.awt.AlphaComposite;
115import java.awt.Composite;
116import java.awt.Font;
117import java.awt.GradientPaint;
118import java.awt.Graphics2D;
119import java.awt.Paint;
120import java.awt.RenderingHints;
121import java.awt.Shape;
122import java.awt.Stroke;
123import java.awt.geom.Ellipse2D;
124import java.awt.geom.Line2D;
125import java.awt.geom.Point2D;
126import java.awt.geom.Rectangle2D;
127import java.io.Serializable;
128
129import java.util.ArrayList;
130import java.util.HashMap;
131import java.util.List;
132import java.util.Map;
133import org.jfree.chart.LegendItem;
134import org.jfree.chart.LegendItemCollection;
135import org.jfree.chart.axis.CategoryAxis;
136import org.jfree.chart.axis.ValueAxis;
137import org.jfree.chart.entity.CategoryItemEntity;
138import org.jfree.chart.entity.EntityCollection;
139import org.jfree.chart.event.RendererChangeEvent;
140import org.jfree.chart.labels.CategoryItemLabelGenerator;
141import org.jfree.chart.labels.CategorySeriesLabelGenerator;
142import org.jfree.chart.labels.CategoryToolTipGenerator;
143import org.jfree.chart.labels.ItemLabelPosition;
144import org.jfree.chart.labels.StandardCategorySeriesLabelGenerator;
145import org.jfree.chart.plot.CategoryCrosshairState;
146import org.jfree.chart.plot.CategoryMarker;
147import org.jfree.chart.plot.CategoryPlot;
148import org.jfree.chart.plot.DrawingSupplier;
149import org.jfree.chart.plot.IntervalMarker;
150import org.jfree.chart.plot.Marker;
151import org.jfree.chart.plot.PlotOrientation;
152import org.jfree.chart.plot.PlotRenderingInfo;
153import org.jfree.chart.plot.ValueMarker;
154import org.jfree.chart.renderer.AbstractRenderer;
155import org.jfree.chart.text.TextUtils;
156import org.jfree.chart.ui.GradientPaintTransformer;
157import org.jfree.chart.ui.LengthAdjustmentType;
158import org.jfree.chart.ui.RectangleAnchor;
159import org.jfree.chart.ui.RectangleEdge;
160import org.jfree.chart.ui.RectangleInsets;
161import org.jfree.chart.urls.CategoryURLGenerator;
162import org.jfree.chart.util.CloneUtils;
163import org.jfree.chart.util.ObjectUtils;
164import org.jfree.chart.util.Args;
165import org.jfree.chart.util.PublicCloneable;
166import org.jfree.chart.util.SortOrder;
167import org.jfree.data.KeyedValues2DItemKey;
168import org.jfree.data.Range;
169import org.jfree.data.category.CategoryDataset;
170import org.jfree.data.general.DatasetUtils;
171
172/**
173 * An abstract base class that you can use to implement a new
174 * {@link CategoryItemRenderer}.  When you create a new
175 * {@link CategoryItemRenderer} you are not required to extend this class,
176 * but it makes the job easier.
177 */
178public abstract class AbstractCategoryItemRenderer extends AbstractRenderer
179        implements CategoryItemRenderer, Cloneable, PublicCloneable,
180        Serializable {
181
182    /** For serialization. */
183    private static final long serialVersionUID = 1247553218442497391L;
184
185    /** The plot that the renderer is assigned to. */
186    private CategoryPlot plot;
187
188    /** A list of item label generators (one per series). */
189    private Map<Integer, CategoryItemLabelGenerator> itemLabelGeneratorMap;
190
191    /** The default item label generator. */
192    private CategoryItemLabelGenerator defaultItemLabelGenerator;
193
194    /** A list of tool tip generators (one per series). */
195    private Map<Integer, CategoryToolTipGenerator> toolTipGeneratorMap;
196
197    /** The default tool tip generator. */
198    private CategoryToolTipGenerator defaultToolTipGenerator;
199
200    /** A list of item label generators (one per series). */
201    private Map<Integer, CategoryURLGenerator> itemURLGeneratorMap;
202
203    /** The default item label generator. */
204    private CategoryURLGenerator defaultItemURLGenerator;
205
206    /** The legend item label generator. */
207    private CategorySeriesLabelGenerator legendItemLabelGenerator;
208
209    /** The legend item tool tip generator. */
210    private CategorySeriesLabelGenerator legendItemToolTipGenerator;
211
212    /** The legend item URL generator. */
213    private CategorySeriesLabelGenerator legendItemURLGenerator;
214
215    /** The number of rows in the dataset (temporary record). */
216    private transient int rowCount;
217
218    /** The number of columns in the dataset (temporary record). */
219    private transient int columnCount;
220
221    /**
222     * Creates a new renderer with no tool tip generator and no URL generator.
223     * The defaults (no tool tip or URL generators) have been chosen to
224     * minimise the processing required to generate a default chart.  If you
225     * require tool tips or URLs, then you can easily add the required
226     * generators.
227     */
228    protected AbstractCategoryItemRenderer() {
229        this.itemLabelGeneratorMap 
230                = new HashMap<Integer, CategoryItemLabelGenerator>();
231        this.toolTipGeneratorMap 
232                = new HashMap<Integer, CategoryToolTipGenerator>();
233        this.itemURLGeneratorMap = new HashMap<Integer, CategoryURLGenerator>();
234        this.legendItemLabelGenerator
235                = new StandardCategorySeriesLabelGenerator();
236    }
237
238    /**
239     * Returns the number of passes through the dataset required by the
240     * renderer.  This method returns {@code 1}, subclasses should
241     * override if they need more passes.
242     *
243     * @return The pass count.
244     */
245    @Override
246    public int getPassCount() {
247        return 1;
248    }
249
250    /**
251     * Returns the plot that the renderer has been assigned to (where
252     * {@code null} indicates that the renderer is not currently assigned
253     * to a plot).
254     *
255     * @return The plot (possibly {@code null}).
256     *
257     * @see #setPlot(CategoryPlot)
258     */
259    @Override
260    public CategoryPlot getPlot() {
261        return this.plot;
262    }
263
264    /**
265     * Sets the plot that the renderer has been assigned to.  This method is
266     * usually called by the {@link CategoryPlot}, in normal usage you
267     * shouldn't need to call this method directly.
268     *
269     * @param plot  the plot ({@code null} not permitted).
270     *
271     * @see #getPlot()
272     */
273    @Override
274    public void setPlot(CategoryPlot plot) {
275        Args.nullNotPermitted(plot, "plot");
276        this.plot = plot;
277    }
278
279    // ITEM LABEL GENERATOR
280
281    /**
282     * Returns the item label generator for a data item.  This implementation
283     * simply passes control to the {@link #getSeriesItemLabelGenerator(int)}
284     * method.  If, for some reason, you want a different generator for
285     * individual items, you can override this method.
286     *
287     * @param row  the row index (zero based).
288     * @param column  the column index (zero based).
289     *
290     * @return The generator (possibly {@code null}).
291     */
292    @Override
293    public CategoryItemLabelGenerator getItemLabelGenerator(int row,
294            int column) {
295        return getSeriesItemLabelGenerator(row);
296    }
297
298    /**
299     * Returns the item label generator for a series.
300     *
301     * @param series  the series index (zero based).
302     *
303     * @return The generator (possibly {@code null}).
304     *
305     * @see #setSeriesItemLabelGenerator(int, CategoryItemLabelGenerator)
306     */
307    @Override
308    public CategoryItemLabelGenerator getSeriesItemLabelGenerator(int series) {
309
310        // otherwise look up the generator table
311        CategoryItemLabelGenerator generator = this.itemLabelGeneratorMap.get(
312                series);
313        if (generator == null) {
314            generator = this.defaultItemLabelGenerator;
315        }
316        return generator;
317    }
318
319    /**
320     * Sets the item label generator for a series and sends a
321     * {@link RendererChangeEvent} to all registered listeners.
322     *
323     * @param series  the series index (zero based).
324     * @param generator  the generator ({@code null} permitted).
325     *
326     * @see #getSeriesItemLabelGenerator(int)
327     */
328    @Override
329    public void setSeriesItemLabelGenerator(int series,
330            CategoryItemLabelGenerator generator) {
331        setSeriesItemLabelGenerator(series, generator, true);
332    }
333    
334    /**
335     * Sets the item label generator for a series and sends a
336     * {@link RendererChangeEvent} to all registered listeners.
337     *
338     * @param series  the series index (zero based).
339     * @param generator  the generator ({@code null} permitted).
340     * @param notify  notify listeners?
341     *
342     * @see #getSeriesItemLabelGenerator(int)
343     */
344    @Override
345    public void setSeriesItemLabelGenerator(int series,
346            CategoryItemLabelGenerator generator, boolean notify) {
347        this.itemLabelGeneratorMap.put(series, generator);
348        if (notify) {
349            fireChangeEvent();
350        }
351    }
352
353    /**
354     * Returns the default item label generator.
355     *
356     * @return The generator (possibly {@code null}).
357     *
358     * @see #setDefaultItemLabelGenerator(CategoryItemLabelGenerator)
359     */
360    @Override
361    public CategoryItemLabelGenerator getDefaultItemLabelGenerator() {
362        return this.defaultItemLabelGenerator;
363    }
364
365    /**
366     * Sets the default item label generator and sends a
367     * {@link RendererChangeEvent} to all registered listeners.
368     *
369     * @param generator  the generator ({@code null} permitted).
370     *
371     * @see #getDefaultItemLabelGenerator()
372     */
373    @Override
374    public void setDefaultItemLabelGenerator(
375            CategoryItemLabelGenerator generator) {
376        setDefaultItemLabelGenerator(generator, true);
377    }
378    
379    /**
380     * Sets the default item label generator and sends a
381     * {@link RendererChangeEvent} to all registered listeners.
382     *
383     * @param generator  the generator ({@code null} permitted).
384     * @param notify  notify listeners?
385     *
386     * @see #getDefaultItemLabelGenerator()
387     */
388    @Override
389    public void setDefaultItemLabelGenerator(
390            CategoryItemLabelGenerator generator, boolean notify) {
391        this.defaultItemLabelGenerator = generator;
392        if (notify) {
393            fireChangeEvent();
394        }
395    }
396
397    // TOOL TIP GENERATOR
398
399    /**
400     * Returns the tool tip generator that should be used for the specified
401     * item.  This method looks up the generator using the "three-layer"
402     * approach outlined in the general description of this interface.  You
403     * can override this method if you want to return a different generator per
404     * item.
405     *
406     * @param row  the row index (zero-based).
407     * @param column  the column index (zero-based).
408     *
409     * @return The generator (possibly {@code null}).
410     */
411    @Override
412    public CategoryToolTipGenerator getToolTipGenerator(int row, int column) {
413
414        CategoryToolTipGenerator result = getSeriesToolTipGenerator(row);
415        if (result == null) {
416            result = this.defaultToolTipGenerator;
417        }
418        return result;
419    }
420
421    /**
422     * Returns the tool tip generator for the specified series (a "layer 1"
423     * generator).
424     *
425     * @param series  the series index (zero-based).
426     *
427     * @return The tool tip generator (possibly {@code null}).
428     *
429     * @see #setSeriesToolTipGenerator(int, CategoryToolTipGenerator)
430     */
431    @Override
432    public CategoryToolTipGenerator getSeriesToolTipGenerator(int series) {
433        return this.toolTipGeneratorMap.get(series);
434    }
435
436    /**
437     * Sets the tool tip generator for a series and sends a
438     * {@link RendererChangeEvent} to all registered listeners.
439     *
440     * @param series  the series index (zero-based).
441     * @param generator  the generator ({@code null} permitted).
442     *
443     * @see #getSeriesToolTipGenerator(int)
444     */
445    @Override
446    public void setSeriesToolTipGenerator(int series,
447            CategoryToolTipGenerator generator) {
448        setSeriesToolTipGenerator(series, generator, true);
449    }
450    
451    /**
452     * Sets the tool tip generator for a series and sends a
453     * {@link RendererChangeEvent} to all registered listeners.
454     *
455     * @param series  the series index (zero-based).
456     * @param generator  the generator ({@code null} permitted).
457     * @param notify  notify listeners?
458     *
459     * @see #getSeriesToolTipGenerator(int)
460     */
461    @Override
462    public void setSeriesToolTipGenerator(int series,
463            CategoryToolTipGenerator generator, boolean notify) {
464        this.toolTipGeneratorMap.put(series, generator);
465        if (notify) {
466            fireChangeEvent();
467        }
468    }
469
470    /**
471     * Returns the default tool tip generator (the "layer 2" generator).
472     *
473     * @return The tool tip generator (possibly {@code null}).
474     *
475     * @see #setDefaultToolTipGenerator(CategoryToolTipGenerator)
476     */
477    @Override
478    public CategoryToolTipGenerator getDefaultToolTipGenerator() {
479        return this.defaultToolTipGenerator;
480    }
481
482    /**
483     * Sets the default tool tip generator and sends a {@link RendererChangeEvent}
484     * to all registered listeners.
485     *
486     * @param generator  the generator ({@code null} permitted).
487     *
488     * @see #getDefaultToolTipGenerator()
489     */
490    @Override
491    public void setDefaultToolTipGenerator(CategoryToolTipGenerator generator) {
492        setDefaultToolTipGenerator(generator, true);
493    }
494    
495    /**
496     * Sets the default tool tip generator and sends a {@link RendererChangeEvent}
497     * to all registered listeners.
498     *
499     * @param generator  the generator ({@code null} permitted).
500     * @param notify  notify listeners?
501     *
502     * @see #getDefaultToolTipGenerator()
503     */
504    @Override
505    public void setDefaultToolTipGenerator(CategoryToolTipGenerator generator, boolean notify) {
506        this.defaultToolTipGenerator = generator;
507        if (notify) {
508            fireChangeEvent();
509        }
510    }
511
512    // URL GENERATOR
513
514    /**
515     * Returns the URL generator for a data item.  This method just calls the
516     * getSeriesItemURLGenerator method, but you can override this behaviour if
517     * you want to.
518     *
519     * @param row  the row index (zero based).
520     * @param column  the column index (zero based).
521     *
522     * @return The URL generator.
523     */
524    @Override
525    public CategoryURLGenerator getItemURLGenerator(int row, int column) {
526        return getSeriesItemURLGenerator(row);
527    }
528
529    /**
530     * Returns the URL generator for a series.
531     *
532     * @param series  the series index (zero based).
533     *
534     * @return The URL generator for the series.
535     *
536     * @see #setSeriesItemURLGenerator(int, CategoryURLGenerator)
537     */
538    @Override
539    public CategoryURLGenerator getSeriesItemURLGenerator(int series) {
540        // otherwise look up the generator table
541        CategoryURLGenerator generator = this.itemURLGeneratorMap.get(series);
542        if (generator == null) {
543            generator = this.defaultItemURLGenerator;
544        }
545        return generator;
546    }
547
548    /**
549     * Sets the URL generator for a series and sends a
550     * {@link RendererChangeEvent} to all registered listeners.
551     *
552     * @param series  the series index (zero based).
553     * @param generator  the generator.
554     *
555     * @see #getSeriesItemURLGenerator(int)
556     */
557    @Override
558    public void setSeriesItemURLGenerator(int series,
559            CategoryURLGenerator generator) {
560        setSeriesItemURLGenerator(series, generator, true);
561    }
562    
563    /**
564     * Sets the URL generator for a series and sends a
565     * {@link RendererChangeEvent} to all registered listeners.
566     *
567     * @param series  the series index (zero based).
568     * @param generator  the generator.
569     * @param notify  notify listeners?
570     *
571     * @see #getSeriesItemURLGenerator(int)
572     */
573    @Override
574    public void setSeriesItemURLGenerator(int series,
575            CategoryURLGenerator generator, boolean notify) {
576        this.itemURLGeneratorMap.put(series, generator);
577        if (notify) {
578            fireChangeEvent();
579        }
580    }
581
582    /**
583     * Returns the default item URL generator.
584     *
585     * @return The item URL generator.
586     *
587     * @see #setDefaultItemURLGenerator(CategoryURLGenerator)
588     */
589    @Override
590    public CategoryURLGenerator getDefaultItemURLGenerator() {
591        return this.defaultItemURLGenerator;
592    }
593
594    /**
595     * Sets the default item URL generator and sends a
596     * {@link RendererChangeEvent} to all registered listeners.
597     *
598     * @param generator  the item URL generator ({@code null} permitted).
599     *
600     * @see #getDefaultItemURLGenerator()
601     */
602    @Override
603    public void setDefaultItemURLGenerator(CategoryURLGenerator generator) {
604        setDefaultItemURLGenerator(generator, true);
605    }
606    
607    /**
608     * Sets the default item URL generator and sends a
609     * {@link RendererChangeEvent} to all registered listeners.
610     *
611     * @param generator  the item URL generator ({@code null} permitted).
612     * @param notify  notify listeners?
613     *
614     * @see #getDefaultItemURLGenerator()
615     */
616    @Override
617    public void setDefaultItemURLGenerator(CategoryURLGenerator generator, boolean notify) {
618        this.defaultItemURLGenerator = generator;
619        if (notify) {
620            fireChangeEvent();
621        }
622    }
623
624    /**
625     * Returns the number of rows in the dataset.  This value is updated in the
626     * {@link AbstractCategoryItemRenderer#initialise} method.
627     *
628     * @return The row count.
629     */
630    public int getRowCount() {
631        return this.rowCount;
632    }
633
634    /**
635     * Returns the number of columns in the dataset.  This value is updated in
636     * the {@link AbstractCategoryItemRenderer#initialise} method.
637     *
638     * @return The column count.
639     */
640    public int getColumnCount() {
641        return this.columnCount;
642    }
643
644    /**
645     * Creates a new state instance---this method is called from the
646     * {@link #initialise(Graphics2D, Rectangle2D, CategoryPlot, int,
647     * PlotRenderingInfo)} method.  Subclasses can override this method if
648     * they need to use a subclass of {@link CategoryItemRendererState}.
649     *
650     * @param info  collects plot rendering info ({@code null} permitted).
651     *
652     * @return The new state instance (never {@code null}).
653     *
654     * @since 1.0.5
655     */
656    protected CategoryItemRendererState createState(PlotRenderingInfo info) {
657        return new CategoryItemRendererState(info);
658    }
659
660    /**
661     * Initialises the renderer and returns a state object that will be used
662     * for the remainder of the drawing process for a single chart.  The state
663     * object allows for the fact that the renderer may be used simultaneously
664     * by multiple threads (each thread will work with a separate state object).
665     *
666     * @param g2  the graphics device.
667     * @param dataArea  the data area.
668     * @param plot  the plot.
669     * @param rendererIndex  the renderer index.
670     * @param info  an object for returning information about the structure of
671     *              the plot ({@code null} permitted).
672     *
673     * @return The renderer state.
674     */
675    @Override
676    public CategoryItemRendererState initialise(Graphics2D g2,
677            Rectangle2D dataArea, CategoryPlot plot, int rendererIndex,
678            PlotRenderingInfo info) {
679
680        setPlot(plot);
681        CategoryDataset data = plot.getDataset(rendererIndex);
682        if (data != null) {
683            this.rowCount = data.getRowCount();
684            this.columnCount = data.getColumnCount();
685        } else {
686            this.rowCount = 0;
687            this.columnCount = 0;
688        }
689        CategoryItemRendererState state = createState(info);
690        state.setElementHinting(plot.fetchElementHintingFlag());
691        int[] visibleSeriesTemp = new int[this.rowCount];
692        int visibleSeriesCount = 0;
693        for (int row = 0; row < this.rowCount; row++) {
694            if (isSeriesVisible(row)) {
695                visibleSeriesTemp[visibleSeriesCount] = row;
696                visibleSeriesCount++;
697            }
698        }
699        int[] visibleSeries = new int[visibleSeriesCount];
700        System.arraycopy(visibleSeriesTemp, 0, visibleSeries, 0,
701                visibleSeriesCount);
702        state.setVisibleSeriesArray(visibleSeries);
703        return state;
704    }
705
706    /**
707     * Adds a {@code KEY_BEGIN_ELEMENT} hint to the graphics target.  This
708     * hint is recognised by <b>JFreeSVG</b> (in theory it could be used by 
709     * other {@code Graphics2D} implementations also).
710     * 
711     * @param g2  the graphics target ({@code null} not permitted).
712     * @param rowKey  the row key that identifies the element ({@code null} not
713     *     permitted).
714     * @param columnKey  the column key that identifies the element 
715     *     ({@code null} not permitted). 
716     * 
717     * @since 1.0.20
718     */
719    protected void beginElementGroup(Graphics2D g2, Comparable rowKey,
720            Comparable columnKey) {
721        beginElementGroup(g2, new KeyedValues2DItemKey(rowKey, columnKey));    
722    }
723    
724    /**
725     * Returns the range of values the renderer requires to display all the
726     * items from the specified dataset.
727     *
728     * @param dataset  the dataset ({@code null} permitted).
729     *
730     * @return The range (or {@code null} if the dataset is
731     *         {@code null} or empty).
732     */
733    @Override
734    public Range findRangeBounds(CategoryDataset dataset) {
735        return findRangeBounds(dataset, false);
736    }
737
738    /**
739     * Returns the range of values the renderer requires to display all the
740     * items from the specified dataset.
741     *
742     * @param dataset  the dataset ({@code null} permitted).
743     * @param includeInterval  include the y-interval if the dataset has one.
744     *
745     * @return The range ({@code null} if the dataset is {@code null}
746     *         or empty).
747     *
748     * @since 1.0.13
749     */
750    protected Range findRangeBounds(CategoryDataset dataset,
751            boolean includeInterval) {
752        if (dataset == null) {
753            return null;
754        }
755        if (getDataBoundsIncludesVisibleSeriesOnly()) {
756            List visibleSeriesKeys = new ArrayList();
757            int seriesCount = dataset.getRowCount();
758            for (int s = 0; s < seriesCount; s++) {
759                if (isSeriesVisible(s)) {
760                    visibleSeriesKeys.add(dataset.getRowKey(s));
761                }
762            }
763            return DatasetUtils.findRangeBounds(dataset,
764                    visibleSeriesKeys, includeInterval);
765        }
766        else {
767            return DatasetUtils.findRangeBounds(dataset, includeInterval);
768        }
769    }
770
771    /**
772     * Returns the Java2D coordinate for the middle of the specified data item.
773     *
774     * @param rowKey  the row key.
775     * @param columnKey  the column key.
776     * @param dataset  the dataset.
777     * @param axis  the axis.
778     * @param area  the data area.
779     * @param edge  the edge along which the axis lies.
780     *
781     * @return The Java2D coordinate for the middle of the item.
782     *
783     * @since 1.0.11
784     */
785    @Override
786    public double getItemMiddle(Comparable rowKey, Comparable columnKey,
787            CategoryDataset dataset, CategoryAxis axis, Rectangle2D area,
788            RectangleEdge edge) {
789        return axis.getCategoryMiddle(columnKey, dataset.getColumnKeys(), area,
790                edge);
791    }
792
793    /**
794     * Draws a background for the data area.  The default implementation just
795     * gets the plot to draw the background, but some renderers will override
796     * this behaviour.
797     *
798     * @param g2  the graphics device.
799     * @param plot  the plot.
800     * @param dataArea  the data area.
801     */
802    @Override
803    public void drawBackground(Graphics2D g2, CategoryPlot plot,
804            Rectangle2D dataArea) {
805        plot.drawBackground(g2, dataArea);
806    }
807
808    /**
809     * Draws an outline for the data area.  The default implementation just
810     * gets the plot to draw the outline, but some renderers will override this
811     * behaviour.
812     *
813     * @param g2  the graphics device.
814     * @param plot  the plot.
815     * @param dataArea  the data area.
816     */
817    @Override
818    public void drawOutline(Graphics2D g2, CategoryPlot plot,
819            Rectangle2D dataArea) {
820        plot.drawOutline(g2, dataArea);
821    }
822
823    /**
824     * Draws a grid line against the domain axis.
825     * <P>
826     * Note that this default implementation assumes that the horizontal axis
827     * is the domain axis. If this is not the case, you will need to override
828     * this method.
829     *
830     * @param g2  the graphics device.
831     * @param plot  the plot.
832     * @param dataArea  the area for plotting data.
833     * @param value  the Java2D value at which the grid line should be drawn.
834     *
835     */
836    @Override
837    public void drawDomainGridline(Graphics2D g2, CategoryPlot plot,
838           Rectangle2D dataArea, double value) {
839
840        Line2D line = null;
841        PlotOrientation orientation = plot.getOrientation();
842
843        if (orientation == PlotOrientation.HORIZONTAL) {
844            line = new Line2D.Double(dataArea.getMinX(), value,
845                    dataArea.getMaxX(), value);
846        }
847        else if (orientation == PlotOrientation.VERTICAL) {
848            line = new Line2D.Double(value, dataArea.getMinY(), value,
849                    dataArea.getMaxY());
850        }
851
852        Paint paint = plot.getDomainGridlinePaint();
853        if (paint == null) {
854            paint = CategoryPlot.DEFAULT_GRIDLINE_PAINT;
855        }
856        g2.setPaint(paint);
857
858        Stroke stroke = plot.getDomainGridlineStroke();
859        if (stroke == null) {
860            stroke = CategoryPlot.DEFAULT_GRIDLINE_STROKE;
861        }
862        g2.setStroke(stroke);
863        Object saved = g2.getRenderingHint(RenderingHints.KEY_STROKE_CONTROL);
864        g2.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL, 
865                RenderingHints.VALUE_STROKE_NORMALIZE);
866        g2.draw(line);
867        g2.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL, saved);
868    }
869
870    /**
871     * Draws a line perpendicular to the range axis.
872     *
873     * @param g2  the graphics device.
874     * @param plot  the plot.
875     * @param axis  the value axis.
876     * @param dataArea  the area for plotting data (not yet adjusted for any 3D
877     *                  effect).
878     * @param value  the value at which the grid line should be drawn.
879     * @param paint  the paint ({@code null} not permitted).
880     * @param stroke  the stroke ({@code null} not permitted).
881     *
882     * @since 1.0.13
883     */
884    @Override
885    public void drawRangeLine(Graphics2D g2, CategoryPlot plot, ValueAxis axis,
886            Rectangle2D dataArea, double value, Paint paint, Stroke stroke) {
887
888        Range range = axis.getRange();
889        if (!range.contains(value)) {
890            return;
891        }
892
893        PlotOrientation orientation = plot.getOrientation();
894        Line2D line = null;
895        double v = axis.valueToJava2D(value, dataArea, plot.getRangeAxisEdge());
896        if (orientation == PlotOrientation.HORIZONTAL) {
897            line = new Line2D.Double(v, dataArea.getMinY(), v,
898                    dataArea.getMaxY());
899        } else if (orientation == PlotOrientation.VERTICAL) {
900            line = new Line2D.Double(dataArea.getMinX(), v,
901                    dataArea.getMaxX(), v);
902        }
903
904        g2.setPaint(paint);
905        g2.setStroke(stroke);
906        Object saved = g2.getRenderingHint(RenderingHints.KEY_STROKE_CONTROL);
907        g2.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL, 
908                RenderingHints.VALUE_STROKE_NORMALIZE);
909        g2.draw(line);
910        g2.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL, saved);
911    }
912
913    /**
914     * Draws a marker for the domain axis.
915     *
916     * @param g2  the graphics device (not {@code null}).
917     * @param plot  the plot (not {@code null}).
918     * @param axis  the range axis (not {@code null}).
919     * @param marker  the marker to be drawn (not {@code null}).
920     * @param dataArea  the area inside the axes (not {@code null}).
921     *
922     * @see #drawRangeMarker(Graphics2D, CategoryPlot, ValueAxis, Marker,
923     *     Rectangle2D)
924     */
925    @Override
926    public void drawDomainMarker(Graphics2D g2, CategoryPlot plot,
927            CategoryAxis axis, CategoryMarker marker, Rectangle2D dataArea) {
928
929        Comparable category = marker.getKey();
930        CategoryDataset dataset = plot.getDataset(plot.getIndexOf(this));
931        int columnIndex = dataset.getColumnIndex(category);
932        if (columnIndex < 0) {
933            return;
934        }
935
936        final Composite savedComposite = g2.getComposite();
937        g2.setComposite(AlphaComposite.getInstance(
938                AlphaComposite.SRC_OVER, marker.getAlpha()));
939
940        PlotOrientation orientation = plot.getOrientation();
941        Rectangle2D bounds;
942        if (marker.getDrawAsLine()) {
943            double v = axis.getCategoryMiddle(columnIndex,
944                    dataset.getColumnCount(), dataArea,
945                    plot.getDomainAxisEdge());
946            Line2D line = null;
947            if (orientation == PlotOrientation.HORIZONTAL) {
948                line = new Line2D.Double(dataArea.getMinX(), v,
949                        dataArea.getMaxX(), v);
950            }
951            else if (orientation == PlotOrientation.VERTICAL) {
952                line = new Line2D.Double(v, dataArea.getMinY(), v,
953                        dataArea.getMaxY());
954            } else {
955                throw new IllegalStateException();
956            }
957            g2.setPaint(marker.getPaint());
958            g2.setStroke(marker.getStroke());
959            g2.draw(line);
960            bounds = line.getBounds2D();
961        }
962        else {
963            double v0 = axis.getCategoryStart(columnIndex,
964                    dataset.getColumnCount(), dataArea,
965                    plot.getDomainAxisEdge());
966            double v1 = axis.getCategoryEnd(columnIndex,
967                    dataset.getColumnCount(), dataArea,
968                    plot.getDomainAxisEdge());
969            Rectangle2D area = null;
970            if (orientation == PlotOrientation.HORIZONTAL) {
971                area = new Rectangle2D.Double(dataArea.getMinX(), v0,
972                        dataArea.getWidth(), (v1 - v0));
973            }
974            else if (orientation == PlotOrientation.VERTICAL) {
975                area = new Rectangle2D.Double(v0, dataArea.getMinY(),
976                        (v1 - v0), dataArea.getHeight());
977            }
978            g2.setPaint(marker.getPaint());
979            g2.fill(area);
980            bounds = area;
981        }
982
983        String label = marker.getLabel();
984        RectangleAnchor anchor = marker.getLabelAnchor();
985        if (label != null) {
986            Font labelFont = marker.getLabelFont();
987            g2.setFont(labelFont);
988            g2.setPaint(marker.getLabelPaint());
989            Point2D coordinates = calculateDomainMarkerTextAnchorPoint(
990                    g2, orientation, dataArea, bounds, marker.getLabelOffset(),
991                    marker.getLabelOffsetType(), anchor);
992            TextUtils.drawAlignedString(label, g2,
993                    (float) coordinates.getX(), (float) coordinates.getY(),
994                    marker.getLabelTextAnchor());
995        }
996        g2.setComposite(savedComposite);
997    }
998
999    /**
1000     * Draws a marker for the range axis.
1001     *
1002     * @param g2  the graphics device (not {@code null}).
1003     * @param plot  the plot (not {@code null}).
1004     * @param axis  the range axis (not {@code null}).
1005     * @param marker  the marker to be drawn (not {@code null}).
1006     * @param dataArea  the area inside the axes (not {@code null}).
1007     *
1008     * @see #drawDomainMarker(Graphics2D, CategoryPlot, CategoryAxis,
1009     *     CategoryMarker, Rectangle2D)
1010     */
1011    @Override
1012    public void drawRangeMarker(Graphics2D g2, CategoryPlot plot,
1013            ValueAxis axis, Marker marker, Rectangle2D dataArea) {
1014
1015        if (marker instanceof ValueMarker) {
1016            ValueMarker vm = (ValueMarker) marker;
1017            double value = vm.getValue();
1018            Range range = axis.getRange();
1019
1020            if (!range.contains(value)) {
1021                return;
1022            }
1023
1024            final Composite savedComposite = g2.getComposite();
1025            g2.setComposite(AlphaComposite.getInstance(
1026                    AlphaComposite.SRC_OVER, marker.getAlpha()));
1027
1028            PlotOrientation orientation = plot.getOrientation();
1029            double v = axis.valueToJava2D(value, dataArea,
1030                    plot.getRangeAxisEdge());
1031            Line2D line = null;
1032            if (orientation == PlotOrientation.HORIZONTAL) {
1033                line = new Line2D.Double(v, dataArea.getMinY(), v,
1034                        dataArea.getMaxY());
1035            }
1036            else if (orientation == PlotOrientation.VERTICAL) {
1037                line = new Line2D.Double(dataArea.getMinX(), v,
1038                        dataArea.getMaxX(), v);
1039            } else {
1040                throw new IllegalStateException();
1041            }
1042
1043            g2.setPaint(marker.getPaint());
1044            g2.setStroke(marker.getStroke());
1045            g2.draw(line);
1046
1047            String label = marker.getLabel();
1048            RectangleAnchor anchor = marker.getLabelAnchor();
1049            if (label != null) {
1050                Font labelFont = marker.getLabelFont();
1051                g2.setFont(labelFont);
1052                Point2D coordinates = calculateRangeMarkerTextAnchorPoint(
1053                        g2, orientation, dataArea, line.getBounds2D(),
1054                        marker.getLabelOffset(), LengthAdjustmentType.EXPAND,
1055                        anchor);
1056                Rectangle2D rect = TextUtils.calcAlignedStringBounds(label, g2, 
1057                        (float) coordinates.getX(), (float) coordinates.getY(), 
1058                        marker.getLabelTextAnchor());
1059                g2.setPaint(marker.getLabelBackgroundColor());
1060                g2.fill(rect);
1061                g2.setPaint(marker.getLabelPaint());
1062                TextUtils.drawAlignedString(label, g2, 
1063                        (float) coordinates.getX(), (float) coordinates.getY(),
1064                        marker.getLabelTextAnchor());
1065            }
1066            g2.setComposite(savedComposite);
1067        }
1068        else if (marker instanceof IntervalMarker) {
1069            IntervalMarker im = (IntervalMarker) marker;
1070            double start = im.getStartValue();
1071            double end = im.getEndValue();
1072            Range range = axis.getRange();
1073            if (!(range.intersects(start, end))) {
1074                return;
1075            }
1076
1077            final Composite savedComposite = g2.getComposite();
1078            g2.setComposite(AlphaComposite.getInstance(
1079                    AlphaComposite.SRC_OVER, marker.getAlpha()));
1080
1081            double start2d = axis.valueToJava2D(start, dataArea,
1082                    plot.getRangeAxisEdge());
1083            double end2d = axis.valueToJava2D(end, dataArea,
1084                    plot.getRangeAxisEdge());
1085            double low = Math.min(start2d, end2d);
1086            double high = Math.max(start2d, end2d);
1087
1088            PlotOrientation orientation = plot.getOrientation();
1089            Rectangle2D rect = null;
1090            if (orientation == PlotOrientation.HORIZONTAL) {
1091                // clip left and right bounds to data area
1092                low = Math.max(low, dataArea.getMinX());
1093                high = Math.min(high, dataArea.getMaxX());
1094                rect = new Rectangle2D.Double(low,
1095                        dataArea.getMinY(), high - low,
1096                        dataArea.getHeight());
1097            }
1098            else if (orientation == PlotOrientation.VERTICAL) {
1099                // clip top and bottom bounds to data area
1100                low = Math.max(low, dataArea.getMinY());
1101                high = Math.min(high, dataArea.getMaxY());
1102                rect = new Rectangle2D.Double(dataArea.getMinX(),
1103                        low, dataArea.getWidth(),
1104                        high - low);
1105            }
1106            Paint p = marker.getPaint();
1107            if (p instanceof GradientPaint) {
1108                GradientPaint gp = (GradientPaint) p;
1109                GradientPaintTransformer t = im.getGradientPaintTransformer();
1110                if (t != null) {
1111                    gp = t.transform(gp, rect);
1112                }
1113                g2.setPaint(gp);
1114            }
1115            else {
1116                g2.setPaint(p);
1117            }
1118            g2.fill(rect);
1119
1120            // now draw the outlines, if visible...
1121            if (im.getOutlinePaint() != null && im.getOutlineStroke() != null) {
1122                if (orientation == PlotOrientation.VERTICAL) {
1123                    Line2D line = new Line2D.Double();
1124                    double x0 = dataArea.getMinX();
1125                    double x1 = dataArea.getMaxX();
1126                    g2.setPaint(im.getOutlinePaint());
1127                    g2.setStroke(im.getOutlineStroke());
1128                    if (range.contains(start)) {
1129                        line.setLine(x0, start2d, x1, start2d);
1130                        g2.draw(line);
1131                    }
1132                    if (range.contains(end)) {
1133                        line.setLine(x0, end2d, x1, end2d);
1134                        g2.draw(line);
1135                    }
1136                } else { // PlotOrientation.HORIZONTAL
1137                    Line2D line = new Line2D.Double();
1138                    double y0 = dataArea.getMinY();
1139                    double y1 = dataArea.getMaxY();
1140                    g2.setPaint(im.getOutlinePaint());
1141                    g2.setStroke(im.getOutlineStroke());
1142                    if (range.contains(start)) {
1143                        line.setLine(start2d, y0, start2d, y1);
1144                        g2.draw(line);
1145                    }
1146                    if (range.contains(end)) {
1147                        line.setLine(end2d, y0, end2d, y1);
1148                        g2.draw(line);
1149                    }
1150                }
1151            }
1152
1153            String label = marker.getLabel();
1154            RectangleAnchor anchor = marker.getLabelAnchor();
1155            if (label != null) {
1156                Font labelFont = marker.getLabelFont();
1157                g2.setFont(labelFont);
1158                Point2D coords = calculateRangeMarkerTextAnchorPoint(
1159                        g2, orientation, dataArea, rect,
1160                        marker.getLabelOffset(), marker.getLabelOffsetType(),
1161                        anchor);
1162                Rectangle2D r = TextUtils.calcAlignedStringBounds(label, 
1163                        g2, (float) coords.getX(), (float) coords.getY(), 
1164                        marker.getLabelTextAnchor());
1165                g2.setPaint(marker.getLabelBackgroundColor());
1166                g2.fill(r);
1167                g2.setPaint(marker.getLabelPaint());
1168                TextUtils.drawAlignedString(label, g2,
1169                        (float) coords.getX(), (float) coords.getY(),
1170                        marker.getLabelTextAnchor());
1171            }
1172            g2.setComposite(savedComposite);
1173        }
1174    }
1175
1176    /**
1177     * Calculates the {@code (x, y)} coordinates for drawing the label for a 
1178     * marker on the range axis.
1179     *
1180     * @param g2  the graphics device.
1181     * @param orientation  the plot orientation.
1182     * @param dataArea  the data area.
1183     * @param markerArea  the rectangle surrounding the marker.
1184     * @param markerOffset  the marker offset.
1185     * @param labelOffsetType  the label offset type.
1186     * @param anchor  the label anchor.
1187     *
1188     * @return The coordinates for drawing the marker label.
1189     */
1190    protected Point2D calculateDomainMarkerTextAnchorPoint(Graphics2D g2,
1191            PlotOrientation orientation, Rectangle2D dataArea,
1192            Rectangle2D markerArea, RectangleInsets markerOffset,
1193            LengthAdjustmentType labelOffsetType, RectangleAnchor anchor) {
1194
1195        Rectangle2D anchorRect = null;
1196        if (orientation == PlotOrientation.HORIZONTAL) {
1197            anchorRect = markerOffset.createAdjustedRectangle(markerArea,
1198                    LengthAdjustmentType.CONTRACT, labelOffsetType);
1199        } else if (orientation == PlotOrientation.VERTICAL) {
1200            anchorRect = markerOffset.createAdjustedRectangle(markerArea,
1201                    labelOffsetType, LengthAdjustmentType.CONTRACT);
1202        }
1203        return anchor.getAnchorPoint(anchorRect);
1204    }
1205
1206    /**
1207     * Calculates the (x, y) coordinates for drawing a marker label.
1208     *
1209     * @param g2  the graphics device.
1210     * @param orientation  the plot orientation.
1211     * @param dataArea  the data area.
1212     * @param markerArea  the rectangle surrounding the marker.
1213     * @param markerOffset  the marker offset.
1214     * @param labelOffsetType  the label offset type.
1215     * @param anchor  the label anchor.
1216     *
1217     * @return The coordinates for drawing the marker label.
1218     */
1219    protected Point2D calculateRangeMarkerTextAnchorPoint(Graphics2D g2,
1220            PlotOrientation orientation, Rectangle2D dataArea,
1221            Rectangle2D markerArea, RectangleInsets markerOffset,
1222            LengthAdjustmentType labelOffsetType, RectangleAnchor anchor) {
1223
1224        Rectangle2D anchorRect = null;
1225        if (orientation == PlotOrientation.HORIZONTAL) {
1226            anchorRect = markerOffset.createAdjustedRectangle(markerArea,
1227                    labelOffsetType, LengthAdjustmentType.CONTRACT);
1228        } else if (orientation == PlotOrientation.VERTICAL) {
1229            anchorRect = markerOffset.createAdjustedRectangle(markerArea,
1230                    LengthAdjustmentType.CONTRACT, labelOffsetType);
1231        }
1232        return anchor.getAnchorPoint(anchorRect);
1233
1234    }
1235
1236    /**
1237     * Returns a legend item for a series.  This default implementation will
1238     * return {@code null} if {@link #isSeriesVisible(int)} or
1239     * {@link #isSeriesVisibleInLegend(int)} returns {@code false}.
1240     *
1241     * @param datasetIndex  the dataset index (zero-based).
1242     * @param series  the series index (zero-based).
1243     *
1244     * @return The legend item (possibly {@code null}).
1245     *
1246     * @see #getLegendItems()
1247     */
1248    @Override
1249    public LegendItem getLegendItem(int datasetIndex, int series) {
1250
1251        CategoryPlot p = getPlot();
1252        if (p == null) {
1253            return null;
1254        }
1255
1256        // check that a legend item needs to be displayed...
1257        if (!isSeriesVisible(series) || !isSeriesVisibleInLegend(series)) {
1258            return null;
1259        }
1260
1261        CategoryDataset dataset = p.getDataset(datasetIndex);
1262        String label = this.legendItemLabelGenerator.generateLabel(dataset,
1263                series);
1264        String description = label;
1265        String toolTipText = null;
1266        if (this.legendItemToolTipGenerator != null) {
1267            toolTipText = this.legendItemToolTipGenerator.generateLabel(
1268                    dataset, series);
1269        }
1270        String urlText = null;
1271        if (this.legendItemURLGenerator != null) {
1272            urlText = this.legendItemURLGenerator.generateLabel(dataset,
1273                    series);
1274        }
1275        Shape shape = lookupLegendShape(series);
1276        Paint paint = lookupSeriesPaint(series);
1277        Paint outlinePaint = lookupSeriesOutlinePaint(series);
1278        Stroke outlineStroke = lookupSeriesOutlineStroke(series);
1279
1280        LegendItem item = new LegendItem(label, description, toolTipText,
1281                urlText, shape, paint, outlineStroke, outlinePaint);
1282        item.setLabelFont(lookupLegendTextFont(series));
1283        Paint labelPaint = lookupLegendTextPaint(series);
1284        if (labelPaint != null) {
1285            item.setLabelPaint(labelPaint);
1286        }
1287        item.setSeriesKey(dataset.getRowKey(series));
1288        item.setSeriesIndex(series);
1289        item.setDataset(dataset);
1290        item.setDatasetIndex(datasetIndex);
1291        return item;
1292    }
1293
1294    /**
1295     * Tests this renderer for equality with another object.
1296     *
1297     * @param obj  the object.
1298     *
1299     * @return {@code true} or {@code false}.
1300     */
1301    @Override
1302    public boolean equals(Object obj) {
1303        if (obj == this) {
1304            return true;
1305        }
1306        if (!(obj instanceof AbstractCategoryItemRenderer)) {
1307            return false;
1308        }
1309        AbstractCategoryItemRenderer that = (AbstractCategoryItemRenderer) obj;
1310
1311        if (!ObjectUtils.equal(this.itemLabelGeneratorMap,
1312                that.itemLabelGeneratorMap)) {
1313            return false;
1314        }
1315        if (!ObjectUtils.equal(this.defaultItemLabelGenerator,
1316                that.defaultItemLabelGenerator)) {
1317            return false;
1318        }
1319        if (!ObjectUtils.equal(this.toolTipGeneratorMap,
1320                that.toolTipGeneratorMap)) {
1321            return false;
1322        }
1323        if (!ObjectUtils.equal(this.defaultToolTipGenerator,
1324                that.defaultToolTipGenerator)) {
1325            return false;
1326        }
1327        if (!ObjectUtils.equal(this.itemURLGeneratorMap,
1328                that.itemURLGeneratorMap)) {
1329            return false;
1330        }
1331        if (!ObjectUtils.equal(this.defaultItemURLGenerator,
1332                that.defaultItemURLGenerator)) {
1333            return false;
1334        }
1335        if (!ObjectUtils.equal(this.legendItemLabelGenerator,
1336                that.legendItemLabelGenerator)) {
1337            return false;
1338        }
1339        if (!ObjectUtils.equal(this.legendItemToolTipGenerator,
1340                that.legendItemToolTipGenerator)) {
1341            return false;
1342        }
1343        if (!ObjectUtils.equal(this.legendItemURLGenerator,
1344                that.legendItemURLGenerator)) {
1345            return false;
1346        }
1347        return super.equals(obj);
1348    }
1349
1350    /**
1351     * Returns a hash code for the renderer.
1352     *
1353     * @return The hash code.
1354     */
1355    @Override
1356    public int hashCode() {
1357        int result = super.hashCode();
1358        return result;
1359    }
1360
1361    /**
1362     * Returns the drawing supplier from the plot.
1363     *
1364     * @return The drawing supplier (possibly {@code null}).
1365     */
1366    @Override
1367    public DrawingSupplier getDrawingSupplier() {
1368        DrawingSupplier result = null;
1369        CategoryPlot cp = getPlot();
1370        if (cp != null) {
1371            result = cp.getDrawingSupplier();
1372        }
1373        return result;
1374    }
1375
1376    /**
1377     * Considers the current (x, y) coordinate and updates the crosshair point
1378     * if it meets the criteria (usually means the (x, y) coordinate is the
1379     * closest to the anchor point so far).
1380     *
1381     * @param crosshairState  the crosshair state ({@code null} permitted,
1382     *                        but the method does nothing in that case).
1383     * @param rowKey  the row key.
1384     * @param columnKey  the column key.
1385     * @param value  the data value.
1386     * @param datasetIndex  the dataset index.
1387     * @param transX  the x-value translated to Java2D space.
1388     * @param transY  the y-value translated to Java2D space.
1389     * @param orientation  the plot orientation ({@code null} not
1390     *                     permitted).
1391     *
1392     * @since 1.0.11
1393     */
1394    protected void updateCrosshairValues(CategoryCrosshairState crosshairState,
1395            Comparable rowKey, Comparable columnKey, double value,
1396            int datasetIndex,
1397            double transX, double transY, PlotOrientation orientation) {
1398
1399        Args.nullNotPermitted(orientation, "orientation");
1400
1401        if (crosshairState != null) {
1402            if (this.plot.isRangeCrosshairLockedOnData()) {
1403                // both axes
1404                crosshairState.updateCrosshairPoint(rowKey, columnKey, value,
1405                        datasetIndex, transX, transY, orientation);
1406            }
1407            else {
1408                crosshairState.updateCrosshairX(rowKey, columnKey,
1409                        datasetIndex, transX, orientation);
1410            }
1411        }
1412    }
1413
1414    /**
1415     * Draws an item label.
1416     *
1417     * @param g2  the graphics device.
1418     * @param orientation  the orientation.
1419     * @param dataset  the dataset.
1420     * @param row  the row.
1421     * @param column  the column.
1422     * @param x  the x coordinate (in Java2D space).
1423     * @param y  the y coordinate (in Java2D space).
1424     * @param negative  indicates a negative value (which affects the item
1425     *                  label position).
1426     */
1427    protected void drawItemLabel(Graphics2D g2, PlotOrientation orientation,
1428            CategoryDataset dataset, int row, int column,
1429            double x, double y, boolean negative) {
1430
1431        CategoryItemLabelGenerator generator = getItemLabelGenerator(row,
1432                column);
1433        if (generator != null) {
1434            Font labelFont = getItemLabelFont(row, column);
1435            Paint paint = getItemLabelPaint(row, column);
1436            g2.setFont(labelFont);
1437            g2.setPaint(paint);
1438            String label = generator.generateLabel(dataset, row, column);
1439            ItemLabelPosition position;
1440            if (!negative) {
1441                position = getPositiveItemLabelPosition(row, column);
1442            }
1443            else {
1444                position = getNegativeItemLabelPosition(row, column);
1445            }
1446            Point2D anchorPoint = calculateLabelAnchorPoint(
1447                    position.getItemLabelAnchor(), x, y, orientation);
1448            TextUtils.drawRotatedString(label, g2,
1449                    (float) anchorPoint.getX(), (float) anchorPoint.getY(),
1450                    position.getTextAnchor(),
1451                    position.getAngle(), position.getRotationAnchor());
1452        }
1453
1454    }
1455
1456    /**
1457     * Returns an independent copy of the renderer.  The {@code plot}
1458     * reference is shallow copied.
1459     *
1460     * @return A clone.
1461     *
1462     * @throws CloneNotSupportedException  can be thrown if one of the objects
1463     *         belonging to the renderer does not support cloning (for example,
1464     *         an item label generator).
1465     */
1466    @Override
1467    public Object clone() throws CloneNotSupportedException {
1468        AbstractCategoryItemRenderer clone
1469            = (AbstractCategoryItemRenderer) super.clone();
1470
1471        if (this.itemLabelGeneratorMap != null) {
1472            clone.itemLabelGeneratorMap = CloneUtils.cloneMapValues(
1473                    this.itemLabelGeneratorMap);
1474        }
1475
1476        if (this.defaultItemLabelGenerator != null) {
1477            if (this.defaultItemLabelGenerator instanceof PublicCloneable) {
1478                PublicCloneable pc
1479                        = (PublicCloneable) this.defaultItemLabelGenerator;
1480                clone.defaultItemLabelGenerator
1481                        = (CategoryItemLabelGenerator) pc.clone();
1482            }
1483            else {
1484                throw new CloneNotSupportedException(
1485                        "ItemLabelGenerator not cloneable.");
1486            }
1487        }
1488
1489        if (this.toolTipGeneratorMap != null) {
1490            clone.toolTipGeneratorMap = CloneUtils.cloneMapValues(
1491                    this.toolTipGeneratorMap);
1492        }
1493
1494        if (this.defaultToolTipGenerator != null) {
1495            if (this.defaultToolTipGenerator instanceof PublicCloneable) {
1496                PublicCloneable pc
1497                        = (PublicCloneable) this.defaultToolTipGenerator;
1498                clone.defaultToolTipGenerator
1499                        = (CategoryToolTipGenerator) pc.clone();
1500            }
1501            else {
1502                throw new CloneNotSupportedException(
1503                        "Default tool tip generator not cloneable.");
1504            }
1505        }
1506
1507        if (this.itemURLGeneratorMap != null) {
1508            clone.itemURLGeneratorMap = CloneUtils.cloneMapValues(
1509                    this.itemURLGeneratorMap);
1510        }
1511
1512        if (this.defaultItemURLGenerator != null) {
1513            if (this.defaultItemURLGenerator instanceof PublicCloneable) {
1514                PublicCloneable pc
1515                        = (PublicCloneable) this.defaultItemURLGenerator;
1516                clone.defaultItemURLGenerator = (CategoryURLGenerator) pc.clone();
1517            }
1518            else {
1519                throw new CloneNotSupportedException(
1520                        "Default item URL generator not cloneable.");
1521            }
1522        }
1523
1524        if (this.legendItemLabelGenerator instanceof PublicCloneable) {
1525            clone.legendItemLabelGenerator = (CategorySeriesLabelGenerator)
1526                    ObjectUtils.clone(this.legendItemLabelGenerator);
1527        }
1528        if (this.legendItemToolTipGenerator instanceof PublicCloneable) {
1529            clone.legendItemToolTipGenerator = (CategorySeriesLabelGenerator)
1530                    ObjectUtils.clone(this.legendItemToolTipGenerator);
1531        }
1532        if (this.legendItemURLGenerator instanceof PublicCloneable) {
1533            clone.legendItemURLGenerator = (CategorySeriesLabelGenerator)
1534                    ObjectUtils.clone(this.legendItemURLGenerator);
1535        }
1536        return clone;
1537    }
1538
1539    /**
1540     * Returns a domain axis for a plot.
1541     *
1542     * @param plot  the plot.
1543     * @param index  the axis index.
1544     *
1545     * @return A domain axis.
1546     */
1547    protected CategoryAxis getDomainAxis(CategoryPlot plot, int index) {
1548        CategoryAxis result = plot.getDomainAxis(index);
1549        if (result == null) {
1550            result = plot.getDomainAxis();
1551        }
1552        return result;
1553    }
1554
1555    /**
1556     * Returns a range axis for a plot.
1557     *
1558     * @param plot  the plot.
1559     * @param index  the axis index.
1560     *
1561     * @return A range axis.
1562     */
1563    protected ValueAxis getRangeAxis(CategoryPlot plot, int index) {
1564        ValueAxis result = plot.getRangeAxis(index);
1565        if (result == null) {
1566            result = plot.getRangeAxis();
1567        }
1568        return result;
1569    }
1570
1571    /**
1572     * Returns a (possibly empty) collection of legend items for the series
1573     * that this renderer is responsible for drawing.
1574     *
1575     * @return The legend item collection (never {@code null}).
1576     *
1577     * @see #getLegendItem(int, int)
1578     */
1579    @Override
1580    public LegendItemCollection getLegendItems() {
1581        LegendItemCollection result = new LegendItemCollection();
1582        if (this.plot == null) {
1583            return result;
1584        }
1585        int index = this.plot.getIndexOf(this);
1586        CategoryDataset dataset = this.plot.getDataset(index);
1587        if (dataset == null) {
1588            return result;
1589        }
1590        int seriesCount = dataset.getRowCount();
1591        if (plot.getRowRenderingOrder().equals(SortOrder.ASCENDING)) {
1592            for (int i = 0; i < seriesCount; i++) {
1593                if (isSeriesVisibleInLegend(i)) {
1594                    LegendItem item = getLegendItem(index, i);
1595                    if (item != null) {
1596                        result.add(item);
1597                    }
1598                }
1599            }
1600        }
1601        else {
1602            for (int i = seriesCount - 1; i >= 0; i--) {
1603                if (isSeriesVisibleInLegend(i)) {
1604                    LegendItem item = getLegendItem(index, i);
1605                    if (item != null) {
1606                        result.add(item);
1607                    }
1608                }
1609            }
1610        }
1611        return result;
1612    }
1613
1614    /**
1615     * Returns the legend item label generator.
1616     *
1617     * @return The label generator (never {@code null}).
1618     *
1619     * @see #setLegendItemLabelGenerator(CategorySeriesLabelGenerator)
1620     */
1621    public CategorySeriesLabelGenerator getLegendItemLabelGenerator() {
1622        return this.legendItemLabelGenerator;
1623    }
1624
1625    /**
1626     * Sets the legend item label generator and sends a
1627     * {@link RendererChangeEvent} to all registered listeners.
1628     *
1629     * @param generator  the generator ({@code null} not permitted).
1630     *
1631     * @see #getLegendItemLabelGenerator()
1632     */
1633    public void setLegendItemLabelGenerator(
1634            CategorySeriesLabelGenerator generator) {
1635        Args.nullNotPermitted(generator, "generator");
1636        this.legendItemLabelGenerator = generator;
1637        fireChangeEvent();
1638    }
1639
1640    /**
1641     * Returns the legend item tool tip generator.
1642     *
1643     * @return The tool tip generator (possibly {@code null}).
1644     *
1645     * @see #setLegendItemToolTipGenerator(CategorySeriesLabelGenerator)
1646     */
1647    public CategorySeriesLabelGenerator getLegendItemToolTipGenerator() {
1648        return this.legendItemToolTipGenerator;
1649    }
1650
1651    /**
1652     * Sets the legend item tool tip generator and sends a
1653     * {@link RendererChangeEvent} to all registered listeners.
1654     *
1655     * @param generator  the generator ({@code null} permitted).
1656     *
1657     * @see #setLegendItemToolTipGenerator(CategorySeriesLabelGenerator)
1658     */
1659    public void setLegendItemToolTipGenerator(
1660            CategorySeriesLabelGenerator generator) {
1661        this.legendItemToolTipGenerator = generator;
1662        fireChangeEvent();
1663    }
1664
1665    /**
1666     * Returns the legend item URL generator.
1667     *
1668     * @return The URL generator (possibly {@code null}).
1669     *
1670     * @see #setLegendItemURLGenerator(CategorySeriesLabelGenerator)
1671     */
1672    public CategorySeriesLabelGenerator getLegendItemURLGenerator() {
1673        return this.legendItemURLGenerator;
1674    }
1675
1676    /**
1677     * Sets the legend item URL generator and sends a
1678     * {@link RendererChangeEvent} to all registered listeners.
1679     *
1680     * @param generator  the generator ({@code null} permitted).
1681     *
1682     * @see #getLegendItemURLGenerator()
1683     */
1684    public void setLegendItemURLGenerator(
1685            CategorySeriesLabelGenerator generator) {
1686        this.legendItemURLGenerator = generator;
1687        fireChangeEvent();
1688    }
1689    
1690    /**
1691     * Adds an entity with the specified hotspot.
1692     *
1693     * @param entities  the entity collection.
1694     * @param dataset  the dataset.
1695     * @param row  the row index.
1696     * @param column  the column index.
1697     * @param hotspot  the hotspot ({@code null} not permitted).
1698     */
1699    protected void addItemEntity(EntityCollection entities,
1700            CategoryDataset dataset, int row, int column, Shape hotspot) {
1701        Args.nullNotPermitted(hotspot, "hotspot");
1702        if (!getItemCreateEntity(row, column)) {
1703            return;
1704        }
1705        String tip = null;
1706        CategoryToolTipGenerator tipster = getToolTipGenerator(row, column);
1707        if (tipster != null) {
1708            tip = tipster.generateToolTip(dataset, row, column);
1709        }
1710        String url = null;
1711        CategoryURLGenerator urlster = getItemURLGenerator(row, column);
1712        if (urlster != null) {
1713            url = urlster.generateURL(dataset, row, column);
1714        }
1715        CategoryItemEntity entity = new CategoryItemEntity(hotspot, tip, url,
1716                dataset, dataset.getRowKey(row), dataset.getColumnKey(column));
1717        entities.add(entity);
1718    }
1719
1720    /**
1721     * Adds an entity to the collection.
1722     *
1723     * @param entities  the entity collection being populated.
1724     * @param hotspot  the entity area (if {@code null} a default will be
1725     *              used).
1726     * @param dataset  the dataset.
1727     * @param row  the series.
1728     * @param column  the item.
1729     * @param entityX  the entity's center x-coordinate in user space (only
1730     *                 used if {@code area} is {@code null}).
1731     * @param entityY  the entity's center y-coordinate in user space (only
1732     *                 used if {@code area} is {@code null}).
1733     *
1734     * @since 1.0.13
1735     */
1736    protected void addEntity(EntityCollection entities, Shape hotspot,
1737                             CategoryDataset dataset, int row, int column,
1738                             double entityX, double entityY) {
1739        if (!getItemCreateEntity(row, column)) {
1740            return;
1741        }
1742        Shape s = hotspot;
1743        if (hotspot == null) {
1744            double r = getDefaultEntityRadius();
1745            double w = r * 2;
1746            if (getPlot().getOrientation() == PlotOrientation.VERTICAL) {
1747                s = new Ellipse2D.Double(entityX - r, entityY - r, w, w);
1748            }
1749            else {
1750                s = new Ellipse2D.Double(entityY - r, entityX - r, w, w);
1751            }
1752        }
1753        String tip = null;
1754        CategoryToolTipGenerator generator = getToolTipGenerator(row, column);
1755        if (generator != null) {
1756            tip = generator.generateToolTip(dataset, row, column);
1757        }
1758        String url = null;
1759        CategoryURLGenerator urlster = getItemURLGenerator(row, column);
1760        if (urlster != null) {
1761            url = urlster.generateURL(dataset, row, column);
1762        }
1763        CategoryItemEntity entity = new CategoryItemEntity(s, tip, url,
1764                dataset, dataset.getRowKey(row), dataset.getColumnKey(column));
1765        entities.add(entity);
1766    }
1767
1768}