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