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