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