KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jfree > chart > renderer > category > CategoryItemRenderer


1 /* ===========================================================
2  * JFreeChart : a free chart library for the Java(tm) platform
3  * ===========================================================
4  *
5  * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
6  *
7  * Project Info: http://www.jfree.org/jfreechart/index.html
8  *
9  * This library is free software; you can redistribute it and/or modify it
10  * under the terms of the GNU Lesser General Public License as published by
11  * the Free Software Foundation; either version 2.1 of the License, or
12  * (at your option) any later version.
13  *
14  * This library is distributed in the hope that it will be useful, but
15  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
17  * License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public
20  * License along with this library; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
22  * USA.
23  *
24  * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
25  * in the United States and other countries.]
26  *
27  * -------------------------
28  * CategoryItemRenderer.java
29  * -------------------------
30  *
31  * (C) Copyright 2001-2005, by Object Refinery Limited and Contributors.
32  *
33  * Original Author: David Gilbert (for Object Refinery Limited);
34  * Contributor(s): Mark Watson (www.markwatson.com);
35  *
36  * $Id: CategoryItemRenderer.java,v 1.10.2.1 2005/10/25 20:54:16 mungady Exp $
37  *
38  * Changes
39  * -------
40  * 23-Oct-2001 : Version 1 (DG);
41  * 16-Jan-2002 : Renamed HorizontalCategoryItemRenderer.java
42  * --> CategoryItemRenderer.java (DG);
43  * 05-Feb-2002 : Changed return type of the drawCategoryItem method from void
44  * to Shape, as part of the tooltips implementation (DG)
45  *
46  * NOTE (30-May-2002) : this has subsequently been changed back
47  * to void, tooltips are now collected along with entities in
48  * ChartRenderingInfo (DG);
49  *
50  * 14-Mar-2002 : Added the initialise method, and changed all bar plots to use
51  * this renderer (DG);
52  * 23-May-2002 : Added ChartRenderingInfo to the initialise method (DG);
53  * 29-May-2002 : Added the getAxisArea(Rectangle2D) method (DG);
54  * 06-Jun-2002 : Updated Javadoc comments (DG);
55  * 26-Jun-2002 : Added range axis to the initialise method (DG);
56  * 24-Sep-2002 : Added getLegendItem() method (DG);
57  * 23-Oct-2002 : Added methods to get/setToolTipGenerator (DG);
58  * 05-Nov-2002 : Replaced references to CategoryDataset with TableDataset (DG);
59  * 06-Nov-2002 : Added the domain axis to the drawCategoryItem method. Renamed
60  * drawCategoryItem() --> drawItem() (DG);
61  * 20-Nov-2002 : Changed signature of drawItem() method to reflect use of
62  * TableDataset (DG);
63  * 26-Nov-2002 : Replaced the isStacked() method with the getRangeType()
64  * method (DG);
65  * 08-Jan-2003 : Changed getSeriesCount() --> getRowCount() and
66  * getCategoryCount() --> getColumnCount() (DG);
67  * 09-Jan-2003 : Changed name of grid-line methods (DG);
68  * 21-Jan-2003 : Merged TableDataset with CategoryDataset (DG);
69  * 10-Apr-2003 : Changed CategoryDataset to KeyedValues2DDataset in
70  * drawItem() method (DG);
71  * 29-Apr-2003 : Eliminated Renderer interface (DG);
72  * 02-Sep-2003 : Fix for bug 790407 (DG);
73  * 16-Sep-2003 : Changed ChartRenderingInfo --> PlotRenderingInfo (DG);
74  * 20-Oct-2003 : Added setOutlinePaint() method (DG);
75  * 06-Feb-2004 : Added missing methods, and moved deprecated methods (DG);
76  * 19-Feb-2004 : Added extra setXXXLabelsVisible() methods (DG);
77  * 29-Apr-2004 : Changed Integer --> int in initialise() method (DG);
78  * 18-May-2004 : Added methods for item label paint (DG);
79  * 05-Nov-2004 : Added getPassCount() method and 'pass' parameter to drawItem()
80  * method (DG);
81  * 07-Jan-2005 : Renamed getRangeExtent() --> findRangeBounds (DG);
82  * 11-Jan-2005 : Removed deprecated code in preparation for 1.0.0 release (DG);
83  * 23-Feb-2005 : Now extends LegendItemSource (DG);
84  * 20-Apr-2005 : Renamed CategoryLabelGenerator
85  * --> CategoryItemLabelGenerator (DG);
86  * 20-May-2005 : Added drawDomainMarker() method (DG);
87  *
88  */
89
90 package org.jfree.chart.renderer.category;
91
92 import java.awt.Font JavaDoc;
93 import java.awt.Graphics2D JavaDoc;
94 import java.awt.Paint JavaDoc;
95 import java.awt.Shape JavaDoc;
96 import java.awt.Stroke JavaDoc;
97 import java.awt.geom.Rectangle2D JavaDoc;
98
99 import org.jfree.chart.LegendItem;
100 import org.jfree.chart.LegendItemSource;
101 import org.jfree.chart.axis.CategoryAxis;
102 import org.jfree.chart.axis.ValueAxis;
103 import org.jfree.chart.event.RendererChangeEvent;
104 import org.jfree.chart.event.RendererChangeListener;
105 import org.jfree.chart.labels.CategoryItemLabelGenerator;
106 import org.jfree.chart.labels.CategoryToolTipGenerator;
107 import org.jfree.chart.labels.ItemLabelPosition;
108 import org.jfree.chart.plot.CategoryMarker;
109 import org.jfree.chart.plot.CategoryPlot;
110 import org.jfree.chart.plot.Marker;
111 import org.jfree.chart.plot.PlotRenderingInfo;
112 import org.jfree.chart.urls.CategoryURLGenerator;
113 import org.jfree.data.Range;
114 import org.jfree.data.category.CategoryDataset;
115
116 /**
117  * A plug-in object that is used by the {@link CategoryPlot} class to display
118  * individual data items from a {@link CategoryDataset}.
119  * <p>
120  * This interface defines the methods that must be provided by all renderers.
121  * If you are implementing a custom renderer, you should consider extending the
122  * {@link AbstractCategoryItemRenderer} class.
123  * <p>
124  * Most renderer attributes are defined using a "three layer" approach. When
125  * looking up an attribute (for example, the outline paint) the renderer first
126  * checks to see if there is a setting (in layer 0) that applies to ALL items
127  * that the renderer draws. If there is, that setting is used, but if it is
128  * <code>null</code> the renderer looks up the next layer, which contains
129  * "per series" settings for the attribute (many attributes are defined on a
130  * per series basis, so this is the layer that is most commonly used). If the
131  * layer 1 setting is <code>null</code>, the renderer will look up the final
132  * layer, which provides a default or "base" setting. Some attributes allow
133  * the base setting to be <code>null</code>, while other attributes enforce
134  * non-<code>null</code> values.
135  */
136
137 public interface CategoryItemRenderer extends LegendItemSource {
138
139     /**
140      * Returns the number of passes through the dataset required by the
141      * renderer. Usually this will be one, but some renderers may use
142      * a second or third pass to overlay items on top of things that were
143      * drawn in an earlier pass.
144      *
145      * @return The pass count.
146      */
147     public int getPassCount();
148
149     /**
150      * Returns the plot that the renderer has been assigned to (where
151      * <code>null</code> indicates that the renderer is not currently assigned
152      * to a plot).
153      *
154      * @return The plot (possibly <code>null</code>).
155      */
156     public CategoryPlot getPlot();
157
158     /**
159      * Sets the plot that the renderer has been assigned to. This method is
160      * usually called by the {@link CategoryPlot}, in normal usage you
161      * shouldn't need to call this method directly.
162      *
163      * @param plot the plot (<code>null</code> not permitted).
164      */
165     public void setPlot(CategoryPlot plot);
166
167     /**
168      * Adds a change listener.
169      *
170      * @param listener the listener.
171      */
172     public void addChangeListener(RendererChangeListener listener);
173     
174     /**
175      * Removes a change listener.
176      *
177      * @param listener the listener.
178      */
179     public void removeChangeListener(RendererChangeListener listener);
180
181     /**
182      * Returns the range of values the renderer requires to display all the
183      * items from the specified dataset.
184      *
185      * @param dataset the dataset (<code>null</code> permitted).
186      *
187      * @return The range (or <code>null</code> if the dataset is
188      * <code>null</code> or empty).
189      */
190     public Range findRangeBounds(CategoryDataset dataset);
191     
192     /**
193      * Initialises the renderer. This method will be called before the first
194      * item is rendered, giving the renderer an opportunity to initialise any
195      * state information it wants to maintain. The renderer can do nothing if
196      * it chooses.
197      *
198      * @param g2 the graphics device.
199      * @param dataArea the area inside the axes.
200      * @param plot the plot.
201      * @param rendererIndex the renderer index.
202      * @param info collects chart rendering information for return to caller.
203      *
204      * @return A state object (maintains state information relevant to one
205      * chart drawing).
206      */
207     public CategoryItemRendererState initialise(Graphics2D JavaDoc g2,
208                                                 Rectangle2D JavaDoc dataArea,
209                                                 CategoryPlot plot,
210                                                 int rendererIndex,
211                                                 PlotRenderingInfo info);
212                            
213     /**
214      * Returns a boolean that indicates whether or not the specified item
215      * should be drawn (this is typically used to hide an entire series).
216      *
217      * @param series the series index.
218      * @param item the item index.
219      *
220      * @return A boolean.
221      */
222     public boolean getItemVisible(int series, int item);
223     
224     /**
225      * Returns a boolean that indicates whether or not the specified series
226      * should be drawn (this is typically used to hide an entire series).
227      *
228      * @param series the series index.
229      *
230      * @return A boolean.
231      */
232     public boolean isSeriesVisible(int series);
233     
234     /**
235      * Returns the flag that controls the visibility of ALL series. This flag
236      * overrides the per series and default settings - you must set it to
237      * <code>null</code> if you want the other settings to apply.
238      *
239      * @return The flag (possibly <code>null</code>).
240      */
241     public Boolean JavaDoc getSeriesVisible();
242     
243     /**
244      * Sets the flag that controls the visibility of ALL series and sends a
245      * {@link RendererChangeEvent} to all registered listeners. This flag
246      * overrides the per series and default settings - you must set it to
247      * <code>null</code> if you want the other settings to apply.
248      *
249      * @param visible the flag (<code>null</code> permitted).
250      */
251     public void setSeriesVisible(Boolean JavaDoc visible);
252     
253     /**
254      * Sets the flag that controls the visibility of ALL series and sends a
255      * {@link RendererChangeEvent} to all registered listeners. This flag
256      * overrides the per series and default settings - you must set it to
257      * <code>null</code> if you want the other settings to apply.
258      *
259      * @param visible the flag (<code>null</code> permitted).
260      * @param notify notify listeners?
261      */
262     public void setSeriesVisible(Boolean JavaDoc visible, boolean notify);
263     
264     /**
265      * Returns the flag that controls whether a series is visible.
266      *
267      * @param series the series index (zero-based).
268      *
269      * @return The flag (possibly <code>null</code>).
270      */
271     public Boolean JavaDoc getSeriesVisible(int series);
272     
273     /**
274      * Sets the flag that controls whether a series is visible and sends a
275      * {@link RendererChangeEvent} to all registered listeners.
276      *
277      * @param series the series index (zero-based).
278      * @param visible the flag (<code>null</code> permitted).
279      */
280     public void setSeriesVisible(int series, Boolean JavaDoc visible);
281     
282     /**
283      * Sets the flag that controls whether a series is visible and, if
284      * requested, sends a {@link RendererChangeEvent} to all registered
285      * listeners.
286      *
287      * @param series the series index.
288      * @param visible the flag (<code>null</code> permitted).
289      * @param notify notify listeners?
290      */
291     public void setSeriesVisible(int series, Boolean JavaDoc visible, boolean notify);
292
293     /**
294      * Returns the base visibility for all series.
295      *
296      * @return The base visibility.
297      */
298     public boolean getBaseSeriesVisible();
299
300     /**
301      * Sets the base visibility and sends a {@link RendererChangeEvent} to all
302      * registered listeners.
303      *
304      * @param visible the flag.
305      */
306     public void setBaseSeriesVisible(boolean visible);
307     
308     /**
309      * Sets the base visibility and, if requested, sends
310      * a {@link RendererChangeEvent} to all registered listeners.
311      *
312      * @param visible the visibility.
313      * @param notify notify listeners?
314      */
315     public void setBaseSeriesVisible(boolean visible, boolean notify);
316
317     // SERIES VISIBLE IN LEGEND (not yet respected by all renderers)
318
319     /**
320      * Returns <code>true</code> if the series should be shown in the legend,
321      * and <code>false</code> otherwise.
322      *
323      * @param series the series index.
324      *
325      * @return A boolean.
326      */
327     public boolean isSeriesVisibleInLegend(int series);
328     
329     /**
330      * Returns the flag that controls the visibility of ALL series in the
331      * legend. This flag overrides the per series and default settings - you
332      * must set it to <code>null</code> if you want the other settings to
333      * apply.
334      *
335      * @return The flag (possibly <code>null</code>).
336      */
337     public Boolean JavaDoc getSeriesVisibleInLegend();
338     
339     /**
340      * Sets the flag that controls the visibility of ALL series in the legend
341      * and sends a {@link RendererChangeEvent} to all registered listeners.
342      * This flag overrides the per series and default settings - you must set
343      * it to <code>null</code> if you want the other settings to apply.
344      *
345      * @param visible the flag (<code>null</code> permitted).
346      */
347     public void setSeriesVisibleInLegend(Boolean JavaDoc visible);
348     
349     /**
350      * Sets the flag that controls the visibility of ALL series in the legend
351      * and sends a {@link RendererChangeEvent} to all registered listeners.
352      * This flag overrides the per series and default settings - you must set
353      * it to <code>null</code> if you want the other settings to apply.
354      *
355      * @param visible the flag (<code>null</code> permitted).
356      * @param notify notify listeners?
357      */
358     public void setSeriesVisibleInLegend(Boolean JavaDoc visible, boolean notify);
359     
360     /**
361      * Returns the flag that controls whether a series is visible in the
362      * legend. This method returns only the "per series" settings - to
363      * incorporate the override and base settings as well, you need to use the
364      * {@link #isSeriesVisibleInLegend(int)} method.
365      *
366      * @param series the series index (zero-based).
367      *
368      * @return The flag (possibly <code>null</code>).
369      */
370     public Boolean JavaDoc getSeriesVisibleInLegend(int series);
371     
372     /**
373      * Sets the flag that controls whether a series is visible in the legend
374      * and sends a {@link RendererChangeEvent} to all registered listeners.
375      *
376      * @param series the series index (zero-based).
377      * @param visible the flag (<code>null</code> permitted).
378      */
379     public void setSeriesVisibleInLegend(int series, Boolean JavaDoc visible);
380     
381     /**
382      * Sets the flag that controls whether a series is visible in the legend
383      * and, if requested, sends a {@link RendererChangeEvent} to all registered
384      * listeners.
385      *
386      * @param series the series index.
387      * @param visible the flag (<code>null</code> permitted).
388      * @param notify notify listeners?
389      */
390     public void setSeriesVisibleInLegend(int series, Boolean JavaDoc visible,
391                                          boolean notify);
392
393     /**
394      * Returns the base visibility in the legend for all series.
395      *
396      * @return The base visibility.
397      */
398     public boolean getBaseSeriesVisibleInLegend();
399
400     /**
401      * Sets the base visibility in the legend and sends a
402      * {@link RendererChangeEvent} to all registered listeners.
403      *
404      * @param visible the flag.
405      */
406     public void setBaseSeriesVisibleInLegend(boolean visible);
407     
408     /**
409      * Sets the base visibility in the legend and, if requested, sends
410      * a {@link RendererChangeEvent} to all registered listeners.
411      *
412      * @param visible the visibility.
413      * @param notify notify listeners?
414      */
415     public void setBaseSeriesVisibleInLegend(boolean visible, boolean notify);
416
417
418     //// PAINT /////////////////////////////////////////////////////////////////
419
420     /**
421      * Returns the paint used to fill data items as they are drawn.
422      *
423      * @param row the row (or series) index (zero-based).
424      * @param column the column (or category) index (zero-based).
425      *
426      * @return The paint (never <code>null</code>).
427      */
428     public Paint JavaDoc getItemPaint(int row, int column);
429
430     /**
431      * Sets the paint to be used for ALL series, and sends a
432      * {@link RendererChangeEvent} to all registered listeners. If this is
433      * <code>null</code>, the renderer will use the paint for the series.
434      *
435      * @param paint the paint (<code>null</code> permitted).
436      */
437     public void setPaint(Paint JavaDoc paint);
438     
439     /**
440      * Returns the paint used to fill an item drawn by the renderer.
441      *
442      * @param series the series index (zero-based).
443      *
444      * @return The paint (never <code>null</code>).
445      */
446     public Paint JavaDoc getSeriesPaint(int series);
447
448     /**
449      * Sets the paint used for a series and sends a {@link RendererChangeEvent}
450      * to all registered listeners.
451      *
452      * @param series the series index (zero-based).
453      * @param paint the paint (<code>null</code> permitted).
454      */
455     public void setSeriesPaint(int series, Paint JavaDoc paint);
456     
457     /**
458      * Returns the base paint.
459      *
460      * @return The base paint (never <code>null</code>).
461      */
462     public Paint JavaDoc getBasePaint();
463
464     /**
465      * Sets the base paint and sends a {@link RendererChangeEvent} to all
466      * registered listeners.
467      *
468      * @param paint the paint (<code>null</code> not permitted).
469      */
470     public void setBasePaint(Paint JavaDoc paint);
471     
472     //// OUTLINE PAINT /////////////////////////////////////////////////////////
473
474     /**
475      * Returns the paint used to outline data items as they are drawn.
476      *
477      * @param row the row (or series) index (zero-based).
478      * @param column the column (or category) index (zero-based).
479      *
480      * @return The paint (never <code>null</code>).
481      */
482     public Paint JavaDoc getItemOutlinePaint(int row, int column);
483
484     /**
485      * Sets the outline paint for ALL series (optional).
486      *
487      * @param paint the paint (<code>null</code> permitted).
488      */
489     public void setOutlinePaint(Paint JavaDoc paint);
490     
491     /**
492      * Returns the paint used to outline an item drawn by the renderer.
493      *
494      * @param series the series (zero-based index).
495      *
496      * @return The paint (never <code>null</code>).
497      */
498     public Paint JavaDoc getSeriesOutlinePaint(int series);
499
500     /**
501      * Sets the paint used for a series outline and sends a
502      * {@link RendererChangeEvent} to all registered listeners.
503      *
504      * @param series the series index (zero-based).
505      * @param paint the paint (<code>null</code> permitted).
506      */
507     public void setSeriesOutlinePaint(int series, Paint JavaDoc paint);
508
509     /**
510      * Returns the base outline paint.
511      *
512      * @return The paint (never <code>null</code>).
513      */
514     public Paint JavaDoc getBaseOutlinePaint();
515
516     /**
517      * Sets the base outline paint and sends a {@link RendererChangeEvent} to
518      * all registered listeners.
519      *
520      * @param paint the paint (<code>null</code> not permitted).
521      */
522     public void setBaseOutlinePaint(Paint JavaDoc paint);
523
524     //// STROKE ////////////////////////////////////////////////////////////////
525
526     /**
527      * Returns the stroke used to draw data items.
528      *
529      * @param row the row (or series) index (zero-based).
530      * @param column the column (or category) index (zero-based).
531      *
532      * @return The stroke (never <code>null</code>).
533      */
534     public Stroke JavaDoc getItemStroke(int row, int column);
535
536     /**
537      * Sets the stroke for ALL series and sends a {@link RendererChangeEvent}
538      * to all registered listeners.
539      *
540      * @param stroke the stroke (<code>null</code> permitted).
541      */
542     public void setStroke(Stroke JavaDoc stroke);
543
544     /**
545      * Returns the stroke used to draw the items in a series.
546      *
547      * @param series the series (zero-based index).
548      *
549      * @return The stroke (never <code>null</code>).
550      */
551     public Stroke JavaDoc getSeriesStroke(int series);
552     
553     /**
554      * Sets the stroke used for a series and sends a
555      * {@link RendererChangeEvent} to all registered listeners.
556      *
557      * @param series the series index (zero-based).
558      * @param stroke the stroke (<code>null</code> permitted).
559      */
560     public void setSeriesStroke(int series, Stroke JavaDoc stroke);
561
562     /**
563      * Returns the base stroke.
564      *
565      * @return The base stroke (never <code>null</code>).
566      */
567     public Stroke JavaDoc getBaseStroke();
568
569     /**
570      * Sets the base stroke.
571      *
572      * @param stroke the stroke (<code>null</code> not permitted).
573      */
574     public void setBaseStroke(Stroke JavaDoc stroke);
575     
576     //// OUTLINE STROKE ////////////////////////////////////////////////////////
577
578     /**
579      * Returns the stroke used to outline data items.
580      * <p>
581      * The default implementation passes control to the getSeriesOutlineStroke
582      * method. You can override this method if you require different behaviour.
583      *
584      * @param row the row (or series) index (zero-based).
585      * @param column the column (or category) index (zero-based).
586      *
587      * @return The stroke (never <code>null</code>).
588      */
589     public Stroke JavaDoc getItemOutlineStroke(int row, int column);
590
591     /**
592      * Sets the outline stroke for ALL series and sends a
593      * {@link RendererChangeEvent} to all registered listeners.
594      *
595      * @param stroke the stroke (<code>null</code> permitted).
596      */
597     public void setOutlineStroke(Stroke JavaDoc stroke);
598     
599     /**
600      * Returns the stroke used to outline the items in a series.
601      *
602      * @param series the series (zero-based index).
603      *
604      * @return The stroke (never <code>null</code>).
605      */
606     public Stroke JavaDoc getSeriesOutlineStroke(int series);
607
608     /**
609      * Sets the outline stroke used for a series and sends a
610      * {@link RendererChangeEvent} to all registered listeners.
611      *
612      * @param series the series index (zero-based).
613      * @param stroke the stroke (<code>null</code> permitted).
614      */
615     public void setSeriesOutlineStroke(int series, Stroke JavaDoc stroke);
616     
617     /**
618      * Returns the base outline stroke.
619      *
620      * @return The stroke (never <code>null</code>).
621      */
622     public Stroke JavaDoc getBaseOutlineStroke();
623
624     /**
625      * Sets the base outline stroke and sends a {@link RendererChangeEvent} to
626      * all registered listeners.
627      *
628      * @param stroke the stroke (<code>null</code> not permitted).
629      */
630     public void setBaseOutlineStroke(Stroke JavaDoc stroke);
631     
632     //// SHAPE /////////////////////////////////////////////////////////////////
633
634     /**
635      * Returns a shape used to represent a data item.
636      *
637      * @param row the row (or series) index (zero-based).
638      * @param column the column (or category) index (zero-based).
639      *
640      * @return The shape (never <code>null</code>).
641      */
642     public Shape JavaDoc getItemShape(int row, int column);
643
644     /**
645      * Sets the shape for ALL series (optional) and sends a
646      * {@link RendererChangeEvent} to all registered listeners.
647      *
648      * @param shape the shape (<code>null</code> permitted).
649      */
650     public void setShape(Shape JavaDoc shape);
651     
652     /**
653      * Returns a shape used to represent the items in a series.
654      *
655      * @param series the series (zero-based index).
656      *
657      * @return The shape (never <code>null</code>).
658      */
659     public Shape JavaDoc getSeriesShape(int series);
660
661     /**
662      * Sets the shape used for a series and sends a {@link RendererChangeEvent}
663      * to all registered listeners.
664      *
665      * @param series the series index (zero-based).
666      * @param shape the shape (<code>null</code> permitted).
667      */
668     public void setSeriesShape(int series, Shape JavaDoc shape);
669     
670     /**
671      * Returns the base shape.
672      *
673      * @return The shape (never <code>null</code>).
674      */
675     public Shape JavaDoc getBaseShape();
676
677     /**
678      * Sets the base shape and sends a {@link RendererChangeEvent} to all
679      * registered listeners.
680      *
681      * @param shape the shape (<code>null</code> not permitted).
682      */
683     public void setBaseShape(Shape JavaDoc shape);
684     
685     // ITEM LABELS VISIBLE
686
687     /**
688      * Returns <code>true</code> if an item label is visible, and
689      * <code>false</code> otherwise.
690      *
691      * @param row the row index (zero-based).
692      * @param column the column index (zero-based).
693      *
694      * @return A boolean.
695      */
696     public boolean isItemLabelVisible(int row, int column);
697     
698     /**
699      * Returns <code>true</code> if the item labels for a series are visible,
700      * and <code>false</code> otherwise.
701      *
702      * @param series the series index (zero-based).
703      *
704      * @return A boolean.
705      */
706     public boolean isSeriesItemLabelsVisible(int series);
707     
708     /**
709      * Sets a flag that controls whether or not the item labels for ALL series
710      * are visible.
711      *
712      * @param visible the flag.
713      */
714     public void setItemLabelsVisible(boolean visible);
715
716     /**
717      * Sets a flag that controls whether or not the item labels for ALL series
718      * are visible.
719      *
720      * @param visible the flag (<code>null</code> permitted).
721      */
722     public void setItemLabelsVisible(Boolean JavaDoc visible);
723
724     /**
725      * Sets the visibility of item labels for ALL series and, if requested,
726      * sends a {@link RendererChangeEvent} to all registered listeners.
727      *
728      * @param visible a flag that controls whether or not the item labels are
729      * visible (<code>null</code> permitted).
730      * @param notify a flag that controls whether or not listeners are
731      * notified.
732      */
733     public void setItemLabelsVisible(Boolean JavaDoc visible, boolean notify);
734
735     /**
736      * Sets a flag that controls the visibility of the item labels for a series.
737      *
738      * @param series the series index (zero-based).
739      * @param visible the flag.
740      */
741     public void setSeriesItemLabelsVisible(int series, boolean visible);
742     
743     /**
744      * Sets a flag that controls the visibility of the item labels for a series.
745      *
746      * @param series the series index (zero-based).
747      * @param visible the flag (<code>null</code> permitted).
748      */
749     public void setSeriesItemLabelsVisible(int series, Boolean JavaDoc visible);
750     
751     /**
752      * Sets the visibility of item labels for a series and, if requested, sends
753      * a {@link RendererChangeEvent} to all registered listeners.
754      *
755      * @param series the series index (zero-based).
756      * @param visible the visible flag.
757      * @param notify a flag that controls whether or not listeners are
758      * notified.
759      */
760     public void setSeriesItemLabelsVisible(int series, Boolean JavaDoc visible,
761                                            boolean notify);
762     
763     /**
764      * Returns the base setting for item label visibility.
765      *
766      * @return A flag (possibly <code>null</code>).
767      */
768     public Boolean JavaDoc getBaseItemLabelsVisible();
769     
770     /**
771      * Sets the base flag that controls whether or not item labels are visible.
772      *
773      * @param visible the flag.
774      */
775     public void setBaseItemLabelsVisible(boolean visible);
776     
777     /**
778      * Sets the base setting for item label visibility.
779      *
780      * @param visible the flag (<code>null</code> permitted).
781      */
782     public void setBaseItemLabelsVisible(Boolean JavaDoc visible);
783     
784     /**
785      * Sets the base visibility for item labels and, if requested, sends a
786      * {@link RendererChangeEvent} to all registered listeners.
787      *
788      * @param visible the visibility flag.
789      * @param notify a flag that controls whether or not listeners are
790      * notified.
791      */
792     public void setBaseItemLabelsVisible(Boolean JavaDoc visible, boolean notify);
793     
794     // ITEM LABEL GENERATOR
795
796     /**
797      * Returns the item label generator for the specified data item.
798      *
799      * @param series the series index (zero-based).
800      * @param item the item index (zero-based).
801      *
802      * @return The generator (possibly <code>null</code>).
803      */
804     public CategoryItemLabelGenerator getItemLabelGenerator(int series,
805             int item);
806
807     /**
808      * Returns the item label generator for a series.
809      *
810      * @param series the series index (zero-based).
811      *
812      * @return The label generator (possibly <code>null</code>).
813      */
814     public CategoryItemLabelGenerator getSeriesItemLabelGenerator(int series);
815
816     /**
817      * Sets the item label generator for ALL series and sends a
818      * {@link RendererChangeEvent} to all registered listeners. This overrides
819      * the per-series settings.
820      *
821      * @param generator the generator (<code>null</code> permitted).
822      */
823     public void setItemLabelGenerator(CategoryItemLabelGenerator generator);
824     
825     /**
826      * Sets the item label generator for a series and sends a
827      * {@link RendererChangeEvent} to all registered listeners.
828      *
829      * @param series the series index (zero-based).
830      * @param generator the generator.
831      */
832     public void setSeriesItemLabelGenerator(
833             int series, CategoryItemLabelGenerator generator);
834
835     /**
836      * Returns the base item label generator.
837      *
838      * @return The generator (possibly <code>null</code>).
839      */
840     public CategoryItemLabelGenerator getBaseItemLabelGenerator();
841
842     /**
843      * Sets the base item label generator and sends a
844      * {@link RendererChangeEvent} to all registered listeners.
845      *
846      * @param generator the generator (<code>null</code> permitted).
847      */
848     public void setBaseItemLabelGenerator(CategoryItemLabelGenerator generator);
849
850     // TOOL TIP GENERATOR
851
852     /**
853      * Returns the tool tip generator that should be used for the specified
854      * item. This method looks up the generator using the "three-layer"
855      * approach outlined in the general description of this interface.
856      *
857      * @param row the row index (zero-based).
858      * @param column the column index (zero-based).
859      *
860      * @return The generator (possibly <code>null</code>).
861      */
862     public CategoryToolTipGenerator getToolTipGenerator(int row, int column);
863
864     /**
865      * Returns the tool tip generator that will be used for ALL items in the
866      * dataset (the "layer 0" generator).
867      *
868      * @return A tool tip generator (possibly <code>null</code>).
869      */
870     public CategoryToolTipGenerator getToolTipGenerator();
871
872     /**
873      * Sets the tool tip generator for ALL series and sends a
874      * {@link org.jfree.chart.event.RendererChangeEvent} to all registered
875      * listeners.
876      *
877      * @param generator the generator (<code>null</code> permitted).
878      */
879     public void setToolTipGenerator(CategoryToolTipGenerator generator);
880     
881     /**
882      * Returns the tool tip generator for the specified series (a "layer 1"
883      * generator).
884      *
885      * @param series the series index (zero-based).
886      *
887      * @return The tool tip generator (possibly <code>null</code>).
888      */
889     public CategoryToolTipGenerator getSeriesToolTipGenerator(int series);
890
891     /**
892      * Sets the tool tip generator for a series and sends a
893      * {@link org.jfree.chart.event.RendererChangeEvent} to all registered
894      * listeners.
895      *
896      * @param series the series index (zero-based).
897      * @param generator the generator (<code>null</code> permitted).
898      */
899     public void setSeriesToolTipGenerator(int series,
900                                           CategoryToolTipGenerator generator);
901
902     /**
903      * Returns the base tool tip generator (the "layer 2" generator).
904      *
905      * @return The tool tip generator (possibly <code>null</code>).
906      */
907     public CategoryToolTipGenerator getBaseToolTipGenerator();
908
909     /**
910      * Sets the base tool tip generator and sends a
911      * {@link org.jfree.chart.event.RendererChangeEvent} to all registered
912      * listeners.
913      *
914      * @param generator the generator (<code>null</code> permitted).
915      */
916     public void setBaseToolTipGenerator(CategoryToolTipGenerator generator);
917
918     //// ITEM LABEL FONT //////////////////////////////////////////////////////
919
920     /**
921      * Returns the font for an item label.
922      *
923      * @param row the row index (zero-based).
924      * @param column the column index (zero-based).
925      *
926      * @return The font (never <code>null</code>).
927      */
928     public Font JavaDoc getItemLabelFont(int row, int column);
929
930     /**
931      * Returns the font used for all item labels. This may be
932      * <code>null</code>, in which case the per series font settings will apply.
933      *
934      * @return The font (possibly <code>null</code>).
935      */
936     public Font JavaDoc getItemLabelFont();
937     
938     /**
939      * Sets the item label font for ALL series and sends a
940      * {@link RendererChangeEvent} to all registered listeners. You can set
941      * this to <code>null</code> if you prefer to set the font on a per series
942      * basis.
943      *
944      * @param font the font (<code>null</code> permitted).
945      */
946     public void setItemLabelFont(Font JavaDoc font);
947     
948     /**
949      * Returns the font for all the item labels in a series.
950      *
951      * @param series the series index (zero-based).
952      *
953      * @return The font (possibly <code>null</code>).
954      */
955     public Font JavaDoc getSeriesItemLabelFont(int series);
956
957     /**
958      * Sets the item label font for a series and sends a
959      * {@link RendererChangeEvent} to all registered listeners.
960      *
961      * @param series the series index (zero-based).
962      * @param font the font (<code>null</code> permitted).
963      */
964     public void setSeriesItemLabelFont(int series, Font JavaDoc font);
965
966     /**
967      * Returns the base item label font (this is used when no other font
968      * setting is available).
969      *
970      * @return The font (<code>never</code> null).
971      */
972     public Font JavaDoc getBaseItemLabelFont();
973
974     /**
975      * Sets the base item label font and sends a {@link RendererChangeEvent}
976      * to all registered listeners.
977      *
978      * @param font the font (<code>null</code> not permitted).
979      */
980     public void setBaseItemLabelFont(Font JavaDoc font);
981     
982     //// ITEM LABEL PAINT /////////////////////////////////////////////////////
983
984     /**
985      * Returns the paint used to draw an item label.
986      *
987      * @param row the row index (zero based).
988      * @param column the column index (zero based).
989      *
990      * @return The paint (never <code>null</code>).
991      */
992     public Paint JavaDoc getItemLabelPaint(int row, int column);
993     
994     /**
995      * Returns the paint used for all item labels. This may be
996      * <code>null</code>, in which case the per series paint settings will
997      * apply.
998      *
999      * @return The paint (possibly <code>null</code>).
1000     */
1001    public Paint JavaDoc getItemLabelPaint();
1002
1003    /**
1004 &nb