    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
    098package org.jfree.chart.renderer.category;
    099
    100import java.awt.Font;
    101import java.awt.Graphics2D;
    102import java.awt.Paint;
    103import java.awt.Shape;
    104import java.awt.Stroke;
    105import java.awt.geom.Rectangle2D;
    106
    107import org.jfree.chart.LegendItem;
    108import org.jfree.chart.LegendItemSource;
    109import org.jfree.chart.axis.CategoryAxis;
    110import org.jfree.chart.axis.ValueAxis;
    111import org.jfree.chart.event.RendererChangeEvent;
    112import org.jfree.chart.event.RendererChangeListener;
    113import org.jfree.chart.labels.CategoryItemLabelGenerator;
    114import org.jfree.chart.labels.CategoryToolTipGenerator;
    115import org.jfree.chart.labels.ItemLabelPosition;
    116import org.jfree.chart.plot.CategoryMarker;
    117import org.jfree.chart.plot.CategoryPlot;
    118import org.jfree.chart.plot.Marker;
    119import org.jfree.chart.plot.PlotRenderingInfo;
    120import org.jfree.chart.urls.CategoryURLGenerator;
    121import org.jfree.data.Range;
    122import org.jfree.data.category.CategoryDataset;
    123import 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 */
    145public 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}