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 * XYItemRenderer.java
029 * -------------------
030 * (C) Copyright 2001-2017, by Object Refinery Limited and Contributors.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   Mark Watson (www.markwatson.com);
034 *                   Sylvain Vieujot;
035 *                   Focus Computer Services Limited;
036 *                   Richard Atkinson;
037 *
038 * Changes
039 * -------
040 * 19-Oct-2001 : Version 1, based on code by Mark Watson (DG);
041 * 22-Oct-2001 : Renamed DataSource.java --> Dataset.java etc. (DG);
042 * 13-Dec-2001 : Changed return type of drawItem from void --> Shape.  The area
043 *               returned can be used as the tooltip region.
044 * 23-Jan-2002 : Added DrawInfo parameter to drawItem() method (DG);
045 * 28-Mar-2002 : Added a property change listener mechanism.  Now renderers do
046 *               not have to be immutable (DG);
047 * 04-Apr-2002 : Added the initialise() method (DG);
048 * 09-Apr-2002 : Removed the translated zero from the drawItem method, it can
049 *               be calculated inside the initialise method if it is required.
050 *               Added a new getToolTipGenerator() method.  Changed the return
051 *               type for drawItem() to void (DG);
052 * 24-May-2002 : Added ChartRenderingInfo the initialise method API (DG);
053 * 25-Jun-2002 : Removed redundant import (DG);
054 * 20-Aug-2002 : Added get/setURLGenerator methods to interface (DG);
055 * 02-Oct-2002 : Fixed errors reported by Checkstyle (DG);
056 * 18-Nov-2002 : Added methods for drawing grid lines (DG);
057 * 17-Jan-2003 : Moved plot classes into a separate package (DG);
058 * 27-Jan-2003 : Added shape lookup table (DG);
059 * 05-Jun-2003 : Added domain and range grid bands (sponsored by Focus Computer
060 *               Services Ltd) (DG);
061 * 27-Jul-2003 : Added getRangeType() to support stacked XY area charts (RA);
062 * 16-Sep-2003 : Changed ChartRenderingInfo --> PlotRenderingInfo (DG);
063 * 25-Feb-2004 : Replaced CrosshairInfo with CrosshairState.  Renamed
064 *               XYToolTipGenerator --> XYItemLabelGenerator (DG);
065 * 26-Feb-2004 : Added lots of new methods (DG);
066 * 30-Apr-2004 : Added getRangeExtent() method (DG);
067 * 06-May-2004 : Added methods for controlling item label visibility (DG);
068 * 13-May-2004 : Removed property change listener mechanism (DG);
069 * 18-May-2004 : Added item label font and paint methods (DG);
070 * 10-Sep-2004 : Removed redundant getRangeType() method (DG);
071 * 06-Oct-2004 : Replaced getRangeExtent() with findRangeBounds() and added
072 *               findDomainBounds (DG);
073 * 23-Nov-2004 : Changed drawRangeGridLine() --> drawRangeLine() (DG);
074 * 07-Jan-2005 : Removed deprecated method (DG);
075 * 24-Feb-2005 : Now extends LegendItemSource (DG);
076 * 20-Apr-2005 : Renamed XYLabelGenerator --> XYItemLabelGenerator (DG);
077 * ------------- JFREECHART 1.0.x ---------------------------------------------
078 * 19-Apr-2007 : Deprecated seriesVisible and seriesVisibleInLegend flags (DG);
079 * 20-Apr-2007 : Deprecated paint, fillPaint, outlinePaint, stroke,
080 *               outlineStroke, shape, itemLabelsVisible, itemLabelFont,
081 *               itemLabelPaint, positiveItemLabelPosition,
082 *               negativeItemLabelPosition and createEntities override
083 *               fields (DG);
084 *
085 */
086
087package org.jfree.chart.renderer.xy;
088
089import java.awt.Font;
090import java.awt.Graphics2D;
091import java.awt.Paint;
092import java.awt.Shape;
093import java.awt.Stroke;
094import java.awt.geom.Rectangle2D;
095
096import org.jfree.chart.LegendItem;
097import org.jfree.chart.LegendItemSource;
098import org.jfree.chart.annotations.XYAnnotation;
099import org.jfree.chart.axis.ValueAxis;
100import org.jfree.chart.event.RendererChangeEvent;
101import org.jfree.chart.event.RendererChangeListener;
102import org.jfree.chart.labels.ItemLabelPosition;
103import org.jfree.chart.labels.XYItemLabelGenerator;
104import org.jfree.chart.labels.XYSeriesLabelGenerator;
105import org.jfree.chart.labels.XYToolTipGenerator;
106import org.jfree.chart.plot.CrosshairState;
107import org.jfree.chart.plot.Marker;
108import org.jfree.chart.plot.PlotRenderingInfo;
109import org.jfree.chart.plot.XYPlot;
110import org.jfree.chart.ui.Layer;
111import org.jfree.chart.urls.XYURLGenerator;
112import org.jfree.data.Range;
113import org.jfree.data.xy.XYDataset;
114
115/**
116 * Interface for rendering the visual representation of a single (x, y) item on
117 * an {@link XYPlot}.
118 * <p>
119 * To support cloning charts, it is recommended that renderers implement both
120 * the {@link Cloneable} and {@code PublicCloneable} interfaces.
121 */
122public interface XYItemRenderer extends LegendItemSource {
123
124    /**
125     * Returns the plot that this renderer has been assigned to.
126     *
127     * @return The plot.
128     */
129    public XYPlot getPlot();
130
131    /**
132     * Sets the plot that this renderer is assigned to.  This method will be
133     * called by the plot class...you do not need to call it yourself.
134     *
135     * @param plot  the plot.
136     */
137    public void setPlot(XYPlot plot);
138
139    /**
140     * Returns the number of passes through the data required by the renderer.
141     *
142     * @return The pass count.
143     */
144    public int getPassCount();
145
146    /**
147     * Returns the lower and upper bounds (range) of the x-values in the
148     * specified dataset.
149     *
150     * @param dataset  the dataset ({@code null} permitted).
151     *
152     * @return The range.
153     */
154    public Range findDomainBounds(XYDataset dataset);
155
156    /**
157     * Returns the lower and upper bounds (range) of the y-values in the
158     * specified dataset.  The implementation of this method will take
159     * into account the presentation used by the renderers (for example,
160     * a renderer that "stacks" values will return a bigger range than
161     * a renderer that doesn't).
162     *
163     * @param dataset  the dataset ({@code null} permitted).
164     *
165     * @return The range (or {@code null} if the dataset is
166     *         {@code null} or empty).
167     */
168    public Range findRangeBounds(XYDataset dataset);
169
170    /**
171     * Add a renderer change listener.
172     *
173     * @param listener  the listener.
174     *
175     * @see #removeChangeListener(RendererChangeListener)
176     */
177    public void addChangeListener(RendererChangeListener listener);
178
179    /**
180     * Removes a change listener.
181     *
182     * @param listener  the listener.
183     *
184     * @see #addChangeListener(RendererChangeListener)
185     */
186    public void removeChangeListener(RendererChangeListener listener);
187
188
189    //// VISIBLE //////////////////////////////////////////////////////////////
190
191    /**
192     * Returns a boolean that indicates whether or not the specified item
193     * should be drawn (this is typically used to hide an entire series).
194     *
195     * @param series  the series index.
196     * @param item  the item index.
197     *
198     * @return A boolean.
199     */
200    public boolean getItemVisible(int series, int item);
201
202    /**
203     * Returns a boolean that indicates whether or not the specified series
204     * should be drawn (this is typically used to hide an entire series).
205     *
206     * @param series  the series index.
207     *
208     * @return A boolean.
209     */
210    public boolean isSeriesVisible(int series);
211
212    /**
213     * Returns the flag that controls whether a series is visible.
214     *
215     * @param series  the series index (zero-based).
216     *
217     * @return The flag (possibly {@code null}).
218     *
219     * @see #setSeriesVisible(int, Boolean)
220     */
221    public Boolean getSeriesVisible(int series);
222
223    /**
224     * Sets the flag that controls whether a series is visible and sends a
225     * {@link RendererChangeEvent} to all registered listeners.
226     *
227     * @param series  the series index (zero-based).
228     * @param visible  the flag ({@code null} permitted).
229     *
230     * @see #getSeriesVisible(int)
231     */
232    public void setSeriesVisible(int series, Boolean visible);
233
234    /**
235     * Sets the flag that controls whether a series is visible and, if
236     * requested, sends a {@link RendererChangeEvent} to all registered
237     * listeners.
238     *
239     * @param series  the series index.
240     * @param visible  the flag ({@code null} permitted).
241     * @param notify  notify listeners?
242     *
243     * @see #getSeriesVisible(int)
244     */
245    public void setSeriesVisible(int series, Boolean visible, boolean notify);
246
247    /**
248     * Returns the default visibility for all series.
249     *
250     * @return The default visibility.
251     *
252     * @see #setDefaultSeriesVisible(boolean)
253     */
254    public boolean getDefaultSeriesVisible();
255
256    /**
257     * Sets the default visibility and sends a {@link RendererChangeEvent} to all
258     * registered listeners.
259     *
260     * @param visible  the flag.
261     *
262     * @see #getDefaultSeriesVisible()
263     */
264    public void setDefaultSeriesVisible(boolean visible);
265
266    /**
267     * Sets the default visibility and, if requested, sends
268     * a {@link RendererChangeEvent} to all registered listeners.
269     *
270     * @param visible  the visibility.
271     * @param notify  notify listeners?
272     *
273     * @see #getDefaultSeriesVisible()
274     */
275    public void setDefaultSeriesVisible(boolean visible, boolean notify);
276
277    // SERIES VISIBLE IN LEGEND (not yet respected by all renderers)
278
279    /**
280     * Returns {@code true} if the series should be shown in the legend,
281     * and {@code false} otherwise.
282     *
283     * @param series  the series index.
284     *
285     * @return A boolean.
286     */
287    public boolean isSeriesVisibleInLegend(int series);
288
289    /**
290     * Returns the flag that controls whether a series is visible in the
291     * legend.  This method returns only the "per series" settings - to
292     * incorporate the override and base settings as well, you need to use the
293     * {@link #isSeriesVisibleInLegend(int)} method.
294     *
295     * @param series  the series index (zero-based).
296     *
297     * @return The flag (possibly {@code null}).
298     *
299     * @see #setSeriesVisibleInLegend(int, Boolean)
300     */
301    public Boolean getSeriesVisibleInLegend(int series);
302
303    /**
304     * Sets the flag that controls whether a series is visible in the legend
305     * and sends a {@link RendererChangeEvent} to all registered listeners.
306     *
307     * @param series  the series index (zero-based).
308     * @param visible  the flag ({@code null} permitted).
309     *
310     * @see #getSeriesVisibleInLegend(int)
311     */
312    public void setSeriesVisibleInLegend(int series, Boolean visible);
313
314    /**
315     * Sets the flag that controls whether a series is visible in the legend
316     * and, if requested, sends a {@link RendererChangeEvent} to all registered
317     * listeners.
318     *
319     * @param series  the series index.
320     * @param visible  the flag ({@code null} permitted).
321     * @param notify  notify listeners?
322     *
323     * @see #getSeriesVisibleInLegend(int)
324     */
325    public void setSeriesVisibleInLegend(int series, Boolean visible,
326                                         boolean notify);
327
328    /**
329     * Returns the default visibility in the legend for all series.
330     *
331     * @return The default visibility.
332     *
333     * @see #setDefaultSeriesVisibleInLegend(boolean)
334     */
335    public boolean getDefaultSeriesVisibleInLegend();
336
337    /**
338     * Sets the default visibility in the legend and sends a
339     * {@link RendererChangeEvent} to all registered listeners.
340     *
341     * @param visible  the flag.
342     *
343     * @see #getDefaultSeriesVisibleInLegend()
344     */
345    public void setDefaultSeriesVisibleInLegend(boolean visible);
346
347    /**
348     * Sets the default visibility in the legend and, if requested, sends
349     * a {@link RendererChangeEvent} to all registered listeners.
350     *
351     * @param visible  the visibility.
352     * @param notify  notify listeners?
353     *
354     * @see #getDefaultSeriesVisibleInLegend()
355     */
356    public void setDefaultSeriesVisibleInLegend(boolean visible, boolean notify);
357
358
359    //// PAINT ////////////////////////////////////////////////////////////////
360
361    /**
362     * Returns the paint used to color data items as they are drawn.
363     *
364     * @param row  the row (or series) index (zero-based).
365     * @param column  the column (or category) index (zero-based).
366     *
367     * @return The paint (never {@code null}).
368     */
369    public Paint getItemPaint(int row, int column);
370
371    /**
372     * Returns the paint used to color an item drawn by the renderer.
373     *
374     * @param series  the series index (zero-based).
375     *
376     * @return The paint (possibly {@code null}).
377     *
378     * @see #setSeriesPaint(int, Paint)
379     */
380    public Paint getSeriesPaint(int series);
381
382    /**
383     * Sets the paint used for a series and sends a {@link RendererChangeEvent}
384     * to all registered listeners.
385     *
386     * @param series  the series index (zero-based).
387     * @param paint  the paint ({@code null} permitted).
388     *
389     * @see #getSeriesPaint(int)
390     */
391    public void setSeriesPaint(int series, Paint paint);
392
393    public void setSeriesPaint(int series, Paint paint, boolean notify);
394
395    /**
396     * Returns the default paint.
397     *
398     * @return The default paint (never {@code null}).
399     *
400     * @see #setDefaultPaint(Paint)
401     */
402    public Paint getDefaultPaint();
403
404    /**
405     * Sets the default paint and sends a {@link RendererChangeEvent} to all
406     * registered listeners.
407     *
408     * @param paint  the paint ({@code null} not permitted).
409     *
410     * @see #getDefaultPaint()
411     */
412    public void setDefaultPaint(Paint paint);
413
414    public void setDefaultPaint(Paint paint, boolean notify);
415
416    // FILL PAINT
417
418    /**
419     * Returns the paint used to fill data items as they are drawn.
420     *
421     * @param row  the row (or series) index (zero-based).
422     * @param column  the column (or category) index (zero-based).
423     *
424     * @return The paint (never {@code null}).
425     */
426    public Paint getItemFillPaint(int row, int column);
427
428    /**
429     * Returns the paint used to fill an item drawn by the renderer.
430     *
431     * @param series  the series index (zero-based).
432     *
433     * @return The paint (possibly {@code null}).
434     */
435    public Paint getSeriesFillPaint(int series);
436
437    /**
438     * Sets the paint used for a series and sends a
439     * {@link RendererChangeEvent} to all registered listeners.
440     *
441     * @param series  the series index (zero-based).
442     * @param paint  the paint ({@code null} permitted).
443     */
444    public void setSeriesFillPaint(int series, Paint paint);
445
446    public void setSeriesFillPaint(int series, Paint paint, boolean notify);
447
448    /**
449     * Returns the default paint.
450     *
451     * @return The default paint (never {@code null}).
452     */
453    public Paint getDefaultFillPaint();
454
455    /**
456     * Sets the default paint and sends a {@link RendererChangeEvent} to all
457     * registered listeners.
458     *
459     * @param paint  the paint ({@code null} not permitted).
460     */
461    public void setDefaultFillPaint(Paint paint);
462
463    public void setDefaultFillPaint(Paint paint, boolean notify);
464
465    //// OUTLINE PAINT ////////////////////////////////////////////////////////
466
467    /**
468     * Returns the paint used to outline data items as they are drawn.
469     *
470     * @param row  the row (or series) index (zero-based).
471     * @param column  the column (or category) index (zero-based).
472     *
473     * @return The paint (never {@code null}).
474     */
475    public Paint getItemOutlinePaint(int row, int column);
476
477    /**
478     * Returns the paint used to outline an item drawn by the renderer.
479     *
480     * @param series  the series (zero-based index).
481     *
482     * @return The paint (possibly {@code null}).
483     *
484     * @see #setSeriesOutlinePaint(int, Paint)
485     */
486    public Paint getSeriesOutlinePaint(int series);
487
488    /**
489     * Sets the paint used for a series outline and sends a
490     * {@link RendererChangeEvent} to all registered listeners.
491     *
492     * @param series  the series index (zero-based).
493     * @param paint  the paint ({@code null} permitted).
494     *
495     * @see #getSeriesOutlinePaint(int)
496     */
497    public void setSeriesOutlinePaint(int series, Paint paint);
498
499    public void setSeriesOutlinePaint(int series, Paint paint, boolean notify);
500
501    /**
502     * Returns the default outline paint.
503     *
504     * @return The paint (never {@code null}).
505     *
506     * @see #setDefaultOutlinePaint(Paint)
507     */
508    public Paint getDefaultOutlinePaint();
509
510    /**
511     * Sets the default outline paint and sends a {@link RendererChangeEvent} to
512     * all registered listeners.
513     *
514     * @param paint  the paint ({@code null} not permitted).
515     *
516     * @see #getDefaultOutlinePaint()
517     */
518    public void setDefaultOutlinePaint(Paint paint);
519
520    public void setDefaultOutlinePaint(Paint paint, boolean notify);
521
522    //// STROKE ///////////////////////////////////////////////////////////////
523
524    /**
525     * Returns the stroke used to draw data items.
526     *
527     * @param row  the row (or series) index (zero-based).
528     * @param column  the column (or category) index (zero-based).
529     *
530     * @return The stroke (never {@code null}).
531     */
532    public Stroke getItemStroke(int row, int column);
533
534    /**
535     * Returns the stroke used to draw the items in a series.
536     *
537     * @param series  the series (zero-based index).
538     *
539     * @return The stroke (possibly {@code null}).
540     *
541     * @see #setSeriesStroke(int, Stroke)
542     */
543    public Stroke getSeriesStroke(int series);
544
545    /**
546     * Sets the stroke used for a series and sends a
547     * {@link RendererChangeEvent} to all registered listeners.
548     *
549     * @param series  the series index (zero-based).
550     * @param stroke  the stroke ({@code null} permitted).
551     *
552     * @see #getSeriesStroke(int)
553     */
554    public void setSeriesStroke(int series, Stroke stroke);
555
556    public void setSeriesStroke(int series, Stroke stroke, boolean notify);
557
558    /**
559     * Returns the default stroke.
560     *
561     * @return The default stroke (never {@code null}).
562     *
563     * @see #setDefaultStroke(Stroke)
564     */
565    public Stroke getDefaultStroke();
566
567    /**
568     * Sets the default stroke and sends a {@link RendererChangeEvent} to all
569     * registered listeners.
570     *
571     * @param stroke  the stroke ({@code null} not permitted).
572     *
573     * @see #getDefaultStroke()
574     */
575    public void setDefaultStroke(Stroke stroke);
576
577    public void setDefaultStroke(Stroke stroke, boolean notify);
578
579    //// OUTLINE STROKE ///////////////////////////////////////////////////////
580
581    /**
582     * Returns the stroke used to outline data items.  The default
583     * implementation passes control to the lookupSeriesOutlineStroke method.
584     * You can override this method if you require different behaviour.
585     *
586     * @param row  the row (or series) index (zero-based).
587     * @param column  the column (or category) index (zero-based).
588     *
589     * @return The stroke (never {@code null}).
590     */
591    public Stroke getItemOutlineStroke(int row, int column);
592
593    /**
594     * Returns the stroke used to outline the items in a series.
595     *
596     * @param series  the series (zero-based index).
597     *
598     * @return The stroke (possibly {@code null}).
599     *
600     * @see #setSeriesOutlineStroke(int, Stroke)
601     */
602    public Stroke getSeriesOutlineStroke(int series);
603
604    /**
605     * Sets the outline stroke used for a series and sends a
606     * {@link RendererChangeEvent} to all registered listeners.
607     *
608     * @param series  the series index (zero-based).
609     * @param stroke  the stroke ({@code null} permitted).
610     *
611     * @see #getSeriesOutlineStroke(int)
612     */
613    public void setSeriesOutlineStroke(int series, Stroke stroke);
614
615    public void setSeriesOutlineStroke(int series, Stroke stroke, boolean notify);
616
617    /**
618     * Returns the default outline stroke.
619     *
620     * @return The stroke (never {@code null}).
621     *
622     * @see #setDefaultOutlineStroke(Stroke)
623     */
624    public Stroke getDefaultOutlineStroke();
625
626    /**
627     * Sets the base outline stroke and sends a {@link RendererChangeEvent} to
628     * all registered listeners.
629     *
630     * @param stroke  the stroke ({@code null} not permitted).
631     *
632     * @see #getDefaultOutlineStroke()
633     */
634    public void setDefaultOutlineStroke(Stroke stroke);
635
636    public void setDefaultOutlineStroke(Stroke stroke, boolean notify);
637
638    //// SHAPE ////////////////////////////////////////////////////////////////
639
640    /**
641     * Returns a shape used to represent a data item.
642     *
643     * @param row  the row (or series) index (zero-based).
644     * @param column  the column (or category) index (zero-based).
645     *
646     * @return The shape (never {@code null}).
647     */
648    public Shape getItemShape(int row, int column);
649
650    /**
651     * Returns a shape used to represent the items in a series.
652     *
653     * @param series  the series (zero-based index).
654     *
655     * @return The shape (possibly {@code null}).
656     *
657     * @see #setSeriesShape(int, Shape)
658     */
659    public Shape getSeriesShape(int series);
660
661    /**
662     * Sets the shape used for a series and sends a {@link RendererChangeEvent}
663     * to all registered listeners.
664     *
665     * @param series  the series index (zero-based).
666     * @param shape  the shape ({@code null} permitted).
667     *
668     * @see #getSeriesShape(int)
669     */
670    public void setSeriesShape(int series, Shape shape);
671
672    public void setSeriesShape(int series, Shape shape, boolean notify);
673
674    /**
675     * Returns the default shape.
676     *
677     * @return The shape (never {@code null}).
678     *
679     * @see #setDefaultShape(Shape)
680     */
681    public Shape getDefaultShape();
682
683    /**
684     * Sets the default shape and sends a {@link RendererChangeEvent} to all
685     * registered listeners.
686     *
687     * @param shape  the shape ({@code null} not permitted).
688     *
689     * @see #getDefaultShape()
690     */
691    public void setDefaultShape(Shape shape);
692
693    public void setDefaultShape(Shape shape, boolean notify);
694
695
696    //// LEGEND ITEMS /////////////////////////////////////////////////////////
697
698    /**
699     * Returns a legend item for a series from a dataset.
700     *
701     * @param datasetIndex  the dataset index.
702     * @param series  the series (zero-based index).
703     *
704     * @return The legend item (possibly {@code null}).
705     */
706    public LegendItem getLegendItem(int datasetIndex, int series);
707
708
709    //// LEGEND ITEM LABEL GENERATOR //////////////////////////////////////////
710
711    /**
712     * Returns the legend item label generator.
713     *
714     * @return The legend item label generator (never {@code null}).
715     *
716     * @see #setLegendItemLabelGenerator(XYSeriesLabelGenerator)
717     */
718    public XYSeriesLabelGenerator getLegendItemLabelGenerator();
719
720    /**
721     * Sets the legend item label generator and sends a
722     * {@link RendererChangeEvent} to all registered listeners.
723     *
724     * @param generator  the generator ({@code null} not permitted).
725     */
726    public void setLegendItemLabelGenerator(XYSeriesLabelGenerator generator);
727
728
729    //// TOOL TIP GENERATOR ///////////////////////////////////////////////////
730
731    /**
732     * Returns the tool tip generator for a data item.
733     *
734     * @param row  the row index (zero based).
735     * @param column  the column index (zero based).
736     *
737     * @return The generator (possibly {@code null}).
738     */
739    public XYToolTipGenerator getToolTipGenerator(int row, int column);
740
741    /**
742     * Returns the tool tip generator for a series.
743     *
744     * @param series  the series index (zero based).
745     *
746     * @return The generator (possibly {@code null}).
747     *
748     * @see #setSeriesToolTipGenerator(int, XYToolTipGenerator)
749     */
750    public XYToolTipGenerator getSeriesToolTipGenerator(int series);
751
752    /**
753     * Sets the tool tip generator for a series and sends a
754     * {@link RendererChangeEvent} to all registered listeners.
755     *
756     * @param series  the series index (zero based).
757     * @param generator  the generator ({@code null} permitted).
758     *
759     * @see #getSeriesToolTipGenerator(int)
760     */
761    public void setSeriesToolTipGenerator(int series, 
762            XYToolTipGenerator generator);
763
764    /**
765     * Returns the default tool tip generator.
766     *
767     * @return The generator (possibly {@code null}).
768     *
769     * @see #setDefaultToolTipGenerator(XYToolTipGenerator)
770     */
771    public XYToolTipGenerator getDefaultToolTipGenerator();
772
773    /**
774     * Sets the default tool tip generator and sends a {@link RendererChangeEvent}
775     * to all registered listeners.
776     *
777     * @param generator  the generator ({@code null} permitted).
778     *
779     * @see #getDefaultToolTipGenerator()
780     */
781    public void setDefaultToolTipGenerator(XYToolTipGenerator generator);
782
783    //// URL GENERATOR ////////////////////////////////////////////////////////
784
785    /**
786     * Returns the URL generator for HTML image maps.
787     *
788     * @return The URL generator (possibly null).
789     */
790    public XYURLGenerator getURLGenerator();
791
792    /**
793     * Sets the URL generator for HTML image maps.
794     *
795     * @param urlGenerator the URL generator (null permitted).
796     */
797    public void setURLGenerator(XYURLGenerator urlGenerator);
798
799    //// ITEM LABELS VISIBLE //////////////////////////////////////////////////
800
801    /**
802     * Returns {@code true} if an item label is visible, and
803     * {@code false} otherwise.
804     *
805     * @param row  the row index (zero-based).
806     * @param column  the column index (zero-based).
807     *
808     * @return A boolean.
809     */
810    public boolean isItemLabelVisible(int row, int column);
811
812    /**
813     * Returns {@code true} if the item labels for a series are visible,
814     * and {@code false} otherwise.
815     *
816     * @param series  the series index (zero-based).
817     *
818     * @return A boolean.
819     */
820    public boolean isSeriesItemLabelsVisible(int series);
821
822    /**
823     * Sets a flag that controls the visibility of the item labels for a
824     * series and sends a {@link RendererChangeEvent} to all registered
825     * listeners.
826     *
827     * @param series  the series index (zero-based).
828     * @param visible  the flag.
829     *
830     * @see #isSeriesItemLabelsVisible(int)
831     */
832    public void setSeriesItemLabelsVisible(int series, boolean visible);
833
834    /**
835     * Sets a flag that controls the visibility of the item labels for a series.
836     *
837     * @param series  the series index (zero-based).
838     * @param visible  the flag ({@code null} permitted).
839     *
840     * @see #isSeriesItemLabelsVisible(int)
841     */
842    public void setSeriesItemLabelsVisible(int series, Boolean visible);
843
844    /**
845     * Sets the visibility of item labels for a series and, if requested,
846     * sends a {@link RendererChangeEvent} to all registered listeners.
847     *
848     * @param series  the series index (zero-based).
849     * @param visible  the visible flag.
850     * @param notify  a flag that controls whether or not listeners are
851     *                notified.
852     *
853     * @see #isSeriesItemLabelsVisible(int)
854     */
855    public void setSeriesItemLabelsVisible(int series, Boolean visible,
856            boolean notify);
857
858    /**
859     * Returns the default setting for item label visibility.
860     *
861     * @return A flag (possibly {@code null}).
862     *
863     * @see #setDefaultItemLabelsVisible(boolean)
864     */
865    public boolean getDefaultItemLabelsVisible();
866
867    /**
868     * Sets the default flag that controls whether or not item labels are visible.
869     *
870     * @param visible  the flag.
871     *
872     * @see #getDefaultItemLabelsVisible()
873     */
874    public void setDefaultItemLabelsVisible(boolean visible);
875
876    /**
877     * Sets the default visibility for item labels and, if requested, sends a
878     * {@link RendererChangeEvent} to all registered listeners.
879     *
880     * @param visible  the visibility flag.
881     * @param notify  a flag that controls whether or not listeners are
882     *                notified.
883     *
884     * @see #getDefaultItemLabelsVisible()
885     */
886    public void setDefaultItemLabelsVisible(boolean visible, boolean notify);
887
888
889    //// ITEM LABEL GENERATOR /////////////////////////////////////////////////
890
891    /**
892     * Returns the item label generator for a data item.
893     *
894     * @param row  the row index (zero based).
895     * @param column  the column index (zero based).
896     *
897     * @return The generator (possibly {@code null}).
898     */
899    public XYItemLabelGenerator getItemLabelGenerator(int row, int column);
900
901    /**
902     * Returns the item label generator for a series.
903     *
904     * @param series  the series index (zero based).
905     *
906     * @return The generator (possibly {@code null}).
907     *
908     * @see #setSeriesItemLabelGenerator(int, XYItemLabelGenerator)
909     */
910    public XYItemLabelGenerator getSeriesItemLabelGenerator(int series);
911
912    /**
913     * Sets the item label generator for a series and sends a
914     * {@link RendererChangeEvent} to all registered listeners.
915     *
916     * @param series  the series index (zero based).
917     * @param generator  the generator ({@code null} permitted).
918     *
919     * @see #getSeriesItemLabelGenerator(int)
920     */
921    public void setSeriesItemLabelGenerator(int series, 
922            XYItemLabelGenerator generator);
923
924    /**
925     * Returns the default item label generator.
926     *
927     * @return The generator (possibly {@code null}).
928     *
929     * @see #setDefaultItemLabelGenerator(XYItemLabelGenerator)
930     */
931    public XYItemLabelGenerator getDefaultItemLabelGenerator();
932
933    /**
934     * Sets the default item label generator and sends a
935     * {@link RendererChangeEvent} to all registered listeners.
936     *
937     * @param generator  the generator ({@code null} permitted).
938     *
939     * @see #getDefaultItemLabelGenerator()
940     */
941    public void setDefaultItemLabelGenerator(XYItemLabelGenerator generator);
942
943    //// ITEM LABEL FONT ///////////////////////////////////////////////////////
944
945    /**
946     * Returns the font for an item label.
947     *
948     * @param row  the row index (zero-based).
949     * @param column  the column index (zero-based).
950     *
951     * @return The font (never {@code null}).
952     */
953    public Font getItemLabelFont(int row, int column);
954
955    /**
956     * Returns the font for all the item labels in a series.
957     *
958     * @param series  the series index (zero-based).
959     *
960     * @return The font (possibly {@code null}).
961     */
962    public Font getSeriesItemLabelFont(int series);
963
964    /**
965     * Sets the item label font for a series and sends a
966     * {@link RendererChangeEvent} to all registered listeners.
967     *
968     * @param series  the series index (zero-based).
969     * @param font  the font ({@code null} permitted).
970     *
971     * @see #getSeriesItemLabelFont(int)
972     */
973    public void setSeriesItemLabelFont(int series, Font font);
974
975    /**
976     * Returns the default item label font (this is used when no other font
977     * setting is available).
978     *
979     * @return The font (never {@code null}).
980     *
981     * @see #setDefaultItemLabelFont(Font)
982     */
983    public Font getDefaultItemLabelFont();
984
985    /**
986     * Sets the default item label font and sends a {@link RendererChangeEvent}
987     * to all registered listeners.
988     *
989     * @param font  the font ({@code null} not permitted).
990     *
991     * @see #getDefaultItemLabelFont()
992     */
993    public void setDefaultItemLabelFont(Font font);
994
995    //// ITEM LABEL PAINT  /////////////////////////////////////////////////////
996
997    /**
998     * Returns the paint used to draw an item label.
999     *
1000     * @param row  the row index (zero based).
1001     * @param column  the column index (zero based).
1002     *
1003     * @return The paint (never {@code null}).
1004     */
1005    public Paint getItemLabelPaint(int row, int column);
1006
1007    /**
1008     * Returns the paint used to draw the item labels for a series.
1009     *
1010     * @param series  the series index (zero based).
1011     *
1012     * @return The paint (possibly {@code null}).
1013     *
1014     * @see #setSeriesItemLabelPaint(int, Paint)
1015     */
1016    public Paint getSeriesItemLabelPaint(int series);
1017
1018    /**
1019     * Sets the item label paint for a series and sends a
1020     * {@link RendererChangeEvent} to all registered listeners.
1021     *
1022     * @param series  the series (zero based index).
1023     * @param paint  the paint ({@code null} permitted).
1024     *
1025     * @see #getSeriesItemLabelPaint(int)
1026     */
1027    public void setSeriesItemLabelPaint(int series, Paint paint);
1028
1029    /**
1030     * Returns the default item label paint.
1031     *
1032     * @return The paint (never {@code null}).
1033     */
1034    public Paint getDefaultItemLabelPaint();
1035
1036    /**
1037     * Sets the default item label paint and sends a {@link RendererChangeEvent}
1038     * to all registered listeners.
1039     *
1040     * @param paint  the paint ({@code null} not permitted).
1041     */
1042    public void setDefaultItemLabelPaint(Paint paint);
1043
1044    // POSITIVE ITEM LABEL POSITION...
1045
1046    /**
1047     * Returns the item label position for positive values.
1048     *
1049     * @param row  the row index (zero-based).
1050     * @param column  the column index (zero-based).
1051     *
1052     * @return The item label position (never {@code null}).
1053     */
1054    public ItemLabelPosition getPositiveItemLabelPosition(int row, int column);
1055
1056    /**
1057     * Returns the item label position for all positive values in a series.
1058     *
1059     * @param series  the series index (zero-based).
1060     *
1061     * @return The item label position (never {@code null}).
1062     */
1063    public ItemLabelPosition getSeriesPositiveItemLabelPosition(int series);
1064
1065    /**
1066     * Sets the item label position for all positive values in a series and
1067     * sends a {@link RendererChangeEvent} to all registered listeners.
1068     *
1069     * @param series  the series index (zero-based).
1070     * @param position  the position ({@code null} permitted).
1071     */
1072    public void setSeriesPositiveItemLabelPosition(int series, 
1073            ItemLabelPosition position);
1074
1075    /**
1076     * Sets the item label position for all positive values in a series and (if
1077     * requested) sends a {@link RendererChangeEvent} to all registered
1078     * listeners.
1079     *
1080     * @param series  the series index (zero-based).
1081     * @param position  the position ({@code null} permitted).
1082     * @param notify  notify registered listeners?
1083     */
1084    public void setSeriesPositiveItemLabelPosition(int series, 
1085            ItemLabelPosition position, boolean notify);
1086
1087    /**
1088     * Returns the default positive item label position.
1089     *
1090     * @return The position (never {@code null}).
1091     */
1092    public ItemLabelPosition getDefaultPositiveItemLabelPosition();
1093
1094    /**
1095     * Sets the default positive item label position.
1096     *
1097     * @param position  the position ({@code null} not permitted).
1098     */
1099    public void setDefaultPositiveItemLabelPosition(ItemLabelPosition position);
1100
1101    /**
1102     * Sets the default positive item label position and, if requested, sends a
1103     * {@link RendererChangeEvent} to all registered listeners.
1104     *
1105     * @param position  the position ({@code null} not permitted).
1106     * @param notify  notify registered listeners?
1107     */
1108    public void setDefaultPositiveItemLabelPosition(ItemLabelPosition position,
1109            boolean notify);
1110
1111
1112    // NEGATIVE ITEM LABEL POSITION...
1113
1114    /**
1115     * Returns the item label position for negative values.  This method can be
1116     * overridden to provide customisation of the item label position for
1117     * individual data items.
1118     *
1119     * @param row  the row index (zero-based).
1120     * @param column  the column (zero-based).
1121     *
1122     * @return The item label position (never {@code null}).
1123     */
1124    public ItemLabelPosition getNegativeItemLabelPosition(int row, int column);
1125
1126    /**
1127     * Returns the item label position for all negative values in a series.
1128     *
1129     * @param series  the series index (zero-based).
1130     *
1131     * @return The item label position (never {@code null}).
1132     */
1133    public ItemLabelPosition getSeriesNegativeItemLabelPosition(int series);
1134
1135    /**
1136     * Sets the item label position for negative values in a series and sends a
1137     * {@link RendererChangeEvent} to all registered listeners.
1138     *
1139     * @param series  the series index (zero-based).
1140     * @param position  the position ({@code null} permitted).
1141     */
1142    public void setSeriesNegativeItemLabelPosition(int series, 
1143            ItemLabelPosition position);
1144
1145    /**
1146     * Sets the item label position for negative values in a series and (if
1147     * requested) sends a {@link RendererChangeEvent} to all registered
1148     * listeners.
1149     *
1150     * @param series  the series index (zero-based).
1151     * @param position  the position ({@code null} permitted).
1152     * @param notify  notify registered listeners?
1153     */
1154    public void setSeriesNegativeItemLabelPosition(int series, 
1155            ItemLabelPosition position, boolean notify);
1156
1157    /**
1158     * Returns the default item label position for negative values.
1159     *
1160     * @return The position (never {@code null}).
1161     */
1162    public ItemLabelPosition getDefaultNegativeItemLabelPosition();
1163
1164    /**
1165     * Sets the default item label position for negative values and sends a
1166     * {@link RendererChangeEvent} to all registered listeners.
1167     *
1168     * @param position  the position ({@code null} not permitted).
1169     */
1170    public void setDefaultNegativeItemLabelPosition(ItemLabelPosition position);
1171
1172    /**
1173     * Sets the default negative item label position and, if requested, sends a
1174     * {@link RendererChangeEvent} to all registered listeners.
1175     *
1176     * @param position  the position ({@code null} not permitted).
1177     * @param notify  notify registered listeners?
1178     */
1179    public void setDefaultNegativeItemLabelPosition(ItemLabelPosition position,
1180            boolean notify);
1181
1182
1183    // CREATE ENTITIES
1184
1185    public boolean getItemCreateEntity(int series, int item);
1186
1187    public Boolean getSeriesCreateEntities(int series);
1188
1189    public void setSeriesCreateEntities(int series, Boolean create);
1190
1191    public void setSeriesCreateEntities(int series, Boolean create,
1192            boolean notify);
1193
1194    public boolean getDefaultCreateEntities();
1195
1196    public void setDefaultCreateEntities(boolean create);
1197
1198    public void setDefaultCreateEntities(boolean create, boolean notify);
1199
1200    //// ANNOTATIONS //////////////////////////////////////////////////////////
1201
1202    /**
1203     * Adds an annotation and sends a {@link RendererChangeEvent} to all
1204     * registered listeners.  The annotation is added to the foreground
1205     * layer.
1206     *
1207     * @param annotation  the annotation ({@code null} not permitted).
1208     */
1209    public void addAnnotation(XYAnnotation annotation);
1210
1211    /**
1212     * Adds an annotation to the specified layer.
1213     *
1214     * @param annotation  the annotation ({@code null} not permitted).
1215     * @param layer  the layer ({@code null} not permitted).
1216     */
1217    public void addAnnotation(XYAnnotation annotation, Layer layer);
1218
1219    /**
1220     * Removes the specified annotation and sends a {@link RendererChangeEvent}
1221     * to all registered listeners.
1222     *
1223     * @param annotation  the annotation to remove ({@code null} not
1224     *                    permitted).
1225     *
1226     * @return A boolean to indicate whether or not the annotation was
1227     *         successfully removed.
1228     */
1229    public boolean removeAnnotation(XYAnnotation annotation);
1230
1231    /**
1232     * Removes all annotations and sends a {@link RendererChangeEvent}
1233     * to all registered listeners.
1234     */
1235    public void removeAnnotations();
1236
1237    /**
1238     * Draws all the annotations for the specified layer.
1239     *
1240     * @param g2  the graphics device.
1241     * @param dataArea  the data area.
1242     * @param domainAxis  the domain axis.
1243     * @param rangeAxis  the range axis.
1244     * @param layer  the layer.
1245     * @param info  the plot rendering info.
1246     */
1247    public void drawAnnotations(Graphics2D g2, Rectangle2D dataArea,
1248            ValueAxis domainAxis, ValueAxis rangeAxis, Layer layer,
1249            PlotRenderingInfo info);
1250
1251    //// DRAWING //////////////////////////////////////////////////////////////
1252
1253    /**
1254     * Initialises the renderer then returns the number of 'passes' through the
1255     * data that the renderer will require (usually just one).  This method
1256     * will be called before the first item is rendered, giving the renderer
1257     * an opportunity to initialise any state information it wants to maintain.
1258     * The renderer can do nothing if it chooses.
1259     *
1260     * @param g2  the graphics device.
1261     * @param dataArea  the area inside the axes.
1262     * @param plot  the plot.
1263     * @param dataset  the dataset.
1264     * @param info  an optional info collection object to return data back to
1265     *              the caller.
1266     *
1267     * @return The number of passes the renderer requires.
1268     */
1269    public XYItemRendererState initialise(Graphics2D g2, Rectangle2D dataArea,
1270            XYPlot plot, XYDataset dataset, PlotRenderingInfo info);
1271
1272    /**
1273     * Called for each item to be plotted.
1274     * <p>
1275     * The {@link XYPlot} can make multiple passes through the dataset,
1276     * depending on the value returned by the renderer's initialise() method.
1277     *
1278     * @param g2  the graphics device.
1279     * @param state  the renderer state.
1280     * @param dataArea  the area within which the data is being rendered.
1281     * @param info  collects drawing info.
1282     * @param plot  the plot (can be used to obtain standard color
1283     *              information etc).
1284     * @param domainAxis  the domain axis.
1285     * @param rangeAxis  the range axis.
1286     * @param dataset  the dataset.
1287     * @param series  the series index (zero-based).
1288     * @param item  the item index (zero-based).
1289     * @param crosshairState  crosshair information for the plot
1290     *                        ({@code null} permitted).
1291     * @param pass  the pass index.
1292     */
1293    public void drawItem(Graphics2D g2, XYItemRendererState state,
1294            Rectangle2D dataArea, PlotRenderingInfo info, XYPlot plot,
1295            ValueAxis domainAxis, ValueAxis rangeAxis, XYDataset dataset,
1296            int series, int item, CrosshairState crosshairState, int pass);
1297
1298    /**
1299     * Fills a band between two values on the axis.  This can be used to color
1300     * bands between the grid lines.
1301     *
1302     * @param g2  the graphics device.
1303     * @param plot  the plot.
1304     * @param axis  the domain axis.
1305     * @param dataArea  the data area.
1306     * @param start  the start value.
1307     * @param end  the end value.
1308     */
1309    public void fillDomainGridBand(Graphics2D g2, XYPlot plot, ValueAxis axis,
1310            Rectangle2D dataArea, double start, double end);
1311
1312    /**
1313     * Fills a band between two values on the range axis.  This can be used to
1314     * color bands between the grid lines.
1315     *
1316     * @param g2  the graphics device.
1317     * @param plot  the plot.
1318     * @param axis  the range axis.
1319     * @param dataArea  the data area.
1320     * @param start  the start value.
1321     * @param end  the end value.
1322     */
1323    public void fillRangeGridBand(Graphics2D g2, XYPlot plot, ValueAxis axis,
1324            Rectangle2D dataArea, double start, double end);
1325
1326    /**
1327     * Draws a grid line against the domain axis.
1328     *
1329     * @param g2  the graphics device.
1330     * @param plot  the plot.
1331     * @param axis  the value axis.
1332     * @param dataArea  the area for plotting data.
1333     * @param value  the value.
1334     * @param paint  the paint ({@code null} not permitted).
1335     * @param stroke  the stroke ({@code null} not permitted).
1336     */
1337    public void drawDomainLine(Graphics2D g2, XYPlot plot, ValueAxis axis,
1338            Rectangle2D dataArea, double value, Paint paint, Stroke stroke);
1339
1340    /**
1341     * Draws a line perpendicular to the range axis.
1342     *
1343     * @param g2  the graphics device.
1344     * @param plot  the plot.
1345     * @param axis  the value axis.
1346     * @param dataArea  the area for plotting data.
1347     * @param value  the data value.
1348     * @param paint  the paint ({@code null} not permitted).
1349     * @param stroke  the stroke ({@code null} not permitted).
1350     */
1351    public void drawRangeLine(Graphics2D g2, XYPlot plot, ValueAxis axis,
1352            Rectangle2D dataArea, double value, Paint paint, Stroke stroke);
1353
1354    /**
1355     * Draws the specified {@code marker} against the domain axis.
1356     *
1357     * @param g2  the graphics device.
1358     * @param plot  the plot.
1359     * @param axis  the value axis.
1360     * @param marker  the marker.
1361     * @param dataArea  the axis data area.
1362     */
1363    public void drawDomainMarker(Graphics2D g2, XYPlot plot, ValueAxis axis,
1364            Marker marker, Rectangle2D dataArea);
1365
1366    /**
1367     * Draws a horizontal line across the chart to represent a 'range marker'.
1368     *
1369     * @param g2  the graphics device.
1370     * @param plot  the plot.
1371     * @param axis  the value axis.
1372     * @param marker  the marker line.
1373     * @param dataArea  the axis data area.
1374     */
1375    public void drawRangeMarker(Graphics2D g2, XYPlot plot, ValueAxis axis,
1376            Marker marker, Rectangle2D dataArea);
1377
1378}