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