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