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     * CategoryItemRenderer.java
029     * -------------------------
030     *
031     * (C) Copyright 2001-2007, by Object Refinery Limited and Contributors.
032     *
033     * Original Author:  David Gilbert (for Object Refinery Limited);
034     * Contributor(s):   Mark Watson (www.markwatson.com);
035     *
036     * $Id: CategoryItemRenderer.java,v 1.10.2.2 2007/02/20 15:38:56 mungady Exp $
037     *
038     * Changes
039     * -------
040     * 23-Oct-2001 : Version 1 (DG);
041     * 16-Jan-2002 : Renamed HorizontalCategoryItemRenderer.java 
042     *               --> CategoryItemRenderer.java (DG);
043     * 05-Feb-2002 : Changed return type of the drawCategoryItem method from void 
044     *               to Shape, as part of the tooltips implementation (DG)        
045     *
046     *               NOTE (30-May-2002) : this has subsequently been changed back 
047     *               to void, tooltips are now collected along with entities in 
048     *               ChartRenderingInfo (DG);
049     *
050     * 14-Mar-2002 : Added the initialise method, and changed all bar plots to use 
051     *               this renderer (DG);
052     * 23-May-2002 : Added ChartRenderingInfo to the initialise method (DG);
053     * 29-May-2002 : Added the getAxisArea(Rectangle2D) method (DG);
054     * 06-Jun-2002 : Updated Javadoc comments (DG);
055     * 26-Jun-2002 : Added range axis to the initialise method (DG);
056     * 24-Sep-2002 : Added getLegendItem() method (DG);
057     * 23-Oct-2002 : Added methods to get/setToolTipGenerator (DG);
058     * 05-Nov-2002 : Replaced references to CategoryDataset with TableDataset (DG);
059     * 06-Nov-2002 : Added the domain axis to the drawCategoryItem method.  Renamed
060     *               drawCategoryItem() --> drawItem() (DG);
061     * 20-Nov-2002 : Changed signature of drawItem() method to reflect use of 
062     *               TableDataset (DG);
063     * 26-Nov-2002 : Replaced the isStacked() method with the getRangeType() 
064     *               method (DG);
065     * 08-Jan-2003 : Changed getSeriesCount() --> getRowCount() and
066     *               getCategoryCount() --> getColumnCount() (DG);
067     * 09-Jan-2003 : Changed name of grid-line methods (DG);
068     * 21-Jan-2003 : Merged TableDataset with CategoryDataset (DG);
069     * 10-Apr-2003 : Changed CategoryDataset to KeyedValues2DDataset in 
070     *               drawItem() method (DG);
071     * 29-Apr-2003 : Eliminated Renderer interface (DG);
072     * 02-Sep-2003 : Fix for bug 790407 (DG);
073     * 16-Sep-2003 : Changed ChartRenderingInfo --> PlotRenderingInfo (DG);
074     * 20-Oct-2003 : Added setOutlinePaint() method (DG);
075     * 06-Feb-2004 : Added missing methods, and moved deprecated methods (DG);
076     * 19-Feb-2004 : Added extra setXXXLabelsVisible() methods (DG);
077     * 29-Apr-2004 : Changed Integer --> int in initialise() method (DG);
078     * 18-May-2004 : Added methods for item label paint (DG);
079     * 05-Nov-2004 : Added getPassCount() method and 'pass' parameter to drawItem() 
080     *               method (DG);
081     * 07-Jan-2005 : Renamed getRangeExtent() --> findRangeBounds (DG);
082     * 11-Jan-2005 : Removed deprecated code in preparation for 1.0.0 release (DG);
083     * 23-Feb-2005 : Now extends LegendItemSource (DG);
084     * 20-Apr-2005 : Renamed CategoryLabelGenerator 
085     *               --> CategoryItemLabelGenerator (DG);
086     * 20-May-2005 : Added drawDomainMarker() method (DG);
087     * ------------- JFREECHART 1.0.x ---------------------------------------------
088     * 20-Feb-2007 : Updated API docs (DG);
089     * 
090     */
091    
092    package org.jfree.chart.renderer.category;
093    
094    import java.awt.Font;
095    import java.awt.Graphics2D;
096    import java.awt.Paint;
097    import java.awt.Shape;
098    import java.awt.Stroke;
099    import java.awt.geom.Rectangle2D;
100    
101    import org.jfree.chart.LegendItem;
102    import org.jfree.chart.LegendItemSource;
103    import org.jfree.chart.axis.CategoryAxis;
104    import org.jfree.chart.axis.ValueAxis;
105    import org.jfree.chart.event.RendererChangeEvent;
106    import org.jfree.chart.event.RendererChangeListener;
107    import org.jfree.chart.labels.CategoryItemLabelGenerator;
108    import org.jfree.chart.labels.CategoryToolTipGenerator;
109    import org.jfree.chart.labels.ItemLabelPosition;
110    import org.jfree.chart.plot.CategoryMarker;
111    import org.jfree.chart.plot.CategoryPlot;
112    import org.jfree.chart.plot.Marker;
113    import org.jfree.chart.plot.PlotRenderingInfo;
114    import org.jfree.chart.urls.CategoryURLGenerator;
115    import org.jfree.data.Range;
116    import org.jfree.data.category.CategoryDataset;
117    
118    /**
119     * A plug-in object that is used by the {@link CategoryPlot} class to display 
120     * individual data items from a {@link CategoryDataset}.
121     * <p>
122     * This interface defines the methods that must be provided by all renderers.  
123     * If you are implementing a custom renderer, you should consider extending the
124     * {@link AbstractCategoryItemRenderer} class.
125     * <p>
126     * Most renderer attributes are defined using a "three layer" approach.  When 
127     * looking up an attribute (for example, the outline paint) the renderer first 
128     * checks to see if there is a setting (in layer 0) that applies to ALL items 
129     * that the renderer draws.  If there is, that setting is used, but if it is 
130     * <code>null</code> the renderer looks up the next layer, which contains 
131     * "per series" settings for the attribute (many attributes are defined on a
132     * per series basis, so this is the layer that is most commonly used).  If the 
133     * layer 1 setting is <code>null</code>, the renderer will look up the final 
134     * layer, which provides a default or "base" setting.  Some attributes allow 
135     * the base setting to be <code>null</code>, while other attributes enforce 
136     * non-<code>null</code> values.
137     */
138    
139    public interface CategoryItemRenderer extends LegendItemSource {
140    
141        /**
142         * Returns the number of passes through the dataset required by the 
143         * renderer.  Usually this will be one, but some renderers may use
144         * a second or third pass to overlay items on top of things that were
145         * drawn in an earlier pass.
146         * 
147         * @return The pass count.
148         */
149        public int getPassCount();
150    
151        /**
152         * Returns the plot that the renderer has been assigned to (where 
153         * <code>null</code> indicates that the renderer is not currently assigned 
154         * to a plot).
155         *
156         * @return The plot (possibly <code>null</code>).
157         * 
158         * @see #setPlot(CategoryPlot)
159         */
160        public CategoryPlot getPlot();
161    
162        /**
163         * Sets the plot that the renderer has been assigned to.  This method is 
164         * usually called by the {@link CategoryPlot}, in normal usage you 
165         * shouldn't need to call this method directly.
166         *
167         * @param plot  the plot (<code>null</code> not permitted).
168         * 
169         * @see #getPlot()
170         */
171        public void setPlot(CategoryPlot plot);
172    
173        /**
174         * Adds a change listener.
175         * 
176         * @param listener  the listener.
177         * 
178         * @see #removeChangeListener(RendererChangeListener)
179         */
180        public void addChangeListener(RendererChangeListener listener);
181        
182        /**
183         * Removes a change listener.
184         * 
185         * @param listener  the listener.
186         * 
187         * @see #addChangeListener(RendererChangeListener)
188         */
189        public void removeChangeListener(RendererChangeListener listener);
190    
191        /**
192         * Returns the range of values the renderer requires to display all the 
193         * items from the specified dataset.
194         * 
195         * @param dataset  the dataset (<code>null</code> permitted).
196         * 
197         * @return The range (or <code>null</code> if the dataset is 
198         *         <code>null</code> or empty).
199         */
200        public Range findRangeBounds(CategoryDataset dataset);
201        
202        /**
203         * Initialises the renderer.  This method will be called before the first 
204         * item is rendered, giving the renderer an opportunity to initialise any 
205         * state information it wants to maintain. The renderer can do nothing if 
206         * it chooses.
207         *
208         * @param g2  the graphics device.
209         * @param dataArea  the area inside the axes.
210         * @param plot  the plot.
211         * @param rendererIndex  the renderer index.
212         * @param info  collects chart rendering information for return to caller.
213         * 
214         * @return A state object (maintains state information relevant to one 
215         *         chart drawing).
216         */
217        public CategoryItemRendererState initialise(Graphics2D g2,
218                                                    Rectangle2D dataArea,
219                                                    CategoryPlot plot,
220                                                    int rendererIndex,
221                                                    PlotRenderingInfo info);
222                               
223        /**
224         * Returns a boolean that indicates whether or not the specified item 
225         * should be drawn (this is typically used to hide an entire series).
226         * 
227         * @param series  the series index.
228         * @param item  the item index.
229         * 
230         * @return A boolean.
231         */
232        public boolean getItemVisible(int series, int item);
233        
234        /**
235         * Returns a boolean that indicates whether or not the specified series 
236         * should be drawn (this is typically used to hide an entire series).
237         * 
238         * @param series  the series index.
239         * 
240         * @return A boolean.
241         */
242        public boolean isSeriesVisible(int series);
243        
244        /**
245         * Returns the flag that controls the visibility of ALL series.  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         * @return The flag (possibly <code>null</code>).
250         * 
251         * @see #setSeriesVisible(Boolean)
252         */
253        public Boolean getSeriesVisible();
254        
255        /**
256         * Sets the flag that controls the visibility of ALL series and sends a 
257         * {@link RendererChangeEvent} to all registered listeners.  This flag 
258         * overrides the per series and default settings - you must set it to 
259         * <code>null</code> if you want the other settings to apply.
260         * 
261         * @param visible  the flag (<code>null</code> permitted).
262         * 
263         * @see #getSeriesVisible()
264         */
265        public void setSeriesVisible(Boolean visible);
266        
267        /**
268         * Sets the flag that controls the visibility of ALL series and sends a 
269         * {@link RendererChangeEvent} to all registered listeners.  This flag 
270         * overrides the per series and default settings - you must set it to 
271         * <code>null</code> if you want the other settings to apply.
272         * 
273         * @param visible  the flag (<code>null</code> permitted).
274         * @param notify  notify listeners?
275         * 
276         * @see #getSeriesVisible()
277         */
278        public void setSeriesVisible(Boolean visible, boolean notify);
279        
280        /**
281         * Returns the flag that controls whether a series is visible.
282         *
283         * @param series  the series index (zero-based).
284         *
285         * @return The flag (possibly <code>null</code>).
286         * 
287         * @see #setSeriesVisible(int, Boolean)
288         */
289        public Boolean getSeriesVisible(int series);
290        
291        /**
292         * Sets the flag that controls whether a series is visible and sends a 
293         * {@link RendererChangeEvent} to all registered listeners.
294         *
295         * @param series  the series index (zero-based).
296         * @param visible  the flag (<code>null</code> permitted).
297         * 
298         * @see #getSeriesVisible(int)
299         */
300        public void setSeriesVisible(int series, Boolean visible);
301        
302        /**
303         * Sets the flag that controls whether a series is visible and, if 
304         * requested, sends a {@link RendererChangeEvent} to all registered 
305         * listeners.
306         * 
307         * @param series  the series index.
308         * @param visible  the flag (<code>null</code> permitted).
309         * @param notify  notify listeners?
310         * 
311         * @see #getSeriesVisible(int)
312         */
313        public void setSeriesVisible(int series, Boolean visible, boolean notify);
314    
315        /**
316         * Returns the base visibility for all series.
317         *
318         * @return The base visibility.
319         * 
320         * @see #setBaseSeriesVisible(boolean)
321         */
322        public boolean getBaseSeriesVisible();
323    
324        /**
325         * Sets the base visibility and sends a {@link RendererChangeEvent} to all
326         * registered listeners.
327         *
328         * @param visible  the flag.
329         * 
330         * @see #getBaseSeriesVisible()
331         */
332        public void setBaseSeriesVisible(boolean visible);
333        
334        /**
335         * Sets the base visibility and, if requested, sends 
336         * a {@link RendererChangeEvent} to all registered listeners.
337         * 
338         * @param visible  the visibility.
339         * @param notify  notify listeners?
340         * 
341         * @see #getBaseSeriesVisible()
342         */
343        public void setBaseSeriesVisible(boolean visible, boolean notify);
344    
345        // SERIES VISIBLE IN LEGEND (not yet respected by all renderers)
346        
347        /**
348         * Returns <code>true</code> if the series should be shown in the legend,
349         * and <code>false</code> otherwise.
350         * 
351         * @param series  the series index.
352         * 
353         * @return A boolean.
354         */
355        public boolean isSeriesVisibleInLegend(int series);
356        
357        /**
358         * Returns the flag that controls the visibility of ALL series in the 
359         * legend.  This flag overrides the per series and default settings - you 
360         * must set it to <code>null</code> if you want the other settings to 
361         * apply.
362         * 
363         * @return The flag (possibly <code>null</code>).
364         * 
365         * @see #setSeriesVisibleInLegend(Boolean)
366         */
367        public Boolean getSeriesVisibleInLegend();
368        
369        /**
370         * Sets the flag that controls the visibility of ALL series in the legend 
371         * and sends a {@link RendererChangeEvent} to all registered listeners.  
372         * This flag overrides the per series and default settings - you must set 
373         * it to <code>null</code> if you want the other settings to apply.
374         * 
375         * @param visible  the flag (<code>null</code> permitted).
376         * 
377         * @see #getSeriesVisibleInLegend()
378         */
379        public void setSeriesVisibleInLegend(Boolean visible);
380        
381        /**
382         * Sets the flag that controls the visibility of ALL series in the legend 
383         * and sends a {@link RendererChangeEvent} to all registered listeners.  
384         * This flag overrides the per series and default settings - you must set 
385         * it to <code>null</code> if you want the other settings to apply.
386         * 
387         * @param visible  the flag (<code>null</code> permitted).
388         * @param notify  notify listeners?
389         * 
390         * @see #getSeriesVisibleInLegend()
391         */
392        public void setSeriesVisibleInLegend(Boolean visible, boolean notify);
393        
394        /**
395         * Returns the flag that controls whether a series is visible in the 
396         * legend.  This method returns only the "per series" settings - to 
397         * incorporate the override and base settings as well, you need to use the 
398         * {@link #isSeriesVisibleInLegend(int)} method.
399         *
400         * @param series  the series index (zero-based).
401         *
402         * @return The flag (possibly <code>null</code>).
403         * 
404         * @see #setSeriesVisibleInLegend(int, Boolean)
405         */
406        public Boolean getSeriesVisibleInLegend(int series);
407        
408        /**
409         * Sets the flag that controls whether a series is visible in the legend 
410         * and sends a {@link RendererChangeEvent} to all registered listeners.
411         *
412         * @param series  the series index (zero-based).
413         * @param visible  the flag (<code>null</code> permitted).
414         * 
415         * @see #getSeriesVisibleInLegend(int)
416         */
417        public void setSeriesVisibleInLegend(int series, Boolean visible);
418        
419        /**
420         * Sets the flag that controls whether a series is visible in the legend
421         * and, if requested, sends a {@link RendererChangeEvent} to all registered 
422         * listeners.
423         * 
424         * @param series  the series index.
425         * @param visible  the flag (<code>null</code> permitted).
426         * @param notify  notify listeners?
427         * 
428         * @see #getSeriesVisibleInLegend(int)
429         */
430        public void setSeriesVisibleInLegend(int series, Boolean visible, 
431                                             boolean notify);
432    
433        /**
434         * Returns the base visibility in the legend for all series.
435         *
436         * @return The base visibility.
437         * 
438         * @see #setBaseSeriesVisibleInLegend(boolean)
439         */
440        public boolean getBaseSeriesVisibleInLegend();
441    
442        /**
443         * Sets the base visibility in the legend and sends a 
444         * {@link RendererChangeEvent} to all registered listeners.
445         *
446         * @param visible  the flag.
447         * 
448         * @see #getBaseSeriesVisibleInLegend()
449         */
450        public void setBaseSeriesVisibleInLegend(boolean visible);
451        
452        /**
453         * Sets the base visibility in the legend and, if requested, sends 
454         * a {@link RendererChangeEvent} to all registered listeners.
455         * 
456         * @param visible  the visibility.
457         * @param notify  notify listeners?
458         * 
459         * @see #getBaseSeriesVisibleInLegend()
460         */
461        public void setBaseSeriesVisibleInLegend(boolean visible, boolean notify);
462    
463    
464        //// PAINT /////////////////////////////////////////////////////////////////
465        
466        /**
467         * Returns the paint used to fill data items as they are drawn.
468         *
469         * @param row  the row (or series) index (zero-based).
470         * @param column  the column (or category) index (zero-based).
471         *
472         * @return The paint (never <code>null</code>).
473         */
474        public Paint getItemPaint(int row, int column);
475    
476        // FIXME: Why no getPaint() method?  Probably just an oversight.
477        
478        /**
479         * Sets the paint to be used for ALL series, and sends a 
480         * {@link RendererChangeEvent} to all registered listeners.  If this is 
481         * <code>null</code>, the renderer will use the paint for the series.
482         * 
483         * @param paint  the paint (<code>null</code> permitted).
484         */
485        public void setPaint(Paint paint);
486        
487        /**
488         * Returns the paint used to fill an item drawn by the renderer.
489         *
490         * @param series  the series index (zero-based).
491         *
492         * @return The paint (never <code>null</code>).
493         * 
494         * @see #setSeriesPaint(int, Paint)
495         */
496        public Paint getSeriesPaint(int series);
497    
498        /**
499         * Sets the paint used for a series and sends a {@link RendererChangeEvent}
500         * to all registered listeners.
501         *
502         * @param series  the series index (zero-based).
503         * @param paint  the paint (<code>null</code> permitted).
504         * 
505         * @see #getSeriesPaint(int)
506         */
507        public void setSeriesPaint(int series, Paint paint);
508        
509        /**
510         * Returns the base paint.
511         *
512         * @return The base paint (never <code>null</code>).
513         * 
514         * @see #setBasePaint(Paint)
515         */
516        public Paint getBasePaint();
517    
518        /**
519         * Sets the base paint and sends a {@link RendererChangeEvent} to all 
520         * registered listeners.
521         *
522         * @param paint  the paint (<code>null</code> not permitted).
523         * 
524         * @see #getBasePaint()
525         */
526        public void setBasePaint(Paint paint);
527        
528        //// OUTLINE PAINT /////////////////////////////////////////////////////////
529        
530        /**
531         * Returns the paint used to outline data items as they are drawn.
532         *
533         * @param row  the row (or series) index (zero-based).
534         * @param column  the column (or category) index (zero-based).
535         *
536         * @return The paint (never <code>null</code>).
537         */
538        public Paint getItemOutlinePaint(int row, int column);
539    
540        // FIXME: Why no getOutlinePaint?  Probably just an oversight.
541        
542        /**
543         * Sets the outline paint for ALL series (optional).
544         * 
545         * @param paint  the paint (<code>null</code> permitted).
546         */
547        public void setOutlinePaint(Paint paint);
548        
549        /**
550         * Returns the paint used to outline an item drawn by the renderer.
551         *
552         * @param series  the series (zero-based index).
553         *
554         * @return The paint (never <code>null</code>).
555         * 
556         * @see #setSeriesOutlinePaint(int, Paint)
557         */
558        public Paint getSeriesOutlinePaint(int series);
559    
560        /**
561         * Sets the paint used for a series outline and sends a 
562         * {@link RendererChangeEvent} to all registered listeners.
563         *
564         * @param series  the series index (zero-based).
565         * @param paint  the paint (<code>null</code> permitted).
566         * 
567         * @see #getSeriesOutlinePaint(int)
568         */
569        public void setSeriesOutlinePaint(int series, Paint paint);
570    
571        /**
572         * Returns the base outline paint.
573         *
574         * @return The paint (never <code>null</code>).
575         * 
576         * @see #setBaseOutlinePaint(Paint)
577         */
578        public Paint getBaseOutlinePaint();
579    
580        /**
581         * Sets the base outline paint and sends a {@link RendererChangeEvent} to 
582         * all registered listeners.
583         *
584         * @param paint  the paint (<code>null</code> not permitted).
585         * 
586         * @see #getBaseOutlinePaint()
587         */
588        public void setBaseOutlinePaint(Paint paint);
589    
590        //// STROKE ////////////////////////////////////////////////////////////////
591        
592        /**
593         * Returns the stroke used to draw data items.
594         *
595         * @param row  the row (or series) index (zero-based).
596         * @param column  the column (or category) index (zero-based).
597         *
598         * @return The stroke (never <code>null</code>).
599         */
600        public Stroke getItemStroke(int row, int column);
601    
602        // FIXME: Why no getStroke?  Probably just an oversight.
603    
604        /**
605         * Sets the stroke for ALL series and sends a {@link RendererChangeEvent} 
606         * to all registered listeners.
607         * 
608         * @param stroke  the stroke (<code>null</code> permitted).
609         */
610        public void setStroke(Stroke stroke);
611    
612        /**
613         * Returns the stroke used to draw the items in a series.
614         *
615         * @param series  the series (zero-based index).
616         *
617         * @return The stroke (never <code>null</code>).
618         * 
619         * @see #setSeriesStroke(int, Stroke)
620         */
621        public Stroke getSeriesStroke(int series);
622        
623        /**
624         * Sets the stroke used for a series and sends a 
625         * {@link RendererChangeEvent} to all registered listeners.
626         *
627         * @param series  the series index (zero-based).
628         * @param stroke  the stroke (<code>null</code> permitted).
629         * 
630         * @see #getSeriesStroke(int)
631         */
632        public void setSeriesStroke(int series, Stroke stroke);
633    
634        /**
635         * Returns the base stroke.
636         *
637         * @return The base stroke (never <code>null</code>).
638         * 
639         * @see #setBaseStroke(Stroke)
640         */
641        public Stroke getBaseStroke();
642    
643        /**
644         * Sets the base stroke and sends a {@link RendererChangeEvent} to all
645         * registered listeners.
646         *
647         * @param stroke  the stroke (<code>null</code> not permitted).
648         * 
649         * @see #getBaseStroke()
650         */
651        public void setBaseStroke(Stroke stroke);
652        
653        //// OUTLINE STROKE ////////////////////////////////////////////////////////
654        
655        /**
656         * Returns the stroke used to outline data items.
657         * <p>
658         * The default implementation passes control to the getSeriesOutlineStroke 
659         * method.  You can override this method if you require different behaviour.
660         *
661         * @param row  the row (or series) index (zero-based).
662         * @param column  the column (or category) index (zero-based).
663         *
664         * @return The stroke (never <code>null</code>).
665         */
666        public Stroke getItemOutlineStroke(int row, int column);
667    
668        // FIXME: Why no getOutlineStroke?  Probably just an oversight.
669    
670        /**
671         * Sets the outline stroke for ALL series and sends a 
672         * {@link RendererChangeEvent} to all registered listeners.
673         *
674         * @param stroke  the stroke (<code>null</code> permitted).
675         */
676        public void setOutlineStroke(Stroke stroke);
677        
678        /**
679         * Returns the stroke used to outline the items in a series.
680         *
681         * @param series  the series (zero-based index).
682         *
683         * @return The stroke (never <code>null</code>).
684         * 
685         * @see #setSeriesOutlineStroke(int, Stroke)
686         */
687        public Stroke getSeriesOutlineStroke(int series);
688    
689        /**
690         * Sets the outline stroke used for a series and sends a 
691         * {@link RendererChangeEvent} to all registered listeners.
692         *
693         * @param series  the series index (zero-based).
694         * @param stroke  the stroke (<code>null</code> permitted).
695         * 
696         * @see #getSeriesOutlineStroke(int)
697         */
698        public void setSeriesOutlineStroke(int series, Stroke stroke);
699        
700        /**
701         * Returns the base outline stroke.
702         *
703         * @return The stroke (never <code>null</code>).
704         * 
705         * @see #setBaseOutlineStroke(Stroke)
706         */
707        public Stroke getBaseOutlineStroke();
708    
709        /**
710         * Sets the base outline stroke and sends a {@link RendererChangeEvent} to 
711         * all registered listeners.
712         *
713         * @param stroke  the stroke (<code>null</code> not permitted).
714         * 
715         * @see #getBaseOutlineStroke()
716         */
717        public void setBaseOutlineStroke(Stroke stroke);
718        
719        //// SHAPE /////////////////////////////////////////////////////////////////
720        
721        /**
722         * Returns a shape used to represent a data item.
723         *
724         * @param row  the row (or series) index (zero-based).
725         * @param column  the column (or category) index (zero-based).
726         *
727         * @return The shape (never <code>null</code>).
728         */
729        public Shape getItemShape(int row, int column);
730    
731        // FIXME: Why no getShape()?  Probably just an oversight.
732    
733        /**
734         * Sets the shape for ALL series (optional) and sends a 
735         * {@link RendererChangeEvent} to all registered listeners.
736         * 
737         * @param shape  the shape (<code>null</code> permitted).
738         */
739        public void setShape(Shape shape);
740        
741        /**
742         * Returns a shape used to represent the items in a series.
743         *
744         * @param series  the series (zero-based index).
745         *
746         * @return The shape (never <code>null</code>).
747         * 
748         * @see #setSeriesShape(int, Shape)
749         */
750        public Shape getSeriesShape(int series);
751    
752        /**
753         * Sets the shape used for a series and sends a {@link RendererChangeEvent}
754         * to all registered listeners.
755         *
756         * @param series  the series index (zero-based).
757         * @param shape  the shape (<code>null</code> permitted).
758         * 
759         * @see #getSeriesShape(int)
760         */
761        public void setSeriesShape(int series, Shape shape);
762        
763        /**
764         * Returns the base shape.
765         *
766         * @return The shape (never <code>null</code>).
767         * 
768         * @see #setBaseShape(Shape)
769         */
770        public Shape getBaseShape();
771    
772        /**
773         * Sets the base shape and sends a {@link RendererChangeEvent} to all 
774         * registered listeners.
775         *
776         * @param shape  the shape (<code>null</code> not permitted).
777         * 
778         * @see #getBaseShape()
779         */
780        public void setBaseShape(Shape shape);
781        
782        // ITEM LABELS VISIBLE 
783        
784        /**
785         * Returns <code>true</code> if an item label is visible, and 
786         * <code>false</code> otherwise.
787         * 
788         * @param row  the row index (zero-based).
789         * @param column  the column index (zero-based).
790         * 
791         * @return A boolean.
792         */
793        public boolean isItemLabelVisible(int row, int column);
794        
795        // FIXME: Why no isItemLabelsVisible()?  Probably just an oversight.
796    
797        /**
798         * Sets a flag that controls whether or not the item labels for ALL series 
799         * are visible.
800         * 
801         * @param visible  the flag.
802         * 
803         * @see #setItemLabelsVisible(Boolean)
804         */
805        public void setItemLabelsVisible(boolean visible);
806    
807        /**
808         * Sets a flag that controls whether or not the item labels for ALL series 
809         * are visible.
810         * 
811         * @param visible  the flag (<code>null</code> permitted).
812         * 
813         * @see #setItemLabelsVisible(boolean)
814         */
815        public void setItemLabelsVisible(Boolean visible);
816    
817        /**
818         * Sets the visibility of item labels for ALL series and, if requested, 
819         * sends a {@link RendererChangeEvent} to all registered listeners.
820         * 
821         * @param visible  a flag that controls whether or not the item labels are
822         *                 visible (<code>null</code> permitted).
823         * @param notify  a flag that controls whether or not listeners are 
824         *                notified.
825         */
826        public void setItemLabelsVisible(Boolean visible, boolean notify);
827    
828        /**
829         * Returns <code>true</code> if the item labels for a series are visible, 
830         * and <code>false</code> otherwise.
831         * 
832         * @param series  the series index (zero-based).
833         * 
834         * @return A boolean.
835         * 
836         * @see #setSeriesItemLabelsVisible(int, Boolean)
837         */    
838        public boolean isSeriesItemLabelsVisible(int series);
839        
840        /**
841         * Sets a flag that controls the visibility of the item labels for a series.
842         * 
843         * @param series  the series index (zero-based).
844         * @param visible  the flag.
845         * 
846         * @see #isSeriesItemLabelsVisible(int)
847         */
848        public void setSeriesItemLabelsVisible(int series, boolean visible);
849        
850        /**
851         * Sets a flag that controls the visibility of the item labels for a series.
852         * 
853         * @param series  the series index (zero-based).
854         * @param visible  the flag (<code>null</code> permitted).
855         * 
856         * @see #isSeriesItemLabelsVisible(int)
857         */
858        public void setSeriesItemLabelsVisible(int series, Boolean visible);
859        
860        /**
861         * Sets the visibility of item labels for a series and, if requested, sends 
862         * a {@link RendererChangeEvent} to all registered listeners.
863         * 
864         * @param series  the series index (zero-based).
865         * @param visible  the visible flag.
866         * @param notify  a flag that controls whether or not listeners are 
867         *                notified.
868         *                
869         * @see #isSeriesItemLabelsVisible(int)
870         */
871        public void setSeriesItemLabelsVisible(int series, Boolean visible, 
872                                               boolean notify);
873        
874        /**
875         * Returns the base setting for item label visibility.
876         * 
877         * @return A flag (possibly <code>null</code>).
878         * 
879         * @see #setBaseItemLabelsVisible(Boolean)
880         */
881        public Boolean getBaseItemLabelsVisible();
882        
883        /**
884         * Sets the base flag that controls whether or not item labels are visible.
885         * 
886         * @param visible  the flag.
887         * 
888         * @see #getBaseItemLabelsVisible()
889         */
890        public void setBaseItemLabelsVisible(boolean visible);
891        
892        /**
893         * Sets the base setting for item label visibility.
894         * 
895         * @param visible  the flag (<code>null</code> permitted).
896         * 
897         * @see #getBaseItemLabelsVisible()
898         */
899        public void setBaseItemLabelsVisible(Boolean visible);
900        
901        /**
902         * Sets the base visibility for item labels and, if requested, sends a 
903         * {@link RendererChangeEvent} to all registered listeners.
904         * 
905         * @param visible  the visibility flag.
906         * @param notify  a flag that controls whether or not listeners are 
907         *                notified.
908         *                
909         * @see #getBaseItemLabelsVisible()
910         */
911        public void setBaseItemLabelsVisible(Boolean visible, boolean notify);
912        
913        // ITEM LABEL GENERATOR
914        
915        /**
916         * Returns the item label generator for the specified data item.
917         *
918         * @param series  the series index (zero-based).
919         * @param item  the item index (zero-based).
920         *
921         * @return The generator (possibly <code>null</code>).
922         */
923        public CategoryItemLabelGenerator getItemLabelGenerator(int series, 
924                int item);
925    
926        // FIXME: Why no getItemLabelGenerator()?  Probably just an oversight.
927    
928        /**
929         * Sets the item label generator for ALL series and sends a 
930         * {@link RendererChangeEvent} to all registered listeners.  This overrides 
931         * the per-series settings. 
932         * 
933         * @param generator  the generator (<code>null</code> permitted).
934         */
935        public void setItemLabelGenerator(CategoryItemLabelGenerator generator);
936        
937        /**
938         * Returns the item label generator for a series.
939         *
940         * @param series  the series index (zero-based).
941         *
942         * @return The label generator (possibly <code>null</code>).
943         * 
944         * @see #setSeriesItemLabelGenerator(int, CategoryItemLabelGenerator)
945         */
946        public CategoryItemLabelGenerator getSeriesItemLabelGenerator(int series);
947    
948        /**
949         * Sets the item label generator for a series and sends a 
950         * {@link RendererChangeEvent} to all registered listeners.  
951         *
952         * @param series  the series index (zero-based).
953         * @param generator  the generator.
954         * 
955         * @see #getSeriesItemLabelGenerator(int)
956         */
957        public void setSeriesItemLabelGenerator(
958                int series, CategoryItemLabelGenerator generator);
959    
960        /**
961         * Returns the base item label generator.
962         *
963         * @return The generator (possibly <code>null</code>).
964         * 
965         * @see #setBaseItemLabelGenerator(CategoryItemLabelGenerator)
966         */
967        public CategoryItemLabelGenerator getBaseItemLabelGenerator();
968    
969        /**
970         * Sets the base item label generator and sends a 
971         * {@link RendererChangeEvent} to all registered listeners.
972         *
973         * @param generator  the generator (<code>null</code> permitted).
974         * 
975         * @see #getBaseItemLabelGenerator()
976         */
977        public void setBaseItemLabelGenerator(CategoryItemLabelGenerator generator);
978    
979        // TOOL TIP GENERATOR
980        
981        /**
982         * Returns the tool tip generator that should be used for the specified 
983         * item.  This method looks up the generator using the "three-layer" 
984         * approach outlined in the general description of this interface.  
985         *
986         * @param row  the row index (zero-based).
987         * @param column  the column index (zero-based).
988         *
989         * @return The generator (possibly <code>null</code>).
990         */
991        public CategoryToolTipGenerator getToolTipGenerator(int row, int column);
992    
993        /**
994         * Returns the tool tip generator that will be used for ALL items in the 
995         * dataset (the "layer 0" generator).
996         * 
997         * @return A tool tip generator (possibly <code>null</code>).
998         * 
999         * @see #setToolTipGenerator(CategoryToolTipGenerator)
1000         */
1001        public CategoryToolTipGenerator getToolTipGenerator();
1002    
1003        /**
1004         * Sets the tool tip generator for ALL series and sends a 
1005         * {@link org.jfree.chart.event.RendererChangeEvent} to all registered 
1006         * listeners.
1007         * 
1008         * @param generator  the generator (<code>null</code> permitted).
1009         * 
1010         * @see #getToolTipGenerator()
1011         */
1012        public void setToolTipGenerator(CategoryToolTipGenerator generator);
1013        
1014        /**
1015         * Returns the tool tip generator for the specified series (a "layer 1" 
1016         * generator).
1017         *
1018         * @param series  the series index (zero-based).
1019         *
1020         * @return The tool tip generator (possibly <code>null</code>).
1021         * 
1022         * @see #setSeriesToolTipGenerator(int, CategoryToolTipGenerator)
1023         */
1024        public CategoryToolTipGenerator getSeriesToolTipGenerator(int series);
1025    
1026        /**
1027         * Sets the tool tip generator for a series and sends a 
1028         * {@link org.jfree.chart.event.RendererChangeEvent} to all registered 
1029         * listeners.
1030         *
1031         * @param series  the series index (zero-based).
1032         * @param generator  the generator (<code>null</code> permitted).
1033         * 
1034         * @see #getSeriesToolTipGenerator(int)
1035         */
1036        public void setSeriesToolTipGenerator(int series, 
1037                                              CategoryToolTipGenerator generator);
1038    
1039        /**
1040         * Returns the base tool tip generator (the "layer 2" generator).
1041         *
1042         * @return The tool tip generator (possibly <code>null</code>).
1043         * 
1044         * @see #setBaseToolTipGenerator(CategoryToolTipGenerator)
1045         */
1046        public CategoryToolTipGenerator getBaseToolTipGenerator();
1047    
1048        /**
1049         * Sets the base tool tip generator and sends a 
1050         * {@link org.jfree.chart.event.RendererChangeEvent} to all registered 
1051         * listeners.
1052         *
1053         * @param generator  the generator (<code>null</code> permitted).
1054         * 
1055         * @see #getBaseToolTipGenerator()
1056         */
1057        public void setBaseToolTipGenerator(CategoryToolTipGenerator generator);
1058    
1059        //// ITEM LABEL FONT  //////////////////////////////////////////////////////
1060        
1061        /**
1062         * Returns the font for an item label.
1063         * 
1064         * @param row  the row index (zero-based).
1065         * @param column  the column index (zero-based).
1066         * 
1067         * @return The font (never <code>null</code>).
1068         */
1069        public Font getItemLabelFont(int row, int column);
1070    
1071        /**
1072         * Returns the font used for all item labels.  This may be 
1073         * <code>null</code>, in which case the per series font settings will apply.
1074         * 
1075         * @return The font (possibly <code>null</code>).
1076         * 
1077         * @see #setItemLabelFont(Font)
1078         */
1079        public Font getItemLabelFont();
1080        
1081        /**
1082         * Sets the item label font for ALL series and sends a 
1083         * {@link RendererChangeEvent} to all registered listeners.  You can set 
1084         * this to <code>null</code> if you prefer to set the font on a per series 
1085         * basis.
1086         * 
1087         * @param font  the font (<code>null</code> permitted).
1088         * 
1089         * @see #getItemLabelFont()
1090         */
1091        public void setItemLabelFont(Font font);
1092        
1093        /**
1094         * Returns the font for all the item labels in a series.
1095         * 
1096         * @param series  the series index (zero-based).
1097         * 
1098         * @return The font (possibly <code>null</code>).
1099         * 
1100         * @see #setSeriesItemLabelFont(int, Font)
1101         */
1102        public Font getSeriesItemLabelFont(int series);
1103    
1104        /**
1105         * Sets the item label font for a series and sends a 
1106         * {@link RendererChangeEvent} to all registered listeners.  
1107         * 
1108         * @param series  the series index (zero-based).
1109         * @param font  the font (<code>null</code> permitted).
1110         * 
1111         * @see #getSeriesItemLabelFont(int)
1112         */
1113        public void setSeriesItemLabelFont(int series, Font font);
1114    
1115        /**
1116         * Returns the base item label font (this is used when no other font 
1117         * setting is available).
1118         * 
1119         * @return The font (<code>never</code> null).
1120         * 
1121         * @see #setBaseItemLabelFont(Font)
1122         */
1123        public Font getBaseItemLabelFont();
1124    
1125        /**
1126         * Sets the base item label font and sends a {@link RendererChangeEvent} 
1127         * to all registered listeners.  
1128         * 
1129         * @param font  the font (<code>null</code> not permitted).
1130         * 
1131         * @see #getBaseItemLabelFont()
1132         */
1133        public void setBaseItemLabelFont(Font font);
1134        
1135        //// ITEM LABEL PAINT  /////////////////////////////////////////////////////
1136    
1137        /**
1138         * Returns the paint used to draw an item label.
1139         * 
1140         * @param row  the row index (zero based).
1141         * @param column  the column index (zero based).
1142         * 
1143         * @return The paint (never <code>null</code>).
1144         */
1145        public Paint getItemLabelPaint(int row, int column);
1146        
1147        /**
1148         * Returns the paint used for all item labels.  This may be 
1149         * <code>null</code>, in which case the per series paint settings will 
1150         * apply.
1151         * 
1152         * @return The paint (possibly <code>null</code>).
1153         * 
1154         * @see #setItemLabelPaint(Paint)
1155         */
1156        public Paint getItemLabelPaint();
1157    
1158        /**
1159         * Sets the item label paint for ALL series and sends a 
1160         * {@link RendererChangeEvent} to all registered listeners.
1161         * 
1162         * @param paint  the paint (<code>null</code> permitted).
1163         * 
1164         * @see #getItemLabelPaint()
1165         */
1166        public void setItemLabelPaint(Paint paint);
1167    
1168        /**
1169         * Returns the paint used to draw the item labels for a series.
1170         * 
1171         * @param series  the series index (zero based).
1172         * 
1173         * @return The paint (possibly <code>null<code>).
1174         * 
1175         * @see #setSeriesItemLabelPaint(int, Paint)
1176         */
1177        public Paint getSeriesItemLabelPaint(int series);
1178    
1179        /**
1180         * Sets the item label paint for a series and sends a 
1181         * {@link RendererChangeEvent} to all registered listeners.
1182         * 
1183         * @param series  the series (zero based index).
1184         * @param paint  the paint (<code>null</code> permitted).
1185         * 
1186         * @see #getSeriesItemLabelPaint(int)
1187         */
1188        public void setSeriesItemLabelPaint(int series, Paint paint);
1189        
1190        /**
1191         * Returns the base item label paint.
1192         * 
1193         * @return The paint (never <code>null<code>).
1194         * 
1195         * @see #setBaseItemLabelPaint(Paint)
1196         */
1197        public Paint getBaseItemLabelPaint();
1198    
1199        /**
1200         * Sets the base item label paint and sends a {@link RendererChangeEvent} 
1201         * to all registered listeners.
1202         * 
1203         * @param paint  the paint (<code>null</code> not permitted).
1204         * 
1205         * @see #getBaseItemLabelPaint()
1206         */
1207        public void setBaseItemLabelPaint(Paint paint);
1208        
1209        // POSITIVE ITEM LABEL POSITION...
1210    
1211        /**
1212         * Returns the item label position for positive values.
1213         * 
1214         * @param row  the row index (zero-based).
1215         * @param column  the column index (zero-based).
1216         * 
1217         * @return The item label position (never <code>null</code>).
1218         */
1219        public ItemLabelPosition getPositiveItemLabelPosition(int row, int column);
1220    
1221        /**
1222         * Returns the item label position for positive values in ALL series.
1223         * 
1224         * @return The item label position (possibly <code>null</code>).
1225         * 
1226         * @see #setPositiveItemLabelPosition(ItemLabelPosition)
1227         */
1228        public ItemLabelPosition getPositiveItemLabelPosition();
1229    
1230        /**
1231         * Sets the item label position for positive values in ALL series, and 
1232         * sends a {@link RendererChangeEvent} to all registered listeners.  You 
1233         * need to set this to <code>null</code> to expose the settings for 
1234         * individual series.
1235         * 
1236         * @param position  the position (<code>null</code> permitted).
1237         * 
1238         * @see #getPositiveItemLabelPosition()
1239         */
1240        public void setPositiveItemLabelPosition(ItemLabelPosition position);
1241        
1242        /**
1243         * Sets the positive item label position for ALL series and (if requested) 
1244         * sends a {@link RendererChangeEvent} to all registered listeners.
1245         * 
1246         * @param position  the position (<code>null</code> permitted).
1247         * @param notify  notify registered listeners?
1248         * 
1249         * @see #getPositiveItemLabelPosition()
1250         */
1251        public void setPositiveItemLabelPosition(ItemLabelPosition position, 
1252                                                 boolean notify);
1253    
1254        /**
1255         * Returns the item label position for all positive values in a series.
1256         * 
1257         * @param series  the series index (zero-based).
1258         * 
1259         * @return The item label position.
1260         * 
1261         * @see #setSeriesPositiveItemLabelPosition(int, ItemLabelPosition)
1262         */
1263        public ItemLabelPosition getSeriesPositiveItemLabelPosition(int series);
1264        
1265        /**
1266         * Sets the item label position for all positive values in a series and 
1267         * sends a {@link RendererChangeEvent} to all registered listeners.
1268         * 
1269         * @param series  the series index (zero-based).
1270         * @param position  the position (<code>null</code> permitted).
1271         * 
1272         * @see #getSeriesPositiveItemLabelPosition(int)
1273         */
1274        public void setSeriesPositiveItemLabelPosition(int series, 
1275                                                       ItemLabelPosition position);
1276    
1277        /**
1278         * Sets the item label position for all positive values in a series and (if
1279         * requested) sends a {@link RendererChangeEvent} to all registered 
1280         * listeners.
1281         * 
1282         * @param series  the series index (zero-based).
1283         * @param position  the position (<code>null</code> permitted).
1284         * @param notify  notify registered listeners?
1285         * 
1286         * @see #getSeriesPositiveItemLabelPosition(int)
1287         */
1288        public void setSeriesPositiveItemLabelPosition(int series, 
1289                                                       ItemLabelPosition position, 
1290            boolean notify);
1291    
1292        /**
1293         * Returns the base positive item label position.
1294         * 
1295         * @return The position.
1296         * 
1297         * @see #setBasePositiveItemLabelPosition(ItemLabelPosition)
1298         */
1299        public ItemLabelPosition getBasePositiveItemLabelPosition();
1300    
1301        /**
1302         * Sets the base positive item label position.
1303         * 
1304         * @param position  the position.
1305         * 
1306         * @see #getBasePositiveItemLabelPosition()
1307         */
1308        public void setBasePositiveItemLabelPosition(ItemLabelPosition position);
1309        
1310        /**
1311         * Sets the base positive item label position and, if requested, sends a 
1312         * {@link RendererChangeEvent} to all registered listeners.
1313         * 
1314         * @param position  the position.
1315         * @param notify  notify registered listeners?
1316         * 
1317         * @see #getBasePositiveItemLabelPosition()
1318         */
1319        public void setBasePositiveItemLabelPosition(ItemLabelPosition position, 
1320                                                     boolean notify);
1321        
1322        
1323        // NEGATIVE ITEM LABEL POSITION...
1324    
1325        /**
1326         * Returns the item label position for negative values.  This method can be
1327         * overridden to provide customisation of the item label position for 
1328         * individual data items.
1329         * 
1330         * @param row  the row index (zero-based).
1331         * @param column  the column (zero-based).
1332         * 
1333         * @return The item label position.
1334         */
1335        public ItemLabelPosition getNegativeItemLabelPosition(int row, int column);
1336    
1337        /**
1338         * Returns the item label position for negative values in ALL series.
1339         * 
1340         * @return The item label position (possibly <code>null</code>).
1341         * 
1342         * @see #setNegativeItemLabelPosition(ItemLabelPosition)
1343         */
1344        public ItemLabelPosition getNegativeItemLabelPosition();
1345    
1346        /**
1347         * Sets the item label position for negative values in ALL series, and 
1348         * sends a {@link RendererChangeEvent} to all registered listeners.  You 
1349         * need to set this to <code>null</code> to expose the settings for 
1350         * individual series.
1351         * 
1352         * @param position  the position (<code>null</code> permitted).
1353         * 
1354         * @see #getNegativeItemLabelPosition()
1355         */
1356        public void setNegativeItemLabelPosition(ItemLabelPosition position);
1357        
1358        /**
1359         * Sets the item label position for negative values in ALL series and (if 
1360         * requested) sends a {@link RendererChangeEvent} to all registered 
1361         * listeners.  
1362         * 
1363         * @param position  the position (<code>null</code> permitted).
1364         * @param notify  notify registered listeners?
1365         * 
1366         * @see #getNegativeItemLabelPosition()
1367         */
1368        public void setNegativeItemLabelPosition(ItemLabelPosition position, 
1369                                                 boolean notify);
1370    
1371        /**
1372         * Returns the item label position for all negative values in a series.
1373         * 
1374         * @param series  the series index (zero-based).
1375         * 
1376         * @return The item label position.
1377         * 
1378         * @see #setSeriesNegativeItemLabelPosition(int, ItemLabelPosition)
1379         */
1380        public ItemLabelPosition getSeriesNegativeItemLabelPosition(int series);
1381    
1382        /**
1383         * Sets the item label position for negative values in a series and sends a 
1384         * {@link RendererChangeEvent} to all registered listeners.
1385         * 
1386         * @param series  the series index (zero-based).
1387         * @param position  the position (<code>null</code> permitted).
1388         * 
1389         * @see #getSeriesNegativeItemLabelPosition(int)
1390         */
1391        public void setSeriesNegativeItemLabelPosition(int series, 
1392                                                       ItemLabelPosition position);
1393    
1394        /**
1395         * Sets the item label position for negative values in a series and (if 
1396         * requested) sends a {@link RendererChangeEvent} to all registered 
1397         * listeners.
1398         * 
1399         * @param series  the series index (zero-based).
1400         * @param position  the position (<code>null</code> permitted).
1401         * @param notify  notify registered listeners?
1402         * 
1403         * @see #getSeriesNegativeItemLabelPosition(int)
1404         */
1405        public void setSeriesNegativeItemLabelPosition(int series, 
1406                                                       ItemLabelPosition position, 
1407                                                       boolean notify);
1408    
1409        /**
1410         * Returns the base item label position for negative values.
1411         * 
1412         * @return The position.
1413         * 
1414         * @see #setBaseNegativeItemLabelPosition(ItemLabelPosition)
1415         */
1416        public ItemLabelPosition getBaseNegativeItemLabelPosition();
1417    
1418        /**
1419         * Sets the base item label position for negative values and sends a 
1420         * {@link RendererChangeEvent} to all registered listeners.
1421         * 
1422         * @param position  the position.
1423         * 
1424         * @see #getBaseNegativeItemLabelPosition()
1425         */
1426        public void setBaseNegativeItemLabelPosition(ItemLabelPosition position);
1427        
1428        /**
1429         * Sets the base negative item label position and, if requested, sends a 
1430         * {@link RendererChangeEvent} to all registered listeners.
1431         * 
1432         * @param position  the position.
1433         * @param notify  notify registered listeners?
1434         * 
1435         * @see #getBaseNegativeItemLabelPosition()
1436         */
1437        public void setBaseNegativeItemLabelPosition(ItemLabelPosition position, 
1438                                                     boolean notify);
1439        
1440        // ITEM URL GENERATOR
1441        
1442        /**
1443         * Returns the URL generator for an item.
1444         *
1445         * @param series  the series index (zero-based).
1446         * @param item  the item index (zero-based).
1447         *
1448         * @return The item URL generator.
1449         */
1450        public CategoryURLGenerator getItemURLGenerator(int series, int item);
1451    
1452        /**
1453         * Sets the item URL generator for ALL series. 
1454         * 
1455         * @param generator  the generator.
1456         * 
1457         * @see #getSeriesItemURLGenerator(int)
1458         */
1459        public void setItemURLGenerator(CategoryURLGenerator generator);
1460        
1461        /**
1462         * Returns the item URL generator for a series.
1463         *
1464         * @param series  the series index (zero-based).
1465         *
1466         * @return The URL generator.
1467         * 
1468         * @see #setSeriesItemURLGenerator(int, CategoryURLGenerator)
1469         */
1470        public CategoryURLGenerator getSeriesItemURLGenerator(int series);
1471    
1472        /**
1473         * Sets the item URL generator for a series.
1474         *
1475         * @param series  the series index (zero-based).
1476         * @param generator  the generator.
1477         * 
1478         * @see #getSeriesItemURLGenerator(int)
1479         */
1480        public void setSeriesItemURLGenerator(int series, 
1481                                              CategoryURLGenerator generator);
1482    
1483        /**
1484         * Returns the base item URL generator.
1485         *
1486         * @return The item URL generator (possibly <code>null</code>).
1487         * 
1488         * @see #setBaseItemURLGenerator(CategoryURLGenerator)
1489         */
1490        public CategoryURLGenerator getBaseItemURLGenerator();
1491    
1492        /**
1493         * Sets the base item URL generator and sends a {@link RendererChangeEvent}
1494         * to all registered listeners.
1495         *
1496         * @param generator  the item URL generator (<code>null</code> permitted).
1497         * 
1498         * @see #getBaseItemURLGenerator()
1499         */
1500        public void setBaseItemURLGenerator(CategoryURLGenerator generator);
1501    
1502        /**
1503         * Returns a legend item for a series.
1504         *
1505         * @param datasetIndex  the dataset index (zero-based).
1506         * @param series  the series (zero-based index).
1507         *
1508         * @return The legend item (possibly <code>null</code>).
1509         */
1510        public LegendItem getLegendItem(int datasetIndex, int series);
1511    
1512        /**
1513         * Draws a background for the data area.
1514         *
1515         * @param g2  the graphics device.
1516         * @param plot  the plot.
1517         * @param dataArea  the data area.
1518         */
1519        public void drawBackground(Graphics2D g2,
1520                                   CategoryPlot plot,
1521                                   Rectangle2D dataArea);
1522    
1523        /**
1524         * Draws an outline for the data area.
1525         *
1526         * @param g2  the graphics device.
1527         * @param plot  the plot.
1528         * @param dataArea  the data area.
1529         */
1530        public void drawOutline(Graphics2D g2,
1531                                CategoryPlot plot,
1532                                Rectangle2D dataArea);
1533    
1534        /**
1535         * Draws a single data item.
1536         *
1537         * @param g2  the graphics device.
1538         * @param state  state information for one chart.
1539         * @param dataArea  the data plot area.
1540         * @param plot  the plot.
1541         * @param domainAxis  the domain axis.
1542         * @param rangeAxis  the range axis.
1543         * @param dataset  the data.
1544         * @param row  the row index (zero-based).
1545         * @param column  the column index (zero-based).
1546         * @param pass  the pass index.
1547         */
1548        public void drawItem(Graphics2D g2,
1549                             CategoryItemRendererState state,
1550                             Rectangle2D dataArea,
1551                             CategoryPlot plot,
1552                             CategoryAxis domainAxis,
1553                             ValueAxis rangeAxis,
1554                             CategoryDataset dataset,
1555                             int row,
1556                             int column,
1557                             int pass);
1558    
1559        /**
1560         * Draws a grid line against the domain axis.
1561         *
1562         * @param g2  the graphics device.
1563         * @param plot  the plot.
1564         * @param dataArea  the area for plotting data (not yet adjusted for any 
1565         *                  3D effect).
1566         * @param value  the value.
1567         * 
1568         * @see #drawRangeGridline(Graphics2D, CategoryPlot, ValueAxis, 
1569         *     Rectangle2D, double)
1570         */
1571        public void drawDomainGridline(Graphics2D g2,
1572                                       CategoryPlot plot,
1573                                       Rectangle2D dataArea,
1574                                       double value);
1575    
1576        /**
1577         * Draws a grid line against the range axis.
1578         *
1579         * @param g2  the graphics device.
1580         * @param plot  the plot.
1581         * @param axis  the value axis.
1582         * @param dataArea  the area for plotting data (not yet adjusted for any 
1583         *                  3D effect).
1584         * @param value  the value.
1585         * 
1586         * @see #drawDomainGridline(Graphics2D, CategoryPlot, Rectangle2D, double)
1587         */
1588        public void drawRangeGridline(Graphics2D g2,
1589                                      CategoryPlot plot,
1590                                      ValueAxis axis,
1591                                      Rectangle2D dataArea,
1592                                      double value);
1593    
1594        /**
1595         * Draws a line (or some other marker) to indicate a particular category on 
1596         * the domain axis.
1597         *
1598         * @param g2  the graphics device.
1599         * @param plot  the plot.
1600         * @param axis  the category axis.
1601         * @param marker  the marker.
1602         * @param dataArea  the area for plotting data (not including 3D effect).
1603         * 
1604         * @see #drawRangeMarker(Graphics2D, CategoryPlot, ValueAxis, Marker, 
1605         *     Rectangle2D)
1606         */
1607        public void drawDomainMarker(Graphics2D g2,
1608                                     CategoryPlot plot,
1609                                     CategoryAxis axis,
1610                                     CategoryMarker marker,
1611                                     Rectangle2D dataArea);
1612    
1613        /**
1614         * Draws a line (or some other marker) to indicate a particular value on 
1615         * the range axis.
1616         *
1617         * @param g2  the graphics device.
1618         * @param plot  the plot.
1619         * @param axis  the value axis.
1620         * @param marker  the marker.
1621         * @param dataArea  the area for plotting data (not including 3D effect).
1622         * 
1623         * @see #drawDomainMarker(Graphics2D, CategoryPlot, CategoryAxis, 
1624         *     CategoryMarker, Rectangle2D)
1625         */
1626        public void drawRangeMarker(Graphics2D g2,
1627                                    CategoryPlot plot,
1628                                    ValueAxis axis,
1629                                    Marker marker,
1630                                    Rectangle2D dataArea);
1631    
1632    }