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